安装与集成
本文以官方示例工程 zlua-demo 为 canonical 参考,路径均指向其 main 分支。
:::info 适用范围 本页描述规范中的统一集成包。旧独立包或其它分支须使用其对应版本说明,不要混用两套 Installer。安装行为以 多版本规范 为准。 :::
概述
ZLua 以 Unity Package(UPM)形式分发。安装 Package 后还须完成本地 Install(包内不携带完整 libil2cpp / Lua 源码)。典型流程:
- 在
Packages/manifest.json引入com.code-philosophy.zlua - 菜单
ZLua/Settings...选择 Lua 版本(默认lua-5.5.0) - 菜单
ZLua/Install...完成本地安装 - 配置 Lua 脚本目录与
LoadLuaModule,启动时调用LuaAppDomain.Initialize - 发布 Il2Cpp 前执行
ZLua/Generate/All(C++ stub,非 C# Wrap)
:::info 运行时 Mono(Editor)与 Il2Cpp(Player)均已完成,Lua 可见语义一致。多版本细节见 多版本管理、项目状态。 :::
前置要求
| 项 | 要求 |
|---|---|
| Unity | 见 兼容性(2022.3 / Unity 6 / 团结等) |
| Scripting Backend | Editor:Mono;Player:Il2Cpp |
| Lua | 由 Settings 指定(默认 lua-5.5.0);Install 时下载 / 装入本地树 |
| 网络 | 首次 Install 下载 PUC-Rio 源码时需要;LuaJIT 须自行 clone,且 Il2Cpp 发布仅 Android / iOS(见 多版本管理、LuaJIT 构建) |
| Git | UPM 从 Git URL 安装时需要 |
方式一:克隆 Demo 工程(推荐首次体验)
git clone https://github.com/focus-creative-games/zlua-demo.git
用任意 兼容性 所列 Unity 版本打开工程后,仍须执行下文 Settings → Install(若 Demo 尚未完成本地安装)。然后 Play SampleScene。核心文件:
| 文件 | 说明 |
|---|---|
| Packages/manifest.json | UPM 依赖,含 ZLua Git URL |
| Assets/Bootstrap.cs | 初始化与 GetFunction |
| Assets/Demo.cs | 供 Lua 调用的 C# 类型 |
| LuaScripts/app.lua | 主 Lua 模块 |
方式二:在现有工程中安装 ZLua
1. 添加 UPM 依赖
编辑 Packages/manifest.json,在 dependencies 中加入:
{
"dependencies": {
"com.code-philosophy.zlua": "https://github.com/focus-creative-games/zlua.git"
}
}
也可指定分支 / 标签,例如:
"com.code-philosophy.zlua": "https://github.com/focus-creative-games/zlua.git#v0.0.1-alpha.2"
保存后 Unity Package Manager 会自动拉取。Package 名称为 com.code-philosophy.zlua(见 zlua/package.json)。
2. 配置 Lua 版本(ZLua/Settings...)
菜单 ZLua/Settings... 打开 Project Settings → ZLua(资源写在 ProjectSettings/ZLua.asset)。
| 字段 | 说明 |
|---|---|
| Enable | 是否启用 ZLua |
| Lua Version Id | 要使用的 Lua / LuaJIT / Luau 版本 id;默认 lua-5.5.0(空则按此默认) |
| MarshalAs Xml Paths | 可选;MarshalAs XML 路径,见 LuaMarshalAs |
| Unity Optimizations | 默认开。字段说明见 Settings;当前效果见 Unity 优化 |
luaVersionId 写法(与 多版本管理 一致):
| 种类 | 格式 | 示例 |
|---|---|---|
| PUC-Rio | lua-X.Y.Z | lua-5.1.5、lua-5.2.4、lua-5.3.6、lua-5.4.8、lua-5.5.0 |
| LuaJIT | luajit-M.N | luajit-2.1(源码须自行 clone 到缓存目录;Il2Cpp 仅 Android / iOS,见 LuaJIT 构建) |
| Luau | luau-M.N | luau-0.743(仅官方仓库 luau 分支;Editor 仅 Windows。Install 按 tag 浅克隆 luau-lang/luau,并编译 Windows x64 静态库。见 兼容性) |
改版本后须重新执行 Install;若 Editor 原生 DLL / scripting define 随系列变化,按 Console 提示 重启 Editor。
3. 本地安装(ZLua/Install...)
菜单 ZLua/Install... 执行 统一 Install(HybridCLR 底座 + ZLua 叠加),在工程本地生成可编译的 Il2Cpp + HybridCLR + Lua + ZLua 树。主要工作:
- 安装 HybridCLR
libil2cpp(il2cpp_plus+hybridclr/)到本地 LocalIl2Cpp(与独立 HybridCLR UPM 互斥,勿再装com.code-philosophy.hybridclr) - 再叠加 ZLua:对 LocalIl2Cpp 打包内
libil2cpppatch,并将ZLua~/zlua-runtime复制到libil2cpp/zlua - 下载(或复用缓存)选定版本的 Lua 源码,安装到本地
libil2cpp/lua - 写入 scripting define、
ZLuaConf.inc(含ZLUA_USE_HYBRIDCLR)等,并做完整性校验;唯一设置UNITY_IL2CPP_PATH
发布前执行 ZLua/Generate/All:只跑一次 StripAOT,再串行 HybridCLR MethodBridge 与 ZLua CodeGenerator。
热更程序集加载后、首次访问类型前,在 Il2Cpp Player 调用 InteropMetadata.RegisterAliasXml / RegisterMarshalAsXml / RegisterExtensionXml(Editor 为空实现;无 Reload)。
PUC-Rio 源码缓存目录一般为 Library/ZLua/LuaSrcCache/(如 lua-5.5.0/)。细则与路径命名见 多版本管理。
:::warning 必须先 Install
未 Install 时构建会失败(提示运行 ZLua/Install...)。ZLua/Generate/All 也依赖本地树已存在。
:::
4. 目录结构(Lua 脚本)
推荐布局(与 Demo 一致):
YourProject/
├── Assets/
│ ├── Bootstrap.cs
│ ├── Editor/SyncLuaScriptsToStreamingAssets.cs
│ └── StreamingAssets/LuaScripts/app.lua.txt # 构建前同步生成
├── LuaScripts/app.lua # Editor 源文件
├── Packages/manifest.json
└── ProjectSettings/ZLua.asset
5. 同步 Lua 到 StreamingAssets(Player 必需)
按 首次构建 配置构建前同步与 Player loader。Editor 从项目根 LuaScripts 读取,Player 的具体加载方式取决于目标平台及项目资源系统。
6. 验证安装
Install 日志成功、工程能编译后,继续 快速开始 创建完整最小示例并验证 Console 输出。
Assembly Definition 说明
- ZLua Package 自带 asmdef(
ZLua.Common、ZLua.Mono、ZLua.Il2Cpp等),无需手动引用 native 插件。 - 你的游戏脚本程序集(如
Assembly-CSharp)引用ZLua即可使用LuaAppDomain、GetFunction等 API。 - Lua 中通过
CSharp['Assembly-CSharp'](或别名CSharp.AC)访问该程序集下的类型。
常见安装问题
| 现象 | 原因 | 处理 |
|---|---|---|
| Package 拉取失败 | 网络 / Git 未安装 | 检查 Git URL;可改用本地 path:"file:../../zlua" |
| 构建提示未 Install | 未跑 ZLua/Install... 或本地树过期 | 执行 Install;换 Unity / 换 Lua 版本后重跑 |
| Install 下载 Lua 失败 | 网络或版本 id 无效 | 检查 luaVersionId;见 多版本管理 缓存约定 |
| Play 后无 Lua 输出 | 未调用 Initialize 或模块路径错误 | 确认 BeforeSceneLoad 已执行;检查 LoadLuaModule 返回非 null |
| Player 找不到脚本 | 未同步 StreamingAssets | 运行 Sync 菜单或重新 Build |
Assembly-CSharp 找不到类型 | 脚本未编译或命名空间错误 | 确认 Demo 类为全局命名空间或修正 Lua 路径 |
| 换 Lua 系列后异常 | Editor DLL / define 未生效 | 按 Install 日志 重启 Editor |
Mono / Il2Cpp 支持
| 步骤 | Mono (Editor) | Il2Cpp (Player) |
|---|---|---|
| UPM 安装 | ✅ | ✅ |
| Settings + Install | ✅ | ✅(本地树供 Player 构建) |
LuaAppDomain.Initialize | ✅ | ✅ |
LuaAppDomain.Reset | ✅ | ✅ |
GetFunction<T> | ✅ | ✅ |
| 完整 Lua↔C# API | ✅ | ✅(语义一致;实现路径不同) |