@codincod/ornament 0.0.0-stage → 0.2.0

package/src/eels.ts

@@ -0,0 +1,667 @@
+/**
+ * A colony of garden eels, standing out of the sand.
+ *
+ * Every other animal in this water is somewhere because of what it decided. A
+ * fish went there, a crab crossed to it, a jellyfish was carried. These are the
+ * one family that has an address and never leaves it: an eel digs a burrow,
+ * lines it, and spends its life with its tail in the hole and the rest of it
+ * standing in the current picking at what the water brings past. It is the
+ * whole animal, and it is a behaviour nothing else here has.
+ *
+ * ## Why it is not `flora.ts` with a head on it
+ *
+ * Because a plant leans and an eel stands. A blade of grass is a thing the
+ * water is doing; the eel is holding a posture against the water, and the
+ * difference shows in what happens when the current turns. A plant follows it
+ * round and takes as long to get there as the water does. An eel is already
+ * facing the new way, because facing into it is the point: what is being eaten
+ * is arriving on it.
+ *
+ * So they read the same current the bed reads, and they read it as a direction
+ * to face rather than as a force to give in to. What is left of the plant in
+ * them is a small bend, which is a body in moving water and not a body being
+ * moved by it.
+ *
+ * ## The wave is the animal
+ *
+ * One eel retracting is a detail nobody sees. A field of them going down in
+ * order, nearest to the thing first, and coming back up in the same order a few
+ * seconds later, is the thing people remember about ever having seen one. It is
+ * also the only piece of collective behaviour in this water that is not a flock:
+ * the flock (`swarm.ts`) is one object with fish drawn on it, and this is a
+ * hundred animals that never coordinate at all. The wave is not organised. Each
+ * eel reacts to the same event on its own, and what makes a wave of it is that
+ * the event reaches them at different times because they are standing at
+ * different distances from it. See `WAVE`.
+ *
+ * That distinction is worth the file. A colony written as a wave, with a
+ * position along the wave per eel, looks the same until something crosses at an
+ * angle, or crosses twice, or stops halfway; then it is a stadium doing a
+ * Mexican wave and this one is still a hundred frightened animals.
+ *
+ * ## They come back out slowly, and that is not politeness
+ *
+ * Going in is free and being out is how it eats, so an eel goes down as fast as
+ * it can and comes up as slowly as it dares. `SNAP` and `EMERGE` are two orders
+ * of magnitude apart on purpose. The asymmetry is what makes a colony that has
+ * been disturbed look disturbed for a while afterwards, which is the honest
+ * consequence of one shark and the reason a sea with events in it feels
+ * different from a sea with animations in it.
+ *
+ * ## What a renderer gets
+ *
+ * `body` is a polyline in px from the mouth of the burrow up, and it is all
+ * there is: an eel is a line with a blunt end, drawn round-capped, and the
+ * blunt end is the head. Recut only when it has moved further than the
+ * tolerance, the same bargain `flora.ts` and `walkers.ts` make, and a colony
+ * standing still in slack water is very nearly free.
+ */
+
+import { abreast, type Presence } from "./biome.ts"
+import { makeNoise2, makeRandom } from "./perlin.ts"
+import type { Point } from "./seabed.ts"
+import { BED_OFF, drawnAt } from "./sizes.ts"
+
+export interface Eel {
+  /**
+   * The body, mouth of the burrow first and head last, in px.
+   *
+   * Recut when the animal has moved further than the tolerance since the last
+   * one, so a colony in slack water hands back the same points for minutes.
+   */
+  body: Point[]
+  /**
+   * How many times this eel has redrawn itself.
+   *
+   * The only thing a renderer has to watch. While it holds, `body` is what it
+   * already was and a kept drawing is still true.
+   */
+  cut: number
+  /** 0 is as far off as this water goes, 1 is up against the glass. */
+  readonly depth: number
+  /**
+   * How thick it is against its own length, 1 being the colony's usual.
+   *
+   * A share rather than a width, because how thick an eel is drawn at this
+   * distance is the renderer's question and how thick this one is against its
+   * neighbours is the colony's.
+   */
+  readonly girth: number
+  /** How far out it is standing, 0 in the hole and 1 at full stretch. */
+  out: number
+  /** How tall it stands at full stretch, in px. */
+  readonly size: number
+  readonly x: number
+  /** The sand at its burrow. */
+  readonly y: number
+}
+
+export interface Eels {
+  /**
+   * Whether a place is inside the colony's clearing.
+   *
+   * For `flora.ts`, which will not root in one. A garden eel bed is bare sand
+   * with weed around the edge of it, and the reason it is bare is the eels:
+   * every burrow is being worked over continuously, and nothing gets to settle.
+   * Written as a question the bed asks rather than as a shape the bed is handed,
+   * because the colony is the one that knows where it dug.
+   */
+  bare(x: number, depth: number): boolean
+  readonly eels: readonly Eel[]
+  /**
+   * A box of a new size, and the ground that came with it.
+   *
+   * The colony is dug again rather than moved. A burrow is a hole in a
+   * particular patch of sand, and a patch of sand that is now somewhere else is
+   * not that patch.
+   */
+  resize(width: number, height: number, floor: (x: number, depth?: number) => number): void
+  step(seconds: number): void
+}
+
+export interface EelsOptions {
+  /**
+   * What else is in the water, asked for once a step.
+   *
+   * Left out, nothing is, and the colony stands out all day. Which is what a
+   * colony with nothing crossing it does.
+   */
+  about?: () => readonly Presence[]
+  /** How many to dig in. Rounded down, and a colony of none is no colony. */
+  count?: number
+  /** The ground at x, at a given distance; `seabed.floorAt`. */
+  floor: (x: number, depth?: number) => number
+  height: number
+  seed: number
+  /** How far an eel may move from its last drawing before it recuts, in px. */
+  tolerance?: number
+  width: number
+}
+
+/**
+ * How long one stands, in metres, and how much of that is out of the hole.
+ *
+ * A garden eel is most of a metre of animal and stands about half of it up. The
+ * length is the whole animal because that is what a reader could look up; what
+ * is drawn is the share, and the rest is in the sand.
+ */
+const LENGTH = 0.72
+
+const STANDING = 0.55
+
+/** How much longer or shorter than its neighbours one of them is. */
+const ODD = 0.34
+
+/**
+ * How much thicker or thinner than its length would say one of them is.
+ *
+ * Drawn apart from the length rather than with it. Girth that follows height
+ * exactly is one animal at several scales, which is what a colony of a hundred
+ * cannot afford to be: the eye picks a repeated shape out of a crowd long
+ * before it picks a repeated movement, so a long thin one and a short thick one
+ * have to both be possible.
+ */
+const GIRTH_ODD = 0.28
+
+/**
+ * How wide a colony is, as a share of the box.
+ *
+ * A patch and not a field. Garden eels live in dense beds with bare sand either
+ * side, and a colony spread across the whole picture is a texture rather than a
+ * place: what says colony is that there is an edge to it and you can see both
+ * ends of it.
+ */
+const PATCH = 0.42
+
+/**
+ * How far back the colony sits, and how deep a band of sand it takes.
+ *
+ * Not at the front. These are drawn as a hundred thin lines, and a hundred thin
+ * lines across the near sand is a thicket in front of everything else in the
+ * picture. Set back, they are a patch of texture on the floor with the reef
+ * behind them, which is where a reader has ever seen one.
+ */
+const DEPTH_AT = 0.52
+
+const DEPTH_BAND = 0.26
+
+/** How much of a colony's drawn size is its distance. The floor's own share. */
+const DEPTH_SIZE = 0.55
+
+/**
+ * How many burrows fit in a square of sand, and the fewest a colony is.
+ *
+ * A real bed is denser than this by a long way. What is being drawn is a
+ * silhouette of a bed at a distance, and past a certain crowding the gaps
+ * between the animals close and it stops reading as animals at all.
+ */
+const CROWDING = 0.00042
+
+const FEWEST = 8
+
+const MOST = 140
+
+/** How far apart two burrows have to be, as a share of one eel's height. */
+const APART = 0.16
+
+/**
+ * How far past the outermost burrow the clearing reaches, as a share of the
+ * colony's own width, and how far either side of it in distance.
+ *
+ * Generous, because what is being kept out is a plant with a root at a point
+ * and a metre of leaf above it: a kelp planted just outside a bed still leans
+ * across the whole of it.
+ */
+const CLEARING = 0.18
+
+const CLEARING_DEEP = 0.16
+
+/** How many features of the current fit across the box. The bed's own. */
+const FIELD_CELLS = 3.6
+
+/** How fast the field slides, so a colony never settles into one shape. */
+const DRIFT = 0.06
+
+/**
+ * How far a head is carried off the line of the burrow, as a share of height.
+ *
+ * Small. An eel in a current is a slightly leaning line and not a bent one:
+ * whatever the water is doing, the animal is holding itself against it, and a
+ * body that gave in to the current would be a body that had stopped feeding.
+ */
+const LEAN = 0.26
+
+/** How much of the lean is the shared current, and how much is its own. */
+const CURRENT_SHARE = 0.72
+
+/** How fast one works through its own part of the sway, slowest to fastest. */
+const SWAY_SLOWEST = 0.14
+
+const SWAY_FASTEST = 0.5
+
+/**
+ * How much of an eel's own sway is the quick part of it, and how many times
+ * faster that part goes.
+ *
+ * One sine is a pendulum. A garden eel is not swinging, it is picking food out
+ * of the water going past, so the slow lean the current puts on it carries a
+ * faster, smaller movement of its own head. The ratio is drawn per animal and
+ * is not a whole number on purpose: a quick part that comes round with the slow
+ * one is a shape that repeats, and a colony of shapes that repeat is a colony
+ * of clockwork whatever rate each of them is set to.
+ */
+const PICK = 0.34
+
+const PICK_TIMES_LEAST = 2.3
+
+const PICK_TIMES_SPAN = 1.3
+
+/**
+ * How much of its length an eel keeps back between one look and the next, and
+ * how long it takes over that.
+ *
+ * Nothing to do with being frightened, which is `wants` and is sudden. This is
+ * the ordinary business of the colony: an eel is not a rod at full height until
+ * something scares it, it is up a bit and down a bit all day. A bed where every
+ * animal is standing at exactly its own full height is the single thing that
+ * makes a hundred of them read as a field of identical stakes, and the fix is
+ * not more sway. It is that they are at different heights, and not the same
+ * different heights a moment later.
+ *
+ * Slow enough that `EMERGE` tracks it without being the thing shaping it: this
+ * sets the height an eel is easing towards, not how fast it may get there.
+ */
+const SHY_LEAST = 0.05
+
+const SHY_SPAN = 0.24
+
+const BREATH_SLOWEST = 0.035
+
+const BREATH_FASTEST = 0.12
+
+/** How finely a body is cut. Enough that the bend has no corners in it. */
+const STEPS = 5
+
+/**
+ * How much bigger than an eel 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` and `nemos.ts` weigh the water by these, and another animal in
+ * the same sea should be frightened of the same things. Something an eel's own
+ * size is another eel.
+ */
+const MINDS = 1.6
+
+const NOTICE = 3.2
+
+/** How much of a fright something with no menace about it can still cause. */
+const BULK = 0.25
+
+/**
+ * How little a thing has to worry a colony before nobody bothers.
+ *
+ * There is a floor because an eel that ducked at everything would be an eel
+ * permanently in its hole, and a colony nobody ever sees is a colony that was
+ * not worth drawing.
+ */
+const MINDS_AT = 0.12
+
+/**
+ * How fast the news crosses the sand, in px a second.
+ *
+ * The one number the wave is. Nothing is sent and nothing is heard: an eel
+ * ducks when the thing is close enough to it, and the ones further along the
+ * bed are further from it, so they duck later. This is what that delay comes
+ * out as once it is written as a speed, and writing it as a speed is what lets
+ * the wave be right when something crosses at an angle rather than along the
+ * row.
+ *
+ * Fast enough to look like one event and slow enough to be a wave. Much faster
+ * and the whole colony drops at once, which is a colony with a switch on it.
+ */
+const WAVE = 620
+
+/**
+ * How long one stays down, in seconds, and how much longer a real fright keeps
+ * it there.
+ *
+ * The floor is short because most of what crosses a bed is nothing, and an eel
+ * that took a turtle as seriously as a shark would spend its life underground.
+ */
+const HOLD_LEAST = 1.4
+
+const HOLD_SPAN = 5.5
+
+/** How much of its own time one eel keeps, so a colony never comes up as a row. */
+const DITHER = 1.6
+
+/**
+ * How fast it goes down and how fast it comes back up, in its own heights a
+ * second.
+ *
+ * Two orders apart. Going down is free and being up is how it eats, so it drops
+ * as fast as it can and returns as slowly as it dares. Ten seconds after a
+ * shark, a bed that snapped back would look like a bed that had not noticed.
+ */
+const SNAP = 9
+
+const EMERGE = 0.26
+
+/**
+ * How far down a startled eel actually goes.
+ *
+ * Not away. A garden eel keeps its head at the mouth of the burrow with
+ * everything else in it, because the hole is the safe place and looking at what
+ * is in the water is worth something. A colony that vanished entirely would
+ * leave bare sand, and bare sand is the wrong picture: what happens is that the
+ * grass goes.
+ */
+const HIDDEN = 0.08
+
+/** How far an eel travels before it is worth redrawing, in px, by default. */
+const TOLERANCE = 0.25
+
+const MIN_SPAN = 1
+
+/**
+ * What frightened the colony, when, and from where.
+ *
+ * One of these at a time. A bed being crossed by two things at once is rare
+ * enough that keeping both would be machinery for a case nobody sees, and the
+ * nearer of them is the one that matters anyway.
+ */
+interface Alarm {
+  at: number
+  force: number
+  x: number
+  y: number
+}
+
+/** Everything about one eel that is not in the drawing. */
+interface Habit {
+  /** How fast it works through its own part of the sway. */
+  readonly beat: number
+  /** How fast it rises and dips out of its own burrow, doing nothing else. */
+  readonly breath: number
+  /** Where in that rise and dip it is. */
+  readonly breathed: number
+  /** How much of its own time it keeps, so no two come up together. */
+  readonly dither: number
+  /** Where its head was when it was last drawn, or null before the first. */
+  drawn: Point | null
+  /** Where in that sway it is, so no two are at the same point of it. */
+  readonly own: number
+  /** How many times faster the quick part of its sway goes than the slow. */
+  readonly picks: number
+  /** How much of its length it keeps back at the bottom of its own dip. */
+  readonly shy: number
+}
+
+export function createEels(options: EelsOptions): Eels {
+  const noise = makeNoise2(options.seed ^ 0x2d71)
+  const random = makeRandom(options.seed ^ 0x51a4)
+
+  let width = Math.max(MIN_SPAN, options.width)
+  let height = Math.max(MIN_SPAN, options.height)
+  let floor = options.floor
+  let drift = 0
+  let clock = 0
+
+  const tolerance = Math.max(0, options.tolerance ?? TOLERANCE)
+
+  const eels: Eel[] = []
+  const habits: Habit[] = []
+
+  let alarm: Alarm | null = null
+
+  /** The clearing, as it stands. Nothing while nothing has been dug. */
+  let clearing: { deep: number; left: number; right: number; shallow: number } | null = null
+
+  /**
+   * Where the colony is dug, this box.
+   *
+   * One patch, placed off the seed, so the same water puts it in the same place
+   * every time it is drawn and a different day puts it somewhere else.
+   */
+  function dig(): void {
+    eels.length = 0
+    habits.length = 0
+    clearing = null
+
+    const wanted = options.count ?? width * height * CROWDING
+    const many = Math.min(MOST, Math.floor(Math.max(0, wanted)))
+    if (many < FEWEST) return
+
+    const patch = width * PATCH
+    const middle = patch / 2 + random() * (width - patch)
+
+    // Placed by rejection rather than by a grid, and then sorted, because a
+    // colony is a patch of holes and a grid of holes is a graveyard. What the
+    // sorting is for is the drawing: an eel behind another has to be drawn
+    // first, and depth is the only thing that settles that.
+    const dug: { depth: number; x: number }[] = []
+    for (let tries = 0; tries < many * 12 && dug.length < many; tries++) {
+      const depth = DEPTH_AT + (random() - 0.5) * DEPTH_BAND
+      const x = middle + (random() - 0.5) * patch
+      const size = stands(depth)
+
+      let clear = true
+      for (const other of dug) {
+        if (Math.abs(other.x - x) < size * APART && Math.abs(other.depth - depth) < APART * 0.2) {
+          clear = false
+          break
+        }
+      }
+      if (clear) dug.push({ depth, x })
+    }
+
+    dug.sort((one, two) => one.depth - two.depth)
+
+    for (const hole of dug) {
+      const size = stands(hole.depth) * (1 + (random() - 0.5) * 2 * ODD)
+      eels.push({
+        body: [],
+        cut: 0,
+        depth: hole.depth,
+        girth: 1 + (random() - 0.5) * 2 * GIRTH_ODD,
+        // Standing already, because a colony that rose out of the sand on the
+        // first frame would be a colony announcing itself.
+        out: 1,
+        size,
+        x: hole.x,
+        y: floor(hole.x, hole.depth),
+      })
+      habits.push({
+        beat: SWAY_SLOWEST + random() * (SWAY_FASTEST - SWAY_SLOWEST),
+        breath: BREATH_SLOWEST + random() * (BREATH_FASTEST - BREATH_SLOWEST),
+        breathed: random() * Math.PI * 2,
+        dither: random() * DITHER,
+        drawn: null,
+        own: random() * Math.PI * 2,
+        picks: PICK_TIMES_LEAST + random() * PICK_TIMES_SPAN,
+        shy: SHY_LEAST + random() * SHY_SPAN,
+      })
+    }
+
+    let left = Number.POSITIVE_INFINITY
+    let right = Number.NEGATIVE_INFINITY
+    let shallow = Number.POSITIVE_INFINITY
+    let deep = Number.NEGATIVE_INFINITY
+    for (const one of eels) {
+      left = Math.min(left, one.x)
+      right = Math.max(right, one.x)
+      shallow = Math.min(shallow, one.depth)
+      deep = Math.max(deep, one.depth)
+    }
+
+    const edge = (right - left) * CLEARING
+    clearing = {
+      deep: deep + CLEARING_DEEP,
+      left: left - edge,
+      right: right + edge,
+      shallow: shallow - CLEARING_DEEP,
+    }
+  }
+
+  /** How tall one at this distance stands, in px. */
+  function stands(depth: number): number {
+    const drawn = drawnAt(LENGTH, BED_OFF) * STANDING * width
+    return drawn * (1 - DEPTH_SIZE + DEPTH_SIZE * depth)
+  }
+
+  /**
+   * How much the water in front of the colony worries it, and where from.
+   *
+   * Read once for the whole bed rather than once an eel. Every eel in a colony
+   * is looking at the same stretch of water, and what tells them apart is where
+   * they are standing in it, which is the wave's business rather than this.
+   */
+  function minded(water: readonly Presence[]): Alarm | null {
+    const one = eels[0]
+    if (!one) return null
+
+    let worst: Alarm | null = null
+
+    for (const thing of water) {
+      if (thing.size < one.size * MINDS) continue
+
+      const reach = thing.size * NOTICE
+      let near = 0
+      for (const eel of eels) {
+        const away = Math.hypot(eel.x - thing.x, eel.y - thing.y)
+        if (away >= reach) continue
+        near = Math.max(near, (1 - away / reach) * abreast(eel.depth, thing.depth))
+      }
+      if (near <= 0) continue
+
+      const force = near * (BULK + (thing.menace ?? 0) * (1 - BULK))
+      if (force < MINDS_AT || (worst && force <= worst.force)) continue
+
+      worst = { at: clock, force, x: thing.x, y: thing.y }
+    }
+
+    return worst
+  }
+
+  /** Where the current is going at a place, as a lean off upright. */
+  function current(x: number, y: number): number {
+    return noise((x / width) * FIELD_CELLS + drift, (y / height) * FIELD_CELLS)
+  }
+
+  /** How far out this eel wants to be standing, right now. */
+  function wants(at: number): number {
+    const one = eels[at]
+    const habit = habits[at]
+    if (!one || !habit) return 1
+
+    // What it is doing when nothing is happening, which is most of the time and
+    // is not nothing: up a bit and down a bit, on its own clock.
+    const easy =
+      1 - habit.shy * (0.5 + 0.5 * Math.sin(clock * habit.breath * Math.PI * 2 + habit.breathed))
+    if (!alarm) return easy
+
+    // The wave, and the whole of it. The news has not arrived until the thing
+    // was near enough for long enough, where near enough is a distance and long
+    // enough is that distance divided by a speed.
+    const reach = Math.hypot(one.x - alarm.x, one.y - alarm.y)
+    const due = alarm.at + reach / WAVE
+    if (clock < due) return easy
+
+    const held = HOLD_LEAST + HOLD_SPAN * alarm.force + habit.dither
+    if (clock >= due + held) return easy
+
+    // Frightened is a floor rather than a share of what it happened to be
+    // doing: an eel that ducks only as far as its own dip had left it is an eel
+    // that ducks less the more it was already down.
+    return Math.min(easy, 1 - alarm.force * (1 - HIDDEN))
+  }
+
+  /** The body as a polyline, from the mouth of the burrow to the head. */
+  function cut(at: number): Point[] {
+    const one = eels[at]
+    const habit = habits[at]
+    if (!one || !habit) return []
+
+    const up = one.size * one.out
+    const shared = current(one.x, one.y)
+    const slow = Math.sin(clock * habit.beat * Math.PI * 2 + habit.own)
+    const quick = Math.sin(clock * habit.beat * habit.picks * Math.PI * 2 + habit.own * habit.picks)
+    const own = slow * (1 - PICK) + quick * PICK
+    const lean = (shared * CURRENT_SHARE + own * (1 - CURRENT_SHARE)) * LEAN * up
+
+    const points: Point[] = []
+    for (let step = 0; step <= STEPS; step++) {
+      const along = step / STEPS
+      // Squared, so the burrow end is upright and the bend is all near the
+      // head. An eel is held rigid where it comes out of the sand, because that
+      // is the part of it that is gripping.
+      points.push({ x: one.x + lean * along * along, y: one.y - up * along })
+    }
+    return points
+  }
+
+  dig()
+
+  return {
+    bare(x: number, depth: number): boolean {
+      if (!clearing) return false
+      return (
+        x >= clearing.left &&
+        x <= clearing.right &&
+        depth >= clearing.shallow &&
+        depth <= clearing.deep
+      )
+    },
+
+    eels,
+
+    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
+      dig()
+    },
+
+    step(seconds: number): void {
+      if (eels.length === 0) return
+
+      clock += seconds
+      drift += seconds * DRIFT
+
+      const water = options.about?.() ?? []
+      const worse = minded(water)
+      // Kept until something worse arrives or the bed has finished with it, so
+      // one shark is one event rather than an event on every frame it is still
+      // in the water for.
+      if (worse && (!alarm || worse.force > alarm.force || clock > alarm.at + HOLD_LEAST)) {
+        alarm = worse
+      }
+
+      for (let at = 0; at < eels.length; at++) {
+        const one = eels[at]
+        const habit = habits[at]
+        if (!one || !habit) continue
+
+        const want = wants(at)
+        const rate = (want < one.out ? SNAP : EMERGE) * seconds
+        one.out += Math.max(-rate, Math.min(rate, want - one.out))
+
+        // Against the last drawing rather than the last step, so an eel that
+        // swayed and came back has not moved. The head is the fastest part of
+        // it and the only part that moves in two directions, so how far the
+        // head has gone is how far the animal has gone: standing still in a
+        // turning current is movement, and rising in slack water is movement.
+        const body = cut(at)
+        const head = body.at(-1)
+        if (!head) continue
+        if (habit.drawn && Math.hypot(head.x - habit.drawn.x, head.y - habit.drawn.y) < tolerance) {
+          continue
+        }
+
+        habit.drawn = head
+        one.body = body
+        one.cut++
+      }
+    },
+  }
+}