@netforge/engine 0.0.0-stage → 0.1.0

package/dist/game/adapter.js

@@ -0,0 +1,341 @@
+/**
+ * The engine-sim SimAdapter: the netcode's seam (net/sim-adapter.ts) over
+ * @netforge/engine-sim, used identically by the room server
+ * (authority, with a GameRunner) and the browser (prediction of its own
+ * character only).
+ *
+ * Wire schema: players carry their whole state at full precision (1/1024 m)
+ * so prediction replays exactly; enemies, gems and projectiles carry only
+ * x/z at 1/16 m plus type, health and flags, which keeps a crowd of 2,000
+ * at a few bits per moving entity.
+ */
+import { addPlayer, applyBeamHit, applyState, arenaHitboxes, arenaSpawn, beamShot, captureState, createWorld, destroyWorld, grantUpgrade, removePlayer, revivePlayer, setCosmetic, setMetaBonus, step, EntityKind, KEEPER_MASK, KEEPER_SHIFT, } from "@netforge/engine-sim";
+import { GameRunner } from "./runner.js";
+import { metaBonus, profileSpec, unpackMeta } from "./profile.js";
+/** Field indices of the engine wire schema. */
+export const F = {
+    px: 0,
+    py: 1,
+    pz: 2,
+    vx: 3,
+    vy: 4,
+    vz: 5,
+    yaw: 6,
+    health: 7,
+    flags: 8,
+    cooldown: 9,
+    buttons: 10,
+    timers: 11,
+    type: 12,
+    level: 13,
+    xp: 14,
+    weapons: 15,
+    wcd: 16,
+    stats: 17,
+    choices: 18,
+    bleed: 19,
+    revive: 20,
+    iframes: 21,
+    dash: 22,
+    ex: 23,
+    ez: 24,
+    /** Players: rerolls used | reroll counter << 4 | keeper << 12 | revive buff ticks << 16 (prediction draws the same cards, moves at the buffed speed). */
+    value: 25,
+};
+/** Units per metre of the crowd position fields (ex, ez): 1/16 m (6 cm) is below what a crowd shows on screen. */
+export const CROWD_UNITS = 16;
+/** Units per metre of player positions (px, py, pz): engine-sim's own fixed point. */
+export const PLAYER_UNITS = 1024;
+const playerFields = [
+    F.px, F.py, F.pz, F.vx, F.vy, F.vz, F.yaw, F.health, F.flags, F.cooldown, F.buttons, F.timers,
+    F.type, F.level, F.xp, F.weapons, F.wcd, F.stats, F.choices, F.bleed, F.revive, F.iframes, F.dash, F.value,
+];
+export const engineSchema = {
+    fields: [
+        { name: 'px', kind: 'int', bits: 19, deltaBits: 12 },
+        { name: 'py', kind: 'int', bits: 15, deltaBits: 10 },
+        { name: 'pz', kind: 'int', bits: 19, deltaBits: 12 },
+        { name: 'vx', kind: 'int', bits: 17, deltaBits: 10 },
+        { name: 'vy', kind: 'int', bits: 17, deltaBits: 10 },
+        { name: 'vz', kind: 'int', bits: 17, deltaBits: 10 },
+        { name: 'yaw', kind: 'angle16', deltaBits: 10 },
+        { name: 'health', kind: 'uint', bits: 20, interp: 'step', deltaBits: 8 },
+        { name: 'flags', kind: 'uint', bits: 8, interp: 'step' },
+        { name: 'cooldown', kind: 'uint', bits: 16, interp: 'step', deltaBits: 6 },
+        { name: 'buttons', kind: 'uint', bits: 16, interp: 'step' },
+        { name: 'timers', kind: 'uint', bits: 16, interp: 'step' },
+        { name: 'type', kind: 'uint', bits: 8, interp: 'step' },
+        { name: 'level', kind: 'uint', bits: 16, interp: 'step', deltaBits: 4 },
+        { name: 'xp', kind: 'uint', bits: 24, interp: 'step', deltaBits: 8 },
+        { name: 'weapons', kind: 'uint', bits: 32, interp: 'step' },
+        { name: 'wcd', kind: 'uint', bits: 32, interp: 'step' },
+        { name: 'stats', kind: 'uint', bits: 32, interp: 'step' },
+        { name: 'choices', kind: 'uint', bits: 32, interp: 'step' },
+        { name: 'bleed', kind: 'uint', bits: 16, interp: 'step', deltaBits: 6 },
+        { name: 'revive', kind: 'uint', bits: 16, interp: 'step', deltaBits: 6 },
+        { name: 'iframes', kind: 'uint', bits: 16, interp: 'step', deltaBits: 6 },
+        { name: 'dash', kind: 'uint', bits: 24, interp: 'step' },
+        { name: 'ex', kind: 'int', bits: 13, deltaBits: 5 },
+        { name: 'ez', kind: 'int', bits: 13, deltaBits: 5 },
+        { name: 'value', kind: 'uint', bits: 28, interp: 'step' },
+    ],
+    xField: F.px,
+    yField: F.pz,
+    unitsPerWorld: PLAYER_UNITS,
+    kindFields: {
+        [EntityKind.Player]: playerFields,
+        // level: the telegraph word (engine-sim Telegraph), 0 except while an attack winds up.
+        [EntityKind.Enemy]: [F.health, F.flags, F.type, F.level, F.ex, F.ez],
+        // flags: Hostile (an enemy's shot) and hazards; level: a hazard's telegraph.
+        [EntityKind.Projectile]: [F.type, F.flags, F.level, F.ex, F.ez],
+        [EntityKind.Pickup]: [F.type, F.ex, F.ez],
+    },
+};
+const TAU = Math.PI * 2;
+const YAW_UNITS = 65536;
+const idleInput = { seq: 0, tick: 0, moveX: 0, moveZ: 0, yaw: 0, buttons: 0 };
+/** The engine InputCommand on the wire: moves as int8, yaw as u16 turn, buttons u16 (48 bits). */
+const inputCodec = {
+    idle: idleInput,
+    write(w, i) {
+        w.writeSigned(axis(i.moveX), 8);
+        w.writeSigned(axis(i.moveZ), 8);
+        w.writeBits(Number.isFinite(i.yaw) ? Math.round((((i.yaw % TAU) + TAU) % TAU) / TAU * YAW_UNITS) & 0xffff : 0, 16);
+        w.writeBits(i.buttons & 0xffff, 16);
+    },
+    read(r) {
+        const moveX = r.readSigned(8) / 127;
+        const moveZ = r.readSigned(8) / 127;
+        const yaw = (r.readBits(16) / YAW_UNITS) * TAU;
+        const buttons = r.readBits(16);
+        return { seq: 0, tick: 0, moveX, moveZ, yaw, buttons };
+    },
+};
+function axis(v) {
+    if (!Number.isFinite(v))
+        return 0;
+    return Math.round(Math.max(-1, Math.min(1, v)) * 127);
+}
+/** engine-sim entity → netcode values in schema order. */
+function toValues(e) {
+    const v = new Array(26).fill(0);
+    v[F.px] = e.px;
+    v[F.pz] = e.pz;
+    v[F.type] = e.type;
+    v[F.health] = e.health;
+    v[F.flags] = e.flags;
+    v[F.ex] = Math.round((e.px * CROWD_UNITS) / PLAYER_UNITS);
+    v[F.ez] = Math.round((e.pz * CROWD_UNITS) / PLAYER_UNITS);
+    v[F.level] = e.level;
+    // Enemies: the crit counter (timers bits 8..11) so clients can mark crit numbers.
+    if (e.kind === EntityKind.Enemy)
+        v[F.timers] = (e.timers >>> 8) & 0xf;
+    if (e.kind !== EntityKind.Player)
+        return v;
+    v[F.py] = e.py;
+    v[F.vx] = e.vx;
+    v[F.vy] = e.vy;
+    v[F.vz] = e.vz;
+    v[F.yaw] = (e.yaw / YAW_UNITS) * TAU;
+    v[F.cooldown] = e.cooldown;
+    v[F.buttons] = e.buttons;
+    v[F.timers] = e.timers;
+    v[F.level] = e.level;
+    v[F.xp] = e.xp;
+    v[F.weapons] = e.weapons;
+    v[F.wcd] = e.wcd;
+    v[F.stats] = e.stats;
+    v[F.choices] = e.choices;
+    v[F.bleed] = e.bleed;
+    v[F.revive] = e.revive;
+    v[F.iframes] = e.iframes;
+    v[F.dash] = e.dash;
+    v[F.value] = e.value & 0xfffffff;
+    return v;
+}
+/** Netcode values → an engine-sim entity (players exact; crowd positions at 1/16 m). */
+function fromValues(s) {
+    const v = s.values;
+    const n = (i) => Math.round(v[i] ?? 0);
+    const player = s.kind === EntityKind.Player;
+    return {
+        netId: s.id,
+        kind: s.kind,
+        owner: s.owner,
+        px: player ? n(F.px) : (n(F.ex) * PLAYER_UNITS) / CROWD_UNITS,
+        py: n(F.py),
+        pz: player ? n(F.pz) : (n(F.ez) * PLAYER_UNITS) / CROWD_UNITS,
+        vx: n(F.vx),
+        vy: n(F.vy),
+        vz: n(F.vz),
+        yaw: Math.round(((((v[F.yaw] ?? 0) % TAU) + TAU) % TAU) / TAU * YAW_UNITS) % YAW_UNITS,
+        health: n(F.health),
+        flags: n(F.flags),
+        ack: 0,
+        cooldown: n(F.cooldown),
+        buttons: n(F.buttons),
+        timers: player ? n(F.timers) : s.kind === EntityKind.Enemy ? (n(F.timers) & 0xf) << 8 : 0,
+        type: n(F.type),
+        value: player ? n(F.value) : 0,
+        level: n(F.level),
+        xp: n(F.xp),
+        weapons: n(F.weapons) >>> 0,
+        wcd: n(F.wcd) >>> 0,
+        stats: n(F.stats),
+        choices: n(F.choices) >>> 0,
+        bleed: n(F.bleed),
+        revive: n(F.revive),
+        iframes: n(F.iframes),
+        dash: n(F.dash),
+    };
+}
+/**
+ * Build the SimAdapter. One instance serves every room of a template; each
+ * room gets its own world from `createWorld`. `maxInputsPerTick: 1`:
+ * engine-sim steps exactly one command per player per tick.
+ */
+export function engineSimAdapter(opts) {
+    const game = opts.game;
+    const tickHz = game?.tickRate ?? opts.arena?.tickRate ?? 30;
+    const baseConfig = game ? game.sim : { ...opts.arena, tickRate: tickHz };
+    const arena = game?.mode === 'arena';
+    const spec = game ? profileSpec(game.manifest) : null;
+    /** Upgrades some gear SKU brings into a staked run (the room issues these commands; the room never takes them from a client). */
+    const gearUpgrades = new Set([...(game?.manifest.skus.values() ?? [])].flatMap((s) => (s.grants && "gear" in s.grants ? [s.grants.gear] : [])));
+    return {
+        name: opts.name,
+        version: opts.version,
+        tickHz,
+        schema: engineSchema,
+        input: inputCodec,
+        maxInputsPerTick: 1,
+        createWorld(seed, role) {
+            // The client predicts only its own character: no spawner, no runner.
+            // Arena: the client has no authority (no projectiles, hits or respawns
+            // of its own); the server resolves human beams with lag compensation.
+            const content = baseConfig.content;
+            const arenaCfg = arena && content ? { ...content, arena: { ...content.arena, authority: role === 'server', externalHitscan: role === 'server' } } : content;
+            // A prediction world holds only its own character: it takes "solo" from the server's flag.
+            const clientContent = arenaCfg ? { ...arenaCfg, coop: { ...arenaCfg.coop, soloFromFlag: true } } : arenaCfg;
+            const cfg = role === 'client'
+                ? { ...baseConfig, seed, enemies: { ...baseConfig.enemies, target: 0 }, ...(clientContent ? { content: clientContent } : {}) }
+                : { ...baseConfig, seed, ...(arenaCfg ? { content: arenaCfg } : {}) };
+            const sim = createWorld(cfg);
+            const runner = role === 'server' && game ? new GameRunner(game, sim, opts.runner) : null;
+            return { sim, role, runner, shots: new Map() };
+        },
+        addPlayer(w, player) {
+            const [sx, sy, sz] = w.sim.config.arena.spawn;
+            if (arena) {
+                const [x, z] = arenaSpawn(w.sim, player);
+                return addPlayer(w.sim, player, [x, sy, z]);
+            }
+            return addPlayer(w.sim, player, [sx + ((player - 1) % 8) * 1.5 - 5, sy, sz]);
+        },
+        removePlayer(w, player) {
+            removePlayer(w.sim, player);
+        },
+        step(w, inputsByPlayer) {
+            const inputs = new Map();
+            for (const [p, list] of inputsByPlayer) {
+                const cmd = list[0];
+                if (cmd)
+                    inputs.set(p, cmd);
+            }
+            w.runner?.beforeStep(inputs);
+            w.shots.clear();
+            const res = step(w.sim, inputs);
+            const out = [];
+            if (w.runner) {
+                const r = w.runner.afterStep(res.events);
+                for (const a of r.awards)
+                    out.push({ type: 'earn', player: a.player, rule: a.rule, units: a.units });
+                for (const p of w.runner.takeProgress())
+                    out.push({ type: 'progress', player: p.player, kind: p.kind, id: p.id });
+                if (r.reset)
+                    out.push({ type: 'run.reset' });
+            }
+            else if (w.role === 'server') {
+                for (const e of res.events)
+                    if (e.type === 'enemy.killed' && e.by > 0)
+                        out.push({ type: 'earn', player: e.by, rule: 'kill', units: 1 });
+            }
+            return out;
+        },
+        snapshot(w) {
+            return captureState(w.sim).entities.map((e) => ({ id: e.netId, kind: e.kind, owner: e.owner, values: toValues(e) }));
+        },
+        applySnapshot(w, entities) {
+            applyState(w.sim, { ...captureState(w.sim), entities: entities.map(fromValues) });
+        },
+        info(w) {
+            return w.runner?.info() ?? null;
+        },
+        restrictInput(input, rights) {
+            const allowed = rights.keepers;
+            if (!allowed)
+                return input;
+            const pick = ((input.buttons & KEEPER_MASK) >>> KEEPER_SHIFT) - 1;
+            if (pick < 0 || allowed.includes(pick))
+                return input;
+            // A locked keeper: play the first open one instead (the room's profile check).
+            const open = allowed[0];
+            const rest = input.buttons & ~KEEPER_MASK;
+            return { ...input, buttons: (open === undefined ? rest : rest | (((open + 1) & 0xf) << KEEPER_SHIFT)) >>> 0 };
+        },
+        startRun(w, player) {
+            w.runner?.startRun(player);
+        },
+        command(w, player, cmd) {
+            if (cmd.name === 'revive')
+                return revivePlayer(w.sim, player);
+            // Owned meta upgrades (issued by the room from the profile, never by a client): capped again here.
+            if (cmd.name === 'meta') {
+                if (!spec || spec.meta.size === 0 || !spec.economy.metaUpgrades)
+                    return false;
+                setMetaBonus(w.sim, player, metaBonus(spec, unpackMeta(spec, cmd.value ?? 0)));
+                return true;
+            }
+            if (cmd.name === 'cosmetic') {
+                setCosmetic(w.sim, player, cmd.value ?? 0);
+                return true;
+            }
+            // A store upgrade: a SKU named after a declared upgrade grants one level of it for this run.
+            const up = game ? game.upgradeIds.indexOf(cmd.name) : -1;
+            if (game && up >= 0 && game.manifest.skus.has(cmd.name))
+                return grantUpgrade(w.sim, player, up);
+            // Gear (issued by the room from the profile at a staked run's start, never by a client): one level of its upgrade.
+            if (game && up >= 0 && gearUpgrades.has(cmd.name))
+                return grantUpgrade(w.sim, player, up);
+            return false;
+        },
+        // Lag compensation: arena beams from human players.
+        ...(arena
+            ? {
+                hitscans(w, player, input) {
+                    const shot = beamShot(w.sim, player, input);
+                    if (!shot)
+                        return null;
+                    w.shots.set(player, shot);
+                    return { shooter: player, ox: shot.x, oy: shot.z, dx: shot.dx, dy: shot.dz, range: shot.range };
+                },
+                hitboxes(w) {
+                    return arenaHitboxes(w.sim).map((h) => ({ entity: h.netId, owner: h.owner, x: h.x, y: h.z, r: h.r }));
+                },
+                applyHit(w, shooter, target) {
+                    const shot = w.shots.get(shooter);
+                    if (shot)
+                        applyBeamHit(w.sim, shot, target.entity);
+                    return [];
+                },
+            }
+            : {}),
+        disposeWorld(w) {
+            destroyWorld(w.sim);
+        },
+    };
+}
+/** Free a world's physics memory (rooms call this on dispose). */
+export function disposeEngineWorld(w) {
+    destroyWorld(w.sim);
+}

package/dist/game/arena-bot.d.ts

@@ -0,0 +1,66 @@
+import type { InputCommand } from "@netforge/engine-sim";
+/** One opponent as an arena bot sees it. */
+export interface ArenaBotOpponent {
+    readonly id: number;
+    readonly x: number;
+    readonly z: number;
+    /** How sharply the bot plays against this opponent (overrides the view's skill): seat bots go easy on a newcomer. */
+    readonly skill?: number;
+    /** Other bots are already on this one: pick it only when nobody else is around. */
+    readonly crowded?: boolean;
+}
+export interface ArenaBotWeapon {
+    readonly kind: string;
+    readonly range: number;
+    readonly count: number;
+}
+/** What an arena bot knows this tick (server side: the present). */
+export interface ArenaBotView {
+    readonly id: number;
+    readonly x: number;
+    readonly z: number;
+    readonly health: number;
+    readonly maxHealth: number;
+    readonly up: boolean;
+    /** The selected loadout slot (0..3). */
+    readonly slot: number;
+    /** The loadout by slot. */
+    readonly loadout: readonly ArenaBotWeapon[];
+    /** Living opponents. */
+    readonly opponents: readonly ArenaBotOpponent[];
+    readonly pickups: readonly {
+        readonly x: number;
+        readonly z: number;
+    }[];
+    readonly pillars: readonly {
+        readonly x: number;
+        readonly z: number;
+        readonly radius: number;
+    }[];
+    /** Arena half extent, m. */
+    readonly half: number;
+    /** Varies how bots strafe and miss between worlds (the world seed); default 0. */
+    readonly seed?: number;
+    /** 1 plays sharp; lower misses more, reacts later and fires in shorter bursts. Default 1. */
+    readonly skill?: number;
+}
+/** A bot's memory between ticks (the caller keeps one per bot). */
+export interface ArenaBotMemory {
+    target: number;
+    since: number;
+    aimError: number;
+    lastHealth: number;
+    /** Tick the current target came into clear sight (-1: not in sight). The bot reacts after a delay. */
+    sightSince?: number;
+}
+export declare function arenaBotMemory(): ArenaBotMemory;
+/** Does the segment from (x0, z0) to (x1, z1) pass through a pillar? */
+export declare function sightBlocked(x0: number, z0: number, x1: number, z1: number, pillars: ArenaBotView["pillars"]): boolean;
+/**
+ * One tick of an arena bot: pick the nearest opponent it can see (sticky
+ * for a while), keep a weapon-appropriate distance while strafing, go for a
+ * heal cell when hurt, switch to the right weapon for the range, and fire
+ * when the shot is clear. Aim carries a per-bot error, so bots are beatable.
+ * `tickRate` scales its timers.
+ */
+export declare function arenaBotInput(v: ArenaBotView, mem: ArenaBotMemory, tick: number, tickRate?: number): InputCommand;

package/dist/game/arena-bot.js

@@ -0,0 +1,188 @@
+/**
+ * Arena bots: they fill empty seats in arena rooms (server side, through
+ * the GameRunner) and play the headless playtests. A bot is a pure function
+ * of what it sees, its small memory and the tick, so a room's run replays
+ * exactly (run verification) and bots never draw from the sim's PRNG.
+ */
+import { Button } from "@netforge/engine-sim";
+export function arenaBotMemory() {
+    return { target: 0, since: 0, aimError: 0, lastHealth: 0, sightSince: -1 };
+}
+/** A fixed integer hash to 0..1. */
+function h01(a, b) {
+    let h = Math.imul(a ^ 0x9e3779b9, 0x85ebca6b) ^ Math.imul(b + 0x6d2b79f5, 0xc2b2ae35);
+    h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+    h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+/** Does the segment from (x0, z0) to (x1, z1) pass through a pillar? */
+export function sightBlocked(x0, z0, x1, z1, pillars) {
+    const dx = x1 - x0;
+    const dz = z1 - z0;
+    const len2 = dx * dx + dz * dz;
+    if (len2 < 1e-9)
+        return false;
+    for (const p of pillars) {
+        const t = Math.max(0, Math.min(1, ((p.x - x0) * dx + (p.z - z0) * dz) / len2));
+        const cx = x0 + dx * t - p.x;
+        const cz = z0 + dz * t - p.z;
+        if (cx * cx + cz * cz < (p.radius + 0.15) ** 2)
+            return true;
+    }
+    return false;
+}
+/**
+ * One tick of an arena bot: pick the nearest opponent it can see (sticky
+ * for a while), keep a weapon-appropriate distance while strafing, go for a
+ * heal cell when hurt, switch to the right weapon for the range, and fire
+ * when the shot is clear. Aim carries a per-bot error, so bots are beatable.
+ * `tickRate` scales its timers.
+ */
+export function arenaBotInput(v, mem, tick, tickRate = 30) {
+    const sec = (s) => Math.max(1, Math.round(s * tickRate));
+    const salt = Math.imul((v.seed ?? 0) >>> 0, 0x9e3779b1) >>> 16;
+    const idle = { seq: 0, tick, moveX: 0, moveZ: 0, yaw: 0, buttons: 0 };
+    if (!v.up) {
+        mem.target = 0;
+        mem.lastHealth = v.maxHealth;
+        return idle;
+    }
+    const seen = (o) => !sightBlocked(v.x, v.z, o.x, o.z, v.pillars);
+    // Target: keep the current one for up to 6 s while it lives and stays in sight, else the nearest visible (or nearest).
+    let target = v.opponents.find((o) => o.id === mem.target);
+    if (!target || tick - mem.since > sec(6) || (!seen(target) && tick - mem.since > sec(1.5))) {
+        let best;
+        let bestScore = Infinity;
+        for (const o of v.opponents) {
+            const score = Math.hypot(o.x - v.x, o.z - v.z) + (seen(o) ? 0 : 25) + (o.crowded ? 18 : 0);
+            if (score < bestScore) {
+                bestScore = score;
+                best = o;
+            }
+        }
+        if (best && best.id !== mem.target) {
+            mem.target = best.id;
+            mem.since = tick;
+            mem.sightSince = -1;
+        }
+        else if (best)
+            mem.since = tick;
+        target = best;
+    }
+    let mx = 0;
+    let mz = 0;
+    let yaw = 0;
+    let buttons = 0;
+    let skill = Math.max(0.05, Math.min(1, v.skill ?? 1));
+    /** Fraction of full speed: a loose bot strafes slowly in a fight, so it can be hit. */
+    let pace = 1;
+    if (target) {
+        const dx = target.x - v.x;
+        const dz = target.z - v.z;
+        const dist = Math.hypot(dx, dz) || 1e-6;
+        const clear = seen(target);
+        // Skill against this target: aim, reaction and bursts all scale with it.
+        skill = Math.max(0.05, Math.min(1, target.skill ?? skill));
+        if (!clear)
+            mem.sightSince = -1;
+        else if ((mem.sightSince ?? -1) < 0)
+            mem.sightSince = tick;
+        // The weapon for the range: the spread gun up close, the beam far away, the rifle between.
+        let want = v.slot;
+        let wantScore = -Infinity;
+        v.loadout.forEach((w, s) => {
+            let score;
+            if (w.kind === "beam")
+                score = dist > 12 ? 3 : 0;
+            else if (w.kind === "nova")
+                score = dist < w.range * 0.9 ? 4 : -2;
+            else if (w.count > 1)
+                score = dist < 7 ? 3 : -1;
+            else
+                score = 2;
+            if (dist > w.range)
+                score -= 5;
+            if (score > wantScore) {
+                wantScore = score;
+                want = s;
+            }
+        });
+        if (want !== v.slot && want <= 2 && tick % 4 === 0)
+            buttons |= Button.Choice1 << want;
+        const weapon = v.loadout[v.slot];
+        const range = weapon?.range ?? 12;
+        // Keep distance (60% of the weapon's reach, 4 to 14 m) and strafe; flip direction every few seconds.
+        // A loose bot fights closer, where it is easier to hit.
+        const keep = Math.max(4, Math.min(14, range * 0.6)) * (0.55 + 0.45 * skill);
+        const radial = Math.max(-1, Math.min(1, (dist - keep) / 4));
+        const flip = h01(v.id ^ salt, Math.floor((tick + v.id * 37) / sec(3.5))) < 0.5 ? 1 : -1;
+        const ux = dx / dist;
+        const uz = dz / dist;
+        mx += ux * radial - uz * flip * 0.85;
+        mz += uz * radial + ux * flip * 0.85;
+        if (!clear) {
+            mx -= uz * flip;
+            mz += ux * flip;
+        }
+        else
+            pace = 0.4 + 0.6 * skill;
+        // Aim with a per-bot error that drifts every third of a second; a loose bot misses by a lot more.
+        const sloppy = 1 + (1 - skill) * (1 + 2.4 * (1 - skill));
+        if (tick % sec(0.33) === 0)
+            mem.aimError = (h01((v.id * 3 + 1) ^ salt, tick) - 0.5) * (0.06 + 0.16 * h01(v.id ^ salt, 7)) * sloppy;
+        yaw = Math.atan2(-dx, -dz) + mem.aimError;
+        // React: hold fire for a moment after the target comes into sight (0.2 s sharp, 0.8 s loose).
+        const reacted = tick - (mem.sightSince ?? tick) >= sec(0.2 + 0.6 * (1 - skill));
+        // Bursts: a loose bot pauses between them (sharp bots fire without a break).
+        const cycle = sec(0.9 + 1.4 * (1 - skill));
+        const burst = (tick + v.id * 29) % cycle < sec(0.9);
+        if (clear && reacted && burst && dist <= range * 0.95)
+            buttons |= Button.Fire;
+    }
+    else {
+        // Nobody to fight: drift around the middle.
+        const a = (tick / sec(8) + v.id) % (Math.PI * 2);
+        mx = Math.cos(a) * 6 - v.x;
+        mz = Math.sin(a) * 6 - v.z;
+    }
+    // Hurt: go for the nearest heal cell within 20 m.
+    if (v.health < v.maxHealth * 0.45) {
+        let cell = null;
+        for (const p of v.pickups) {
+            const d = Math.hypot(p.x - v.x, p.z - v.z);
+            if (d < 20 && (!cell || d < cell.d))
+                cell = { x: p.x, z: p.z, d };
+        }
+        if (cell) {
+            mx = ((cell.x - v.x) / Math.max(0.5, cell.d)) * 2 + mx * 0.2;
+            mz = ((cell.z - v.z) / Math.max(0.5, cell.d)) * 2 + mz * 0.2;
+        }
+    }
+    // Keep off pillars and walls.
+    for (const p of v.pillars) {
+        const ox = v.x - p.x;
+        const oz = v.z - p.z;
+        const d = Math.hypot(ox, oz);
+        const reach = p.radius + 2;
+        if (d < reach && d > 1e-6) {
+            mx += (ox / d) * (reach - d);
+            mz += (oz / d) * (reach - d);
+        }
+    }
+    const edge = v.half - 3;
+    if (v.x > edge)
+        mx -= (v.x - edge) * 0.8;
+    if (v.x < -edge)
+        mx -= (v.x + edge) * 0.8;
+    if (v.z > edge)
+        mz -= (v.z - edge) * 0.8;
+    if (v.z < -edge)
+        mz -= (v.z + edge) * 0.8;
+    // Dodge: dash when hit hard, and now and then (a loose bot rarely thinks to).
+    if ((skill >= 0.4 && mem.lastHealth - v.health >= 25) || (skill >= 0.5 && (tick + v.id * 13) % sec(5.8) === 0))
+        buttons |= Button.Sprint;
+    mem.lastHealth = v.health;
+    const len = Math.hypot(mx, mz) || 1;
+    // Input frame (yaw 0): moveX is +x, moveZ is -z.
+    return { seq: 0, tick, moveX: (mx / len) * pace, moveZ: (-mz / len) * pace, yaw, buttons };
+}

package/dist/game/bot.d.ts

@@ -0,0 +1,95 @@
+import type { InputCommand } from "@netforge/engine-sim";
+export interface BotView {
+    readonly x: number;
+    readonly z: number;
+    /** The player's packed `choices` field (offers pending when non-zero). */
+    readonly choices: number;
+    /** Arena half extent, m. */
+    readonly half: number;
+}
+/** One tick of input. `enemies` are nearby enemy positions [x, z]; `id` varies the bot's path. */
+export declare function botInput(me: BotView, enemies: Iterable<readonly [number, number]>, tick: number, id: number): InputCommand;
+/** A danger the bot can see coming: a telegraphed area that lands soon (circle, or a lane from (x, z) along (dx, dz)). */
+export interface BotDanger {
+    readonly x: number;
+    readonly z: number;
+    /** Circle radius, or lane half width, m. */
+    readonly r: number;
+    /** Lane: unit direction and length; omit for a circle. */
+    readonly dx?: number;
+    readonly dz?: number;
+    readonly len?: number;
+}
+/** What a human-like bot sees this tick (the caller passes the present; the bot reacts to it late). */
+export interface HumanBotView {
+    readonly x: number;
+    readonly z: number;
+    readonly up: boolean;
+    /** The player's packed `choices` field. */
+    readonly choices: number;
+    /** The player's packed weapon slots (to pick upgrades greedily). */
+    readonly weapons: number;
+    /** Arena half extent, m. */
+    readonly half: number;
+    /** Living enemies on (or just off) screen. */
+    readonly enemies: readonly (readonly [number, number])[];
+    /** Gems and pickups on screen. */
+    readonly gems: readonly (readonly [number, number])[];
+    readonly pillars: readonly {
+        readonly x: number;
+        readonly z: number;
+        readonly radius: number;
+    }[];
+    /** Telegraphed attacks about to land. */
+    readonly dangers?: readonly BotDanger[];
+    /** How far the player's weapons reach, m (the bot orbits about there; default 5). */
+    readonly reach?: number;
+    /** Bosses on screen: players focus them, circling at their weapons' reach. */
+    readonly bosses?: readonly (readonly [number, number])[];
+    /** Teammates who are down: players go and stand next to them to revive. */
+    readonly downed?: readonly (readonly [number, number])[];
+}
+export interface HumanBotOptions {
+    /** Ticks between seeing something and acting on it (6 ticks = 200 ms at 30 Hz). */
+    readonly reactionTicks?: number;
+    /** "random": any offer; "greedy": level owned weapons, then new weapons, then passives. */
+    readonly picks?: "random" | "greedy";
+    /** Number of weapons the game declares (offer indices below it are weapons). */
+    readonly weaponCount?: number;
+    /** Weapon indices that are evolutions (greedy picks always take them). */
+    readonly evolved?: readonly number[];
+    /** Evolution pairings: [weapon index, offer index of the passive it needs]. Greedy picks value a passive an owned weapon needs. */
+    readonly pairs?: readonly (readonly [number, number])[];
+    /** Varies the bot's path and picks. */
+    readonly seed?: number;
+}
+/**
+ * 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 declare class HumanBot {
+    private readonly delay;
+    private readonly picks;
+    private readonly nWeapons;
+    private readonly evolved;
+    private readonly pairs;
+    private s;
+    private readonly seen;
+    private arc;
+    private heading;
+    private downSince;
+    private cardSince;
+    private cardWait;
+    private lastDash;
+    private lastTurn;
+    constructor(opts?: HumanBotOptions);
+    private rnd;
+    /** One tick of input from what the player sees now. */
+    input(now: HumanBotView, tick: number): InputCommand;
+    private choose;
+}