The first thing we need to consider in swarm dynamics is the individual. Before a group can behave intelligently, each member needs to perceive its local environment. We start from one boid's point of view: what can it see, and how strongly does it register what's nearby?

Every boid carries a forward-facing cone of awareness — a limited field of view that extends ahead along its heading. Anything outside this cone is invisible to the boid, no matter how close. This is deliberate: real organisms don't have eyes in the back of their head, and restricting perception to a forward cone produces much more natural avoidance behavior than a full 360° awareness would.

When another particle drifts into the cone, the boid registers it with an intensity that depends purely on distance — touching the boid produces maximum signal, while a particle at the edge of the cone barely registers. This creates a smooth gradient of attention rather than a binary on/off.

Detection kernel

const dx = particle.x - boid.x;
const dy = particle.y - boid.y;
const dist = Math.sqrt(dx * dx + dy * dy);

// Angle relative to boid's heading
const angle = Math.atan2(dy, dx) - boid.heading;

// Inside ±55° awareness cone?
const FOV = 55 * Math.PI / 180;
const inCone = dist < radius
            && Math.abs(angle) < FOV;

// Closer → more opaque (stronger signal)
const opacity = inCone
  ? 1 - dist / radius
  : 0;

Now that our boid has awareness, we need to understand how it makes decisions. Seeing a nearby particle isn't useful unless it leads to action. This step gives the boid a simple rule: if something is in your cone, steer away from it.

The strength of the avoidance is proportional to proximity — a particle barely inside the cone produces a gentle nudge, while one headed straight at the boid at close range produces a sharp turn away. When multiple particles are detected simultaneously, their individual repulsive contributions are summed into a single steering vector in the plane.

Like the full tank (Step 3), this boid moves forward only at a fixed cruise speed: steering forces may change its heading (the direction of its velocity) but not its speed. To keep the scene readable, we confine it to the lower half of the tank (between mid-height and the bottom). Particles rain down from above within ±45° of head-on. When the threat clears, a gentle pull toward the bottom-center mimics cruising home — the same idea as the cohesion-style centering in the flock, simplified here to one point.

Avoidance kernel

// Accumulate avoidance (full 2D)
let avoidX = 0, avoidY = 0;
for (const p of detected) {
  const strength = 1 - p.dist / radius;
  avoidX += -p.dx / p.dist * strength;
  avoidY += -p.dy / p.dist * strength;
}

// Steering + gentle home toward bottom center
const desiredVx = boid.vx + avoidX * avoidanceForce + (homeX - boid.x) * pull;
const desiredVy = boid.vy + avoidY * avoidanceForce + (homeY - boid.y) * pull;

// Rotational dynamics (no instant heading snap)
const desiredHeading = Math.atan2(desiredVy, desiredVx);
const err = wrapAngle(desiredHeading - boid.heading);
boid.turnVel = (boid.turnVel + err * turnAccel) * turnDamping;
boid.turnVel = clamp(boid.turnVel, -maxTurnRate, maxTurnRate);
boid.heading += boid.turnVel;

// Forward-only propulsion at fixed speed
boid.vx = Math.cos(boid.heading) * cruise;
boid.vy = Math.sin(boid.heading) * cruise;

Steps 1 and 2 gave a single boid perception and reaction. Now we put that logic into every boid in the tank and let them loose. There is no central controller, no predefined paths, no collision grid — each individual applies the exact same awareness cone and steering forces from the previous steps (then keeps a fixed cruise speed, as in Step 2), considering only the neighbors it can see.

The red boids are "hero" agents — they show their awareness cones and detection lines so you can see the local perception at work. The white boids are running the exact same logic but without the visual debug overlay, giving you a sense of the population density without the visual clutter. Together they demonstrate a key insight from Reynolds' 1987 paper: complex, coordinated group behavior emerges from simple, local rules.

Try cranking up the boid count and shrinking the awareness radius — you'll see them pack tighter and react later, producing more chaotic, last-second dodges. A larger radius produces smoother, earlier avoidance.

Move the pointer over the tank — boids treat your cursor as a moving obstacle. Outer walls are obstacles too, so boids turn away when a wall enters their cone.

Before a boid can check for collisions in 3D, it needs to know which directions to look. We need a way to distribute sample points evenly — and the tool for that is a deceptively simple loop: place each successive point at a fixed angular offset from the last, spiraling outward from the center.

The key is the turn fraction — how much of a full circle each point rotates relative to the previous one. At 0, all points pile on a single line. At 0.5, they alternate between two arms. But at 1/φ (where φ is the golden ratio), something remarkable happens: no two points ever land near each other, producing the most uniform distribution possible from a sequential process.

This works because the golden ratio is the "most irrational" number — its continued-fraction representation converges more slowly than any other irrational, so the angular gaps never repeat or cluster. Try dragging the turn fraction slider toward 0.618 and watch the pattern emerge.

Golden ratio

// Golden ratio turn fraction
const PHI = (1 + Math.sqrt(5)) / 2;
const GOLDEN_FRAC = 1 / PHI;

for (let i = 0; i < N; i++) {
  const r = i / (N - 1);
  const angle = i * GOLDEN_FRAC * TWO_PI;
  points.push({
    x: r * Math.cos(angle),
    y: r * Math.sin(angle),
  });
}

The Fibonacci disc gives us a beautiful flat distribution, but boids live in 3D — they need sample directions spread across a sphere. The problem: if we naively map our disc points onto a sphere, they bunch up at the poles.

The fix is a power correction on the radial distance. At the default exponent of 1.0, points cluster. At 0.5 (square root), the mapping becomes equal-area and points spread uniformly across the sphere surface. Drag the exponent slider to see the transition — and drag on the sphere itself to orbit around it.

These sphere points will become the boid's collision ray directions. One subtlety: perfectly uniform distribution isn't necessarily optimal. A boid looking straight ahead doesn't need many tightly-packed samples in a narrow forward cone — it's too wide to fit through tiny gaps. In practice, sparser forward sampling with denser peripheral coverage works better.

Sphere mapping kernel

// Power-corrected radial distance
const t = i / (N - 1);
const r = Math.pow(t, power);
const angle = i * turnFrac * TWO_PI;

// Disc radius → polar angle
const theta = Math.acos(1 - 2 * r);
const phi = angle;

// Spherical → Cartesian direction
const dir = {
  x: Math.sin(theta) * Math.cos(phi),
  y: Math.sin(theta) * Math.sin(phi),
  z: Math.cos(theta),
};

Now the Fibonacci sphere directions become collision rays. The boid cycles through its precomputed sample directions and steers toward the first one that isn't blocked by an obstacle.

The critical difference from 2D: dodging is not a lateral strafe. The boid rotates its entire body toward the clear direction, which also rotates its visual field. This means the set of visible obstacles changes as the boid turns — it's navigating with a moving camera, not a fixed one.

Each sample direction is tested with a simple ray-sphere intersection. The boid picks the first unobstructed ray (biased away from dead-ahead to prefer evasive maneuvers over braking), then smoothly slerps its heading toward that direction.

Ray sampling kernel

// Local → world transform
const worldDir = v3Norm(v3Add(
  v3Add(v3Scale(right, s.x),
        v3Scale(up, s.y)),
  v3Scale(forward, s.z)
));

// Ray-sphere intersection test
for (const obs of obstacles) {
  const proj = v3Dot(toObs, worldDir);
  const perp = v3Sub(toObs,
    v3Scale(worldDir, proj));
  if (v3Len(perp) < obs.size)
    blocked = true;
}

// Steering target from first clear ray
desiredDir = bestDir;

// Angular acceleration -> angular velocity -> forward rotation
axis = normalize(cross(boid.forward, desiredDir));
angleErr = atan2(length(cross(boid.forward, desiredDir)),
                 dot(boid.forward, desiredDir));
boid.angVel = damp(boid.angVel + axis * angleErr * turnAccel);
boid.forward = rotate(boid.forward, boid.angVel);

Everything comes together. Each boid carries the same Fibonacci-sampled collision rays from Step 5, the same rotation-based steering from Step 6, and is released into a shared 3D space with no central controller.

The red boids show their sample rays and awareness interactions. The white boids run identical logic but without the debug overlay. A soft spherical boundary keeps everyone from drifting off into the void — when a boid approaches the edge, it receives a gentle nudge back toward center.

This is Reynolds' 1987 insight, fully realized in 3D: complex, coordinated group behavior from nothing more than local perception and a handful of simple rules. No pathfinding graph, no collision grid, no central planner.

N-body avoidance kernel

// N-body ray check
for (const s of boid.sampleDirs) {
  const wd = localToWorld(s, boid);
  let clear = true;

  for (const other of allBoids) {
    if (other === boid) continue;
    if (rayHits(boid.pos, wd, other))
      { clear = false; break; }
  }
  if (clear) { bestDir = wd; break; }
}

let desiredDir = boid.forward + bestDir * avoidW
               + cohDir * cohesionW
               + avgDir * alignW + wallPush;
steerToward3D(boid, desiredDir);

// Ray-wall intersection per axis
for (let a = 0; a < 3; a++) {
  const tPlus  = (wall[a] - pos[a])
                / dir[a];
  const tMinus = (-wall[a] - pos[a])
                / dir[a];
  const tWall = Math.min(
    tPlus > 0 ? tPlus : Infinity,
    tMinus > 0 ? tMinus : Infinity);
  if (tWall < range) blocked = true;
}