@netforge/engine 0.0.0-stage → 0.2.0

package/dist/game/profile.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Universal saves and the coin model, as the engine declares them.
+ *
+ * A player's progress (achievements, unlocked keepers, today's goals,
+ * titles, owned cosmetics and unlocks, meta upgrade levels, settings) is
+ * kept per player on the room server, keyed by the signed-in wallet or a
+ * guest id, never in the browser. The room grants achievements, goals and
+ * titles from the authoritative sim, checks keeper picks against what the
+ * profile has unlocked, and applies owned meta upgrades at the start of
+ * every run. This module is the shared, pure part: what a game declares
+ * that a profile can hold, and the rules both the server and clients use
+ * (unlocks, today's goals, meta prices and caps). No I/O here.
+ */
+import type { GameManifest } from "../api/registry.js";
+import { type EconomyDef, type MetaStat, type MetaUpgradeDef, type SkuGrant } from "../api/schemas.js";
+/** What a SKU is in the coin model: an in-run consumable, a look owned for good, or an unlock owned for good. */
+export type SkuKind = "consumable" | "cosmetic" | "unlock" | "gear";
+export interface ProfileSku {
+    readonly id: string;
+    readonly kind: SkuKind;
+    /** Whole coins, or null when the SKU sells for dollars only. */
+    readonly coins: number | null;
+    readonly grants: SkuGrant | null;
+}
+/** What one game lets a profile hold, from its manifest. */
+export interface ProfileSpec {
+    /**
+     * Keepers in index order (the index rides the input bits); `unlock` is the
+     * achievement that opens it; `sold`: a store SKU sells it (then it has no
+     * unlock, and it is open only once bought).
+     */
+    readonly keepers: readonly {
+        readonly id: string;
+        readonly unlock: string | null;
+        readonly sold: boolean;
+    }[];
+    readonly achievements: readonly string[];
+    readonly missions: ReadonlyMap<string, {
+        readonly when: string;
+        readonly n: number;
+    }>;
+    readonly titles: readonly string[];
+    readonly skus: ReadonlyMap<string, ProfileSku>;
+    readonly meta: ReadonlyMap<string, MetaUpgradeDef>;
+    readonly economy: EconomyDef;
+}
+/** Event a run reports for a player's profile (the room writes it; the browser never does). */
+export interface RunProgress {
+    readonly player: number;
+    readonly kind: "achievement" | "goal" | "title";
+    /** The declared achievement, mission or title id. */
+    readonly id: string;
+}
+/** Which keepers a profile may play (by index), from its achievements and owned unlocks. */
+export interface ProfileUnlockState {
+    readonly achievements: Iterable<string>;
+    /** Achievements the profile holds only through the one-time local import: they never open a sold keeper. */
+    readonly imported?: Iterable<string>;
+    /** Owned SKU ids. */
+    readonly owned: Iterable<string>;
+}
+export declare function skuKind(grants: SkuGrant | undefined | null): SkuKind;
+/** Owned gear (losable, staked runs only): the SKU, the run upgrade it brings, and its loss line. */
+export declare function ownedGear(spec: ProfileSpec, owned: Iterable<string>): Array<{
+    sku: string;
+    upgrade: string;
+    loseBelow: number;
+    coins: number;
+}>;
+/** The profile view of a manifest. */
+export declare function profileSpec(m: GameManifest): ProfileSpec;
+/** UTC day number (days since 1970-01-01): daily goals roll over at 00:00 UTC. */
+export declare function utcDay(ms: number): number;
+/** Today's goals: `n` of the declared missions, the same for everyone on a UTC day. */
+export declare function todaysGoals(ids: readonly string[], day: number, n?: number): string[];
+/**
+ * Keeper indices a profile may play: free keepers, keepers whose achievement
+ * it reached, keepers it bought. A sold keeper opens only by purchase: an
+ * imported achievement never opens it (defense in depth; the build already
+ * refuses a keeper that is both earned and sold).
+ */
+export declare function openKeepers(spec: ProfileSpec, state: ProfileUnlockState): number[];
+/** Cosmetic ids a profile owns (0, the default look, always). */
+export declare function ownedCosmetics(spec: ProfileSpec, owned: Iterable<string>): number[];
+/** Coins for the next level of a meta upgrade from `level` (0 = none owned), or null at the top. Geometric: cost x growth^level. */
+export declare function metaPrice(def: MetaUpgradeDef, level: number): number | null;
+/**
+ * The stat bonus a profile's meta levels give, with the engine's caps
+ * applied again (+15% per stat, +30% in total, scaled down evenly past
+ * it), whatever the declarations or the stored levels say.
+ */
+export declare function metaBonus(spec: ProfileSpec, levels: Readonly<Record<string, number>>): Partial<Record<MetaStat, number>>;
+/** Meta levels as one integer (3 bits per upgrade, declaration order), the payload of the room's "meta" sim command. */
+export declare function packMeta(spec: ProfileSpec, levels: Readonly<Record<string, number>>): number;
+export declare function unpackMeta(spec: ProfileSpec, value: number): Record<string, number>;
+/** Room command names a client may never send: the room issues them from the profile. */
+export declare const RESERVED_COMMANDS: ReadonlySet<string>;

package/dist/game/profile.js

@@ -0,0 +1,140 @@
+import { META_MAX_PER_STAT, META_MAX_TOTAL } from "../api/schemas.js";
+export function skuKind(grants) {
+    if (!grants)
+        return "consumable";
+    return "cosmetic" in grants ? "cosmetic" : "gear" in grants ? "gear" : "unlock";
+}
+/** Owned gear (losable, staked runs only): the SKU, the run upgrade it brings, and its loss line. */
+export function ownedGear(spec, owned) {
+    const out = [];
+    for (const id of owned) {
+        const s = spec.skus.get(id);
+        if (s?.grants && "gear" in s.grants)
+            out.push({ sku: id, upgrade: s.grants.gear, loseBelow: s.grants.loseBelow, coins: s.coins ?? 0 });
+    }
+    return out;
+}
+/** The profile view of a manifest. */
+export function profileSpec(m) {
+    const skus = new Map();
+    const sold = new Set();
+    for (const [id, s] of m.skus) {
+        skus.set(id, { id, kind: skuKind(s.grants), coins: s.coins ?? null, grants: s.grants ?? null });
+        if (s.grants && "keeper" in s.grants)
+            sold.add(s.grants.keeper);
+    }
+    return {
+        keepers: [...m.keepers].map(([id, k]) => ({ id, unlock: k.unlock ?? null, sold: sold.has(id) })),
+        achievements: [...m.achievements.keys()],
+        missions: new Map([...m.missions].map(([id, d]) => [id, { when: d.when, n: d.n }])),
+        titles: [...m.titles.keys()],
+        skus,
+        meta: m.metaUpgrades,
+        economy: m.economy,
+    };
+}
+/** UTC day number (days since 1970-01-01): daily goals roll over at 00:00 UTC. */
+export function utcDay(ms) {
+    return Math.floor(ms / 86_400_000);
+}
+/** Today's goals: `n` of the declared missions, the same for everyone on a UTC day. */
+export function todaysGoals(ids, day, n = 3) {
+    const pool = [...ids];
+    const out = [];
+    let h = (day * 2654435761) >>> 0;
+    while (out.length < n && pool.length > 0) {
+        h = (Math.imul(h ^ (h >>> 15), 0x2c1b3c6d) + 0x9e3779b9) >>> 0;
+        out.push(...pool.splice(h % pool.length, 1));
+    }
+    return out;
+}
+/**
+ * Keeper indices a profile may play: free keepers, keepers whose achievement
+ * it reached, keepers it bought. A sold keeper opens only by purchase: an
+ * imported achievement never opens it (defense in depth; the build already
+ * refuses a keeper that is both earned and sold).
+ */
+export function openKeepers(spec, state) {
+    const reached = new Set(state.achievements);
+    const imported = new Set(state.imported ?? []);
+    const bought = new Set();
+    for (const id of state.owned) {
+        const g = spec.skus.get(id)?.grants;
+        if (g && "keeper" in g)
+            bought.add(g.keeper);
+    }
+    const out = [];
+    spec.keepers.forEach((k, i) => {
+        if (bought.has(k.id))
+            return void out.push(i);
+        if (k.sold) {
+            if (k.unlock !== null && reached.has(k.unlock) && !imported.has(k.unlock))
+                out.push(i);
+            return;
+        }
+        if (k.unlock === null || reached.has(k.unlock))
+            out.push(i);
+    });
+    return out;
+}
+/** Cosmetic ids a profile owns (0, the default look, always). */
+export function ownedCosmetics(spec, owned) {
+    const out = new Set([0]);
+    for (const id of owned) {
+        const g = spec.skus.get(id)?.grants;
+        if (g && "cosmetic" in g)
+            out.add(g.cosmetic);
+    }
+    return [...out].sort((a, b) => a - b);
+}
+/** Coins for the next level of a meta upgrade from `level` (0 = none owned), or null at the top. Geometric: cost x growth^level. */
+export function metaPrice(def, level) {
+    if (!Number.isInteger(level) || level < 0 || level >= def.levels)
+        return null;
+    return Math.round(def.cost * Math.pow(def.growth, level));
+}
+/**
+ * The stat bonus a profile's meta levels give, with the engine's caps
+ * applied again (+15% per stat, +30% in total, scaled down evenly past
+ * it), whatever the declarations or the stored levels say.
+ */
+export function metaBonus(spec, levels) {
+    const out = {};
+    for (const [id, def] of spec.meta) {
+        const lv = Math.max(0, Math.min(def.levels, Math.floor(levels[id] ?? 0)));
+        if (lv > 0)
+            out[def.stat] = (out[def.stat] ?? 0) + def.step * lv;
+    }
+    let total = 0;
+    for (const k of Object.keys(out)) {
+        out[k] = Math.min(META_MAX_PER_STAT, out[k] ?? 0);
+        total += out[k] ?? 0;
+    }
+    if (total > META_MAX_TOTAL)
+        for (const k of Object.keys(out))
+            out[k] = ((out[k] ?? 0) * META_MAX_TOTAL) / total;
+    return out;
+}
+/** Meta levels as one integer (3 bits per upgrade, declaration order), the payload of the room's "meta" sim command. */
+export function packMeta(spec, levels) {
+    let v = 0;
+    let i = 0;
+    for (const [id, def] of spec.meta) {
+        const lv = Math.max(0, Math.min(def.levels, 7, Math.floor(levels[id] ?? 0)));
+        v += lv * Math.pow(8, i++);
+    }
+    return v;
+}
+export function unpackMeta(spec, value) {
+    const out = {};
+    let v = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+    for (const [id, def] of spec.meta) {
+        const lv = Math.min(def.levels, v % 8);
+        if (lv > 0)
+            out[id] = lv;
+        v = Math.floor(v / 8);
+    }
+    return out;
+}
+/** Room command names a client may never send: the room issues them from the profile. */
+export const RESERVED_COMMANDS = new Set(["meta"]);

package/dist/game/race.d.ts

@@ -0,0 +1,177 @@
+/**
+ * The race machinery shared by the platformer and the racer templates: a
+ * round is a run (countdown, race, results), finishing order, seat bots that
+ * fill empty places and never earn, the declared systems on the race clock,
+ * earn rules, achievements and missions. Each template plugs its own sim in
+ * through `RaceCore` (platformer.ts, racer.ts).
+ *
+ * Runs only on the authoritative side (room server, headless harness).
+ * Clients predict their own body and read the rest from snapshots and the
+ * broadcast `RaceInfo`.
+ */
+import type { InputCommand } from "@netforge/engine-sim";
+import type { GameManifest } from "../api/registry.js";
+import type { EarnAward, GameEvent } from "./earn.js";
+import type { RunProgress } from "./profile.js";
+/** What the sim says happened this tick, as named game events for one player. */
+export interface RaceSimEvent {
+    readonly name: string;
+    readonly player: number;
+}
+/** A template's sim as the race runner drives it. */
+export interface RaceCore {
+    readonly tickRate: number;
+    /** Player ids present, ascending. */
+    ids(): number[];
+    add(id: number, bot: boolean, frozen: boolean): void;
+    remove(id: number): void;
+    /** A fresh round on course `course`: everyone back to the start, run upgrades cleared, frozen or not. */
+    reset(course: number, frozen: boolean): void;
+    setFrozen(frozen: boolean): void;
+    finished(id: number): boolean;
+    /** Course progress, 0..1 (1: finished). */
+    progress(id: number): number;
+    position(id: number): readonly [number, number, number];
+    /** One fixed tick. Events: "player.finished" plus the template's own ("coin.collected", "lap.completed", ...). */
+    step(inputs: ReadonlyMap<number, InputCommand>): RaceSimEvent[];
+    /** What a bot does now: deterministic, `skill` 0..1. */
+    botInput(id: number, clock: number, skill: number): InputCommand;
+    /** One level of a declared upgrade (store SKU or gear) for the rest of the round. */
+    grant(id: number, upgrade: number): boolean;
+    setCosmetic(id: number, cosmetic: number): void;
+}
+export type RacePhase = "countdown" | "racing" | "results";
+export interface RacePlayerInfo {
+    readonly id: number;
+    readonly bot: boolean;
+    /** Finishing place (1 = first), or null while racing. */
+    readonly place: number | null;
+    /** Seconds from the start to the finish line, or null. */
+    readonly time: number | null;
+    /** 0..1 along the course. */
+    readonly progress: number;
+    /** Live position among everyone (finished first, then by progress). */
+    readonly rank: number;
+    readonly counts: Readonly<Record<string, number>>;
+    readonly ready: boolean;
+}
+export interface RaceInfo {
+    readonly run: number;
+    readonly phase: RacePhase;
+    /** The course (level or track) index this round runs. */
+    readonly course: number;
+    /** Seconds left of the countdown (countdown phase). */
+    readonly countdown: number;
+    /** Seconds since the start signal. */
+    readonly seconds: number;
+    /** Seconds left before the round closes (time limit), or null. */
+    readonly left: number | null;
+    readonly players: readonly RacePlayerInfo[];
+    readonly announce: {
+        readonly id: number;
+        readonly text: string;
+        readonly tone: "info" | "danger" | "reward";
+    } | null;
+    readonly next: {
+        readonly label: string;
+        readonly in: number;
+    } | null;
+    /** Seconds until the next round while results show. */
+    readonly nextRunIn: number | null;
+    /** Results: each human's coins by earn rule this round. */
+    readonly coins: readonly {
+        readonly id: number;
+        readonly rules: readonly {
+            readonly rule: string;
+            readonly units: number;
+        }[];
+    }[];
+}
+export interface RaceRunnerOptions {
+    /** Seconds of countdown before each round. Default 3. */
+    readonly countdownSeconds?: number;
+    /** Seconds the results show. Default 8. */
+    readonly endSeconds?: number;
+    /** After every person present has finished, seconds the others get. Default 4. */
+    readonly graceSeconds?: number;
+    /** After the first person finishes, seconds everyone else has to reach the finish (an idle player never holds the round). Default 25. */
+    readonly finishWindowSeconds?: number;
+}
+export interface RaceStep {
+    readonly events: readonly GameEvent[];
+    readonly awards: readonly EarnAward[];
+    readonly reset: boolean;
+}
+export declare class RaceRunner {
+    readonly manifest: GameManifest;
+    readonly core: RaceCore;
+    private readonly opts;
+    private scheduler;
+    private runN;
+    private runTick;
+    private clock;
+    private phase;
+    private phaseTicks;
+    private course;
+    private pending;
+    private dispatchingUnpaid;
+    private readonly lateStart;
+    private readonly earn;
+    private readonly achievements;
+    private readonly missions;
+    private readonly tracked;
+    private reached;
+    private readonly places;
+    private readonly times;
+    private readonly coins;
+    private readonly ready;
+    private announcement;
+    private announceN;
+    private upcomingAt;
+    private allDoneTick;
+    /** Run tick the round closes at once someone has finished (-1: nobody yet). */
+    private closeAt;
+    private readonly windowTicks;
+    private rng;
+    private readonly countdownTicks;
+    private readonly endTicks;
+    private readonly graceTicks;
+    private readonly limitTicks;
+    constructor(manifest: GameManifest, core: RaceCore, opts: {
+        readonly bots: number;
+        readonly roundSeconds: number | null;
+        readonly courses: number;
+        readonly seed: number;
+    } & RaceRunnerOptions);
+    private random;
+    private newRun;
+    private playerViews;
+    get phaseNow(): RacePhase;
+    get runNumber(): number;
+    get courseNow(): number;
+    placeOf(id: number): number | null;
+    /** Seats bots fill up to, with at least one person present; one change a tick. */
+    private fillSeats;
+    /** A player joined (room addPlayer): they race from the start, held if the countdown runs. */
+    joined(id: number): void;
+    left(id: number): void;
+    /** Call before each sim step: seats, systems, the clock, and every bot's input. */
+    beforeStep(inputs: Map<number, InputCommand>): void;
+    private humansPresent;
+    private record;
+    /** The round is over: "round.finished" for everyone present, then results. */
+    private closeRound;
+    /** Call after each sim step with its events. */
+    afterStep(sim: readonly RaceSimEvent[]): RaceStep;
+    private allReady;
+    private progress;
+    takeProgress(): RunProgress[];
+    /** A referee run starts for this player: counts start over; a run begun mid-race is not paid world progress. */
+    startRun(player: number): void;
+    count(player: number, event: string): number;
+    /** Live order: finished by place, then everyone else by progress (ties by id). */
+    standings(): number[];
+    /** Ticks until the round closes (the time limit, or the finish window once someone has finished), or null. */
+    private leftTicks;
+    info(): RaceInfo;
+}