feat(scripting-lua): expose C# enums to Lua deterministically via RegisterScriptEnum

Add RegisterScriptEnum<TEnum>() / RegisterScriptEnum(Type) container extensions and a
ScriptEnumData descriptor. Registered enums flow to the engine as a typed list and are
exposed during initialization (RegisterEnums), independently of Lua meta-file generation,
which previously ran after enum registration and on a background thread — so enums were
not reliably exposed. Explicitly-registered enums are also fed to the documentation
generator so the LSP meta file includes them.

Author: tgiachi

src/SquidStd.Scripting.Lua/Data/Internal/ScriptEnumData.cs

@@ -0,0 +1,31 @@
+namespace SquidStd.Scripting.Lua.Data.Internal;
+
+/// <summary>
+/// Record describing an enum type to expose to Lua as a read-only global table, keyed by member
+/// name. Registered through <c>RegisterScriptEnum</c> and consumed during engine initialization.
+/// </summary>
+public sealed record ScriptEnumData
+{
+    /// <summary>
+    /// The .NET enum type to expose to Lua.
+    /// </summary>
+    public Type EnumType { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the ScriptEnumData record.
+    /// </summary>
+    /// <param name="enumType">The .NET enum type to expose to Lua.</param>
+    /// <exception cref="ArgumentNullException">Thrown when enumType is null.</exception>
+    /// <exception cref="ArgumentException">Thrown when enumType is not an enum.</exception>
+    public ScriptEnumData(Type enumType)
+    {
+        ArgumentNullException.ThrowIfNull(enumType);
+
+        if (!enumType.IsEnum)
+        {
+            throw new ArgumentException("Type must be an enum.", nameof(enumType));
+        }
+
+        EnumType = enumType;
+    }
+}

src/SquidStd.Scripting.Lua/Extensions/Scripts/AddScriptModuleExtension.cs

@@ -65,5 +65,29 @@ public IContainer RegisterScriptModule(Type scriptModule)
         /// <returns>The container for method chaining.</returns>
         public IContainer RegisterScriptModule<TScriptModule>() where TScriptModule : class
             => container.RegisterScriptModule(typeof(TScriptModule));
+
+        /// <summary>
+        /// Registers an enum type to expose to Lua as a read-only, case-insensitive global table
+        /// keyed by member name. The exposure is deterministic: the enum is registered during engine
+        /// initialization, independently of Lua meta-file generation.
+        /// </summary>
+        /// <param name="enumType">The enum type to expose.</param>
+        /// <returns>The container for method chaining.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when enumType is null.</exception>
+        /// <exception cref="ArgumentException">Thrown when enumType is not an enum.</exception>
+        public IContainer RegisterScriptEnum(Type enumType)
+        {
+            container.AddToRegisterTypedList(new ScriptEnumData(enumType));
+
+            return container;
+        }
+
+        /// <summary>
+        /// Registers an enum type to expose to Lua using a generic type parameter.
+        /// </summary>
+        /// <typeparam name="TEnum">The enum type to expose.</typeparam>
+        /// <returns>The container for method chaining.</returns>
+        public IContainer RegisterScriptEnum<TEnum>() where TEnum : struct, Enum
+            => container.RegisterScriptEnum(typeof(TEnum));
     }
 }

src/SquidStd.Scripting.Lua/Services/LuaScriptEngineService.cs

@@ -52,6 +52,7 @@ public class LuaScriptEngineService : IScriptEngineService, IDisposable
     private readonly ConcurrentDictionary<string, ConcurrentDictionary<string, byte>> _manualModuleFunctions = new();
     private readonly ConcurrentDictionary<string, string> _scriptCache = new();
     private readonly List<ScriptModuleData> _scriptModules;
+    private readonly List<ScriptEnumData> _scriptEnums;
     private readonly IContainer _serviceProvider;
 
     private int _cacheHits;
@@ -85,7 +86,8 @@ public LuaScriptEngineService(
         IContainer serviceProvider,
         LuaEngineConfig engineConfig,
         List<ScriptModuleData> scriptModules = null,
-        List<ScriptUserData> loadedUserData = null
+        List<ScriptUserData> loadedUserData = null,
+        List<ScriptEnumData> scriptEnums = null
     )
     {
         JsonUtils.RegisterJsonContext(SquidStdScriptJsonContext.Default);
@@ -94,6 +96,7 @@ public LuaScriptEngineService(
         loadedUserData ??= new();
 
         _scriptModules = scriptModules;
+        _scriptEnums = scriptEnums ?? new();
         _directoriesConfig = directoriesConfig;
         _serviceProvider = serviceProvider;
         _engineConfig = engineConfig;
@@ -1101,6 +1104,16 @@ private async Task GenerateLuaMetaFileAsync(CancellationToken cancellationToken)
                 LuaDocumentationGenerator.AddClassToGenerate(userData.UserType);
             }
 
+            // Document explicitly-registered enums (RegisterScriptEnum) too.
+            foreach (var scriptEnum in _scriptEnums)
+            {
+                if (scriptEnum?.EnumType is { IsEnum: true } enumType &&
+                    !LuaDocumentationGenerator.FoundEnums.Contains(enumType))
+                {
+                    LuaDocumentationGenerator.FoundEnums.Add(enumType);
+                }
+            }
+
             AddConstant("engine_version", _engineConfig.EngineVersion);
 
             // Generate meta.lua
@@ -1420,9 +1433,25 @@ private void RegisterEnum(Type enumType)
     [RequiresUnreferencedCode("Enum metadata is discovered dynamically when building Lua documentation.")]
     private void RegisterEnums()
     {
-        var enumsFound = LuaDocumentationGenerator.FoundEnums.ToArray();
+        // Explicitly registered enums (RegisterScriptEnum) are the deterministic source; the enums
+        // discovered by the documentation generator are folded in for backward compatibility. A set
+        // keyed by type prevents registering the same enum twice.
+        var enumTypes = new HashSet<Type>();
+
+        foreach (var scriptEnum in _scriptEnums)
+        {
+            if (scriptEnum?.EnumType is not null)
+            {
+                enumTypes.Add(scriptEnum.EnumType);
+            }
+        }
+
+        foreach (var enumType in LuaDocumentationGenerator.FoundEnums.ToArray())
+        {
+            enumTypes.Add(enumType);
+        }
 
-        foreach (var enumType in enumsFound)
+        foreach (var enumType in enumTypes)
         {
             RegisterEnum(enumType);
         }

tests/SquidStd.Tests/Scripting/Lua/LuaScriptEngineServiceTests.cs

@@ -213,11 +213,41 @@ public async Task StartAsync_AttachesEventBridgeAndAddsBootstrapConstants()
         Assert.Equal("SquidStd", engine.ExecuteFunction("ENGINE").Data);
     }
 
+    [Fact]
+    public async Task RegisterScriptEnum_ExposesReadOnlyCaseInsensitiveGlobalTable()
+    {
+        using var temp = new TempDirectory();
+        using var container = new Container();
+        using var engine = CreateEngine(
+            temp,
+            container,
+            scriptEnums: [new ScriptEnumData(typeof(SampleColor))]
+        );
+
+        await engine.StartAsync(CancellationToken.None);
+
+        // Snake-cased global name, member values, and case-insensitive access.
+        Assert.Equal(2d, engine.ExecuteFunction("sample_color.Green").Data);
+        Assert.Equal(4d, engine.ExecuteFunction("sample_color.blue").Data);
+
+        // Unknown members read as nil.
+        Assert.Equal(true, engine.ExecuteFunction("sample_color.Missing == nil").Data);
+
+        // Adding a new member is rejected (the enum table is guarded against extension).
+        Assert.Equal(
+            false,
+            engine.ExecuteFunction(
+                "(function() local ok = pcall(function() sample_color.NewColor = 99 end); return ok end)()"
+            ).Data
+        );
+    }
+
     private static LuaScriptEngineService CreateEngine(
         TempDirectory temp,
         IContainer container,
         List<ScriptModuleData>? scriptModules = null,
-        List<ScriptUserData>? loadedUserData = null
+        List<ScriptUserData>? loadedUserData = null,
+        List<ScriptEnumData>? scriptEnums = null
     )
     {
         var scriptsDirectory = temp.Combine("scripts");
@@ -229,10 +259,18 @@ private static LuaScriptEngineService CreateEngine(
             container,
             new(luarcDirectory, scriptsDirectory, "SquidStd", "1.0.0"),
             scriptModules,
-            loadedUserData
+            loadedUserData,
+            scriptEnums
         );
     }
 
+    private enum SampleColor
+    {
+        Red = 1,
+        Green = 2,
+        Blue = 4
+    }
+
     public sealed class FiveArgumentUserData(int first, int second, int third, int fourth, int fifth)
     {
         public int Total { get; } = first + second + third + fourth + fifth;