Modding • Lua

Arcbound Lua Modding API (EA v1)

Lua mods load from Mods/<modId>/Scripts/init.lua at boot. Hooks must be registered during boot, and changing enabled mods requires restart.

← Modding home JSON spec →

1) Runtime policy

Mods are loaded at boot from Mods/<modId>/Scripts/init.lua
api.register_hook(...) is only allowed during boot
Mods are not hot-reloaded during active gameplay (restart required)

2) Folder layout

Mods/
  <modId>/
    mod.json
    Scripts/
      init.lua
    ... optional JSON def operation files ...

3) Global values

mod_id (string): current mod id from mod.json
api (table): API functions

4) API functions (high level)

Logging

api.log(message)

Hook registration

api.register_hook(eventName, callback)

Time + phase

api.get_phase()  -- "boot" | "phase1" | "phase2"
api.get_day()    -- integer

Definitions

api.def_exists(defType, stableId)
api.def_name(defType, stableId)

5) Resources + alerts

Alerts

api.push_alert(message, alertType)

Known alertType examples: CollapseEvent, Fire, HullBreach, LowFood, LowOxygen, MissionComplete, MissionDelayed, CrewCritical.

World resources

api.get_world_resource(key)
api.take_world_resource(key, amount)
api.spawn_world_resource(key, amount, x, y, z, maxRadius)

6) Hook events + payloads (summary)

on_boot
on_phase_changed
on_day_advanced
on_phase2_day_advanced
on_mission_completed
on_phase2_event

Payloads may be nil; modders should nil-check fields for compatibility.

7) Example init.lua

lua

api.log("mod boot: " .. tostring(mod_id))

api.register_hook("on_boot", function(ctx)
  api.log("boot phase=" .. tostring(ctx and ctx.phase))
end)

api.register_hook("on_day_advanced", function(ctx)
  if not ctx then return end
  if ctx.day % 10 == 0 then
    api.add_resource("Alloys", 5)
    api.push_alert("Logistics cache recovered (+5 alloys).", "MissionComplete")
  end
end)

api.register_hook("on_phase2_event", function(ctx)
  if not ctx then return end
  api.log("phase2 event: " .. tostring(ctx.event_id) .. " variant=" .. tostring(ctx.variant_id))
end)

8) Compatibility + versioning

Treat this as Lua API v1 for EA.
New functions/hooks are non-breaking.
Renaming/removing functions, hooks, or payload fields is breaking (bump API notes).
Modders should nil-check payload fields for forward compatibility.