GoesSoftware.SuperSDK.Lua 7.3.0

SuperSDK.Lua

SuperSDK Lua 脚本桥接库，基于 MoonSharp（纯 C# Lua 5.2 解释器，无需安装任何外部运行时）。

dotnet add package GoesSoftware.SuperSDK.Lua

1. 初始化

1.1 静态门面（单例，向后兼容）

using SuperSDK.Lua;

LuaEngine.Initialize();                 // 扫描 [LuaExpose] 并注册
LuaEngine.ModulesPath = "Scripts/libs"; // 可选，require 搜索路径

Initialize() 幂等，重复调用无副作用。
LuaEngine 所有静态方法委托给内部的 LuaEngine.Default 实例。

1.2 实例模式（多运行时隔离）

当需要多个独立 Lua 运行环境时（例如每个 Fixture / Slot 一个独立引擎），直接创建 LuaRuntime 实例：

var runtime1 = new LuaRuntime();
runtime1.ModulesPath = "Scripts/libs";
runtime1.Initialize();

var runtime2 = new LuaRuntime();
runtime2.Initialize();

runtime1.Execute("x = 100");
runtime2.Execute("x = 200");

runtime1.Call<int>("x");  // → 100
runtime2.Call<int>("x");  // → 200

runtime1.Dispose();
runtime2.Dispose();

线程安全：不同 LuaRuntime 实例可安全运行在不同线程。
同一实例不能同时从多个线程调用。

2. 导出 C# 对象到 Lua

2.1 自动注入：[LuaExpose]

[LuaExpose(Name = "App")]        // 不指定 Name 则用类名
public class AppBridge
{
    public int    Add(int a, int b)  => a + b;
    public string Greet(string name) => $"Hello, {name}!";
}
// LuaRuntime.Initialize() 时自动扫描程序集，注入为 Lua 全局 App

• 普通类：自动 new() 后注册（需无参构造函数）
• 静态类：以 UserData.CreateStatic 注册

2.2 手动注入实例：Register<T>()

// 非泛型版（通过运行时类型推断）
runtime.Register("config", new ConfigBridge());

// 泛型版（推荐）：类型注册使用声明类型 T，不受派生类影响
runtime.Register<ConfigBridge>("config", new ConfigBridge());

2.3 跨 Runtime 共享同一对象

把同一 C# 实例注入多个 LuaRuntime，它们操作的是同一块内存：

var hwService = new HardwareService(fixtureId);

foreach (var runner in slotRunners.Values)
    runner.Runtime.Register<HardwareService>("hw", hwService);

-- Lua 里任意 Slot 调用，共享同一硬件服务
hw:Open()
local data = hw:Read()

2.4 可见性规则

注册进 Lua 后，成员的可见性由 C# 访问修饰符 决定：

如需精确控制，使用 [MoonSharpHidden] 隐藏特定成员：

[MoonSharpUserData]
public class HardwareService
{
    public void Open()  { ... }   // ✅ Lua 可调用

    [MoonSharpHidden]
    public void InternalReset() { ... }  // ❌ Lua 不可见
}

[MoonSharpUserData] 本身不影响可见性，仅让 MoonSharp 在首次使用时自动完成类型注册，省去手动调用 UserData.RegisterType<T>()。

3. 枚举注入：InjectEnum<T>()

将 C# 枚举自动注入为 Lua 全局 table，枚举值变动时 Lua 端无需任何修改：

runtime.InjectEnum<TestStatus>();
// 等效于在 Lua 执行: TestStatus = { Pass=0, Fail=1, Skip=2 }

if result == TestStatus.Pass then
    Log("test", "通过")
end

可指定自定义表名：

runtime.InjectEnum<Direction>("Dir");  // Lua: Dir = { North=0, South=1, ... }

4. 执行脚本

// 执行 Lua 代码字符串
runtime.Execute("x = 42");

// 执行 .lua 文件
runtime.ExecuteFile("Scripts/main.lua");

// 调用 Lua 全局函数
DynValue result = runtime.Call("myFunc", arg1, arg2);
int sum = runtime.Call<int>("add", 3, 4);

4.1 批量加载目录：LoadDirectory()

按自定义顺序加载目录下所有 *.lua 文件（跳过 _ 开头的文件）：

runtime.LoadDirectory(
    path:           "Scripts/",
    orderFn:        f => Path.GetFileNameWithoutExtension(f) switch {
                        "Common"  => 1,   // 最先加载
                        "hook"    => 2,
                        "startup" => 99,  // 最后加载
                        _         => 50
                    },
    logTag:         "MyRunner",
    recursive:      true,
    errorFormatter: ex => ex.Message
);

5. 内置全局函数

初始化后自动注入，无需 require，直接在 Lua 中调用：

日志函数同时发布 LuaLogMsg，C# 可订阅：

MessageBus.Subscribe<LuaLogMsg>(this, e =>
    Console.WriteLine($"[{e.Level}] {e.LogName}: {e.Text}"));

6. 消息总线（Pub / Sub）

消息类型只在 C# 端定义，通过 RegisterMessage<T>() 暴露给 Lua。
Lua 和 C# 共享同一条 MessageBus 管道，消息双向互通。

// C# 端：定义 + 注册
public class PlayerDiedEvent
{
    public string Reason { get; set; } = "";
}

runtime.RegisterMessage<PlayerDiedEvent>();

-- Lua 端：订阅 + 发布
Sub("PlayerDiedEvent", function(msg)
    LogInfo("game", "死亡原因：" .. msg.Reason)
end)

local msg = PlayerDiedEvent()
msg.Reason = "fell into void"
Pub(msg)

// C# 端同样可以收发
MessageBus.Subscribe<PlayerDiedEvent>(this, e =>
    Console.WriteLine("Died: " + e.Reason));

MessageBus.Pub(new PlayerDiedEvent { Reason = "explosion" });
// → Lua 的 Sub 回调同样会触发

自定义发布通道（例如 Slot 隔离）：

runtime.RegisterMessage<ItemTestResultMsg>(
    customPubHandler: msg => MessageBus.Pub(msg, msg.FixtureId, msg.SlotId));

7. 预加载标准库

以下库无需 require，初始化后直接可用。

7.1 json — rxi/json.lua v0.1.2（MIT）

local s = json.encode({ name = "SDK", ver = 3 })
local t = json.decode(s)
print(t.name)  -- → SDK

7.2 inspect — kikito/inspect.lua v3.1.0（MIT）

LogInfo("dbg", inspect({ 1, 2, { a = 3 } }))
-- → { 1, 2, { a = 3 } }

7.3 math.* 扩展

7.4 re — .NET Regex 包装

完整 API

LuaRuntime（实例类）

每个实例拥有独立的 Script、消息处理器和全局作用域。

LuaEngine（静态门面）

所有方法委托给 LuaEngine.Default（LuaRuntime 实例），向后完全兼容。

SuperSDK Lua 脚本桥接库，基于 MoonSharp（纯 C# Lua 5.2 解释器，无需安装任何外部运行时）。

dotnet add package GoesSoftware.SuperSDK.Lua

1. 初始化

1.1 静态门面（单例，向后兼容）

using SuperSDK.Lua;

LuaEngine.Initialize();                          // 扫描 [LuaExpose] 并注册
LuaEngine.ModulesPath = "Scripts/libs";           // 可选，require 搜索路径

Initialize() 幂等，重复调用无副作用。
LuaEngine 所有静态方法委托给内部的 LuaEngine.Default 实例。

1.2 实例模式（多运行时隔离）

当需要多个独立 Lua 运行环境时（例如每个 Fixture 一个独立引擎），直接创建 LuaRuntime 实例：

using SuperSDK.Lua;

// 每个实例拥有独立的 Script、Pub/Sub 处理器和全局变量
var runtime1 = new LuaRuntime();
runtime1.ModulesPath = "Scripts/libs";
runtime1.Initialize();

var runtime2 = new LuaRuntime();
runtime2.Initialize();

// 各自执行不会互相影响
runtime1.Execute("x = 100");
runtime2.Execute("x = 200");

runtime1.Call<int>("x");  // → 100
runtime2.Call<int>("x");  // → 200

// 用完释放
runtime1.Dispose();
runtime2.Dispose();

线程安全：不同 LuaRuntime 实例可以安全地运行在不同线程上。
同一实例不能同时从多个线程调用。

2. 导出 C# 对象到 Lua

[LuaExpose(Name = "App")]       // Lua 中 App.XXX 访问，不指定 Name 则用类名
public class AppBridge
{
    public int    Add(int a, int b)   => a + b;
    public string Greet(string name)  => $"Hello, {name}!";
}

• 普通类：自动 new() 后注册（需无参构造函数）
• 静态类：以 UserData.CreateStatic 注册
• 手动注册（静态门面）：LuaEngine.Register("MyObj", instance)
• 手动注册（实例）：runtime.Register("MyObj", instance)

3. 执行脚本

// ── 静态门面 ─────────────────────────────────────
var result = LuaEngine.Execute("return App.Add(3, 4)");
LuaEngine.ExecuteFile("Scripts/main.lua");
int sum = LuaEngine.Call<int>("add", 3, 4);

// ── 实例模式 ─────────────────────────────────────
var rt = new LuaRuntime();
rt.Initialize();
rt.ExecuteFile("Scripts/main.lua");
int sum2 = rt.Call<int>("add", 3, 4);

4. 内置全局函数

初始化后自动注入，无需 require，直接在 Lua 中调用：

日志函数同时发布 LuaLogMsg，C# 可订阅：

MessageBus.Subscribe<LuaLogMsg>(this, e =>
    Console.WriteLine($"[{e.Level}] {e.LogName}: {e.Text}"));

5. 消息总线（Pub / Sub）

消息类型只在 C# 端定义，通过 RegisterMessage<T>() 暴露给 Lua。
Lua 和 C# 共享同一条 MessageBus 管道，消息双向互通。

// ── C# 端：定义 + 注册 ───────────────────────────
public class PlayerDiedEvent
{
    public string Reason { get; set; } = "";
}

LuaEngine.RegisterMessage<PlayerDiedEvent>();

-- ── Lua 端：订阅 + 发布 ──────────────────────────
Sub("PlayerDiedEvent", function(msg)
    LogInfo("game", "死亡原因：" .. msg.Reason)
end)

local msg = PlayerDiedEvent()
msg.Reason = "fell into void"
Pub(msg)

// ── C# 端同样可以收发 ────────────────────────────
MessageBus.Subscribe<PlayerDiedEvent>(this, e =>
    Console.WriteLine("Died: " + e.Reason));

MessageBus.Pub(new PlayerDiedEvent { Reason = "explosion" });
// → Lua 的 Sub 回调同样会触发

6. 预加载标准库

以下库无需 require，初始化后直接可用（嵌入资源随 NuGet 包发布）。

6.1 json — rxi/json.lua v0.1.2（MIT）

local s = json.encode({ name = "SDK", ver = 3 })
local t = json.decode(s)
print(t.name)   -- → SDK

6.2 inspect — kikito/inspect.lua v3.1.0（MIT）

LogInfo("dbg", inspect({ 1, 2, { a = 3 } }))
-- → { 1, 2, { a = 3 } }

6.3 math.* 扩展

6.4 re — .NET Regex 包装

完整 API

LuaEngine（静态门面）

所有方法委托给 LuaEngine.Default（ LuaRuntime 实例），向后完全兼容。

LuaRuntime（实例类）

每个实例拥有独立的 Script、消息处理器和全局作用域。