@codincod/ornament 0.0.0-stage → 0.1.0

package/src/nemos.ts

@@ -0,0 +1,606 @@
+/**
+ * Clownfish, which live on one reef and go nowhere else.
+ *
+ * The simulation for the animals `reef.ts` houses, kept free of the DOM the way
+ * the rest of the ornament is. Everything else that swims in this water is
+ * passing through: the shoal crosses the picture and comes back, the visitors
+ * arrive and leave. A nemo is the one animal here with an address.
+ *
+ * ## Why it never leaves
+ *
+ * Because the real one does not. A clownfish is stung by everything on a reef
+ * except the anemone it grew up in, so the anemone is the whole of its world
+ * and it spends its life within a few body lengths of it. That is the rarest
+ * thing a background can show you: an animal that is somewhere rather than
+ * going somewhere. A shoal drifting past says the water is wide, and one fish
+ * fussing over the same patch of rock says the water is lived in.
+ *
+ * It is also the only reason the reef reads as a place at all. A mound with
+ * nothing tending it is scenery, and the same mound with something that keeps
+ * coming back to one corner of it is a home with a shape you learn.
+ *
+ * So there is no wandering off. Every station one picks is a place it asked the
+ * reef about first, and anything that would take it off the rock is refused
+ * rather than corrected later, which is what makes the claim in the name of
+ * this file true on every frame and not merely most of them.
+ *
+ * ## The turn
+ *
+ * `shoal.ts` forbids a fish to turn round, and the reason is sound: mirroring a
+ * drawing mid-swim turns the animal inside out, and easing the mirror instead
+ * foreshortens it through edge-on, which reads as paper turning in the wind. A
+ * fish crossing the picture never has to turn, so it never does.
+ *
+ * A fish tied to one anemone has to turn constantly, so the rule cannot hold
+ * here and the reason it was made has to be answered instead. What made the
+ * foreshortening read as paper was that it happened at speed: an animal going
+ * somewhere does not narrow. So a nemo turns only where a real one does, at the
+ * end of a run, having stopped. It arrives, hovers, and comes about while it is
+ * barely moving, and the drawing narrows through nothing at the moment nothing
+ * about it is travelling. See `Nemo.face`.
+ *
+ * ## Fright is looking, not being told
+ *
+ * This used to be a call. Something outside worked out that a shark had come
+ * near enough to matter and told the fish how frightened to be, which is a
+ * director's note, and there is no director in the sea. Nothing tells a
+ * clownfish anything. It watches the water, and what it does about what it sees
+ * is its own.
+ *
+ * So a nemo is handed a way of asking what else is out there, `about`, and it
+ * looks for itself every step. What it minds is anything bigger than it is, and
+ * how far off it minds one from is set by how big that thing is, because a
+ * silhouette twice the size is one you notice twice as far away. Something its
+ * own size or smaller it ignores, whatever it is doing: a clownfish is not
+ * afraid of a shrimp, and it will let a fish its own size swim through the
+ * anemone without moving. It weighs all of it by how nearly abreast the thing
+ * is swimming, so a shark cruising past the glass leaves a reef in the murk
+ * alone however neatly the two line up on the screen.
+ *
+ * There are three answers and which one a fish gives is its own business.
+ * Something merely large, or something hunting a long way off, and it quickens:
+ * it stays out, keeps doing what it was doing, and does it faster, which is
+ * what a reef looks like when a shape goes over. Something hunting and close,
+ * and it gives up on the outing and goes home. A fish that bolted for the
+ * anemone every time anything crossed the picture would be a fish nobody ever
+ * saw out in the water.
+ *
+ * ## The third answer is going at it
+ *
+ * A household is ranked by size and the largest is the female, and she does not
+ * hide. She swims out at whatever it is. It is the most reliably observable
+ * thing a clownfish does, it is why anybody who has been on a reef with a
+ * camera has been bitten by a fish the length of a finger, and a reef where the
+ * only answer to a shark is a fish disappearing is a reef with the best of it
+ * left out.
+ *
+ * So `nerve` runs down the household. The female barely minds a shadow and
+ * comes out to meet a hunter; the smallest is in the tentacles before anybody
+ * else has noticed. What that draws is the picture a reef actually gives you:
+ * the little ones gone, and one fish out in front of the anemone facing
+ * something a hundred times its size.
+ *
+ * Nothing has to be wired up for this to work. A water with nothing in it hands
+ * back nothing and the fish go about their day.
+ *
+ * Everything is seeded, so the same seed keeps the same fish on the same rock.
+ */
+
+import { abreast, type Presence } from "./biome.ts"
+import { makeRandom } from "./perlin.ts"
+import type { Head, Reef } from "./reef.ts"
+import type { Point } from "./seabed.ts"
+import { drawnTilt } from "./shoal.ts"
+
+export interface Nemo {
+  /** Where it is going, which is always somewhere it asked the reef about. */
+  aim: Point
+  /** Tail beat, in radians. */
+  beat: number
+  /** How far into going at something it is, 1 fresh and 0 over it. */
+  charge: number
+  /** How far into the tentacles it is: 0 out in the water, 1 gone from sight. */
+  cover: number
+  /**
+   * The drawn width, from -1 to 1, whose sign is which way it points.
+   *
+   * A renderer scales the animal by this and takes the sign as the mirror, so a
+   * fish coming about is squeezed to nothing and opens out the other way. It is
+   * the mirroring `shoal.ts` refuses to do, allowed here because it only ever
+   * happens to a fish that has stopped; see the note at the top of this file.
+   */
+  face: number
+  /** How frightened it is: 1 fresh, 0 over it. */
+  fright: number
+  /** Seconds left on the station it is holding. */
+  hold: number
+  /** The anemone it lives in. Its address, its distance and its way out. */
+  host: Head
+  /** Its own phase, so no two of them waggle together. */
+  readonly lane: number
+  /** Body length in px, its anemone's distance already taken out of it. */
+  length: number
+  /**
+   * How easily this one is put off, against what it is looking at.
+   *
+   * Low is steady. It runs down the household from the female, so the same
+   * shadow crossing the same anemone empties it of everything but one fish.
+   */
+  readonly nerve: number
+  /** Where it comes in the household. 0 is the female, and she is the largest. */
+  readonly rank: number
+  /** How far to turn the drawing, in radians, after mirroring it by `face`. */
+  tilt: number
+  /** px a second. */
+  vx: number
+  vy: number
+  x: number
+  y: number
+}
+
+export interface Nemos {
+  readonly nemos: readonly Nemo[]
+  /**
+   * Take the reef again, after it has been rebuilt under them.
+   *
+   * A resize raises a fresh reef, so every anemone a fish knew about is gone,
+   * and how many anemones there are is not what it was either. The households
+   * are settled again from what the new reef offers.
+   */
+  resettle(): void
+  step(seconds: number): void
+}
+
+export interface NemosOptions {
+  /**
+   * What else is in this water, asked afresh every step.
+   *
+   * Left out, the water is empty as far as the fish can tell, which is what a
+   * reef on its own page is. Whatever supplies it is not commanding anything:
+   * it says what is there, and each fish decides for itself whether that is
+   * worth minding.
+   */
+  about?: () => readonly Presence[]
+  /**
+   * The most fish to settle, for a caller on a budget.
+   *
+   * Left out, the reef decides: every anemone on it gets its household, and a
+   * reef with no anemone on it holds no clownfish at all.
+   */
+  count?: number
+  reef: Reef
+  seed: number
+}
+
+/**
+ * How many fish one anemone keeps, fewest to most.
+ *
+ * How many there are is a fact about the reef rather than a number a caller
+ * thought of. A clownfish anemone holds a household: a large female, her
+ * mate, and whatever young are waiting their turn, and they do not leave and
+ * they do not join another. So the reef gets the fish its anemones can house,
+ * a reef with one anemone has one huddle on one side of it, and nobody has to
+ * keep a fish count and an anemone count in step by hand.
+ */
+const GROUP_LEAST = 2
+
+const GROUP_SPAN = 3
+
+/**
+ * How much smaller each fish in a household is than the one above it.
+ *
+ * A clownfish household is a queue, and the queue is visible: they are ranked
+ * by size, everybody knows their place in it, and when the female goes the next
+ * one up grows into the gap. Drawing them all one size is drawing a shoal that
+ * happens to be standing in an anemone.
+ */
+const RANK_STEP = 0.16
+
+/** The smallest a fish gets however far down the queue it is. */
+const RANK_LEAST = 0.45
+
+/**
+ * How steady the female is, and how much jumpier each one below her.
+ *
+ * The spread is the point rather than either end of it. What makes a reef read
+ * as inhabited is that one thing crossing it gets several different answers,
+ * and the cheapest way to several answers is one figure that is not the same
+ * for any two animals.
+ */
+const NERVE_BOLD = 0.34
+
+const NERVE_RUNG = 0.3
+
+const NERVE_JUMPY = 1.2
+
+/**
+ * How long a fish is against the anemone it lives in, and how much that varies.
+ *
+ * Against the anemone, because that is what it is always next to and the only
+ * thing anybody can judge its size by. It also settles a question a fixed size
+ * in px cannot: the reef is drawn against the window it is in, so a clownfish
+ * measured in px is a whale on a phone. A hand's length of fish against a
+ * dinner plate of host is what the two of them come to in the water, and this
+ * keeps it that way at any size.
+ */
+const BODY = 0.3
+
+const BODY_SPAN = 0.3
+
+/**
+ * How fast it swims, in body lengths a second, and how much of that it keeps
+ * once it has arrived somewhere.
+ *
+ * The hover is the important half. A clownfish at station is not still, it is
+ * holding against the water with its whole body going, and a fish that stopped
+ * dead between runs would read as a sticker somebody moved.
+ */
+const PACE = 2.6
+
+const HOVER = 0.35
+
+/** How much faster a frightened one goes. */
+const BOLT = 2.2
+
+/** How long it holds a station before choosing another, in seconds. */
+const HOLD_LEAST = 0.6
+
+const HOLD_SPAN = 1.9
+
+/**
+ * How far from its anemone it will go, in body lengths.
+ *
+ * Short, and shorter than the reef is wide, which is the point of it. The fish
+ * is bound to the reef because it is bound to one anemone on the reef, so a
+ * reef with anemones at both ends has fish at both ends and a bare stretch in
+ * between, rather than a herd milling evenly over the whole rock.
+ */
+const RANGE = 9
+
+/** How close counts as arrived, in body lengths. */
+const ARRIVE = 0.6
+
+/** How far above the rock it keeps, in body lengths. */
+const CLEAR = 0.9
+
+/** How quickly it eases onto the line it wants, as a share a second. */
+const EASE = 4.5
+
+/**
+ * How far it waggles off its line, in body lengths a second.
+ *
+ * A clownfish does not hold a line. It rows itself along on its pectorals with
+ * its whole body rocking, so the path is a wobble with a direction to it, and
+ * the wobble is most of what tells this animal from a fish that is going
+ * somewhere. It is taken across the line of travel rather than up the picture,
+ * because a fish rising to the top of the anemone rocks side to side as much as
+ * one crossing it does.
+ */
+const WAGGLE = 1.4
+
+/** How far it goes per beat of its tail, in body lengths. */
+const STRIDE = 0.42
+
+/**
+ * How fast it comes about, in units of `Nemo.face` a second.
+ *
+ * Quick. The turn is the one moment the drawing is not an animal, so what it
+ * has to be is over: slow enough that nothing jumps between two frames, fast
+ * enough that nobody watching gets a good look at the edge-on frame.
+ */
+const FLIP = 7
+
+/** How slowly it has to be going before it will come about, in body lengths. */
+const FLIP_BELOW = 0.9
+
+/** How long a fright lasts, in seconds. */
+const FRIGHT_FADE = 4.5
+
+/**
+ * How far off a thing is minded from, against how big across it is.
+ *
+ * Against its size, because that is what being noticed actually depends on. A
+ * fixed reach makes a passing turtle and a passing whale equally alarming at
+ * the same distance and neither of them alarming at all a moment before, and
+ * what that reads as is a trigger line drawn on the water.
+ */
+const NOTICE = 7
+
+/** How much bigger than the fish a thing has to be before it minds it. */
+const MINDS = 1.6
+
+/**
+ * How alarming something with no menace about it is, at its worst.
+ *
+ * Not nothing. A turtle going over is a shadow going over, and every small fish
+ * on a reef looks up at a shadow; what it does not do is leave. So the plain
+ * bulk of a thing buys a quickening and never more than one, and the rest of
+ * the reading is what it looks like it eats.
+ */
+const BULK = 0.4
+
+/**
+ * How frightened it has to be to give up on where it was going.
+ *
+ * Above what the bulk of a harmless thing can buy on its own, deliberately. A
+ * shadow quickens a fish and a hunter sends it home, and the line between them
+ * is here.
+ */
+const FRIGHT_HOME = 0.55
+
+/** How fast it works its way into the tentacles and back out, a share a second. */
+const COVER_IN = 2.4
+
+const COVER_OUT = 0.7
+
+/** How close to home it has to be to get inside, in body lengths. */
+const COVER_NEAR = 1.2
+
+/**
+ * How alarming a thing has to be before the female goes out to meet it.
+ *
+ * Read off what she is looking at rather than off her own fright, because she
+ * is the one fish here who barely has any, and a threshold on the fright of an
+ * animal picked for not being frightened would never be crossed.
+ */
+const CHARGE_AT = 0.3
+
+/** How long she keeps at it after the thing has gone, in seconds. */
+const CHARGE_FADE = 2.4
+
+/** How many places it will ask the reef about before settling for home. */
+const TRIES = 12
+
+export function createNemos(options: NemosOptions): Nemos {
+  const reef = options.reef
+  const random = makeRandom(options.seed ^ 0x6f2d)
+
+  const nemos: Nemo[] = []
+
+  /** The anemones on this reef, which is the whole of where a fish may live. */
+  const anemones = (): Head[] => reef.heads.filter((one) => one.kind === "anemone")
+
+  /**
+   * A station somewhere over the reef, or home if the reef offered nothing.
+   *
+   * The fish proposes and the reef disposes. Nothing here works out where the
+   * rock is or how far the reef reaches; it asks, and asks again if the answer
+   * was no, which is why the same routine serves a reef of any shape.
+   */
+  function station(one: Nemo): Point {
+    const reach = RANGE * one.length
+
+    for (let tries = 0; tries < TRIES; tries++) {
+      const angle = random() * Math.PI * 2
+      const out = Math.sqrt(random()) * reach
+      const x = one.host.x + Math.cos(angle) * out
+      const y = one.host.y + Math.sin(angle) * out
+
+      if (!reef.holds(x, y, one.host.depth)) continue
+      if (y > reef.surfaceAt(x, one.host.depth) - CLEAR * one.length) continue
+
+      return { x, y }
+    }
+
+    return { x: one.host.x, y: one.host.y - CLEAR * one.length }
+  }
+
+  /** One fish, at its place in the queue, facing whichever way it turned out. */
+  function settle(host: Head, rank: number): Nemo {
+    const queue = Math.max(RANK_LEAST, 1 - rank * RANK_STEP)
+    const length = host.span * BODY * queue * (1 - BODY_SPAN / 2 + random() * BODY_SPAN)
+    const x = host.x + (random() - 0.5) * host.span
+    // Above the rock at its own x rather than above the anemone's. A household
+    // is spread across the width of its host, and the rock under one end of
+    // that spread is not the rock under the middle of it.
+    const y = Math.min(host.y, reef.surfaceAt(x, host.depth)) - CLEAR * length
+
+    return {
+      aim: { x, y },
+      beat: random() * Math.PI * 2,
+      charge: 0,
+      cover: 0,
+      face: random() < 0.5 ? -1 : 1,
+      fright: 0,
+      hold: random() * HOLD_SPAN,
+      host,
+      lane: random() * Math.PI * 2,
+      length,
+      nerve: Math.min(NERVE_JUMPY, NERVE_BOLD + rank * NERVE_RUNG),
+      rank,
+      tilt: 0,
+      vx: 0,
+      vy: 0,
+      x,
+      y,
+    }
+  }
+
+  function populate(): void {
+    const most = Math.max(0, options.count ?? Number.POSITIVE_INFINITY)
+    nemos.length = 0
+
+    for (const host of anemones()) {
+      const group = GROUP_LEAST + Math.floor(random() * (GROUP_SPAN + 1))
+      for (let made = 0; made < group && nemos.length < most; made++) {
+        nemos.push(settle(host, made))
+      }
+    }
+  }
+
+  /** Onto the line it wants, at the speed it wants, with its tail going. */
+  function swim(one: Nemo, dt: number): void {
+    const toX = one.aim.x - one.x
+    const toY = one.aim.y - one.y
+    const away = Math.hypot(toX, toY)
+    const near = away < ARRIVE * one.length
+
+    const stirred = Math.max(one.fright, one.charge)
+    const pace = (near ? HOVER : 1) * PACE * (1 + stirred * BOLT) * one.length
+    const wantX = away > 0 ? (toX / away) * pace : 0
+    const wantY = away > 0 ? (toY / away) * pace : 0
+
+    const rate = Math.min(1, EASE * dt)
+    one.vx += (wantX - one.vx) * rate
+    one.vy += (wantY - one.vy) * rate
+
+    const speed = Math.hypot(one.vx, one.vy)
+    one.beat += (speed / Math.max(1, STRIDE * one.length)) * dt * Math.PI * 2
+
+    const roll = Math.sin(one.beat + one.lane) * WAGGLE * one.length
+    const sideX = speed > 0 ? -(one.vy / speed) * roll : 0
+    const sideY = speed > 0 ? (one.vx / speed) * roll : 0
+
+    one.x += (one.vx + sideX) * dt
+    one.y += (one.vy + sideY) * dt
+  }
+
+  /**
+   * Back onto the reef, if that step took it off.
+   *
+   * A refusal rather than a correction, and it is given the place the fish came
+   * from rather than working one out from the speed, because the waggle moves
+   * it as well and a step undone by halves lands somewhere it never was. Where
+   * it wanted to go was somewhere the reef agreed to, so this only fires when
+   * the reef has moved under it or the waggle threw it wide, and in both cases
+   * the honest answer is that the fish never went there.
+   */
+  function keep(one: Nemo, fromX: number, fromY: number): void {
+    const top = reef.surfaceAt(one.x, one.host.depth) - CLEAR * one.length
+
+    if (one.y > top && reef.holds(one.x, top, one.host.depth)) {
+      one.y = top
+      one.vy = Math.min(one.vy, 0)
+    }
+
+    if (reef.holds(one.x, one.y, one.host.depth)) return
+
+    one.x = fromX
+    one.y = fromY
+    one.vx = 0
+    one.vy = 0
+    one.hold = 0
+    one.aim = { x: one.host.x, y: one.host.y - CLEAR * one.length }
+  }
+
+  /** Coming about, which it will only do once it has stopped. */
+  function turn(one: Nemo, dt: number): void {
+    const speed = Math.hypot(one.vx, one.vy)
+    const slow = speed < FLIP_BELOW * one.length
+    const want = slow && Math.abs(one.vx) > 0 ? Math.sign(one.vx) : Math.sign(one.face) || 1
+    const step = FLIP * dt
+
+    one.face += Math.min(Math.max(want - one.face, -step), step)
+    one.tilt = drawnTilt(Math.atan2(one.vy, Math.abs(one.vx)), Math.sign(one.face) || 1)
+  }
+
+  /**
+   * How alarmed this fish is by what it can see of the water, right now.
+   *
+   * Its own reading, taken fresh every step rather than remembered, so a thing
+   * that came near and went away leaves nothing behind but the fright already
+   * fading. The nearest thing wins; a fish being approached by two of something
+   * is not twice as frightened, it is frightened.
+   */
+  function minded(one: Nemo, water: readonly Presence[]): { alarm: number; at: Presence | null } {
+    let alarm = 0
+    let at: Presence | null = null
+
+    for (const thing of water) {
+      if (thing.size < one.length * 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.host.depth, thing.depth)
+      const worry = near * (BULK + (thing.menace ?? 0) * (1 - BULK))
+      if (worry <= alarm) continue
+
+      alarm = worry
+      at = thing
+    }
+
+    return { alarm, at }
+  }
+
+  /**
+   * Where the female goes to meet something, which is towards it.
+   *
+   * As far towards it as the reef will let her and no further, so the fish that
+   * never leaves the rock does not leave the rock to see something off. She
+   * works out along that line until the reef stops agreeing, which is the same
+   * asking `station` does and the same refusal.
+   */
+  function meet(one: Nemo, at: Presence): Point {
+    const home = { x: one.host.x, y: one.host.y - CLEAR * one.length }
+    const toX = at.x - one.host.x
+    const toY = at.y - one.host.y
+    const away = Math.hypot(toX, toY)
+    if (away < 1) return home
+
+    const out = Math.min(away, RANGE * one.length)
+    for (let back = TRIES; back >= 1; back--) {
+      const reach = out * (back / TRIES)
+      const x = one.host.x + (toX / away) * reach
+      const y = one.host.y + (toY / away) * reach
+
+      if (!reef.holds(x, y, one.host.depth)) continue
+      if (y > reef.surfaceAt(x, one.host.depth) - CLEAR * one.length) continue
+
+      return { x, y }
+    }
+
+    return home
+  }
+
+  /** Into the tentacles while it is frightened, and out again once it is not. */
+  function hide(one: Nemo, dt: number): void {
+    const home = Math.hypot(one.x - one.host.x, one.y - one.host.y) < COVER_NEAR * one.length
+    const want = one.fright > FRIGHT_HOME && home ? 1 : 0
+    const rate = (want > one.cover ? COVER_IN : COVER_OUT) * dt
+
+    one.cover += Math.min(Math.max(want - one.cover, -rate), rate)
+  }
+
+  populate()
+
+  return {
+    nemos,
+
+    resettle() {
+      populate()
+    },
+
+    step(seconds) {
+      const dt = Math.min(Math.max(seconds, 0), 0.1)
+      const water = options.about?.() ?? []
+
+      for (const one of nemos) {
+        const seen = minded(one, water)
+        const goes = one.rank === 0 && seen.at != null && seen.alarm > CHARGE_AT
+
+        one.fright = Math.max(0, Math.max(one.fright - dt / FRIGHT_FADE, seen.alarm * one.nerve))
+        one.charge = Math.max(0, Math.max(one.charge - dt / CHARGE_FADE, goes ? seen.alarm : 0))
+        one.hold -= dt
+
+        if (goes && seen.at != null) {
+          one.aim = meet(one, seen.at)
+        } else if (one.fright > FRIGHT_HOME) {
+          one.aim = { x: one.host.x, y: one.host.y - CLEAR * one.length }
+        } else if (one.hold <= 0) {
+          one.hold = HOLD_LEAST + random() * HOLD_SPAN
+          one.aim = station(one)
+        }
+
+        const fromX = one.x
+        const fromY = one.y
+
+        swim(one, dt)
+        keep(one, fromX, fromY)
+        turn(one, dt)
+        hide(one, dt)
+      }
+    },
+  }
+}