@codincod/ornament 0.0.0-stage → 0.2.0

package/src/cephalopods.ts

@@ -0,0 +1,1041 @@
+/**
+ * Squid in the water, octopuses on the floor.
+ *
+ * Kept free of the DOM the way the rest of the ornament is, and kept apart from
+ * `shoal.ts` because a cephalopod is not a fish with different steering. A fish
+ * is a body that beats continuously and travels continuously; these two are
+ * neither, and the whole reason for having them in the scene is that they break
+ * the rhythm everything else keeps.
+ *
+ * ## The squid, and why it is worth the trouble
+ *
+ * A shoal, however well steered, settles into one tempo. Every animal in it is
+ * always swimming, so the water has a background rate and after a minute the
+ * eye has it. A squid does not have a rate. It hangs, does nothing, then goes,
+ * hard, and hangs again.
+ *
+ * That is one cycle with two very unequal halves:
+ *
+ *   * **Filling.** Most of the cycle. The mantle swells, the animal barely
+ *     moves, and what movement there is is the water carrying it. The arms
+ *     spread because nothing is holding them.
+ *   * **The jet.** A fraction of it. The mantle snaps thin, the arms are pulled
+ *     into a point, and the animal covers more ground than it did in the whole
+ *     of the fill.
+ *
+ * The mantle drives the speed rather than the other way round, which is the
+ * same rule `shoal.ts` uses for a tail and for the same reason: an animal whose
+ * drawing and whose travel come off one number cannot fall out of step with
+ * itself.
+ *
+ * It never turns round, for the reason `Fish.facing` gives. A squid mirrored
+ * mid-glide would be worse than a fish mirrored, because there is no beat to
+ * hide the frame it happens on.
+ *
+ * ## The octopus
+ *
+ * Not in the water at all. It is on the bottom, which is the point: everything
+ * else in this scene is suspended, and an animal in contact with the ground is
+ * what tells you the ground is solid.
+ *
+ * It works along the floor rather than swimming over it, so its height comes
+ * from the seabed under it and never from a decision of its own. The arms are
+ * the whole animal, each on its own phase and none of them the same length.
+ *
+ * ## What it does with the day, and where the numbers came from
+ *
+ * It had two behaviours to begin with, a crawl and a jet, and it alternated
+ * them for as long as anybody watched. That is not an animal. It is a duty
+ * cycle, and the eye has the whole of it inside a few seconds.
+ *
+ * So the repertoire is taken off field work rather than invented. Sultan et
+ * al., "Deception in the dark, an ethogram of Callistoctopus furvus", Journal
+ * of Molluscan Studies 91(3), 2025, scored wild octopuses frame by frame and
+ * reported what share of watched time went to each behaviour. `DOINGS` is that
+ * table, one row a behaviour, and two of its findings are the whole reason for
+ * this rewrite:
+ *
+ *   * **Most of an octopus is not travel.** Between sitting still and working
+ *     its arms into crevices without moving the body, close to two fifths of
+ *     the day goes to being somewhere rather than going somewhere. The old one
+ *     had no way of not crawling except to jet.
+ *   * **Jetting is a small part of it, and it is an answer.** It is the second
+ *     line of defence, after not being seen has failed, so most of it is
+ *     provoked. `UNPROVOKED` splits the measured share: that much is the
+ *     animal's own idea and the rest waits for a `Startle`, which is what a
+ *     hull going over hands down.
+ *
+ * The pick weights come off `DOINGS` rather than being tuned by hand, because a
+ * bout is a length of time and the long behaviours would otherwise swallow the
+ * day. Adding another behaviour is a row here and a posture in `POSTURES`.
+ *
+ * The speeds come off the same shelf. Huffard, "Locomotion by Abdopus
+ * aculeatus", Journal of Experimental Biology 209, 2006, timed the modes: a
+ * crawl at 0.62 body lengths a second, a walk on the back arms at rather more
+ * than twice that, a jet at under three times it and five at the very top. The
+ * old jet was nearly nine times the crawl, which is why it read as a firework
+ * rather than an escape. What is kept off that paper is the ratios; this water
+ * runs slower than the sea on purpose, and everything in it does.
+ */
+
+import { makeRandom } from "./perlin.ts"
+import type { Point } from "./seabed.ts"
+import { drawnTilt, felt, type Startle } from "./shoal.ts"
+import { BED_OFF, drawnAt, SWIMMING_OFF } from "./sizes.ts"
+
+export interface Squid {
+  /** 0 is as far off as this water goes, 1 is up against the glass. */
+  readonly depth: number
+  /** Which way it points, once and for life: 1 rightward, -1 left. */
+  readonly facing: number
+  /** Radians, and always inside a shallow cone off level. */
+  heading: number
+  /** Nose to arm tip in px, depth already taken out of it. */
+  readonly size: number
+  /** px/s, which is whatever the mantle is doing. */
+  speed: number
+  /**
+   * How hard the mantle is squeezed, 0 slack and 1 shut.
+   *
+   * The one number the drawing and the travel are both read off.
+   */
+  squeeze: number
+  /**
+   * How far to rotate the drawing, in radians, after mirroring it by `facing`.
+   *
+   * Not the heading; see `Fish.tilt`, which this is the same fact as and for
+   * the same reason. A squid mirrors exactly as a fish does, and every
+   * renderer got the angle backwards for a leftward one, so it jetted up the
+   * screen while pointing down it.
+   */
+  tilt: number
+  x: number
+  y: number
+}
+
+/** One of the behaviours `DOINGS` scores, and the whole of what an octopus does. */
+export type OctopusDoing =
+  | "bury"
+  | "crawl"
+  | "handle"
+  | "jet"
+  | "pounce"
+  | "probe"
+  | "rest"
+  | "stilt"
+
+export interface Octopus {
+  /**
+   * How full the mantle is, 0 empty and 1 swelled.
+   *
+   * Ventilation, which never stops. It is the only thing a stopped octopus has
+   * to say it is alive: at this size an animal holding still with nothing
+   * moving on it is a stone, which is a compliment to the camouflage and a
+   * problem for the picture.
+   */
+  breath: number
+  /** How far through its own gait it is, which is what moves the arms. */
+  crawl: number
+  readonly depth: number
+  /** What it is doing. `DOINGS` says how likely that was and how long it runs. */
+  doing: OctopusDoing
+  /**
+   * Which way it points: 1 rightward, -1 left.
+   *
+   * It turns, which a squid never does, and the reason the two differ is that
+   * an octopus has moments of standing still to turn in. See `take`.
+   */
+  facing: number
+  /**
+   * How hard it is being driven right now, 0 at rest and 1 mid-jet.
+   *
+   * The arms are read off this rather than off the speed, because the two are
+   * not the same thing: an arm streams because the water is going past it, and
+   * the water is going past it hardest at the moment of the push.
+   */
+  haul: number
+  /** How far off the floor it is, in its own head widths. Below it when buried. */
+  lift: number
+  /** How far the arms are thrown out, 0 gathered under it and 1 stretched. */
+  reach: number
+  /** Head width in px, depth already taken out of it. */
+  readonly size: number
+  x: number
+  /** Where it is. The floor decides this while it is on the floor. */
+  y: number
+}
+
+export interface Cephalopods {
+  readonly octopuses: readonly Octopus[]
+  resize(width: number, height: number, floor: (x: number) => number): void
+  readonly squids: readonly Squid[]
+  /**
+   * Advance by `seconds`. `startle` is whatever the water is being told to do
+   * this tick, which the octopuses answer and the squid do not: a squid is
+   * already somewhere else, and an animal sitting on the ground is the one with
+   * a reason to care that something went over.
+   */
+  step(seconds: number, startle?: Startle | null): void
+}
+
+export interface CephalopodOptions {
+  floor: (x: number) => number
+  height: number
+  octopuses?: number
+  seed: number
+  squids?: number
+  width: number
+}
+
+/** How long one jet cycle lasts, slowest to fastest, in seconds. */
+const CYCLE_SLOWEST = 3.4
+
+const CYCLE_FASTEST = 6.8
+
+/**
+ * What share of the cycle is the jet itself.
+ *
+ * Small, and it has to be. Give the push a third of the cycle and the animal
+ * reads as swimming badly rather than as jetting; give it a tenth and the
+ * stillness before it becomes the thing you notice, which is correct.
+ */
+const JET_SHARE = 0.16
+
+/** How fast a squid travels at the peak of a jet, in its own lengths a second. */
+const JET_PEAK = 4.2
+
+/** What it keeps while filling, as a share of that. Nearly nothing. */
+const GLIDE = 0.07
+
+/** How fast it sheds speed once the jet is over, per second. */
+const DRAG = 2.1
+
+/**
+ * The ends of a squid's length, in metres, mantle and arms together.
+ *
+ * A reef squid rather than anything from deep water, and `sizes.ts` puts it at
+ * the same distance the rest of the water swims at, so a squid crossing in
+ * front of a shoal is the size a squid is beside those fish.
+ */
+const SQUID_SHORTEST = 0.16
+
+const SQUID_LONGEST = 0.38
+
+/** How steeply a squid may travel, either side of level. */
+const SQUID_PITCH = 0.42
+
+/** How far its line wanders while it fills, and how fast it takes a new one. */
+const WANDER = 0.5
+
+const RETHINK_LEAST = 2.5
+
+const RETHINK_SPAN = 5
+
+/** How far down the water a squid is ever born. They belong to the open water
+ *  above the bed, and one that starts in the weeds looks like a mistake. */
+const ROOF = 0.72
+
+/** How far past the sides one goes before it comes back on the other. */
+const MARGIN = 1.1
+
+/**
+ * How near the top or the bed a squid gets before it starts turning away, in
+ * its own lengths, and how hard it leans on the line it was holding.
+ *
+ * It used to have no opinion about either. The step ended by clamping it back
+ * inside the water, so an animal that had drifted up spent the next several
+ * seconds sliding along the ceiling still nosed at it, which reads exactly like
+ * an animal swimming in one direction and facing another. The clamp is still
+ * there underneath, because a jet is fast enough to cross this band inside one
+ * frame, but nothing should ever reach it.
+ *
+ * The pull is stronger than `WANDER` on purpose. A squid that argued with the
+ * surface would be a squid that lost.
+ */
+const SHY_BAND = 2.4
+
+const SHY_PULL = 1.4
+
+/**
+ * The ends of an octopus's head across, in metres.
+ *
+ * The head and not the animal, which is the number this file draws from and is
+ * about a fifth of what the arms reach. `sizes.ts` turns it into a share of the
+ * box at the distance the floor lies at, so an octopus at the mouth of a den
+ * and a crab going past it are the sizes they are against each other.
+ */
+const OCTOPUS_SMALLEST = 0.09
+
+const OCTOPUS_LARGEST = 0.17
+
+/**
+ * The repertoire, and what share of a life each behaviour takes.
+ *
+ * `share` is measurement: the percentage of watched time the ethogram in the
+ * module note scored for each, with its burying and its going to ground added
+ * together because at this size they are the same picture. The rest of the
+ * table is judgement, and the note says which is which so nobody tunes the
+ * wrong column. `least` and `span` are how long one bout runs here, in
+ * seconds, which no ethogram reports.
+ */
+const DOINGS: Readonly<Record<OctopusDoing, { least: number; share: number; span: number }>> = {
+  /** Into the sand and out of sight, which is its first answer to anything. */
+  bury: { least: 7, share: 9.65, span: 13 },
+  crawl: { least: 2.5, share: 41.29, span: 4.5 },
+  /** Hunched over whatever it caught, arms knotted underneath it. */
+  handle: { least: 3, share: 0.85, span: 4 },
+  jet: { least: 1.2, share: 4.79, span: 0.8 },
+  /** The parachute: arms opened into a bell and dropped over a stone. */
+  pounce: { least: 0.9, share: 0.65, span: 0.6 },
+  /** Body still, arms into the crevices without it. The one it lives on. */
+  probe: { least: 3, share: 21.82, span: 6 },
+  rest: { least: 5, share: 17.41, span: 11 },
+  /** Walking on the back pair, with the rest coiled up over it. */
+  stilt: { least: 1.5, share: 0.8, span: 2.5 },
+}
+
+/**
+ * What share of jetting is the animal's own idea.
+ *
+ * The ethogram counts every jet it saw, and a good deal of what a wild octopus
+ * jets away from is the person holding the camera. Here the thing that turns up
+ * is a `Startle`, so the measured share is split in two: this much happens
+ * unasked and the rest waits to be provoked. Left whole, every octopus in the
+ * scene would be bolting from nothing several times a minute, which is what the
+ * old one did and what this is for.
+ */
+const UNPROVOKED = 0.2
+
+/**
+ * How near and how hard a startle has to be felt before it lets go.
+ *
+ * Under this the answer is to stop being visible rather than to leave, and that
+ * is the right way round. An octopus's first defence is that you did not see
+ * it. The jet is what is left when that has failed.
+ */
+const BOLT = 0.45
+
+/** The behaviours it is standing still through, and so can turn round in. */
+const STILL: ReadonlySet<OctopusDoing> = new Set<OctopusDoing>(["bury", "handle", "probe", "rest"])
+
+/** How likely it is to have turned round by the end of one of those. */
+const TURN_ODDS = 0.35
+
+/**
+ * How far it gets in one pull, in head widths a second at the peak of it.
+ *
+ * Higher than the old steady pace it replaces, and it has to be: half the
+ * cycle is now a gather where it does not move at all, so the same ground has
+ * to be covered in half the time or the animal is slower than it was as well
+ * as jerkier.
+ */
+const CRAWL_REACH = 0.62
+
+/** How far it comes up off the floor as it pulls, in its own head widths. */
+const CRAWL_RISE = 0.06
+
+/** How fast its arms work through their gait, in cycles a second. */
+const GAIT = 0.55
+
+/**
+ * How fast it walks on the back pair, in head widths a second.
+ *
+ * Steady rather than pulsed, which is the difference between the two gaits: a
+ * crawl is a haul and a rest and a haul, and a walk on two arms is a walk. The
+ * timing work put it at rather more than twice a crawl and that is what this is.
+ */
+const STILT_PACE = 0.48
+
+/** How far up it stands to do it, in its own head widths. */
+const STILT_RISE = 0.42
+
+/** How deep it sinks when it buries, in its own head widths. */
+const BURY_DEPTH = 0.62
+
+/**
+ * How fast a jet goes at the peak of it, in head widths a second.
+ *
+ * It was nearly nine times the crawl and it read as a firework going off. The
+ * timing work puts a jet at under three times a crawl on the mean and five at
+ * the very top of the range, so this is the top of that and no further.
+ */
+const JET_RUSH = 1.6
+
+/** How far off the floor a jet takes it, in its own head widths. */
+const JET_HEIGHT = 2.2
+
+/** How fast it ventilates when it is idle, in cycles a second. */
+const BREATH_CALM = 0.42
+
+/** And how much more of that a hard haul adds, because working costs air. */
+const BREATH_WORKED = 1.6
+
+/** How far the arms stream behind, standing still and at full drive. */
+const TRAIL_HELD = 0.22
+
+const TRAIL_DRIVEN = 1.15
+
+/** How far back these stand. Squid keep out of the very front of the glass. */
+const DEPTH_FAR = 0.15
+
+const DEPTH_NEAR = 0.85
+
+/** How much of a body's drawn size, and with it its speed, is its depth. */
+const DEPTH_SIZE = 0.6
+
+const MIN_SPAN = 1
+
+interface Beat {
+  /** The line it is holding, and how long before it takes another. */
+  aim: number
+  /** Seconds into the current cycle. */
+  at: number
+  hold: number
+  /** How long this cycle runs. */
+  span: number
+}
+
+/** One octopus's turn at one behaviour, and its breathing, which outlasts it. */
+interface Bout {
+  /** Seconds into it. */
+  at: number
+  /** How far through a ventilation it is, in turns. */
+  puff: number
+  /** How long this one runs. */
+  span: number
+}
+
+export function createCephalopods(options: CephalopodOptions): Cephalopods {
+  const random = makeRandom(options.seed ^ 0x0c70)
+
+  let width = Math.max(MIN_SPAN, options.width)
+  let height = Math.max(MIN_SPAN, options.height)
+  let floor = options.floor
+
+  const squids: Squid[] = []
+  const octopuses: Octopus[] = []
+  const beats: Beat[] = []
+  const bouts: Bout[] = []
+
+  function bornSquid(): Squid {
+    const depth = DEPTH_FAR + random() * (DEPTH_NEAR - DEPTH_FAR)
+    const facing = random() < 0.5 ? -1 : 1
+    const long = SQUID_SHORTEST + random() * (SQUID_LONGEST - SQUID_SHORTEST)
+    const length = drawnAt(long, SWIMMING_OFF) * width
+    const aim = (random() - 0.5) * WANDER
+    const x = random() * width
+    const size = length * (1 - DEPTH_SIZE + DEPTH_SIZE * depth)
+
+    // Inside the water it is allowed, and not merely inside the box. One born
+    // over the surface was shoved back under it on its first frame, which is a
+    // squid travelling a body length sideways in a thirtieth of a second.
+    const top = size * MARGIN
+    const bed = Math.max(top, Math.min(floor(x) - size * 0.4, height * ROOF))
+
+    beats.push({
+      aim,
+      at: random() * CYCLE_SLOWEST,
+      hold: RETHINK_LEAST + random() * RETHINK_SPAN,
+      span: CYCLE_SLOWEST + random() * (CYCLE_FASTEST - CYCLE_SLOWEST),
+    })
+
+    return {
+      depth,
+      facing,
+      heading: point(facing, aim),
+      size,
+      speed: 0,
+      squeeze: 0,
+      tilt: drawnTilt(point(facing, aim), facing),
+      x,
+      y: top + random() * (bed - top),
+    }
+  }
+
+  /** How long one bout of this lasts, drawn out of `DOINGS`. */
+  function span(doing: OctopusDoing): number {
+    const row = DOINGS[doing]
+    return row.least + random() * row.span
+  }
+
+  /**
+   * Put it on to something else.
+   *
+   * It turns while it is standing still and never while it is going, which is
+   * the same rule `Squid.facing` states in its harder form. Flipping a moving
+   * animal swaps which way its arms stream between two frames, and what that
+   * reads as is the drawing being replaced rather than the animal turning
+   * round. Standing still there is nothing streaming to swap.
+   */
+  function take(one: Octopus, bout: Bout, doing: OctopusDoing): void {
+    if (STILL.has(one.doing) && random() < TURN_ODDS) one.facing = -one.facing
+    one.doing = doing
+    bout.at = 0
+    bout.span = span(doing)
+  }
+
+  function bornOctopus(): Octopus {
+    const depth = DEPTH_FAR + random() * (DEPTH_NEAR - DEPTH_FAR)
+    const doing = pick(random)
+    const across = OCTOPUS_SMALLEST + random() * (OCTOPUS_LARGEST - OCTOPUS_SMALLEST)
+    const head = drawnAt(across, BED_OFF) * width
+    const run = span(doing)
+    const x = random() * width
+
+    // Part way through it already. A scene that opened with every octopus on
+    // the first frame of the same fresh bout would spend its first minute in
+    // lockstep, which is the one minute anybody is certain to watch.
+    bouts.push({ at: random() * run, puff: random(), span: run })
+
+    return {
+      breath: 0,
+      crawl: random() * Math.PI * 2,
+      depth,
+      doing,
+      facing: random() < 0.5 ? -1 : 1,
+      haul: 0,
+      lift: 0,
+      reach: 1,
+      size: head * (1 - DEPTH_SIZE + DEPTH_SIZE * depth),
+      x,
+      y: floor(x),
+    }
+  }
+
+  function stock(): void {
+    squids.length = 0
+    octopuses.length = 0
+    beats.length = 0
+    bouts.length = 0
+
+    for (let made = 0; made < Math.max(0, options.squids ?? 0); made++) squids.push(bornSquid())
+    for (let made = 0; made < Math.max(0, options.octopuses ?? 0); made++) {
+      octopuses.push(bornOctopus())
+    }
+  }
+
+  stock()
+
+  return {
+    octopuses,
+
+    resize(nextWidth, nextHeight, nextFloor) {
+      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)
+      floor = nextFloor
+
+      for (const one of squids) {
+        one.x *= scaleX
+        one.y *= scaleY
+      }
+      for (const one of octopuses) {
+        one.x *= scaleX
+        one.y = floor(one.x) - one.lift * one.size
+      }
+    },
+    squids,
+
+    step(seconds, startle) {
+      const dt = Math.min(Math.max(seconds, 0), 0.1)
+
+      for (let at = 0; at < squids.length; at++) {
+        const one = squids[at]
+        const beat = beats[at]
+        if (!one || !beat) continue
+
+        beat.at += dt
+        if (beat.at >= beat.span) {
+          beat.at -= beat.span
+          beat.span = CYCLE_SLOWEST + random() * (CYCLE_FASTEST - CYCLE_SLOWEST)
+        }
+
+        // The mantle first, and everything else read off it.
+        const through = beat.at / beat.span
+        one.squeeze = through < JET_SHARE ? Math.sin((through / JET_SHARE) * Math.PI) : 0
+
+        const push = one.squeeze * JET_PEAK * one.size
+        const glide = GLIDE * JET_PEAK * one.size
+        one.speed =
+          push > one.speed ? push : glide + (one.speed - glide) * Math.max(0, 1 - DRAG * dt)
+
+        beat.hold -= dt
+        if (beat.hold <= 0) {
+          beat.aim = (random() - 0.5) * WANDER
+          beat.hold = RETHINK_LEAST + random() * RETHINK_SPAN
+        }
+
+        // Eased rather than set. `beat.aim` is a fresh number every few
+        // seconds, and a body that took it whole snapped onto the new line
+        // between two frames: the squid appeared to twitch round rather than
+        // turn, which is the one thing a drifting animal must not do.
+        const edge = one.size * MARGIN
+        const bed = floor(one.x) - one.size * 0.4
+
+        one.heading = ease(
+          one.heading,
+          point(one.facing, beat.aim + shy(one.y, edge, bed, one.size)),
+          TURN * dt,
+        )
+        one.tilt = drawnTilt(one.heading, one.facing)
+        one.x += Math.cos(one.heading) * one.speed * dt
+        one.y += Math.sin(one.heading) * one.speed * dt
+
+        if (one.x > width + edge) one.x = -edge
+        if (one.x < -edge) one.x = width + edge
+        one.y = Math.min(Math.max(one.y, edge), bed)
+      }
+
+      for (let at = 0; at < octopuses.length; at++) {
+        const one = octopuses[at]
+        const bout = bouts[at]
+        if (!one || !bout) continue
+
+        // Breathing outlasts the bout and is the one thing here that never
+        // stops, so it is stepped before anything gets a say in it.
+        bout.puff = (bout.puff + (BREATH_CALM + one.haul * BREATH_WORKED) * dt) % 1
+        one.breath = (1 - Math.cos(bout.puff * Math.PI * 2)) / 2
+
+        // Something went over. Hard and near enough and it leaves; anything
+        // less and it goes into the sand, which is the answer it prefers.
+        const felt = pressure(startle, one)
+        if (felt > BOLT) {
+          if (one.doing !== "jet") take(one, bout, "jet")
+        } else if (felt > 0 && one.doing !== "jet" && one.doing !== "bury") {
+          take(one, bout, "bury")
+        }
+
+        bout.at += dt
+        if (bout.at >= bout.span) take(one, bout, pick(random))
+
+        const through = Math.min(1, bout.at / bout.span)
+        advance(one, through, dt)
+
+        const edge = one.size * MARGIN
+        if (one.x > width + edge) one.x = -edge
+        if (one.x < -edge) one.x = width + edge
+        one.y = floor(one.x) - one.lift * one.size
+      }
+    },
+  }
+}
+
+/**
+ * The ladder the next behaviour is drawn off, each rung a running total.
+ *
+ * Built once, because `DOINGS` never moves.
+ */
+const ODDS = weigh()
+
+/**
+ * How likely each behaviour is to be chosen, given how long it then lasts.
+ *
+ * A bout is a length of time, so drawing straight off `share` would hand the
+ * long behaviours far more of the day than the field work gave them: burying is
+ * a tenth of a life in bouts of a dozen seconds, and a pounce is under a
+ * hundredth in bouts of one. Dividing the share by the mean bout undoes that,
+ * and what comes out at the far end is time spent, which is what was measured.
+ */
+function weigh(): { doing: OctopusDoing; upto: number }[] {
+  const rungs: { doing: OctopusDoing; upto: number }[] = []
+  let total = 0
+
+  for (const doing of Object.keys(DOINGS).sort() as OctopusDoing[]) {
+    const row = DOINGS[doing]
+    const share = doing === "jet" ? row.share * UNPROVOKED : row.share
+    total += share / (row.least + row.span / 2)
+    rungs.push({ doing, upto: total })
+  }
+
+  for (const rung of rungs) rung.upto /= total
+  return rungs
+}
+
+/** What it does next, which is nothing to do with what it was doing. */
+function pick(random: () => number): OctopusDoing {
+  const roll = random()
+  for (const rung of ODDS) if (roll <= rung.upto) return rung.doing
+  return "crawl"
+}
+
+/**
+ * How hard a startle is felt where this one is standing, 0 to 1.
+ *
+ * Linear out to `reach` and nothing past it, and weighed by how much of the
+ * startle reaches this distance at all; see `felt`. A fish and an octopus
+ * disagree about what to do with a startle and agree about how much of it there
+ * is, which is why both of those come off the same two lines in `shoal.ts`.
+ */
+function pressure(startle: Startle | null | undefined, one: Octopus): number {
+  if (!startle || startle.force <= 0 || startle.reach <= 0) return 0
+
+  const gap = Math.hypot(one.x - startle.x, one.y - startle.y)
+  if (gap >= startle.reach) return 0
+
+  return startle.force * (1 - gap / startle.reach) * felt(one.depth, startle)
+}
+
+/**
+ * One octopus, moved on by whatever it happens to be doing.
+ *
+ * Every arm of this sets `haul`, `lift` and `reach`, because the drawing reads
+ * all three every frame and a behaviour that left one of them alone would be
+ * wearing the last one's posture. Only the three that travel touch `x`.
+ */
+function advance(one: Octopus, through: number, dt: number): void {
+  switch (one.doing) {
+    case "bury": {
+      // Down, a while under, and back up. Most of the bout is spent buried, so
+      // the going down and the coming up are quick at either end of it.
+      const under = Math.min(1, Math.min(through, 1 - through) * 6)
+      one.haul = 0
+      one.lift = -BURY_DEPTH * under
+      one.reach = 1 - under * 0.55
+      break
+    }
+
+    case "crawl": {
+      one.crawl += GAIT * dt * Math.PI * 2
+
+      // A step rather than a slide. The old gait never let the pace reach
+      // zero, and an animal that is always moving a little is an animal being
+      // dragged: what says walking is the stop. So the pull is the positive
+      // half of the cycle and the other half is a gather, where it stands
+      // still and brings its arms up under it.
+      one.haul = Math.max(0, Math.sin(one.crawl)) ** 1.4
+      one.lift = one.haul * CRAWL_RISE
+      one.reach = 1
+      one.x += one.facing * CRAWL_REACH * one.haul * one.size * dt
+      break
+    }
+
+    case "handle": {
+      // Hunched over something, arms knotted under the head, and the only
+      // movement is the worrying at it.
+      one.crawl += GAIT * 0.6 * dt * Math.PI * 2
+      one.haul = 0
+      one.lift = 0
+      one.reach = 0.5 + Math.sin(one.crawl) * 0.08
+      break
+    }
+
+    case "jet": {
+      // Off the ground and travelling, arms streamed. The arc is the whole of
+      // it: an octopus that jetted along the floor would be an octopus on
+      // rails, and the reason to jet at all is to leave.
+      one.haul = Math.sin(through * Math.PI) ** 0.6
+      one.lift = Math.sin(through * Math.PI) * JET_HEIGHT
+      one.reach = 1
+      one.x += one.facing * JET_RUSH * one.size * one.haul * dt
+      break
+    }
+
+    case "pounce": {
+      // Open, then shut. Arms thrown wide into a bell, lifted, and dropped
+      // over a stone, and whatever was under the stone is now inside. The
+      // closing is faster than the opening because it is a strike.
+      one.crawl += GAIT * dt * Math.PI * 2
+      one.haul = 0
+      one.lift = Math.sin(Math.min(1, through * 1.6) * Math.PI) * 0.3
+      one.reach =
+        through < 0.55
+          ? 0.5 + Math.min(1, through * 2.2) * 0.6
+          : Math.max(0.25, 1.1 - (through - 0.55) * 6)
+      break
+    }
+
+    case "probe": {
+      // Still, with the arms going where the body does not. This is the one it
+      // spends most of its standing life on, so the sweep is slow enough to
+      // watch: an arm in a crevice takes seconds over it.
+      one.crawl += GAIT * 0.45 * dt * Math.PI * 2
+      one.haul = 0
+      one.lift = 0
+      one.reach = 0.72 + Math.sin(one.crawl * 0.6) * 0.28
+      break
+    }
+
+    case "rest": {
+      one.crawl += GAIT * 0.2 * dt * Math.PI * 2
+      one.haul = 0
+      one.lift = 0
+      one.reach = 0.45 + Math.sin(one.crawl) * 0.05
+      break
+    }
+
+    case "stilt": {
+      // Up on the back pair with the rest coiled over it, and the pace steady:
+      // two arms alternating is a walk, and a walk does not stall the way the
+      // crawl does. It stands up at the start and sits back down at the end,
+      // because appearing at full height is a cut rather than a movement.
+      one.crawl += GAIT * 1.7 * dt * Math.PI * 2
+      const up = Math.min(1, Math.min(through, 1 - through) * 5)
+      one.haul = 0.25
+      one.lift = STILT_RISE * up
+      one.reach = 1
+      one.x += one.facing * STILT_PACE * one.size * up * dt
+      break
+    }
+  }
+}
+
+/**
+ * Which way the water is telling it to go, if it is telling it anything.
+ *
+ * Positive is down, the way `point` reads an aim. Nothing at all through the
+ * middle of the water, which is the point: this is a wall it notices when it is
+ * near one, not a force pulling it to the centre of the picture.
+ */
+function shy(y: number, top: number, bed: number, size: number): number {
+  // Never more than a share of the water, or in a shallow scene the two bands
+  // overlap and the animal is told to go up and down at once. What it did then
+  // was hold still against whichever of the two was winning.
+  const band = Math.max(1, Math.min(size * SHY_BAND, (bed - top) * 0.4))
+  const under = Math.max(0, top + band - y)
+  const over = Math.max(0, y - (bed - band))
+
+  return ((under - over) / band) * SHY_PULL
+}
+
+/** How fast a squid comes round onto a new line, in radians a second. */
+const TURN = 0.9
+
+/** A step of the way from one number to another, and never past it. */
+function ease(from: number, to: number, step: number): number {
+  const gap = to - from
+  return Math.abs(gap) <= step ? to : from + Math.sign(gap) * step
+}
+
+/** The nearest heading a body facing this way is allowed to hold. */
+function point(facing: number, want: number): number {
+  const asked = Math.atan2(Math.sin(want), facing * Math.cos(want))
+  const rel = SQUID_PITCH * Math.tanh(asked / SQUID_PITCH)
+  return facing > 0 ? rel : Math.PI - rel
+}
+
+/**
+ * A squid, drawn at whatever its mantle is doing.
+ *
+ * Built nose-first along positive x with the arms trailing behind the origin,
+ * in a body a unit long, so a renderer scales it by `Squid.size` and mirrors it
+ * by `Squid.facing` exactly as it does a fish.
+ *
+ * The mantle is a leaf: wide where the fins are, drawn to a point at the nose,
+ * and narrowing to the collar where the arms leave. Squeezing it takes width
+ * out and puts length in, because that is where the water went.
+ */
+export function squidBody(squeeze: number): string {
+  const fat = 0.19 - squeeze * 0.07
+  const long = 0.62 + squeeze * 0.1
+  const fin = 0.2 - squeeze * 0.05
+
+  return [
+    `M${long.toFixed(3)} 0`,
+    `Q${(long * 0.55).toFixed(3)} ${(-fat).toFixed(3)} 0 ${(-fat * 0.72).toFixed(3)}`,
+    `L0 ${(fat * 0.72).toFixed(3)}`,
+    `Q${(long * 0.55).toFixed(3)} ${fat.toFixed(3)} ${long.toFixed(3)} 0`,
+    "Z",
+    // The fins, one either side, back where the mantle is widest.
+    `M${(long * 0.52).toFixed(3)} ${(-fat * 0.86).toFixed(3)}`,
+    `Q${(long * 0.86).toFixed(3)} ${(-fat - fin).toFixed(3)} ${(long * 0.97).toFixed(3)} ${(-fat * 0.2).toFixed(3)}`,
+    "Z",
+    `M${(long * 0.52).toFixed(3)} ${(fat * 0.86).toFixed(3)}`,
+    `Q${(long * 0.86).toFixed(3)} ${(fat + fin).toFixed(3)} ${(long * 0.97).toFixed(3)} ${(fat * 0.2).toFixed(3)}`,
+    "Z",
+  ].join(" ")
+}
+
+/**
+ * The arms, as polylines leaving the collar.
+ *
+ * Gathered into a point during a jet and spread while filling, which is not a
+ * flourish: it is the only part of the animal that shows the water it is
+ * pushing against.
+ */
+export function squidArms(squeeze: number, count = 8): Point[][] {
+  const arms: Point[][] = []
+  // Gathered at full squeeze, never shut. Arms folded into a single line make
+  // the animal a dart, and a dart has no arms to notice: what is wanted is a
+  // handful of them held tight, which still reads as a handful.
+  const spread = (1 - squeeze) * 0.44 + 0.2
+
+  for (let made = 0; made < count; made++) {
+    const side = made / (count - 1) - 0.5
+    const lean = side * spread
+    const reach = 0.34 + Math.abs(side) * 0.16
+    const points: Point[] = []
+
+    for (let step = 0; step <= 5; step++) {
+      const t = step / 5
+      points.push({
+        x: -t * reach,
+        y: lean * t * (0.5 + t) + Math.sin(t * 2.6 + side * 5) * 0.03 * (1 - squeeze) * t,
+      })
+    }
+    arms.push(points)
+  }
+
+  return arms
+}
+
+/**
+ * An octopus's mantle, in a head a unit wide sitting on the origin.
+ *
+ * A bag with a waist rather than a dome. The dome is what it was first and the
+ * dome is a mushroom: what tells an octopus from a jellyfish above the arms is
+ * that the mantle narrows where it meets them, so there is a head and then a
+ * gather, and the arms leave the gather.
+ *
+ * `breath` is the ventilation, 0 empty and 1 full, and it takes width in and
+ * lets a little height out, because that is where the water went. It is a small
+ * enough movement that nobody will name it, which is correct: what it is for is
+ * that a stopped octopus is still doing something. Most of this animal's day is
+ * now spent not travelling, and without a breath under it that day is a sprite
+ * that has been left on the ground.
+ */
+export function octopusHead(breath: number): string {
+  const full = Math.min(Math.max(breath, 0), 1)
+  const wide = 1 + full * 0.08
+  const tall = 1 - full * 0.05
+  const w = (at: number): string => (at * wide).toFixed(3)
+  const h = (at: number): string => (at * tall).toFixed(3)
+
+  return [
+    `M${w(-0.3)} ${h(0.14)}`,
+    `Q${w(-0.5)} ${h(-0.06)} ${w(-0.44)} ${h(-0.4)}`,
+    `Q${w(-0.36)} ${h(-0.78)} 0 ${h(-0.8)}`,
+    `Q${w(0.36)} ${h(-0.78)} ${w(0.44)} ${h(-0.4)}`,
+    `Q${w(0.5)} ${h(-0.06)} ${w(0.3)} ${h(0.14)}`,
+    "Z",
+  ].join(" ")
+}
+
+/** The mantle with the breath out of it, for anything wanting a still one. */
+export const OCTOPUS_HEAD = octopusHead(0)
+
+/** How one behaviour holds its arms. Alongside `DOINGS`, a row a behaviour. */
+interface Posture {
+  /** How far the tips curl back up and in towards the body. */
+  curl: number
+  /** How far an arm falls towards the floor along its own length. */
+  drop: number
+  /** How wide the arms are spread across the ground. */
+  fan: number
+  /**
+   * How much longer the leading arms are than the trailing ones.
+   *
+   * The sign is the whole of what tells a probe from a walk on two arms.
+   * Positive reaches forward and tucks the back: the body stays where it is and
+   * the front arms go into the crevice. Negative stands on the back pair and
+   * coils the front over the head, which is the bipedal gait. `curl` follows
+   * it, so whichever end is short is also the end that is curled up.
+   */
+  lead: number
+  /** Arm length, in head widths. */
+  reach: number
+  /** How much the gait moves them at all, 0 held still. */
+  work: number
+}
+
+/**
+ * What each behaviour looks like, which is almost entirely a matter of arms.
+ *
+ * The head barely changes, so if these eight are not distinguishable from one
+ * another here then the animal has one behaviour however many `DOINGS` lists.
+ */
+const POSTURES: Readonly<Record<OctopusDoing, Posture>> = {
+  bury: { curl: 0.05, drop: 0.08, fan: 3.4, lead: 0, reach: 0.75, work: 0.12 },
+  crawl: { curl: 0, drop: 0.34, fan: 2.5, lead: 0.25, reach: 1, work: 1 },
+  handle: { curl: 0.32, drop: 0.26, fan: 1.3, lead: 0, reach: 0.66, work: 0.4 },
+  jet: { curl: 0, drop: 0.06, fan: 0.7, lead: 0, reach: 1.1, work: 0.15 },
+  pounce: { curl: 0, drop: 0.1, fan: 3.2, lead: 0, reach: 1, work: 0.25 },
+  probe: { curl: 0.22, drop: 0.3, fan: 2.6, lead: 1, reach: 1, work: 0.7 },
+  rest: { curl: 0.3, drop: 0.3, fan: 1.9, lead: 0, reach: 0.68, work: 0.25 },
+  stilt: { curl: 0.62, drop: 0.55, fan: 1.5, lead: -1.6, reach: 0.95, work: 0.9 },
+}
+
+/** As much of an octopus as its arms are drawn off. An `Octopus` is one. */
+export interface OctopusPose {
+  crawl: number
+  doing: OctopusDoing
+  facing: number
+  haul: number
+  reach: number
+}
+
+/**
+ * An octopus's arms, in a body a unit wide, rooted at the origin.
+ *
+ * Each arm has its own phase off the shared gait, so the animal is always part
+ * way through reaching with some of them and gathering with the rest. Arms all
+ * doing the same thing at once are a windscreen wiper with too many blades.
+ *
+ * It takes the animal rather than a number now, because there is no longer one
+ * number to take: which arm is long, how far it falls and whether the gait is
+ * running at all are all read off what it is doing.
+ */
+export function octopusArms(pose: OctopusPose, count = 8): Point[][] {
+  const arms: Point[][] = []
+  const drive = Math.min(Math.max(pose.haul, 0), 1)
+  const held = POSTURES[pose.doing] ?? POSTURES.crawl
+  const open = Math.min(Math.max(pose.reach, 0), 1.2)
+
+  for (let made = 0; made < count; made++) {
+    // Fanned across most of a half-turn rather than dropped straight down. An
+    // octopus is mostly arm and it is mostly sideways: a bundle of them hanging
+    // under a dome is a jellyfish, and it takes only spreading them out along
+    // the ground to be the other animal entirely.
+    const side = made / (count - 1) - 0.5
+
+    // Two groups out of phase rather than one each, and the split runs front to
+    // back. Every arm on its own phase is that many things happening at once
+    // and it reads as a spin; a leading half reaching while a trailing half
+    // pushes reads as a gait, which is what it is.
+    const phase = pose.crawl + (side > 0 ? 0 : Math.PI) + made * 0.12
+    const work = Math.sin(phase) * held.work
+
+    // Which end of the animal this arm is on: 1 leading, -1 trailing.
+    const ahead = Math.sign(side * pose.facing) || 1
+    const grown = held.reach * open * (1 + ahead * held.lead * 0.35)
+    const reach = grown * (0.9 + Math.abs(side) * 0.5) * (0.88 + work * 0.12)
+    const curl = held.curl * (1 - ahead * held.lead * 0.8)
+
+    // Which way the water is going past it. An arm behind a moving animal is
+    // pulled straight out behind it, and that is the single clearest statement
+    // a shape this size can make about which way it is going: without it the
+    // thing is symmetrical, and a symmetrical animal sliding sideways is being
+    // dragged rather than swimming.
+    const stream = -pose.facing * (TRAIL_HELD + drive * TRAIL_DRIVEN)
+
+    // Gathered as it goes. Arms spread wide are arms holding ground; arms
+    // brought in are arms in the water, so the fan closes as the push builds.
+    const fan = held.fan * (1 - drive * 0.62) * open
+
+    const points: Point[] = []
+
+    for (let step = 0; step <= 6; step++) {
+      const t = step / 6
+      // Out first and down after, so an arm lies along the floor for most of
+      // its length instead of dangling. `t * t` on the drop is what does that.
+      //
+      // About a body and a bit either side, which is as far as this can go. An
+      // octopus is mostly arm, but an animal whose arms are three times its own
+      // width reads as a spider, and one whose arms are longer than the shot is
+      // wide reads as a mistake.
+      const along = side * fan * reach * t
+      const wave = Math.sin(phase + t * 2.2) * 0.14 * t * (1 - t) * 4 * held.work
+      // A gathered arm comes in and up, and only so far up. The mantle sits
+      // above the origin and it is solid, so an arm lifted much past the line
+      // it is rooted on is an arm drawn behind the head, which at this weight
+      // is an arm that is not there at all. Gathered still has to be visible.
+      points.push({
+        x: along + stream * t * reach - ahead * curl * t * t * 0.28,
+        y: (t * t * held.drop + t * 0.1) * (1 - drive * 0.7) - wave * 0.22 - curl * t * t * 0.5,
+      })
+    }
+    arms.push(points)
+  }
+
+  return arms
+}