Lua/C++ bindings

Overview

LandSandBoat uses sol2 to expose C++ game objects to Lua scripts. The binding layer lives in src/map/lua/ and consists of:

CLua* wrapper classes — thin wrappers around C++ game objects that expose methods to Lua
sol_bindings.h/cpp — macro infrastructure and sol_lua_push overloads that allow C++ to pass objects to Lua
luautils.h/cpp — the global Lua state, event dispatch functions, and utility helpers

The global sol::state lua is declared in luautils.h and is the single Lua VM that all scripts share.

How bindings work

Each C++ game class that Lua scripts can touch has a corresponding CLua* wrapper:

C++ class          Lua wrapper          Lua type name
─────────────────────────────────────────────────────
CBaseEntity    →   CLuaBaseEntity   →   "BaseEntity"
CZone          →   CLuaZone         →   "Zone"
CItem          →   CLuaItem         →   "Item"
CSpell         →   CLuaSpell        →   "Spell"
CStatusEffect  →   CLuaStatusEffect →   "StatusEffect"
CBattlefield   →   CLuaBattlefield  →   "Battlefield"
CInstance      →   CLuaInstance     →   "Instance"

sol_bindings macros

sol_bindings.h defines convenience macros for registering types and their inheritance:

// Register a new Lua usertype
SOL_USERTYPE("BaseEntity", CLuaBaseEntity);

// Register a usertype that inherits from another
SOL_USERTYPE_INHERIT("CharEntity", CLuaBaseEntity, CLuaBaseEntity);

// Register a method on the current type
SOL_REGISTER("getID", CLuaBaseEntity::getID);

// Register a read-only property
SOL_READONLY("id", CLuaBaseEntity::getID);

Pushing objects from C++ to Lua

When C++ needs to pass a game object to a Lua callback, sol_lua_push overloads handle the conversion. The SOL_BIND_DEF macro generates these:

// sol_bindings.h — generated declarations
SOL_BIND_DEC(CLuaBaseEntity, CBaseEntity);

// For subclasses that should be pushed as the base Lua type:
SOL_BIND_DEC_SUB(CLuaBaseEntity, CBaseEntity, CCharEntity);
SOL_BIND_DEC_SUB(CLuaBaseEntity, CBaseEntity, CMobEntity);
SOL_BIND_DEC_SUB(CLuaBaseEntity, CBaseEntity, CNpcEntity);

This means that when C++ calls a Lua function and passes a CCharEntity*, it automatically arrives in Lua as a BaseEntity with all CLuaBaseEntity methods available.

Binding files reference

lua_baseentity — base entity methods

Files: lua_baseentity.h/cppThe largest binding file. CLuaBaseEntity wraps CBaseEntity and provides methods available to all entity types (characters, mobs, NPCs, pets, trusts):

Identity: getID(), getName(), getEntityType()
Position: getPos(), setPos(), getZone()
Stats: getHP(), getMP(), getTP(), getMainJob(), getMainLvl()
Status effects: addStatusEffect(), delStatusEffect(), hasStatusEffect()
Inventory: addItem(), hasItem(), delItem()
Flags and variables: getCharVar(), setCharVar()
Events: startEvent(), updateEvent(), release()

Character subtype (CCharEntity) and mob subtype (CMobEntity) both arrive in Lua as BaseEntity.

lua_zone — zone methods

Files: lua_zone.h/cppCLuaZone wraps CZone and provides:

Local variables: getLocalVar(), setLocalVar(), resetLocalVars()
Trigger areas: registerCuboidTriggerArea(), registerCylindricalTriggerArea()
Entity queries via the zone object

lua_item — item methods

Files: lua_item.h/cppCLuaItem wraps CItem and its subtypes (CItemEquipment, CItemWeapon, CItemUsable, CItemFurnishing, etc.):

Item identity: getID(), getName(), getStackSize()
Equipment: slot, level requirements, jobs allowed
Usable items: charges, cast time, recast time

lua_spell — spell methods

Files: lua_spell.h/cppCLuaSpell wraps CSpell:

getID(), getName(), getSkillType()
Target and AoE information
Element, MP cost, cast and recast times
Interrupted and reflected state

lua_statuseffect — status effect methods

Files: lua_statuseffect.h/cppCLuaStatusEffect wraps CStatusEffect:

getStatusID(), getPower(), getTick(), getDuration()
setDuration(), setPower(), setSubPower()
Source entity, tier, and flag access

lua_battlefield — battlefield methods

Files: lua_battlefield.h/cppCLuaBattlefield wraps CBattlefield (BCNM/ISNM/ENM content):

getID(), getStatus(), setStatus()
getTimeLimit(), getTimeInside()
addEnemy(), getLocalVar(), setLocalVar()
Win/loss/time-limit condition triggers

lua_instance — instance methods

Files: lua_instance.h/cppCLuaInstance wraps CInstance (instanced zone content):

getID(), getStage(), setStage()
Progress tracking, time remaining
Entity spawning within the instance

lua_ability, lua_mobskill, lua_weaponskill

CLuaAbility — job ability methods (ID, type, range, area)
CLuaMobSkill — mob skill methods (ID, range, target type)
CLuaWeaponSkill — weapon skill methods (ID, skill type, TP cost)
CLuaPetSkill — pet skill methods

lua_trade_container — trade container methods

Files: lua_trade_container.h/cppCLuaTradeContainer wraps CTradeContainer:

getItem(), getItemCount(), hasItemQty()
Trade slot iteration

luautils — C++ to Lua dispatch

luautils.h/cpp is the bridge that allows C++ to call Lua functions. It declares the global sol::state lua and provides:

callGlobal — calling Lua from C++

// Call a void global function
luautils::callGlobal<void>("xi.server.onTimeServerTick");

// Call with arguments
luautils::callGlobal<void>("xi.player.onPlayerDeath", PChar);

// Call and get a return value
auto value = luautils::callGlobal<uint32>("xi.server.functionThatReturnsANumber");

If the function is not found or throws an error, callGlobal logs the error and returns a default value.

Event dispatch

The luautils namespace exposes C++ functions for every game event that Lua scripts can handle:

// Zone lifecycle
void OnZoneIn(CCharEntity* PChar);
void OnZoneOut(CCharEntity* PChar);
void OnZoneInitialize(uint16 ZoneID);
void OnZoneTick(CZone* PZone);

// NPC interaction
int32 OnTrigger(CCharEntity* PChar, CBaseEntity* PNpc);
void  OnTrade(CCharEntity* PChar, CBaseEntity* PNpc);

// Mob events
void OnMobSpawn(CBaseEntity* PMob);
void OnMobEngage(CBaseEntity* PMob, CBaseEntity* PTarget);
void OnMobDeath(CBaseEntity* PMob, CBaseEntity* PKiller);

// Player events
void OnPlayerDeath(CCharEntity* PChar);
void OnPlayerLevelUp(CCharEntity* PChar);
void OnPlayerMount(CCharEntity* PChar);

// Spell/ability events
int32 OnSpellCast(CBattleEntity* PCaster, CBattleEntity* PTarget, CSpell* PSpell);
int32 OnUseAbility(CBattleEntity* PUser, CBattleEntity* PTarget, CAbility* PAbility, action_t* action);

Calling C++ from Lua

From a Lua script, C++-bound methods are called directly on the object:

-- NPC trigger handler in scripts/zones/South_Gustaberg/npcs/MyNPC.lua
local entity = {}

entity.onTrigger = function(player, npc)
    -- player is a CLuaBaseEntity wrapping CCharEntity
    local name = player:getName()        -- calls CLuaBaseEntity::getName()
    local level = player:getMainLvl()    -- calls CLuaBaseEntity::getMainLvl()
    local zone  = player:getZone()       -- returns a CLuaZone

    -- Start a cutscene event
    player:startEvent(100)
end

return entity

-- Mob death handler
local mob = {}

mob.onMobDeath = function(mob, player, optParams)
    -- Drop a key item on death
    if player then
        player:addKeyItem(xi.ki.FORBIDDEN_KEY)
        player:messageBasic(xi.msg.basic.KEYITEM_OBTAINED, xi.ki.FORBIDDEN_KEY)
    end
end

return mob

sol_bindings.cpp — registration

sol_bindings.cpp contains the actual sol_lua_push function bodies generated by the SOL_BIND_DEF and SOL_BIND_DEF_SUB macros. These are the functions that sol2 calls when C++ code passes a C++ pointer into a Lua function call. They ensure null pointers become nil in Lua and that subclass pointers are correctly presented as the base Lua type.

Contributing

Architecture

Tools

Overview

How bindings work

sol_bindings macros

Pushing objects from C++ to Lua

Binding files reference

luautils — C++ to Lua dispatch

callGlobal — calling Lua from C++

Event dispatch

Calling C++ from Lua

sol_bindings.cpp — registration

​Overview

​How bindings work

​sol_bindings macros

​Pushing objects from C++ to Lua

​Binding files reference

​luautils — C++ to Lua dispatch

​callGlobal — calling Lua from C++

​Event dispatch

​Calling C++ from Lua

​sol_bindings.cpp — registration

Overview

How bindings work

sol_bindings macros

Pushing objects from C++ to Lua

Binding files reference

luautils — C++ to Lua dispatch

callGlobal — calling Lua from C++

Event dispatch

Calling C++ from Lua

sol_bindings.cpp — registration