Skip to main content

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:

EasierModern, simple, zero config (no per-type C# Wrap whitelist)
More completeCovers nearly all common C#↔Lua features (generics, overloads, ref/out, arrays, delegates…)
FasterFour-way Il2Cpp measurements; see Performance for the report, environment, and ratios.
Less GCLow-allocation Marshal paths; distinguish managed and Lua allocation, warm-up and steady state. See GC boundaries.
Shared bridgeC++ stubs share reduced signatures. Binary-size savings need measurement; see Bridge analysis.
Broader versionsMultiple Lua engines and maintained Unity LTS series; see the compatibility matrix for versions, platforms, and branch limits.
Native HybridCLR supportWorks with HybridCLR v9.0.0+ out of the box; seamless interop with hot-update code
HybridCLR hot updateUnified installation and runtime metadata registration; see HybridCLR integration.
More active maintenanceFull-time professional team

Full rationale: Why ZLua; four-way comparison: Comparison.

Core features​

CapabilityNotes
Lua → C#Lazy-loaded CSharp root table; fields/methods/properties; generics and arrays; overloads; add_/remove_ for events
C# → LuaLuaAppDomain.GetFunction<T> then Invoke the Delegate
Dual runtimeMono (Editor) and Il2Cpp (Player) both done; same semantics, different implementation paths
MarshalByVal / 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​