Lua scripting overview

Every piece of game content in LandSandBoat is driven by Lua scripts. NPCs, quests, missions, monsters, spells, abilities, and items all run through scripts loaded from the scripts/ directory. The C++ server core handles networking, the game loop, and low-level entity management; Lua handles all game logic on top of that.

The `xi` namespace

All server-side Lua code lives under the global xi table. Sub-namespaces group related constants and functions:

Namespace	Contents
`xi.settings`	Server configuration values (rates, toggles)
`xi.zone`	Zone ID constants (`xi.zone.NORTHERN_SAN_DORIA`, etc.)
`xi.item`	Item ID constants
`xi.ki`	Key item ID constants
`xi.magic`	Magic spell constants and calculation helpers
`xi.mob`	Mob scripting helpers and NM spawn utilities
`xi.shop`	Shop display helpers
`xi.player`	Player creation and login hooks
`xi.server`	Server lifecycle hooks
`xi.effect`	Status effect constants
`xi.mod`	Modifier constants (stats, rates)
`xi.skill`	Skill type constants
`xi.job`	Job constants
`xi.race`	Race constants
`xi.nation`	Nation constants
`xi.questLog`	Quest log area constants
`xi.quest.id`	Quest ID sub-tables (e.g., `xi.quest.id.sandoria`)
`xi.questStatus`	Quest status constants (`QUEST_AVAILABLE`, etc.)

C++ and Lua bindings

LandSandBoat uses sol2 to expose C++ objects to Lua. The binding definitions live in src/map/lua/. Each major game object has its own binding file:

src/map/lua/
  lua_baseentity.cpp / .h     # All entities (players, mobs, NPCs)
  lua_spell.cpp / .h          # Spell objects
  lua_weaponskill.cpp / .h    # Weapon skill objects
  lua_mobskill.cpp / .h       # Mob skill objects
  lua_ability.cpp / .h        # Job ability objects
  lua_item.cpp / .h           # Item objects
  lua_zone.cpp / .h           # Zone objects
  lua_trade_container.cpp / .h # Trade containers
  lua_statuseffect.cpp / .h   # Status effect objects
  lua_attack.cpp / .h         # Attack objects
  lua_battlefield.cpp / .h    # Battlefield instances
  lua_instance.cpp / .h       # Content instances
  lua_loot.cpp / .h           # Loot/treasure pool objects
  luautils.cpp / .h           # Global utility functions
  sol_bindings.cpp / .h       # sol2 registration

Methods on these objects are called with the colon syntax in Lua:

player:addItem(xi.item.ONION_SWORD)       -- calls CBaseEntity::addItem
player:getMainLvl()                        -- calls CBaseEntity::getMainLvl
mob:spawn()                               -- calls CBaseEntity::spawn
spell:getElement()                        -- calls CLuaSpell::getElement

Directory structure

scripts/
  globals/         -- Globally loaded scripts (see Global scripts)
    combat/        -- Combat calculation modules
    interaction/   -- Interaction framework classes
    spells/        -- Spell calculation helpers (damage_spell.lua, etc.)
    job_utils/     -- Per-job utility functions
  actions/         -- Executable game actions
    spells/        -- Per-spell scripts (black/, white/, blue/, etc.)
    abilities/     -- Per-ability scripts
    mobskills/     -- Per-mob-skill scripts
    weaponskills/  -- Per-weapon-skill scripts
  zones/           -- One directory per zone (~290 zones)
    <ZoneName>/
      Zone.lua           -- Zone-level event handlers
      IDs.lua            -- Zone-local text/NPC/mob ID tables
      DefaultActions.lua -- Default NPC dialogue/events
      npcs/              -- Per-NPC script files
      mobs/              -- Per-mob/NM script files
  quests/          -- Quest scripts using the interaction framework
  missions/        -- Mission scripts
  commands/        -- GM and player command scripts
  items/           -- Per-item use/check scripts (named by item name)
  mixins/          -- Reusable mob behavior components
  events/          -- Seasonal event scripts

Global scripts

Server hooks, npcUtil, shop, treasure, and other globally loaded modules.

Zones and NPCs

Zone structure, IDs.lua, Zone.lua handlers, NPC script patterns.

Interaction framework

The quest/mission section and action system.

Quests and missions

Quest containers, variables, status constants, and registration.

Actions and handlers

All action types, modifiers, table shorthand, and handler signatures.

Combat scripting

Weapon skills, mob skills, physical damage calculations.

Spells and abilities

Spell scripts, magic calculations, blue magic, job abilities.

Item scripting

Item use handlers, trade checks, item utility functions.

Mob scripting

Mob handlers, NM spawn systems, placeholder lists, mob skill scripting.

Interaction Framework

Game Systems

Lua scripting overview

The `xi` namespace

C++ and Lua bindings

Directory structure

Global scripts

Zones and NPCs

Interaction framework

Quests and missions

Actions and handlers

Combat scripting

Spells and abilities

Item scripting

Mob scripting

​The xi namespace

​C++ and Lua bindings

​Directory structure

Global scripts

Zones and NPCs

Interaction framework

Quests and missions

Actions and handlers

Combat scripting

Spells and abilities

Item scripting

Mob scripting

The `xi` namespace

C++ and Lua bindings

Directory structure