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 benchmarks: Lua→C# ≈ 2.57× / 3.52× / 7.68× for xLua / toLua / SLua vs ZLua; see Performance |
| Less GC | Reference types and structs default to 0 GC; flexible strategies such as OpaqueValue |
| Tiny bridge | Same-signature merged C++ stubs; footprint can be an order of magnitude smaller; down to 0 bridge functions |
| Broader versions | Lua 5.1–5.5 / LuaJIT (Il2Cpp JIT only Android / iOS); Unity 2021+; Tuanjie Engine |
| 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
- 5-minute Quick start — minimal working example
- Why ZLua — why pick ZLua
- Installation — UPM install and project layout
- Guides — progressive tutorials (install → interop → build → …)
- Comparison — vs xLua / toLua / SLua
- Performance benchmarks — reproducible Il2Cpp comparison and latest report
- Spec overview — authoritative semantic contract