Skip to main content

Installation

This page uses the official sample project zlua-demo as the canonical reference; paths point at its main branch.

:::info Scope This page describes the unified integration package in the specification. Older standalone packages and other branches need their matching version instructions. Do not mix Installer workflows. See Multi-version specification. :::

Overview​

ZLua ships as a Unity Package (UPM). After adding the package you must still complete local Install (the package does not carry a full libil2cpp / Lua source tree). Typical flow:

  1. Add com.code-philosophy.zlua in Packages/manifest.json
  2. Menu ZLua/Settings... — pick a Lua version (default lua-5.5.0)
  3. Menu ZLua/Install... — finish local install
  4. Configure the Lua script directory and LoadLuaModule; call LuaAppDomain.Initialize at startup
  5. Before shipping Il2Cpp, run ZLua/Generate/All (C++ stubs, not C# Wrap)

:::info Runtime Mono (Editor) and Il2Cpp (Player) are both done, with matching Lua-visible semantics. Multi-version details: Multi-version, Project status. :::

Prerequisites​

ItemRequirement
UnitySee the maintained LTS versions in Compatibility.
Scripting BackendEditor: Mono; Player: Il2Cpp
LuaChosen in Settings (default lua-5.5.0); downloaded / installed into the local tree at Install
NetworkNeeded on first Install to download PUC-Rio sources; LuaJIT must be cloned yourself, and Il2Cpp shipping is Android / iOS only (see Multi-version, LuaJIT build)
GitRequired when installing UPM from a Git URL

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

Open the project with any Unity version listed under Compatibility, then still run Settings → Install below (if the Demo has not finished local install). Play SampleScene. Key files:

FileNotes
Packages/manifest.jsonUPM deps, including the ZLua Git URL
Assets/Bootstrap.csInit and GetFunction
Assets/Demo.csC# types called from Lua
LuaScripts/app.luaMain Lua module

Option 2: Install ZLua in an existing project​

1. Add the UPM dependency​

Edit Packages/manifest.json and add under dependencies:

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

You can pin a branch / tag, for example:

"com.code-philosophy.zlua": "https://github.com/focus-creative-games/zlua.git#v0.0.1-alpha.2"

After save, Unity Package Manager pulls automatically. Package id is com.code-philosophy.zlua (see zlua/package.json).

2. Configure Lua version (ZLua/Settings...)​

Menu ZLua/Settings... opens Project Settings → ZLua (asset at ProjectSettings/ZLua.asset).

FieldNotes
EnableWhether ZLua is enabled
Lua Version IdLua / LuaJIT / Luau version id; default lua-5.5.0 (empty → this default)
MarshalAs Xml PathsOptional; MarshalAs XML paths — see LuaMarshalAs
Unity OptimizationsOn by default. Field notes: Settings; current effect: Unity optimizations

luaVersionId formats (aligned with Multi-version):

KindFormatExamples
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 sources into the cache yourself; Il2Cpp only Android / iOS — see LuaJIT build)
Luauluau-M.Nluau-0.743 (official luau branch only; Editor is Windows only. Install shallow-clones that tag from luau-lang/luau and builds Windows x64 static libraries. See Compatibility)

After changing version, run Install again; if Editor native DLLs / scripting defines change with the series, restart the Editor as Console prompts.

3. Local Install (ZLua/Install...)​

The unified Installer creates the HybridCLR base (il2cpp_plus + hybridclr/), applies ZLua patches, copies ZLua~/zlua-runtime, and installs the selected Lua engine. It writes defines and ZLuaConf.inc, validates the result, and owns UNITY_IL2CPP_PATH. Do not add the standalone com.code-philosophy.hybridclr UPM package.

ZLua/Generate/All runs StripAOT once, then HybridCLR MethodBridge and ZLua CodeGenerator in sequence. For hot-update XML, load the assembly and register metadata before first type binding; see InteropMetadata.

PUC-Rio sources are cached in Library/ZLua/LuaSrcCache/. See the Install specification.

4. Script layout​

YourProject/
├── Assets/
│ ├── Bootstrap.cs
│ ├── Editor/SyncLuaScriptsToStreamingAssets.cs
│ └── StreamingAssets/LuaScripts/app.lua.txt # Generated before build
├── LuaScripts/app.lua # Editor source
├── Packages/manifest.json
└── ProjectSettings/ZLua.asset

5. Player script loading​

Follow First Player build for script synchronization and the Player loader. The Editor reads project-root LuaScripts; Player loading depends on the target platform and project resource system.

6. Verify installation​

Once Install succeeds and the project compiles, follow Quick start for complete minimal files and expected Console output.

Assembly Definition notes​

  • The ZLua Package ships asmdefs (ZLua.Common, ZLua.Mono, ZLua.Il2Cpp, etc.); you do not need to reference native plugins manually.
  • Your game script assembly (e.g. Assembly-CSharp) references ZLua to use LuaAppDomain, GetFunction, etc.
  • From Lua, access types under that assembly via CSharp['Assembly-CSharp'] (or alias CSharp.AC).

Common install issues​

SymptomCauseFix
Package fetch failsNetwork / Git missingCheck Git URL; or use a local path: "file:../../zlua"
Build says not InstalledDidn’t run ZLua/Install... or local tree staleRun Install; re-run after Unity / Lua version changes
Install fails downloading LuaNetwork or invalid version idCheck luaVersionId; see Multi-version cache rules
No Lua output after PlayInitialize not called or wrong module pathConfirm BeforeSceneLoad ran; ensure LoadLuaModule returns non-null
Player can’t find scriptsStreamingAssets not syncedRun Sync menu or rebuild
Assembly-CSharp type not foundScript not compiled or wrong namespacePut Demo types in global namespace or fix Lua path
Oddities after changing Lua seriesEditor DLL / defines not appliedRestart Editor per Install logs

Mono / Il2Cpp support​

StepMono (Editor)Il2Cpp (Player)
UPM install✅✅
Settings + Install✅✅ (local tree for Player builds)
LuaAppDomain.Initialize✅✅
LuaAppDomain.Reset✅✅
GetFunction<T>✅✅
Full Lua↔C# API✅✅ (same semantics; different implementation paths)

Next steps​