Skip to main content
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:
NamespaceContents
xi.settingsServer configuration values (rates, toggles)
xi.zoneZone ID constants (xi.zone.NORTHERN_SAN_DORIA, etc.)
xi.itemItem ID constants
xi.kiKey item ID constants
xi.magicMagic spell constants and calculation helpers
xi.mobMob scripting helpers and NM spawn utilities
xi.shopShop display helpers
xi.playerPlayer creation and login hooks
xi.serverServer lifecycle hooks
xi.effectStatus effect constants
xi.modModifier constants (stats, rates)
xi.skillSkill type constants
xi.jobJob constants
xi.raceRace constants
xi.nationNation constants
xi.questLogQuest log area constants
xi.quest.idQuest ID sub-tables (e.g., xi.quest.id.sandoria)
xi.questStatusQuest 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us