跳到主要内容

安装与集成

本文以官方示例工程 zlua-demo 为 canonical 参考,路径均指向其 main 分支。

:::info 适用范围 本页描述规范中的统一集成包。旧独立包或其它分支须使用其对应版本说明,不要混用两套 Installer。安装行为以 多版本规范 为准。 :::

概述​

ZLua 以 Unity Package(UPM)形式分发。安装 Package 后还须完成本地 Install(包内不携带完整 libil2cpp / Lua 源码)。典型流程:

  1. 在 Packages/manifest.json 引入 com.code-philosophy.zlua
  2. 菜单 ZLua/Settings... 选择 Lua 版本(默认 lua-5.5.0)
  3. 菜单 ZLua/Install... 完成本地安装
  4. 配置 Lua 脚本目录与 LoadLuaModule,启动时调用 LuaAppDomain.Initialize
  5. 发布 Il2Cpp 前执行 ZLua/Generate/All(C++ stub,非 C# Wrap)

:::info 运行时 Mono(Editor)与 Il2Cpp(Player)均已完成,Lua 可见语义一致。多版本细节见 多版本管理、项目状态。 :::

前置要求​

项要求
Unity见 兼容性(2022.3 / Unity 6 / 团结等)
Scripting BackendEditor:Mono;Player:Il2Cpp
Lua由 Settings 指定(默认 lua-5.5.0);Install 时下载 / 装入本地树
网络首次 Install 下载 PUC-Rio 源码时需要;LuaJIT 须自行 clone,且 Il2Cpp 发布仅 Android / iOS(见 多版本管理、LuaJIT 构建)
GitUPM 从 Git URL 安装时需要

方式一:克隆 Demo 工程(推荐首次体验)​

git clone https://github.com/focus-creative-games/zlua-demo.git

用任意 兼容性 所列 Unity 版本打开工程后,仍须执行下文 Settings → Install(若 Demo 尚未完成本地安装)。然后 Play SampleScene。核心文件:

文件说明
Packages/manifest.jsonUPM 依赖,含 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-Riolua-X.Y.Zlua-5.1.5、lua-5.2.4、lua-5.3.6、lua-5.4.8、lua-5.5.0
LuaJITluajit-M.Nluajit-2.1(源码须自行 clone 到缓存目录;Il2Cpp 仅 Android / iOS,见 LuaJIT 构建)
Luauluau-M.Nluau-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 树。主要工作:

  1. 安装 HybridCLR libil2cpp(il2cpp_plus + hybridclr/)到本地 LocalIl2Cpp(与独立 HybridCLR UPM 互斥,勿再装 com.code-philosophy.hybridclr)
  2. 再叠加 ZLua:对 LocalIl2Cpp 打包内 libil2cpp patch,并将 ZLua~/zlua-runtime 复制到 libil2cpp/zlua
  3. 下载(或复用缓存)选定版本的 Lua 源码,安装到本地 libil2cpp/lua
  4. 写入 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✅✅(语义一致;实现路径不同)

下一步​