Mods

What you can build

A mod is a folder in src/mods/ with a mod.cfg file in it. The game loads every enabled mod at startup, sends it events every frame, and reloads it the moment you save a file. Mods are written in Lua, in OrphanASM (the engine's own assembly language), or both.

Mods are sandboxed. They can't touch files outside their own folder, run programs, or freeze the game: every call has a time budget and every Lua mod has a memory cap. A broken mod shows an error on the MODS screen instead of taking the game down.

These mods ship in src/mods/. Reading them next to this guide is the fastest way to learn:

The test mods in tests/luatest/ are small and exercise one part of the API each, so they're good reading too. The full list of every function, generated from the game's own docs, is docs/MOD_API.md in the source, and the same text is in Orphan Editor's F1 panel.

Setup and tools

Build the game and the editor

From the project folder, run build.bat, or use Geany's Build menu, which calls the same script.

Both programs run with src/ as their working folder, so every path in this guide, like mods/hello_lua/main.lua, is relative to src/.

The three places you'll work

• Orphan Editor (bin/orphan_editor.exe): a code editor made for mods, with autocomplete and docs for the whole API (press F1), live error checking, a preview window that runs your mod, a debugger, and a live link to the running game.
• The MODS screen: main menu → MODS. Switch mods on and off, see errors, change mod settings, play maps.
• The dev console: press ` in the game. Every mod command lives here (cheat sheet).

You can use any text editor instead of Orphan Editor. Hot reload works either way: save the file and the game reloads the mod within a second.

Editor shortcuts worth knowing

Your first mod

This walks through a small Lua mod, from an empty folder to a feature with a setting, in about ten minutes.

1. Create it.In Orphan Editor pick Mods → New Lua Mod and call it first_mod. You can also type mod_new first_mod in the game console, or click NEW MOD on the MODS screen. You get mods/first_mod/mod.cfg and a working main.lua.
2. Say hello.Replace main.lua with:

   orphan.on("load", function()
     orphan.ok("first_mod is alive")
   end)
   
   orphan.command("greet", "Say hi", function(name)
     orphan.log("hi " .. (name or "operator"))
   end)

   Press Ctrl+Shift+G to start the game, open the console with ` and type greet Sam.
3. Draw something.Add a draw handler. Save, and it appears in the running game without a restart:

   orphan.on("draw", function()
     local w = orphan.draw.width()
     orphan.draw.rect(w - 230, 60, 220, 40, { 0, 0, 0, 160 })
     orphan.draw.text("FIRST MOD", w - 220, 70, 20, "lime")
   end)

4. Keep state across reloads.Plain locals reset every time you save. Anything you put in orphan.persist survives:

   local clicks = orphan.persist.clicks or 0
   orphan.on("update", function(dt)
     if orphan.input.pressed("F10") then
       clicks = clicks + 1
       orphan.persist.clicks = clicks
     end
   end)

5. Add a setting.orphan.newcvar makes a saved setting that appears on your mod's page in the MODS screen. A boolean default gives a switch, a min and max give a slider:

   local show = orphan.newcvar("first_show", true, "Show the panel")
   local size = orphan.newcvar("first_size", 20, "Text size", 10, 40)
   orphan.on("cvar", function(name, value)
     if name == "first_show" then show = value end
     if name == "first_size" then size = value end
   end)

   Use show and size in your draw handler, then flip the switch on the MODS screen.
6. Debug it.With the editor attached (the status bar says SPASTAZ ATTACHED), click left of the line number on a line inside your update handler. The next time that line runs, the game pauses your mod there and the editor shows its variables. Press F10 to step, F5 to continue.
7. Fill in the manifest.Open mod.cfg and give your mod a real name, version and description. That's what players see on the MODS screen (chapter 4).

The manifest: mod.cfg

name        = Hover Pads
version     = 1.0
author      = You
description = Pads that float things above them, for the Sandbox
entry       = main.lua          # main.oasm for OrphanASM
enabled     = 1                 # load at startup
priority    = 10                # lower loads first (after requirements)
api_version = 1                 # the mod API this was written for
requires    = sandbox >= 1.0
network     = required          # servers running it need joining players to have it
private     = sv_, server/      # files a server keeps to itself (chapter 14)

Network: playing online

network says whether a server running your mod needs the players joining it to have it too:

• required: always, while it's running on the server. Use it for anything that changes the game: rules, entities, weapons.
• mode: only while one of its game modes is the one being played.
• left out: it's only this player's business (HUDs, tools).

A mod that makes the game mode being played is always required. Players who haven't got it can download it from the server when they join (chapter 21).

Requirements

requires is a comma-separated list of mod folder names. Each can carry a version check with >=, >, =, < or <=. Versions compare as numbers per part, so 1.10 is newer than 1.9.

• If a requirement is missing, disabled, broken or too old, your mod doesn't load, and the MODS screen says exactly which one and why.
• Enabling a mod (the MODS switch or mod_enable) also enables everything it requires, all the way down.
• Disabling a mod stops the mods that need it. When it comes back, they start again on their own.
• A cycle (a requires b, b requires a) is reported as an error on both.

Load order

Mods load requirements first, then by priority, then by folder name. The same order decides who gets events first, and whose answer wins when several mods answer the same veto or question. mod_order in the console prints it.

API versions

The engine's mod API version is 1. Put api_version = 1 in every mod.

Hot reload

The game checks each loaded mod's folder about once a second (turn it off with mod_hotreload 0). Any changed file reloads the mod: its unload handlers run, textures and sounds are freed, and the whole mod starts fresh. *.save files don't count, so a mod saving its own data doesn't reload itself. With the editor attached, a save reloads the mod straight away.

Lua reference

Every Lua mod runs in its own Lua 5.4 state. You get the base, string, table, math, utf8 and coroutine libraries plus a safe part of os (os.time, os.clock, os.date). There's no io, debug or package, load only takes text, and print goes to the console. Everything else is under the global orphan table.

Events

Register handlers with orphan.on(event, fn). You can have several handlers per event. orphan.on returns the function so you can remove it later with orphan.off(event, fn).

The game sends many more: wounds, broken bones, explosions, doors, entities, and the vetoes that can stop a shot or a respawn. Chapter 7 lists them all.

Core functions

Tasks and waiting

Every handler runs as a coroutine, so you can wait without freezing the game. orphan.wait pauses just your code; the game keeps running.

orphan.on("round_start", function()
  orphan.wait(2)                       -- 2 seconds later, same handler
  orphan.game.banner("GOOD LUCK")
end)

local id = orphan.every(5, function()   -- every 5 s; return false to stop
  orphan.log("still here")
end)
orphan.after(30, function() orphan.cancel(id) end)

Drawing

Drawing functions only work inside a draw handler. Coordinates are screen pixels (in the editor preview, a 640×360 canvas).

Colours can be a name ("red", "lime", "white", "orange", "gray"...), a hex string ("#ff8800" or "#ff880080"), a number 0xRRGGBBAA, or a table { r, g, b, a } with values 0–255.

Textures, sounds and music

Load files from your own mod folder. Loading the same path twice returns the same id, and everything is freed when your mod unloads.

local badge = orphan.gfx.load("assets/badge.png")       -- id, width, height
local ping, err = orphan.sound.load("assets/ping.wav")
if not ping then orphan.warn(err) end

orphan.on("round_start", function() orphan.sound.play(ping, 0.6) end)
orphan.on("draw", function()
  orphan.draw.imageEx(badge, 60, 60, 1.0, orphan.time() * 45)
end)

Input

Input functions return false while the console is open, so your mod never reacts to typing.

Files and saved data

All paths are inside your mod folder. .., drive letters and absolute paths are refused.

Custom events between mods

orphan.emit is how mods talk to each other. A mod that requires another can listen for its events:

-- in weather_mod
orphan.emit("weather", "rain", 0.8)

-- in any other mod (Lua)
orphan.on("weather", function(kind, strength) ... end)
; in an OrphanASM mod: a label named on_weather gets the numbers in r1../f0..

orphan.ask(event, ...) is the same with an answer: every mod's handlers run in load order until one returns something, and that's what ask returns (nil when nobody answered). The game asks this way for its vetoes.

Calling OrphanASM from Lua

local prog = orphan.asm.load("fast.oasm")
local r0, f0 = prog:call("sum_to", 1000)   -- ints go to r1.., floats to f0..

A program also has :reg(i[, v]), :freg(i[, v]), :peek(addr[, "i32"|"u8"|"f32"]), :poke(addr, v[, type]), :string(addr), :label(name), :status() and :reset().

Memory

orphan.mem.stats() returns the process's workingSet, peak, private, cpu, threads, and lua (bytes used by your mod). orphan.mem.lua() returns just the last one.

Game modes and the match: orphan.game

orphan.game is everything a mod can see and do in a match, and how a mod adds whole game modes. A mode you register shows up in PLAY > GAME MODE and in mp_gamemode <id> next to the built-in ones, and it plays online: players who join without your mod are offered it.

Reading the match

actor(id) returns { id, name, team, alive, bot, health, x, y, z, yaw, weapon, kills, deaths, arrested, hostage, extracted, surrendered, down }.

Teams: 0 and 1 are the two sides, 2 is civilians, 3 is the police (a third side, against both, that a mode can bring in). Weapons are named the way people say them: "glock17", "m9", "m1911", "ak47", "m4a1", "mp5", "m870", "frag", "flashbang". Items include "fentanyl", "bandage" and "tourniquet".

Changing the match (host only)

State everyone sees

What the host sets here goes out to every player with the game's snapshots, so a hud hook on any machine can read it. All of it is cleared when a match starts.

Bodies, movement and looks (host only)

These change one person or bot. Movement is predicted on the player's own machine, so it feels instant online.

Reading works anywhere: eye(id) gives where their eyes are and the way they look, cansee(a, b), trace(x1,y1,z1, x2,y2,z2[, ignore]) against the map and people, and near(x, y, z, r[, team]) lists the living near a spot.

Driving bots (host only)

botcontrol(id, true) switches a bot's own judgement off and hands it to you, until you switch it back.

Hooks that change what happens

Any mod can answer these events. The first mod that returns something decides.

Your own sounds

Put .ogg, .wav, .mp3, .flac or .qoa files in your mod folder. local groan = orphan.game.snd("sounds/groan") gives you a name every machine can play. Files named groan_1, groan_2 and so on are picked from at random. Play it at someone with soundon(id, name[, volume]), at a spot with sound(name, x, y, z), or use it in voice. Players who join get the files with your mod.

Talking between machines: orphan.net

Messages carry up to eight numbers, strings or booleans. Handle them with orphan.on("net:" .. name, fn(sender, ...)). Clients are limited to a steady rate of messages.

See mods/zombies (five kinds of zombie, all from Lua: crawlers, quadruped leapers, brutes, their own sounds), mods/surf (Source-style surfing with checkpoints, a timer and bots that surf) and mods/gang_wars (crews dressed by the mod) for complete examples.

Making a game mode

orphan.game.mode{...} registers a mode. Registering the same id again replaces it, which is how hot reload works: save the file and the mode updates.

orphan.game.mode{
  id = "gangwars", name = "Gang Wars", desc = "One line for the menu",
  teams = { "GROVE", "BLOODS" },
  colors = { {38,128,52}, {168,28,34} },     -- shirts and HUD (false: the usual)
  botNames = { { "Dre", "Tiny" }, { "Shadow", "Duke" } },
  streetClothes = true,
  hunters = true,
  damage = 1.8,
  roundTime = 240,
  roundStart = function() end,               -- host: before anyone spawns
  spawn = function(id) end,                  -- host: hand out their kit
  tick = function(dt) end,                   -- host: every tick of a live round
  checkEnd = function() return nil end,      -- host: a team, "draw", or nil (+ why)
  death = function(victim, killer) end,      -- host
  banner = function(team) return "..." end,  -- the line under GO GO GO
  hud = function(w, h) end,                  -- every machine: draw with orphan.draw
}

A complete mode: King of the Hill

Hold the marked spot for 60 seconds in total. It reads its hill from the map (a marker you place in Spade), keeps the score in shared slots, and shows it to everyone.

local G = orphan.game
local HILL, NEED = { x = 0, y = 0, z = 0 }, 60

G.mode{
  id = "hill", name = "King of the Hill",
  desc = "Hold the marked spot for 60 seconds in total.",
  teams = { "SWAT", "CREW" }, roundTime = 300,

  roundStart = function()
    local spots = G.spawns("hill")          -- a custom marker placed in Spade
    if spots[1] then HILL = spots[1] end
    G.set(1, 0); G.set(2, 0)
    G.marker(1, HILL.x, HILL.y + 2, HILL.z, "HILL")
  end,

  tick = function(dt)
    local on = { [0] = 0, [1] = 0 }
    for _, id in ipairs(G.players()) do
      local a = G.actor(id)
      if a and a.alive and a.team <= 1 and (a.x - HILL.x)^2 + (a.z - HILL.z)^2 < 9 then on[a.team] = on[a.team] + 1 end
    end
    if on[0] > 0 and on[1] == 0 then G.set(1, G.get(1) + dt) end
    if on[1] > 0 and on[0] == 0 then G.set(2, G.get(2) + dt) end
    G.objective(string.format("HILL   SWAT %d s   CREW %d s   (first to %d)", G.get(1), G.get(2), NEED))
  end,

  checkEnd = function()                             -- with checkEnd, wipes and the clock are ours to handle
    if G.get(1) >= NEED then return 0, "SWAT held the hill" end
    if G.get(2) >= NEED then return 1, "The crew held the hill" end
    if G.alive(0) == 0 then return 1, "SWAT are down" end
    if G.alive(1) == 0 then return 0, "The crew are down" end
    if G.roundtime() <= 0 then return "draw", "Nobody held it long enough" end
  end,
}

name        = King of the Hill
version     = 1.0
entry       = main.lua
enabled     = 1
api_version = 1
network     = mode              # players need it while this mode is played

Maps for your mode

Your mode can be played on any map, and spawns(class) reads any marker the map has. To give a map spots of its own for your mode, open it in Spade, drop a Custom marker (Toolbox > Gameplay) where you want it, and set its Class in Properties to a name of your choosing, like hill. Every marker of that class comes back from orphan.game.spawns("hill") as {x, y, z, yaw}. The map's own markers work too: spawn_swat, spawn_suspect, info_breaker and the rest (Spade's guide lists them all).

To tie a mode to one map, set map = "my_map" in it. Other modes then won't be offered that map.

Events and vetoes

The game tells mods what happens in a match, and asks them before some things happen. Listen with orphan.on as usual. Most come only on the host, the machine running the match (chapter 14), because that's where it happens.

Vetoes and changes

For these the game asks: the first handler (in load order) that returns something decides. Return nothing to let it be.

-- friendly fire off, headshots double, and no shooting in the first 10 seconds
local G = orphan.game
local started = 0
orphan.on("round_start", function() started = G.time() end)
orphan.on("damage", function(victim, attacker, amount, weapon, headshot)
  local v, a = G.actor(victim), G.actor(attacker)
  if v and a and victim ~= attacker and v.team == a.team then return false end
  if headshot then return amount * 2 end
end)
orphan.on("fire_bullet", function(shooter)
  if G.time() - started < 10 then G.notice("Not yet!", shooter) return false end
end)

What happened

Scripted entities and physics

orphan.ents is the game's version of scripted entities: things in the world with a look, real physics (the same engine as the ragdolls and props) and Lua hooks. The host spawns and runs them; every machine sees them move, interpolated from the snapshots. A class is a table; an entity is a table too, with its class behind it, so methods and fields work as you'd expect.

local ents = orphan.ents
ents.define("bounce_pad", {
  printName = "Bounce pad", category = "Fun", spawnable = true,   -- spawnable: in the Sandbox's spawn menu
  shape = "box", size = { 0.6, 0.05, 0.6 }, mass = 30, color = { 40, 200, 120 },
  init = function(self) self:freeze(true) self.power = 9 end,
  touch = function(self, other, kind)
    if kind == "actor" then orphan.game.push(other, 0, self.power, 0) end
  end,
  use = function(self, actor) self.power = self.power == 9 and 16 or 9 self:nw("power", self.power) end,
  damage = function(self, amount, attacker) if amount < 20 then return false end end,   -- shrugs off small hits
})

orphan.command("pad", "A bounce pad in front of you", function()
  local me = orphan.game.me()
  local x, y, z, dx, dy, dz = orphan.game.eye(me)
  local hit = orphan.phys.trace(x, y, z, x + dx * 5, y + dy * 5, z + dz * 5, me)
  if hit.hit then ents.spawn("bounce_pad", hit.x, hit.y + 0.05, hit.z) end
end)

Classes

ents.define(name, class) takes the look (shape box, sphere, capsule, cylinder or model with a file from your folder, size, color, light), the physics (mass, health) and the hooks. base names another class, from any mod, to build on: what you don't say comes from it.

Any other function in the class is a method you can call on the entity (self:light_fuse()), and ent:call("hook") runs one by name, which is how another mod can trigger yours.

Entities

ents.spawn(class, x, y, z [, opts]) returns the entity (opts: angles, yaw, rot, size, color, frozen, owner, and any field you like, copied onto it). Find them again with ents.get(id), all(), find(class [, derived]) or near(x, y, z, radius).

Physics: orphan.phys

These take a ref: anything physical. An entity, a prop's or ragdoll part's ref from a trace (hit.ref), or "world" for the map.

-- a box on a 2 m rope from the ceiling above you, swinging
local x, y, z = orphan.game.eye(orphan.game.me())
local up = orphan.phys.trace(x, y, z, x, y + 10, z)
local box = orphan.ents.spawn("bounce_pad", x + 1, y, z)
if up.hit then
  orphan.phys.constrain("rope", box, 0, 0.05, 0, "world", up.x, up.y, up.z, { length = 2 })
end

Up to 256 entities and 128 ropes and cables are in the world at once.

Scripted weapons

Two kinds. A scripted tool is held in the hands like the multitool and does whatever your Lua says; its hooks run on the host as the buttons go down and up, and it draws itself (boxes, or a draw hook) on every machine. A scripted gun is a real gun of the game's (rounds, ballistics, recoil, wall penetration) with your numbers.

orphan.weapons.define("pad_launcher", {
  printName = "Pad launcher", category = "Fun", spawnable = true,
  hint = "LMB: throw a bounce pad   R: take them all back",
  delay = 0.5,                                       -- seconds between primaries
  model = { { c = { 0, 0, 0.1 }, s = { 0.05, 0.05, 0.25 }, color = "lime" } },   -- boxes in the hand
  nw = { "count" },                                  -- numbers every machine sees
  primary = function(self)
    local id = self:owner()
    local x, y, z, dx, dy, dz = orphan.game.eye(id)
    local pad = orphan.ents.spawn("bounce_pad", x + dx, y + dy, z + dz, { owner = id })
    if pad then pad:freeze(false) pad:push(dx * 60, dy * 60 + 20, dz * 60) end
    self.n = (self.n or 0) + 1
    self:nw("count", self.n)
  end,
  reload = function(self)
    for _, e in ipairs(orphan.ents.find("bounce_pad")) do if e:owner() == self:owner() then e:remove() end end
    self.n = 0 self:nw("count", 0)
  end,
})

orphan.on("spawn", function(id) orphan.weapons.give(id, "pad_launcher") end)

Hooks: primary, secondary, reload (pressed), primaryRelease, secondaryRelease, think(self, dt), deploy, holster, and draw / hud(w, h) on the machine holding it. automatic = true repeats primary every delay while the button is held. self:owner() is who holds it and self:nw(key [, value]) shares a number.

weapons.give(actor, name [, select]), strip, has, select, active, carried and list manage them. give_sweps in the console (cheats on) gives you every one.

Guns of your own

-- a heavy-barrel M4: slower, harder hitting, a 20-round magazine
local id = orphan.weapons.gun("m4_heavy", {
  base = "m4a1", printName = "M4 Heavy", damage = 48, rpm = 600, magSize = 20,
  modes = { "semi", "auto" }, recoilUp = 1.4, color = { 60, 60, 66 },
})
orphan.on("spawn", function(actor) orphan.game.give(actor, "m4_heavy", 4) end)

Drawing in the world

2D drawing (orphan.draw) works in the draw event. 3D drawing works in the draw3d event, in the world with depth and lighting, on every machine: use it for markers, beams, holograms, screens on walls.

local d3 = orphan.draw3d
orphan.on("draw3d", function()
  for _, e in ipairs(orphan.ents.find("bounce_pad")) do
    local x, y, z = e:pos()
    d3.beam(x, y, z, x, y + 2, z, 0.05, { 40, 255, 140, 120 })
    d3.text("x" .. (e:nw("power") or 9), x, y + 2.2, z, 0.25, "lime")
  end
  -- a screen on a wall: draw on it in pixels with orphan.draw, 1 px = 1 cm
  d3.panel(4, 2, -3, { 0, 90, 0 }, 0.01, function()
    orphan.draw.rect(0, 0, 200, 80, { 0, 0, 0, 200 })
    orphan.draw.text("PADS: " .. #orphan.ents.find("bounce_pad"), 10, 25, 30, "lime")
  end)
end)

Effects: orphan.fx

particle(kind, x,y,z, vx,vy,vz [, life, size, color]) with kinds dust, blood, spark, smoke, debris, fire, water, flash and cloud; sparks, puff, blood, decal (a mark on a surface), light (a light that fades), shake. These happen on the machine that calls them. fx.all(name, ...) on the host plays one on every machine, and fx.explosion(x, y, z [, power [, owner]]) is a real one: it hurts, throws things and breaks walls.

Windows and widgets

orphan.ui is a widget toolkit: windows you can drag and resize, tabs, buttons, sliders, text boxes, lists, grids. It draws in the game's skin (or your own: ui.skin). A popup window takes the mouse and keyboard from the game while it's open, and Esc closes it.

local ui = orphan.ui
local win
orphan.command("pads", "The bounce pad settings", function()
  if win then win:remove() win = nil return end
  win = ui.window("Bounce pads", 320, 220, { popup = true })
  local power = ui.create("slider", win); power:dock("top", 4)
  power:setText("Power"); power:setRange(2, 30, 0); power:setValue(9)
  local glow = ui.create("check", win); glow:dock("top", 4); glow:setText("Glow")
  local go = ui.create("button", win); go:dock("bottom", 4); go:setText("Apply to all")
  function go:onClick()
    orphan.net.tohost("pads", power.value, glow.checked)
    ui.notify("Done", 2, "lime")
  end
end)

Widgets: panel, label, button, check, slider, entry, list, tabs, scroll, grid, combo, color, image, progress. Lay them out with dock("top"|"bottom"|"left"|"right"|"fill", margin) or setPos / setSize; react with onClick and onChange(self, value), or read slider.value, check.checked, entry:getText(). tabs:addTab(name) returns the page to fill, list:addRow, combo:addOption.

Taking the mouse and keyboard

The body, drugs and forensics

Every person in SPASTAZ runs a medical simulation: blood, oxygen, pulse, organs, bones, pain, shock, drugs. orphan.body reads it on any machine and changes it on the host.

-- a drug of your own: it slows you down, and bullets do a fifth of the damage while it lasts
orphan.body.defineDrug("ironskin", {
  halfLife = 30, onset = 2,
  dose = function(id, n) orphan.game.notice("You feel heavy.", id) end,
  tick = function(id, level, dt) orphan.game.movement(id, { speed = 1 - math.min(level, 1) * 0.4 }) end,
  wornOff = function(id) orphan.game.movement(id, { speed = 1 }) end,
})
orphan.on("damage", function(victim, attacker, amount)
  if orphan.body.level(victim, "ironskin") > 0.5 then return amount * 0.2 end
end)
orphan.command("ironskin", "Take a dose", function() orphan.body.dose(orphan.game.me(), "ironskin") end)

Doors, power and weather

-- lights out and a storm when the last suspect is left
orphan.on("death", function()
  if orphan.game.alive(1) == 1 then
    orphan.world.blackout()
    orphan.world.weather("storm")
    for _, d in ipairs(orphan.world.doors()) do if not d.gone then orphan.world.door(d.id, "lock") end end
  end
end)

Maps can call your mod too: a trigger part in Spade with an Event sends trigger_enter / trigger_leave with that event name, and orphan.game.armtrigger(event, on) switches them.

Realms and networking

In a match one machine is the host (offline, that's you; online, the player hosting or the dedicated server) and the rest are clients. Every machine runs your mod. The host runs the match: the functions marked "Host" only do something there, and the events about the match only come there. Clients draw, play sounds, show menus and send the host what their player wants.

Files by realm

Name files sv_*.lua (host), cl_*.lua (clients) or sh_*.lua (both) and load them with orphan.include: cl_ files aren't loaded on a dedicated server, and with private = sv_ in mod.cfg the server never sends its sv_ files to players, so your server code stays yours. include returns nil where a file isn't loaded.

Messages

-- client: ask the host for something
orphan.net.tohost("pads", 12, true)

-- host: check what came in (n number, s string, b boolean, ? anything; upper case may be nil)
orphan.net.receive("pads", "nb", function(sender, power, glow)
  power = math.max(2, math.min(30, power))
  for _, e in ipairs(orphan.ents.find("bounce_pad")) do
    if e:owner() == sender then e.power = power e:glow(glow) end
  end
  orphan.net.send(sender, "pads_done", power)
end)

-- client: the answer
orphan.on("net:pads_done", function(sender, power) orphan.ui.notify("Pads at " .. power) end)

net.send(id, name, ...) and net.broadcast(name, ...) go from the host; net.tohost from anywhere (on the host itself it arrives straight away, from your own player). Up to 8 arguments: numbers, booleans and strings up to 1024 characters. A client may send 120 messages a second; past that the host drops them. Everything a client sends is a request: check it on the host, as above.

Cameras and films

orphan.camera takes this machine's view: for cutscenes, kill cams, security monitors, or films. It stays yours until you release it, and three Esc presses always give it back.

local cam = orphan.camera
-- a slow circle round the bomb, no HUD, for 6 seconds
orphan.on("explosion", function(x, y, z)
  cam.hud(false)
  cam.orbit(x, y, z, 6, 2.5, 30)
  orphan.after(6, function() cam.release() cam.hud(true) end)
end)

set(x,y,z, tx,ty,tz [, fov [, roll]]) puts the view anywhere, follow(actor or ent [, back [, up]]) rides behind something, orbit circles, view() says where it is now, release() gives the view back, and hud(on) hides everything for a clean shot. For moving shots, path({...}) makes a smooth path from keyframes, play(path [, {loop=, onEnd=}]) flies the view along it, record() / stopRecording() turn what you see into a path, and save / load keep paths in your folder. The shipped Director mod (F7) is built on these: record what you see and play it back, dolly shots from keyframes, a letterbox. Read mods/director to see how.

The Sandbox mode

Sandbox is a game mode that ships as a mod (src/mods/sandbox), written with nothing but the API in this guide. Pick it in PLAY > GAME MODE, or mp_gamemode sandbox. Any map works, and it never ends.

Making addons for it

Anything you mark spawnable = true, in any mod, shows up in the Sandbox spawn menu under its category: entity classes on the Entities tab, scripted weapons and guns on the Weapons tab. So a Sandbox addon is just a mod with entities or weapons in it. The bounce pad and pad launcher from chapters 8 and 9 are one already. Put requires = sandbox in it only if you use something of the Sandbox's own, like its sbox_base class (which makes things ownable, undoable and copyable by the duplicator):

orphan.ents.define("hover_pad", {
  base = "sbox_base", printName = "Hover pad", category = "Hover Pads", spawnable = true,
  shape = "box", size = { 0.5, 0.04, 0.5 }, mass = 15, color = { 90, 90, 255 },
  think = function(self, dt)
    local x, y, z = self:pos()
    for _, e in ipairs(orphan.ents.near(x, y + 1, z, 1)) do
      if e ~= self then e:force(0, e:mass() * 12, 0) end    -- holds them up
    end
  end,
})

Share it on the workshop's Sandbox addons board: players install it from MODS > WORKSHOP, and servers send it to anyone joining.

Maps with their own Lua

A map can carry its own scripts inside its file: a button that floods the basement, a boss in the attic, a puzzle door. They travel with the map, so everyone who plays it has them. When the map loads they run as a mod named @map, on the host and on every client, starting at main.lua. They're always sandboxed: no console commands, no settings but their own, nothing outside their folder.

1. Write them like any mod, in a folder (say mods/my_map_scripts/) with a main.lua. Use orphan.game.map(), the map's markers (orphan.game.spawns("my_marker")) and its trigger events.
2. In the console: maplua_pack my_map mods/my_map_scripts. That puts them into assets/maps/my_map.mbsptz. Add a name at the end (maplua_pack my_map mods/my_map_scripts my_map_v2) to write a copy instead.
3. Load the map. The console says its scripts are running, or why not.

-- main.lua in a map: the vault door opens when someone reaches the switch, and the alarm goes
local G = orphan.game
orphan.on("trigger_enter", function(id, event)
  if event ~= "vault_switch" or not orphan.server() then return end
  for _, d in ipairs(orphan.world.doors()) do
    local x, y, z = d.x, d.y, d.z
    if x > 10 and z < -4 then orphan.world.door(d.id, "open") end   -- the vault's doors
  end
  G.banner("ALARM", "The vault is open")
end)

maplua_unpack my_map some/folder gets them out again to work on, and maplua_strip my_map takes them out of the map. Spade keeps them when it saves the map. Only .lua, mod.cfg, text, json, png, jpg, wav, ogg and mp3 files go in (4 MB at most), and of a mod.cfg only name and requires count. Players who'd rather not run map scripts set mod_maplua 0.

OrphanASM

OrphanASM is a small, safe assembly language that runs in a virtual machine inside the engine. Every memory access is bounds-checked, so a bad pointer stops your program with a clear message ("trap") instead of crashing the game.

The machine

• Registers: r0–r15 (32-bit integers; r14 is also fp, r15 is sp) and f0–f7 (32-bit floats).
• Flags: Z (zero/equal), N (negative/less), C (unsigned less), set by cmp, test and fcmp.
• Memory: 64 KB by default, up to 4 MB with .memory. Addresses below 16 trap (a null-pointer guard), your .data starts at 16, and the stack grows down from the top.
• Calls: call/ret, up to 256 deep.
• Budget: 2,000,000 instructions per call by default (mod_asm_budget). Use yield to spread long work over several frames.

Entry points

Each entry point ends with ret. halt stops the program for good.

A complete mod

.data
hello:  .string "hello from mover\n"
x:      .float 40
speed:  .float 120

.text
init:
    mov r1, hello
    sys print_str
    ret

update:                     ; f0 = dt
    fld f1, [x]
    fld f2, [speed]
    fmul f2, f0             ; speed * dt
    fadd f1, f2
    sys screen_w
    itof f3, r0
    fsub f3, 60.0
    fcmp f1, f3
    jl .store
    fmov f1, 40.0           ; wrap around
.store:
    fst [x], f1
    ret

draw:
    fld f0, [x]
    fmov f1, 60.0
    fmov f2, 20.0
    fmov f3, 20.0
    mov r1, 0x46A0FFFF      ; colour 0xRRGGBBAA
    sys draw_rect
    ret

Labels that start with a dot, like .store, are local to the label above them, so every function can have its own .loop.

Directives

Instructions

Operands are registers, constants, labels (their address), or memory as [label], [reg] or [reg + offset]. Arithmetic has two forms: add r1, r2 means r1 += r2, and add r1, r2, r3 means r1 = r2 + r3.

Syscalls

sys name calls the engine. Arguments go in r1–r6 and f0–f3, results come back in r0 / f0. Strings are addresses of zero-terminated text. asm_syscalls in the console lists them all with their registers.

From the console: asm_check file assembles and lists errors, asm_run file [label] runs main: once, and asm_disasm file shows what the assembler made. Paths are relative to mods/.

The MODS screen and mod settings

Main menu → MODS, or menu_mods in the console. The left list shows every installed mod with a status light: green running, orange waiting for a requirement or has a warning, red error, grey off. The switch turns a mod on or off and saves that in its mod.cfg.

The detail page for the selected mod shows:

• its description, version, author, kind and API level,
• its state, with the full error or warning if there is one,
• REQUIRES and NEEDED BY: which mods it depends on and which depend on it,
• SETTINGS: every setting the mod made, as a switch, slider or −/+ control,
• STATS: time per frame, Lua memory, tasks, textures, sounds, reload count,
• buttons: ENABLE/DISABLE, RELOAD, OPEN FOLDER, EDIT (opens the mod in Orphan Editor).

At the bottom: RESCAN finds new mod folders, NEW MOD creates a working Lua mod, and OPEN MODS FOLDER opens Explorer.

The workshop tab

The WORKSHOP tab lists uploads from the workshop: mods, weapons and gear, Sandbox addons, maps. You can search them and sort by newest, top rated, most downloaded or recently updated. INSTALL downloads the upload's .zip, checks it and unpacks it into your mods folder. A new install starts switched off and sandboxed until you enable it, and UPDATE appears when the upload has a newer version. To be installable from the game, an upload must link straight to a .zip with mod.cfg at its top or inside one folder.

Settings in detail

local on    = orphan.newcvar("radar_on", true, "Show the radar")            -- switch
local zoom  = orphan.newcvar("radar_zoom", 1.0, "Radar zoom", 0.5, 3.0)  -- slider
local blips = orphan.newcvar("radar_blips", 8, "Max blips")              -- - / + buttons

• The help text becomes the label on the MODS screen. Name settings with your mod's prefix so they don't collide with anyone else's.
• Settings are saved in config.cfg. They keep their value while the mod is off, and come back when it's on again.
• Changes from the MODS screen or the console fire your cvar event. Update your local copy there.
• Up to 32 settings and 32 commands per mod.

Debugging

In the editor preview

Press F5 on a .lua or .oasm file and it runs in the preview panel. For anything about the match (orphan.game, entities, weapons), run it in the game instead: the editor attaches to it (below). Click the preview to send it your keyboard and mouse.

• Breakpoints: click left of the line numbers or press F9. The run pauses there, and the DEBUG tab shows the call stack, locals, upvalues (marked ^), watch expressions and globals.
• Stepping: F10 over, F11 into, Shift+F11 out, F5 continue, F6 pause at the next line that runs.
• ASM: the same keys, plus registers (changes highlighted), flags, disassembly around the current line, the call stack, a memory viewer (type an address, a label or sp) and all data labels.
• Problems as you type: Lua syntax errors, ASM assembly errors, mod.cfg mistakes (unknown keys, missing entry file, requirements that don't exist) all underlined in place.

Inside the running game

The game listens for Orphan Editor on 127.0.0.1:27960. That address only accepts connections from the same PC; live_link 0 turns it off. When the game runs, the editor attaches within a couple of seconds and the status bar shows SPASTAZ ATTACHED.

• Console mirror: the game's console appears in the editor's console as [game] lines.
• Send commands: click to: editor in the console header (or the status bar) to switch input to the game, then type any console command.
• Instant reload: saving a mod file reloads that mod in the game straight away.
• Breakpoints in the game: set one in a mod's file and that mod pauses inside the game when it gets there. The game keeps running and only your mod waits. The editor jumps to the line and shows the stack, locals, upvalues and globals; watches are evaluated in the game. F10/F11 step, F5 continues.
• Pause on demand: F6 with a mod file open pauses that mod at the next line it runs.
• MODS panel: in the editor's right panel it shows each mod's state in the game, and its switches apply there too.

Testing without a screen

The dedicated server can play a match with nobody in it and let your mod decide whether it passed. It's how the game tests its own mod API (tests/luatest/, run them all with tests\run_lua_tests.ps1):

spastaz_dedicated.exe --luatest my_mod warehouse 1500 mp_gamemode sandbox

That loads my_mod (a comma list loads several), starts warehouse, runs at most 1500 ticks (60 a second) with the settings after it, and stops when your mod says how it went:

orphan.task(function()
  orphan.wait(0.5)
  local bot = orphan.game.addbot(0, "Tester")
  orphan.weapons.give(bot, "pad_launcher", true)
  orphan.wait(1)
  local ok = orphan.weapons.active(bot) == "pad_launcher"
  orphan.setcvar("luatest_result", ok and 1 or 2)     -- 1 passed, 2 failed
end)

Bots can be driven from Lua (orphan.game.botcontrol, botpress, botbuttons, botgoto...) to press buttons and walk about for you.

Handy console commands while debugging

Limits, the sandbox and servers

These keep one bad mod from spoiling the game. The numbers with a console variable can be changed by the player.

File access is limited to your own mod folder, for Lua and ASM alike. Cheats (cheat cvars, give_sweps and so on) need the player to type sv_cheats 1 first. A mod can't turn cheats on for them.

Joining a server that runs mods

When you join, your game names its running mods and a fingerprint of each one's files. The server checks you have every mod it needs (its network setting, chapter 4) and that your copy is the same as its own. If you're missing one, or have a different copy, you're shown what's needed and how big it is:

• DOWNLOAD AND JOIN: the server sends the files and they're checked against its fingerprint. The mod goes into mods/, gets switched on, and you join again by yourself. A different copy you already had is kept in mods/.backup/.
• CANCEL: you don't join.

The console commands mod_download and mod_decline do the same. A copy you already have but had switched off is just switched on. Downloads are capped at 64 MB, and files can't land outside the mod's own folder.

Downloaded mods are sandboxed

A mod that came from a server, and a map's own scripts, can't:

• run console commands (orphan.exec, orphan.game.exec, the ASM exec syscall);
• change any setting except the ones it made itself with orphan.newcvar;
• write more than 64 MB.

The console says so once when it tries. The list of sandboxed mods is mods/.sandboxed, which is outside every mod's folder, so a mod can't take itself off it. The MODS screen marks these mods DOWNLOADED FROM A SERVER. mod_trust <mod> lifts the sandbox, and mod_sandbox <mod> puts it back.

Troubleshooting

Crash reports

A Lua error or an ASM trap is not a crash. It stays inside your mod and shows in the console and on the MODS screen. If the engine itself crashes, SPASTAZ writes a report to src/reports/crash_SPASTAZ_<date>_<time>.txt and tells the player where it is. The report contains:

• the exception (for example, a write to a NULL pointer) and where it happened,
• a stack trace with function names,
• which mod's code was running at the time,
• registers, the loaded mods, memory use, and the last 60 console lines.

Exception  0xC0000005 ACCESS_VIOLATION (bad pointer)
At         spastaz.exe+0x6176A  Cmd_CrashTest+0xC1
           tried to WRITE address 0x0  (a NULL pointer, or NULL + small offset)
Mod        engine code called from mod 'hover_pads' was running - check that mod first

If a player's report names your mod, the bug is usually something your mod asked the engine to do. Send the report along with the steps to reproduce. crash_test (with sv_cheats 1) crashes on purpose, to check the reporter works.

Sharing your mod

1. Fill in name, version, author, description and api_version.
2. Set enabled = 0 so players choose to turn it on.
3. List every mod you rely on in requires, with a minimum version if you use something new in it.
4. Delete your own *.save files, and any test files.
5. Zip the folder (not just its contents).

Upload the zip to the workshop on the board that fits (Mods, Weapons & gear, Sandbox addons, Maps). Players install it from MODS > WORKSHOP in the game. By hand, they unzip it into src/mods/, press RESCAN on the MODS screen (or restart), and switch it on.

Servers running it

A server lists its game mode and the mods joining players need, and the server browser (on the site and in the game) shows them and can filter on them: type sandbox and you see the Sandbox servers. Players who haven't got a mod download it from the server as they join.

Versioning

Bump version whenever you change something other mods might depend on: an event you emit, a setting, a weapon name. Mods that need the new behaviour can then say requires = your_mod >= 1.3.

API changes

Console cheat sheet