@netforge/engine 0.0.0-stage → 0.2.0

package/dist/game/bot.js

@@ -0,0 +1,285 @@
+/**
+ * A playtest bot that plays a survivor-style game reasonably: circles the
+ * arena, steers away from nearby enemies, dashes out of crowds and takes an
+ * upgrade whenever one is offered. Used by the headless harness and by the
+ * networked load bots (which see only their area of interest).
+ */
+import { Button } from "@netforge/engine-sim";
+/** One tick of input. `enemies` are nearby enemy positions [x, z]; `id` varies the bot's path. */
+export function botInput(me, enemies, tick, id) {
+    const ring = Math.min(me.half * 0.5, 22) + (id % 4) * 3;
+    const r = Math.hypot(me.x, me.z) || 1;
+    const dir = id % 2 === 0 ? 1 : -1;
+    // Tangent around the centre plus a pull back onto the ring.
+    let dx = (-me.z / r) * dir + (me.x / r) * ((ring - r) / ring) * 2;
+    let dz = (me.x / r) * dir + (me.z / r) * ((ring - r) / ring) * 2;
+    let crowd = 0;
+    for (const [ex, ez] of enemies) {
+        const ox = me.x - ex;
+        const oz = me.z - ez;
+        const d2 = ox * ox + oz * oz;
+        if (d2 > 36 || d2 < 1e-6)
+            continue;
+        const w = 3 / d2;
+        dx += ox * w;
+        dz += oz * w;
+        if (d2 < 4)
+            crowd++;
+    }
+    const len = Math.hypot(dx, dz) || 1;
+    let buttons = 0;
+    if ((me.choices & 0xff) !== 0 && tick % 2 === 0)
+        buttons |= Button.Choice1 << ((id + (tick >> 1)) % 3);
+    if (crowd >= 6 && tick % 8 === 0)
+        buttons |= Button.Sprint;
+    // yaw 0: moveX is +x, moveZ is -z.
+    return { seq: 0, tick, moveX: dx / len, moveZ: -dz / len, yaw: 0, buttons };
+}
+/**
+ * A playtest bot that plays like a person, for fun metrics
+ * (GAME-DESIGN.md "measure fun with bots"): it reacts about 200 ms late,
+ * kites in wide arcs instead of circling the centre, walks over gems when
+ * it is safe, dashes when something is about to touch it or a telegraph is
+ * about to land under it, and takes a second or so to read each card.
+ * Template-agnostic: it needs positions only. Deterministic for a given
+ * input sequence (its own xorshift, never the sim's PRNG).
+ */
+export class HumanBot {
+    delay;
+    picks;
+    nWeapons;
+    evolved;
+    pairs;
+    s;
+    seen = [];
+    arc;
+    heading = 0;
+    downSince = -1;
+    cardSince = -1;
+    cardWait = 30;
+    lastDash = -999;
+    lastTurn = 0;
+    constructor(opts = {}) {
+        this.delay = Math.max(0, Math.floor(opts.reactionTicks ?? 6));
+        this.picks = opts.picks ?? "random";
+        this.nWeapons = opts.weaponCount ?? 0;
+        this.evolved = new Set(opts.evolved ?? []);
+        this.pairs = opts.pairs ?? [];
+        this.s = ((opts.seed ?? 1) * 2654435761) >>> 0 || 1;
+        this.arc = this.rnd() < 0.5 ? 1 : -1;
+        this.heading = this.rnd() * Math.PI * 2;
+    }
+    rnd() {
+        let s = this.s;
+        s ^= s << 13;
+        s ^= s >>> 17;
+        s ^= s << 5;
+        this.s = s >>> 0;
+        return this.s / 4294967296;
+    }
+    /** One tick of input from what the player sees now. */
+    input(now, tick) {
+        this.seen.push(now);
+        if (this.seen.length > this.delay + 1)
+            this.seen.shift();
+        // Perception is late; the bot's own position is not (you know where you are).
+        const late = this.seen[0] ?? now;
+        let buttons = 0;
+        const pending = now.choices >>> 24;
+        if (pending > 0 && now.up) {
+            if (this.cardSince < 0) {
+                this.cardSince = tick;
+                this.cardWait = 24 + Math.floor(this.rnd() * 12);
+            }
+            if (tick - this.cardSince >= this.cardWait) {
+                const k = this.choose(now.choices, now.weapons);
+                if (k >= 0)
+                    buttons |= Button.Choice1 << k;
+                this.cardSince = -1;
+            }
+        }
+        else
+            this.cardSince = -1;
+        if (!now.up) {
+            // Down: read the prompt for a beat, then press dash once (a free self-revive, if one is left).
+            if (this.downSince < 0)
+                this.downSince = tick;
+            const press = tick - this.downSince === 45 ? Button.Sprint : 0;
+            return { seq: 0, tick, moveX: 0, moveZ: 0, yaw: 0, buttons: press };
+        }
+        this.downSince = -1;
+        // Threat: nearby enemies push, nearer ones much harder.
+        let tx = 0;
+        let tz = 0;
+        let nearest = Infinity;
+        let close = 0;
+        for (const e of late.enemies) {
+            const ox = now.x - e[0];
+            const oz = now.z - e[1];
+            const d2 = ox * ox + oz * oz;
+            if (d2 > 100 || d2 < 1e-6)
+                continue;
+            const d = Math.sqrt(d2);
+            nearest = Math.min(nearest, d);
+            if (d < 4)
+                close++;
+            const w = 1 / (d2 * d);
+            tx += ox * w;
+            tz += oz * w;
+        }
+        const threat = Math.hypot(tx, tz);
+        let dx = Math.cos(this.heading);
+        let dz = Math.sin(this.heading);
+        let drift = false;
+        const boss = late.bosses?.[0];
+        let downedMate;
+        let dd = 25 * 25;
+        for (const d of now.downed ?? []) {
+            const d2 = (d[0] - now.x) ** 2 + (d[1] - now.z) ** 2;
+            if (d2 < dd) {
+                dd = d2;
+                downedMate = d;
+            }
+        }
+        if (downedMate && close < 6) {
+            // A teammate is down nearby: go and stand by them (the revive needs 3 s within 2.5 m).
+            dx = downedMate[0] - now.x;
+            dz = downedMate[1] - now.z;
+            if (dx * dx + dz * dz < 1.5) {
+                dx = -dz * 0.2;
+                dz = dx * 0.2;
+            }
+        }
+        else if (boss && close < 5) {
+            // A boss on screen: circle it at reach, so the weapons keep landing.
+            const bx = now.x - boss[0];
+            const bz = now.z - boss[1];
+            const bd = Math.hypot(bx, bz) || 1;
+            const reach = (now.reach ?? 5) * 0.85 + 1.5;
+            const radial = bd < reach * 0.8 ? 1 : bd > reach * 1.1 ? -1 : 0;
+            dx = (-bz / bd) * this.arc + (bx / bd) * radial;
+            dz = (bx / bd) * this.arc + (bz / bd) * radial;
+        }
+        else if (threat > 0.004) {
+            // Kite: circle the threat at about the weapons' reach. Too close: step out; too far: lean in.
+            const ax = tx / threat;
+            const az = tz / threat;
+            const reach = now.reach ?? 5;
+            const radial = close >= 5 ? 1.6 : nearest < reach * 0.55 ? 1 : nearest > reach * 0.95 ? -0.5 : 0.25;
+            dx = -az * this.arc + ax * radial;
+            dz = ax * this.arc + az * radial;
+        }
+        else {
+            // Calm: go for the nearest gem, else wander on a slowly turning heading.
+            let best = 81;
+            for (const g of late.gems) {
+                const gx = g[0] - now.x;
+                const gz = g[1] - now.z;
+                const d2 = gx * gx + gz * gz;
+                if (d2 < best) {
+                    best = d2;
+                    dx = gx;
+                    dz = gz;
+                }
+            }
+            if (best === 81) {
+                // No gem near: close in on the nearest enemy on screen to about 6 m (players farm XP).
+                let near = Infinity;
+                for (const e of late.enemies) {
+                    const ex = e[0] - now.x;
+                    const ez = e[1] - now.z;
+                    const d2 = ex * ex + ez * ez;
+                    if (d2 < near) {
+                        near = d2;
+                        dx = ex;
+                        dz = ez;
+                    }
+                }
+                if (near !== Infinity && near > 36)
+                    best = 0;
+            }
+            if (best === 81) {
+                // Nothing on screen: drift at half speed (players wait for the action, they do not sprint away from it).
+                if (tick - this.lastTurn > 60) {
+                    this.lastTurn = tick;
+                    this.heading += (this.rnd() - 0.5) * 1.2;
+                }
+                dx = Math.cos(this.heading) * 0.5;
+                dz = Math.sin(this.heading) * 0.5;
+                drift = true;
+            }
+        }
+        // Walls: turn back toward the middle before running into one.
+        const lim = now.half - 10;
+        if (Math.abs(now.x) > lim)
+            dx += (-Math.sign(now.x) * (Math.abs(now.x) - lim)) / 3;
+        if (Math.abs(now.z) > lim)
+            dz += (-Math.sign(now.z) * (Math.abs(now.z) - lim)) / 3;
+        // Pillars: slide around them.
+        for (const p of now.pillars) {
+            const ox = now.x - p.x;
+            const oz = now.z - p.z;
+            const d = Math.hypot(ox, oz);
+            if (d < p.radius + 2 && d > 1e-6) {
+                dx += (ox / d) * 1.5;
+                dz += (oz / d) * 1.5;
+            }
+        }
+        // Telegraphs: step out of anything about to land under you, and dash if it is close.
+        let inDanger = false;
+        for (const g of late.dangers ?? []) {
+            const ox = now.x - g.x;
+            const oz = now.z - g.z;
+            if (g.dx !== undefined && g.dz !== undefined) {
+                const along = ox * g.dx + oz * g.dz;
+                const side = ox * -g.dz + oz * g.dx;
+                if (along > -1 && along < (g.len ?? 0) + 1 && Math.abs(side) < g.r + 0.8) {
+                    inDanger = true;
+                    const s = side >= 0 ? 1 : -1;
+                    dx += -g.dz * s * 4;
+                    dz += g.dx * s * 4;
+                }
+            }
+            else if (ox * ox + oz * oz < (g.r + 0.8) * (g.r + 0.8)) {
+                inDanger = true;
+                const d = Math.hypot(ox, oz) || 1;
+                dx += (ox / d) * 4;
+                dz += (oz / d) * 4;
+            }
+        }
+        if ((inDanger || nearest < 1.1 || close >= 5) && tick - this.lastDash > 40) {
+            buttons |= Button.Sprint;
+            this.lastDash = tick;
+        }
+        const len = Math.hypot(dx, dz) || 1;
+        this.heading = Math.atan2(dz, dx);
+        const speed = drift ? 0.5 : 1;
+        return { seq: 0, tick, moveX: (dx / len) * speed, moveZ: (-dz / len) * speed, yaw: 0, buttons };
+    }
+    choose(choices, weapons) {
+        const offers = [(choices & 0xff) - 1, ((choices >>> 8) & 0xff) - 1, ((choices >>> 16) & 0xff) - 1];
+        const valid = [];
+        offers.forEach((u, k) => {
+            if (u >= 0)
+                valid.push([u, k]);
+        });
+        if (valid.length === 0)
+            return -1;
+        if (this.picks === "random")
+            return valid[Math.floor(this.rnd() * valid.length)][1];
+        const owned = new Set();
+        for (let s = 0; s < 4; s++) {
+            const wi = ((weapons >>> (s * 8)) & 0x0f) - 1;
+            if (wi >= 0)
+                owned.add(wi);
+        }
+        // A build with a goal: evolutions first, then the passive an owned weapon needs, then owned weapons, new weapons, other passives.
+        const needed = new Set(this.pairs.filter(([wi]) => owned.has(wi)).map(([, u]) => u));
+        const score = (u) => (this.evolved.has(u) ? 5 : needed.has(u) ? 3.5 : u < this.nWeapons ? (owned.has(u) ? 3 : 2) : 1);
+        let best = valid[0];
+        for (const v of valid)
+            if (score(v[0]) > score(best[0]))
+                best = v;
+        return best[1];
+    }
+}

package/dist/game/compile.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Compile a game manifest (what the model declared through the API) into
+ * engine-sim content: enemy types, weapons, passives and progression. This
+ * is how prefabs and weapons stop being validated-only and start running in
+ * the sim.
+ */
+import type { SimConfig, WeaponLevelStats } from "@netforge/engine-sim";
+import type { GameManifest } from "../api/registry.js";
+import type { PrefabDef, WeaponDef as ApiWeaponDef } from "../api/schemas.js";
+import type { CompiledPlatformer } from "./platformer.js";
+import type { CompiledRacer } from "./racer.js";
+import type { CameraView } from "./view.js";
+/** Templates that run on the survivor machinery (co-op, auto-firing weapons, downs and revives, keepers). */
+export declare const COOP_TEMPLATES: ReadonlySet<string>;
+/**
+ * Survivor-machinery defaults every game gets unless it says otherwise
+ * (GAME-DESIGN.md): a generous magnet, half a second of hit i-frames, a
+ * solo pause on level-up cards and a shove plus a second of i-frames when
+ * co-op cards open.
+ */
+export declare const SURVIVOR_DEFAULTS: {
+    readonly magnet: 3.75;
+    readonly hitIframes: 0.5;
+    readonly choicePulseRadius: 2.5;
+    readonly choicePulseIframes: 1;
+    /** Co-op XP: half of each gem to teammates within 20 m. */
+    readonly share: {
+        readonly mode: "nearby";
+        readonly fraction: 0.5;
+        readonly radius: 20;
+    };
+    /** The reviver's buff: 5 s of x1.25 damage and x1.15 speed. */
+    readonly reviveBuff: {
+        readonly seconds: 5;
+        readonly damage: 1.25;
+        readonly speed: 1.15;
+    };
+    /** Going down is short: 10 s downed (crawling), one free get-up a run, then back in 5 s beside a teammate. */
+    readonly downed: {
+        readonly seconds: 10;
+        readonly crawl: 0.35;
+        readonly selfRevives: 1;
+        readonly respawn: 5;
+    };
+    /** Getting up shoves enemies within this radius, m. */
+    readonly risePulseRadius: 4;
+};
+export interface CompiledGame {
+    readonly manifest: GameManifest;
+    /** Pass to engine-sim's createWorld (add a seed). Identical on the server and the client. */
+    readonly sim: SimConfig;
+    /** Enemy prefab ids by engine type index. */
+    readonly enemyPrefabs: readonly string[];
+    /** Engine type index by enemy prefab id. */
+    readonly enemyType: ReadonlyMap<string, number>;
+    /** Pickup prefab ids by gem tier (0 small, 1 medium, 2 large); several tiers may share a prefab. */
+    readonly pickupPrefabs: readonly string[];
+    /** Special pickup prefab ids (heals, vacuums, bombs, chests): entity type PICKUP_SPECIAL + index. */
+    readonly specialPickups: readonly string[];
+    /** Weapon ids by engine weapon index, then upgrade ids: the order of level-up offer indices. */
+    readonly weaponIds: readonly string[];
+    readonly upgradeIds: readonly string[];
+    readonly tickRate: number;
+    /** "arena": the shooter machinery (loadouts, respawn, rounds, seat-filling bots); "platformer": the race-to-the-flag machinery (platformer.ts); else the survivor machinery. */
+    readonly mode: "survivor" | "arena" | "platformer" | "racer";
+    /** Platformer: the courses, feel and upgrade stats (null for other templates). */
+    readonly platformer?: CompiledPlatformer;
+    /** Racer: the circuits, handling and upgrade stats (null for other templates). */
+    readonly racer?: CompiledRacer;
+    /** Arena: weapon indices in loadout slots 1..4. */
+    readonly loadout: readonly number[];
+    /** Arena: seats bots fill up to (0: none). */
+    readonly bots: number;
+    /** Arena: round length and frag limit; null for survivor runs. */
+    readonly round: {
+        readonly seconds: number;
+        readonly frags: number | null;
+    } | null;
+    /** What a player sees: screen-edge distances by heading (the director spawns past them; the playtest counts inside them as on screen). */
+    readonly view: readonly number[];
+}
+/** Arena defaults: a 3 minute round, a 3 s respawn, 2 s spawn protection, heal cells last 20 s. */
+export declare const ARENA_DEFAULTS: {
+    readonly roundSeconds: 180;
+    readonly respawnSeconds: 3;
+    readonly spawnProtectSeconds: 2;
+    readonly pickupSeconds: 20;
+    readonly pillarHeight: 2.4;
+};
+/** Every level's numbers: level 1 is the weapon's own, each declared level applies its changes to the one before. */
+export declare function levelTable(w: ApiWeaponDef, tickRate: number): WeaponLevelStats[];
+/** "enemy" or "pickup": explicit, else a prefab something drops is a pickup. */
+export declare function prefabKind(m: GameManifest, id: string, p: PrefabDef): "enemy" | "pickup";
+export declare function compileGame(m: GameManifest, opts?: {
+    maxEntities?: number;
+    views?: readonly CameraView[];
+}): CompiledGame;