Write-exports

Stability: Stable.

These are the primitives a hook or registered driver calls to act on a scene. They all take a scene id as the first argument (the id you got from the snapshot or the hook). Calls on an unknown scene id are a safe no-op.

All of these are read-from-snapshot, write-through-exports: you never touch the internal Scene object.

State & rounds

`setState(id, state, seconds)`

Set the scene's phase. seconds arms the phase timer (snap.phaseEnd becomes now + seconds*1000); omit it for an untimed phase (phaseEnd = 0).

Param	Type	Notes
`id`	number	Scene id.
`state`	string	`'waiting'` \| `'live'` \| `'ended'`.
`seconds`	number?	Optional phase duration.

exports.engine:setState(sceneId, 'live', 300)   -- live for 5 minutes
exports.engine:setState(sceneId, 'waiting')      -- untimed

`setRound(id, n)`

Set the round counter (shown on the HUD as R<n>).

exports.engine:setRound(sceneId, 1)

The mode state bag (`mst`)

Each scene has a free-form mst table for your mode's own state. You read it back via snapshot.mst. (Team scores are NOT in mst — the engine owns them privately and surfaces them read-only as snapshot.wins, an array by team index.)

`setVar(id, key, value)`

exports.engine:setVar(sceneId, 'bombPlanted', true)

`getVar(id, key)`

Returns the stored value, or nil.

local planted = exports.engine:getVar(sceneId, 'bombPlanted')

Spawning

`spawnAll(id, opts)`

(Re)spawn every player in the scene. The loadout, armour, and placement come from the descriptor + the battleground (by team index), so the client stays mode-agnostic. The entrance is the battleground's choice, not yours: a per-mode block with ground spawns places each player standing on the point for their seat; one with only areas parachutes them in from altitude. Either way the spawn is vulnerable from frame one — no freeze, no hold phase.

`opts` key	Type	Default	Meaning
`alive`	boolean	`true`	Mark players alive (counts toward `alive[team]`).

exports.engine:spawnAll(sceneId, { alive = true })   -- start of round
exports.engine:spawnAll(sceneId, { alive = false })  -- back to waiting

`spawnOne(id, src, opts)`

(Re)spawn a single player. Same opts as spawnAll. No-op if that player isn't in the scene.

exports.engine:spawnOne(sceneId, victimSrc, { alive = true })

Messaging the roster

`announce(id, clientEvent, ...)`

TriggerClientEvent to every player in the scene. Use it to fire the engine's client events (or your own mode's client events).

exports.engine:announce(sceneId, 'engine:live')
exports.engine:announce(sceneId, 'engine:roundEnd', 'Police')

`notify(id, msg)`

Send a UI notification to the whole roster. Supports GTA colour codes.

exports.engine:notify(sceneId, '~g~Objective captured!')

`bigMessage(id, text, ms)`

Show a large centre-screen banner to the roster for ms milliseconds.

exports.engine:bigMessage(sceneId, 'SUDDEN DEATH', 4000)

Hazards

Environmental damage and death — the primitive a system (a shrinking zone, a kill volume) uses to harm a combatant. Both target one live combatant of the scene; a spectator, an already-dead player, or someone in another scene is a safe no-op.

`hurt(id, src, amount)`

Deal amount HP of environmental damage (GTA ped scale 0–200) to src.

exports.engine:hurt(sceneId, src, 2)   -- e.g. storm tick on a player outside the ring

`kill(id, src)`

Instantly eliminate src.

exports.engine:kill(sceneId, src)

Player peds are client-authoritative, so these route through the client and apply to the player's own ped; the resulting death flows through the engine's normal death funnel — elimination, killfeed, spectate and stats fire unchanged, so a system never special-cases dying.

Quick reference

Export	Signature	Acts on
`setState`	`(id, state, seconds?)`	phase + phase timer
`setRound`	`(id, n)`	round counter
`setVar`	`(id, key, value)`	`mst[key]`
`getVar`	`(id, key)` → value	reads `mst[key]`
`spawnAll`	`(id, { alive? })`	every player
`spawnOne`	`(id, src, { alive? })`	one player
`announce`	`(id, clientEvent, ...)`	TriggerClientEvent to roster
`notify`	`(id, msg)`	UI notify to roster
`bigMessage`	`(id, text, ms)`	banner to roster
`hurt`	`(id, src, amount)`	environmental damage to one combatant
`kill`	`(id, src)`	eliminate one combatant