Steering Behaviours and Flocking

What it does

You spawn an agent with a config: a top speed, a force budget, a mass and a list of behaviours, each with its own tuning, a weight and a priority. Each fixed step the agent works through its behaviours, highest priority first, and each claims part of the force budget. Avoidance, terrain, ceiling, containment and edges come first, flocking and following a leader next, goals last, and once the budget is spent the rest get nothing. That ordering is what stops a flock steering into a wall to keep up with its neighbours.

Bind an agent to a render handle and it writes its pose each step, interpolated between fixed steps, with yaw and pitch turning towards its velocity and an optional bank into turns. Ground walkers keep their height on a ground function and can pitch with the slope; flyers and swimmers steer in all three axes. Or read agent.pos and use it however you like: the pack holds no roster objects and draws nothing, so it runs in a worker or a test exactly as it does in a frame.

Beyond single behaviours, attractors and repulsors pull or scatter whole regions, and a strong repulsor push makes agents panic and run faster for a while, which is how a shoal bolts from a shark. navigate steers along a route planned by nav or nav-mesh, re-planning as the target moves, and flow follows a flow field, for hundreds of walkers heading to one place. Every wander draws from the agent's own stream, forked from the game's seeded one, so a replay wanders exactly as the first run did.

Features

• Seventeen behaviours — seek, flee, arrive, pursue, evade, wander, follow, flock, avoid, terrain, ceiling, contain, edge, leader, navigate, flow and custom.
• Priority blending — behaviours claim a force budget highest priority first, so staying safe wins over goals.
• Boids flocking — separation, alignment and cohesion over the nearest neighbours, with a spatial hash above 40 agents.
• Fields and obstacles — attractors and repulsors that can follow a live object, panic after a strong push, and sphere and box obstacles.
• Planned routes — navigate over any planner with a path method, sized for the agent's body, turning for the next waypoint as soon as it can reach it directly.
• Flow fields — flow follows nav's flow field, its weighted grid adapted by a function, or any field you write.
• Ground and flight — height held to a ground function with optional slope pitch, or full 3D movement with a pitch clamp and banking.
• Six presets — firefly, fish, shoal, hunter, bird and patrol.
• 2D agents — spawn2d and flock2d drive a sprite's x, y and rot with the same behaviours in 2D.
• Seeded and replayable — per-agent streams forked from the game's, with snapshot and restore.

Good for

• Flocks, shoals and swarms: birds, fish and fireflies that move as groups and scatter from a predator.
• Patrolling guards in a stealth game, following routes round a tile map or over 3D terrain.
• Hordes and crowds pouring along a flow field to one goal, such as a tower-defence wave or a zombie rush.
• Homing missiles and hunters that pursue a moving target and aim for where it will be.
• Wildlife and ambience: wandering animals and insects that bring a world to life.
• Escorts and followers that keep station behind a leader.

Make it yours

Every agent is its config and every behaviour its tuning. The config sets maxSpeed, maxForce, mass, turnRate, maxPitch, bank, panicSpeed, a ground, a seed, the handle to drive, and tickEvery to solve steering only every nth step, for level of detail; each behaviour has its own distances, a weight and a priority. Presets are a starting point to override, and a custom behaviour adds a force of your own.

Two different uses: a 3D underwater scene where a shoal flocks with a little wander, and a repulsor following the shark makes it panic and bolt at its panic speed; and a top-down 2D stealth game where a guard sprite avoids obstacles and navigates a nav grid towards the hero, re-planning as the hero moves, while a flock of birds wanders overhead.

A quick look

A 2D guard that navigates towards the hero, a school of fish, and a shark they flee:

const grid = game.nav.grid2d({ cols: 20, rows: 12, cell: 32, walkable });
const guard = game.steering.spawn2d({
    handle: guardSprite, pos: { x: 48, y: 48 }, maxSpeed: 140, maxForce: 700,
    behaviors: [{ kind: 'avoid' }, { kind: 'navigate', grid, target: () => ({ x: hero.x, y: hero.y }), radius: 10 }],
});
const fish = game.steering.flock2d({ maxSpeed: 90, maxForce: 300,
    behaviors: [{ kind: 'flock', radius: 48 }, { kind: 'wander', weight: 0.4 }] }, fishSprites);
game.steering.agents2d.repulsor({ follow: shark, radius: 120, strength: 2000 });

Works with

• nav — the grids that planned routes run over, and the flow fields hordes follow.
• nav-mesh — routes over bridges, arches and floors above floors; its own crowd is a separate avoidance system, so use one or the other for a given crowd.
• path-3d — smooth 3D curves for agents to follow.
• actors — lighter one-call movement chips for a 2D arcade shooter.
• track — authored routes with junctions, when the way is fixed rather than steered.
• stealth — sight, hearing and suspicion for the guards you steer.

Good to know

• Agents do not collide with each other: separation keeps them apart, which reads right for crowds but is no solid-body guarantee.
• avoid sees only the obstacles you give the system, on the ground plane; it does not avoid other agents or walls it has not been told about.
• A steered body swings a little wide of sharp turns by its own momentum, so pair navigate with avoid or collision where contact matters.
• 2D agents have no terrain or ceiling, and 2D and 3D agents are separate systems that never flock together.
• It moves a handle but does not animate it: how the body looks while moving is your game's.