快速开始

本教程基于官方示例 zlua-demo，逐步完成 C# 调用 Lua 与 Lua 访问 C#。建议先 clone Demo 工程对照操作。

Mono · 已完成Il2Cpp · 已完成 — 本页示例在 Editor 与 Player 均可用；Player 构建须 Generate，见 兼容性。

:::tip 示例源码

组件	链接
C# 入口	Assets/Bootstrap.cs
C# 类型	Assets/Demo.cs
Lua 模块	LuaScripts/app.lua

:::

前置条件

• 已完成 安装与集成（含 Settings + Install），或已 clone zlua-demo
• 任意 兼容性 所列 Unity 版本，Editor 下 Play 即可

第 1 步：初始化 ZLua

Bootstrap 在场景加载前注册 Lua 加载器并初始化域：

[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
private static void InitZLuaOnStartup()
{
    LuaAppDomain.Initialize(LoadLuaModule);
}

LoadLuaModule("app") 在 Editor 下读取 LuaScripts/app.lua（见 Bootstrap.cs）。

不需要手动创建 LuaState、执行 require 或注册 wrap——ZLua 启动时完成全局 CLR 与 Lua 环境集成。

第 2 步：C# 调用 Lua

用 LuaAppDomain.GetFunction<T> 取得 Lua 函数对应的 Delegate；Lua 模块 return 表导出同名函数。

C#

Action AppMain;
Func<int, int, int> AppAdd;

void Awake()
{
    // 须在 InitZLuaOnStartup（Initialize）之后；勿用 static 字段初始化器
    AppMain = LuaAppDomain.GetFunction<Action>("app", "main");
    AppAdd = LuaAppDomain.GetFunction<Func<int, int, int>>("app", "add");
}

void Start()
{
    AppMain();
    int value = AppAdd(10, 20);
    Debug.Log($"AppAdd(10,20)={value}");  // 30
}

Lua

local function main()
    print("lua main start")
    -- ...
end

local function add(a, b)
    return a + b
end

return {
    main = main,
    add = add,
}

完整逻辑见 LuaScripts/app.lua。

预期 Console 输出（Editor Play）

lua main start
[test_call_static_method] start
Demo.Add: 8
...
AppAdd(10,20)=30

第 3 步：Lua 访问 C# 类型

程序集别名

Lua 中通过 CSharp 根表懒加载程序集与类型：

CSharp['AC'] = CSharp['Assembly-CSharp']   -- 短别名，Demo 惯例

静态方法

print(CSharp.AC.Demo.Add(3, 5))       -- 8
print(CSharp.AC.Demo.Multi(3, 5))     -- 15

构造与实例方法

local demo = CSharp.AC.Demo()
print(demo:GetX())                    -- 0
demo:SetX(10)

字段与属性

字段与无参 Property 写法相同：

demo.x = 20
print(demo:GetX())                    -- 20

静态成员

CSharp.AC.Demo.s_x = 10
print(CSharp.AC.Demo.GetSX())         -- 10

以上测试函数在 app.lua 的 test_* 系列中。

访问规则速记

操作	Lua 写法
构造实例	CSharp.AC.Demo()
实例字段/属性	demo.x / demo:SetX(10)
实例方法	demo:Run(10)
静态字段	CSharp.AC.Demo.s_x
静态方法	CSharp.AC.Demo.Add(3, 5)
含 namespace 的类型	CSharp.AC['MyGame.UI.Panel']

第 4 步（可选）：方法重载

Demo.Run 有 int 与 string 两个重载。可用全签名键精确点名，或挂短名后冒号调用：

demo['Run(System.Int32)'](demo, 10)

local run_i32 = demo['Run(System.Int32)']
zlua.register_method("run_i32", run_i32)
demo:run_i32(10)

详见 方法重载。

构建 Il2Cpp Player

1. 执行 ZLua/Generate/All（生成 C++ stub）
2. 确保已配置 SyncLuaScriptsToStreamingAssets
3. Build Settings → Il2Cpp → Build

详见 项目状态、Editor 与 Player。

Mono / Il2Cpp 支持

本页示例	Mono (Editor)	Il2Cpp (Player)
Initialize + GetFunction	✅	✅
静态/实例方法、字段	✅	✅
Property / 重载	✅	✅（语义以规范为准）

常见错误

错误	排查
module 'app' not found	检查 LuaScripts/app.lua 是否存在；LoadLuaModule 路径
类型 Demo 为 nil	程序集名错误；应为 CSharp.AC.Demo
AppAdd 返回 0	Lua 模块未 return { add = add }；或函数名与 GetFunction 的 method 参数不一致
Player 无 Lua 输出	未同步 StreamingAssets/LuaScripts/app.lua.txt

下一步

循序渐进请走使用指南主线：

1. 安装与 Lua 版本
2. 初始化与最小互调
3. 构建流程
4. Lua 调用 C# → C# 调用 Lua → …

学习路径

上一篇	安装与集成
下一篇	安装与 Lua 版本