add-lua-binding-simple

name	add-lua-binding-simple
description	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.
metadata	{"argument-hint":"TypeName [output-file]"}

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

1. Identify the type you want to bind (e.g., my_type, my_enum)
2. Choose the binding file (usually src/catalua_bindings_ids.cpp for IDs, or a relevant catalua_bindings_*.cpp)
3. Add Luna documentation macro to src/catalua_luna_doc.h
4. Register the binding in the appropriate function
5. 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 property
• SET_MEMB_RO(name) - Read-only member
• SET_FX(name) - Member function
• SET_FX_T(name, signature) - Member function with specific overload

Luna Macros

• LUNA_ID(CppType, "LuaName") - For string_id/int_id pairs
• LUNA_DOC(CppType, "LuaName") - For documentation-only types
• LUNA_ENUM(CppType, "LuaName") - For enum types
• LUNA_VAL(CppType, "LuaName") - For value types
• LUNA_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

1. Linker errors: Make sure the type header is included
2. Missing comparison operators: Some types need operator== and operator<
3. Build errors: Check macro syntax and semicolons

Files to Modify

• src/catalua_luna_doc.h - Add LUNA_* macro
• src/catalua_bindings_ids.cpp - For ID types
• src/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