Add Lua Binding Simple
Developmentadd-lua-binding-simpleAdd Lua Binding Simple is an Agent Skill for development published in the cataclysmbn/Cataclysm-BN repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Add simple Cataclysm-BN Lua bindings for string_id types, enums, and basic read-only C++ types. Use when exposing straightforward C++ types to Lua.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/cataclysmbn/Cataclysm-BN/blob/HEAD/.agents/skills/add-lua-binding-simple/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-lua-binding-simple, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Add Simple Lua Binding
This skill helps you add Lua bindings for simple C++ types like string_id, enums, or basic classes.
What You'll Do
- Identify the type you want to bind (e.g.,
my_type,my_enum) - Choose the binding file (usually
src/catalua_bindings_ids.cppfor IDs, or a relevantcatalua_bindings_*.cpp) - Add Luna documentation macro to
src/catalua_luna_doc.h - Register the binding in the appropriate function
- Build and test the changes
Step-by-Step Instructions
For string_id types
// In src/catalua_luna_doc.h, add:
LUNA_ID( my_type, "MyType" )
// In src/catalua_bindings_ids.cpp, in reg_game_ids():
reg_id<my_type, has_int_id>( lua );
// Use true if type has int_id, false otherwise
For enum types
// In src/catalua_luna_doc.h, add:
LUNA_ENUM( my_enum, "MyEnum" )
// In appropriate catalua_bindings_*.cpp file:
{
auto values = sol::initializers(
"VALUE_ONE", my_enum::VALUE_ONE,
"VALUE_TWO", my_enum::VALUE_TWO
);
luna::set_enum( lua, values );
}
Note: Use trailing return types and auto throughout (see patterns below).
For simple data types (read-only)
// In src/catalua_luna_doc.h, add:
LUNA_DOC( my_class, "MyClass" )
// In appropriate catalua_bindings_*.cpp:
#define UT_CLASS my_class
{
auto ut = luna::new_usertype<UT_CLASS>(
lua,
luna::no_bases,
luna::no_constructor
);
// Add members
SET_MEMB( my_field ); // Mutable field
SET_MEMB_RO( const_field ); // Read-only field
SET_FX( my_method ); // Method
}
#undef UT_CLASS
Important Patterns
Documentation Comments
DOC( "Description of the type" );
DOC( "Additional details about usage" );
Member Macros
SET_MEMB(name)- Mutable member variable or propertySET_MEMB_RO(name)- Read-only memberSET_FX(name)- Member functionSET_FX_T(name, signature)- Member function with specific overload
Luna Macros
LUNA_ID(CppType, "LuaName")- For string_id/int_id pairsLUNA_DOC(CppType, "LuaName")- For documentation-only typesLUNA_ENUM(CppType, "LuaName")- For enum typesLUNA_VAL(CppType, "LuaName")- For value typesLUNA_PTR_VAL(CppType, "LuaName")- For pointer types
Testing
After adding bindings:
# Build
cmake --build --preset linux-full --target cataclysm-bn-tiles
# Test in Lua console (debug menu -> Lua console)
local my_id = MyTypeId.new("some_id")
print(my_id:str())
print(my_id:is_valid())
Common Issues
- Linker errors: Make sure the type header is included
- Missing comparison operators: Some types need
operator==andoperator< - Build errors: Check macro syntax and semicolons
Files to Modify
src/catalua_luna_doc.h- Add LUNA_* macrosrc/catalua_bindings_ids.cpp- For ID typessrc/catalua_bindings_*.cpp- For other types (choose appropriate file)
References
- Lua Integration Docs:
docs/en/mod/lua/explanation/lua_integration.md - Existing Examples:
src/catalua_bindings_ids.cpp - Luna System:
src/catalua_luna.h