@codincod/ornament 0.0.0-stage → 0.2.0

package/src/flow_field.ts

@@ -0,0 +1,491 @@
+/**
+ * Light cycles driven by a Perlin field.
+ *
+ * The simulation behind the Trace world page's background, kept free of the DOM
+ * so the drawing half stays a drawing half and this stays readable on its own.
+ *
+ * The idea in one line: sample Perlin noise for a direction, then throw away
+ * everything about that direction except which of the four cardinals it is
+ * closest to. A smooth field read through a four-way quantiser stops looking
+ * like the usual particle-flow wallpaper and starts looking like light cycles,
+ * because the riders can only ever turn ninety degrees, and because a field
+ * that varies smoothly makes neighbouring riders agree for a while and then
+ * peel apart. That is the whole ornament: Perlin's noise drawn with Trace's
+ * geometry.
+ *
+ * Two of the rules are borrowed from the real world in `codin-cod-worlds/trace`, not
+ * invented here, because the ornament should not contradict the game it sits
+ * in front of. A trail holds a bounded number of cells and the oldest expires
+ * (`DESIGN.md`, "the trail is finite"), and a rider may not reverse into its
+ * own neck. What is *not* borrowed is rider-on-rider collision: these riders
+ * pass through each other, because a background that empties itself is worse
+ * scenery than one that does not.
+ *
+ * They do collide with a wall the reader draws. Dragging the pointer lays a
+ * line across the field and a rider that reaches it dies there and respawns
+ * somewhere else, which is the one thing on this canvas anybody can actually
+ * do. Riders do not steer around it: a wall you have to watch them dodge is a
+ * wall that does nothing, and the whole appeal is that the line you drew is the
+ * thing that stopped them. The wall expires on its own (`WALL_LIFE`) so the
+ * field always comes back, and drawing suppresses the pointer's usual shove,
+ * since riders fleeing the cursor would never reach the line under it.
+ *
+ * The edge is a wall, and that is load-bearing rather than cosmetic. The first
+ * version wrapped riders around to the far side, which is cheaper and looks
+ * fine on paper. In practice a rider that left through an edge arrived in a
+ * part of the field that was also pointing outward, so it left again on the
+ * very next tick, and since a wrapped trail has to be cut (or it draws one
+ * straight line across the whole canvas) those riders spent their lives as a
+ * single flickering dot in a corner. Turning them along the wall instead keeps
+ * every trail whole and costs nothing.
+ */
+
+import { makeNoise2, makeRandom, type Noise2 } from "./perlin"
+
+export interface Cell {
+  readonly x: number
+  readonly y: number
+}
+
+export interface Rider {
+  cell: Cell
+  direction: Cell
+  /** Which `rider-N` colour this one wears, so it matches the real board. */
+  readonly slot: number
+  /** Oldest cell first, current cell last. */
+  readonly trail: Cell[]
+}
+
+/** A drawn wall cell, or the mark a rider left dying on one. */
+export interface Fading {
+  readonly cell: Cell
+  /** 1 when new, falling to 0 as it expires. What the painter fades on. */
+  readonly life: number
+}
+
+export interface Field {
+  /**
+   * Lay wall along the segment between two cells, or on one cell if `from` is
+   * null. Takes a segment rather than a cell because a pointer moving quickly
+   * reports positions cells apart, and a wall with holes in it is a wall
+   * riders slip through.
+   */
+  draw(from: Cell | null, to: Cell): void
+  /**
+   * Re-fit to a resized grid, keeping the riders that still fit on it. When
+   * `riders` is given and differs, the field grows or thins to that count, so a
+   * phone turned landscape or a window dragged wide is not left with a
+   * desktop's crowd on a postcard or a postcard's handful on a desktop.
+   */
+  resize(cols: number, rows: number, riders?: number): void
+  readonly riders: readonly Rider[]
+  /** Where riders have just died, for painting. */
+  readonly sparks: readonly Fading[]
+  /** Advance one tick. `pointer` is in cell coordinates, or null if absent. */
+  step(pointer: Cell | null): void
+  /** The wall, for painting. */
+  readonly walls: readonly Fading[]
+}
+
+export interface FieldOptions {
+  cols: number
+  riders: number
+  rows: number
+  seed: number
+  /** Cells a trail keeps before the oldest expires. */
+  trail: number
+}
+
+/** A floor so a sliver of a window never empties the field completely. */
+const MIN_FIELD_RIDERS = 1
+
+const CARDINALS: readonly Cell[] = [
+  { x: 1, y: 0 },
+  { x: 0, y: 1 },
+  { x: -1, y: 0 },
+  { x: 0, y: -1 },
+]
+
+/**
+ * How far apart two cells have to be before the field gives them unrelated
+ * directions. Smaller means longer straights and lazier sweeps; larger turns
+ * the whole thing into confetti. This is the number to reach for first if the
+ * ornament ever needs retuning.
+ */
+const FIELD_SCALE = 0.055
+
+/**
+ * How far apart the two samples that make up a flow vector are taken.
+ *
+ * The field's direction is built from two noise reads rather than by turning
+ * one read into an angle, and this is what keeps the second read from simply
+ * echoing the first. Any large non-integer offset does; it stays under the
+ * noise's 256-unit repeat so the two samples land in genuinely different parts
+ * of the same field.
+ */
+const FIELD_OFFSET = 137.5
+
+/** How far the field slides per tick, so riders cannot settle into a loop. */
+const DRIFT = 0.004
+
+/**
+ * How much better than carrying straight on another direction has to look
+ * before a rider takes it.
+ *
+ * Without a margin the rider re-decides from scratch every tick and takes
+ * whatever is fractionally ahead. The field is smooth, but "which cardinal is
+ * closest" is not: it flips every time the flow crosses 45°, and because
+ * turning changes which axis the rider is sampling along, the flip feeds back
+ * on itself. Riders came out shimmering down diagonal staircases, turning
+ * every 1.7 cells.
+ *
+ * Deliberately above 1, which is the largest dot product a unit flow vector
+ * can offer. That makes the rule "drive on until the field actively disagrees"
+ * rather than "take the best option each tick". The pointer can still overrule
+ * it, because `POINTER_PUSH` is larger again.
+ *
+ * 1.1 was not enough, and the margin turns out to have a cliff in it. A rider
+ * only reverses its opinion when the flow has swung round behind it, and in
+ * that regime the straight-on score has already been dragged near zero by its
+ * own negative dot product, so the margin is no longer protecting anything and
+ * the choice goes back to being decided by which side of 45° the flow fell.
+ * Riders turned every 4.4 cells rather than the 8 this comment used to claim,
+ * and a 22-cell trail folded into a knot: measured over 3000 ticks, 41% of
+ * trails crossed themselves and 28% fitted inside six cells square, which is
+ * what reads as a rider stuck in a box.
+ *
+ * At 1.4 both go to roughly zero (1% and 0.1%) and the run length lands at 15
+ * cells, one or two corners in a trail. The cliff is sharp on both sides: 1.3
+ * still knots 7% of trails, and by 1.5 the field cannot turn a rider at all
+ * and every one of them ends up orbiting the frame.
+ */
+const TURN_MARGIN = 1.4
+
+/** Cells from the pointer at which its influence has fallen to nothing. */
+const POINTER_REACH = 9
+
+/**
+ * How far from a wall the wall starts pushing back, and how hard.
+ *
+ * Turning riders along the edge rather than wrapping them keeps their trails
+ * whole, but it has a second-order cost: the turn leaves a rider travelling
+ * parallel to the wall one cell from it, `TURN_MARGIN` then commits it to that
+ * heading, and the flow that drove it into the wall is still pointing outward
+ * where it now stands. So it runs the whole length of the frame. Riders spent
+ * a third of their time on literal edge cells, against the 7% you would get by
+ * scattering them at random, and the ornament grew a bright border.
+ *
+ * A soft shove inward, shaped exactly like the pointer's and summed into the
+ * same vector, fixes it without a special case in the steering: the wall is
+ * just another thing the flow has an opinion about. Below the field's own unit
+ * strength, so it biases rather than dictates, and it takes edge dwelling to
+ * 13%. Deliberately below `POINTER_PUSH`, so a pointer can still hold a rider
+ * against a wall if someone wants to.
+ *
+ * The reach is clamped to a third of each axis so that on a narrow phone the
+ * two opposing walls do not squeeze every rider into a single lane; where they
+ * do overlap they cancel, which leaves the middle of the grid alone.
+ */
+const WALL_REACH = 8
+
+const WALL_PUSH = 0.9
+
+/**
+ * Ticks a drawn wall cell survives. About eight seconds at the ornament's tick,
+ * which is long enough to catch riders that were nowhere near when the line was
+ * drawn, and short enough that a reader who scribbled over the whole viewport
+ * gets their field back without having to reload the page.
+ */
+const WALL_LIFE = 60
+
+/** Ticks the mark at a kill survives. Long enough to be read as a death. */
+const SPARK_LIFE = 9
+
+/**
+ * The soft field that keeps riders off each other, and how far it reaches.
+ *
+ * One smooth field steering everything is the whole idea, and the cost of the
+ * idea is that riders who find each other agree from then on: they sample
+ * almost the same noise, so they make the same decision, and nothing pushed
+ * them apart because they pass through each other. Committing riders to longer
+ * runs made it worse, since two that align then stay aligned. Measured, riders
+ * sat 3.3 cells from their nearest neighbour where random scattering gives 7.5,
+ * and 62% of ticks a rider was within two cells of another on the same heading,
+ * which is two riders drawn on top of each other reading as one.
+ *
+ * So riders repel each other, summed into the same vector as the walls and the
+ * pointer rather than as a special case. The point is a force field, not a grid:
+ * a `smoothstep` falloff that barely registers at arm's length and firms up only
+ * as two riders close, so they glide apart instead of snapping to a spacing. Held
+ * gently on purpose. A hard push held the pair-up near zero, which looked like
+ * riders obeying a lattice; this leaves it near 4%, so they still drift together
+ * now and then and part again, which is what a field does and a rule does not.
+ *
+ * Weaker than `WALL_PUSH`, which is weaker than `POINTER_PUSH`: a rider yields
+ * to the edge of the screen, and both yield to the reader.
+ */
+const SWARM_REACH = 6
+
+const SWARM_PUSH = 0.5
+
+/**
+ * How hard the pointer shoves, relative to the field's unit-length vector.
+ * Above the field's own strength on purpose: at the pointer's centre the shove
+ * has to be able to overrule the field outright, or riders drive through it
+ * and the interaction reads as a coincidence rather than a response.
+ */
+const POINTER_PUSH = 2.6
+
+export function createField(options: FieldOptions): Field {
+  const noise = makeNoise2(options.seed)
+  const random = makeRandom(options.seed ^ 0x5f3d)
+
+  let cols = Math.max(1, options.cols)
+  let rows = Math.max(1, options.rows)
+  let drift = 0
+
+  const riders: Rider[] = Array.from({ length: options.riders }, (_, index) =>
+    spawnRider(index, random, cols, rows),
+  )
+
+  const walls = new Map<string, number>()
+  const sparks = new Map<string, number>()
+
+  const fade = (entries: Map<string, number>, span: number): Fading[] =>
+    Array.from(entries, ([at, left]) => ({ cell: unkey(at), life: left / span }))
+
+  return {
+    draw(from, to) {
+      const target = clamp(round(to), cols, rows)
+      const start = from ? clamp(round(from), cols, rows) : target
+      const span = Math.max(Math.abs(target.x - start.x), Math.abs(target.y - start.y))
+
+      for (let i = 0; i <= span; i++) {
+        const at = span === 0 ? target : lerp(start, target, i / span)
+        walls.set(key(at), WALL_LIFE)
+      }
+    },
+
+    resize(nextCols, nextRows, nextRiders) {
+      cols = Math.max(1, nextCols)
+      rows = Math.max(1, nextRows)
+
+      if (nextRiders != null) {
+        while (riders.length > nextRiders && riders.length > MIN_FIELD_RIDERS) riders.pop()
+        while (riders.length < nextRiders) {
+          riders.push(spawnRider(riders.length, random, cols, rows))
+        }
+      }
+
+      for (const rider of riders) {
+        if (rider.cell.x < cols && rider.cell.y < rows) continue
+        rider.cell = clamp(rider.cell, cols, rows)
+        rider.trail.length = 0
+        rider.trail.push(rider.cell)
+      }
+    },
+    riders,
+
+    get sparks() {
+      return fade(sparks, SPARK_LIFE)
+    },
+
+    step(pointer) {
+      drift += DRIFT
+      expire(walls)
+      expire(sparks)
+
+      for (const rider of riders) {
+        rider.direction = steer(noise, rider, riders, drift, pointer, cols, rows)
+        const next = {
+          x: rider.cell.x + rider.direction.x,
+          y: rider.cell.y + rider.direction.y,
+        }
+
+        if (walls.has(key(next))) {
+          sparks.set(key(next), SPARK_LIFE)
+          respawn(rider, random, cols, rows, walls)
+          continue
+        }
+
+        rider.cell = next
+        rider.trail.push(rider.cell)
+        if (rider.trail.length > options.trail) rider.trail.shift()
+      }
+    },
+
+    get walls() {
+      return fade(walls, WALL_LIFE)
+    },
+  }
+}
+
+/**
+ * The field's direction at the rider, as one of the four cardinals.
+ *
+ * Three things narrow the choice, in order. Only cells on the grid are
+ * candidates, so the edge is a wall a rider turns along rather than something
+ * it drives through, and the wall leans on the flow as it gets close so that
+ * turning along it is not the same as sticking to it. Reversing is rejected
+ * the way the real world rejects it,
+ * unless a rider has driven into a corner and reversing is the only move left,
+ * because the alternative is a rider frozen against a wall forever. And
+ * carrying straight on gets a bonus, which is the hysteresis that makes a
+ * light cycle commit to a run instead of shimmering along a diagonal.
+ */
+function steer(
+  noise: Noise2,
+  rider: Rider,
+  riders: readonly Rider[],
+  drift: number,
+  pointer: Cell | null,
+  cols: number,
+  rows: number,
+): Cell {
+  const nx = rider.cell.x * FIELD_SCALE + drift * 0.3
+  const ny = rider.cell.y * FIELD_SCALE + drift
+
+  let flowX = noise(nx, ny)
+  let flowY = noise(nx + FIELD_OFFSET, ny + FIELD_OFFSET)
+  const length = Math.hypot(flowX, flowY) || 1
+  flowX /= length
+  flowY /= length
+
+  const wallX = Math.min(WALL_REACH, Math.floor(cols / 3))
+  const wallY = Math.min(WALL_REACH, Math.floor(rows / 3))
+  flowX += wall(rider.cell.x, wallX) - wall(cols - 1 - rider.cell.x, wallX)
+  flowY += wall(rider.cell.y, wallY) - wall(rows - 1 - rider.cell.y, wallY)
+
+  for (const other of riders) {
+    if (other === rider) continue
+    const awayX = rider.cell.x - other.cell.x
+    const awayY = rider.cell.y - other.cell.y
+    const distance = Math.hypot(awayX, awayY)
+    if (distance >= SWARM_REACH) continue
+
+    const t = 1 - distance / SWARM_REACH
+    const strength = t * t * (3 - 2 * t) * SWARM_PUSH
+    const spread = Math.max(distance, 0.5)
+    flowX += (awayX / spread) * strength
+    flowY += (awayY / spread) * strength
+  }
+
+  if (pointer) {
+    const awayX = rider.cell.x - pointer.x
+    const awayY = rider.cell.y - pointer.y
+    const distance = Math.hypot(awayX, awayY)
+
+    if (distance < POINTER_REACH) {
+      const strength = ((POINTER_REACH - distance) / POINTER_REACH) * POINTER_PUSH
+      const spread = Math.max(distance, 0.5)
+      flowX += (awayX / spread) * strength
+      flowY += (awayY / spread) * strength
+    }
+  }
+
+  const onGrid = CARDINALS.filter((candidate) => {
+    const x = rider.cell.x + candidate.x
+    const y = rider.cell.y + candidate.y
+    return x >= 0 && x < cols && y >= 0 && y < rows
+  })
+
+  const forward = onGrid.filter(
+    (candidate) => !(candidate.x === -rider.direction.x && candidate.y === -rider.direction.y),
+  )
+  const pool = forward.length > 0 ? forward : onGrid
+
+  let best: Cell | null = null
+  let bestDot = -Infinity
+
+  for (const candidate of pool) {
+    const straight = candidate.x === rider.direction.x && candidate.y === rider.direction.y
+    const dot = candidate.x * flowX + candidate.y * flowY + (straight ? TURN_MARGIN : 0)
+    if (dot > bestDot) {
+      bestDot = dot
+      best = candidate
+    }
+  }
+
+  return best ?? rider.direction
+}
+
+/**
+ * Riders are placed from the seeded PRNG, so their starting positions are as
+ * fixed as the field they drive through and the page opens the same way every
+ * time. Not from a second noise field, which was the first attempt: noise
+ * values cluster around zero, and twelve riders placed that way all start in a
+ * knot in the middle of the screen with most of it left empty.
+ */
+function spawnRider(index: number, random: () => number, cols: number, rows: number): Rider {
+  const cell = { x: Math.floor(random() * cols), y: Math.floor(random() * rows) }
+
+  return {
+    cell,
+    direction: CARDINALS[index % CARDINALS.length]!,
+    slot: index % 10,
+    trail: [cell],
+  }
+}
+
+const key = (cell: Cell): string => `${cell.x},${cell.y}`
+
+function unkey(at: string): Cell {
+  const [x, y] = at.split(",")
+  return { x: Number(x), y: Number(y) }
+}
+
+const round = (cell: Cell): Cell => ({ x: Math.round(cell.x), y: Math.round(cell.y) })
+
+const lerp = (from: Cell, to: Cell, t: number): Cell => ({
+  x: Math.round(from.x + (to.x - from.x) * t),
+  y: Math.round(from.y + (to.y - from.y) * t),
+})
+
+function expire(entries: Map<string, number>): void {
+  for (const [at, left] of entries) {
+    if (left <= 1) entries.delete(at)
+    else entries.set(at, left - 1)
+  }
+}
+
+/**
+ * Put a killed rider back somewhere else, trail and all.
+ *
+ * It keeps its slot, so the colours on screen stay the same set rather than
+ * churning every time somebody draws a line. The retries are to avoid dropping
+ * it straight back onto the wall that just killed it; if a reader has covered
+ * the whole viewport there may be nowhere clean left, in which case it spawns
+ * anyway and dies again next tick, which is a fair thing to happen to someone
+ * who scribbled over the whole viewport.
+ */
+function respawn(
+  rider: Rider,
+  random: () => number,
+  cols: number,
+  rows: number,
+  walls: Map<string, number>,
+): void {
+  let cell = { x: 0, y: 0 }
+  for (let attempt = 0; attempt < 8; attempt++) {
+    cell = { x: Math.floor(random() * cols), y: Math.floor(random() * rows) }
+    if (!walls.has(key(cell))) break
+  }
+
+  rider.cell = cell
+  rider.direction = CARDINALS[Math.floor(random() * CARDINALS.length)] ?? CARDINALS[0]!
+  rider.trail.length = 0
+  rider.trail.push(cell)
+}
+
+/** One wall's inward shove on a rider `distance` cells away from it. */
+function wall(distance: number, reach: number): number {
+  if (reach <= 0 || distance >= reach) return 0
+  return ((reach - distance) / reach) * WALL_PUSH
+}
+
+function clamp(cell: Cell, cols: number, rows: number): Cell {
+  return {
+    x: Math.min(Math.max(cell.x, 0), cols - 1),
+    y: Math.min(Math.max(cell.y, 0), rows - 1),
+  }
+}