Swarm flow-field structure

field_freq is the swarm’s spatial lever and the one that decides how many distinct streams a frame can hold. The scene steers every particle by a scalar potential sampled at world * field_freq, so it sets the size of a current relative to the frame. Default 2.3, which is the constant it replaced — a preset that does not bind it is unchanged. Measured across the range on a since-retired swarm:

value	what the frame does
0.8	the field’s structure is larger than the frame, so there are no legible channels at all — a uniform dense mass with one slow convergence front migrating across it over tens of seconds
2.3	broad rolling currents with visible density waves: crests gathering, wakes thinning
6.0	a few sharply resolved sinuous ribbons with genuinely empty dark space between them

Note which direction reads as busier: it is the low end, not the high one. A high field_freq does not make confetti — it separates the swarm into distinct streams and gives back negative space, while a low one packs the frame edge to edge because every particle is inside the same enormous current.

Read it against spin, which is the temporal lever and a different question entirely: field_freq says how finely the field is divided, spin how fast it is rewritten. The family’s apparent flocking is not a per-particle rule — it emerges from neighbours falling onto the same streamline and travelling together — so a coarse field (low field_freq) with a near-frozen one (low spin) is the formation-holding end, and raising either dissolves the flock toward shimmer.

spin integrates a phase (ADR-0132), the same shape fragment_field’s field_speed / fold_speed, warp_mesh’s warp_speed and parametric_curve’s spin take — so it is safe to bind to audio. A rate that instead multiplied the shared clock is what makes this matter: a since-retired swarm bound spin to mid, and under that older form a 0.75 swing a hundred seconds into a set advanced the field clock about four seconds in one frame against a nominal 0.019 — a re-roll of the whole field, growing without bound as a set runs. Every shipped swarm is tuned for the integrated form.

The swarm’s marks individuate the way the emitter’s do — same names, same semantics (see Individuation). size_spread widens the per-mark size as a fraction either side of size; the swarm’s seeded scatter already varies mildly on its own, and this opens that distribution further. twinkle is a per-mark brightness oscillation whose rate and phase both come off the seed, so the field shimmers while the whole-frame light sits still — which is what separates it from binding brightness to an oscillator, which flashes the frame as one sheet. Both default 0; an unbound preset is byte-unchanged. This is the pair that makes a sparse starfield able to twinkle at all (backlog 0068).

The swarm also carries reseed, the attractor family’s percussive accent with the attractor’s semantics: a rising edge past 0.5 disturbs the population where it is — a seeded kick of ±6 % of the domain per axis — rather than respawning it into a box, so it reads as the field being shaken, never erased, and the flow re-gathers it within a few seconds. It is edge-triggered: bind a gate (reseed = "onset > 0.6"), not a level — a held high fires once, not continuously. It is also the recovery lever for a sustained-force pile-up (backlog 0085); note that the minutes horizon of that recovery is outside what the test suite can see, so a world leaning on it owes a one-off soak check of its own.

Two things the swarm does on its own, with nothing to bind.

The swarm lives in a volume and is seen through a camera (ADR-0259). Every particle has a depth inside a slab in front of the eye, and that depth changes: a slow current of the same flow field carries particles toward and away from the camera over tens of seconds. Each sprite is projected through the same perspective camera as plexus and the space curves, so everything depth does falls out of the projection rather than out of a hand-made cue:

• Size. size is stated at the middle of the slab; a near mark draws larger and a far one smaller, about 2.7x apart from front to back.
• Speed. The flow is evaluated in the world, so under the same current a far particle crosses the screen more slowly than a near one, because it is farther away.
• Light. depth_fade dims a particle with its depth. Its default reproduces the old 0.45-to-1.05 ramp; 0 lights every depth alike.
• Focus. focus and aperture give the swarm a focal plane, as on plexus: marks at the focal depth stay sharp and the layers in front and behind grow soft and dim by the area they spread over. A blurred polygon reads as a soft polygon. aperture = 0, the default, keeps every mark sharp, and the blur is clamped to the tier’s swarm cap.
• Layers. Particles at different depths ride different currents, so the layers cross and separate rather than following the same streamlines at several sizes.

There is still no sorting and no occlusion: the scene blends additively, so two particles at different depths that overlap simply sum, and depth reads strongest on a sparse field.

The world is a torus shaped like the camera’s view. Across the frame it wraps, and it extends a quarter past the frame’s edge at every depth, so the wrap seam is off-screen near and far alike. A particle that reaches either end of the slab fades out and re-enters at the other end, so the depth wrap never pops.

The camera is a subset of the shared block. fov narrows or widens the view (a wider one uses up the margin, and much wider shows the seam). yaw and pitch turn it about the middle of the slab, so the near and far layers slide past each other in opposite directions; both are held to the sway the margin covers, so bind them to a slow wave rather than a clock. There is no distance: the slab is placed relative to the camera, and an orbit would show the edge of the world.

zoom and pan_* no longer parallax. zoom divides the field of view and pan_* shift the projected picture, so both move every layer together. zoom below about 0.82 shows the seam, and pan spends the same margin.

The margin and the fade cost visible density — about a third of the population is off-screen at any moment, and the far layers are dim — which is priced into the shipped presets’ size and brightness.

The swarm’s mark is no longer only a round blob: shape and points give it a silhouette — see Shaped marks, which covers this scene and the emitter together.