@codincod/ornament 0.0.0-stage → 0.2.0

package/src/census.ts

@@ -0,0 +1,262 @@
+/**
+ * How much of each animal a sea holds.
+ *
+ * The other half of `sizes.ts`, and it is here for the same fault. That file
+ * was written because every drawing had picked a size that looked right on its
+ * own and a boat had come out the size of a turtle. This one is the same story
+ * told about how many: every renderer picked a density that read well where it
+ * was written, and the water ended up with more crabs on the sand than fish in
+ * the column. A crab at eleven per thousand pixels of bed is defensible where
+ * it stands. A fish at one per sixty thousand square pixels is defensible where
+ * it stands. What lies between them is a sea nobody has ever swum in, and
+ * nothing catches it, because the two numbers are never read side by side.
+ *
+ * So every animal says how many of it a stretch of reef holds, in the unit a
+ * survey would report it in, and this turns that into how many to draw.
+ *
+ * ## Why the numbers are not used as they stand
+ *
+ * A reef carries upwards of a hundred fish over every hundred square metres of
+ * it, and most of them are small ones hanging above the coral. Drawn as
+ * counted, that is a screen of fish with a sea somewhere behind them, and
+ * everything else in the water is lost among them. Thin the whole table until
+ * the fish are countable and the crab, the octopus and the starfish all round
+ * to none, which leaves a bare floor under a busy column.
+ *
+ * The root is the compression that settles it, and it is the same bargain
+ * `sizes.ts` strikes over length. Something commoner is still drawn commoner,
+ * so the order is never wrong; the ends are pulled in far enough that the rare
+ * animal is still in the water somewhere. What is kept is which is commoner,
+ * rather than by how much.
+ *
+ * ## The mix comes out of the same table
+ *
+ * How common a moon jelly is against a comb jelly is the question of how common
+ * a jellyfish is against a fish, asked inside one family. A file that answered
+ * it in its own column would answer it a second way by the end of the year, so
+ * the shares a family draws its next animal from are these numbers normalised.
+ * A family after a count and a family after a mix read one statement.
+ *
+ * ## A day of its own
+ *
+ * `plenty.ts` decides how good a year the whole sea is having. This decides
+ * which animal is having it. Every kind swings from one day to the next on its
+ * own draw, and how far it swings is its own business: blooming is what a
+ * jellyfish does and a grouper does not. So `swings` is a column, and a week of
+ * water is a comb jelly week and then a moon jelly one.
+ *
+ * ## What it does not decide
+ *
+ * Where anything goes, when it turns up, or whether a renderer can afford it.
+ * A shark and a manta are in here for their share against each other and for
+ * nothing else, because what actually puts one in the water is a rest between
+ * crossings (`visitors.ts`); a bed with a thousand plants on it is capped by
+ * whoever has to draw them. This is what the sea holds, and the appetite is
+ * still `plenty.ts`.
+ */
+
+import { stir } from "./perlin.ts"
+import { thriving } from "./plenty.ts"
+
+export type Kind =
+  | "barrel"
+  | "box"
+  | "comb"
+  | "crab"
+  | "crown"
+  | "cruiser"
+  | "darter"
+  | "dolphin"
+  | "drifter"
+  | "eel"
+  | "escort"
+  | "mane"
+  | "manowar"
+  | "manta"
+  | "mermaid"
+  | "moon"
+  | "octopus"
+  | "puffer"
+  | "shark"
+  | "squid"
+  | "starfish"
+  | "stinger"
+  | "swordfish"
+  | "turtle"
+
+interface Held {
+  /**
+   * How many of it live over a hundred square metres of reef.
+   *
+   * The unit a transect is counted in, so a number here can be argued with by
+   * somebody who has swum one. It is what stands in the water at a given
+   * moment rather than what passes through in a season: a shark is scarce here
+   * because a shark is scarce at any one moment, and it is scarce in the
+   * picture for the same reason.
+   */
+  readonly holds: number
+  /**
+   * How hard a day is allowed to swing it, as a power of the day's own draw.
+   *
+   * At 0 a kind is as common today as it was yesterday, which is what holding a
+   * territory looks like from outside. At 1 it rises and falls with the year
+   * `plenty.ts` decided. Past that it blooms: the draw is weighted low, so a
+   * high power leaves most weeks ordinary or thin and now and then fills the
+   * water with one animal, which is the only shape a bloom comes in.
+   */
+  readonly swings: number
+}
+
+/**
+ * What a reef holds, animal by animal.
+ *
+ * Read down the `holds` column rather than across a row: the column is the
+ * whole point of the file, and every number in it was chosen against its
+ * neighbours rather than against how much of the picture the animal deserves.
+ * Where a figure is a range in the wild it is the ordinary end of that range,
+ * since `swings` is what carries the rest.
+ */
+const SEA: Readonly<Record<Kind, Held>> = {
+  /** A dustbin lid of a jelly, in on a season rather than resident. */
+  barrel: { holds: 0.09, swings: 1.8 },
+  /** Small, scarce, and inshore for part of the year. */
+  box: { holds: 0.025, swings: 1.6 },
+  /** Comb jellies outnumber everything else adrift in the water. */
+  comb: { holds: 0.66, swings: 2 },
+  /** Most crabs on a reef are under it. This is the few that are out. */
+  crab: { holds: 3, swings: 0.4 },
+  /** Deep water, and up here only where cold water is. */
+  crown: { holds: 0.03, swings: 1.4 },
+  /** Snapper, surgeon, parrot: the fish a reef reads as at a glance. */
+  cruiser: { holds: 24, swings: 0.35 },
+  /** Damsels and anthias over the coral, which is most of what a reef holds. */
+  darter: { holds: 90, swings: 0.5 },
+  /** They pass along a coast rather than live on one stretch of it. */
+  dolphin: { holds: 0.04, swings: 0.5 },
+  /** A grouper holds a hole and there are only so many holes. */
+  drifter: { holds: 1.1, swings: 0.15 },
+  /** Where there is a bed of them there are hundreds, and where there is not
+   *  there are none. The colony's own arithmetic thins it to what fits. */
+  eel: { holds: 140, swings: 1.2 },
+  /** Butterflyfish, which go about in twos and are never far apart. */
+  escort: { holds: 6, swings: 0.35 },
+  /** A cold water animal, and in warm water a rarity worth the day. */
+  mane: { holds: 0.06, swings: 1.8 },
+  /** It goes where the wind puts it, so it arrives in a fleet or not at all. */
+  manowar: { holds: 0.015, swings: 2.6 },
+  /** Scarcest of the large ones, and tied to the few places they gather. */
+  manta: { holds: 0.012, swings: 0.7 },
+  /** Not an animal and not on a density; `visitors.ts` keeps her calendar. */
+  mermaid: { holds: 0, swings: 0 },
+  /** The jelly anybody can name, and it is common enough to earn that. */
+  moon: { holds: 0.45, swings: 2 },
+  /** One to a den, and a den is a find. */
+  octopus: { holds: 0.5, swings: 0.25 },
+  /** Solitary, territorial, and one to a stretch of reef this size. */
+  puffer: { holds: 0.4, swings: 0.4 },
+  /** A reef shark works a stretch of reef that is larger than this one. */
+  shark: { holds: 0.09, swings: 0.4 },
+  /** Reef squid keep company, so where there is one there are a few. */
+  squid: { holds: 0.6, swings: 0.8 },
+  /** Slow, obvious, and lying in the open, which is why they read as common. */
+  starfish: { holds: 4, swings: 0.5 },
+  /** The sea nettle, in on the season the way the barrel is. */
+  stinger: { holds: 0.18, swings: 1.8 },
+  /** A billfish over a reef is a visitor from the water beyond it. */
+  swordfish: { holds: 0.05, swings: 0.6 },
+  /** They graze a reef and sleep under its ledges, so one is about. */
+  turtle: { holds: 0.12, swings: 0.35 },
+}
+
+/**
+ * How hard the range is pulled in.
+ *
+ * The root `sizes.ts` takes of a length, taken here of a density, and picked
+ * the same way: at this it is the small fish that carry the water and the crab
+ * and the octopus are still in it. Nearer 1 and the darters bury everything
+ * else; nearer 0 and every animal in the sea is about as common as every other,
+ * which is the picture this file exists to prevent.
+ */
+const ROOT = 0.55
+
+/**
+ * How wide a stretch of sea the box is a window on, in metres.
+ *
+ * It follows from `sizes.ts` rather than being chosen here. A fish of a third
+ * of a metre swimming at eight comes out at a fortieth of the box, and a window
+ * that fits forty of those across it is a window on about this much water. It
+ * is worth knowing that the answer is a room and not an ocean: everything in
+ * this scene is close enough to touch, which is why a shark crossing it is an
+ * event.
+ */
+const ACROSS = 13
+
+/**
+ * How many the sea is drawn with, against how many it holds.
+ *
+ * The one number the file is tuned by, and it was fixed by the shoal: the
+ * desktop's water held about forty fish before any of this was written down, so
+ * it holds about forty now, and every other animal moved to meet them.
+ */
+const SCALE = 2.1
+
+/** Square metres of reef in view, which a taller window sees more of. */
+function seaIn(width: number, height: number): number {
+  return ACROSS * ACROSS * (height / Math.max(1, width))
+}
+
+/**
+ * A number of this kind's own, so no two kinds have the same day.
+ *
+ * Off the name rather than off a position in the table, because a position
+ * moves when something is added above it, and a sea that changed everywhere
+ * because a jellyfish was added is a sea nobody can reason about.
+ */
+function own(kind: Kind): number {
+  let run = 0
+  for (let at = 0; at < kind.length; at++) run = stir(run + kind.charCodeAt(at))
+  return run & 0xffff
+}
+
+/**
+ * How common this kind is drawn today: compressed, and then given its day.
+ *
+ * That order is the whole of it. Compressed first and swung afterwards, a bloom
+ * is a bloom; swung first and compressed afterwards, the root takes most of the
+ * day back off it again and a week of water is a week of the same water.
+ */
+function drawnHolds(kind: Kind, seed: number): number {
+  const held = SEA[kind]
+  if (held.holds <= 0) return 0
+  return held.holds ** ROOT * thriving(seed, own(kind)) ** held.swings
+}
+
+/**
+ * How many of these kinds to draw in a box this size, on this day.
+ *
+ * Comes back as it falls out rather than rounded, since a caller with a floor
+ * and a ceiling of its own wants the raw appetite to apply them to.
+ */
+export function manyIn(
+  kinds: readonly Kind[],
+  width: number,
+  height: number,
+  seed: number,
+): number {
+  let sum = 0
+  for (const kind of kinds) sum += drawnHolds(kind, seed)
+  return (SCALE * sum * seaIn(width, height)) / 100
+}
+
+/**
+ * The shares to draw one of these kinds from, on this day.
+ *
+ * Weights against each other rather than chances, which is the shape every
+ * family in this ornament already wanted. They are not normalised, because
+ * nothing that draws from them needs them to be.
+ */
+export function mixOf<K extends Kind>(kinds: readonly K[], seed: number): Record<K, number> {
+  const mix = {} as Record<K, number>
+  for (const kind of kinds) mix[kind] = drawnHolds(kind, seed)
+  return mix
+}