@netforge/engine 0.0.0-stage → 0.2.0

package/dist/api/dungeon.js

@@ -0,0 +1,216 @@
+/**
+ * dungeon(...): a procedural dungeon floor from a seed
+ * ("dungeon layouts can be generated from a seed on both sides").
+ *
+ * Rooms sit on a grid of cells, grown from the start room as a random
+ * tree, with a few extra doors that make loops. Neighbouring rooms are
+ * joined by straight corridors. The result is the `field` a dungeon game
+ * passes to game({ field }) (walls and floors as boxes, the start room at
+ * [0, 0] where players spawn) and the rooms with their depth from the
+ * start, so a system can wake encounters room by room.
+ *
+ * Pure and deterministic: the same spec gives the same dungeon on the room
+ * server, in the client and in the playtest, with nothing downloaded.
+ */
+import { z } from "zod";
+import { GameDefinitionError } from "./schemas.js";
+export const dungeonSchema = z
+    .object({
+    /** Any whole number: a different seed is a different dungeon. */
+    seed: z.number().int().min(0).max(0xffffffff),
+    /** Rooms on the floor, the start and the boss room included. */
+    rooms: z.number().int().min(3, "a dungeon has at least 3 rooms").max(20, "20 rooms is the cap (a run should end in about 10 minutes)"),
+    /** Grid cell size in metres: room spacing. Default 24. */
+    cell: z.number().int().min(16).max(32).default(24),
+    /** Room side in metres, [smallest, largest]. Default [12, 18]. Kept at least 4 m under the cell. */
+    size: z.tuple([z.number().int().min(8).max(28), z.number().int().min(8).max(28)]).default([12, 18]),
+    /** Corridor width in metres (even). Default 4. */
+    corridor: z.number().int().min(2).max(8).default(4),
+    /** Extra doors beyond the tree, for loops. Default 2. */
+    loops: z.number().int().min(0).max(8).default(2),
+})
+    .strict();
+/** mulberry32: a small seeded PRNG. */
+function prng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+const evenIn = (rnd, lo, hi) => {
+    const a = Math.ceil(lo / 2);
+    const b = Math.floor(hi / 2);
+    return 2 * (a + Math.floor(rnd() * (b - a + 1)));
+};
+/** Build a dungeon floor from a spec. Throws GameDefinitionError with readable lines on a bad spec. */
+export function dungeon(spec) {
+    const parsed = dungeonSchema.safeParse(spec);
+    if (!parsed.success)
+        throw new GameDefinitionError("dungeon(...)", parsed.error.issues.map((i) => `${i.path.join(".") || "spec"}: ${i.message}`));
+    const s = parsed.data;
+    const [lo, hi] = s.size[0] <= s.size[1] ? s.size : [s.size[1], s.size[0]];
+    if (hi > s.cell - 4)
+        throw new GameDefinitionError("dungeon(...)", [`size ${hi} m does not fit a ${s.cell} m cell with walls between rooms: keep size under cell - 4`]);
+    if (s.corridor > lo - 2)
+        throw new GameDefinitionError("dungeon(...)", [`a ${s.corridor} m corridor is wider than the smallest room's wall allows: keep corridor at most size[0] - 2`]);
+    const rnd = prng(s.seed);
+    // A square grid big enough to grow in; the start is its middle cell, so the floor stays near [0, 0].
+    const g = Math.max(3, Math.ceil(Math.sqrt(s.rooms)) + 2);
+    const mid = Math.floor(g / 2);
+    const key = (i, j) => j * g + i;
+    const cells = [[mid, mid]];
+    const index = new Map([[key(mid, mid), 0]]);
+    const links = [new Set()];
+    const DIRS = [
+        [1, 0],
+        [-1, 0],
+        [0, 1],
+        [0, -1],
+    ];
+    let guard = 0;
+    while (cells.length < s.rooms && guard++ < 10_000) {
+        // Grow from a random room, leaning toward the newest so the floor reaches out rather than balling up.
+        const from = rnd() < 0.5 ? cells.length - 1 : Math.floor(rnd() * cells.length);
+        const [ci, cj] = cells[from];
+        const [di, dj] = DIRS[Math.floor(rnd() * 4)];
+        const ni = ci + di;
+        const nj = cj + dj;
+        if (ni < 0 || nj < 0 || ni >= g || nj >= g || index.has(key(ni, nj)))
+            continue;
+        const id = cells.length;
+        cells.push([ni, nj]);
+        index.set(key(ni, nj), id);
+        links.push(new Set([from]));
+        links[from]?.add(id);
+    }
+    // Loops: a few extra doors between neighbours that are not joined yet.
+    for (let k = 0, tries = 0; k < s.loops && tries < 200; tries++) {
+        const a = Math.floor(rnd() * cells.length);
+        const [ai, aj] = cells[a];
+        const [di, dj] = DIRS[Math.floor(rnd() * 4)];
+        const b = index.get(key(ai + di, aj + dj));
+        if (b === undefined || links[a]?.has(b))
+            continue;
+        links[a]?.add(b);
+        links[b]?.add(a);
+        k++;
+    }
+    // Depth from the start (breadth first).
+    const depth = new Array(cells.length).fill(-1);
+    depth[0] = 0;
+    const queue = [0];
+    for (let h = 0; h < queue.length; h++) {
+        const a = queue[h];
+        for (const b of links[a] ?? []) {
+            if (depth[b] !== -1)
+                continue;
+            depth[b] = (depth[a] ?? 0) + 1;
+            queue.push(b);
+        }
+    }
+    // Rooms: centred in their cells (so corridors run straight), even sizes on whole metres.
+    const rooms = cells.map(([i, j], id) => {
+        const w = id === 0 ? hi : evenIn(rnd, lo, hi);
+        const d = id === 0 ? hi : evenIn(rnd, lo, hi);
+        return { id, x: (i - mid) * s.cell, z: (j - mid) * s.cell, hx: w / 2, hz: d / 2, depth: depth[id] ?? 0, links: [...(links[id] ?? [])].sort((a, b) => a - b) };
+    });
+    const floors = rooms.map((r) => [r.x, r.z, r.hx, r.hz]);
+    const half = s.corridor / 2;
+    for (const a of rooms) {
+        for (const bi of a.links) {
+            if (bi < a.id)
+                continue;
+            const b = rooms[bi];
+            if (a.z === b.z) {
+                const [l, r] = a.x < b.x ? [a, b] : [b, a];
+                const x0 = l.x + l.hx;
+                const x1 = r.x - r.hx;
+                floors.push([(x0 + x1) / 2, a.z, (x1 - x0) / 2 + 0.5, half]);
+            }
+            else {
+                const [l, r] = a.z < b.z ? [a, b] : [b, a];
+                const z0 = l.z + l.hz;
+                const z1 = r.z - r.hz;
+                floors.push([a.x, (z0 + z1) / 2, half, (z1 - z0) / 2 + 0.5]);
+            }
+        }
+    }
+    // Walls: every 1 m cell next to the floor that is not floor, merged into boxes.
+    let ext = 0;
+    for (const [x, z, hx, hz] of floors)
+        ext = Math.max(ext, Math.abs(x) + hx, Math.abs(z) + hz);
+    const n = Math.ceil(ext) + 2;
+    const size = 2 * n;
+    const floor = new Uint8Array(size * size);
+    for (const [x, z, hx, hz] of floors) {
+        for (let j = Math.floor(z - hz + n); j < Math.ceil(z + hz + n); j++) {
+            for (let i = Math.floor(x - hx + n); i < Math.ceil(x + hx + n); i++) {
+                if (i >= 0 && j >= 0 && i < size && j < size)
+                    floor[j * size + i] = 1;
+            }
+        }
+    }
+    const wall = new Uint8Array(size * size);
+    for (let j = 0; j < size; j++) {
+        for (let i = 0; i < size; i++) {
+            if (floor[j * size + i] === 1)
+                continue;
+            let near = false;
+            for (let dj = -1; dj <= 1 && !near; dj++) {
+                for (let di = -1; di <= 1; di++) {
+                    const a = i + di;
+                    const b = j + dj;
+                    if (a >= 0 && b >= 0 && a < size && b < size && floor[b * size + a] === 1) {
+                        near = true;
+                        break;
+                    }
+                }
+            }
+            if (near)
+                wall[j * size + i] = 1;
+        }
+    }
+    // Merge: maximal runs along x per row, then runs with the same ends stacked down the rows.
+    const walls = [];
+    let open = new Map();
+    for (let j = 0; j <= size; j++) {
+        const next = new Map();
+        for (let i = 0; j < size && i < size; i++) {
+            if (wall[j * size + i] !== 1)
+                continue;
+            let i1 = i;
+            while (i1 + 1 < size && wall[j * size + i1 + 1] === 1)
+                i1++;
+            const k = `${i}:${i1}`;
+            const prev = open.get(k);
+            next.set(k, prev ? [prev[0], prev[1], prev[2]] : [i, i1, j]);
+            if (prev)
+                open.delete(k);
+            i = i1;
+        }
+        for (const [i0, i1, j0] of open.values())
+            walls.push([(i0 + i1 + 1) / 2 - n, (j0 + j) / 2 - n, (i1 - i0 + 1) / 2, (j - j0) / 2]);
+        open = next;
+    }
+    const halfSize = Math.max(20, Math.min(120, n + 1));
+    let boss = rooms[0];
+    for (const r of rooms)
+        if (r.depth > boss.depth || (r.depth === boss.depth && r.id > boss.id))
+            boss = r;
+    return {
+        field: { halfSize, pillars: [], walls, floors },
+        rooms,
+        start: rooms[0],
+        boss,
+        roomAt(x, z) {
+            for (const r of rooms)
+                if (Math.abs(x - r.x) <= r.hx && Math.abs(z - r.z) <= r.hz)
+                    return r.id;
+            return -1;
+        },
+    };
+}

package/dist/api/harness.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Headless test harness: run a game on the server sim
+ * with bot players and report what happened.
+ *
+ * When a game module has been declared (game(), prefabs, weapons, systems,
+ * earn rules), it runs that game exactly as the room server does: compiled
+ * content in engine-sim, the systems on the GameRunner, earn rules counted
+ * per player. With no game declared it runs the week-2 engine-sim arena
+ * (the built-in chaser spawner) with scripted bots.
+ */
+export interface HarnessAssertion {
+    readonly name: string;
+    readonly check: (report: HarnessReport) => boolean;
+}
+export interface HarnessOptions {
+    readonly ticks: number;
+    readonly bots: number;
+    /** Arena: enemies the spawner keeps alive. Game: hold at least this many alive on top of the waves (stress). */
+    readonly enemies?: number;
+    readonly seed?: number;
+    readonly tickRate?: number;
+    readonly assert?: readonly HarnessAssertion[];
+    /**
+     * Who plays (survivor-style games): "basic" circles and never misses a
+     * beat (the default, a stress player); "human" reacts 200 ms late, kites
+     * in wide arcs, takes a second per card (the fun metrics' player).
+     */
+    readonly bot?: "basic" | "human";
+    /** Human bots' card picks: "random" (default) or "greedy". */
+    readonly picks?: "random" | "greedy";
+    /** With `enemies`: hold a mix of every non-boss enemy type (all behaviours on) instead of type 0. */
+    readonly enemyMix?: boolean;
+}
+/**
+ * How fun the opening and the run felt to the bots, measured (GAME-DESIGN.md).
+ * Horde games (survivor-like) are measured over the first run; arena games
+ * over every life. Fields that do not apply to the genre are null.
+ */
+export interface FunMetrics {
+    readonly genre: "horde" | "arena" | "race";
+    /** Seconds until an enemy first came within 3 m of a player (horde) or a player first took damage (arena). */
+    readonly firstThreatSeconds: number | null;
+    /** Seconds until the first reward: the first level-up (horde) or the first kill (arena). */
+    readonly firstRewardSeconds: number | null;
+    /** Horde: highest player level at 1:00, 3:00, 6:00 and 9:00 of the first run (null when the run ended first). */
+    readonly levelAt: {
+        readonly "60": number | null;
+        readonly "180": number | null;
+        readonly "360": number | null;
+        readonly "540": number | null;
+    };
+    /** Horde: times a player went down before 1:00. */
+    readonly deathsBeforeMinute: number | null;
+    /** Horde: the most enemies on one player's screen at 0:30. */
+    readonly onScreenAt30: number | null;
+    /** Horde: contact hits each player took in the first minute. */
+    readonly contactHitsFirstMinute: number | null;
+    /** Horde: share of downs after 3:00 that a telegraphed attack caused (null with no such downs). */
+    readonly telegraphedDeathShare: number | null;
+    /** Horde: share of enemy spawns that appeared on a player's screen (should be 0). */
+    readonly spawnsOnScreen: number | null;
+    /** Horde: how long the first run lasted (the whole playtest when it never ended), s. */
+    readonly survivalSeconds: number | null;
+    /** Arena: median seconds from a (re)spawn to the first damage taken (spawn camping when short). */
+    readonly spawnToDamageSeconds: number | null;
+    /** Arena: share of deaths within 3 s of spawning. */
+    readonly spawnDeathShare: number | null;
+    /** Arena: best player's kills over the mean (1 is even; above 3 one player stomps). */
+    readonly killSpread: number | null;
+    /** Arena: times the lead changed hands, per round. */
+    readonly leadChanges: number | null;
+    /** Horde: bosses killed in the first run, with seconds from spawn to kill. */
+    readonly bossKills: readonly {
+        readonly prefab: string;
+        readonly seconds: number;
+    }[];
+    /** Horde: what last hit each player that went down in the first run ("contact", "charge", "blast", ...). */
+    readonly downsBySource: Readonly<Record<string, number>>;
+    /** Horde: seconds until a player first took damage of any kind (null if never). */
+    readonly firstHitSeconds?: number | null;
+    /** Horde: lowest health any player was left on by a hit before 2:00 (null if nobody was hit). */
+    readonly lowestHealthBy120?: number | null;
+    /** Horde: seconds until the first elite and the first boss (mini or final) appeared. */
+    readonly firstEliteSeconds?: number | null;
+    readonly firstBossSeconds?: number | null;
+    /** Horde: share of player time in the first run spent downed or out (waiting, not playing). */
+    readonly downTimeShare?: number | null;
+    /** Race: median seconds from the start signal to a playtest player's first finish (null: nobody finished). */
+    readonly finishSeconds?: number | null;
+    /** Race: share of playtest player rounds that reached the finish. */
+    readonly finishRate?: number | null;
+    /** Race: falls (platformer) or wall hits (racer) per playtest player per round. */
+    readonly mishapsPerRound?: number | null;
+    /** Race: seconds until a playtest player first collected a coin. */
+    readonly firstCoinSeconds?: number | null;
+    /** Race: per course, whether the route planner (platformer) found a way to the finish, and its seconds. */
+    readonly routes?: readonly {
+        readonly course: number;
+        readonly found: boolean;
+        readonly seconds: number | null;
+    }[];
+}
+export interface HarnessReport {
+    readonly ticks: number;
+    readonly bots: number;
+    /** Arena: deaths. Game: times a player went down. */
+    readonly deaths: number;
+    readonly kills: number;
+    /** Game mode: highest wave reached (1 + waves cleared), 0 in the arena. */
+    readonly wave: number;
+    /** Game mode: runs that ended, by outcome. */
+    readonly runs: {
+        readonly won: number;
+        readonly lost: number;
+    };
+    /** Game mode: highest player level reached. */
+    readonly maxLevel: number;
+    /** Game mode: most enemies alive at once. */
+    readonly peakEnemies: number;
+    /** Arena: the most kills one player scored in a round (0 for survivor games). */
+    readonly topScore: number;
+    /** Arena: players (bots included) who scored at least one kill. */
+    readonly scorers: number;
+    /** Game mode: earn awards by rule id (units). */
+    readonly earned: Readonly<Record<string, number>>;
+    /** Mean wall-clock milliseconds per sim tick: the FPS-equivalent server cost. */
+    readonly msPerTick: number;
+    readonly p99MsPerTick: number;
+    readonly earnEmitted: number;
+    /** True when nothing changed (no kills, no damage, no movement) for 30 s of sim time. */
+    readonly softlock: boolean;
+    /** Fun metrics (game mode only). */
+    readonly fun?: FunMetrics;
+    /**
+     * Board genres (tower defense, idle, cards, collector): the genre's own
+     * playtest checks (a failing check fails the gate) and how far the bots
+     * got through its arc (0..1, the progression score).
+     */
+    readonly rules?: {
+        readonly template: string;
+        readonly checks: readonly {
+            readonly ok: boolean;
+            readonly line: string;
+        }[];
+        readonly progress: number;
+    };
+    readonly failed: readonly string[];
+}
+export declare function runHarness(opts: HarnessOptions): Promise<HarnessReport>;