@codincod/ornament 0.0.0-stage → 0.2.0

package/src/passers.ts

@@ -0,0 +1,730 @@
+/**
+ * What goes past overhead, what is looking for you, and what is passing
+ * through.
+ *
+ * A boat crossing the surface, sonar, and a submarine. All three are rare on a
+ * scale nothing else in the ornament is: each happens at most once in a day,
+ * and the submarine only on about one day in seven. Kept free of the DOM the
+ * way the rest is.
+ *
+ * ## Why a thing that almost never happens is worth the code
+ *
+ * Because the alternative is a loop, and a loop is what turns a background into
+ * wallpaper. Everything else here is on a cycle short enough to see the whole
+ * of: the fish come round, the kelp sways, the bubbles burst and rest, and
+ * after a minute you have watched the entire vocabulary. A scene that still has
+ * something in it you have not seen is a scene you have not finished.
+ *
+ * It also gives the water a surface and a beyond. A hull passing over the top
+ * of the picture says the water is under something; a ping says somebody is out
+ * there; a submarine says they came looking. None of that can be said by
+ * anything swimming.
+ *
+ * ## Rare in the day, not rare in the minute
+ *
+ * The first version counted seconds: a boat every eight minutes or so of the
+ * scene's own running time. That is the wrong clock for the surface this ended
+ * up on. A desktop advances its water only while the wallpaper is uncovered, so
+ * the eight minutes are eight minutes of glimpses, and a boat that is rare per
+ * minute watched turns out to be a boat you see most times you clear a
+ * workspace. Rarity anybody can feel is rarity in the day.
+ *
+ * So each kind keeps an appointment instead. The day's plan is drawn from the
+ * seed and the date, which makes it the same plan on every screen of a machine
+ * and a different one tomorrow: whether this kind happens at all today, and the
+ * moment it is due. Once the clock is past that moment the passer is owed, and
+ * it crosses the next time there is somebody to see it, after a stretch of
+ * watched time so that it never arrives on the instant a window closes. Then it
+ * is done until tomorrow.
+ *
+ * Which means a passer waits rather than being missed. A machine that was off
+ * at four in the morning gets its boat when it wakes up, and a machine nobody
+ * looks at all day gets one crossing when they finally do, not the nine it
+ * would have been owed. The hole in it is honest and stated here: nothing is
+ * written to disk, so restarting the shell forgets what has already crossed and
+ * a day with a restart in it can hold a second boat.
+ *
+ * ## All three are one shape
+ *
+ * A passer is a thing that is not here, then is here, then is not. They differ
+ * in how likely they are, how long they take, where in the column they sit, and
+ * what a renderer makes of them, so they share `Passer` and everything else
+ * lives in a table. Adding another kind means another row.
+ *
+ * ## A passer has to leave a mark on the water
+ *
+ * The first boat did not. It was a silhouette sliding across the ceiling with
+ * two straight lines trailing off the stern, and the two lines were supposed to
+ * be a wake. They read as a beam: a hard pair of rays opening into the picture
+ * off the back of a hull is a searchlight, or the sonar the ping is meant to
+ * be, and the eye is quite sure it is being pointed at. Nothing else about the
+ * boat said the water had noticed it at all.
+ *
+ * So a hull now leaves `wake`, which is churn: puffs of white water let go at
+ * the stern that swell, open into the V a hull actually leaves, thin, and go.
+ * They belong to the water rather than to the boat, which is the whole point of
+ * them. They stay where they were made while the hull goes on, and they are
+ * still dying out after it has left the picture, so what somebody sees is a
+ * boat that pushed the water aside rather than a boat drawn on top of it.
+ *
+ * And a passer says what it is doing to the fish, in `startle`. A hull
+ * overhead and a ping going through are both things a shoal reacts to, and
+ * `shoal.ts` takes one straight: the fish under the boat dive and scatter, and
+ * a ping empties the water in front of it. That is the difference between a
+ * scene with a boat in it and a scene a boat is happening to.
+ */
+
+import { makeRandom, stir } from "./perlin.ts"
+import { drawnAt } from "./sizes.ts"
+
+export type PassKind = "boat" | "sonar" | "submarine"
+
+export interface Passer {
+  /** How far through its crossing, 0 to 1. */
+  along: number
+  /** Which way it is going: 1 rightward, -1 left. Meaningless for sonar. */
+  readonly facing: number
+  readonly kind: PassKind
+  /** Its size in px: hull length for a boat, the ring's reach for sonar. */
+  readonly scale: number
+  /** How loud it is now, 0 to 1, faded in and out at the ends. */
+  weight: number
+  /** Where it is, in the box's own units. */
+  x: number
+  y: number
+}
+
+/**
+ * One puff of churned water, left behind by whatever made it.
+ *
+ * It has no course of its own. Where it was made is where it stays, and all it
+ * does from there is swell, drift off the line it was made on, and thin out.
+ * The two arms of a wake are one of these let go alternately to either side.
+ */
+export interface Froth {
+  /** How far through its life it is, 0 new and 1 gone. */
+  age: number
+  r: number
+  /**
+   * The size of the thing that made it, in px.
+   *
+   * Kept so the puff can go on swelling and opening at its own rate after its
+   * boat has left the picture. A renderer has no use for it.
+   */
+  readonly scale: number
+  /**
+   * Which way it drifts off the line it was made on, and how fast.
+   *
+   * The sign is the arm of the wake it belongs to. The size of it is what
+   * keeps the two arms from being two rows of dots: every puff opens at its
+   * own rate, so the churn spreads into a band that is thickest at the arms
+   * and has water in it everywhere, which is what a wake is.
+   */
+  readonly side: number
+  x: number
+  y: number
+}
+
+/**
+ * What the water is being told to do right now, for anything living in it.
+ *
+ * A push out from a point, felt to `reach` and no further. `shoal.ts` takes it
+ * as a thing to get away from, which is why the numbers are in px and a share
+ * rather than in anything to do with boats: a fish has no opinion about what
+ * kind of passer it is under.
+ */
+export interface Startle {
+  /** How hard it is felt at the middle of it, 0 to 1. */
+  force: number
+  /** How far out it is felt at all, in px. */
+  reach: number
+  x: number
+  y: number
+}
+
+export interface Passers {
+  readonly passing: readonly Passer[]
+  resize(width: number, height: number): void
+  /** Where the water is being disturbed now, or null while it is still. */
+  readonly startle: Startle | null
+  /**
+   * `seconds` is watched time, which is what a crossing is made of, and `now`
+   * is the wall clock, which is what the day's plan is read against. They are
+   * two different clocks on a desktop and telling them apart is the whole of
+   * the timing here: a covered wallpaper stops the first and not the second.
+   */
+  step(seconds: number, now?: Date): void
+  /** The churn left behind, oldest first. */
+  readonly wake: readonly Froth[]
+}
+
+export interface PassersOptions {
+  /** Ignore the day's plan and keep crossing. See `createPassers`. */
+  eager?: boolean
+  height: number
+  kinds?: readonly PassKind[]
+  seed: number
+  width: number
+}
+
+/**
+ * How far up and out the two hulls are, in metres.
+ *
+ * A boat is not small, it is far, and writing it down that way is what keeps
+ * the next one from being wrong: it is a shape crossing the ceiling rather than
+ * a thing you are swimming beside, and the height of the water column is most
+ * of why. Drawn as though it were alongside, it filled the top of the frame and
+ * the eye went to it and stayed.
+ *
+ * The submarine is out in the blue instead, which is the only place a hull that
+ * long can be and still be a hull rather than a wall. Both go through
+ * `sizes.ts` with the animals, so the boat comes out over a turtle and under a
+ * shark, and the rare thing is the largest silhouette this water ever draws.
+ */
+const BOAT_OFF = 30
+
+const SUB_OFF = 150
+
+/** How much of a crossing is spent fading in, and the same again fading out. */
+const FADE = 0.16
+
+/** How far down the box a boat's waterline sits, as a share of the height. */
+const WATERLINE = 0.035
+
+/** How far past each side a boat starts and finishes, as shares of the width. */
+const OFFING = 0.2
+
+/** How far in from a side a ping comes from: never the middle. */
+const PING_EDGE = 0.18
+
+interface Habit {
+  /**
+   * How many days in ten it happens at all.
+   *
+   * The one number that decides whether something is scenery or a find. A boat
+   * and a ping are every day, so the water has a beyond to it as a matter of
+   * course; the submarine is not, because a thing that turns up daily is a
+   * thing you stop looking for.
+   */
+  readonly chance: number
+  /** Where it sits in the column, as shares of the height. */
+  readonly deepLeast: number
+  readonly deepSpan: number
+  /**
+   * How big it is drawn, as a share of the box's width.
+   *
+   * A hull says it in metres of hull at metres of distance and lets `sizes.ts`
+   * do the sum. Sonar has no length to state: what it is measuring out is how
+   * far the ring reaches, which is a share of the box and nothing else.
+   */
+  readonly sizeLeast: number
+  readonly sizeSpan: number
+  /** How long a crossing takes, at least and up to that again. */
+  readonly takeLeast: number
+  readonly takeSpan: number
+}
+
+/**
+ * How likely each is on a given day, how deep it goes, and how long it takes.
+ *
+ * The boat is the largest thing the scene ever draws and it is a hard
+ * silhouette across the top of the picture, so it gets one crossing a day and
+ * no more. Sonar is cheaper to look at and does not travel at all, but it is
+ * the loudest thing here in the sense that matters: something out there knows
+ * you are down here. Once is plenty.
+ *
+ * The submarine is the rare one, and it is rare in the only way that lasts. It
+ * could have been made rare per minute, and then it would be a thing you see
+ * every few sittings and stop seeing after a fortnight; on about one day in
+ * seven it is a thing somebody mentions.
+ */
+const HABITS: Readonly<Record<PassKind, Habit>> = {
+  boat: {
+    chance: 1,
+    deepLeast: WATERLINE,
+    deepSpan: 0,
+    sizeLeast: drawnAt(6, BOAT_OFF),
+    sizeSpan: drawnAt(11, BOAT_OFF) - drawnAt(6, BOAT_OFF),
+    takeLeast: 26,
+    takeSpan: 18,
+  },
+  sonar: {
+    chance: 1,
+    deepLeast: 0.12,
+    deepSpan: 0.43,
+    sizeLeast: 0.4,
+    sizeSpan: 0.3,
+    takeLeast: 4.5,
+    takeSpan: 2.5,
+  },
+  submarine: {
+    chance: 0.15,
+    deepLeast: 0.17,
+    deepSpan: 0.19,
+    sizeLeast: drawnAt(55, SUB_OFF),
+    sizeSpan: drawnAt(90, SUB_OFF) - drawnAt(55, SUB_OFF),
+    takeLeast: 38,
+    takeSpan: 22,
+  },
+}
+
+interface Churn {
+  /** How much water it moves, as a share of what a hull at full pelt moves. */
+  readonly force: number
+  /** Where the churn leaves it, along and across, in units of `scale`. */
+  readonly x: number
+  readonly y: number
+}
+
+/**
+ * What each does to the water it is in.
+ *
+ * The boat is at the surface with its screws in the top of the water, so it
+ * moves the most and it moves it where everything can see. A submarine at depth
+ * moves about half as much: it is smaller, it is further off, and a wake that
+ * came off it as hard as the boat's would make it the loud thing in the picture
+ * when the point of it is that it went by almost unnoticed.
+ *
+ * Sonar moves none. It is a sound, and the only mark it leaves is on the fish.
+ */
+const CHURN: Readonly<Record<PassKind, Churn>> = {
+  boat: { force: 1, x: -1, y: 0.19 },
+  sonar: { force: 0, x: 0, y: 0 },
+  submarine: { force: 0.5, x: -1.12, y: 0 },
+}
+
+/**
+ * Seconds between one puff of churn and the next, while something is crossing.
+ *
+ * Close enough together that the puffs overlap at the stern, which is the
+ * difference between foam and beads. Foam is not a collection of things: it is
+ * a patch of water that has gone white, and the only way a renderer drawing
+ * discs gets a patch is to hand it more discs than there is room for.
+ */
+const FROTH_GAP = 0.04
+
+/** How long a puff of churn lasts, in seconds. */
+const FROTH_LIFE = 4.4
+
+/**
+ * The most churn the water holds at once, which is the two above and a margin.
+ *
+ * A ceiling rather than a count, and it exists because a renderer that keeps a
+ * pool of shapes needs to know how deep to make the pool. Running out at the
+ * young end would leave a gap of clear water between the stern and its own
+ * wake, which is a boat that has stopped churning while still under power.
+ */
+export const FROTH_MOST = 112
+
+/** How big a puff leaves, and how fast it swells, in units of `scale`. */
+const FROTH_SEED = 0.07
+
+const FROTH_SWELL = 0.04
+
+/**
+ * How fast the two arms open, in units of `scale` a second.
+ *
+ * The V of a wake is a fixed angle in the real world, so what opens it here is
+ * time rather than distance: a puff a second old sits about this far off the
+ * line the hull ran down, whatever the hull was doing. It slows as it ages,
+ * because the water it is pushing into is water at rest.
+ */
+const FROTH_OPEN = 0.2
+
+/**
+ * How far a hull is felt through the water, in units of its own `scale`, and
+ * how hard a ping is felt against a hull.
+ *
+ * A hull is felt close in and a ping is felt everywhere it has got to, which is
+ * the honest difference between a thing displacing water and a sound going
+ * through it. The ping is the softer of the two on purpose: a shoal that bolted
+ * from a noise would be a shoal that had been hurt, and this one has only been
+ * asked a question.
+ */
+const HULL_FELT = 2.6
+
+const PING_FELT = 0.55
+
+/** Seconds in a day, which is the unit the whole plan is written in. */
+const DAY = 24 * 60 * 60
+
+/**
+ * How long an owed passer waits for watched time before it crosses, at least
+ * and up to that again.
+ *
+ * Not zero, and this is the difference between a scene and a trick. A boat that
+ * arrived the instant the last window closed would be a boat that had been
+ * waiting for you, and everything else in this water is indifferent to whether
+ * anybody is there. A minute or two of ordinary sea first, and it is weather.
+ */
+const WAIT_LEAST = 35
+
+const WAIT_SPAN = 130
+
+/** Watched seconds between the end of one crossing and the start of the next. */
+const APART = 90
+
+const MIN_SPAN = 1
+
+/**
+ * The passers of a piece of water.
+ *
+ * `eager` throws the day's plan away and crosses one after another, and it
+ * exists for previews and for tests. Nothing should pass it in earnest: a boat
+ * you get for turning the screen on is a boat on a schedule, and the whole
+ * claim of this file is that there is no schedule.
+ */
+export function createPassers(options: PassersOptions): Passers {
+  const random = makeRandom(options.seed ^ 0x30b7)
+  const kinds = options.kinds ?? (["boat", "sonar", "submarine"] as const)
+  const eager = options.eager ?? false
+
+  let width = Math.max(MIN_SPAN, options.width)
+  let height = Math.max(MIN_SPAN, options.height)
+
+  const passing: Passer[] = []
+  const takes = new Map<PassKind, number>()
+
+  /** The churn in the water, and which arm of the wake the next puff is on. */
+  const wake: Froth[] = []
+  let since = 0
+  let arm = 1
+
+  /** What the water is being told to do this tick; see `Startle`. */
+  let felt: Startle | null = null
+
+  /** The day the plan below was drawn for, as `daySeed` counts a day. */
+  let planned = 0
+
+  /** When each kind is due today, in seconds into the day, or null for not today. */
+  const due = new Map<PassKind, number | null>()
+
+  /** How much watched time each still owes before it crosses; see `WAIT_LEAST`. */
+  const waits = new Map<PassKind, number>()
+
+  /** What has already crossed today, and how long since the last one did. */
+  const gone = new Set<PassKind>()
+  let apart = APART
+
+  /**
+   * Draw a day's plan.
+   *
+   * A pure function of the seed and the date, on its own generator, so every
+   * screen of a machine agrees about what today holds without any of them
+   * saying so, and tomorrow is a different day rather than the next few numbers
+   * of this one. Both rolls are spent whatever the first one says, because a
+   * plan whose shape depended on its own outcome would put the kinds in a
+   * queue: a day without a submarine would hand the boat the submarine's hour.
+   */
+  function plan(day: number): void {
+    planned = day
+    gone.clear()
+
+    const dice = makeRandom(stir(options.seed ^ day ^ 0x51ed) | 0)
+
+    for (const kind of kinds) {
+      const happens = dice() < HABITS[kind].chance
+      const at = Math.floor(dice() * DAY)
+      due.set(kind, happens ? at : null)
+      waits.set(kind, WAIT_LEAST + dice() * WAIT_SPAN)
+    }
+  }
+
+  function launch(kind: PassKind): void {
+    const habit = HABITS[kind]
+    const facing = random() < 0.5 ? -1 : 1
+    const scale = width * (habit.sizeLeast + random() * habit.sizeSpan)
+    const deep = habit.deepLeast + random() * habit.deepSpan
+
+    takes.set(kind, habit.takeLeast + random() * habit.takeSpan)
+    gone.add(kind)
+
+    // Owing a puff from the first tick, so a hull is churning by the time the
+    // frame has it rather than a tenth of a second later.
+    since = FROTH_GAP
+
+    // A ping never comes from the middle of the water, because a ring centred
+    // in the picture is a target reticle rather than something out there. It
+    // comes from a side, high up, which is where anything looking for you is.
+    // The two that travel start off the picture entirely; see `OFFING`.
+    const side = kind === "sonar" ? (facing > 0 ? 1 - PING_EDGE : PING_EDGE) : 0
+
+    passing.push({
+      along: 0,
+      facing,
+      kind,
+      scale,
+      weight: 0,
+      x: width * side,
+      y: height * deep,
+    })
+  }
+
+  /**
+   * Which kind, if any, is owed a crossing right now.
+   *
+   * One at a time and a gap between them, because two of these at once is a
+   * busy sea and this is a scene whose whole argument is that almost nothing
+   * happens in it. Everything owed keeps standing until it gets its turn.
+   */
+  function owed(dt: number, clock: number): PassKind | null {
+    if (passing.length > 0 || apart > 0) return null
+
+    // The one that has been waiting longest, rather than the first in the list.
+    // Order in a list is not a reason to go first, and the kind that would
+    // always lose that argument is the submarine: it is owed on one day in
+    // seven, and on those days it would queue behind the two that are owed
+    // every day.
+    let next: PassKind | null = null
+    let oldest = Number.POSITIVE_INFINITY
+
+    for (const kind of kinds) {
+      if (gone.has(kind)) continue
+
+      const at = due.get(kind)
+      if (at == null || clock < at || at >= oldest) continue
+
+      oldest = at
+      next = kind
+    }
+
+    if (!next) return null
+
+    const left = (waits.get(next) ?? 0) - dt
+    waits.set(next, left)
+    return left <= 0 ? next : null
+  }
+
+  /**
+   * Let go of a puff of churn at the stern, if one is due.
+   *
+   * Alternate arms rather than one either side at every beat. Two puffs born at
+   * the same instant on the same line are a mirror, and a mirrored wake is a
+   * drawing of a wake; taking turns puts every puff on its own clock and the
+   * two arms come out of step the way water is. How far off its arm each one
+   * goes is its own business; see `Froth.side`.
+   */
+  function shed(one: Passer, churn: Churn, dt: number): void {
+    since += dt
+    if (since < FROTH_GAP) return
+
+    since = 0
+    arm = -arm
+
+    if (wake.length >= FROTH_MOST) wake.shift()
+
+    wake.push({
+      age: 0,
+      r: one.scale * churn.force * FROTH_SEED * (0.6 + random() * 0.8),
+      scale: one.scale * churn.force,
+      side: arm * (0.3 + random() * 0.7),
+      x: one.x + one.facing * one.scale * churn.x + (random() - 0.5) * one.scale * 0.09,
+      y: one.y + one.scale * churn.y + (random() - 0.5) * one.scale * 0.05,
+    })
+  }
+
+  /**
+   * How hard a ping is being felt, from the front of it.
+   *
+   * The first ring is the one out in front, so it is the one the fish meet.
+   * The rings behind it are a sound arriving twice more and the water has
+   * already been told what it needed to know.
+   */
+  function heard(one: Passer): Startle | null {
+    const front = ringAt(one.along, PING_RINGS[0] ?? 0)
+    if (!front) return null
+
+    return {
+      force: PING_FELT * front.weight * one.weight,
+      reach: front.reach * one.scale,
+      x: one.x,
+      y: one.y,
+    }
+  }
+
+  /** Carry the churn on: swell, open away from the line, thin, and go. */
+  function settle(dt: number): void {
+    for (let at = wake.length - 1; at >= 0; at--) {
+      const puff = wake[at]
+      if (!puff) continue
+
+      puff.age += dt / FROTH_LIFE
+      if (puff.age >= 1) {
+        wake.splice(at, 1)
+        continue
+      }
+
+      puff.r += puff.scale * FROTH_SWELL * dt
+      puff.y += puff.side * puff.scale * FROTH_OPEN * (1 - puff.age) * dt
+    }
+  }
+
+  return {
+    passing,
+
+    resize(nextWidth, nextHeight) {
+      width = Math.max(MIN_SPAN, nextWidth)
+      height = Math.max(MIN_SPAN, nextHeight)
+      // Whatever was crossing is dropped rather than rescaled. A boat that
+      // changed length halfway over would be worse than no boat, and a window
+      // being dragged is the one moment nobody is watching the water anyway.
+      // It stays spent for the day: half a boat is the day's boat.
+      passing.length = 0
+      wake.length = 0
+      felt = null
+    },
+
+    get startle() {
+      return felt
+    },
+
+    step(seconds, now = new Date()) {
+      const dt = Math.min(Math.max(seconds, 0), 0.1)
+      const day = now.getFullYear() * 10000 + (now.getMonth() + 1) * 100 + now.getDate()
+      if (day !== planned) plan(day)
+
+      apart = Math.max(0, apart - dt)
+
+      if (eager) {
+        if (passing.length === 0) {
+          gone.clear()
+          launch(kinds[Math.floor(random() * kinds.length)] ?? "boat")
+        }
+      } else {
+        const next = owed(dt, now.getHours() * 3600 + now.getMinutes() * 60 + now.getSeconds())
+        if (next) launch(next)
+      }
+
+      for (let at = passing.length - 1; at >= 0; at--) {
+        const one = passing[at]
+        if (!one) continue
+
+        one.along += dt / Math.max(takes.get(one.kind) ?? 1, 0.001)
+        if (one.along >= 1) {
+          passing.splice(at, 1)
+          apart = APART
+          continue
+        }
+
+        // In at one end and out at the other, so nothing ever appears. A hull
+        // that popped into being at the edge of the picture would say the
+        // picture has an edge, which is the one thing the water must not admit.
+        one.weight = Math.min(1, one.along / FADE, (1 - one.along) / FADE)
+
+        if (one.kind === "sonar") continue
+        const from = -OFFING * width
+        const to = width * (1 + OFFING)
+        one.x = one.facing > 0 ? from + one.along * (to - from) : to - one.along * (to - from)
+      }
+
+      // What the water is doing about it, after everything has been moved: the
+      // churn comes off a stern that is already where this tick left it, and a
+      // fish is answering the boat it can see rather than the one from last
+      // frame. There is only ever one passer, so the last word is the only one.
+      felt = null
+
+      for (const one of passing) {
+        const churn = CHURN[one.kind]
+        if (churn.force <= 0) {
+          felt = heard(one)
+          continue
+        }
+
+        shed(one, churn, dt)
+        felt = {
+          force: churn.force * one.weight,
+          reach: one.scale * HULL_FELT,
+          x: one.x,
+          y: one.y,
+        }
+      }
+
+      settle(dt)
+    },
+    wake,
+  }
+}
+
+/**
+ * A boat, in a hull two units long, sitting on its own waterline at the origin.
+ *
+ * Seen from under it, which is the only view this water has. That means no
+ * superstructure and no detail above the line: what there is to draw is a hull
+ * from below, and a hull from below is a long shallow curve with a bow at one
+ * end. The `+x` end is the bow.
+ *
+ * Two propellers rather than one, because one on the centreline reads as a
+ * rudder. They say the thing is under power, and the wake coming off them says
+ * the water knows it; like everything else under a unit here they are a path
+ * rather than a shape a renderer would round to whole pixels before scaling it
+ * up.
+ */
+export const HULL = "M-1 0 L1 0 L0.82 0.2 Q0.1 0.34 -0.72 0.28 Q-0.94 0.24 -1 0 Z"
+
+export const SCREWS =
+  "M-0.78 0.15 A0.07 0.07 0 1 1 -0.78 0.29 A0.07 0.07 0 1 1 -0.78 0.15 Z " +
+  "M-0.62 0.19 A0.07 0.07 0 1 1 -0.62 0.33 A0.07 0.07 0 1 1 -0.62 0.19 Z"
+
+/**
+ * A submarine, two units long, on its own centreline at the origin.
+ *
+ * Seen from the side, because unlike the boat it is down here in the water with
+ * everything else, and a thing at your own depth is a thing you see the flank
+ * of. The `+x` end is the bow.
+ *
+ * One path, in six pieces that overlap: hull, sail, the periscope out of the
+ * top of it, the fairwater planes across it, and a fin above and below the
+ * stern. It has to be filled with a winding rule rather than an odd-even one,
+ * which is the whole reason this note exists: under odd-even the sail would cut
+ * a hole out of the hull where it sits on it, and the drawing would come apart
+ * exactly where it is meant to join. Every subpath is wound the same way so a
+ * winding fill sees one silhouette.
+ *
+ * The periscope is four hundredths of a unit wide and nobody will ever
+ * knowingly see it. It is there because the difference between a shape that
+ * reads as a submarine and a shape that reads as a cigar is entirely in what
+ * sticks out of it.
+ */
+export const SUBMARINE =
+  "M-0.92 -0.15 L0.4 -0.17 Q0.86 -0.16 1 0 Q0.86 0.16 0.4 0.17 L-0.92 0.15 " +
+  "Q-1 0.1 -1 0 Q-1 -0.1 -0.92 -0.15 Z " +
+  "M0.02 -0.16 L0.08 -0.44 L0.3 -0.44 L0.34 -0.16 Z " +
+  "M0.16 -0.44 L0.16 -0.62 L0.2 -0.62 L0.2 -0.44 Z " +
+  "M-0.02 -0.38 L0.42 -0.38 L0.42 -0.33 L-0.02 -0.33 Z " +
+  "M-0.74 -0.14 L-0.96 -0.4 L-0.84 -0.4 L-0.62 -0.14 Z " +
+  "M-0.62 0.14 L-0.84 0.4 L-0.96 0.4 L-0.74 0.14 Z"
+
+/**
+ * Its screw, as two blades on a shaft astern.
+ *
+ * Apart from the hull for the same reason the boat's is: it is the one part
+ * that says the thing is under power rather than sinking, and a renderer may
+ * want to weight it differently or leave it out at a size where it would be a
+ * smudge.
+ */
+export const SUB_SCREW =
+  "M-1 -0.02 L-1.14 -0.14 L-1.18 -0.06 L-1.04 0 L-1.18 0.06 L-1.14 0.14 L-1 0.02 Z"
+
+/**
+ * How many rings a ping puts out, and where in its life each one starts.
+ *
+ * Three, staggered, which is what a ping sounds like and therefore what it
+ * should look like. One ring is a bubble.
+ */
+export const PING_RINGS: readonly number[] = [0, 0.16, 0.32]
+
+/**
+ * How far out a ring has got and how loud it still is, at `along` through the
+ * whole ping.
+ *
+ * The reach eases out and the weight falls off with it, which is a wave losing
+ * itself in the water rather than a circle being scaled. Returns null before
+ * its ring has started or after it has gone, so a renderer can skip it without
+ * knowing the arithmetic.
+ */
+export function ringAt(along: number, offset: number): { reach: number; weight: number } | null {
+  const t = (along - offset) / (1 - offset)
+  if (t <= 0 || t >= 1) return null
+
+  return { reach: 1 - (1 - t) ** 2, weight: (1 - t) ** 1.6 }
+}