ugly-game 0.1.0

package/dist/moat.d.ts

@@ -0,0 +1,64 @@
+/** The only thing the harness needs from a game: a deterministic sim it can clone, hash, and step. */
+export interface MoatSim<S, I> {
+    clone(s: S): S;
+    hash(s: S): string;
+    step(s: S, input: I): void;
+}
+/** Run a sim over an input stream and record the per-step content hash (index 0 = the initial state). */
+export declare function runTrace<S, I>(sim: MoatSim<S, I>, init: S, inputs: I[]): string[];
+export interface Equivalence {
+    inSync: boolean;
+    firstDivergentStep: number;
+    steps: number;
+}
+/** Compare a reference trace to a candidate trace; report the first divergent step (or in-sync). */
+export declare function equivalence(reference: string[], candidate: string[]): Equivalence;
+/** The oracle check: a reference runner and a candidate runner (which may use DIFFERENT code paths —
+ *  brute vs culled, full-load vs streamed, perfect-knowledge vs predicted) must agree tick-for-tick. */
+export declare function oracleCheck(reference: () => string[], candidate: () => string[]): Equivalence;
+/** Re-run a sim to a given step and return the state there — for localizing WHICH field diverged (the
+ *  game supplies a `locate(refState, candState)`, e.g. the factory's "tile (9,7) content A=1 B=0"). */
+export declare function stateAt<S, I>(sim: MoatSim<S, I>, init: S, inputs: I[], step: number): S;
+export interface SweepResult<P, V extends string> {
+    results: {
+        perturbation: P;
+        verdict: V;
+        detail?: unknown;
+    }[];
+    counts: Record<string, number>;
+    flagged: {
+        perturbation: P;
+        verdict: V;
+        detail?: unknown;
+    }[];
+    total: number;
+    clean: boolean;
+}
+/** Apply each perturbation, replay + classify (the game's `run`), and flag the ones `bad` says are bugs. */
+export declare function perturbationSweep<P, V extends string>(perturbations: P[], run: (p: P, i: number) => {
+    verdict: V;
+    detail?: unknown;
+}, bad: (v: V) => boolean): SweepResult<P, V>;
+export type MoatCheck = {
+    kind: 'equivalence';
+    name: string;
+    axis: string;
+    expectSync?: boolean;
+    run: () => Equivalence;
+} | {
+    kind: 'sweep';
+    name: string;
+    axis: string;
+    run: () => SweepResult<unknown, string>;
+};
+export interface MoatOutcome {
+    name: string;
+    axis: string;
+    kind: 'equivalence' | 'sweep';
+    pass: boolean;
+    summary: string;
+}
+/** Run one moat check and reduce it to a pass/fail + one-line summary — the same shape for every axis. */
+export declare function runMoat(check: MoatCheck): MoatOutcome;
+/** Run a whole suite of moats — the productized thesis: one harness, every axis. */
+export declare function runMoatSuite(checks: MoatCheck[]): MoatOutcome[];

package/dist/moat.js

@@ -0,0 +1,76 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// THE MOAT HARNESS — the AI-debuggable-game thesis, productized. Across the factory, FPS, physics, and
+// open-world slices we hand-wrote six bespoke "explorers/oracles" that each find real bugs in a
+// deterministic game. They are all one of TWO shapes, and this module is those two shapes made reusable,
+// so a NEW game inherits the moat instead of re-deriving it:
+//
+//   (1) ORACLE EQUIVALENCE — an OPTIMIZED run (culled / parallel / streamed / predicted+rolled-back /
+//       lockstep-client-B) must be BYTE-IDENTICAL to a GROUND-TRUTH run (brute / serial / fully-loaded /
+//       perfect-knowledge / lockstep-client-A). Compare per-step hashes; a divergence is localized to
+//       the exact step (and, with a game `locate`, the exact field). Covers factory culling/parallel/
+//       lockstep-desync, FPS rollback netcode, and open-world streaming invariance.
+//
+//   (2) PERTURBATION SWEEP — take a deterministic base world, apply each of many PLAUSIBLE perturbations
+//       (remove a belt, stand the player on each tile, aim at each target, spawn a bot at each cell,
+//       inject a level defect), DETERMINISTICALLY replay, and CLASSIFY the outcome; flag the bad ones.
+//       Covers the factory deadlock hunt, FPS reachability, AI spawn-reachability, KCC traversal, seams.
+//
+// Every verdict is a reproducible replay, not a screenshot dispute — because the sim under test is a
+// pure function of its inputs. This file has ZERO game knowledge; it only needs a deterministic sim.
+// ─────────────────────────────────────────────────────────────────────────────
+// ═══════════════════════ Pattern 1 · ORACLE EQUIVALENCE ═══════════════════════
+/** Run a sim over an input stream and record the per-step content hash (index 0 = the initial state). */
+export function runTrace(sim, init, inputs) {
+    const s = sim.clone(init);
+    const out = [sim.hash(s)];
+    for (const inp of inputs) {
+        sim.step(s, inp);
+        out.push(sim.hash(s));
+    }
+    return out;
+}
+/** Compare a reference trace to a candidate trace; report the first divergent step (or in-sync). */
+export function equivalence(reference, candidate) {
+    const n = Math.min(reference.length, candidate.length);
+    for (let i = 0; i < n; i++)
+        if (reference[i] !== candidate[i])
+            return { inSync: false, firstDivergentStep: i, steps: n };
+    return { inSync: reference.length === candidate.length, firstDivergentStep: -1, steps: n };
+}
+/** The oracle check: a reference runner and a candidate runner (which may use DIFFERENT code paths —
+ *  brute vs culled, full-load vs streamed, perfect-knowledge vs predicted) must agree tick-for-tick. */
+export function oracleCheck(reference, candidate) {
+    return equivalence(reference(), candidate());
+}
+/** Re-run a sim to a given step and return the state there — for localizing WHICH field diverged (the
+ *  game supplies a `locate(refState, candState)`, e.g. the factory's "tile (9,7) content A=1 B=0"). */
+export function stateAt(sim, init, inputs, step) {
+    const s = sim.clone(init);
+    for (let i = 0; i < step && i < inputs.length; i++)
+        sim.step(s, inputs[i]);
+    return s;
+}
+/** Apply each perturbation, replay + classify (the game's `run`), and flag the ones `bad` says are bugs. */
+export function perturbationSweep(perturbations, run, bad) {
+    const results = perturbations.map((p, i) => { const r = run(p, i); return { perturbation: p, verdict: r.verdict, detail: r.detail }; });
+    const counts = {};
+    for (const r of results)
+        counts[r.verdict] = (counts[r.verdict] ?? 0) + 1;
+    const flagged = results.filter((r) => bad(r.verdict));
+    return { results, counts, flagged, total: results.length, clean: flagged.length === 0 };
+}
+/** Run one moat check and reduce it to a pass/fail + one-line summary — the same shape for every axis. */
+export function runMoat(check) {
+    if (check.kind === 'equivalence') {
+        const e = check.run();
+        const expectSync = check.expectSync ?? true;
+        const pass = e.inSync === expectSync;
+        const summary = e.inSync ? `byte-identical to the oracle over ${e.steps} steps` : `diverges from the oracle @ step ${e.firstDivergentStep}`;
+        return { name: check.name, axis: check.axis, kind: 'equivalence', pass, summary };
+    }
+    const s = check.run();
+    const counts = Object.entries(s.counts).map(([k, v]) => `${v} ${k}`).join(', ');
+    return { name: check.name, axis: check.axis, kind: 'sweep', pass: s.clean, summary: s.clean ? `all ${s.total} clean (${counts})` : `${s.flagged.length}/${s.total} flagged (${counts})` };
+}
+/** Run a whole suite of moats — the productized thesis: one harness, every axis. */
+export function runMoatSuite(checks) { return checks.map(runMoat); }

package/dist/noise.d.ts

@@ -0,0 +1,35 @@
+/** Deterministic 0..1 at an integer lattice point (hashed, engine-portable). */
+export declare function hashLattice(seed: number, ix: number, iz: number): number;
+/** One octave of bilinear value-noise over a lattice of period F, normalized to [0,1]. */
+export declare function octave01(seed: number, x: number, z: number, F: number): number;
+/** One octave of bilinear value-noise, amplitude amp (matches world.ts's original `octave`). */
+export declare function octave(seed: number, x: number, z: number, F: number, amp: number): number;
+export interface FbmCfg {
+    octaves: number;
+    F: number;
+    amp: number;
+    lacunarity?: number;
+    gain?: number;
+    seedStep?: number;
+}
+/** Fractal Brownian motion: sum of octaves at increasing frequency (×lacunarity) and decreasing
+ *  amplitude (×gain). Output ∈ [0, Σ amp_i]. Each octave uses a distinct derived seed. */
+export declare function fbm2(seed: number, x: number, z: number, cfg: FbmCfg): number;
+/** Ridged noise — sharp crests where the underlying octave is mid-valued. Output ∈ [0, amp]. */
+export declare function ridged2(seed: number, x: number, z: number, F: number, amp: number): number;
+/** Billow noise — puffy lobes (dunes/clouds); complement of ridged. Output ∈ [0, amp]. */
+export declare function billow2(seed: number, x: number, z: number, F: number, amp: number): number;
+/** Domain warp: displace the sample point by two decorrelated octaves. Per-axis displacement ∈
+ *  [-warpAmp, warpAmp], so a downstream field's slope grows by at most warpAmp/warpF (bounded). */
+export declare function domainWarp2(seed: number, x: number, z: number, warpF: number, warpAmp: number): [number, number];
+export interface Worley {
+    f1: number;
+    f2: number;
+    cellId: number;
+}
+/** Worley/cellular noise: distance to nearest (f1) and 2nd-nearest (f2) feature point, plus a stable
+ *  id of the nearest cell. f2−f1 is a natural crack/edge field (rivers, region borders). */
+export declare function worley2(seed: number, x: number, z: number, F: number): Worley;
+/** Voronoi region label ∈ [0, regions): which of N regions the nearest feature cell maps to.
+ *  Piecewise-constant → gives biome regions with organic (jittered) borders. */
+export declare function voronoiRegion(seed: number, x: number, z: number, F: number, regions: number): number;

package/dist/noise.js

@@ -0,0 +1,91 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// NOISE — the deterministic terrain PLATFORM primitives (generic, no world/biome assumptions).
+// Every function is a pure function of (seed, coords) using ONLY IEEE-exact ops (+ - * / sqrt via
+// dmath) so terrain is bit-identical across engines — the moat. These compose (in terrainCompose.ts)
+// into rich per-biome terrain that stays WALKABLE: the load-bearing property here is that value-noise
+// has a BOUNDED per-unit slope (≤ amp/F), which is what lets composed height respect the step budget.
+// Building blocks: value-noise octaves, FBM, ridged/billow variants, domain warp, and worley/voronoi
+// cellular fields (used for biome regions and river/crack edges). See design/moonshot-open-world.md.
+// ─────────────────────────────────────────────────────────────────────────────
+import { dhypot } from './dmath';
+/** Deterministic 0..1 at an integer lattice point (hashed, engine-portable). */
+export function hashLattice(seed, ix, iz) {
+    let n = (Math.imul(ix, 73856093) ^ Math.imul(iz, 19349663) ^ Math.imul(seed, 83492791)) >>> 0;
+    n = Math.imul(n ^ (n >>> 13), 1274126177) >>> 0;
+    return (n % 100000) / 100000;
+}
+/** One octave of bilinear value-noise over a lattice of period F, normalized to [0,1]. */
+export function octave01(seed, x, z, F) {
+    const x0 = Math.floor(x / F), z0 = Math.floor(z / F), fx = x / F - x0, fz = z / F - z0;
+    const a = hashLattice(seed, x0, z0), b = hashLattice(seed, x0 + 1, z0), c = hashLattice(seed, x0, z0 + 1), d = hashLattice(seed, x0 + 1, z0 + 1);
+    const ab = a + (b - a) * fx, cd = c + (d - c) * fx;
+    return ab + (cd - ab) * fz;
+}
+/** One octave of bilinear value-noise, amplitude amp (matches world.ts's original `octave`). */
+export function octave(seed, x, z, F, amp) {
+    return octave01(seed, x, z, F) * amp;
+}
+/** Fractal Brownian motion: sum of octaves at increasing frequency (×lacunarity) and decreasing
+ *  amplitude (×gain). Output ∈ [0, Σ amp_i]. Each octave uses a distinct derived seed. */
+export function fbm2(seed, x, z, cfg) {
+    const lac = cfg.lacunarity ?? 2, gain = cfg.gain ?? 0.5, step = cfg.seedStep ?? 1013;
+    let sum = 0, F = cfg.F, amp = cfg.amp, s = seed;
+    for (let i = 0; i < cfg.octaves; i++) {
+        sum += octave01(s, x, z, F) * amp;
+        F /= lac;
+        amp *= gain;
+        s = (s * 6364136223 + step) | 0;
+    }
+    return sum;
+}
+/** Ridged noise — sharp crests where the underlying octave is mid-valued. Output ∈ [0, amp]. */
+export function ridged2(seed, x, z, F, amp) {
+    return (1 - Math.abs(2 * octave01(seed, x, z, F) - 1)) * amp;
+}
+/** Billow noise — puffy lobes (dunes/clouds); complement of ridged. Output ∈ [0, amp]. */
+export function billow2(seed, x, z, F, amp) {
+    return Math.abs(2 * octave01(seed, x, z, F) - 1) * amp;
+}
+/** Domain warp: displace the sample point by two decorrelated octaves. Per-axis displacement ∈
+ *  [-warpAmp, warpAmp], so a downstream field's slope grows by at most warpAmp/warpF (bounded). */
+export function domainWarp2(seed, x, z, warpF, warpAmp) {
+    const dx = (2 * octave01(seed ^ 0x1b56, x, z, warpF) - 1) * warpAmp;
+    const dz = (2 * octave01(seed ^ 0x7f2a, x, z, warpF) - 1) * warpAmp;
+    return [x + dx, z + dz];
+}
+/** Nearest & second-nearest jittered feature cell to (x,z) at period F. Shared by worley2 + regions. */
+function nearest(seed, x, z, F) {
+    const cx = Math.floor(x / F), cz = Math.floor(z / F);
+    let f1 = Infinity, f2 = Infinity, ncx = cx, ncz = cz;
+    for (let i = -1; i <= 1; i++)
+        for (let j = -1; j <= 1; j++) {
+            const gcx = cx + i, gcz = cz + j;
+            const fxp = (gcx + hashLattice(seed ^ 0x2c1b, gcx, gcz)) * F; // jittered feature point
+            const fzp = (gcz + hashLattice(seed ^ 0x51af, gcx, gcz)) * F;
+            const d = dhypot(x - fxp, z - fzp);
+            if (d < f1) {
+                f2 = f1;
+                f1 = d;
+                ncx = gcx;
+                ncz = gcz;
+            }
+            else if (d < f2) {
+                f2 = d;
+            }
+        }
+    return { ncx, ncz, f1, f2 };
+}
+/** Worley/cellular noise: distance to nearest (f1) and 2nd-nearest (f2) feature point, plus a stable
+ *  id of the nearest cell. f2−f1 is a natural crack/edge field (rivers, region borders). */
+export function worley2(seed, x, z, F) {
+    const n = nearest(seed, x, z, F);
+    const cellId = (hashLattice(seed ^ 0x9e37, n.ncx, n.ncz) * 1e6) | 0;
+    return { f1: n.f1, f2: n.f2, cellId };
+}
+/** Voronoi region label ∈ [0, regions): which of N regions the nearest feature cell maps to.
+ *  Piecewise-constant → gives biome regions with organic (jittered) borders. */
+export function voronoiRegion(seed, x, z, F, regions) {
+    const n = nearest(seed, x, z, F);
+    const h = (Math.imul(n.ncx | 0, 374761393) ^ Math.imul(n.ncz | 0, 668265263) ^ Math.imul(seed, 2246822519)) >>> 0;
+    return h % regions;
+}

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "ugly-game",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist"],
+  "scripts": { "build": "tsc -p tsconfig.json", "prepublishOnly": "tsc -p tsconfig.json" },
+  "peerDependencies": { "react": ">=18" },
+  "devDependencies": { "typescript": "^5.6.0", "@types/react": "^19.0.0", "@webgpu/types": "^0.1.40" }
+}