@netforge/engine 0.0.0-stage → 0.1.0

package/dist/game/racer.js

@@ -0,0 +1,379 @@
+/**
+ * The racer template's machinery: compile a manifest's tracks into the
+ * engine-sim kart sim, drive it with the race runner (race.ts), seat bots
+ * that drive the racing line, a client autopilot, and the netcode
+ * SimAdapter.
+ */
+import { Button, BOT_PLAYER_BASE, KART_STATS, KartFlag, addKart, applyKart, captureKart, createKartWorld, grantKartStat, kartProgress, kartStep, lateralOffset, nearestSample, removeKart, resetKart, setKartTrack, setKartsFrozen, } from "@netforge/engine-sim";
+import { raceInputCodec } from "./platformer.js";
+import { RaceRunner } from "./race.js";
+/** Racer defaults: a 4 minute limit, 60 Hz, five seat bots. */
+export const RACER_DEFAULTS = { roundSeconds: 240, tickRate: 60, bots: 5 };
+/** Compile the racer parts of a manifest. Issues are agent-readable. */
+export function compileRacer(m, issues) {
+    const g = m.game;
+    if (!g.tracks || g.tracks.length === 0)
+        issues.push("a racer game sets tracks: [{ points, width, laps, ... }] (the circuits)");
+    if (m.weapons.size > 0)
+        issues.push("weapon(...) is not part of the racer template: boost pads, coins and drifts make the race");
+    if (m.director)
+        issues.push("director(...) is not part of the racer template");
+    if (g.arena || g.field || g.levels)
+        issues.push("arena, field and levels belong to other templates; a racer declares tracks");
+    if (g.players.loadout)
+        issues.push("players.loadout is for the arena template");
+    if (m.keepers.size > 0)
+        issues.push("keeper(...) is for the survivor template");
+    for (const [id, p] of m.prefabs)
+        if ((p.kind ?? "enemy") === "enemy" && !p.prop)
+            issues.push(`prefab "${id}" is an enemy; the racer template has no enemies`);
+    const upgradeStat = [];
+    const statSteps = KART_STATS.map(() => 0);
+    for (const [id, u] of m.upgrades) {
+        const i = KART_STATS.indexOf(u.stat);
+        if (i < 0) {
+            issues.push(`upgrade "${id}" raises ${u.stat}; racer upgrades raise one of: ${KART_STATS.join(", ")}`);
+            upgradeStat.push("speed");
+            continue;
+        }
+        if (u.stat === "speed" && u.step > 0.2)
+            issues.push(`upgrade "${id}": a speed step above 0.2 (+20% a level) breaks the races`);
+        statSteps[i] = u.step;
+        upgradeStat.push(u.stat);
+    }
+    const names = [];
+    const tracks = (g.tracks ?? []).map((t, ti) => {
+        names.push(t.name ?? `Track ${ti + 1}`);
+        const where = `tracks[${ti}]`;
+        // Neighbouring control points closer than the width fold the road over itself.
+        t.points.forEach((p, i) => {
+            const q = t.points[(i + 1) % t.points.length];
+            if (Math.hypot(q[0] - p[0], q[1] - p[1]) < 6)
+                issues.push(`${where}.points[${i}] is within 6 m of the next point: spread the control points out`);
+        });
+        let len = 0;
+        for (let i = 0; i < t.points.length; i++) {
+            const p = t.points[i];
+            const q = t.points[(i + 1) % t.points.length];
+            len += Math.hypot(q[0] - p[0], q[1] - p[1]);
+        }
+        if (len < 200)
+            issues.push(`${where} is ${Math.round(len)} m round; a lap needs at least 200 m`);
+        return { points: t.points, width: t.width, laps: t.laps, boosts: t.boosts, coins: t.coins, verge: t.verge };
+    });
+    const kt = g.kart ?? {};
+    const tuning = Object.fromEntries(Object.entries(kt).filter(([, v]) => v !== undefined));
+    return { tracks, names, tuning, statSteps, upgradeStat };
+}
+// ---------------------------------------------------------------- bots
+/**
+ * What a kart bot does: steer at a point on the racing line ahead (further
+ * at speed), lift off for tight bends, and drift through long ones at
+ * higher skill. `skill` 0..1 shades its top speed and its line.
+ */
+export function kartBotInput(w, k, clock, skill, lane = 0, mem) {
+    const idle = { seq: 0, tick: clock, moveX: 0, moveZ: 0, yaw: 0, buttons: 0 };
+    if ((k.flags & (KartFlag.Frozen | KartFlag.Finished)) !== 0)
+        return idle;
+    const t = w.track;
+    const speed = Math.hypot(k.vx, k.vz);
+    const ahead = Math.round((8 + speed * 0.55) / 2);
+    const i = (k.seg + ahead) % t.count;
+    const far = (k.seg + ahead * 2) % t.count;
+    const nx = -(t.tz[i] ?? 0);
+    const nz = t.tx[i] ?? 0;
+    // Pass a kart close ahead on our line: move over to the side it is not on.
+    const fx = Math.cos(k.yaw);
+    const fz = Math.sin(k.yaw);
+    let pass = 0;
+    for (const o of w.karts.values()) {
+        if (o === k)
+            continue;
+        const dx = o.x - k.x;
+        const dz = o.z - k.z;
+        const ahead = dx * fx + dz * fz;
+        const side = -dx * fz + dz * fx;
+        if (ahead > 0 && ahead < 10 && Math.abs(side) < 2.2)
+            pass = side >= 0 ? -1 : 1;
+    }
+    const off = Math.max(-0.8, Math.min(0.8, lane * 0.45 + pass * 0.55)) * t.half;
+    const tx = (t.x[i] ?? 0) + nx * off;
+    const tz = (t.z[i] ?? 0) + nz * off;
+    const want = Math.atan2(tz - k.z, tx - k.x);
+    let d = want - k.yaw;
+    while (d > Math.PI)
+        d -= Math.PI * 2;
+    while (d < -Math.PI)
+        d += Math.PI * 2;
+    const steer = Math.max(-1, Math.min(1, d * 2.2));
+    // How sharp the road bends ahead: the angle between here and further on.
+    const bend = Math.abs(Math.atan2((t.tx[i] ?? 0) * (t.tz[far] ?? 0) - (t.tz[i] ?? 0) * (t.tx[far] ?? 0), (t.tx[i] ?? 0) * (t.tx[far] ?? 0) + (t.tz[i] ?? 0) * (t.tz[far] ?? 0)));
+    const cap = w.tuning.topSpeed * (0.78 + 0.2 * skill);
+    let throttle = speed < cap ? 1 : 0;
+    if (bend > 0.9 && speed > cap * 0.7)
+        throttle = -0.3;
+    let buttons = 0;
+    const drifting = (k.flags & KartFlag.Drifting) !== 0;
+    // Drift into a long bend and hold it through (a held drift charges the mini-turbo); let go as the road straightens.
+    if (mem && skill > 0.55) {
+        if (!drifting && bend > 0.5 && bend < 1.1 && speed > 14 && Math.abs(steer) > 0.35)
+            mem.driftUntil = clock + Math.round((0.6 + skill * 0.3) * w.tickRate);
+        // Let go early when the drift swings the nose past the line (the heading error flips against the drift).
+        const dir = (k.flags & KartFlag.DriftRight) !== 0 ? 1 : -1;
+        const overturn = drifting && d * dir < -0.25;
+        if (!overturn && clock < mem.driftUntil)
+            buttons |= Button.Sprint;
+    }
+    // A stuck kart (a wall nose-in) backs off and turns.
+    if (speed < 2 && clock % 120 > 60)
+        return { ...idle, moveX: -steer, moveZ: -1 };
+    return { seq: 0, tick: clock, moveX: steer, moveZ: throttle, yaw: 0, buttons };
+}
+// ---------------------------------------------------------------- core
+export class KartCore {
+    compiled;
+    tickRate;
+    world;
+    nextSlot = 0;
+    memory = new Map();
+    constructor(compiled, tickRate, authority = true) {
+        this.compiled = compiled;
+        this.tickRate = tickRate;
+        this.world = createKartWorld({ tickRate, tracks: compiled.tracks, tuning: compiled.tuning, statSteps: compiled.statSteps, authority });
+    }
+    ids() {
+        return [...this.world.karts.keys()].sort((a, b) => a - b);
+    }
+    /** The lowest grid slot nobody holds. */
+    freeSlot() {
+        const used = new Set([...this.world.karts.values()].map((k) => k.slot));
+        let s = 0;
+        while (used.has(s))
+            s++;
+        return s;
+    }
+    add(id, bot, frozen) {
+        if (this.world.karts.has(id))
+            return;
+        addKart(this.world, id, { bot, frozen, slot: this.freeSlot() });
+        this.nextSlot++;
+    }
+    remove(id) {
+        removeKart(this.world, id);
+    }
+    reset(course, frozen) {
+        setKartTrack(this.world, course);
+        this.world.tick = 0;
+        // People take the front of the grid, seat bots fill in behind them.
+        const order = [...this.world.karts.values()].sort((a, b) => (a.id >= BOT_PLAYER_BASE ? 1 : 0) - (b.id >= BOT_PLAYER_BASE ? 1 : 0) || a.id - b.id);
+        order.forEach((k, slot) => {
+            k.slot = slot;
+            k.stats = 0;
+            resetKart(this.world, k, frozen);
+        });
+    }
+    setFrozen(frozen) {
+        setKartsFrozen(this.world, frozen);
+    }
+    finished(id) {
+        return ((this.world.karts.get(id)?.flags ?? 0) & KartFlag.Finished) !== 0;
+    }
+    progress(id) {
+        const k = this.world.karts.get(id);
+        return k ? Math.min(1, kartProgress(this.world, k) / this.world.track.def.laps) : 0;
+    }
+    position(id) {
+        const k = this.world.karts.get(id);
+        return k ? [k.x, 0, k.z] : [0, 0, 0];
+    }
+    step(inputs) {
+        const out = [];
+        for (const e of kartStep(this.world, inputs)) {
+            if (e.type === "coin")
+                out.push({ name: "coin.collected", player: e.kart });
+            else if (e.type === "lap")
+                out.push({ name: "lap.completed", player: e.kart });
+            else if (e.type === "finish")
+                out.push({ name: "player.finished", player: e.kart });
+            else if (e.type === "turbo")
+                out.push({ name: e.tier >= 3 ? "drift.ultra" : "drift.boosted", player: e.kart });
+            else if (e.type === "wall")
+                out.push({ name: "kart.bumped", player: e.kart });
+        }
+        return out;
+    }
+    botInput(id, clock, skill) {
+        const k = this.world.karts.get(id);
+        if (!k)
+            return { seq: 0, tick: clock, moveX: 0, moveZ: 0, yaw: 0, buttons: 0 };
+        const lane = ((id * 7) % 5) / 2 - 1;
+        let mem = this.memory.get(id);
+        if (!mem) {
+            mem = { driftUntil: 0 };
+            this.memory.set(id, mem);
+        }
+        return kartBotInput(this.world, k, clock, skill, lane * 0.6, mem);
+    }
+    grant(id, upgrade) {
+        const stat = this.compiled.upgradeStat[upgrade];
+        return stat ? grantKartStat(this.world, id, stat) : false;
+    }
+    setCosmetic(id, cosmetic) {
+        const k = this.world.karts.get(id);
+        if (k)
+            k.cosmetic = cosmetic & 0xff;
+    }
+}
+// ---------------------------------------------------------------- netcode
+/** Field indices of the racer wire schema. */
+export const KF = { x: 0, z: 1, yaw: 2, vx: 3, vz: 4, flags: 5, timers: 6, track: 7, coinsLo: 8, coinsHi: 9, finishTick: 10, stats: 11, cosmetic: 12, clock: 13 };
+export const kartSchema = {
+    fields: [
+        { name: "x", kind: "int", bits: 22, deltaBits: 12 },
+        { name: "z", kind: "int", bits: 22, deltaBits: 12 },
+        { name: "yaw", kind: "uint", bits: 16, interp: "step" },
+        { name: "vx", kind: "int", bits: 18, deltaBits: 12 },
+        { name: "vz", kind: "int", bits: 18, deltaBits: 12 },
+        { name: "flags", kind: "uint", bits: 8, interp: "step" },
+        { name: "timers", kind: "uint", bits: 25, interp: "step" },
+        { name: "track", kind: "uint", bits: 28, interp: "step" },
+        { name: "coinsLo", kind: "uint", bits: 31, interp: "step" },
+        { name: "coinsHi", kind: "uint", bits: 31, interp: "step" },
+        { name: "finishTick", kind: "uint", bits: 20, interp: "step" },
+        { name: "stats", kind: "uint", bits: 20, interp: "step" },
+        { name: "cosmetic", kind: "uint", bits: 16, interp: "step" },
+        { name: "clock", kind: "uint", bits: 20, interp: "step", deltaBits: 6 },
+    ],
+    xField: KF.x,
+    yField: KF.z,
+    unitsPerWorld: 1024,
+};
+function toValues(s) {
+    return [s.x, s.z, s.yaw, s.vx, s.vz, s.flags, s.timers, s.track, s.coinsLo, s.coinsHi, s.finishTick, s.stats, s.cosmetic, s.clock];
+}
+export function kartFromValues(e) {
+    const v = (i) => Math.round(e.values[i] ?? 0);
+    return {
+        id: e.id,
+        x: v(KF.x),
+        z: v(KF.z),
+        yaw: v(KF.yaw) & 0xffff,
+        vx: v(KF.vx),
+        vz: v(KF.vz),
+        flags: v(KF.flags),
+        timers: v(KF.timers) >>> 0,
+        track: v(KF.track) >>> 0,
+        coinsLo: v(KF.coinsLo) >>> 0,
+        coinsHi: v(KF.coinsHi) >>> 0,
+        finishTick: v(KF.finishTick),
+        stats: v(KF.stats) >>> 0,
+        cosmetic: v(KF.cosmetic),
+        clock: v(KF.clock),
+    };
+}
+/** The racer's SimAdapter: the room runs the race; a client predicts only its own kart (no bumps). */
+export function kartAdapter(o) {
+    const upgradeIds = [...o.manifest.upgrades.keys()];
+    const gear = new Set([...o.manifest.skus.values()].flatMap((s) => (s.grants && "gear" in s.grants ? [s.grants.gear] : [])));
+    return {
+        name: o.name,
+        version: o.version,
+        tickHz: o.tickRate,
+        schema: kartSchema,
+        input: raceInputCodec,
+        maxInputsPerTick: 1,
+        createWorld(seed, role) {
+            const core = new KartCore(o.compiled, o.tickRate, role === "server");
+            const runner = role === "server" ? new RaceRunner(o.manifest, core, { bots: o.bots, roundSeconds: o.roundSeconds, courses: o.compiled.tracks.length, seed, ...o.runner }) : null;
+            return { role, core, runner };
+        },
+        addPlayer(w, player) {
+            if (w.runner)
+                w.runner.joined(player);
+            else
+                w.core.add(player, false, false);
+            return player;
+        },
+        removePlayer(w, player) {
+            if (w.runner)
+                w.runner.left(player);
+            else
+                w.core.remove(player);
+        },
+        step(w, inputsByPlayer) {
+            const inputs = new Map();
+            for (const [p, list] of inputsByPlayer) {
+                const c = list[0];
+                if (c)
+                    inputs.set(p, c);
+            }
+            if (!w.runner) {
+                w.core.step(inputs);
+                return [];
+            }
+            w.runner.beforeStep(inputs);
+            const r = w.runner.afterStep(w.core.step(inputs));
+            const out = [];
+            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" });
+            return out;
+        },
+        snapshot(w) {
+            return w.core.ids().map((id) => ({ id, kind: 1, owner: id, values: toValues(captureKart(w.core.world, w.core.world.karts.get(id))) }));
+        },
+        applySnapshot(w, entities) {
+            for (const e of entities)
+                applyKart(w.core.world, kartFromValues(e));
+        },
+        info(w) {
+            return w.runner ? { ...w.runner.info(), level: o.compiled.names[w.runner.courseNow] ?? null, laps: w.core.world.track.def.laps } : null;
+        },
+        startRun(w, player) {
+            w.runner?.startRun(player);
+        },
+        command(w, player, cmd) {
+            if (cmd.name === "cosmetic") {
+                w.core.setCosmetic(player, cmd.value ?? 0);
+                return true;
+            }
+            const up = upgradeIds.indexOf(cmd.name);
+            if (up < 0)
+                return false;
+            if (!o.manifest.skus.has(cmd.name) && !gear.has(cmd.name))
+                return false;
+            const stat = o.compiled.upgradeStat[up];
+            const def = o.manifest.upgrades.get(cmd.name);
+            const k = w.core.world.karts.get(player);
+            if (!stat || !def || !k)
+                return false;
+            const lvl = (k.stats >>> (KART_STATS.indexOf(stat) * 4)) & 0xf;
+            if (lvl >= def.maxLevel)
+                return false;
+            return w.core.grant(player, up);
+        },
+        disposeWorld() { },
+    };
+}
+/** A client autopilot: the seat bot's driving on our newest predicted kart. */
+export function kartAutopilot(compiled, tickRate) {
+    const core = new KartCore(compiled, tickRate, false);
+    const mem = { driftUntil: 0 };
+    return (self, tick, skill = 1, others = []) => {
+        if (!self)
+            return { seq: 0, tick, moveX: 0, moveZ: 0, yaw: 0, buttons: 0 };
+        // The karts we can see, so we pass them instead of queueing behind.
+        for (const id of [...core.world.karts.keys()])
+            if (id !== self.id && !others.some((o) => o.id === id))
+                core.world.karts.delete(id);
+        for (const o of others)
+            if (o.id !== self.id)
+                applyKart(core.world, kartFromValues(o));
+        const k = applyKart(core.world, kartFromValues(self));
+        return kartBotInput(core.world, k, tick, skill, 0, mem);
+    };
+}
+export { nearestSample, lateralOffset };

package/dist/game/runner.d.ts

@@ -0,0 +1,286 @@
+import type { HitSource, InputCommand, SimEvent, SimWorld } from "@netforge/engine-sim";
+import type { CompiledGame } from "./compile.js";
+import type { EarnAward, GameEvent } from "./earn.js";
+import type { RunProgress } from "./profile.js";
+export type RunPhase = "playing" | "won" | "lost";
+export interface RunnerOptions {
+    /**
+     * Measurement only: keep this many enemies alive (topped up on rings,
+     * up to 64 a tick) on top of the game's own waves. Default 0 (off).
+     */
+    readonly holdEnemies?: number;
+    /** Measurement only: downed players stand straight back up. */
+    readonly godMode?: boolean;
+    /** Measurement only: the held crowd cycles through every non-boss enemy type (all behaviours on), not type 0. */
+    readonly holdMix?: boolean;
+    /** Seconds every player may be down before the run is lost. Default 5. */
+    readonly loseGraceSeconds?: number;
+    /** Seconds the end screen shows before a fresh run. Default 10 (arena 8). */
+    readonly endSeconds?: number;
+}
+export interface RunPlayerInfo {
+    readonly id: number;
+    readonly level: number;
+    readonly kills: number;
+    readonly downed: boolean;
+    readonly dead: boolean;
+    /** Times this player died this run. */
+    readonly deaths: number;
+    /** A server bot filling a seat. */
+    readonly bot: boolean;
+    /** Keeper id (null when the game declares none). */
+    readonly keeper: string | null;
+    /** A revive buff is running. */
+    readonly buffed: boolean;
+    /** This run's counts of the events the game's missions and achievements key on. */
+    readonly counts: Readonly<Record<string, number>>;
+    /** Achievement ids reached this run. */
+    readonly achievements: readonly string[];
+    /** Voted to play again (end screen). */
+    readonly ready: boolean;
+}
+/** One player's line on the end screen. Everything is data: names are declared ids, titles are declared text. */
+export interface RunSummaryPlayer {
+    readonly id: number;
+    readonly keeper: string | null;
+    /** Weapons with their level and the damage each dealt this run. */
+    readonly weapons: readonly {
+        readonly id: string;
+        readonly level: number;
+        readonly damage: number;
+    }[];
+    readonly passives: readonly {
+        readonly id: string;
+        readonly level: number;
+    }[];
+    readonly level: number;
+    readonly kills: number;
+    readonly damage: number;
+    readonly revives: number;
+    readonly downs: number;
+    readonly pickups: number;
+    /** What put this player down last (enemy prefab id and how), or null. */
+    readonly downedBy: {
+        readonly prefab: string;
+        readonly source: HitSource;
+    } | null;
+    /** Coins earned this run by earn rule (units of each rule's pay). */
+    readonly coins: readonly {
+        readonly rule: string;
+        readonly units: number;
+    }[];
+    /** Declared titles this player took. */
+    readonly titles: readonly string[];
+    readonly achievements: readonly string[];
+}
+export interface RunSummary {
+    /** Most enemies alive at once this run. */
+    readonly peak: number;
+    readonly seconds: number;
+    readonly players: readonly RunSummaryPlayer[];
+}
+/** Arena: one kill, newest last. `ago` is seconds since it happened. */
+export interface KillFeedEntry {
+    readonly by: number;
+    readonly victim: number;
+    readonly ago: number;
+}
+/** What the room broadcasts about the run (a few times a second, a few hundred bytes). */
+export interface RunInfo {
+    readonly run: number;
+    readonly phase: RunPhase;
+    /** Seconds since the run started. */
+    readonly seconds: number;
+    /** 1 + waves cleared (a dungeon's rooms cleared count as waves). */
+    readonly wave: number;
+    readonly kills: number;
+    readonly enemies: number;
+    /** The first living boss (kept for older clients; see `bosses`). */
+    readonly boss: {
+        readonly prefab: string;
+        readonly health: number;
+        readonly max: number;
+    } | null;
+    /** Every living boss, oldest first: each gets a HUD bar, and an edge arrow when off screen (x, z in m). */
+    readonly bosses: readonly {
+        readonly prefab: string;
+        readonly health: number;
+        readonly max: number;
+        readonly x: number;
+        readonly z: number;
+    }[];
+    /** True while the sim is paused for a solo player's upgrade cards. */
+    readonly paused: boolean;
+    /** The latest announcement (id increases with each new one), for the HUD's banner. */
+    readonly announce: {
+        readonly id: number;
+        readonly text: string;
+        readonly tone: "info" | "danger" | "reward";
+    } | null;
+    readonly players: readonly RunPlayerInfo[];
+    /** Seconds until a fresh run while the end screen shows. */
+    readonly nextRunIn: number | null;
+    /** Arena: the round clock and frag limit; null for survivor runs. */
+    readonly round: {
+        readonly seconds: number;
+        readonly left: number;
+        readonly frags: number | null;
+    } | null;
+    /** Arena: the last few kills. */
+    readonly feed: readonly KillFeedEntry[];
+    /** The HUD countdown a system set with `upcoming` ("THE BELL WARDEN" in 42 s), or null. */
+    readonly next: {
+        readonly label: string;
+        readonly in: number;
+    } | null;
+    /** The end screen's data while the run is over (null while playing). */
+    readonly summary: RunSummary | null;
+}
+export interface RunnerStep {
+    readonly events: readonly GameEvent[];
+    readonly awards: readonly EarnAward[];
+    /** True when this tick started a fresh run (players reset, counts cleared). */
+    readonly reset: boolean;
+}
+/**
+ * How sharp seat bots play against a person, from that person's record this
+ * round: a newcomer (no kills yet) faces loose bots, and they sharpen as
+ * the person wins (GAME-DESIGN.md "Bots that ramp").
+ */
+export declare function seatBotSkillVs(kills: number, deaths: number): number;
+export declare class GameRunner {
+    readonly compiled: CompiledGame;
+    readonly world: SimWorld;
+    private readonly opts;
+    private scheduler;
+    private runTick;
+    private runN;
+    private phase;
+    private phaseTicks;
+    private allDownTicks;
+    private pending;
+    /** Players whose referee run started after this world (round) began: world and fight progress never pays them (record). */
+    private readonly lateStart;
+    /** Systems are handling an unpaid event: what they emit now is unpaid too. */
+    private dispatchingUnpaid;
+    private readonly earn;
+    private readonly kills;
+    private readonly deaths;
+    private readonly emitted;
+    private teamKills;
+    private bosses;
+    private feed;
+    private readonly endTicks;
+    private readonly graceTicks;
+    private readonly arena;
+    private readonly roundTicks;
+    private readonly botMemory;
+    private readonly loadout;
+    private clock;
+    private director;
+    private holdNext;
+    private announcement;
+    private announceN;
+    /** Run tick when an XP boost ends (0: none). */
+    private boostEnds;
+    /** The sim was paused for a solo pick at the start of this step: the run clock stands still. */
+    private pausedStep;
+    private readonly ready;
+    private upcomingAt;
+    private readonly achievements;
+    private readonly missions;
+    /** Event names the missions and achievements count (their per-player counts go to the HUD). */
+    private readonly tracked;
+    /** Per enemy type: the "<prefab>.killed" event to raise, when something counts it. */
+    private readonly killNames;
+    private readonly unlocked;
+    /** Achievements, goals and titles reached since the room last took them (it writes them to profiles). */
+    private reached;
+    private readonly revives;
+    private readonly downs;
+    private readonly pickups;
+    private readonly lastHit;
+    private readonly downedBy;
+    private readonly coins;
+    private peak;
+    private viewTick;
+    private view;
+    constructor(compiled: CompiledGame, world: SimWorld, opts?: RunnerOptions);
+    private newRun;
+    private radiusOf;
+    /** Bosses are tougher with more players: health x (1 - k + k x players), k = players.bossHealthPerPlayer (0.55). */
+    private bossScale;
+    private spawnEdge;
+    private playerViews;
+    private presentPlayers;
+    private spawn;
+    private finish;
+    /**
+     * Profile progress since the last call: achievements and mission goals
+     * reached (humans only) and titles taken at the end of a run. The room
+     * server writes these to the players' profiles; the browser never does.
+     */
+    takeProgress(): RunProgress[];
+    /**
+     * Arena: the round is over. "round.top" credits the top fragger(s) (with at
+     * least one kill), "round.finished" everyone present. Topping a board of
+     * seat bots pays nothing: "round.top" is unpaid unless another person was
+     * in the round at the end.
+     */
+    private finishRound;
+    get phaseNow(): RunPhase;
+    get runNumber(): number;
+    /**
+     * Call once before each sim step: fills empty arena seats with bots,
+     * runs the systems' timers (waves) and the round clock while playing, and,
+     * given the step's input map, adds every bot's input to it.
+     */
+    beforeStep(inputs?: Map<number, InputCommand>): void;
+    /** Every human present voted to play again (bots always agree), after the end screen had a moment. */
+    private allReady;
+    /** A player joining a run in progress starts players.lateJoinBehind levels below the team's average, cards waiting. */
+    private catchUp;
+    private prefabOfEnemy;
+    /** Seats bots fill up to, with at least one human present; bots leave as humans join. One change a tick. */
+    private fillSeats;
+    /**
+     * Arena: what a bot (or a playtest player) does this tick, from the
+     * present state. Deterministic, so a room's run replays exactly.
+     */
+    autopilot(id: number): InputCommand;
+    private hold;
+    /** Earn credits humans only: bots fill seats, they never earn, and an unpaid event (a bot's death, a board of bots topped) pays no one. */
+    private record;
+    /** Call once after each sim step with its events. */
+    afterStep(simEvents: readonly SimEvent[]): RunnerStep;
+    /** Achievements and missions count the run's events (humans only, like earn). */
+    private progress;
+    private countsOf;
+    private keeperId;
+    /** The end screen: each player's build, damage per weapon, what downed them, coins and titles. */
+    summary(): RunSummary;
+    /** Each human's end-screen row, without titles. */
+    private summaryRows;
+    /** Who took each declared title (by id): the most (or, with 2+ players, the least) of its stat. */
+    private titleIds;
+    info(): RunInfo;
+    private bossHealth;
+    /** Boss NetIds alive now. */
+    bossIds(): number[];
+    /**
+     * A referee run starts for this player (the room's sign-in or round start):
+     * their earn counts and once-per-run payouts start over, and systems hear
+     * "run.started" (unpaid) so their own counters can start over too (a kill
+     * streak). A run started after this world began is never paid world or
+     * fight progress (boss.killed, wave.cleared, round.top, run.won, system
+     * emits: every event that is not the player's own act) until the next
+     * world, since that progress predates the run.
+     */
+    startRun(player: number): void;
+    /** Earn counts for one player this run (HUD and tests). */
+    count(player: number, event: string): number;
+    /** Total number of times an event has fired this run. */
+    emittedCount(event: string): number;
+    /** Kills by one player this run (arena: opponents). */
+    killsOf(player: number): number;
+}