@codincod/ornament 0.0.0-stage → 0.2.0

package/src/puffers.ts

@@ -0,0 +1,510 @@
+/**
+ * The one animal in this water that does not run.
+ *
+ * Every other response in this sea is a way of leaving. A fish darts, a crab
+ * freezes and then bolts, an octopus jets, a jellyfish furls and sinks, an
+ * anemone shuts, a colony of eels drops into the sand. All of it is the same
+ * sentence said in six ways, and a sea that only knows one sentence is a sea
+ * where nothing that happens means anything, because the answer is always the
+ * same answer.
+ *
+ * A pufferfish stays. It swallows water until it is a ball with spines out and
+ * then hangs there, and what it is saying is not "I am leaving" but "you cannot
+ * get this in your mouth". It is the only argument in the picture, and it is
+ * the whole reason to draw one.
+ *
+ * ## Why it is not a fish in `shoal.ts`
+ *
+ * Because it is not driven the way a fish is. A fish in that file is a spine
+ * with a wave running down it and a heading it eases onto, and what makes it
+ * look like a fish is that the body it is drawn as is the body that is pushing
+ * it. A pufferfish sculls with two small fins on the sides of a body that is
+ * held rigid. It is closer to a helicopter than to a fish, and every constant
+ * in `shoal.ts` is about the thing it is not.
+ *
+ * The other half is that a shoal steers on fright and this one does not. A fish
+ * that stopped fleeing would break every rule that file is built out of.
+ *
+ * ## What swelling costs
+ *
+ * Everything, which is why it is not free here either. Inflating is expensive
+ * and it takes a while to undo, so a real one does not do it lightly and does
+ * not stop doing it the moment the danger has passed: `SWELL` and `SETTLE` are
+ * far apart for the same reason `eels.ts` has them far apart, and it is the same
+ * fact about animals. Half deflated with nothing about is what one looks like
+ * for a minute after something went by, and it is the state that makes the event
+ * before it legible.
+ *
+ * ## What a renderer gets
+ *
+ * `body` is a closed outline in px and `spines` are lines standing off it, both
+ * recut only when the animal has changed enough to be worth it. The outline goes
+ * from an oval to very nearly a circle, the tail shrinks against it as it goes,
+ * and the spines are nothing at rest: a pufferfish at rest is a slightly
+ * lumpy fish, and that is what makes the other state read.
+ */
+
+import { abreast, type Presence } from "./biome.ts"
+import { makeRandom } from "./perlin.ts"
+import type { Point } from "./seabed.ts"
+import { BED_OFF, drawnAt } from "./sizes.ts"
+
+export interface Puffer {
+  /** The outline, closed, in px. */
+  body: Point[]
+  /**
+   * How many times it has redrawn itself.
+   *
+   * The only thing a renderer has to watch. A pufferfish spends most of a
+   * sitting at rest and drifting slowly, so it holds a drawing for a long time.
+   */
+  cut: number
+  /** 0 is as far off as this water goes, 1 is up against the glass. */
+  readonly depth: number
+  /** Where the eye sits, in px. */
+  eye: Point
+  /** Which way it is pointed, once and for life: 1 rightward, -1 left. */
+  readonly facing: number
+  /** How wide it is across at rest, in px. */
+  readonly size: number
+  /** The spines, each a triangle standing off the body. Empty at rest. */
+  spines: Point[][]
+  /** How swollen it is, 0 a fish and 1 a ball with spines out. */
+  swell: number
+  x: number
+  y: number
+}
+
+export interface Puffers {
+  readonly puffers: readonly Puffer[]
+  resize(width: number, height: number, floor: (x: number, depth?: number) => number): void
+  step(seconds: number): void
+}
+
+export interface PuffersOptions {
+  /**
+   * What else is in the water, asked for once a step.
+   *
+   * Left out, nothing is, and a pufferfish with nothing to argue with is a
+   * slightly lumpy fish sculling about, which is what one is.
+   */
+  about?: () => readonly Presence[]
+  count?: number
+  /** The ground at x, at a given distance; `seabed.floorAt`. */
+  floor: (x: number, depth?: number) => number
+  height: number
+  seed: number
+  /** How far it may move from its last drawing before it recuts, in px. */
+  tolerance?: number
+  width: number
+}
+
+/**
+ * How long one is, in metres.
+ *
+ * A reef pufferfish, which is the ordinary one and is a hand's length. The
+ * giants are a different animal and a different picture.
+ */
+const LENGTH = 0.3
+
+/** How much bigger or smaller than that one of them is. */
+const ODD = 0.22
+
+/** How much of its drawn size is its distance. The floor's own share. */
+const DEPTH_SIZE = 0.55
+
+/**
+ * How far back they go, and how far off the sand they hang.
+ *
+ * Near the bottom without being on it. A pufferfish works the floor and the
+ * lower reef, and one drawn out in the open water is a balloon somebody let go
+ * of. The height off the sand is in its own body widths, so a small one keeps
+ * closer to the ground than a large one, which is what they do.
+ */
+const DEPTH_FAR = 0.3
+
+const DEPTH_NEAR = 0.95
+
+const OVER_LEAST = 0.6
+
+const OVER_SPAN = 3.4
+
+/** How fast it sculls, in its own widths a second, and how far off that one
+ *  of them is. Slow. Two fins the size of a thumbnail on a body like a fist. */
+const SCULL = 0.42
+
+const DAWDLE = 0.45
+
+/** How long it holds a heading, in seconds. It has nowhere to be. */
+const HOLD_LEAST = 4
+
+const HOLD_SPAN = 11
+
+/** How far past the side it goes before it comes back on the other. */
+const MARGIN = 1.5
+
+/**
+ * How much bigger than a pufferfish a thing has to be before it is minded, and
+ * how far off it is minded from as a share of its own size.
+ *
+ * `walkers.ts`, `nemos.ts` and `eels.ts` weigh the water by these. The rule is
+ * shared and the answer is not, which is the point of having four animals read
+ * one register.
+ */
+const MINDS = 1.7
+
+const NOTICE = 2.6
+
+/** How much of an alarm something with no menace about it can still cause. */
+const BULK = 0.25
+
+/** How little a thing has to worry it before it is not worth the water. */
+const MINDS_AT = 0.16
+
+/**
+ * How fast it swells and how fast it settles, in shares of full a second.
+ *
+ * Far apart, and the far apart is the animal. Swallowing enough water to double
+ * is a second's work and getting rid of it again is not, so what a pufferfish
+ * looks like for a while after something went past is a pufferfish that has not
+ * finished being frightened.
+ */
+const SWELL = 1.6
+
+const SETTLE = 0.1
+
+/**
+ * How much wider it gets, and how much rounder.
+ *
+ * The width is the smaller half of it. What says inflated is that the animal
+ * has stopped being a fish shape: a deflated one is a long oval and a swollen
+ * one is a circle, and the eye reads the roundness before it reads the size.
+ */
+const GROWTH = 0.55
+
+/** How long a body is against its width, at rest and full. */
+const LONG_REST = 1.5
+
+const LONG_FULL = 1.06
+
+/** How finely the outline is cut. Enough that a circle has no corners in it. */
+const RIM = 30
+
+/**
+ * The tail, as a share of the body's own width: how long at rest, how much of
+ * that survives being swollen, and how far it fans.
+ *
+ * Nearly none of it survives. A tail on a sphere is a flap, and the flap is
+ * what makes the sphere read as an animal rather than as a mine.
+ */
+const TAIL = 0.26
+
+const TAIL_KEPT = 0.34
+
+const TAIL_FAN = 0.5
+
+/** How much of the rim the tail joins across, either side of the back. */
+const TAIL_ROOT = 0.05
+
+/** How fast the tail works, and how far it sweeps, in radians. */
+const BEAT_SLOWEST = 0.5
+
+const BEAT_FASTEST = 0.9
+
+const SWEEP = 0.42
+
+/**
+ * How many spines it carries, how long one is against the body, and how much
+ * of the swell has to happen before any of them show.
+ *
+ * They lie flat until the skin is stretched, which is a fact about the animal
+ * and is also the thing that makes the drawing work: spines out on a resting
+ * fish would be a hedgehog.
+ */
+const SPINES = 16
+
+const SPINE_LONG = 0.19
+
+const SPINE_FROM = 0.25
+
+/** How much of the gap between two spines the base of one takes. */
+const SPINE_SEAT = 0.3
+
+/** Where the eye sits along the body and how far off the middle, and how big
+ *  it is. A pufferfish is mostly eye, which is why it reads as a face. */
+const EYE_ALONG = 0.62
+
+const EYE_UP = 0.22
+
+/** How far it drifts before it is worth redrawing, in px, by default. */
+const TOLERANCE = 0.3
+
+const MIN_SPAN = 1
+
+/** What it was when it was last drawn. */
+interface Drawn {
+  swell: number
+  wag: number
+  x: number
+  y: number
+}
+
+/** Everything about one that is not in the drawing. */
+interface Habit {
+  /** How fast the tail works. */
+  readonly beat: number
+  /** Where in that beat it is. */
+  clock: number
+  drawn: Drawn | null
+  /** Radians. Where it is going, which is nowhere in particular. */
+  heading: number
+  /** Seconds left on the heading it is holding. */
+  hold: number
+  /** How high off the sand it hangs, in its own widths. */
+  readonly over: number
+  /** How fast it sculls, as a share of the ordinary. */
+  readonly pace: number
+}
+
+export function createPuffers(options: PuffersOptions): Puffers {
+  const random = makeRandom(options.seed ^ 0x71c3)
+
+  let width = Math.max(MIN_SPAN, options.width)
+  let height = Math.max(MIN_SPAN, options.height)
+  let floor = options.floor
+
+  const tolerance = Math.max(0, options.tolerance ?? TOLERANCE)
+
+  const puffers: Puffer[] = []
+  const habits: Habit[] = []
+
+  function fill(): void {
+    puffers.length = 0
+    habits.length = 0
+
+    const many = Math.max(0, Math.floor(options.count ?? 0))
+    for (let made = 0; made < many; made++) {
+      const depth = DEPTH_FAR + random() * (DEPTH_NEAR - DEPTH_FAR)
+      const across = drawnAt(LENGTH, BED_OFF) * width
+      const size = across * (1 - DEPTH_SIZE + DEPTH_SIZE * depth) * (1 + (random() - 0.5) * 2 * ODD)
+      const x = random() * width
+
+      puffers.push({
+        body: [],
+        cut: 0,
+        depth,
+        eye: { x, y: 0 },
+        facing: random() < 0.5 ? -1 : 1,
+        size,
+        spines: [],
+        swell: 0,
+        x,
+        y: 0,
+      })
+      habits.push({
+        beat: BEAT_SLOWEST + random() * (BEAT_FASTEST - BEAT_SLOWEST),
+        clock: random() * Math.PI * 2,
+        drawn: null,
+        heading: 0,
+        hold: random() * HOLD_SPAN,
+        over: OVER_LEAST + random() * OVER_SPAN,
+        pace: 1 + (random() - 0.5) * 2 * DAWDLE,
+      })
+    }
+
+    for (let at = 0; at < puffers.length; at++) sit(at)
+  }
+
+  /** Put it where it hangs over the sand it is above. */
+  function sit(at: number): void {
+    const one = puffers[at]
+    const habit = habits[at]
+    if (!one || !habit) return
+
+    one.y = Math.min(height, floor(one.x, one.depth) - one.size * habit.over)
+  }
+
+  /**
+   * How much the water worries it, right now.
+   *
+   * The same rule the rest of the sea reads, and a different answer. What comes
+   * out of this is not where to go: it is how much water to swallow.
+   */
+  function minded(one: Puffer, water: readonly Presence[]): number {
+    let worst = 0
+
+    for (const thing of water) {
+      if (thing.size < one.size * MINDS) continue
+
+      const reach = thing.size * NOTICE
+      const away = Math.hypot(one.x - thing.x, one.y - thing.y)
+      if (away >= reach) continue
+
+      const near = (1 - away / reach) * abreast(one.depth, thing.depth)
+      worst = Math.max(worst, near * (BULK + (thing.menace ?? 0) * (1 - BULK)))
+    }
+
+    return worst < MINDS_AT ? 0 : worst
+  }
+
+  /**
+   * The outline, from an oval at rest to a circle full.
+   *
+   * One shape rather than two blended, because two drawings crossfaded is what
+   * a sprite sheet does and it shows: the halfway frame of a crossfade is two
+   * animals at once. What changes here is how long the body is against how wide
+   * it is, and every point on the outline is on the one animal the whole way
+   * through.
+   */
+  function cut(at: number): void {
+    const one = puffers[at]
+    const habit = habits[at]
+    if (!one || !habit) return
+
+    const wide = (one.size / 2) * (1 + one.swell * GROWTH)
+    const long = wide * (LONG_REST + (LONG_FULL - LONG_REST) * one.swell)
+
+    const body: Point[] = []
+    for (let step = 0; step < RIM; step++) {
+      const turn = (step / RIM) * Math.PI * 2
+      body.push({
+        x: one.x + Math.cos(turn) * long * one.facing,
+        y: one.y + Math.sin(turn) * wide,
+      })
+    }
+
+    // The tail, hung off the back and swept by its own clock. It is drawn as
+    // part of the outline rather than beside it, so a swollen fish has one
+    // silhouette instead of a ball with a leaf behind it.
+    const wag = Math.sin(habit.clock) * SWEEP
+    const stub = one.size * TAIL * (TAIL_KEPT + (1 - TAIL_KEPT) * (1 - one.swell))
+    const from = { x: one.x - long * one.facing, y: one.y }
+    const tip = {
+      x: from.x - Math.cos(wag) * stub * one.facing,
+      y: from.y + Math.sin(wag) * stub,
+    }
+    const fan = stub * TAIL_FAN
+
+    // Spliced at the back of the rim rather than at the seam, and across a few
+    // points of it rather than between two. The seam is where the outline
+    // wraps, which is the front of the animal, and a tail let in there is a
+    // wedge driven through the middle of the fish; let in between two adjacent
+    // points it is a wedge hung off one, which is a leaf on a string. What a
+    // tail actually joins is a stretch of the back.
+    const back = Math.round(RIM / 2)
+    const root = Math.max(1, Math.round(RIM * TAIL_ROOT))
+    one.body = [
+      ...body.slice(0, back - root),
+      { x: tip.x, y: tip.y + fan },
+      { x: tip.x, y: tip.y - fan },
+      ...body.slice(back + root),
+    ]
+
+    one.eye = {
+      x: one.x + long * EYE_ALONG * one.facing,
+      y: one.y - wide * EYE_UP,
+    }
+
+    // Triangles rather than lines, because a spine has a point on it and a
+    // stroke with a round cap has a thumb. Each one sits on a chord of the rim
+    // and leaves from the middle of it, so the base is the width the body can
+    // actually spare and the taper is the rim's own curvature.
+    one.spines = []
+    if (one.swell > SPINE_FROM) {
+      const out = ((one.swell - SPINE_FROM) / (1 - SPINE_FROM)) * one.size * SPINE_LONG
+      const seat = (Math.PI * 2 * SPINE_SEAT) / SPINES
+      for (let step = 0; step < SPINES; step++) {
+        const turn = (step / SPINES) * Math.PI * 2
+        const on = (off: number) => ({
+          x: one.x + Math.cos(turn + off) * long * one.facing,
+          y: one.y + Math.sin(turn + off) * wide,
+        })
+        one.spines.push([
+          on(-seat),
+          {
+            x: one.x + Math.cos(turn) * (long + out) * one.facing,
+            y: one.y + Math.sin(turn) * (wide + out),
+          },
+          on(seat),
+        ])
+      }
+    }
+
+    habit.drawn = { swell: one.swell, wag, x: one.x, y: one.y }
+    one.cut++
+  }
+
+  /** How far the drawing has drifted from what is on screen. */
+  function stir(at: number): number {
+    const one = puffers[at]
+    const habit = habits[at]
+    if (!one || !habit || !habit.drawn) return Number.POSITIVE_INFINITY
+
+    const was = habit.drawn
+    const wag = Math.sin(habit.clock) * SWEEP
+    return (
+      Math.hypot(one.x - was.x, one.y - was.y) +
+      Math.abs(one.swell - was.swell) * one.size +
+      Math.abs(wag - was.wag) * one.size * TAIL
+    )
+  }
+
+  fill()
+
+  return {
+    puffers,
+
+    resize(next: number, tall: number, ground: (x: number, depth?: number) => number): void {
+      width = Math.max(MIN_SPAN, next)
+      height = Math.max(MIN_SPAN, tall)
+      floor = ground
+      fill()
+    },
+
+    step(seconds: number): void {
+      const water = options.about?.() ?? []
+
+      for (let at = 0; at < puffers.length; at++) {
+        const one = puffers[at]
+        const habit = habits[at]
+        if (!one || !habit) continue
+
+        const worries = minded(one, water)
+
+        // The whole animal, in one line. It swells towards what the water
+        // deserves and settles back at a fraction of the rate, and it never
+        // steers on either: where it was going is where it is still going.
+        const rate = (worries > one.swell ? SWELL : SETTLE) * seconds
+        one.swell += Math.max(-rate, Math.min(rate, worries - one.swell))
+
+        habit.clock += seconds * habit.beat * Math.PI * 2
+
+        habit.hold -= seconds
+        if (habit.hold <= 0) {
+          habit.hold = HOLD_LEAST + random() * HOLD_SPAN
+          // A shallow pitch either side of level and never a turn, the reason
+          // `shoal.ts` gives: a drawn animal faces one way, and one that
+          // mirrored would turn inside out between two frames.
+          habit.heading = (random() - 0.5) * 0.6
+        }
+
+        // Slower the more swollen it is, because a ball is a worse shape to
+        // push through water than a fish is, and a pufferfish that kept its
+        // speed while doubling would be a pufferfish nothing had happened to.
+        const pace = SCULL * habit.pace * one.size * (1 - one.swell * 0.7)
+        one.x += Math.cos(habit.heading) * pace * seconds * one.facing
+        one.y += Math.sin(habit.heading) * pace * seconds
+
+        const edge = one.size * MARGIN
+        if (one.x < -edge) one.x += width + edge * 2
+        if (one.x > width + edge) one.x -= width + edge * 2
+
+        const over = floor(one.x, one.depth) - one.size * habit.over
+        one.y += (over - one.y) * Math.min(1, seconds)
+
+        if (stir(at) < tolerance) continue
+        cut(at)
+      }
+    },
+  }
+}