@codincod/ornament 0.0.0-stage → 0.2.0

package/src/seabed.ts

@@ -0,0 +1,525 @@
+/**
+ * The bottom: what the water sits on, and what is standing further out.
+ *
+ * The ground layer of a seascape, kept free of the DOM the way the rest of the
+ * ornament is. Nothing here moves, so there is no `step`. A floor that drifted
+ * would be an earthquake.
+ *
+ * ## Why a seascape needs one
+ *
+ * Fish, snow and light give water a volume but no bottom, and water with no
+ * bottom has no scale in it: a picture of animals at unknown distances. Put a
+ * floor in and everything above it acquires a height. It is also the thing
+ * every other layer needs to exist at all, since kelp has to be rooted, a vent
+ * has to come out of something, and a wreck has to be lying on it.
+ *
+ * ## The floor
+ *
+ * A profile sampled across the box, not a straight line and not a jagged one.
+ * Two octaves of the same Perlin field the fish read: a long swell that puts
+ * the whole bed high at one end, and a shorter one for the lumps. Anything more
+ * and it reads as a mountain range seen from a helicopter, which is a landscape
+ * rather than a seabed.
+ *
+ * `floorAt` is the interface the rest of the scene actually uses, and it is
+ * exact rather than a lookup into `ridge`: a stone or a kelp plant sitting a
+ * pixel above the sand looks like it is hovering, and that is the sort of
+ * mistake that is invisible in a still and obvious in motion.
+ *
+ * ## The floor has a second axis, and it is distance
+ *
+ * `floorAt(x, depth)` is the ground under something standing that far back. The
+ * whole bed used to be one line, which meant every rooted thing in the water
+ * stood on the same line: a hundred plants of graded sizes all growing out of
+ * one edge, which reads as a stage rather than as a place. Depth is a picture's
+ * first subject and a single ridge cannot carry it.
+ *
+ * So the ground climbs the box as it goes back, its swells grow broad, and it
+ * reads a different lane of the same field at each distance, which is what
+ * keeps the far ground a different shape rather than the near one lifted. Where
+ * a far hill and a near one overlap is where the eye reads the gap between
+ * them, and the dip between two hills is a valley for free.
+ *
+ * `ranges` are that ground cut at a handful of distances, which is what a
+ * renderer draws. They are ground rather than scenery: things root to them, and
+ * a plant at a given depth is standing on `floorAt` at that same depth.
+ *
+ * ## What is standing further out
+ *
+ * Cliffs, in the murk behind all of it. They are not terrain the scene uses;
+ * nothing roots to them and nothing collides with them. They exist because a
+ * silhouette at the back of the water is the cheapest possible statement that
+ * the water continues past the edge of the picture, and without one the scene
+ * is a tank.
+ *
+ * They stand on the ground at their own distance, which is the furthest ground
+ * there is, and they rise well above it: a cliff that stopped at the same
+ * height as what it stands on would read as more ground.
+ */
+
+import { makeNoise2, makeRandom } from "./perlin.ts"
+
+export interface Point {
+  readonly x: number
+  readonly y: number
+}
+
+export interface Stone {
+  /** How far back it lies, which is its weight and most of its size. */
+  readonly depth: number
+  /** How far it is turned, in radians. Stones are not upright. */
+  readonly lean: number
+  /** How wide and how tall, in px. */
+  readonly rise: number
+  readonly span: number
+  readonly x: number
+  readonly y: number
+}
+
+export interface Cliff {
+  /** How far back it stands, which is all its weight. */
+  readonly depth: number
+  /** Its skyline, left to right, running past both edges of the box. */
+  readonly ridge: readonly Point[]
+}
+
+/** The ground at one distance, from the furthest to just behind the sand. */
+export interface Range {
+  readonly depth: number
+  /** Its outline, left to right along the top. */
+  readonly ridge: readonly Point[]
+}
+
+export interface Seabed {
+  readonly cliffs: readonly Cliff[]
+  /**
+   * The y of the ground at x, for anything that has to sit on it.
+   *
+   * `depth` is how far forward the thing standing there is, 1 at the front of
+   * the picture and towards 0 in the murk. It defaults to the front, so a
+   * caller with nothing to say about distance gets the sand it always got.
+   */
+  floorAt(x: number, depth?: number): number
+  readonly ranges: readonly Range[]
+  resize(width: number, height: number): void
+  /** The sand's own outline, left to right. */
+  readonly ridge: readonly Point[]
+  readonly stones: readonly Stone[]
+}
+
+export interface SeabedOptions {
+  cliffs?: number
+  height: number
+  ranges?: number
+  seed: number
+  stones?: number
+  width: number
+}
+
+/**
+ * How much of the box is left under the nearest ground there is, and how far
+ * that ground rolls.
+ *
+ * Almost none, and that is the whole of it. It used to be a tenth, which read
+ * as a shelf: the ground at the front of the picture stopped a tenth of the way
+ * up the box and the bottom of the screen was the face of it, seen from above,
+ * with nothing on it. Nothing could be on it either, since the nearest a rooted
+ * thing goes is this line, so every plant, stone and crab in the scene stood
+ * along one edge with bare sand below them.
+ *
+ * Bringing it to the floor of the box is what gives the front of the picture
+ * somewhere to be. The near end of every distance in the scene now lands at the
+ * bottom edge, so the bed spreads down to it and the nearest plants are cut off
+ * by it, which is what being close to something looks like. The ground is no
+ * less shallow for it: what closes the bottom of the scene is the stack of
+ * bands behind this one, each shut under the box, and they are where they were.
+ */
+const FLOOR_SEAT = 0.01
+
+const FLOOR_ROLL = 0.085
+
+/**
+ * The same two, for the furthest ground the water has.
+ *
+ * It sits a third of the way up the box, which is as far back as a seascape can
+ * go before the ground is level with the fish and the picture has no sky in it.
+ * It rolls harder than the sand does because what is up there is hills: the
+ * near bed is a floor with lumps on it, and the far one is country.
+ */
+const HORIZON_SEAT = 0.36
+
+const HORIZON_ROLL = 0.12
+
+/** How many features of the long swell and the short one fit across the box. */
+const SWELL_CELLS = 1.3
+
+const LUMP_CELLS = 5.5
+
+/**
+ * The same two at the horizon, where everything is broader.
+ *
+ * Distance takes the detail out of ground long before it takes the shape, which
+ * is why a far hill is a silhouette and a near one is a slope with rubble on
+ * it. Fewer features across the same box is the whole of that.
+ */
+const HORIZON_SWELL_CELLS = 0.8
+
+const HORIZON_LUMP_CELLS = 2.1
+
+/**
+ * How fast the ground climbs the box as it goes back.
+ *
+ * Distance on a flat plane is not linear on the screen and never has been: the
+ * ground a step in front of your foot takes a third of the picture and the
+ * ground a mile off takes a hair, and everything between the two is squeezed
+ * towards the horizon. Held to a straight line, bands of ground come out evenly
+ * spaced, and evenly spaced lines across a picture are a contour map.
+ *
+ * An exponent rather than a proper projection, because there is no camera here
+ * and nothing to be right about: what it has to do is bunch at the back and
+ * open out at the front, which is the whole of what the eye is reading.
+ */
+const DEPTH_FALL = 1.6
+
+/**
+ * How far the field is walked as the ground goes back.
+ *
+ * Distance is the second axis of one Perlin field, so this is how much of it a
+ * screen's worth of distance crosses. Too little and the far hills are the near
+ * lumps drawn higher, which is the one thing that gives a flat picture away;
+ * this is enough that no two distances share a shape.
+ */
+const DISTANCE_LANES = 3.1
+
+/** How much of the roll belongs to the lumps rather than the swell. */
+const LUMP_SHARE = 0.34
+
+/** How finely the sand's outline is cut. */
+const RIDGE_STEPS = 96
+
+/** How far past each side the outline runs, so no edge shows a seam. */
+const OVERHANG = 40
+
+/** The ends of a stone's width in px, and how tall one is against that. */
+const STONE_SMALLEST = 9
+
+const STONE_LARGEST = 38
+
+const STONE_SQUAT = 0.62
+
+/** How far a stone may be turned, in radians. */
+const STONE_LEAN = 0.5
+
+/**
+ * How far back stones lie, and how much of a stone's drawn size is that.
+ *
+ * They go back further than a plant does, because scree is what a slope is made
+ * of and a slope with rubble only along its foot is a slope somebody swept.
+ * Nothing like the whole of the size, though: a stone at a tenth of its size is
+ * a grain of sand, and a beach of those is a texture rather than a distance.
+ */
+const STONE_FAR = 0.3
+
+const STONE_NEAR = 1
+
+const STONE_SHRINK = 0.55
+
+/**
+ * How far back the ground is cut, from the furthest band to the nearest.
+ *
+ * The near end stops well short of the sand, because two ridges a hand apart
+ * read as one ridge that has been drawn twice. What is wanted is a clear gap
+ * between what you are standing on and what is behind it.
+ */
+const RANGE_FAR = 0.08
+
+const RANGE_NEAR = 0.75
+
+/**
+ * How high a cliff stands above the ground it is on, as a share of the box, and
+ * how wide.
+ *
+ * Wide, because a cliff is being read at a distance where the only information
+ * is its outline. A small one is a rock, and a rock at the back of the water is
+ * a stone somebody has drawn badly. Not as tall as it once was: it used to
+ * stand on the sand at the front of the picture and had a whole box to climb,
+ * and it stands on the horizon now, where the water above it is all there is
+ * left.
+ *
+ * Both come off one roll of the dice, so a summit that is high is broad and one
+ * that is low is narrow. Rolled apart, the tall end of one meets the narrow end
+ * of the other every so often, and what that draws is a tooth: sides at sixty
+ * degrees coming to a point, which no mountain has and nothing standing in
+ * water keeps.
+ */
+const CLIFF_RISE_LEAST = 0.06
+
+const CLIFF_RISE_SPAN = 0.16
+
+const CLIFF_SPAN_LEAST = 0.12
+
+const CLIFF_SPAN_SPAN = 0.26
+
+/**
+ * How finely a range's skyline is cut.
+ *
+ * Finer than it was. It used to be one hill a few hundred px wide and fourteen
+ * steps was plenty for that; it is the whole width of the box and then some
+ * now, and fourteen steps across a wall would be a summit with three sides.
+ *
+ * Finer again, because the skyline carries what grows on it, and a fringe cut
+ * at thirteen px a step is a row of thumbs rather than a scruff. Points are the
+ * cheap half of the bill down here: a range is one shape however many of them
+ * its outline holds.
+ */
+const CLIFF_STEPS = 280
+
+/**
+ * How far the growth on a skyline stands off it, as a share of the box, how
+ * many stretches of it there are across the width, and how much of a range has
+ * nothing on it at all.
+ *
+ * Bare rock at this distance is a shape somebody forgot to finish, which is the
+ * argument `crags.ts` makes about the near wall and is no less true of the far
+ * one. Nothing up there can be told apart: a hill at the back of the water is
+ * an outline, so what a plant on it amounts to is that the outline stops being
+ * smooth. Colonies rather than an even fur, for the reason a near face is
+ * crowded in places and bare in others, and the same reason a summit under a
+ * lawn is a hill somebody has drawn hair on.
+ */
+const FRINGE_RISE = 0.038
+
+const FRINGE_PATCHES = 3.4
+
+const FRINGE_BARE = 0.12
+
+/** How far back the ranges stand. Nearly the colour of the water, and no nearer. */
+const CLIFF_DEEP = 0.05
+
+const CLIFF_NEAR = 0.16
+
+/**
+ * How many ranges the summits are shared out between.
+ *
+ * Each is a skyline of its own at its own distance, so what the eye gets is one
+ * range standing behind another rather than a row of hills at one remove. Three,
+ * because two is a pair and four at these weights is two the reader can find and
+ * two they cannot.
+ */
+const CLIFF_RANGES = 3
+
+/** How far apart two stands of growth on a skyline are, in px. */
+const STRAND_SPAN = 26
+
+const MIN_SPAN = 1
+
+/** Where between two numbers a distance falls, 0 at the back and 1 at the front. */
+const mix = (far: number, near: number, at: number): number => far + (near - far) * at
+
+export function createSeabed(options: SeabedOptions): Seabed {
+  const colonies = makeNoise2(options.seed ^ 0xc010)
+  const sprigs = makeNoise2(options.seed ^ 0x5197)
+  const swell = makeNoise2(options.seed ^ 0x5eab)
+  const lumps = makeNoise2(options.seed ^ 0x10c5)
+  const random = makeRandom(options.seed ^ 0x2d0e)
+
+  let width = Math.max(MIN_SPAN, options.width)
+  let height = Math.max(MIN_SPAN, options.height)
+
+  /**
+   * The ground at x, as far back as `depth` says.
+   *
+   * Everything a distance changes about ground is here and nowhere else, which
+   * is what lets a plant, a stone and a whole cut band all agree about where
+   * the bottom is at their own distance. It climbs, it broadens, it flattens
+   * its detail, and it reads its own lane of the field so that it is a
+   * different piece of country rather than the same one drawn higher.
+   */
+  function floorAt(x: number, depth = 1): number {
+    const near = Math.max(0, Math.min(1, depth))
+    const lane = (1 - near) * DISTANCE_LANES
+    const up = near ** DEPTH_FALL
+
+    const seat = height * (1 - mix(HORIZON_SEAT, FLOOR_SEAT, up))
+    const roll = height * mix(HORIZON_ROLL, FLOOR_ROLL, up)
+    const long = swell((x / width) * mix(HORIZON_SWELL_CELLS, SWELL_CELLS, near), lane)
+    const short = lumps((x / width) * mix(HORIZON_LUMP_CELLS, LUMP_CELLS, near), lane + 4.7)
+
+    return seat - (long * (1 - LUMP_SHARE) + short * LUMP_SHARE) * roll
+  }
+
+  function cutRidge(depth: number): Point[] {
+    const points: Point[] = []
+    for (let at = 0; at <= RIDGE_STEPS; at++) {
+      const x = -OVERHANG + (at / RIDGE_STEPS) * (width + OVERHANG * 2)
+      points.push({ x, y: floorAt(x, depth) })
+    }
+    return points
+  }
+
+  /**
+   * The ground cut at each distance, furthest first.
+   *
+   * Spread evenly rather than rolled, because bands are read as a stack: two
+   * that landed at the same distance would be one band with a seam in it, and
+   * the whole of what they are for is the gap between them.
+   */
+  function cutRanges(count: number): Range[] {
+    const bands: Range[] = []
+    for (let at = 0; at < count; at++) {
+      const depth =
+        count < 2 ? RANGE_FAR : RANGE_FAR + (at / (count - 1)) * (RANGE_NEAR - RANGE_FAR)
+      bands.push({ depth, ridge: cutRidge(depth) })
+    }
+    return bands
+  }
+
+  /**
+   * How far something growing at x stands off the skyline there.
+   *
+   * Every other point of the outline and none of the ones between, which is
+   * what makes this read as growth rather than as more rock: a strand is a
+   * spike with a gap beside it, and a smooth field at any frequency is a lump
+   * however small it is drawn. What varies is how tall each one is and whether
+   * there is anything there at all, and both are read off the water rather than
+   * rolled, so a range's fringe is a fact about that range and comes back the
+   * same on a resize.
+   */
+  function fringe(x: number, depth: number, at: number): number {
+    if (at % 2 === 0) return 0
+
+    const patch = colonies((x / width) * FRINGE_PATCHES, depth * 7.3)
+    if (patch < FRINGE_BARE) return 0
+
+    const thick = (patch - FRINGE_BARE) / (1 - FRINGE_BARE)
+    const stand = Math.abs(sprigs(x / STRAND_SPAN, depth * 11.7))
+
+    return height * FRINGE_RISE * thick * (0.4 + stand * 0.6)
+  }
+
+  /**
+   * One cliff, as a lump of its own.
+   *
+   * A summit is a half-cosine rather than noise, so it has a peak and two
+   * shoulders instead of a row of equal bumps, and the noise is what stops the
+   * two shoulders matching. That much is the only thing between one of these and
+   * a hill drawn by a child.
+   *
+   * What is returned is a whole skyline and not one hill. Each used to be its
+   * own little polygon dropped on the bed, and a shape that stops somewhere in
+   * the middle of the picture has ends, which is a problem no amount of colour
+   * fixes: shut under the box, the way a band of ground is, it grew two vertical
+   * walls running the height of the picture and a mountain came to a straight
+   * edge and fell off it. Shut along its own foot instead, the ends taper to a
+   * knife and lie on the ground in front like a crack in it.
+   *
+   * A range has no ends. This runs past both edges of the box exactly as the
+   * ground does, its summits are the highest of however many domes are standing
+   * at that x, and what closes it is off the side of the picture where nobody
+   * is looking. Between the summits it is simply the ground at its own distance,
+   * which is what the land between two mountains is.
+   */
+  function raise(depth: number, peaks: number): Cliff {
+    const domes = Array.from({ length: Math.max(1, peaks) }, () => {
+      const bulk = random()
+
+      return {
+        middle: random() * width,
+        rise: height * (CLIFF_RISE_LEAST + bulk * CLIFF_RISE_SPAN),
+        rough: makeNoise2((random() * 0xffff) | 0),
+        span: width * (CLIFF_SPAN_LEAST + bulk * CLIFF_SPAN_SPAN),
+      }
+    })
+
+    const ridge: Point[] = []
+    for (let at = 0; at <= CLIFF_STEPS; at++) {
+      const x = -OVERHANG + (at / CLIFF_STEPS) * (width + OVERHANG * 2)
+
+      let lift = 0
+      for (const dome of domes) {
+        const t = (x - (dome.middle - dome.span / 2)) / dome.span
+        if (t <= 0 || t >= 1) continue
+        const swell = (1 - Math.cos(t * Math.PI * 2)) / 2
+        lift = Math.max(lift, dome.rise * swell * (1 + dome.rough(t * 3.1, 0) * 0.34))
+      }
+
+      ridge.push({ x, y: floorAt(x, depth) - lift - fringe(x, depth, at) })
+    }
+
+    return { depth, ridge }
+  }
+
+  function settle(): Stone {
+    const x = random() * width
+    const depth = STONE_FAR + random() * (STONE_NEAR - STONE_FAR)
+    const shrink = 1 - STONE_SHRINK + STONE_SHRINK * depth
+    const span = (STONE_SMALLEST + random() ** 1.5 * (STONE_LARGEST - STONE_SMALLEST)) * shrink
+
+    return {
+      depth,
+      lean: (random() - 0.5) * STONE_LEAN * 2,
+      rise: span * STONE_SQUAT * (0.7 + random() * 0.6),
+      span,
+      x,
+      y: floorAt(x, depth),
+    }
+  }
+
+  let ridge = cutRidge(1)
+  let ranges = cutRanges(Math.max(0, options.ranges ?? 0))
+  /**
+   * The ranges, furthest first, with the summits shared out between them.
+   *
+   * `cliffs` is a count of summits rather than of ranges, which is what a caller
+   * counting against the width of its box is actually asking about: a wider
+   * screen wants more peaks along the same skylines, not more skylines.
+   */
+  function skylines(): Cliff[] {
+    const summits = Math.max(0, options.cliffs ?? 0)
+    if (summits === 0) return []
+
+    return Array.from({ length: CLIFF_RANGES }, (_, at) => {
+      const step = CLIFF_RANGES > 1 ? at / (CLIFF_RANGES - 1) : 0
+      const share =
+        Math.round((summits * (at + 1)) / CLIFF_RANGES) - Math.round((summits * at) / CLIFF_RANGES)
+
+      return raise(CLIFF_DEEP + step * (CLIFF_NEAR - CLIFF_DEEP), share)
+    })
+  }
+
+  let cliffs = skylines()
+  let stones = Array.from({ length: Math.max(0, options.stones ?? 0) }, settle)
+
+  return {
+    get cliffs() {
+      return cliffs
+    },
+    floorAt,
+    get ranges() {
+      return ranges
+    },
+
+    /**
+     * A resized box is rebuilt rather than scaled.
+     *
+     * Everything here is a pure function of the seed and the box, so rebuilding
+     * gives the same bed the same box would have had from the start. Scaling
+     * would stretch the sand's own grain, and a seabed that got wider when a
+     * window did would be the one thing on screen admitting it is a drawing.
+     */
+    resize(nextWidth, nextHeight) {
+      width = Math.max(MIN_SPAN, nextWidth)
+      height = Math.max(MIN_SPAN, nextHeight)
+      ridge = cutRidge(1)
+      ranges = cutRanges(ranges.length)
+      cliffs = skylines()
+      stones = stones.map(settle)
+    },
+    get ridge() {
+      return ridge
+    },
+    get stones() {
+      return stones
+    },
+  }
+}