@codincod/ornament 0.0.0-stage → 0.2.0

package/src/swarm.ts

@@ -0,0 +1,587 @@
+/**
+ * A flock of thousands, once in a while.
+ *
+ * Kept free of the DOM the way the rest of the ornament is. It is not a shoal
+ * and it is not a second `shoal.ts`: the fish in that file are steered one at a
+ * time and each of them has an opinion, which is what makes a dozen of them
+ * read as animals. Do that to a thousand and two things happen, both bad. It
+ * costs a thousand times as much, and it looks wrong, because a bait ball is
+ * not a thousand fish deciding. It is one thing with a thousand fish in it.
+ *
+ * ## What the eye is actually reading
+ *
+ * Not the fish. At the size a fish in a flock is drawn, nobody can follow one,
+ * and anybody watching one of these is reading three things instead:
+ *
+ *   * **The shape.** A ball, a ceiling, a ribbon. It is the shape that says how
+ *     many there are, and it is the shape that turns.
+ *   * **The grain.** Fish at slightly different distances, so the mass has a
+ *     front and a back rather than being a stipple. This is most of why marks
+ *     that could be counted read as thousands: the eye gives up counting the
+ *     moment they stop lying on one plane.
+ *   * **What happens when something goes through it.** A flock opens and closes
+ *     again. That is the whole reason a flock is worth having in a scene that
+ *     already has fish in it.
+ *
+ * So a fish here has no opinions at all. It has a place in the flock's own
+ * frame, it holds it, and everything it appears to decide is the flock turning
+ * or something pushing it aside. `HOMED` is what brings it back.
+ *
+ * ## How many marks the mass is made of
+ *
+ * As many as it takes to read as packed, which is more than it used to be. The
+ * count was a few hundred while the reason for it was the frame: a renderer
+ * draws one mark per fish, and a desktop background does not get to spend a
+ * frame on scenery. Timed in the wgpu renderer, three thousand specks cost
+ * about a millisecond of a twenty-three millisecond frame, so the frame was
+ * never the thing holding the number down, and a few hundred marks spread over
+ * a mass tens of metres across is not a flock. It is a sprinkle with a shape.
+ *
+ * So the count follows from the mass instead. Each shape says how tightly it
+ * packs and how big it is, and how many fish are in it falls out of the two,
+ * which is why a ceiling is thousands of marks and a ball is a fraction of
+ * that while being the denser of the two. The pool a renderer hands over is
+ * still a ceiling on all of it.
+ *
+ * ## Why a speck does not hold its drawing
+ *
+ * Everything else in this water that costs a renderer real money holds its last
+ * drawing until it has moved far enough to be worth another one, and the flock
+ * is the layer where that buys nothing. Nearly every speck travels past a
+ * quarter of a pixel between frames, and most of them past a whole one, and a
+ * whole pixel on a mark a few px long is a mark the eye can watch stepping. A
+ * flock is the one thing down here that never stops, which is the whole of what
+ * it is for.
+ *
+ * So what a speck wants is not fewer frames of itself. It is fewer of itself in
+ * the murk, where nobody could make one out anyway, and that is a different
+ * change from this one.
+ * `docs/decisions/0027-let-an-element-decide-when-its-drawing-is-stale.md` is
+ * the contract this is the exception to, and the exception is written here so
+ * that reading it costs less than measuring it again.
+ *
+ * ## Rarer than anything that swims and commoner than a boat
+ *
+ * It sits between the two clocks the ornament already keeps. `visitors.ts` is
+ * minutes and `passers.ts` is days, and this is a long stretch of minutes: often
+ * enough that somebody who keeps a desktop uncovered will meet one, seldom
+ * enough that it is the thing they mention.
+ */
+
+import type { Biome } from "./biome.ts"
+import { makeNoise2, makeRandom } from "./perlin.ts"
+import type { Startle } from "./shoal.ts"
+
+export type SwarmShape = "ball" | "ceiling" | "ribbon"
+
+/** One fish of a flock, which is a mark rather than an animal. */
+export interface Speck {
+  /** 0 is as far off as this water goes, 1 is up against the glass. */
+  depth: number
+  /** How long it is drawn, in px, with the distance already in it. */
+  size: number
+  /** Which way it is pointing, in radians. It is going that way. */
+  tilt: number
+  x: number
+  y: number
+}
+
+export interface Swarm {
+  resize(width: number, height: number, count?: number): void
+  /** What the flock is at the moment, for a renderer that wants to know. */
+  readonly shape: SwarmShape
+  readonly specks: readonly Speck[]
+  /**
+   * Advance by `seconds`. `startle` is whatever is going through the flock,
+   * which is the only thing here that is not the flock's own business.
+   */
+  step(seconds: number, startle?: Startle | null): void
+  /** How loud the flock is now, 0 to 1. Nothing at all while there is none. */
+  readonly weight: number
+}
+
+export interface SwarmOptions {
+  /** How many fish. A renderer's ceiling, not a count of anything real. */
+  count: number
+  /** Come round one after another with no rest. For previews and for tests. */
+  eager?: boolean
+  height: number
+  seed: number
+  shapes?: readonly SwarmShape[]
+  /**
+   * The water this is in, so that whatever lives down there can see it.
+   *
+   * A flock enters as one thing rather than as several hundred, which is how it
+   * is seen. What passes over a crab is a shadow the width of the whole ball;
+   * offered a fish at a time it would be hundreds of animals none of them
+   * bigger than the crab itself, and nothing on the floor would look up.
+   */
+  water?: Biome
+  width: number
+}
+
+/**
+ * How each shape is laid out, and where it sits in the column.
+ *
+ * `wide` and `tall` are the flock's own radii as shares of the box's width, and
+ * `thick` is the same measure into the screen, which is what gives the mass a
+ * front and a back. A ball is nearly as deep as it is wide because it is a
+ * ball; a ceiling is broad, shallow and deep, because what it is is the
+ * underside of a shoal spread out over you.
+ *
+ * The ceiling is the one worth the trouble. A ball is a shape in the water with
+ * you and a ceiling is a shape you are under, which is the difference between
+ * watching a flock and being in one. It seats high and reaches past both edges
+ * of the picture on purpose: a ceiling with ends is a cloud.
+ */
+interface Layout {
+  /**
+   * How wide the mass really is, in metres.
+   *
+   * What every fish in it is drawn against, and the only place this scene says
+   * how big a flock is out loud. A ball is a room across, a ribbon is a street,
+   * and a ceiling is the far side of what anybody can see.
+   */
+  readonly across: number
+  /** How fast the whole mass turns over, in turns a second. */
+  readonly churn: number
+  /**
+   * How many fish stand over a square metre of the face this shape shows.
+   *
+   * A share of the pool was the wrong statement, because it made the mark
+   * count independent of `across`: widen a ceiling from a street to a horizon
+   * and the same marks were asked to cover it, so the mass thinned and nothing
+   * said so. This is the same fact `census.ts` keeps for the sea, told about
+   * one animal in one shape.
+   *
+   * It is a per-shape number rather than one number in metres, because how
+   * tightly fish pack is what separates these shapes. A ball is a knot they
+   * have tied against something hunting them and it is the densest thing in
+   * this water; a ceiling is the same animals with nothing after them, spread
+   * out over you, and it is loose. Packing a ceiling like a ball would be a
+   * ball the size of the sky.
+   */
+  readonly packed: number
+  /** Where in the column it sits, as shares of the height. */
+  readonly seatLeast: number
+  readonly seatSpan: number
+  /** How long it takes to cross, at least and up to that again. */
+  readonly takeLeast: number
+  readonly takeSpan: number
+  readonly tall: number
+  readonly thick: number
+  readonly wide: number
+}
+
+const LAYOUTS: Readonly<Record<SwarmShape, Layout>> = {
+  ball: {
+    across: 8,
+    churn: 0.05,
+    packed: 20,
+    seatLeast: 0.18,
+    seatSpan: 0.34,
+    takeLeast: 70,
+    takeSpan: 40,
+    tall: 0.11,
+    thick: 0.11,
+    wide: 0.12,
+  },
+  ceiling: {
+    across: 45,
+    churn: 0.015,
+    packed: 11,
+    seatLeast: 0.04,
+    seatSpan: 0.12,
+    takeLeast: 95,
+    takeSpan: 50,
+    tall: 0.1,
+    thick: 0.3,
+    wide: 0.75,
+  },
+  ribbon: {
+    across: 22,
+    churn: 0.03,
+    packed: 13,
+    seatLeast: 0.2,
+    seatSpan: 0.36,
+    takeLeast: 60,
+    takeSpan: 34,
+    tall: 0.05,
+    thick: 0.1,
+    wide: 0.36,
+  },
+}
+
+/** How far past each side the flock starts and finishes, as shares of width. */
+const OFFING = 0.55
+
+/** How much of a crossing is spent fading in, and the same again fading out. */
+const FADE = 0.12
+
+/**
+ * Watched seconds between one flock leaving and the next arriving.
+ *
+ * Longer than a visitor's rest by a good deal, and this is the number that
+ * decides whether the thing is an event or a feature of the water. Anything
+ * that comes round inside a sitting stops being thousands of fish and becomes
+ * the fish animation.
+ */
+const REST_LEAST = 420
+
+const REST_SPAN = 620
+
+/** How much of that rest the water waits before the first flock of a sitting. */
+const OPENING = 0.4
+
+/** How far back the flock as a whole swims, and how much of that is its depth. */
+const DEEP_LEAST = 0.3
+
+const DEEP_SPAN = 0.5
+
+const DEPTH_SIZE = 0.7
+
+/**
+ * How long one fish is, in metres, and how much longer or shorter than that
+ * any one of them may be.
+ *
+ * An anchovy, which is what a bait ball is made of. It is the one animal in
+ * this ornament that is not sized by `sizes.ts`, and the reason is worth
+ * writing down: everything else is a single body somewhere in the water, and a
+ * flock is a body made of bodies. The root that keeps a shark from swamping a
+ * reef fish would put a fish the size of your hand in a ball the size of a bus,
+ * which is a ball of about nine fish.
+ *
+ * So the flock is the yardstick instead. A fish is drawn at its own length
+ * against the mass it is in, which is honest for the same reason a clownfish is
+ * measured against its anemone in `nemos.ts`: the two are at one distance, so
+ * nothing is being compressed between them.
+ */
+const FISH_LONG = 0.11
+
+const FISH_ODD = 0.22
+
+/**
+ * How far a fish wanders inside the flock, and how fast.
+ *
+ * Small, and it has to be. A fish that wanders far is a fish somebody can
+ * follow, and a mass whose parts can be followed is not a mass. What this is
+ * for is that a flock holding perfectly still inside itself reads as a pattern
+ * printed on a moving card.
+ */
+const FIDGET = 0.055
+
+const FIDGET_RATE = 0.55
+
+/** How many features of the fidget field fit across one flock. */
+const FIDGET_CELLS = 2.6
+
+/**
+ * How hard a flock is pushed by something coming through it, and how far the
+ * push reaches past what pushed it.
+ *
+ * A flock is the one thing in this water that answers a disturbance visibly,
+ * because it is the only thing with enough parts for the answer to have a
+ * shape: the hole a shark leaves is a picture of the shark.
+ *
+ * What it must not be is a rout. A real bait ball harried by something is torn
+ * to pieces, and it is a picture about being eaten; this water is not that. So
+ * the push is a dent that the mass closes over rather than a hole through it,
+ * which is what `HOMED` is doing on the other side of the same sum.
+ */
+const SHOVE = 0.85
+
+const SHOVE_REACH = 1
+
+/** How fast a pushed fish comes back to its place, per second. */
+const HOMED = 1.2
+
+/** How much of a flock has to have arrived before the water can see it. */
+const SEEN = 0.05
+
+/** How far a mark may be turned by what it is doing, at most. */
+const TILT_EASE = 3.5
+
+const MIN_SPAN = 1
+
+/**
+ * How many marks a shape is made of, off its own size and its own packing.
+ *
+ * The face it shows, in metres: `across` wide, and as tall as `tall` is against
+ * `wide`, since the two are shares of one number and their ratio is the shape's
+ * own. What is behind that face is not counted, which is why `packed` is a
+ * density on a face rather than through a volume: a ceiling is deeper than a
+ * ball and would come out the denser of the two, and it is the looser one.
+ */
+function marks(layout: Layout): number {
+  return Math.round(layout.packed * layout.across * layout.across * (layout.tall / layout.wide))
+}
+
+/**
+ * The flock of a piece of water.
+ *
+ * `eager` throws the rest away and brings one round after another, for the
+ * preview harness and for tests. Nothing should pass it in earnest.
+ */
+export function createSwarm(options: SwarmOptions): Swarm {
+  const random = makeRandom(options.seed ^ 0x5f0c)
+  const field = makeNoise2(options.seed ^ 0x1caa)
+  const shapes = options.shapes ?? (["ball", "ceiling", "ribbon"] as const)
+  const eager = options.eager ?? false
+
+  let width = Math.max(MIN_SPAN, options.width)
+  let height = Math.max(MIN_SPAN, options.height)
+  let count = Math.max(0, Math.round(options.count))
+
+  /**
+   * The pool, and the part of it this flock is using.
+   *
+   * `specks` holds the same objects rather than copies of them, so a renderer
+   * reading it and this file moving them are looking at one set of marks.
+   */
+  const pool: Speck[] = []
+
+  const specks: Speck[] = []
+
+  /** Where each one lives in the flock's own frame, and how it is pushed off it. */
+  const homes: {
+    /** How long this one is, before the distance is taken out of it. */
+    long: number
+    pushX: number
+    pushY: number
+    u: number
+    v: number
+    w: number
+  }[] = []
+
+  /** What is crossing: its shape, its course, and how far through it is. */
+  let shape: SwarmShape = "ball"
+  let along = 1
+  let deep = 1
+  let facing = 1
+  let seat = 0
+  let spin = 0
+  let take = 1
+  let weight = 0
+
+  /** Watched seconds still owed before the next flock arrives. */
+  let rest = (REST_LEAST + random() * REST_SPAN) * OPENING
+
+  /** The clock the fidget field is read against. */
+  let drift = 0
+
+  // The whole flock as one presence, measured off where its fish actually are
+  // rather than off where it was aimed. A ball that something has just gone
+  // through is wider than the ball that set off, and how wide it looks is the
+  // only thing anything reading this cares about.
+  options.water?.enter(() => {
+    const first = specks[0]
+    if (weight <= SEEN || !first) return []
+
+    let left = first.x
+    let right = left
+    let top = first.y
+    let bottom = top
+    let far = 0
+
+    for (const one of specks) {
+      if (one.x < left) left = one.x
+      if (one.x > right) right = one.x
+      if (one.y < top) top = one.y
+      if (one.y > bottom) bottom = one.y
+      far += one.depth
+    }
+
+    return [
+      {
+        depth: far / specks.length,
+        size: right - left,
+        x: (left + right) / 2,
+        y: (top + bottom) / 2,
+      },
+    ]
+  })
+
+  /**
+   * A place in the flock, drawn as a point of a solid rather than of a disc.
+   *
+   * The cube root is what makes it solid. Drawn straight off three rolls the
+   * points bunch in the middle and the mass has a hot core with a haze round
+   * it, which is a nebula. Taking the radius to the third root spreads them
+   * evenly through the volume, so the flock has a skin and the eye can find its
+   * edge, which is the thing it is reading the shape off.
+   */
+  function place(): { u: number; v: number; w: number } {
+    const u = random() * 2 - 1
+    const v = random() * 2 - 1
+    const w = random() * 2 - 1
+    const reach = Math.hypot(u, v, w) || 1
+    const full = random() ** (1 / 3)
+
+    return { u: (u / reach) * full, v: (v / reach) * full, w: (w / reach) * full }
+  }
+
+  function fill(): void {
+    pool.length = 0
+    specks.length = 0
+    homes.length = 0
+
+    for (let made = 0; made < count; made++) {
+      homes.push({
+        long: 1 - FISH_ODD + random() * FISH_ODD * 2,
+        pushX: 0,
+        pushY: 0,
+        ...place(),
+      })
+      pool.push({ depth: 1, size: 1, tilt: 0, x: 0, y: 0 })
+    }
+  }
+
+  function arrive(): void {
+    shape = shapes[Math.floor(random() * shapes.length)] ?? "ball"
+    const layout = LAYOUTS[shape]
+
+    along = 0
+    deep = DEEP_LEAST + random() * DEEP_SPAN
+    facing = random() < 0.5 ? -1 : 1
+    seat = height * (layout.seatLeast + random() * layout.seatSpan)
+    spin = random() * Math.PI * 2
+    take = layout.takeLeast + random() * layout.takeSpan
+    weight = 0
+
+    for (const home of homes) {
+      home.pushX = 0
+      home.pushY = 0
+    }
+
+    specks.length = 0
+    const using = Math.min(pool.length, marks(layout))
+    for (let at = 0; at < using; at++) {
+      const one = pool[at]
+      if (one) specks.push(one)
+    }
+  }
+
+  /**
+   * Move every fish to where the flock has it now.
+   *
+   * One pass, and everything a fish is doing is in it: its place in the mass,
+   * the mass turning, its own small fidget, and whatever is shoving it. There
+   * is nothing here that reads another fish, which is the whole reason a flock
+   * of this size is affordable at all.
+   */
+  function carry(dt: number, middle: number, startle: Startle | null): void {
+    const layout = LAYOUTS[shape]
+    const wide = width * layout.wide
+    const tall = width * layout.tall
+    const thick = layout.thick
+    // What one fish's length comes to, drawn: the mass is so many metres
+    // across and so many pixels across, and a fish is its own length of that.
+    const mark = ((wide * 2) / layout.across) * FISH_LONG
+    const cos = Math.cos(spin)
+    const sin = Math.sin(spin)
+    const fall = HOMED * dt
+
+    for (let at = 0; at < specks.length; at++) {
+      const home = homes[at]
+      const one = specks[at]
+      if (!home || !one) continue
+
+      // The mass turns about its own middle, which is what a bait ball does and
+      // the one motion that reads at this size. It is the same turn for every
+      // fish in it, so the shape is preserved and the parts are not.
+      const u = home.u * cos - home.w * sin
+      const w = home.u * sin + home.w * cos
+
+      const wobbleX = field(home.u * FIDGET_CELLS + drift, home.v * FIDGET_CELLS)
+      const wobbleY = field(home.v * FIDGET_CELLS, home.u * FIDGET_CELLS - drift)
+
+      const wantX = middle + (u + wobbleX * FIDGET) * wide
+      const wantY = seat + (home.v + wobbleY * FIDGET) * tall
+
+      if (startle && startle.force > 0) {
+        const offX = wantX + home.pushX - startle.x
+        const offY = wantY + home.pushY - startle.y
+        const gap = Math.hypot(offX, offY)
+        const reach = startle.reach * SHOVE_REACH
+
+        if (gap < reach && gap > 0) {
+          const push = ((reach - gap) / reach) * startle.force * SHOVE * dt * reach
+          home.pushX += (offX / gap) * push
+          home.pushY += (offY / gap) * push
+        }
+      }
+
+      home.pushX -= home.pushX * Math.min(1, fall)
+      home.pushY -= home.pushY * Math.min(1, fall)
+
+      const nextX = wantX + home.pushX
+      const nextY = wantY + home.pushY
+
+      // Pointing along whatever it just did, eased, so a fish that is barely
+      // moving does not spin. A mark whose angle is read straight off a frame's
+      // worth of travel is a mark that flickers.
+      const runX = nextX - one.x
+      const runY = nextY - one.y
+      if (Math.hypot(runX, runY) > 0.01) {
+        const want = Math.atan2(runY, runX)
+        const turn = Math.atan2(Math.sin(want - one.tilt), Math.cos(want - one.tilt))
+        one.tilt += turn * Math.min(1, TILT_EASE * dt)
+      }
+
+      one.depth = Math.max(0.05, Math.min(1, deep + w * thick))
+      one.size = home.long * mark * (1 - DEPTH_SIZE + DEPTH_SIZE * one.depth)
+      one.x = nextX
+      one.y = nextY
+    }
+  }
+
+  fill()
+
+  return {
+    resize(nextWidth, nextHeight, nextCount) {
+      width = Math.max(MIN_SPAN, nextWidth)
+      height = Math.max(MIN_SPAN, nextHeight)
+      if (nextCount != null) count = Math.max(0, Math.round(nextCount))
+      // Whatever was crossing is dropped, the way a passer is. A flock that
+      // changed size halfway over would be a flock that had been counted.
+      along = 1
+      weight = 0
+      fill()
+    },
+
+    get shape() {
+      return shape
+    },
+
+    specks,
+
+    step(seconds, startle = null) {
+      const dt = Math.min(Math.max(seconds, 0), 0.1)
+      drift += FIDGET_RATE * dt
+
+      if (along >= 1) {
+        weight = 0
+        rest -= dt
+        if (eager || rest <= 0) {
+          arrive()
+          rest = REST_LEAST + random() * REST_SPAN
+        }
+        if (along >= 1) return
+      }
+
+      along += dt / Math.max(take, 0.001)
+      spin += LAYOUTS[shape].churn * Math.PI * 2 * dt
+      weight = Math.max(0, Math.min(1, along / FADE, (1 - along) / FADE))
+
+      const from = -OFFING * width
+      const to = width * (1 + OFFING)
+      const at = Math.min(1, along)
+
+      carry(dt, facing > 0 ? from + at * (to - from) : to - at * (to - from), startle)
+    },
+
+    get weight() {
+      return weight
+    },
+  }
+}