@netforge/engine 0.0.0-stage → 0.1.0

package/dist/game/director.js

@@ -0,0 +1,179 @@
+/**
+ * The spawn director (GAME-DESIGN.md): the engine's
+ * answer to "top the crowd up to N". It runs on the authoritative side next
+ * to the systems, on the run clock, and is fully deterministic (the sim's
+ * PRNG, tick counts, netId-ordered loops in the sim).
+ *
+ *  - Spawns from a weighted pool at a curve-driven rate, up to a
+ *    curve-driven number alive, scaled by players present.
+ *  - Spawns just outside each player's screen (engine-sim edge points):
+ *    never on it, never clamped to a wall.
+ *  - Bodies the cap held back become "crowded" multipliers on later spawns.
+ *  - Recycles stragglers far off screen to the edge ahead of a moving player.
+ */
+import { edgeSpawnPoint, enemyCount, entityHeadroom, listPlayers, recycleEnemies, setEnemySpeed, simRandom, spawnEnemyScaled } from "@netforge/engine-sim";
+/** Value of a curve at `t` seconds: linear between keyframes, held outside them. */
+export function curveAt(c, t) {
+    if (typeof c === "number")
+        return c;
+    const first = c[0];
+    if (!first)
+        return 0;
+    if (t <= first[0])
+        return first[1];
+    for (let i = 1; i < c.length; i++) {
+        const b = c[i];
+        if (t <= b[0]) {
+            const a = c[i - 1];
+            return a[1] + ((b[1] - a[1]) * (t - a[0])) / (b[0] - a[0]);
+        }
+    }
+    return c[c.length - 1][1];
+}
+/** Ticks between straggler sweeps. */
+const RECYCLE_PERIOD = 15;
+export class Director {
+    def;
+    world;
+    hooks;
+    budget;
+    /** Bodies the cap held back, owed as toughness. */
+    pressure = 0;
+    /** Spawn-rate multiplier set by systems (events), and until when. */
+    boost = 1;
+    boostUntil = 0;
+    pausedUntil = 0;
+    /** Run tick of the next elite (-1: none planned). */
+    nextElite = -1;
+    constructor(def, world, hooks) {
+        this.def = def;
+        this.world = world;
+        this.hooks = hooks;
+        this.budget = def.start;
+        if (def.elites)
+            this.nextElite = Math.round(def.elites.from * world.tickRate);
+    }
+    /** Systems: stop spawning for `ticks` from `now` (events, set pieces). */
+    pause(now, ticks) {
+        this.pausedUntil = Math.max(this.pausedUntil, now + ticks);
+    }
+    /** Systems: multiply the spawn rate by `k` for `ticks` from `now`. */
+    surge(now, k, ticks) {
+        this.boost = k;
+        this.boostUntil = now + ticks;
+    }
+    /** Players present (at least 1), for the per-player scaling. */
+    players() {
+        return Math.max(1, listPlayers(this.world).length);
+    }
+    /** The living-enemy target at run tick `tick` (scaled by players). */
+    aliveTarget(tick) {
+        const t = tick / this.world.tickRate;
+        const mult = 1 + this.def.perPlayer * (this.players() - 1);
+        return Math.min(this.def.max, Math.round(curveAt(this.def.alive, t) * mult));
+    }
+    /** One run tick. */
+    tick(tick) {
+        const w = this.world;
+        const rate = w.tickRate;
+        const def = this.def;
+        if (def.recycle !== false && tick % RECYCLE_PERIOD === 0 && tick > 0) {
+            const r = def.recycle === true ? { seconds: 2.5, margin: 8 } : def.recycle;
+            recycleEnemies(w, RECYCLE_PERIOD, Math.round(r.seconds * rate), r.margin);
+        }
+        const t = tick / rate;
+        setEnemySpeed(w, curveAt(def.speed, t));
+        if (tick < this.pausedUntil)
+            return;
+        if (this.nextElite >= 0 && tick >= this.nextElite && def.elites) {
+            const e = this.pick(t);
+            if (e && this.spawnGroup(e.prefab, 1, t, true) > 0) {
+                const [lo, hi] = def.elites.every;
+                this.nextElite = tick + Math.round((lo + simRandom(w) * (hi - lo)) * rate);
+            }
+        }
+        const n = this.players();
+        const mult = 1 + def.perPlayer * (n - 1);
+        let perSecond = curveAt(def.rate, t) * mult * (this.hooks.bossAlive() ? def.whileBoss : 1);
+        if (tick < this.boostUntil)
+            perSecond *= this.boost;
+        this.budget = Math.min(this.budget + perSecond / rate, Math.max(this.budget, perSecond * 2 + 1));
+        const cap = Math.min(def.max, Math.round(curveAt(def.alive, t) * mult));
+        let alive = enemyCount(w);
+        let guard = 64;
+        while (this.budget >= 1 && guard-- > 0) {
+            if (alive >= cap) {
+                // The cap holds the body back; it comes back as toughness instead.
+                this.budget -= 1;
+                this.pressure = Math.min(this.pressure + 1, cap);
+                continue;
+            }
+            const entry = this.pick(t);
+            if (!entry) {
+                this.budget = 0;
+                break;
+            }
+            const g = entry.group;
+            const size = Array.isArray(g) ? g[0] + Math.floor(simRandom(w) * (g[1] - g[0] + 1)) : g;
+            const spawned = this.spawnGroup(entry.prefab, Math.min(size, cap - alive), t);
+            this.budget -= Math.max(1, size);
+            alive += spawned;
+            if (spawned === 0)
+                break;
+        }
+    }
+    pick(t) {
+        const def = this.def;
+        let total = 0;
+        const weights = [];
+        for (const e of def.pool) {
+            let wgt = 0;
+            if (t >= e.from && (e.until === undefined || t < e.until)) {
+                wgt = e.weight;
+                if (def.fade && t - e.from > def.fade.after)
+                    wgt *= def.fade.weight;
+            }
+            weights.push(wgt);
+            total += wgt;
+        }
+        if (total <= 0)
+            return null;
+        let r = simRandom(this.world) * total;
+        for (let i = 0; i < def.pool.length; i++) {
+            r -= weights[i] ?? 0;
+            if (r < 0)
+                return def.pool[i] ?? null;
+        }
+        return def.pool[def.pool.length - 1] ?? null;
+    }
+    /** Spawn up to `count` of a prefab from one heading off one player's screen. */
+    spawnGroup(prefab, count, t, elite = false) {
+        const w = this.world;
+        const type = this.hooks.typeOf(prefab);
+        if (type === undefined || count <= 0)
+            return 0;
+        const radius = this.hooks.radiusOf(prefab);
+        const def = this.def;
+        const base = { health: curveAt(def.health, t), damage: curveAt(def.damage, t), xp: curveAt(def.xp, t) };
+        // A group shares a heading: one stream from one direction.
+        const heading = count > 1 ? simRandom(w) * Math.PI * 2 : undefined;
+        const ahead = heading === undefined && simRandom(w) < def.ahead;
+        let n = 0;
+        for (let i = 0; i < count; i++) {
+            if (entityHeadroom(w) <= 64)
+                break;
+            const at = edgeSpawnPoint(w, undefined, heading !== undefined ? { heading, spread: 0.45, radius } : ahead ? { relative: "ahead", spread: 2, radius } : { radius });
+            if (!at)
+                break;
+            let scale = base;
+            if (this.pressure > 0) {
+                this.pressure--;
+                scale = { health: (base.health ?? 1) * def.crowded.health, damage: (base.damage ?? 1) * def.crowded.damage, xp: (base.xp ?? 1) * def.crowded.xp };
+            }
+            const id = spawnEnemyScaled(w, type, at[0], at[1], elite ? { ...scale, elite: true } : scale);
+            this.hooks.spawned?.(prefab, id);
+            n++;
+        }
+        return n;
+    }
+}

package/dist/game/earn-source.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Earn rules as source text: read and rewrite the `earn.rule(...)` lines of a
+ * game's src/game.ts.
+ *
+ * game.ts is the single source of truth for what a game pays. The room
+ * server's referee pays the compiled module's `pay`, and the launch
+ * registers one RewardVault rule per `earn.rule`, in declaration order
+ * (vault rule ids 1, 2, 3...). So the
+ * Launch panel never keeps its own copy of a payout: an edit there is a
+ * rewrite of game.ts, which goes through the same gate and build as any
+ * other change, and what launches is what the build declares.
+ *
+ * Pure, no imports, so the Net Forge server, the Net Forge site and the
+ * tests can all share it.
+ */
+export type OncePer = "run" | "day" | "lifetime";
+/** One `earn.rule(id, { when, n, pay, oncePer })` declaration. */
+export interface SourceEarnRule {
+    readonly id: string;
+    /** The game event it counts, e.g. "wave.cleared". */
+    readonly when: string;
+    /** Pays when the event's count reaches n in a run. */
+    readonly n: number;
+    /** Whole coins (1 coin = 1 token), up to 6 decimals. */
+    readonly pay: number;
+    readonly oncePer: OncePer;
+}
+/** The engine's id rule (api/schemas.ts idSchema). */
+export declare const EARN_RULE_ID: RegExp;
+/** The engine's event-name rule (api/schemas.ts earnRuleSchema.when). */
+export declare const EARN_EVENT: RegExp;
+/** Most rules one game declares (the Launch panel's limit too). */
+export declare const MAX_EARN_RULES = 8;
+/** Highest count a rule may wait for. */
+export declare const MAX_EARN_N = 100000;
+/** Highest payout one rule may make in one run, in coins. */
+export declare const MAX_EARN_PAY = 1000000;
+/**
+ * Events the sim raises by itself that may pay, per template (engine
+ * registry `on(...)` docs). A game's own `emit("...")` events are added from
+ * its source. Player-state events (downed, died, revived, levelup) are left
+ * out on purpose: they are cheap to farm.
+ */
+export declare const SIM_EARN_EVENTS: Readonly<Record<string, readonly string[]>>;
+/** The plain trigger a player reads, from the rule's event and count. */
+export declare function earnRuleLabel(when: string, n: number): string;
+export interface ReadEarnRules {
+    /** Every rule the panel can read, in declaration order (the vault's id order). */
+    readonly rules: readonly SourceEarnRule[];
+    /** Why some declaration cannot be read or rewritten; empty when the panel can edit them all. */
+    readonly problems: readonly string[];
+}
+/** The game's earn rules, in declaration order. */
+export declare function readEarnRules(source: string): ReadEarnRules;
+/** Events a game may pay on: the template's sim events and every `emit("...")` in its source. */
+export declare function earnEvents(source: string): string[];
+/** Every problem with a rule set, as one plain line each; empty when it can be written. */
+export declare function checkEarnRules(rules: readonly SourceEarnRule[], events: readonly string[]): string[];
+/** A fresh rule id for an event and count, unique among `taken`. */
+export declare function newEarnRuleId(when: string, n: number, taken: readonly string[]): string;
+/** The one line a rule is written as. */
+export declare function earnRuleLine(r: SourceEarnRule): string;
+export declare class EarnSourceError extends Error {
+}
+/**
+ * game.ts with its earn rules replaced by `rules`, in that order. The
+ * declarations are written as one block where the first one was, so the
+ * order in the file is the order given (the vault's rule ids). Throws
+ * EarnSourceError when an existing declaration cannot be read safely
+ * (nested, multi-line or computed): those games change their rules in chat.
+ */
+export declare function writeEarnRules(source: string, rules: readonly SourceEarnRule[]): string;
+/** Same rules, same order, same values (labels and launch settings aside). */
+export declare function sameEarnRules(a: readonly SourceEarnRule[], b: readonly SourceEarnRule[]): boolean;
+/**
+ * The buy-in run, `earn.stake({ min, max, multiple })` (the mandatory sink
+ * loop), read and rewritten the same way: one top-level
+ * line in game.ts, so the Launch panel shows exactly what the build pays.
+ */
+export interface SourceEarnStake {
+    /** Smallest stake a run takes, in coins. */
+    readonly min: number;
+    /** Largest stake a run takes, in coins. */
+    readonly max: number;
+    /** The stake's payout ceiling is stake x multiple. */
+    readonly multiple: number;
+}
+/** PLACEHOLDER: the engine's cap on the multiple (api/schemas.ts STAKE_MAX_MULTIPLE). */
+export declare const MAX_STAKE_MULTIPLE = 2;
+/** The engine's cap on one stake, in coins (api/schemas.ts STAKE_MAX_COINS). */
+export declare const MAX_STAKE_COINS = 1000000;
+export interface ReadEarnStake {
+    /** The declaration, or null when there is none (or it cannot be read). */
+    readonly stake: SourceEarnStake | null;
+    /** Why the panel cannot read or rewrite it; empty when it can. */
+    readonly problems: readonly string[];
+}
+/** The game's buy-in run terms. */
+export declare function readEarnStake(source: string): ReadEarnStake;
+/** Every problem with stake terms, as one plain line each; empty when they can be written. */
+export declare function checkEarnStake(s: SourceEarnStake): string[];
+/** The one line the stake is written as. */
+export declare function earnStakeLine(s: SourceEarnStake): string;
+/**
+ * game.ts with its buy-in run set to `stake`: the declaration is rewritten
+ * in place, or added after the last earn rule when there is none. Throws
+ * EarnSourceError when an existing one cannot be read safely.
+ */
+export declare function writeEarnStake(source: string, stake: SourceEarnStake): string;
+/** Same terms. */
+export declare function sameEarnStake(a: SourceEarnStake | null, b: SourceEarnStake | null): boolean;
+/** A PvP pot, `earn.pot({ entry, recycle })` (optional; the arena template). */
+export interface SourceEarnPot {
+    /** Coins each entrant pays in. */
+    readonly entry: number;
+    /** Share of every pot that stays in the reward pool. */
+    readonly recycle: number;
+    /** Pots are off by default until a legal review: true only when the line says `enabled: true`. */
+    readonly enabled?: boolean;
+}
+/** The game's PvP pot, read only (null when it has none or it is not written with plain values on one line). */
+export declare function readEarnPot(source: string): SourceEarnPot | null;