feat(render): magnetization coherence for the tunnel particles

Stage 2 of the magnetic particle substrate.

- displace() gains a curl-noise flow-field term scaled by a single
  uCoherence uniform: at 0 the particles sit crisply on the lattice, at 1
  they drift together into clumps and filaments (neighbours share the
  field, so they magnetize coherently with no N-body cost).
- coherence.ts drives uCoherence: a slow ~11s breathing oscillator plus a
  boost kick, damped toward 0 as the nearest obstacle closes in so danger
  and the white path stay crisp when it matters.
- Per-surface by scoping: only the tunnel point skin reads coherence, so
  the ship (and cubes) never magnetize — the ship stays the one crisp
  anchor amid the shimmer.

5 new unit tests (range, breathing swing, boost monotonicity, danger
damping, out-of-range ignore). Full suite 61 green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: crs48

docs/explorations/0003_[_]_MAGNETIC_PARTICLE_SUBSTRATE.md

@@ -354,9 +354,9 @@ Stage 1 — ripples:
 
 Stage 2 — magnetization:
 
-- [ ] `uCoherence` uniform; lattice↔curl-flow blend in `displace()`.
-- [ ] Slow oscillator + boost kick + telegraph damping to drive `uCoherence`.
-- [ ] Optional per-surface coherence (ship stays crisp).
+- [x] `uCoherence` uniform; lattice↔curl-flow blend in `displace()`.
+- [x] Slow oscillator + boost kick + telegraph damping to drive `uCoherence`.
+- [x] Optional per-surface coherence (ship stays crisp).
 
 Stage 3 — glow (optional, gated):
 

src/main.ts

@@ -6,8 +6,9 @@ import { createRunState, updateRun, type RunState } from "./game/run";
 import { readHighScore, scoreFromDistance } from "./game/scoring";
 import { findSection } from "./game/world";
 import { createInputController } from "./input/controller";
-import { TELEGRAPH_FAR_CELLS } from "./tube/space";
+import { CELL_DEPTH, TELEGRAPH_FAR_CELLS } from "./tube/space";
 import { updateCameraRig } from "./render/camera";
+import { magnetizationCoherence } from "./render/particles/coherence";
 import { createDebugOverlay, updateDebugOverlay } from "./render/debugOverlay";
 import { createHud, updateHud } from "./render/hud";
 import { updateObstacleView } from "./render/obstacles";
@@ -83,6 +84,15 @@ const renderFrame = (state: RunState, dtSeconds: number): void => {
   const player = state.game.player;
   const section = findSection(state.world, player.distance);
   const speedFactor = BOOST_MULTIPLIERS[player.boostLevel];
+  const guidance = guidanceAhead(state.world, player.distance, state.collectedBoosts);
+  const coherence = magnetizationCoherence({
+    timeSeconds: elapsedSeconds,
+    boostLevel: player.boostLevel,
+    obstacleDistance:
+      guidance.obstacle === undefined
+        ? Number.POSITIVE_INFINITY
+        : guidance.obstacle.cell * CELL_DEPTH - player.distance,
+  });
 
   updateTubeView(
     renderScene.tube,
@@ -122,6 +132,7 @@ const renderFrame = (state: RunState, dtSeconds: number): void => {
     timeSeconds: elapsedSeconds,
     pixelRatio: renderScene.renderer.getPixelRatio(),
     impacts: state.impacts,
+    coherence,
   });
   renderScene.renderer.render(renderScene.scene, renderScene.cameraRig.camera);
   updateDebugOverlay(

src/render/particles/coherence.ts

@@ -0,0 +1,39 @@
+// Magnetization coherence: a single scalar in [0, 1] that blends the tunnel
+// particles between *lattice* (0 — crisp, sitting on their anchors) and
+// *magnetized* (1 — drifting along a shared curl-noise flow field into clumps
+// and filaments). Because it is one number, "sometimes magnetized to each
+// other" costs almost nothing and stays fully art-directable.
+//
+// Only the tunnel point skin reads coherence, so the ship and cubes never
+// magnetize — per-surface coherence by scoping, and the ship stays the one
+// crisp "you" amid the shimmer.
+
+import { MAX_BOOST_LEVEL } from "../../game/config";
+
+// Magnetism breathes in and out over this period, so it comes and goes rather
+// than sitting on.
+const COHERENCE_PERIOD_SECONDS = 11;
+const BREATHE_PEAK = 0.5;
+const BOOST_KICK = 0.35;
+// A cube within this many world units damps magnetization toward 0 so the
+// danger — and the white safe path — reads crisp when it matters most.
+const DANGER_RANGE = 22;
+
+const clamp01 = (value: number): number => Math.max(0, Math.min(1, value));
+
+export type CoherenceInputs = {
+  readonly timeSeconds: number;
+  readonly boostLevel: number;
+  // Distance to the nearest obstacle ahead in world units; Infinity if none.
+  readonly obstacleDistance: number;
+};
+
+export const magnetizationCoherence = (inputs: CoherenceInputs): number => {
+  const phase = (inputs.timeSeconds * 2 * Math.PI) / COHERENCE_PERIOD_SECONDS;
+  const breathe = BREATHE_PEAK * (0.5 + 0.5 * Math.sin(phase));
+  const boostKick = BOOST_KICK * clamp01(inputs.boostLevel / MAX_BOOST_LEVEL);
+  const raw = breathe + boostKick;
+
+  const danger = clamp01(1 - inputs.obstacleDistance / DANGER_RANGE);
+  return clamp01(raw * (1 - danger));
+};

src/render/particles/displacement.glsl.ts

@@ -103,6 +103,11 @@ uniform float uImpactSpeed;
 uniform float uImpactFalloff;
 uniform float uImpactLifetime;
 uniform vec4 uImpacts[${String(MAX_IMPACTS)}];
+
+uniform float uCoherence;
+uniform float uMagAmplitude;
+uniform float uMagFrequency;
+uniform float uMagDrift;
 `;
 
 // displace: nudge a world-space (camera-relative) anchor by the sum of every
@@ -150,6 +155,12 @@ vec3 displace(vec3 anchor, vec3 inward, float sTube, float thetaTube, float seed
 
   float radial = wv_wakeRadial(sTube, thetaTube) + wv_impactRadial(sTube, thetaTube);
   pos += inward * radial;
+
+  // Magnetization: neighbouring particles share this curl-noise flow field, so
+  // they drift into clumps and filaments together. uCoherence scales it in and
+  // out; at 0 the particles sit crisply on the lattice.
+  vec3 flow = curlNoise(anchor * uMagFrequency + vec3(uTime * uMagDrift));
+  pos += flow * uMagAmplitude * uCoherence;
   return pos;
 }
 `;

src/render/particles/system.ts

@@ -11,6 +11,7 @@ import {
   createParticleUniforms,
   setImpactUniforms,
   setParticleBend,
+  setParticleCoherence,
   setParticleShip,
   updateParticleUniforms,
   type ParticleUniforms,
@@ -37,6 +38,7 @@ export type ParticleUpdate = {
   readonly timeSeconds: number;
   readonly pixelRatio: number;
   readonly impacts: readonly RippleImpact[];
+  readonly coherence: number;
 };
 
 export const updateParticleSystem = (
@@ -59,4 +61,5 @@ export const updateParticleSystem = (
     speed: update.speedFactor,
   });
   setImpactUniforms(system.uniforms, update.impacts);
+  setParticleCoherence(system.uniforms, update.coherence);
 };

src/render/particles/uniforms.ts

@@ -33,6 +33,9 @@ const POINT_SIZE = 46;
 const PARTICLE_COLOR = new Color(0.04, 0.04, 0.05);
 const PARTICLE_OPACITY = 0.55;
 const WAKE_AMPLITUDE = 0.35;
+const MAG_AMPLITUDE = 0.55;
+const MAG_FREQUENCY = 0.15;
+const MAG_DRIFT = 0.2;
 
 type FloatUniform = { value: number };
 type FloatArrayUniform = { value: number[] };
@@ -62,6 +65,10 @@ export type ParticleUniforms = {
   readonly uImpactFalloff: FloatUniform;
   readonly uImpactLifetime: FloatUniform;
   readonly uImpacts: { value: Float32Array };
+  readonly uCoherence: FloatUniform;
+  readonly uMagAmplitude: FloatUniform;
+  readonly uMagFrequency: FloatUniform;
+  readonly uMagDrift: FloatUniform;
   readonly uPointSize: FloatUniform;
   readonly uPixelRatio: FloatUniform;
   readonly uColor: { value: Color };
@@ -98,6 +105,10 @@ export const createParticleUniforms = (
     uImpactFalloff: { value: IMPACT_FALLOFF },
     uImpactLifetime: { value: IMPACT_LIFETIME_SECONDS },
     uImpacts: { value: new Float32Array(MAX_IMPACTS * 4) },
+    uCoherence: { value: 0 },
+    uMagAmplitude: { value: MAG_AMPLITUDE },
+    uMagFrequency: { value: MAG_FREQUENCY },
+    uMagDrift: { value: MAG_DRIFT },
     uPointSize: { value: POINT_SIZE },
     uPixelRatio: { value: pixelRatio },
     uColor: { value: PARTICLE_COLOR.clone() },
@@ -160,6 +171,14 @@ export const setParticleShip = (
   uniforms.uShipSpeed.value = ship.speed;
 };
 
+// How magnetized the tunnel particles are right now, in [0, 1].
+export const setParticleCoherence = (
+  uniforms: ParticleUniforms,
+  coherence: number,
+): void => {
+  uniforms.uCoherence.value = coherence;
+};
+
 // Pack the live ripple ring buffer into the vec4[] uniform. Unused slots carry
 // strength 0, which the shader skips.
 export const setImpactUniforms = (

test/render/particles/coherence.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+
+import { magnetizationCoherence } from "../../../src/render/particles/coherence";
+
+const FAR = Number.POSITIVE_INFINITY;
+
+describe("magnetizationCoherence", () => {
+  it("always stays within [0, 1]", () => {
+    for (let t = 0; t < 60; t += 0.37) {
+      for (const boostLevel of [0, 1, 2, 3]) {
+        for (const obstacleDistance of [0, 5, 11, 22, 50, FAR]) {
+          const value = magnetizationCoherence({ timeSeconds: t, boostLevel, obstacleDistance });
+          expect(value).toBeGreaterThanOrEqual(0);
+          expect(value).toBeLessThanOrEqual(1);
+        }
+      }
+    }
+  });
+
+  it("breathes over time when nothing else is acting", () => {
+    const samples = Array.from({ length: 48 }, (_, index) =>
+      magnetizationCoherence({ timeSeconds: index * 0.25, boostLevel: 0, obstacleDistance: FAR }),
+    );
+    const min = Math.min(...samples);
+    const max = Math.max(...samples);
+    // A visible in-and-out swing, never a hard toggle.
+    expect(max - min).toBeGreaterThan(0.3);
+    expect(min).toBeGreaterThanOrEqual(0);
+  });
+
+  it("rises with boost level", () => {
+    const none = magnetizationCoherence({ timeSeconds: 0, boostLevel: 0, obstacleDistance: FAR });
+    const some = magnetizationCoherence({ timeSeconds: 0, boostLevel: 1, obstacleDistance: FAR });
+    const full = magnetizationCoherence({ timeSeconds: 0, boostLevel: 3, obstacleDistance: FAR });
+
+    expect(some).toBeGreaterThan(none);
+    expect(full).toBeGreaterThan(some);
+  });
+
+  it("is damped toward zero as danger closes in, so danger reads crisp", () => {
+    const inputs = { timeSeconds: 0, boostLevel: 3 } as const;
+    const far = magnetizationCoherence({ ...inputs, obstacleDistance: FAR });
+    const near = magnetizationCoherence({ ...inputs, obstacleDistance: 11 });
+    const onTop = magnetizationCoherence({ ...inputs, obstacleDistance: 0 });
+
+    expect(near).toBeLessThan(far);
+    expect(onTop).toBe(0);
+  });
+
+  it("ignores obstacles beyond the danger range", () => {
+    const far = magnetizationCoherence({ timeSeconds: 3, boostLevel: 2, obstacleDistance: FAR });
+    const justOutside = magnetizationCoherence({ timeSeconds: 3, boostLevel: 2, obstacleDistance: 40 });
+    expect(justOutside).toBeCloseTo(far, 10);
+  });
+});