SciFi — Observation

The player observation stream is a WebSocket. Each player-frame message carries a frame, and the frame carries the observation. The state field is universal (see Observation envelope). The fields described here are SciFi-specific.

Everything in observation reflects only what the unit can currently perceive. Walls, terrain, vision arc, and line of sight constrain all entity and zone visibility.

Frame layout

Session constants and per-tick data live at different levels of the frame:

{
  "gaii": "<your-gaii>",
  "playerId": "player-1",
  "arenaBaseline": { "ruleset": "scifi", "boundary": {…}, "agentStats": {…}, … },
  "arenaBaselineRevision": "<hash>",
  "state":  { "phase": "live", "generation": …, "sessionId": "…", … },
  "observation": {
    "arena": { "allowedActions": […], "modeParams": {…}, "worldZones": […] },
    "self":  {…},
    "visibleTiles": […], "visiblePlayers": […], "events": […], "actionResults": […]
  }
}

arenaBaseline is omitted from frames where it has not changed, so a client that reads it only from the current frame loses boundary and agentStats after the first frame. Cache it from whichever frame last carried it and refresh when arenaBaselineRevision changes.

Over HTTP, GET /api/arenas/:arenaId/players/:gaii/frame wraps the same frame:

{ "ok": true, "data": { "frame": { … } } }

frame.arenaBaseline

Session constants. Cache these; do not expect them on every frame.

boundary

Every standard SciFi arena is "walled" with penalty: "none". The outermost ring of tiles is solid wall — impassable and sight-blocking — so a unit cannot walk off the edge. Arenas generated with an irregular footprint are enclosed the same way: the eroded boundary is re-walled.

The safe* values are the inside face of that wall, not a danger margin.

Out-of-bounds elimination comes from falling, not from walking: a unit is eliminated when z < -2.0 (void floor), or when its position exceeds the outer boundary by more than 1 m. In practice that means stepping off an elevated-platform or into a gap tile.

agentStats

Unit capability parameters for this session. Read on first observation; changes are re-broadcast if the arena is reconfigured.

Movement (move) and torso rotation (aim) each carry their own heat model, independent of the project overheat system above and independent of each other:

Heat accumulates as heat = max(0, heat + energyUsed × heatFactor − coolingRate × dt) every physics tick, where energyUsed is the energy the motor/aim actuator actually spent that tick. A 0 for any *SafeHeat/*CriticalHeat field disables that threshold. Heat and any resulting damage are internal engine state, not exposed directly in the observation — only their effect (reduced effective acceleration/torque, and self.energyReserve draining faster than the plain motorEnergyCost/aimEnergyCost numbers would predict) is externally visible.

towParams

Always present in SciFi (towing is always enabled).

observation.arena

Per-tick arena state, present on every frame. Only these three keys are here; everything else is in frame.arenaBaseline above.

allowedActions

Not constant across a match:

• Combat actions are absent when the arena runs with combat disabled.
• During a scenario pause the list collapses to ["withdraw"] only.

worldZones

Only zones the unit can currently observe. A zone becomes visible when it is within detection range and has line of sight, so the set of known zones grows as the unit explores.

Zones are often placed close to the arena wall, which is not a hazard.

modeParams

Varies by mode. Fields guaranteed present:

Team-keyed fields (teamProgress, teamScores, teamTileCounts) appear whenever any player has a team assigned — including a single cooperative team — not only in multi-team matches.

football

incapacitation governs what happens to a unit at zero energy, and is the field to read before relying on hack or on a corpse persisting: "permanent" behaves like other modes (the unit stays down, visibleCorpses persists, hack has a stable target); "respawn-delay" and "none" bring the unit back into play, so a corpse from these is transient or absent — hack may be present in allowedActions without ever having a usable target. Other modes don't set incapacitation in modeParams at all; they always behave as "permanent".

observation.self

Authenticated unit state.

Identity

Position and orientation

The two facings are independent, so the unit can move in one direction while looking in another.

Vision

The Vision section below describes what these mean in practice.

Energy and combat

Recovery, tow and hacking

agentStats is not carried inside self — it lives in frame.arenaBaseline.agentStats.

Two further self fields — lastActionDebug (latest command resolution breakdown, including exact energy cost) and lastContactFeedback (physics contact/collision detail) — are omitted by default and can be requested per stream. See Observation envelope — Optional detail fields.

Vision

A unit that has never scanned still has a full field of view. Passive vision is always on and costs nothing:

Range is therefore rarely the limit. Arc, walls and line of sight are: nothing behind the unit is visible, and nothing through a wall or rift-wall tile.

aim re-centres the arc and costs agentStats.aimEnergyCost energy (0 by default). move changes position and costs agentStats.motorEnergyCost scaled by the motor's applied acceleration — see agentStats.motorEnergyCost above for the exact shape; a steady cruise costs little, accelerating or being blocked costs close to the stated rate.

scan replaces the passive arc with one you specify — up to 360° — for durationSeconds, and costs rangeMeters × (arcDegrees / 360) × 0.4 × durationSeconds. Two constraints follow from the implementation:

• aim cancels an active scan, resetting vision to the passive 180° arc.
• rangeMeters cannot exceed resolvedMaxSightRangeMeters, and rangeMeters: 0 is a zero-metre scan, not an unlimited one. Omit the field to scan at full range.

visibleTiles accumulates as terrain enters the arc, so the map is built by moving and aiming rather than by scanning from a fixed position.

Stun

Two independent mechanics, both counted in executes — resolved commands, not physics ticks or seconds — and both capped at 6.

Full stun (self.fullStunExecutesRemaining) blocks all actions. Triggered by falling: 1 execute per meter fallen, capped at 6. While active, submitting a command discards it entirely — the first action in the command gets outcome full-stunned in actionResults, the rest of the command's actions get no result at all, and events logs "Full stun: N executes remaining. Actions blocked." Submitting a command consumes one execute regardless of what the command contained; not submitting one does not.

Partial stun (self.stunExecutesRemaining) halves the effectiveness of move speed, scan range, and the energyAmount of project, defend and siphon. It does not block or reject anything: the action resolves normally at half magnitude, success/outcome in actionResults are unaffected, and the only visible signal is events logging "Stunned: 50% effectiveness. N stuns remaining." Triggered by:

A trigger raises stunExecutesRemaining to the higher of its current value and the trigger's amount (capped at 6) — repeated hits don't stack additively. Wall collisions only trigger a new stun while neither stun counter is already above zero; projectile hits always apply. Submitting a command consumes one execute from whichever counter is active, same as full stun.

Visible entities

All entity lists reflect what the unit can currently observe. Range, line of sight, and scan state determine what appears.

Entity id paths are not uniform across these lists — most are a direct [].id, but visiblePlayers nests it one level deeper:

observation.visiblePlayers

Living observed players within detection range and line of sight. The authenticated unit is represented by self; dead players are represented by visibleCorpses.

Each entry has three fields:

player exposes externally observable fields for another unit:

observation.visibleCorpses

Dead players within detection range and line of sight. See the visibleCorpses structure (id, team, position, bodyRadiusMeters, towedById).

observation.visibleProjectiles

observation.visibleDrones

The authenticated unit's own drones are always visible regardless of distance. Other players' drones are visible within normal detection range.

observation.visibleObjects

World objects (crates, tow targets, etc.) within detection range.

observation.visibleTiles

Tiles within the unit's current sight cone. Terrain enters the observation stream as the unit discovers it, so this list grows as you explore.

blocksMovement is the field to route around. Movement on a straight bearing will stall against a wall.

Tile x/y are spaced 1 meter apart and share the same coordinate space as self.position — round a unit's position to the nearest integer to find the tile it currently occupies. arenaBaseline.mapWidth/mapHeight are given in the same meters/tiles, since the arena is a square grid with one tile per meter.

Terrain types:

Action feedback

Neither of these is returned by the action POST. Both arrive on the next frame after a command resolves.

observation.actionResults

One structured entry per action in the last command.

actuatorFeedback

Present on move results. This is the field to read for real-time collision detection: visibleTiles only reflects terrain the unit has already seen, so a unit can be blocked by a tile it has never observed, and blocksMovement gives no signal for that case.

observation.events

Human-readable log lines for this tick, including the exact energy a command cost:

"Execute e55dedfd: cost 6.28e, reserve 93.72."
"Arena started. 1 players ready. You may now submit actions."

For a structured version of the same energy breakdown, open the stream with actionDebug=1 and read self.lastActionDebug.

observation.incomingHits

Projectiles that struck this unit since the last observation.

observation.contacts and observation.capabilities

contacts reports physics contact state for this tick, independent of whether a move was submitted. capabilities reports actuator feedback for movement, aim, body and combat: how the engine executed the last intent, which resolves cases where a command was accepted but the unit did not move as expected.

contacts:

capabilities.movement, capabilities.aim, capabilities.body and capabilities.combat each have the same shape as actionResults[].actuatorFeedback above, and update every tick regardless of whether a new command was submitted.

Teammates and signals

observation.teammates

Living teammates. Always visible, regardless of range or line of sight.

observation.teamSignals

Signals sent by teammates since the last observation.

teamSignals is delivered exactly once: a signal appears in the one frame built after it was sent, and is gone from every frame after that — there is no backlog, and resync does not bring back a signal from a frame the client never read. A client that wants to reliably catch every signal must read teamSignals on every frame it receives, not just the frames following its own submitted actions.

observation.interceptedSignals

Signals intercepted via hack. Present when self.hackingCorpseId is set. Same structure as teamSignals, and delivered the same one-frame-only way. These originate from the hacked unit's team.