Write a weapon.
Write a world rule.

What a plugin is

A plugin is a Lua source file. When the game loads it, the file runs once and registers things — a blueprint, a weapon, or a fire behaviour on the global engine table; a per-tick system or an event hook on your own plugin table. After that, the engine calls back into your registrations as the match plays.

Here is a complete, if pointless, plugin. It spawns a spark wherever anyone fires:

a whole pluginengine.on("fire", function(shooter, weapon)
  local x = engine.get(shooter, "pos", "x")
  local y = engine.get(shooter, "pos", "y")
  engine.spawn("spark-fire", x, y)
end)

There is no import, no main(), no boilerplate. The file is the plugin. Everything it can do, it does through engine — which is the only thing in scope besides Lua's own string, table, and math libraries.

The three rules that make it work

Everything else follows from these. Internalize them and the API stops surprising you.

These aren't style guidance — they're enforced by the boundary. A leaked reference simply can't form, and a hot Lua loop is something the API steers you away from writing.

Registering things

A few calls hook your code into the game: a fire behaviour by name on engine, and your per-tick work + event hooks on your own plugin table. The engine calls each back at the right moment.

Reaching into the world

These act on the current world — the one whose tick is running. Ids are handles; every value in and out is a scalar.

Declared systems

A system is how a plugin does work every tick, for every matching entity — without ever writing the loop.

You hand plugin.system a component filter and a function. The engine batches the query in JS and calls your function once per entity, as (id, dt). The hot iteration is the engine's; your Lua is a few glue calls. This is the whole reason a per-tick feature like the jetpack costs almost nothing. (For work that isn't per-entity — a world clock, a spawner — use plugin.tick(fn), called once a tick as fn(dt).)

a hazard that ticks damage to anyone standing in lavaplugin.system({ "pos", "health", "body" }, function(id, dt)
  local y = engine.get(id, "pos", "y")
  if y > 2000 then                              -- below the lava line
    engine.emit({ t = "damage", target = id, amount = 18 * dt, owner = 0 })
  end
end)

Lifecycle events

The engine announces the moments that matter. Hook them with plugin.on to react — grant a buff on spawn, count a kill, spread fire on death.

Every argument is a handle or a scalar, so a hook's arguments can be used with the world API directly. The engine emits these whether or not anyone listens, so hooking one is free until you do — and a hook only fires while your plugin is enabled in the world, so a hook-driven plugin switches off cleanly with its toggle.

Contributing content

Plugins own their data too. Declaring a blueprint or a weapon is the one place a whole structure crosses the boundary — and it's fine, because it's static config copied once at load, never live state.

the ember a fire-weapon lobsengine.defineBlueprint("fine-ember", {
  components = {
    pos = { x = 0, y = 0 }, vel = { x = 0, y = 0 },
    gravity = { g = 1400, grounded = false },
    lifetime = { ttl = 5 },
    ember = { owner = 0, team = "", fire = "fire-zone" },
  },
})

Services & dependencies

Plugins build on plugins. An infrastructure plugin exposes an API; a content plugin depends on it and calls in. The dependency always points down — core never names a plugin, and a plugin never names its dependents.

engine.provide(name, table) publishes a table of functions. engine.require(name) fetches it. Both stay inside the VM, so a call like items.register("fine", …) is just a Lua call — no boundary crossing, no cost.

a content plugin standing on the items infrastructurelocal items = engine.require("items")
items.register("fine", { give = "weapon", weapon = "fine", ammo = 3 })

You declare which plugins yours needs; the host loads them in dependency order, so a provider always runs before anyone who requires it. A missing dependency or a cycle fails loudly at load, not mysteriously at runtime.

Guardrails

Three things the host guarantees, so a plugin can't quietly break a match.

A whole plugin, end to end

This is This Is Fine — a complete weapon, shipping in the game, in one file. It declares the ember it lobs, the weapon that lobs it, the fire behaviour, and its pickup item. It depends only on items. Core names none of it.

content/plugins/this-is-fine.lua — abridged-- the ember it lobs (a gravity-bound orb that lights a fire where it lands)
engine.defineBlueprint("fine-ember", {
  components = {
    pos = { x = 0, y = 0 }, vel = { x = 0, y = 0 },
    gravity = { g = 1400 }, lifetime = { ttl = 5 },
    ember = { owner = 0, team = "", fire = "fire-zone" },
  },
})

-- the weapon: lob a fine-ember on a long cooldown
engine.defineWeapon("fine", {
  label = "This Is Fine", behavior = "drop", cooldown = 4.5,
  projectile = "fine-ember", ammo = { max = 6, start = 0 },
})

-- the fire behaviour: spawn the ember at the aim, stamped with the shooter's team + id
engine.behavior("drop", function(fire)
  local id = engine.spawn(fire.projectile, fire.aim_x, fire.aim_y)
  engine.set(id, "ember", {
    team  = engine.get(fire.shooter, "body", "team"),
    owner = fire.shooter,
  })
end)

-- its pickup item, registered into the items infrastructure
local items = engine.require("items")
items.register("fine", { give = "weapon", weapon = "fine", ammo = 3 })

Every mechanism in this guide appears here: a blueprint, a weapon, a fire behaviour that spawns-and-stamps by handle, and a dependency on an infrastructure plugin. Nothing else in the codebase knows this weapon exists.

Is it a primitive, infrastructure, or content?

When you're not sure where something belongs, the deciding question isn't importance — it's frequency and shared-ness.

• Content-agnostic and needed by everything? → a primitive in the JS engine. The ECS, spawn, query, events, terrain, rng. You use these; you don't write them.
• A game system others build on, that a world might toggle? → an infrastructure plugin (Lua). Items, lighting, day/night, hunger. It exposes an API via provide.
• An individual piece of content? → a content plugin (Lua). A weapon, an enemy, a hazard. It depends on infrastructure and names itself to no one.

The litmus for the hard cases: would a sandbox reasonably run without it? A world with no fire weapons is sensible — so fire is a plugin. A world with no ability to spawn entities at all is not — so spawn is a primitive.