luaBinding Reference

Module defined in lua/common/luaBinding.lua. Core C++/Lua binding infrastructure implementing property getters/setters, inheritance chains, and SimObject field access for engine-bound classes.

---

Exports

All exports are global functions (called by the C++ binding system).

Functions

__luaBindIndex(t, k)

Metatable __index handler for C++-bound instance objects. Searches: metatable → getters → super chain.

• Parameters:
  • t - userdata - The bound object
  • k - string - Property/method name

__luaBindIndexStatic(t, k)

Metatable __index handler for C++-bound static classes. Similar to __luaBindIndex but calls getters without self.

__luaBindNewindex(t, k, v)

Metatable __newindex handler for C++-bound instance objects. Searches setters in current and super metatables.

• Parameters:
  • t - userdata - The bound object
  • k - string - Property name
  • v - any - Value to set

__luaBindNewindexStatic(t, k, v)

Metatable __newindex handler for static classes (no self parameter).

__finalizeLuaBindings(classes, luaVMname)

Called after all C++ classes are registered. Optimizes metatables: flattens SimObject hierarchies, sets up field accessors, removes unnecessary indirection.

• Parameters:
  • classes - table - Map of class names to metatable tables
  • luaVMname - string - Lua VM type (e.g., "vlua", "game")

testBindings()

Unit test for the binding system using TestNamespace.TestClassA/B.

Internal Notes

• Metatable structure: mt[1] = getters table, mt[2] = setters table, mt[3] = super metatable
• Getter/setter functions are cached in the origin metatable after first lookup for O(1) subsequent access
• SimObject types (identified by isSubClassOf and key starting with 'd') get special handling:
  • Flattened metatable (all super methods/getters merged)
  • Custom __index/__newindex that falls through to getStaticDataFieldbyName/getDynDataFieldbyName
  • Fields mt[4-7] store data field accessor functions
• Optimization pass: when a class has no super, no getters, or no setters, unnecessary metatable entries are removed
• Function names are hardcoded and must not be changed (referenced from C++)