@codincod/ornament 0.0.0-stage → 0.1.0

package/src/drift.ts

@@ -0,0 +1,435 @@
+/**
+ * What the water carries: snow falling through it, and bubbles going up.
+ *
+ * The simulation behind the drifting half of a seascape, kept free of the DOM
+ * the way `shoal.ts` is, so the drawing half stays a drawing half.
+ *
+ * This exists because of what a shoal on its own looks like. Fish are large,
+ * few and far apart, so between them is water with nothing in it, and water
+ * with nothing in it does not read as water. It reads as a background colour
+ * that happens to have animals on top. The fix is not more fish: a screen busy
+ * with animals is a screen that wants looking at, which is the one thing an
+ * ornament may not ask for. The fix is smaller things.
+ *
+ * ## Snow
+ *
+ * Marine snow is the real thing this is named after, and the real thing is what
+ * makes it work. It is mostly falling, slowly, and it is everywhere at once, so
+ * the eye reads a volume of water rather than a plane. Each mote is a couple of
+ * pixels at most and faint with it, which is what lets there be enough of them
+ * to fill a screen without any one of them being a thing you notice.
+ *
+ * They fall at their own rate and slide with the same Perlin field that steers
+ * the fish, which is the whole reason they belong in this file and not in a
+ * stylesheet. Snow that fell straight down would be rain. Snow that agrees with
+ * the fish about which way the water is moving is the water becoming visible.
+ *
+ * ## Bubbles
+ *
+ * Bubbles come off a vent, which is a fixed point on the floor, in strings
+ * rather than singly, and then the vent goes quiet for a while. That rhythm is
+ * the point. A steady stream is a machine; a burst and a pause is something
+ * down there breathing.
+ *
+ * A bubble grows as it rises, because the pressure on it drops, and it wobbles
+ * because it is not rigid. Both are cheap and both are what the eye checks
+ * against without knowing it. What it does at the top is nothing: it reaches
+ * the surface and is gone, since a bubble that faded out in mid-water would be
+ * asking why.
+ *
+ * ## A mote is redrawn when it has fallen far enough to be worth it
+ *
+ * Snow is the cheapest thing in this water to simulate and among the dearest
+ * to hand over. A mote has no geometry, so nothing here is cut; what a renderer
+ * pays is the copy and the tessellation, for every mote on every frame, and
+ * most of them have gone nowhere a screen could show. So a mote holds the place
+ * it was last drawn at until it has fallen `tolerance` away from it, and `cut`
+ * is how a renderer knows. Two subtractions and a hypotenuse, on numbers the
+ * fall has already produced.
+ *
+ * `docs/decisions/0027-let-an-element-decide-when-its-drawing-is-stale.md` is
+ * the argument. Bubbles are left out of it. There are few of them, none lasts
+ * more than seconds, and one rises further between frames than any tolerance
+ * worth setting would hold it back by.
+ *
+ * Everything is seeded, so the same seed gives the same weather twice.
+ */
+
+import { makeNoise2, makeRandom, type Noise2 } from "./perlin.ts"
+
+export interface Bubble {
+  /** 0 is as far off as this water goes, 1 is up against the glass. */
+  readonly depth: number
+  /** Its own lane through the wobble, so no two in a string weave alike. */
+  readonly lane: number
+  /** Radius in px, which grows the whole way up; see `SWELL`. */
+  r: number
+  /** How long it has been up, in seconds, which is what drives the wobble. */
+  rose: number
+  x: number
+  y: number
+}
+
+export interface Mote {
+  /**
+   * How many times this mote has been redrawn.
+   *
+   * The only thing a renderer has to watch. While it holds, the mote has not
+   * fallen far enough for another drawing to differ from the one already on the
+   * screen, so a renderer that leaves it alone leaves a picture that is still
+   * true to within the tolerance.
+   */
+  cut: number
+  readonly depth: number
+  /** Its own lane through the field, so neighbours do not fall as a sheet. */
+  readonly lane: number
+  /** Radius in px, with depth already taken out of it. */
+  readonly r: number
+  /** Its own share of the fall, so a drift is not a curtain coming down. */
+  readonly rate: number
+  x: number
+  y: number
+}
+
+export interface Drift {
+  readonly bubbles: readonly Bubble[]
+  readonly motes: readonly Mote[]
+  /** Re-fit to a resized box, carrying what is in it across in proportion. */
+  resize(width: number, height: number, motes?: number): void
+  step(seconds: number): void
+}
+
+export interface DriftOptions {
+  /**
+   * Where the floor is at a given x, for anything that has to sit on it.
+   *
+   * A function rather than a number because a seabed is not level, and a vent
+   * that hangs in the water a little above the sand is worse than no vent. The
+   * default is the bottom of the box, which is what a surface with no seabed
+   * drawn on it wants.
+   */
+  floor?: (x: number) => number
+  height: number
+  motes: number
+  seed: number
+  /**
+   * How far a mote may fall from its last drawing before it is drawn again, in
+   * px.
+   *
+   * `FloraOptions.tolerance` for the snow, and the same bargain. At nothing
+   * every mote is redrawn on every step, which is how this behaved before. At a
+   * quarter of a pixel most of them are left alone on most frames, and what is
+   * given up is a fall that arrives in quarter-pixel steps on a dot drawn a
+   * couple of px across and faint with it.
+   */
+  tolerance?: number
+  /** How many places on the floor bubbles come from. */
+  vents?: number
+  width: number
+}
+
+/**
+ * How many of the field's features fit across the box.
+ *
+ * Deliberately coarser than the shoal's, so the snow is answering a broader
+ * swell than the fish are. Matching them exactly was the first attempt and it
+ * looked wrong in a way that took a while to name: every mote near a fish was
+ * doing what the fish did, so the snow read as the fish's wake rather than as
+ * the water both of them are in.
+ */
+const FIELD_CELLS = 2.2
+
+/** How fast the field slides, so nothing ever settles into a loop. */
+const DRIFT = 0.04
+
+/** How far the field can push a mote sideways, in px a second at depth 1. */
+const SWAY = 13
+
+/** How fast snow falls, slowest to fastest, in px a second at depth 1. */
+const FALL_SLOWEST = 4
+
+const FALL_FASTEST = 13
+
+/**
+ * The spread of mote sizes in px, at depth 1, and how hard the draw leans small.
+ *
+ * Leaning hard, because size here is doing the work distance does. A field of
+ * evenly sized dots is a texture and the eye dismisses it; a field where most
+ * are at the limit of being visible and a few are clearly nearer is depth, and
+ * depth is the only reason to draw any of this.
+ *
+ * It is the one thing in this water not written down in metres, and that is
+ * deliberate. Snow is a fleck of a millimetre or two adrift within reach of the
+ * glass, and `sizes.ts` weighs a length against a distance: something that
+ * small that close comes out of the sum larger than the fish behind it. What is
+ * being drawn is a texture on the water rather than an animal in it.
+ */
+const MOTE_SMALLEST = 0.4
+
+const MOTE_LARGEST = 1.9
+
+const MOTE_BIAS = 2.6
+
+/** How far a mote falls before it is worth drawing again, in px, by default. */
+const TOLERANCE = 0.25
+
+/** How much of a mote's size and speed is its depth. */
+const DEPTH_SIZE = 0.75
+
+/** The nearest and furthest anything drifting is ever put. */
+const DEPTH_NEAR = 1
+
+const DEPTH_FAR = 0.08
+
+/** How fast a bubble rises, slowest to fastest, in px a second at depth 1. */
+const RISE_SLOWEST = 38
+
+const RISE_FASTEST = 66
+
+/** A bubble's radius where it leaves the vent, in px, and how much it gains. */
+const BUBBLE_SMALLEST = 1.1
+
+const BUBBLE_LARGEST = 2.9
+
+/**
+ * How much bigger a bubble is at the surface than at the floor.
+ *
+ * Modest. The honest figure for a shallow sea is close to nothing, and the
+ * honest figure for a deep one is a great deal more than this, but a bubble
+ * that arrives at the top four times the size it left is a balloon. What this
+ * has to do is stop the string reading as a column of identical dots.
+ */
+const SWELL = 0.6
+
+/**
+ * How far a bubble weaves off its line, in px, and how fast it weaves.
+ *
+ * Wide enough to be seen from across a room. A vent draws the eye because it is
+ * the one thing in the water moving against everything else, so a string that
+ * goes up dead straight is the most obviously ruled line in the scene. What
+ * stops it being a line is that no two bubbles in the string are at the same
+ * point of the same weave, which is what `Bubble.lane` is for.
+ */
+const WOBBLE = 9
+
+const WOBBLE_RATE = 1.9
+
+/**
+ * How long a vent runs, and how long it rests, in seconds.
+ *
+ * The rest is much the longer of the two, which is what keeps a seascape from
+ * turning into an aquarium ornament. Most of the time nothing is coming out of
+ * the floor at all, and then something is.
+ */
+const VENT_RUN_LEAST = 0.7
+
+const VENT_RUN_SPAN = 1.6
+
+const VENT_REST_LEAST = 5
+
+const VENT_REST_SPAN = 14
+
+/**
+ * How long between bubbles while a vent is running, in seconds.
+ *
+ * A wide spread rather than a tight one, because the spacing up the string is
+ * the tell. Bubbles let go on a near-constant interval arrive evenly spaced and
+ * the whole column reads as a dotted line drawn on the water.
+ */
+const VENT_GAP_LEAST = 0.07
+
+const VENT_GAP_SPAN = 0.5
+
+/** A floor for the box, so a sliver of a window never divides by nothing. */
+const MIN_SPAN = 1
+
+interface Vent {
+  /** Seconds until the next bubble, or until this vent changes its mind. */
+  next: number
+  /** Whether it is running or resting. */
+  running: boolean
+  /** Seconds left in the run or the rest it is in. */
+  until: number
+  readonly x: number
+  readonly y: number
+}
+
+export function createDrift(options: DriftOptions): Drift {
+  const noise = makeNoise2(options.seed ^ 0x1d3f)
+  const random = makeRandom(options.seed ^ 0x7a21)
+
+  let width = Math.max(MIN_SPAN, options.width)
+  let height = Math.max(MIN_SPAN, options.height)
+  let slide = 0
+
+  const floor = options.floor ?? (() => height)
+
+  const tolerance = Math.max(0, options.tolerance ?? TOLERANCE)
+
+  const mote = (): Mote => {
+    const depth = DEPTH_FAR + random() * (DEPTH_NEAR - DEPTH_FAR)
+    const shrink = 1 - DEPTH_SIZE + DEPTH_SIZE * depth
+
+    return {
+      cut: 0,
+      depth,
+      lane: random() * 200,
+      r: (MOTE_SMALLEST + random() ** MOTE_BIAS * (MOTE_LARGEST - MOTE_SMALLEST)) * shrink,
+      rate: (FALL_SLOWEST + random() * (FALL_FASTEST - FALL_SLOWEST)) * shrink,
+      x: random() * width,
+      y: random() * height,
+    }
+  }
+
+  const motes: Mote[] = []
+
+  /** Where each mote stood when it was last drawn, alongside the mote itself. */
+  const held: { x: number; y: number }[] = []
+
+  function sow(): void {
+    const one = mote()
+    motes.push(one)
+    held.push({ x: one.x, y: one.y })
+  }
+
+  /** Say a mote is where it is now, so a renderer comes and reads it again. */
+  function draw(at: number): void {
+    const one = motes[at]
+    const was = held[at]
+    if (!one || !was) return
+
+    was.x = one.x
+    was.y = one.y
+    one.cut++
+  }
+
+  for (let made = 0; made < Math.max(0, options.motes); made++) sow()
+
+  const vent = (): Vent => {
+    const x = random() * width
+    return {
+      next: 0,
+      running: false,
+      until: random() * (VENT_REST_LEAST + VENT_REST_SPAN),
+      x,
+      y: floor(x),
+    }
+  }
+
+  const vents: Vent[] = Array.from({ length: Math.max(0, options.vents ?? 0) }, vent)
+  const bubbles: Bubble[] = []
+
+  function release(from: Vent): void {
+    const depth = DEPTH_FAR + random() * (DEPTH_NEAR - DEPTH_FAR)
+
+    bubbles.push({
+      depth,
+      lane: random() * 200,
+      r: (BUBBLE_SMALLEST + random() * (BUBBLE_LARGEST - BUBBLE_SMALLEST)) * depth,
+      rose: 0,
+      x: from.x + (random() - 0.5) * WOBBLE,
+      y: from.y,
+    })
+  }
+
+  return {
+    bubbles,
+    motes,
+
+    resize(nextWidth, nextHeight, count) {
+      const scaleX = Math.max(MIN_SPAN, nextWidth) / width
+      const scaleY = Math.max(MIN_SPAN, nextHeight) / height
+      width = Math.max(MIN_SPAN, nextWidth)
+      height = Math.max(MIN_SPAN, nextHeight)
+
+      for (let at = 0; at < motes.length; at++) {
+        const one = motes[at]
+        if (!one) continue
+        one.x *= scaleX
+        one.y *= scaleY
+        draw(at)
+      }
+      for (const one of bubbles) {
+        one.x *= scaleX
+        one.y *= scaleY
+      }
+
+      if (count == null) return
+      while (motes.length > count) {
+        motes.pop()
+        held.pop()
+      }
+      while (motes.length < count) sow()
+    },
+
+    step(seconds) {
+      const dt = Math.min(Math.max(seconds, 0), 0.1)
+      slide += DRIFT * dt
+      const scale = FIELD_CELLS / width
+
+      for (let at = 0; at < motes.length; at++) {
+        const one = motes[at]
+        const was = held[at]
+        if (!one || !was) continue
+
+        const push = noise(one.x * scale + one.lane, one.y * scale + one.lane + slide)
+        one.x += push * SWAY * one.depth * dt
+        one.y += one.rate * dt
+
+        if (one.y > height + one.r) {
+          one.y = -one.r
+          one.x = random() * width
+        }
+        one.x = around(one.x, width, one.r)
+
+        if (Math.hypot(one.x - was.x, one.y - was.y) >= tolerance) draw(at)
+      }
+
+      for (const from of vents) {
+        from.until -= dt
+        if (from.until <= 0) {
+          from.running = !from.running
+          from.until = from.running
+            ? VENT_RUN_LEAST + random() * VENT_RUN_SPAN
+            : VENT_REST_LEAST + random() * VENT_REST_SPAN
+          from.next = 0
+        }
+
+        if (!from.running) continue
+
+        from.next -= dt
+        if (from.next > 0) continue
+
+        from.next = VENT_GAP_LEAST + random() * VENT_GAP_SPAN
+        release(from)
+      }
+
+      for (let at = bubbles.length - 1; at >= 0; at--) {
+        const one = bubbles[at]
+        if (!one) continue
+
+        const climb = (RISE_SLOWEST + one.depth * (RISE_FASTEST - RISE_SLOWEST)) * one.depth
+        one.rose += dt
+        one.y -= climb * dt
+        one.r += one.r * SWELL * (climb / Math.max(height, MIN_SPAN)) * dt
+        one.x += Math.cos(one.rose * WOBBLE_RATE + one.lane) * WOBBLE * dt
+
+        if (one.y + one.r < 0) bubbles.splice(at, 1)
+      }
+    },
+  }
+}
+
+/**
+ * Off one side and back on the other.
+ *
+ * Snow wraps sideways and respawns at the top rather than wrapping there, which
+ * is not an inconsistency. A mote that left the bottom and arrived at the top in
+ * the same column would draw a visible seam down the picture, because the eye
+ * follows a falling thing and finds it again. Sideways nothing is following it.
+ */
+function around(value: number, span: number, margin: number): number {
+  if (value > span + margin) return -margin
+  if (value < -margin) return span + margin
+  return value
+}