@netforge/engine 0.0.0-stage → 0.1.0

package/dist/api/registry.js

@@ -0,0 +1,394 @@
+import { GameDefinitionError, achievementSchema, keeperSchema, missionSchema, titleSchema, directorSchema, earnRuleSchema, earnStakeSchema, earnPotSchema, economySchema, metaUpgradeSchema, META_MAX_PER_STAT, META_MAX_TOTAL, META_MAX_UPGRADES, gameSchema, idSchema, parseOrThrow, prefabSchema, skuSchema, upgradeSchema, weaponSchema, } from "./schemas.js";
+const fresh = () => ({
+    game: null,
+    director: null,
+    prefabs: new Map(),
+    weapons: new Map(),
+    upgrades: new Map(),
+    systems: new Map(),
+    earnRules: new Map(),
+    stake: null,
+    pot: null,
+    skus: new Map(),
+    keepers: new Map(),
+    achievements: new Map(),
+    missions: new Map(),
+    titles: new Map(),
+    economy: null,
+    metaUpgrades: new Map(),
+    content: new Map(),
+});
+let reg = fresh();
+/**
+ * Set by `collectManifest`: the module that declared this registry is done.
+ * The next declaration starts a fresh registry, so a process can load more
+ * than one game module in turn (the room server hosts every template), each
+ * manifest collecting its own game right after importing it.
+ */
+let sealed = false;
+function unseal() {
+    if (!sealed)
+        return;
+    reg = fresh();
+    sealed = false;
+}
+const unique = (map, kind, id) => {
+    if (map.has(id))
+        throw new GameDefinitionError(`${kind} "${id}"`, [`${kind} "${id}" is declared twice; ids must be unique`]);
+};
+const checkId = (kind, id) => parseOrThrow(idSchema, id, `${kind} id`);
+/** Declare the game. Exactly one per game module; it is the module's default export. */
+export function game(def) {
+    unseal();
+    if (reg.game)
+        throw new GameDefinitionError("game()", ["game() is called twice; a game module declares exactly one game"]);
+    const parsed = parseOrThrow(gameSchema, def, "game()");
+    reg.game = parsed;
+    return parsed;
+}
+/** Declare a prefab: a spawnable entity template. */
+export function prefab(id, def) {
+    unseal();
+    checkId("prefab", id);
+    unique(reg.prefabs, "prefab", id);
+    const parsed = parseOrThrow(prefabSchema, def, `prefab("${id}")`);
+    reg.prefabs.set(id, parsed);
+    return parsed;
+}
+/** Declare a weapon (survivor template): it fires by itself; players gain and level weapons at level-up. */
+export function weapon(id, def) {
+    unseal();
+    checkId("weapon", id);
+    unique(reg.weapons, "weapon", id);
+    const parsed = parseOrThrow(weaponSchema, def, `weapon("${id}")`);
+    reg.weapons.set(id, parsed);
+    return parsed;
+}
+/** Declare a passive upgrade offered at level-up (survivor template). */
+export function upgrade(id, def) {
+    unseal();
+    checkId("upgrade", id);
+    unique(reg.upgrades, "upgrade", id);
+    if (reg.upgrades.size >= 8)
+        throw new GameDefinitionError(`upgrade("${id}")`, ["at most 8 passive upgrades per game"]);
+    const parsed = parseOrThrow(upgradeSchema, def, `upgrade("${id}")`);
+    reg.upgrades.set(id, parsed);
+    return parsed;
+}
+/**
+ * Declare the spawn director (at most one per game): who spawns, how many,
+ * how fast and how tough, over the run's clock. See directorSchema.
+ */
+export function director(def) {
+    if (reg.director)
+        throw new GameDefinitionError("director()", ["director() is called twice; a game has at most one director"]);
+    const parsed = parseOrThrow(directorSchema, def, "director()");
+    reg.director = parsed;
+    return parsed;
+}
+/** Declare a system. `setup` runs once when a run starts and schedules work with `every`, `after`, `onTick`. */
+export function system(name, setup) {
+    unseal();
+    checkId("system", name);
+    unique(reg.systems, "system", name);
+    if (typeof setup !== "function")
+        throw new GameDefinitionError(`system("${name}")`, ["the second argument must be a function"]);
+    reg.systems.set(name, setup);
+}
+/**
+ * Declare a keeper (a playable character): a start weapon and a signature
+ * passive. Players pick one before their first level; at most 15.
+ */
+export function keeper(id, def) {
+    unseal();
+    checkId("keeper", id);
+    unique(reg.keepers, "keeper", id);
+    if (reg.keepers.size >= 15)
+        throw new GameDefinitionError(`keeper("${id}")`, ["at most 15 keepers per game"]);
+    const parsed = parseOrThrow(keeperSchema, def, `keeper("${id}")`);
+    reg.keepers.set(id, parsed);
+    return parsed;
+}
+/** Declare an achievement (counted per player per run; it unlocks keepers, never coins). */
+export function achievement(id, def) {
+    unseal();
+    checkId("achievement", id);
+    unique(reg.achievements, "achievement", id);
+    const parsed = parseOrThrow(achievementSchema, def, `achievement("${id}")`);
+    reg.achievements.set(id, parsed);
+    return parsed;
+}
+/** Declare a daily goal (the HUD shows three a day; it pays nothing). */
+export function mission(id, def) {
+    unseal();
+    checkId("mission", id);
+    unique(reg.missions, "mission", id);
+    const parsed = parseOrThrow(missionSchema, def, `mission("${id}")`);
+    reg.missions.set(id, parsed);
+    return parsed;
+}
+/** Declare an end-screen title ("The Butcher": the most kills). */
+export function title(id, def) {
+    unseal();
+    checkId("title", id);
+    unique(reg.titles, "title", id);
+    const parsed = parseOrThrow(titleSchema, def, `title("${id}")`);
+    reg.titles.set(id, parsed);
+    return parsed;
+}
+/**
+ * Declare the game's coin model (at most once). Without it a game uses the
+ * recommended default: coins buy cosmetics, unlocks and in-run consumables,
+ * never permanent stat power. economy({ store: "cosmetics" }) sells looks
+ * only; economy({ metaUpgrades: true }) opts in to metaUpgrade(...).
+ */
+export function economy(def = {}) {
+    unseal();
+    if (reg.economy)
+        throw new GameDefinitionError("economy()", ["economy() is called twice; a game has one coin model"]);
+    const parsed = parseOrThrow(economySchema, def, "economy()");
+    reg.economy = parsed;
+    return parsed;
+}
+/**
+ * Declare a meta upgrade: a permanent stat bonus a player buys with coins,
+ * level by level (opt-in: economy({ metaUpgrades: true })). The engine caps
+ * meta power at +15% per stat and +30% in total, and costs grow
+ * geometrically. The store shows every level's bonus and price.
+ */
+export function metaUpgrade(id, def) {
+    unseal();
+    checkId("meta upgrade", id);
+    unique(reg.metaUpgrades, "meta upgrade", id);
+    if (reg.metaUpgrades.size >= META_MAX_UPGRADES)
+        throw new GameDefinitionError(`metaUpgrade("${id}")`, [`at most ${META_MAX_UPGRADES} meta upgrades per game`]);
+    const parsed = parseOrThrow(metaUpgradeSchema, def, `metaUpgrade("${id}")`);
+    reg.metaUpgrades.set(id, parsed);
+    return parsed;
+}
+/** Earn rules (every game must have at least one). */
+export const earn = {
+    rule(id, def) {
+        unseal();
+        checkId("earn rule", id);
+        unique(reg.earnRules, "earn rule", id);
+        const parsed = parseOrThrow(earnRuleSchema, def, `earn.rule("${id}")`);
+        reg.earnRules.set(id, parsed);
+        return parsed;
+    },
+    /**
+     * The buy-in run, the mandatory sink loop: earning
+     * above free play takes a stake of the game's coins at run start. One per
+     * game, written on one line so Net Forge's Launch panel can read and edit it.
+     */
+    stake(def) {
+        unseal();
+        if (reg.stake)
+            throw new GameDefinitionError("earn.stake", ["a game declares earn.stake(...) once"]);
+        const parsed = parseOrThrow(earnStakeSchema, def, "earn.stake");
+        reg.stake = parsed;
+        return parsed;
+    },
+    /**
+     * A PvP pot, optional, for the arena
+     * template: entrants pay `entry` coins before a round, the result splits
+     * the pot, and `recycle` of it stays in the reward pool.
+     */
+    pot(def) {
+        unseal();
+        if (reg.pot)
+            throw new GameDefinitionError("earn.pot", ["a game declares earn.pot(...) once"]);
+        const parsed = parseOrThrow(earnPotSchema, def, "earn.pot");
+        reg.pot = parsed;
+        return parsed;
+    },
+};
+/** Store SKUs: upgrades and cosmetics priced in the game's coins (and/or USDG). */
+export const store = {
+    sku(id, def) {
+        unseal();
+        checkId("sku", id);
+        unique(reg.skus, "sku", id);
+        const parsed = parseOrThrow(skuSchema, def, `store.sku("${id}")`);
+        reg.skus.set(id, parsed);
+        return parsed;
+    },
+};
+/**
+ * Collect and cross-check what the game module declared. Called by the
+ * build and the runtime after importing the module, not by game code.
+ */
+export function collectManifest() {
+    const issues = [];
+    if (!reg.game)
+        issues.push("no game() declaration; export default game({...})");
+    if (reg.earnRules.size === 0)
+        issues.push("every game needs at least one earn.rule(...)");
+    if (!reg.stake)
+        issues.push("every game needs a buy-in run: earn.stake({ min, max, multiple }) (the sink loop)");
+    if (reg.pot && reg.game && reg.game.template !== "arena")
+        issues.push("earn.pot(...) is for player-versus-player games: the arena template");
+    for (const id of [...reg.skus.keys(), ...reg.metaUpgrades.keys()])
+        if (id === POT_REASON)
+            issues.push(`"${POT_REASON}" is the pot's coin spend reason; pick another id`);
+    for (const id of reg.skus.keys())
+        if (id === STAKE_REASON)
+            issues.push(`store.sku("${id}"): "${STAKE_REASON}" is the buy-in run's coin spend reason; pick another id`);
+    for (const id of reg.metaUpgrades.keys())
+        if (id === STAKE_REASON)
+            issues.push(`metaUpgrade("${id}"): "${STAKE_REASON}" is the buy-in run's coin spend reason; pick another id`);
+    for (const [id, p] of reg.prefabs) {
+        for (const d of p.drops) {
+            const did = typeof d === "string" ? d : d.id;
+            if (!reg.prefabs.has(did))
+                issues.push(`prefab "${id}" drops "${did}", which is not a declared prefab`);
+        }
+    }
+    if (reg.weapons.size > 15)
+        issues.push("at most 15 weapons per game");
+    const start = reg.game?.players.weapon;
+    if (start !== undefined && !reg.weapons.has(start))
+        issues.push(`players.weapon is "${start}", which is not a declared weapon`);
+    for (const id of reg.game?.players.loadout ?? [])
+        if (!reg.weapons.has(id))
+            issues.push(`players.loadout has "${id}", which is not a declared weapon`);
+    const drop = reg.game?.players.drop;
+    if (drop !== undefined && !reg.prefabs.has(drop))
+        issues.push(`players.drop is "${drop}", which is not a declared prefab`);
+    for (const e of reg.director?.pool ?? []) {
+        if (!reg.prefabs.has(e.prefab))
+            issues.push(`director pool has "${e.prefab}", which is not a declared prefab`);
+        if (Array.isArray(e.group) && e.group[0] > e.group[1])
+            issues.push(`director pool "${e.prefab}": group [min, max] needs min <= max`);
+        if (e.until !== undefined && e.until <= e.from)
+            issues.push(`director pool "${e.prefab}": until must be after from`);
+    }
+    for (const [id, k] of reg.keepers) {
+        if (!reg.weapons.has(k.weapon))
+            issues.push(`keeper "${id}" starts with "${k.weapon}", which is not a declared weapon`);
+        if (k.passive !== undefined && !reg.upgrades.has(k.passive))
+            issues.push(`keeper "${id}" has passive "${k.passive}", which is not a declared upgrade`);
+        if (k.unlock !== undefined && !reg.achievements.has(k.unlock))
+            issues.push(`keeper "${id}" unlocks with "${k.unlock}", which is not a declared achievement`);
+    }
+    if (reg.keepers.size > 0 && [...reg.keepers.values()].every((k) => k.unlock !== undefined)) {
+        issues.push("at least one keeper needs no unlock (everyone must have a keeper to start with)");
+    }
+    const [firstKeeper, first] = [...reg.keepers][0] ?? [];
+    if (first?.unlock !== undefined)
+        issues.push(`keeper "${firstKeeper}" is declared first, so it is everyone's default: it cannot have an unlock (declare a free keeper first)`);
+    issues.push(...economyIssues(reg));
+    if (issues.length > 0 || !reg.game || !reg.stake)
+        throw new GameDefinitionError("game module", issues);
+    sealed = true;
+    return {
+        game: reg.game,
+        prefabs: reg.prefabs,
+        weapons: reg.weapons,
+        upgrades: reg.upgrades,
+        systems: reg.systems,
+        earnRules: reg.earnRules,
+        stake: reg.stake,
+        pot: reg.pot,
+        skus: reg.skus,
+        director: reg.director,
+        keepers: reg.keepers,
+        achievements: reg.achievements,
+        missions: reg.missions,
+        titles: reg.titles,
+        economy: reg.economy ?? parseOrThrow(economySchema, {}, "economy()"),
+        metaUpgrades: reg.metaUpgrades,
+        content: reg.content,
+    };
+}
+/**
+ * A genre declaration (rules/genres: tower(...), board(...), card(...)):
+ * stored under "<kind>:<id>" for the genre's compile step to read. Ids are
+ * unique per kind. Game code calls the genre's own typed function, never this.
+ */
+export function declareContent(kind, id, value) {
+    unseal();
+    const key = `${kind}:${id}`;
+    if (reg.content.has(key))
+        throw new GameDefinitionError(`${kind}("${id}")`, [`${kind} "${id}" is declared twice; ids must be unique`]);
+    reg.content.set(key, value);
+}
+/** Genre content of one kind, in declaration order (id, value). */
+export function contentOf(m, kind) {
+    const out = [];
+    for (const [k, v] of m.content)
+        if (k.startsWith(`${kind}:`))
+            out.push([k.slice(kind.length + 1), v]);
+    return out;
+}
+/** The coin spend reason a buy-in run's stake is spent under (the referee reads it at run start). */
+export const STAKE_REASON = "stake";
+/** The coin spend reason a PvP pot entry is spent under. */
+export const POT_REASON = "pot";
+/** A coin spend's reason (the SKU or meta upgrade id) must fit the referee's ledger. */
+const SPEND_REASON = /^[a-z][a-z0-9_]{1,30}$/;
+/** The coin model's cross-checks. */
+function economyIssues(r) {
+    const issues = [];
+    const e = r.economy ?? { store: "default", metaUpgrades: false };
+    const firstKeeper = [...r.keepers.keys()][0];
+    const looks = new Map();
+    for (const [id, sku] of r.skus) {
+        if (sku.coins !== undefined && !SPEND_REASON.test(id))
+            issues.push(`store.sku("${id}"): a coin-priced SKU id is 2-31 characters (a-z, 0-9, _)`);
+        const g = sku.grants;
+        if (e.store === "cosmetics" && !(g && "cosmetic" in g)) {
+            issues.push(`store.sku("${id}"): economy({ store: "cosmetics" }) sells looks only; give it grants: { cosmetic: <id> } or remove it`);
+        }
+        if (!g)
+            continue;
+        if ("keeper" in g) {
+            const k = r.keepers.get(g.keeper);
+            if (!k)
+                issues.push(`store.sku("${id}") unlocks keeper "${g.keeper}", which is not a declared keeper`);
+            else if (g.keeper === firstKeeper)
+                issues.push(`store.sku("${id}") sells keeper "${g.keeper}", the free default keeper`);
+            else if (k.unlock !== undefined) {
+                issues.push(`keeper "${g.keeper}" is both unlocked by an achievement ("${k.unlock}") and sold by store.sku("${id}"); a keeper is earned or bought, never both (drop its unlock, or the SKU)`);
+            }
+        }
+        else if ("gear" in g) {
+            if (!r.upgrades.has(g.gear))
+                issues.push(`store.sku("${id}") is gear for "${g.gear}", which is not a declared upgrade`);
+            if (sku.coins === undefined || sku.usdg !== undefined)
+                issues.push(`store.sku("${id}"): gear sells for coins only (its coins stay in the reward pool when it is lost)`);
+        }
+        else {
+            const other = looks.get(g.cosmetic);
+            if (other !== undefined)
+                issues.push(`store.sku("${id}") and store.sku("${other}") both grant cosmetic ${g.cosmetic}`);
+            looks.set(g.cosmetic, id);
+        }
+    }
+    if (r.metaUpgrades.size > 0 && !e.metaUpgrades) {
+        issues.push("metaUpgrade(...) is opt-in: declare economy({ metaUpgrades: true }) to sell permanent stat upgrades for coins");
+    }
+    const perStat = new Map();
+    let total = 0;
+    for (const [id, m] of r.metaUpgrades) {
+        if (!SPEND_REASON.test(id))
+            issues.push(`metaUpgrade("${id}"): its id is 2-31 characters (a-z, 0-9, _)`);
+        if (r.skus.has(id))
+            issues.push(`metaUpgrade("${id}") and store.sku("${id}") share an id; ids are coin spend reasons and must differ`);
+        const v = m.step * m.levels;
+        perStat.set(m.stat, (perStat.get(m.stat) ?? 0) + v);
+        total += v;
+    }
+    for (const [stat, v] of perStat) {
+        if (v > META_MAX_PER_STAT + 1e-9)
+            issues.push(`meta upgrades raise ${stat} by +${Math.round(v * 100)}% at their top levels; the engine caps one stat at +${Math.round(META_MAX_PER_STAT * 100)}%`);
+    }
+    if (total > META_MAX_TOTAL + 1e-9)
+        issues.push(`meta upgrades add +${Math.round(total * 100)}% in total at their top levels; the engine caps all meta power at +${Math.round(META_MAX_TOTAL * 100)}%`);
+    return issues;
+}
+/** Forget all declarations (the build and tests load several game modules in one process). */
+export function resetRegistry() {
+    reg = fresh();
+    sealed = false;
+}

package/dist/api/scheduler.d.ts

@@ -0,0 +1,56 @@
+import type { GameManifest, PlayerView, SpawnEdgeOptions } from "./registry.js";
+/** What the scheduler needs from the simulation it drives. */
+export interface SystemHost {
+    readonly tickRate: number;
+    tick(): number;
+    players(): readonly PlayerView[];
+    spawn(prefab: string, at: readonly [number, number, number], opts?: {
+        readonly elite?: boolean;
+    }): void;
+    random(): number;
+    emit(event: string, players?: readonly number[]): void;
+    /** Living enemies of a prefab (or all). Hosts that do not simulate enemies may omit it. */
+    alive?(prefab?: string): number;
+    respawnDead?(): void;
+    end?(outcome: "won" | "lost"): void;
+    /**
+     * A ring point around (cx, cz) inside the arena and clear of obstacles,
+     * or null. Hosts without one get plain ring math.
+     */
+    ringPoint?(cx: number, cz: number, radius: number, prefab: string): readonly [number, number] | null;
+    /** Spawn just off screen (the host knows the camera). Hosts without one fall back to a ring at 24 m. */
+    spawnEdge?(prefab: string, opts: SpawnEdgeOptions): number;
+    spawnPickup?(prefab: string, at: readonly [number, number, number]): void;
+    announce?(text: string, tone: "info" | "danger" | "reward"): void;
+    upcoming?(label: string, seconds: number): void;
+    bossAlive?(): boolean;
+    pauseDirector?(seconds: number): void;
+    surge?(multiplier: number, seconds: number): void;
+    xpBoost?(multiplier: number, seconds: number): void;
+    scatter?(prefab: string, count: number): number;
+    clear?(prefab: string): number;
+    onScreen?(x: number, z: number): boolean;
+}
+/**
+ * Runs the declared systems' schedules against a host, one fixed tick at a
+ * time. Timers are tick-based (seconds are rounded to whole ticks at
+ * declaration), so the schedule is identical on the server and in client
+ * prediction. Timers fire in declaration order within a tick.
+ */
+export declare class SystemScheduler {
+    private readonly manifest;
+    private readonly host;
+    private readonly timers;
+    private readonly perTick;
+    private readonly listeners;
+    private started;
+    constructor(manifest: GameManifest, host: SystemHost);
+    private toTicks;
+    private context;
+    /** Run every system's setup once. Call at the start of a run, before the first `tick`. */
+    start(): void;
+    /** Deliver a game event to the systems that subscribed with `on`. */
+    dispatch(event: string, players: readonly number[]): void;
+    /** Fire everything due at the host's current tick. Call once per fixed tick. */
+    tick(): void;
+}

package/dist/api/scheduler.js

@@ -0,0 +1,160 @@
+import { GameDefinitionError } from "./schemas.js";
+/**
+ * Runs the declared systems' schedules against a host, one fixed tick at a
+ * time. Timers are tick-based (seconds are rounded to whole ticks at
+ * declaration), so the schedule is identical on the server and in client
+ * prediction. Timers fire in declaration order within a tick.
+ */
+export class SystemScheduler {
+    manifest;
+    host;
+    timers = [];
+    perTick = [];
+    listeners = new Map();
+    started = false;
+    constructor(manifest, host) {
+        this.manifest = manifest;
+        this.host = host;
+    }
+    toTicks(seconds, what) {
+        if (!(Number.isFinite(seconds) && seconds > 0)) {
+            throw new GameDefinitionError(what, [`seconds must be a positive number, got ${seconds}`]);
+        }
+        return Math.max(1, Math.round(seconds * this.host.tickRate));
+    }
+    context(system) {
+        const h = this.host;
+        const prefabs = this.manifest.prefabs;
+        const checkPrefab = (id) => {
+            if (!prefabs.has(id))
+                throw new GameDefinitionError(`system("${system}")`, [`spawns "${id}", which is not a declared prefab`]);
+        };
+        return {
+            tick: () => h.tick(),
+            time: () => h.tick() / h.tickRate,
+            players: () => h.players(),
+            every: (seconds, fn) => {
+                const period = this.toTicks(seconds, `system("${system}").every`);
+                this.timers.push({ due: h.tick() + period, period, n: 0, fn, repeat: true });
+            },
+            after: (seconds, fn) => {
+                const period = this.toTicks(seconds, `system("${system}").after`);
+                this.timers.push({ due: h.tick() + period, period, n: 0, fn: () => fn(), repeat: false });
+            },
+            onTick: (fn) => {
+                this.perTick.push(fn);
+            },
+            spawn: (id, at, opts) => {
+                checkPrefab(id);
+                h.spawn(id, at, opts);
+            },
+            spawnRing: (id, opts) => {
+                checkPrefab(id);
+                const all = h.players().filter((p) => p.alive);
+                const centre = opts.around !== undefined ? all.filter((p) => p.id === opts.around) : all;
+                const count = Math.max(0, Math.floor(opts.count));
+                for (let i = 0; i < count; i++) {
+                    const p = centre.length > 0 ? centre[Math.floor(h.random() * centre.length)] : undefined;
+                    const [cx, cy, cz] = p ? p.position : [0, 0, 0];
+                    if (h.ringPoint) {
+                        const at = h.ringPoint(cx, cz, opts.radius, id);
+                        if (at)
+                            h.spawn(id, [at[0], cy, at[1]]);
+                        continue;
+                    }
+                    const a = h.random() * Math.PI * 2;
+                    h.spawn(id, [cx + Math.cos(a) * opts.radius, cy, cz + Math.sin(a) * opts.radius]);
+                }
+            },
+            spawnEdge: (id, opts) => {
+                checkPrefab(id);
+                const count = Math.max(0, Math.floor(opts.count));
+                if (count === 0)
+                    return 0;
+                if (h.spawnEdge)
+                    return h.spawnEdge(id, { ...opts, count });
+                const all = h.players().filter((p) => p.alive);
+                let n = 0;
+                for (let i = 0; i < count; i++) {
+                    const p = all.length > 0 ? all[Math.floor(h.random() * all.length)] : undefined;
+                    const [cx, cy, cz] = p ? p.position : [0, 0, 0];
+                    const a = h.random() * Math.PI * 2;
+                    h.spawn(id, [cx + Math.cos(a) * 24, cy, cz + Math.sin(a) * 24]);
+                    n++;
+                }
+                return n;
+            },
+            emit: (event, players) => h.emit(event, players),
+            random: () => h.random(),
+            alive: (id) => {
+                if (id !== undefined)
+                    checkPrefab(id);
+                return h.alive ? h.alive(id) : 0;
+            },
+            on: (event, fn) => {
+                const list = this.listeners.get(event) ?? [];
+                list.push(fn);
+                this.listeners.set(event, list);
+            },
+            respawnDead: () => h.respawnDead?.(),
+            spawnPickup: (id, at) => {
+                checkPrefab(id);
+                h.spawnPickup?.(id, at);
+            },
+            announce: (text, opts) => {
+                const t = String(text).slice(0, 60);
+                if (t)
+                    h.announce?.(t, opts?.tone ?? "info");
+            },
+            upcoming: (label, seconds) => {
+                const t = String(label).slice(0, 40);
+                if (t)
+                    h.upcoming?.(t, this.toTicks(seconds, `system("${system}").upcoming`) / h.tickRate);
+            },
+            bossAlive: () => h.bossAlive?.() ?? false,
+            pauseDirector: (seconds) => h.pauseDirector?.(this.toTicks(seconds, `system("${system}").pauseDirector`) / h.tickRate),
+            surge: (multiplier, seconds) => h.surge?.(Math.max(0, Math.min(10, multiplier)), this.toTicks(seconds, `system("${system}").surge`) / h.tickRate),
+            xpBoost: (multiplier, seconds) => h.xpBoost?.(Math.max(0, Math.min(10, multiplier)), this.toTicks(seconds, `system("${system}").xpBoost`) / h.tickRate),
+            scatter: (id, count) => {
+                checkPrefab(id);
+                return h.scatter?.(id, Math.max(0, Math.min(200, Math.floor(count)))) ?? 0;
+            },
+            clear: (id) => {
+                checkPrefab(id);
+                return h.clear?.(id) ?? 0;
+            },
+            end: (outcome) => h.end?.(outcome),
+            onScreen: (x, z) => h.onScreen?.(x, z) ?? false,
+        };
+    }
+    /** Run every system's setup once. Call at the start of a run, before the first `tick`. */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        for (const [name, setup] of this.manifest.systems)
+            setup(this.context(name));
+    }
+    /** Deliver a game event to the systems that subscribed with `on`. */
+    dispatch(event, players) {
+        for (const fn of this.listeners.get(event) ?? [])
+            fn(players);
+    }
+    /** Fire everything due at the host's current tick. Call once per fixed tick. */
+    tick() {
+        const now = this.host.tick();
+        for (const fn of this.perTick)
+            fn();
+        for (let i = 0; i < this.timers.length; i++) {
+            const t = this.timers[i];
+            if (!t || t.due > now)
+                continue;
+            t.n++;
+            t.fn(t.n);
+            if (t.repeat)
+                t.due += t.period;
+            else
+                this.timers.splice(i--, 1);
+        }
+    }
+}