Skip to main content

Why ZLua

xLua, toLua, and SLua proved that “Lua in Unity” works. ZLua targets the next layer: make Lua↔C# truly modern, complete, and fast and lean enough on Il2Cpp—instead of piling on more config, whitelists, and mountains of Wrap.

Detailed matrix: Comparison; migration: migration.


Seven reasons (30 seconds)​

One-liner
EasierMore modern design; extremely simple; zero config (no per-type C# Wrap whitelist)
More completeStandard, complete C#↔Lua interop covering nearly all common C# features
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.
More active maintenanceFull-time professional team; faster bug response and feature iteration

1. Easier: modern, simple, zero config​

Traditional schemes often burden you with:

  • Maintaining LuaCallCSharp / export lists
  • Re-Generating huge C# Wrap whenever APIs change
  • Imperative C#→Lua via LuaEnv / GetInPath / Call

ZLua models interop closer to declarative P/Invoke:

What you wantZLua
C# call LuaLuaAppDomain.GetFunction<T>(…) then Invoke the Delegate
Override Marshal[LuaMarshalAs]
Lua access C#Lazy-loaded CSharp root table — no per-type Wrap config
// Must be after Initialize (e.g. Awake); do not use static field initializers
var AppAdd = LuaAppDomain.GetFunction<Func<int, int, int>>("app", "add");
// AppAdd(10, 20);
CSharp['AC'] = CSharp['Assembly-CSharp']
print(CSharp.AC.Demo.Add(3, 5))

Zero config means: no per-type C# Wrap whitelist or member-level Wrap project. Editor works out of the box; for Il2Cpp Player run ZLua/Generate/All once (generates C++ stubs, not xLua-style C# Wrap).

→ Quick start · Guides


2. More complete: almost anything callable in C# is callable​

The goal is not “export a few hot-path APIs”, but standard, complete C#↔Lua interop, including but not limited to:

CategoryCapabilities
Typesclass / struct / interface / enum / nullable
MembersStatic and instance: fields, properties, methods
AdvancedGeneric classes, generic methods, delegates, arrays (incl. multi-dim)
Language detailsMethod overloads, ref / out / in, Event (add_ / remove_)

Semantics are contracted by the Spec; both ends (Mono Editor / Il2Cpp Player) have matching Lua-visible behavior.

→ Compatibility matrix · Features


3. Faster: not “theoretically a bit quicker”​

On Il2Cpp Win64 Release, four-way aligned benchmarks (public repo zlua-benchmark; notes in PERFORMANCE):

See Performance for the report, Unity version, sample count, ratios, and measured limits.

Root cause is direct: drop libxlua round-trips + huge C# Wrap, and finish marshal + methodPointer call once in C++.

tip

Even fast interop needs profiling first. If the script boundary is only 2% of frame time, 5× interop saves ~1.6%. ZLua fits combat formulas, UI, and many small per-frame calls as boundary hotspots.

→ Performance


4. Less & faster GC​

Default strategy targets hot paths:

StrategyMeaning
Reference typesDefault object table / userdata — avoid pointless boxing and temporary object[]
structRepresentation and allocation depend on fields, direction, and Marshal strategy; measure the target Player.
OpaqueValuelightuserdata temporary handles: more flexible low-allocation strategy within a sync call chain
enumDefault integer; no forced boxed userdata

For write-back use Opaque / ByVal userdata; bare numbers do not write back (aligned with C# ref semantics — see ref/out/in).

→ GC · Lifetime Spec


5. Signature-shared C++ bridges​

SolutionTypical size model
xLua / toLua / SLuaPer-type / per-member Wrap; size grows roughly linearly with exported members
ZLua (Il2Cpp)Merge same signatures into efficient C++ stubs (ReducedType reuse)

So while still accessing almost all C# types, fields, properties, and methods:

  • Signature reuse reduces duplicated bridge code; binary-size ratios are not yet measured.
  • Compare generated source, distinct stubs, and final Player size separately; no universal size or speed claim follows from the model.

Editor (Mono) uses Expression Emit, not shipped in the Player package; Player size is driven by C++ stubs.

→ Bridge & size


6. More Unity and Lua versions​

More versions means less risk of being stuck on one Lua/Unity combo. Full matrix: Compatibility.

→ Supported versions & platforms


7. More active maintenance​

ZLua is maintained by a full-time professional team:

  • More responsive bug handling
  • Faster feature and Spec iteration
  • Docs, benchmarks, and in-package Docs evolve together

Treat Lua interop as long-term infrastructure, not a “stale third-party plugin”.


When not to choose ZLua​

Honest boundaries matter too:

SituationSuggestion
Unwilling to maintain libil2cpp integrationPlugin-shaped xLua / toLua is lighter
Hard dependency on xLua Hotfix pipelinesKeep using xLua
Large xLua asset base, no short-term migration budgetRead Migrate from xLua first

Next steps​

  1. Quick start + zlua-demo
  2. Performance · GC · BRIDGE
  3. Features
  4. Spec overview

Further reading​

DocContent
Design overviewGetFunction and bidirectional bridging
Dual runtimeMono / Il2Cpp split
GlossaryOpaque / ByVal / stub, etc.
Il2Cpp implPlayer module map