@codincod/ornament 0.0.0-stage → 0.1.0

package/src/perlin.ts

@@ -0,0 +1,168 @@
+/**
+ * Ken Perlin's gradient noise, in two dimensions, as first published.
+ *
+ * Perlin wrote it in 1983 because the computer graphics he was working on
+ * looked machine-made, and the film he was working on was Tron. That is the
+ * whole reason this file exists here: the one surface that draws it is the page
+ * of the world that plays that film's game, and the joke only lands if the
+ * noise is really his.
+ *
+ * The shape of the algorithm: every integer lattice point owns a fixed random
+ * unit gradient. To sample a point, take the four lattice corners around it,
+ * dot each corner's gradient with the vector running from that corner to the
+ * point, and blend the four results together. The blend runs through Perlin's
+ * S-curve rather than straight lerps, and that is the part that matters; with
+ * linear blending the lattice shows up as visible creases on every cell edge.
+ *
+ * Kept deliberately small: one seedable 2D field, no octaves, no simplex.
+ * Nothing else in the codebase wants coherent noise, and a general noise
+ * library would be a lot of unused surface. If a second caller ever needs
+ * fractal detail, sum a few of these at doubling frequencies rather than
+ * growing this file.
+ *
+ * Because the gradients come from a fixed 256-entry table, the field repeats
+ * every 256 units. That is the algorithm's well-known limitation, and it costs
+ * nothing here: the flow field samples a few dozen units across at most.
+ */
+
+const SIZE = 256
+const MASK = SIZE - 1
+
+/**
+ * Two-dimensional gradient noise, returning roughly [-1, 1].
+ *
+ * "Roughly", because the theoretical bound is what a sample can reach when it
+ * lands exactly where two opposed gradients line up, which almost never
+ * happens. Callers that need a hard range must clamp; the flow field does not,
+ * since it only reads the value as an angle.
+ */
+export type Noise2 = (x: number, y: number) => number
+
+/**
+ * Gradient noise in 2D peaks at sqrt(2)/2 rather than 1, so the raw dot
+ * products come back short. Scaling by its reciprocal puts the field back on
+ * the [-1, 1] every caller expects to be handed.
+ */
+const NORMALISE = Math.SQRT2
+
+/**
+ * xorshift32, so the field is identical on every load and in every browser.
+ *
+ * `Math.random()` would do the job and would also mean the page looked subtly
+ * different every time it was opened, which makes an ornament feel like a
+ * glitch rather than a decision. A fixed seed makes the field a drawing
+ * somebody chose.
+ *
+ * Exported because the flow field wants the same guarantee for its riders'
+ * starting positions. Noise is the wrong tool for that: its values cluster
+ * around zero rather than spreading evenly, so twelve riders placed by noise
+ * all start in a knot in the middle of the screen.
+ */
+export function makeRandom(seed: number): () => number {
+  let state = seed | 0 || 1
+  return () => {
+    state ^= state << 13
+    state ^= state >>> 17
+    state ^= state << 5
+    return (state >>> 0) / 0x1_0000_0000
+  }
+}
+
+/**
+ * One number scattered into another.
+ *
+ * Two seeds that differ in one low bit are two xorshift states that differ in
+ * one low bit, and those walk two neighbouring paths for their first few
+ * numbers: a day and the day after it laying out the same sea nudged sideways,
+ * or a plan that says the same thing on the first of the month as on the
+ * second. This is the avalanche step that stops it, one multiply and two folds,
+ * so a bit anywhere reaches every bit.
+ *
+ * Wanted wherever a seed is derived from something that counts rather than
+ * something arbitrary: a date, a day of the month, the id of an element. A seed
+ * somebody picked out of the air needs none of it.
+ */
+export function stir(from: number): number {
+  let seed = from >>> 0
+  seed = Math.imul(seed ^ (seed >>> 16), 0x45d9f3b) >>> 0
+  return (seed ^ (seed >>> 16)) >>> 0
+}
+
+export function makeNoise2(seed: number): Noise2 {
+  const random = makeRandom(seed)
+
+  const permutation = new Int32Array(SIZE + SIZE + 2)
+  const gradientX = new Float64Array(SIZE + SIZE + 2)
+  const gradientY = new Float64Array(SIZE + SIZE + 2)
+
+  for (let i = 0; i < SIZE; i++) {
+    permutation[i] = i
+    const angle = random() * Math.PI * 2
+    gradientX[i] = Math.cos(angle)
+    gradientY[i] = Math.sin(angle)
+  }
+
+  for (let i = SIZE - 1; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1))
+    const held = permutation[i]!
+    permutation[i] = permutation[j]!
+    permutation[j] = held
+  }
+
+  for (let i = 0; i < SIZE + 2; i++) {
+    permutation[SIZE + i] = permutation[i]!
+    gradientX[SIZE + i] = gradientX[i]!
+    gradientY[SIZE + i] = gradientY[i]!
+  }
+
+  const dot = (gradient: number, x: number, y: number): number =>
+    gradientX[gradient]! * x + gradientY[gradient]! * y
+
+  return (x, y) => {
+    const cellX = Math.floor(x)
+    const cellY = Math.floor(y)
+
+    const dx0 = x - cellX
+    const dy0 = y - cellY
+    const dx1 = dx0 - 1
+    const dy1 = dy0 - 1
+
+    const bx0 = cellX & MASK
+    const by0 = cellY & MASK
+    const bx1 = (bx0 + 1) & MASK
+    const by1 = (by0 + 1) & MASK
+
+    const i = permutation[bx0]!
+    const j = permutation[bx1]!
+
+    const g00 = permutation[i + by0]!
+    const g10 = permutation[j + by0]!
+    const g01 = permutation[i + by1]!
+    const g11 = permutation[j + by1]!
+
+    const sx = sCurve(dx0)
+    const sy = sCurve(dy0)
+
+    const top = lerp(sx, dot(g00, dx0, dy0), dot(g10, dx1, dy0))
+    const bottom = lerp(sx, dot(g01, dx0, dy1), dot(g11, dx1, dy1))
+
+    return lerp(sy, top, bottom) * NORMALISE
+  }
+}
+
+/**
+ * Perlin's original ease, 3t² - 2t³: an S from (0,0) to (1,1) whose first
+ * derivative is zero at both ends, which is what hides the lattice.
+ *
+ * His 1997 revision uses 6t⁵ - 15t⁴ + 10t³ instead, whose *second* derivative
+ * also vanishes at the ends and so survives being differentiated for normal
+ * maps. The field here is only ever read as an angle, never differentiated, so
+ * the cheaper original is the honest choice as well as the historical one.
+ */
+function sCurve(t: number): number {
+  return t * t * (3 - 2 * t)
+}
+
+function lerp(t: number, a: number, b: number): number {
+  return a + t * (b - a)
+}

package/src/plenty.ts

@@ -0,0 +1,65 @@
+/**
+ * How much of everything a day grew.
+ *
+ * Every count in this scene is worked out from the size of the box: so many
+ * plants per thousand pixels, so many fish per so much area. That is right, and
+ * it has one consequence nobody wanted. The box does not change, so neither
+ * does the sea. A desktop reseeded at midnight puts a different bed in a
+ * different place and grows exactly as much of it as yesterday did, and the
+ * thing a reader actually notices about a week of water is not where the kelp
+ * is, it is whether there is much of it.
+ *
+ * So the day picks a number and everything counted is counted through it. Two
+ * days apart are a thin sand flat and a bed you cannot see the floor through,
+ * and neither one is a bug.
+ *
+ * ## Why it is not evenly spread
+ *
+ * A range applied flat makes the ends as common as the middle, and then the
+ * spectacular day comes round often enough to stop being spectacular. Weighted
+ * the way it is here, most water is ordinary or a little under, a lush week is
+ * something you notice, and the bed you cannot see the floor through is
+ * something you wait for. Rare is the whole point of the top of the range.
+ *
+ * ## What it does not decide
+ *
+ * How much a renderer can afford. Each one caps what it asks for, and the caps
+ * are different: the desktop's bed is tessellated on the processor every frame
+ * and the native one uploads it once and bends it on the card, so the second
+ * can hold ten thousand plants where the first cannot hold one. This number is
+ * the day's appetite, not anybody's budget.
+ */
+
+import { makeRandom } from "./perlin.ts"
+
+/** The leanest day, as a share of an ordinary one. */
+const LEAN = 0.55
+
+/** How far above that the richest day reaches. */
+const RANGE = 1.75
+
+/**
+ * How the range is leaned on.
+ *
+ * Above one, and the low end is where most days land. It was picked against a
+ * decade of seeds, for a middle day that grows about what this scene grew
+ * before there was a number at all, and a top of the range you wait weeks for.
+ */
+const BIAS = 2.0
+
+/**
+ * A multiplier for anything counted, given the day's seed.
+ *
+ * `at` separates one kind of count from another where a caller wants them
+ * loose: the same seed and the same `at` always give the same number, so it can
+ * be asked for again at a refit without the sea changing under the reader.
+ */
+export function thriving(seed: number, at = 0): number {
+  const random = makeRandom((seed ^ 0x5eed) + at * 0x9e37)
+  // Two draws thrown away first: `makeRandom` is a small integer generator and
+  // its opening number tracks its seed closely, which for seeds a day apart is
+  // a week of water sliding steadily from lean to lush.
+  random()
+  random()
+  return LEAN + RANGE * random() ** BIAS
+}