Introduction
ZLua is a modern native Lua solution highly optimized for Unity Il2Cpp.
It unifies bidirectional C# ↔ Lua calls with clear rules, treating Lua as another form of Native—analogous to P/Invoke—with concepts such as LuaAppDomain.GetFunction and [LuaMarshalAs], while hiding the error-prone Lua C API.
Why choose ZLua
Compared with xLua / toLua / SLua, ZLua’s core claims are:
| Easier | Modern, simple, zero config (no per-type C# Wrap whitelist) |
| More complete | Covers nearly all common C#↔Lua features (generics, overloads, ref/out, arrays, delegates…) |
| Faster | Four-way Il2Cpp measurements; see Performance for the report, environment, and ratios. |
| Less GC | Low-allocation Marshal paths; distinguish managed and Lua allocation, warm-up and steady state. See GC boundaries. |
| Shared bridge | C++ stubs share reduced signatures. Binary-size savings need measurement; see Bridge analysis. |
| Broader versions | Multiple Lua engines and maintained Unity LTS series; see the compatibility matrix for versions, platforms, and branch limits. |
| Native HybridCLR support | Works with HybridCLR v9.0.0+ out of the box; seamless interop with hot-update code |
| HybridCLR hot update | Unified installation and runtime metadata registration; see HybridCLR integration. |
| More active maintenance | Full-time professional team |
Full rationale: Why ZLua; four-way comparison: Comparison.
Core features
| Capability | Notes |
|---|---|
| Lua → C# | Lazy-loaded CSharp root table; fields/methods/properties; generics and arrays; overloads; add_/remove_ for events |
| C# → Lua | LuaAppDomain.GetFunction<T> then Invoke the Delegate |
| Dual runtime | Mono (Editor) and Il2Cpp (Player) both done; same semantics, different implementation paths |
| Marshal | ByVal / ByObj / Opaque and more; see Marshal Spec |
:::info Current status Mono · DoneIl2Cpp · Done
Develop day-to-day in the Editor (Mono); ship and measure performance on the Il2Cpp Player (run ZLua/Generate/All before building). See Project status.
:::
Next steps
- Quick start — minimal working example
- Why ZLua — why pick ZLua
- Installation — UPM install and project layout
- Guides — progressive tutorials (install → interop → build → …)
- HybridCLR integration — dual-package install order and hot-update constraints
- Comparison — vs xLua / toLua / SLua
- Performance benchmarks — reproducible Il2Cpp comparison and latest report
- Spec overview — authoritative semantic contract