Things that decide for themselves

orblit_agent is two layers that usually get conflated, and shouldn’t be.

Steering answers where to go: a force, computed from the world, that moves something this frame. Seek, flee, arrive, wander, separate, align, cohere, pursue, evade.

Behaviour trees answer what to want: which of those to be doing, and when to stop.

An agent that flees when frightened and wanders the rest of the time is a behaviour tree choosing between two steering behaviours. Build it as one thing and you have a state machine that needs rewriting every time a state is added.

Steering composes by adding

Behaviours return forces, and forces add. That’s the whole composition model, and it’s why a flock is separate + align + cohere with weights rather than a flocking algorithm.

Two things the textbooks get wrong

separate must not normalise. Its whole point is that it pushes harder the closer things get. Normalising the result throws that away and gives you a uniform shove, which looks right until things bunch up, and then doesn’t.

arrive does overshoot. The usual claim is that it doesn’t. It does. What it actually buys you is a controlled approach speed, which was the thing you wanted anyway. Plan for the overshoot rather than assuming it away.

Behaviour trees

Sequences, selectors, decorators and leaves: the standard vocabulary. A tick returns running, succeeded or failed, and a node that was running last tick gets resumed rather than restarted.

Unlike the sampled parts of the engine, a behaviour tree genuinely steps. A decision made last tick is meant to persist, and that’s history rather than a value at a time. See sampled, not stepped for where the line falls.

Spatial queries

Steering needs neighbours, and asking every agent about every other agent is quadratic. orblit_collide gives you the spatial hash for it.

The XOR hash trap

A spatial hash of the form x*a ^ y*b ^ z*c collides on symmetric coordinates, and the symptom is a strange one. A shape lands in the same bucket twice and then pairs with itself, so an agent tries to separate from where it already is. Mix the coordinates sequentially instead of by XOR.