Axmol v3: New Lua Binding System Replaces tolua++
Published on September 3, 2026 by halx99
We’ve completed a major modernization of Axmol v3’s Lua binding system.
The long-standing Python + tolua++ toolchain has been replaced with a new generator built around PowerShell, C#, and libclang, with sol2 handling general Lua/C++ type conversion.
This is much more than a generator replacement. The new architecture makes Lua bindings easier to maintain as the C++ API evolves, while preserving Axmol-specific behavior such as object identity, lifetime management, inheritance, Lua overrides, callbacks, and dynamic fields.
Highlights
- AST-based generation using libclang instead of fragile text parsing
- A single cross-platform entry point: axmol genbindings
- Coverage of 15 modules and 499 registered classes
- Automatic handling of inheritance, overloads, default arguments, enums, fields, and std::function callbacks
- Deterministic generated output that can be verified in CI
- Clear separation between generated bindings, runtime behavior, and special adapters
- Support for Lua 5.1–5.5 and LuaJIT 2.1+
- Significant binding performance improvements during the rewrite
In our Windows Release/O3 binding performance test, the previous binding system handled roughly 12,500–13,000 sprites at the target frame rate, while the new implementation reaches around 14,500 after lookup-path optimization.
Most existing Lua projects should continue using familiar APIs such as sprite:method() without changes.
The work is being developed in:
This rewrite removes a large amount of historical tolua++ infrastructure and gives Axmol a much cleaner foundation for maintaining and expanding Lua support in v3.
Thank you to everyone supporting Axmol. Sponsorship helps make large, long-term engineering work like this possible.