Entity roles

The 23 roles an entity can play in a Sandbox world, what the runtime does with each one mode by mode, their parameters and entity triggers.

Everything you place on the Cast and Build steps is an entity: an asset (or nothing, for invisible markers), a position, a rotation, a scale and above all a role. The role tells the runtime how to treat the object: solid scenery, a pickup, an enemy, a door, an event zone, a waypoint…

Tower defense entities in the studio — Waypoints, base, turrets and enemy spawn placed on the Build step.

Anatomy of an entity

An entity is a small JSON object in doc.entities. A document accepts up to 3,000 of them. The role is picked in the inspector; role-specific parameters appear below it.

idstringrequired

Unique id within the document. Show / remove actions and scripts target it.

assetIdstring | nullrequired

The asset shown. null for an invisible marker (spawn, waypoint, event zone, spawner…).

roleEntityRolerequired

The role, see the table below.

pos[x, y, z]required

Position in world units.

yawnumberrequired

Rotation around the vertical axis, in degrees.

scalenumberrequired

Uniform scale. It also affects the collision radius and, for a light, its range.

paramsEntityParamsrequired

Role parameters (tag, behaviour, trigger, spawner…).

entity.jsonJSON

{
  "id": "e_k2f9",
  "assetId": "a_gate",
  "role": "door",
  "pos": [12, 3, 12],
  "yaw": 45,
  "scale": 1,
  "params": { "text": "camp key" }
}

The gate of the “Quiet Island” template: it opens once the player has picked up the “camp key”.

The 23 roles

Some roles are handled by every mode (doors, keys, moving platforms, NPCs, triggers, spawners, lights, sounds); others only make sense in a given mode. The “Solid” column gives the default, which params.solid overrides (modes also make some roles walk-through when they start).

Role	Solid	What the runtime does
`player`	—	Player start and avatar. The first one found is used; without one the player appears at (0, 0) as a hero (or a kart in race).
`prop`	yes	Scenery. Blocks movement and stops bullets in arena.
`obstacle`	yes	Like a prop; in Runner, bumping into it costs a life.
`platform`	yes	Moving platform: follows `params.path` and carries the player standing on it.
`coin`	no	Platformer: +1 coin (100 pts). Explore: collected, and collecting all wins when there is no finish. Arena: restores 1 HP. Race: short boost. Runner: +10 pts, comes back every loop.
`key`	no	Picked up on contact in every mode and grants the key named by `params.text` (or the entity id).
`door`	yes	Disappears on contact if the player holds the key named by `params.text`; with no name it opens on first contact.
`checkpoint`	no	Race: crossed in `params.order` order. Platformer: respawn point.
`finish`	no	Race: the line that counts laps. Platformer and explore: the goal, subject to `rules.coinsToWin`.
`enemy`	no	Follows its behaviour (see NPCs and behaviours). Hurts on contact, is stomped from above in platformer, shot in arena, shoves in explore, serves as the wave template in arena and tower defense, and as an opposing bot in CTF.
`npc`	yes	Static character: in range it shows `params.label` (or “Press E to talk”) and `E` displays `params.text` for 4 s.
`hazard`	no	Platformer and runner: costs a life. Arena: 1 HP. Race: spin-out. Explore: sends you back to the last safe ground.
`boost`	no	Race: speed pad (1.4 s). Platformer and explore: bounce pad, height × `params.strength`. Runner: +0.4 speed.
`spawn`	—	Where waves come from in arena and tower defense. Ignored elsewhere.
`text`	no*	Sign. In explore, `E` in range shows `params.text` and counts the sign as read (+50 pts). *Solid in explore.
`trigger`	no	Event zone: runs its `params.trigger`, and emits `enter` / `leave` to rules when it has a tag.
`light`	no	Point light placed 1 unit above the entity.
`spawner`	—	Spawns an asset over time (`params.spawner`).
`sound`	—	Spatialised sound source, started when the game begins.
`flag`	no	CTF: team flag (`params.team`).
`base`	yes	CTF: team base where the flag is brought home. Tower defense: the gate to defend.
`turret`	yes	Fires on its own at the nearest enemy in range (`range`, `fireRate`).
`waypoint`	no	Tower defense: steps of the enemies’ path, in `params.order` order.

Same world, another mode

Switching mode keeps every entity: a coin that heals in arena becomes a goal in explore. Per-mode details are in Game modes.

Parameters (EntityParams)

Every parameter is optional. Each one is only read by the roles that need it; the inspector only shows the ones that apply to the chosen role.

Common

tagstring

Free label targeted by rules (touch, pickup, removeTag…) and exposed to scripts.

hiddenbooleanDefault false

Hidden at start; a show / showTag action reveals it.

solidboolean

Forces collision on or off (see the Solid column above for the default).

tintstring

Colour that overrides a mesh asset’s material; the light colour for the light role (default #ffd58a).

labelstring

Prompt shown when in range of an NPC or an “interact” trigger.

textstring

An NPC’s line, a sign’s text, the name of the key a key grants or a door requires.

clipsPartial<Record<ClipRole, string>>

Clip per animation role (idle, move, jump, hit, attack, spin), see Animation.

Actors and movement

An enemy’s AI.

speednumberDefault 2.2

Enemy movement speed (units / s).

radiusnumberDefault 6

Detection and roaming radius; a light’s range (default 8).

hpnumberDefault 1

An enemy’s hit points.

path{ to: [x, y, z]; seconds: number; pause?: number }

Back-and-forth to an offset, for moving platforms and any other role.

strengthnumberDefault 1

A bounce pad’s strength; a light’s intensity.

ordernumberDefault 0

Order of checkpoints (race) and waypoints (tower defense).

team'red' | 'blue'

Team of flags, bases and bots in CTF.

valuenumber

Present in the format; no mode reads it today.

Systems

spawner{ asset, role, every, max, total, radius, behavior? }

See Spawners.

rangenumber

A turret’s range (7 outside tower defense, 6 in tower defense).

fireRatenumber

Turret shots per second (1.2 outside tower defense, 1.6 in tower defense).

sound{ url, radius, loop, volume }

Sound source of the sound role.

triggerTrigger

Local event, see the next section.

Entity triggers

A trigger attaches a list of actions to one specific entity, without going through the Rules step. It is set in the inspector (“Events”) and works on any role; the trigger role with no asset turns it into an invisible zone.

on'touch' | 'interact' | 'stomp'required

touch: the moment the player makes contact. interact: when the player presses E in range (the prompt shows label or “Press E”). stomp exists in the format but no mode fires it today; the studio only offers the first two.

oncebooleanrequired

Fires only once per game.

needsstring

Name of a key the player must hold (picked up from a key entity or granted by the unlock action). Otherwise the HUD shows “Needs …”.

actionsTriggerAction[]required

Run in order, with the entity as the source.

Trigger actions

type	Fields	Effect
`message`	`text`	Shows a HUD message for 2.5 s.
`score`	`value`	Adds to the score (a bonus added on top of the mode’s score).
`teleport`	`x, y, z`	Teleports the player and resets their velocity.
`remove`	`target?`	Hides the target entity, or the source when there is no target.
`show`	`target`	Reveals a hidden entity.
`win` / `lose`	`text?`	Ends the game, won or lost.
`heal` / `hurt`	`value`	Heals or hurts the player (lives in platformer, HP in arena and CTF; no effect in the other modes).
`speed`	`value, seconds`	Multiplies the player’s speed for a while.
`spawn`	`asset, role, count`	Spawns up to 20 copies around the source.
`unlock`	`key`	Grants a named key (for a door or a `needs`).

chest-trigger.jsonJSON

{
  "role": "trigger",
  "params": {
    "label": "Press E to open",
    "trigger": {
      "on": "interact",
      "once": true,
      "actions": [
        { "type": "message", "text": "The chest was full of coins." },
        { "type": "score", "value": 500 },
        { "type": "spawn", "asset": "a_coin", "role": "coin", "count": 6 }
      ]
    }
  }
}

The chest of “Quiet Island”: a one-time interaction worth 500 points that spills six coins.

Tags and events

The tag links an entity to the global logic. When a tagged entity is touched, picked up, killed or activated with E, the runtime emits the matching event to the rules, with its tag. A rule can target one tag or *, which matches any tag.

Event	When
`touch`	The player makes contact with a tagged entity (other than the trigger role).
`enter` / `leave`	The player enters / leaves a tagged `trigger` entity.
`interact`	The player presses `E` in contact with a tagged entity.
`pickup`	A coin (platformer, explore) or a key (every mode) is picked up.
`kill`	An enemy dies (stomped, shot, or hit by a turret outside tower defense).

No tag, no rule event

Rules only receive events from entities that have a tag, even with *. Scripts also receive pickup and kill from untagged entities, with { entityId, role, tag }. Entities created by a spawner inherit the spawner’s tag.

Going further

NPCs and behavioursPatrol, chase, guard, flee, wander and A* pathfinding.Spawners and turretsWaves, turrets, waypoints, flags, sounds and lights.Rules and eventsReact to tags across the whole game.ScriptingRead and drive entities in JavaScript.

Anatomy of an entity#

The 23 roles#

Parameters (EntityParams)#

Common#

Actors and movement#

Systems#

Entity triggers#

Trigger actions#

Tags and events#

Going further#