Skip to content

Spatial

The @shell/spatial package provides 2D flow-field navigation, a spatial grid, dynamic obstacles, terrain costs, range-gated steering, and agent separation.

@shell/spatial is a game-level package. It is not included in @shell/engine-2d, so install it separately even when your application already uses the 2D engine:

Terminal window
pnpm add @shell/spatial

Add SpatialPlugin to the world and configure the navigable world bounds:

import { Engine2D, World } from '@shell/engine-2d';
import { SpatialPlugin } from '@shell/spatial';
const world = new World();
world.addPlugin(
Engine2D({ canvas, resizeTo: window }),
SpatialPlugin.config({
cellSize: 32,
width: 2048,
height: 2048,
}),
);
await world.mount();

Install it once: its resources serve every Scene of the world. A Scene’s targets and obstacles go with it when it is unloaded. While a Scene is paused, spatial’s systems leave its entities out: its agents stand still, and its obstacles and targets leave the grid until it resumes.

OptionDefaultDescription
cellSize64Width and height of one navigation and spatial-index cell
width4096Navigable world width, with centerX in its middle
height4096Navigable world height, with centerY in its middle
centerX0World position of the grid’s middle
centerY0World position of the grid’s middle
flowFieldMaxHeapPopsPerUpdate4096Shared amount of flow-field build work allowed per Update
flowFieldMaxFieldsStartedPerUpdate4Maximum number of new flow-field builds started per Update
lineOfSightIntervalMs100Approximate time over which every range-gated agent is checked once

Choose a cellSize that reflects the useful navigation resolution of the game. Smaller cells produce more precise routes but increase the size and rebuild cost of every navigation profile.

The grid is centred on the origin unless centerX and centerY say otherwise: by default it covers -2048 to 2048 on both axes, which fits a scene whose camera looks at (0, 0). A world that runs from the origin states its middle:

SpatialPlugin.config({ width: 2048, height: 2048, centerX: 1024, centerY: 1024 });

A position outside the grid counts as on its edge. SpatialGrid, NavigationProfile, and FlowField have minX and minY, the world position of the grid’s minimum corner: cell x starts at minX + x * cellSize.

SpatialSettings is a settings type (spatial:settings) with the same fields as the configuration. The Project’s settings of it (File › Project Settings in the editor) are used in place of what the plugin was configured with, and what they leave unset is the type’s default. It is how a project that added spatial as a Package in the editor sets these numbers, since no code of its own installs the plugin. The grid is sized when it is first used, so a change applies to the next play.

A target needs FlowFieldTarget and either a Position or an explicitly assigned GridCell. An agent needs Position, Velocity, GridCell, and FlowFieldAgent:

import { Define, Position, Velocity } from '@shell/engine-2d';
import { FlowFieldAgent, FlowFieldTarget, GridCell } from '@shell/spatial';
const Target = Define.prefab().with(Position, { x: 1600, y: 900 }).with(FlowFieldTarget);
const Agent = Define.prefab()
.with(Position, { x: 100, y: 100 })
.with(Velocity)
.with(GridCell)
.with(FlowFieldAgent, { speed: 120 });
const commands = world.get('commands');
commands.spawn(Target);
commands.spawn(Agent);

FlowFieldTarget automatically adds its required GridCell. For a positioned target, the plugin keeps that cell synchronized. The agent’s velocity is steered toward the target during fixed updates, and the kinematics dependency installed by SpatialPlugin integrates that velocity into Position.

Flow-field construction is budgeted, so a newly created or changed field can take multiple updates to publish in a large world. Agents keep using the last completed field while a replacement builds.

PluginPurpose
GridPluginSynchronizes GridCell and exposes the spatialGrid resource
FlowfieldPluginTracks targets, builds flow fields, and steers agent velocity
ObstaclePluginMaps positioned obstacles and terrain costs onto the default profile
LineOfSightPluginOptionally gates steering by target range and chooses priority groups
SeparationPluginAdds local repulsion between participating agents
KinematicPluginIntegrates the velocity changed by flow-field and separation steering

The package also exports these plugins individually. Use the aggregate for normal navigation; use a standalone plugin when you only need one capability, such as GridPlugin.

  • Flow Fields — Create agents and targets, use groups, and access navigation profiles
  • Obstacles & Terrain — Block cells or make regions more expensive to cross
  • Agent Behaviors — Gate steering by range, select fallback targets, and separate crowds
  • Spatial Grid — Find entities by cell or world-space bounds, with or without navigation