NPCs, behaviours and pathfinding

Bring characters to life: NPCs that talk, enemies that patrol, chase or guard, A* pathfinding around water and props, and back-and-forth paths.

Sandbox tells two kinds of characters apart. The NPC (npc) is someone to talk to: it stays put and speaks when you press E. The enemy (enemy) is an actor: it moves according to a behaviour and walks around obstacles using a navigation grid.

NPCs that talk

An NPC is solid and stationary. When the player comes close (about 1.2 units beyond its radius), the HUD shows the params.label prompt, or “Press E to talk” by default. Pressing E shows params.text for four seconds and turns the character toward the player. This works in every mode.

Place a character
On the Cast step, NPCs group, click Add an NPC and pick a character: it lands in the right role. You can also place any asset with the Character role on the Build step.
Write its line
Fill in the text (text) and, if you like, the prompt (label).
Hook it to the logic
Give it a tag: every E press then emits an interact event that your rules and scripts can listen to, for instance to hand out a quest.

villager.jsonJSON

{
  "role": "npc",
  "assetId": "a_sheep",
  "params": {
    "text": "The camp key fell near the western rocks. Bring it to the gate.",
    "label": "Press E to talk",
    "tag": "villager"
  }
}

Behaviours (behavior) only apply to enemies: an NPC does not move. For a character that walks around without attacking, use an enemy in explore, where contact shoves without hurting, or a path (see below).

Enemy behaviours

The behaviour is read by the shared AI of the platformer, explore and arena modes. With no value, an enemy patrols. Everything is measured from its starting position (its “home”) and its radius (6 by default).

Behaviour	What it does
`patrol`	Loops gently around its starting point; if the player comes within 0.6 × radius, it starts chasing.
`chase`	Chases the player once within 1.5 × radius, with pathfinding.
`guard`	Holds its post; only chases the player who comes within its radius near the post, then walks back.
`flee`	Moves away from the player while within its radius.
`wander`	Picks a random point within its radius every 2 to 5 s and walks there, at half speed.
`orbit`	Circles its starting point (radius / 2), following the ground.
`idle`, `spin`, `bob`	Stays in place. `spin` and `bob` exist in the format but do not move the entity: to make an object turn or float, use an animation clip (Spin / Bob presets).

behaviorstringDefault 'patrol'

One of the behaviours above.

speednumberDefault 2.2

Speed in units per second (the player runs at 6.5).

radiusnumberDefault 6

Detection, patrol and wander radius.

hpnumberDefault 1

Hits taken before dying (stomp, bullet, turret).

Depending on the mode

Touching an enemy costs a life, unless you land on it from above: it loses 1 HP and you bounce. At 0 HP it disappears (+150 points, kill event).

Placed enemies form wave one and switch to chase when they have no behaviour. Later waves clone them, always chasing, faster and faster.

In race, runner and tower defense, behaviours are ignored: race bots follow the checkpoints, runner enemies are obstacles, tower defense enemies follow the waypoints. In CTF, bots have their own AI (steal your flag, defend theirs) and use speed (3 by default).

Pathfinding (A*)

When an enemy wants to reach a target (the player, its post, a wander point), it first checks whether the straight line is clear. If not, it follows a path computed by A* on a navigation grid, refreshed twice a second.

Element	Rule
Grid	One cell per terrain cell, built the first time it is needed.
Water	A cell more than 0.6 units below the water level is blocked: enemies walk around deep lakes.
Obstacles	Static solid entities (props, doors, NPCs…) block their footprint. Entities with a `path` are skipped since they move.
Slopes	A step higher than 0.55 units cannot be climbed; climbing costs more than flat ground.
Diagonals	Allowed, without cutting an obstacle’s corners.
Blocked target	The path aims for the nearest open cell (up to 3 cells around).

The grid is frozen at the first query: a prop that appears or disappears later does not change it. Place important walls from the start.

Back-and-forth paths

The path parameter makes any entity move back and forth between its starting position and an offset, with smooth easing. That is what makes moving platforms (the platform role, which carries the player standing on it), but also a sliding door, a hazard sweeping a corridor or a floating prop.

to[x, y, z]required

Offset of the destination from the starting position.

secondsnumberrequired

Duration of one leg (0.2 s minimum).

pausenumberDefault 0

Wait time at each end.

moving-platform.jsonJSON

{
  "role": "platform",
  "params": {
    "solid": true,
    "path": { "to": [6, 0, 0], "seconds": 3, "pause": 0.6 }
  }
}

The “Sky Steps” platform: 6 units to the right in 3 s, 0.6 s pause at each end.

NPCs that talk#

Enemy behaviours#

Depending on the mode#

Pathfinding (A*)#

Back-and-forth paths#

See also#