跳到主要内容

安装与 Lua 版本

使用指南从本页开始：先装好包、选好 Lua 版本，再进入 初始化与最小互调。UPM 细节与 Demo 路径对照见 入门 · 安装与集成。

你要完成的三件事​

  1. 在工程中引入 com.code-philosophy.zlua
  2. 菜单 ZLua/Settings... 选定 Lua Version Id（默认 lua-5.5.0）
  3. 菜单 ZLua/Install... 生成本地 libil2cpp + Lua + zlua 树
注意

包内 不 携带完整 libil2cpp / Lua 源码。未 Install 时构建会失败；ZLua/Generate/All 也依赖本地树已存在。

1. 引入 Package​

编辑 Packages/manifest.json：

{
  "dependencies": {
    "com.code-philosophy.zlua": "https://github.com/focus-creative-games/zlua.git"
  }
}

也可钉版本标签，例如 #v0.0.1-alpha.2。首次体验推荐直接 clone zlua-demo。

2. 选定 Lua 版本（ZLua/Settings...）​

打开 Project Settings → ZLua（写入 ProjectSettings/ZLua.asset）。

字段说明
Enable是否启用 ZLua
Lua Version IdLua / LuaJIT 版本 id；空则默认 lua-5.5.0
MarshalAs Xml Paths可选；预编译程序集的 MarshalAs XML，见 LuaMarshalAs
Lua Alias Xml Paths可选；方法换名 XML（ZLuaAlias），见 LuaAlias
Lua Extension Xml Paths可选；C# Extension 映射 XML（ZLuaExtensions），见 Extension 方法

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）

改版本后须重新 Install；若 Editor DLL / scripting define 随系列变化，按 Console 提示 重启 Editor。平台与版本矩阵见 兼容性；多版本细则见 多版本管理。第三方 C 模块（socket / cjson 等）须按 同一系列 重编，见 第三方原生插件。

3. 本地 Install（ZLua/Install...）​

Install 主要工作：

  1. 复制 Editor 的 libil2cpp 到工程本地并打 patch
  2. 下载（或复用缓存）选定 Lua 源码到本地 libil2cpp/lua
  3. 将包内 ZLua~/zlua-runtime 复制到 libil2cpp/zlua
  4. 写入 scripting define、ZLuaConf.inc 等并校验

PUC-Rio 缓存一般在 Library/ZLua/LuaSrcCache/（如 lua-5.5.0/）。

4. 脚本目录（先搭好，下一篇会用到）​

推荐与 Demo 一致：

  • Editor： 项目根 LuaScripts/*.lua
  • Player： StreamingAssets/LuaScripts/*.lua.txt（构建前 Sync）

目录树、Sync 脚本、asmdef 说明见 安装与集成。

验证​

  1. Settings 中版本正确，Install 日志成功
  2. 工程能编译；下一篇用 Initialize + 最小互调确认 Play 有输出

常见问题​

现象处理
Package 拉取失败检查 Git / 网络；或改用本地 file: 路径
提示未 Install执行 ZLua/Install...；换 Unity / 换 Lua 版本后重跑
下载 Lua 失败检查 luaVersionId 与网络；见 多版本管理
换系列后异常按日志 重启 Editor

学习路径​

上一篇快速开始
下一篇初始化与最小互调

相关文档​