@netforge/kit-play 0.0.0-stage → 0.2.0

package/dist/host/core.js

@@ -0,0 +1,247 @@
+// The local play host's authoritative loop: one world, a fixed tick, one
+// input queue per player and per-player delta snapshots, built only from
+// the engine's open netcode (@netforge/engine/net). It is written for
+// one computer: no lag compensation history (hitscans resolve against the
+// current hitboxes, which is exact at local latency), no run log, no
+// replay, and nothing that pays anyone.
+import { decodeInputPacket, DEFAULT_INPUT_QUEUE, encodeSnapshot, InputQueue, kindFieldIndices, quantizeEntity, SnapshotHistory, } from "@netforge/engine/net";
+export const SNAPSHOT_HZ = 20;
+/** Jitter-buffer depth for one-input-per-tick sims (the room server's default). */
+const ONE_PER_TICK_DEPTH = 2;
+/** Distance along a unit ray to a circle, or null. */
+export function rayCircle(ox, oy, ux, uy, cx, cy, r) {
+    const mx = ox - cx;
+    const my = oy - cy;
+    const b = mx * ux + my * uy;
+    const c = mx * mx + my * my - r * r;
+    if (c > 0 && b > 0)
+        return null;
+    const disc = b * b - c;
+    if (disc < 0)
+        return null;
+    const t = -b - Math.sqrt(disc);
+    return t < 0 ? 0 : t;
+}
+/** The nearest hitbox a hitscan meets that the shooter does not own, or null. */
+export function resolveHitscan(boxes, req) {
+    const len = Math.hypot(req.dx, req.dy);
+    if (len === 0)
+        return null;
+    const ux = req.dx / len;
+    const uy = req.dy / len;
+    let best = null;
+    let bestT = Infinity;
+    for (const h of boxes) {
+        if (h.owner === req.shooter)
+            continue;
+        const t = rayCircle(req.ox, req.oy, ux, uy, h.x, h.y, h.r);
+        if (t !== null && t <= req.range && t < bestT) {
+            bestT = t;
+            best = h;
+        }
+    }
+    return best;
+}
+export class LocalCore {
+    sim;
+    aoi;
+    worldRef;
+    tickN = 0;
+    snapAccum = 0;
+    conns = new Map();
+    rights = new Map();
+    nextPlayer = 1;
+    freeIds = [];
+    boxes = [];
+    constructor(sim, aoi, seed) {
+        this.sim = sim;
+        this.aoi = aoi;
+        this.worldRef = sim.createWorld(seed, "server");
+    }
+    get world() {
+        return this.worldRef;
+    }
+    get tick() {
+        return this.tickN;
+    }
+    get players() {
+        return [...this.conns.keys()];
+    }
+    addPlayer() {
+        const player = this.freeIds.shift() ?? this.nextPlayer++;
+        if (player > 0xffff)
+            throw new Error("player ids exhausted");
+        const entity = this.sim.addPlayer(this.worldRef, player);
+        this.conns.set(player, {
+            player,
+            entity,
+            queue: new InputQueue({
+                ...DEFAULT_INPUT_QUEUE,
+                maxCredits: Math.min(DEFAULT_INPUT_QUEUE.maxCredits, this.sim.maxInputsPerTick ?? Infinity),
+                ...(this.sim.maxInputsPerTick === 1 ? { targetDepth: ONE_PER_TICK_DEPTH } : {}),
+            }),
+            history: new SnapshotHistory(64),
+            ackTick: 0,
+        });
+        return { player, entity };
+    }
+    removePlayer(player) {
+        if (!this.conns.delete(player))
+            return;
+        this.rights.delete(player);
+        this.sim.removePlayer(this.worldRef, player);
+        this.freeIds.push(player);
+    }
+    setRights(player, rights) {
+        if (!this.conns.has(player))
+            return;
+        if (rights)
+            this.rights.set(player, rights);
+        else
+            this.rights.delete(player);
+    }
+    command(player, cmd) {
+        if (!this.sim.command || !this.conns.has(player))
+            return false;
+        return this.sim.command(this.worldRef, player, cmd);
+    }
+    startRun(player) {
+        if (this.conns.has(player))
+            this.sim.startRun?.(this.worldRef, player);
+    }
+    receiveInput(player, bytes) {
+        const c = this.conns.get(player);
+        if (!c)
+            return;
+        let pkt;
+        try {
+            pkt = decodeInputPacket(this.sim.input, bytes);
+        }
+        catch {
+            return;
+        }
+        if (pkt.ackTick > c.ackTick && pkt.ackTick <= this.tickN)
+            c.ackTick = pkt.ackTick;
+        else if (pkt.ackTick === 0)
+            c.ackTick = 0;
+        const rights = this.rights.get(player);
+        const restrict = this.sim.restrictInput;
+        c.queue.receive(rights && restrict ? pkt.commands.map((cmd) => ({ ...cmd, input: restrict.call(this.sim, cmd.input, rights) })) : pkt.commands);
+    }
+    step() {
+        this.tickN++;
+        const events = [];
+        const inputs = new Map();
+        for (const c of this.conns.values()) {
+            const list = [];
+            for (const cmd of c.queue.consume()) {
+                const req = this.sim.hitscans?.(this.worldRef, c.player, cmd.input) ?? null;
+                if (req && this.sim.applyHit) {
+                    const hit = resolveHitscan(this.boxes, req);
+                    if (hit)
+                        events.push(...this.sim.applyHit(this.worldRef, c.player, hit));
+                }
+                list.push(cmd.input);
+            }
+            inputs.set(c.player, list);
+        }
+        events.push(...this.sim.step(this.worldRef, inputs));
+        if (this.sim.hitboxes)
+            this.boxes = this.sim.hitboxes(this.worldRef);
+        this.snapAccum += SNAPSHOT_HZ / this.sim.tickHz;
+        let snapshots = new Map();
+        if (this.snapAccum >= 1) {
+            this.snapAccum -= 1;
+            snapshots = this.buildSnapshots();
+        }
+        return { tick: this.tickN, events, snapshots };
+    }
+    /** A fresh world at a run boundary; every player is re-added under the same id. Returns the new entity ids. */
+    rebase(seed) {
+        this.sim.disposeWorld?.(this.worldRef);
+        this.worldRef = this.sim.createWorld(seed, "server");
+        this.boxes = [];
+        const out = new Map();
+        for (const c of this.conns.values()) {
+            c.entity = this.sim.addPlayer(this.worldRef, c.player);
+            c.history = new SnapshotHistory(64);
+            c.ackTick = 0;
+            out.set(c.player, c.entity);
+        }
+        return out;
+    }
+    dispose() {
+        this.sim.disposeWorld?.(this.worldRef);
+    }
+    buildSnapshots() {
+        const schema = this.sim.schema;
+        const upw = schema.unitsPerWorld;
+        const states = this.sim.snapshot(this.worldRef);
+        const byId = new Map();
+        for (const s of states)
+            byId.set(s.id, s);
+        const packed = new Map();
+        const qOf = (s) => {
+            let q = packed.get(s.id);
+            if (!q) {
+                q = { id: s.id, kind: s.kind, owner: s.owner, q: quantizeEntity(schema, s, kindFieldIndices(schema, s.kind)) };
+                packed.set(s.id, q);
+            }
+            return q;
+        };
+        const { radius, maxEntities, kindCaps, alwaysKinds } = this.aoi;
+        const out = new Map();
+        for (const c of this.conns.values()) {
+            const self = byId.get(c.entity);
+            const visible = [];
+            if (self) {
+                const x = (self.values[schema.xField] ?? 0) / upw;
+                const y = (self.values[schema.yField] ?? 0) / upw;
+                const seen = new Set([self.id]);
+                visible.push(qOf(self));
+                if (alwaysKinds) {
+                    for (const e of states) {
+                        if (!seen.has(e.id) && alwaysKinds.includes(e.kind)) {
+                            seen.add(e.id);
+                            visible.push(qOf(e));
+                        }
+                    }
+                }
+                const near = [];
+                for (const e of states) {
+                    if (seen.has(e.id))
+                        continue;
+                    const dx = (e.values[schema.xField] ?? 0) / upw - x;
+                    const dy = (e.values[schema.yField] ?? 0) / upw - y;
+                    const d = dx * dx + dy * dy;
+                    if (d <= radius * radius)
+                        near.push({ e, d });
+                }
+                near.sort((a, b) => a.d - b.d);
+                const used = new Map();
+                for (const { e } of near) {
+                    if (visible.length >= maxEntities)
+                        break;
+                    const cap = kindCaps?.[e.kind];
+                    const n = used.get(e.kind) ?? 0;
+                    if (cap !== undefined && n >= cap)
+                        continue;
+                    used.set(e.kind, n + 1);
+                    visible.push(qOf(e));
+                }
+            }
+            const baseline = c.ackTick > 0 ? (c.history.get(c.ackTick) ?? null) : null;
+            const bytes = encodeSnapshot(schema, {
+                tick: this.tickN,
+                baselineTick: baseline ? c.ackTick : 0,
+                ackSeq: c.queue.lastAppliedSeq,
+                self: c.entity,
+                ...(this.sim.maxInputsPerTick === 1 ? { inputBuffer: c.queue.pending } : {}),
+            }, visible, baseline);
+            c.history.put(this.tickN, visible);
+            c.history.pruneBefore(c.ackTick);
+            out.set(c.player, bytes);
+        }
+        return out;
+    }
+}

package/dist/host/entry.d.ts

@@ -0,0 +1,20 @@
+import type { LocalAoi } from "./core.js";
+import { type RunningHost } from "./server.js";
+export interface EntryOptions {
+    readonly adapter: string;
+    readonly manifest: {
+        readonly fn: string;
+        readonly field?: "manifest";
+    };
+    readonly seats: number;
+    readonly aoi: LocalAoi;
+    readonly port: number;
+    readonly host: string;
+    readonly clientDir: string;
+    readonly libraryDir: string | null;
+}
+export declare function startHost(tpl: Readonly<Record<string, unknown>>, o: EntryOptions): Promise<RunningHost & {
+    readonly template: string;
+    readonly place: string;
+    readonly title: string;
+}>;

package/dist/host/entry.js

@@ -0,0 +1,37 @@
+// Starts the local host for one game module. `kit play` bundles this file
+// together with the template's src/manifest.ts (the creator's src/game.ts in
+// place of the template's), so the sim, the engine and the host share one
+// copy of every module, and imports the bundle.
+import { initSim } from "@netforge/engine-sim";
+import { profileSpec } from "@netforge/engine/game";
+import { LocalProfiles } from "./profile.js";
+import { startServer } from "./server.js";
+export async function startHost(tpl, o) {
+    await initSim();
+    const make = tpl[o.adapter];
+    const get = tpl[o.manifest.fn];
+    if (typeof make !== "function" || typeof get !== "function")
+        throw new Error(`the template does not export ${o.adapter} and ${o.manifest.fn}`);
+    const sim = make();
+    const got = get();
+    const manifest = (o.manifest.field ? got[o.manifest.field] : got);
+    const template = typeof tpl.TEMPLATE === "string" ? tpl.TEMPLATE : "";
+    const place = typeof tpl.PLACE === "string" ? tpl.PLACE : "local";
+    const spec = profileSpec(manifest);
+    const storeCommands = new Set();
+    for (const [id, s] of manifest.skus)
+        if (!s.grants && s.coins !== undefined)
+            storeCommands.add(id);
+    const gameName = typeof tpl.GAME_NAME === "string" ? tpl.GAME_NAME : template;
+    const running = await startServer({
+        sim,
+        template,
+        place,
+        instanceCap: o.seats,
+        aoi: o.aoi,
+        profile: spec,
+        profiles: new LocalProfiles(gameName, spec),
+        storeCommands,
+    }, { port: o.port, host: o.host, clientDir: o.clientDir, libraryDir: o.libraryDir });
+    return { ...running, template, place, title: gameName };
+}

package/dist/host/profile.d.ts

@@ -0,0 +1,29 @@
+import { type ProfileSpec } from "@netforge/engine/game";
+import type { GameProfile } from "@netforge/engine/net";
+export declare function isGuestId(v: unknown): v is string;
+export declare class LocalProfiles {
+    private readonly game;
+    private readonly spec;
+    private readonly now;
+    private readonly byId;
+    private readonly listeners;
+    constructor(game: string, spec: ProfileSpec | null, now?: () => number);
+    onChange(fn: (id: string) => void): () => void;
+    private saved;
+    private changed;
+    /** Keeper indices this profile may pick (null: the game has no keepers). */
+    keepers(id: string | null): number[] | null;
+    ownsCosmetic(id: string | null, value: number): boolean;
+    record(id: string, kind: "achievement" | "goal" | "title", item: string): void;
+    /** A permanent SKU bought with play money (POST /profile/redeem): the look or unlock is owned from now on. */
+    redeem(id: string, item: string): {
+        ok: boolean;
+        error?: string;
+    };
+    /** Meta upgrade levels owned (bought with play money). */
+    metaLevels(id: string | null): Readonly<Record<string, number>>;
+    settings(id: string, settings: unknown): void;
+    name(id: string, displayName: unknown): void;
+    view(id: string | null): GameProfile;
+    private store;
+}

package/dist/host/profile.js

@@ -0,0 +1,163 @@
+// Saved progress for local play, in memory only: achievements, goals and
+// titles the sim reports, the looks and unlocks bought with play money,
+// settings and a display name. Everything is gone when `kit play` stops.
+// Nothing here is a wallet, a balance or a claim.
+import { metaPrice, openKeepers, ownedCosmetics, todaysGoals, utcDay } from "@netforge/engine/game";
+const GUEST_RE = /^[A-Za-z0-9_-]{16,80}$/;
+export function isGuestId(v) {
+    return typeof v === "string" && GUEST_RE.test(v);
+}
+export class LocalProfiles {
+    game;
+    spec;
+    now;
+    byId = new Map();
+    listeners = new Set();
+    constructor(game, spec, now = Date.now) {
+        this.game = game;
+        this.spec = spec;
+        this.now = now;
+    }
+    onChange(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    saved(id) {
+        let s = this.byId.get(id);
+        if (!s) {
+            s = { achievements: new Map(), goals: new Map(), titles: new Map(), owned: new Set(), meta: {}, settings: {}, displayName: null };
+            this.byId.set(id, s);
+        }
+        return s;
+    }
+    changed(id) {
+        for (const fn of this.listeners)
+            fn(id);
+    }
+    /** Keeper indices this profile may pick (null: the game has no keepers). */
+    keepers(id) {
+        const spec = this.spec;
+        if (!spec || spec.keepers.length === 0)
+            return null;
+        const s = id ? this.saved(id) : null;
+        return openKeepers(spec, { achievements: s ? s.achievements.keys() : [], owned: s ? s.owned : [] });
+    }
+    ownsCosmetic(id, value) {
+        if (value === 0)
+            return true;
+        if (!this.spec || !id)
+            return false;
+        return ownedCosmetics(this.spec, this.saved(id).owned).includes(value);
+    }
+    record(id, kind, item) {
+        const s = this.saved(id);
+        if (kind === "achievement") {
+            if (s.achievements.has(item))
+                return;
+            s.achievements.set(item, this.now());
+        }
+        else if (kind === "goal") {
+            const day = utcDay(this.now());
+            const set = s.goals.get(day) ?? new Set();
+            if (set.has(item))
+                return;
+            set.add(item);
+            s.goals.set(day, set);
+        }
+        else {
+            s.titles.set(item, (s.titles.get(item) ?? 0) + 1);
+        }
+        this.changed(id);
+    }
+    /** A permanent SKU bought with play money (POST /profile/redeem): the look or unlock is owned from now on. */
+    redeem(id, item) {
+        const def = this.spec?.meta.get(item);
+        if (def) {
+            const s = this.saved(id);
+            const level = s.meta[item] ?? 0;
+            if (level >= def.levels)
+                return { ok: false, error: "at the top level" };
+            s.meta[item] = level + 1;
+            this.changed(id);
+            return { ok: true };
+        }
+        const sku = this.spec?.skus.get(item);
+        if (!sku)
+            return { ok: false, error: "no such item" };
+        const s = this.saved(id);
+        if (sku.kind === "consumable")
+            return { ok: false, error: "a run upgrade is bought in the run" };
+        s.owned.add(item);
+        this.changed(id);
+        return { ok: true };
+    }
+    /** Meta upgrade levels owned (bought with play money). */
+    metaLevels(id) {
+        return id ? { ...this.saved(id).meta } : {};
+    }
+    settings(id, settings) {
+        if (typeof settings !== "object" || settings === null || Array.isArray(settings))
+            return;
+        if (JSON.stringify(settings).length > 8192)
+            return;
+        this.saved(id).settings = { ...settings };
+        this.changed(id);
+    }
+    name(id, displayName) {
+        if (typeof displayName !== "string")
+            return;
+        const n = displayName.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, 24);
+        this.saved(id).displayName = n || null;
+        this.changed(id);
+    }
+    view(id) {
+        const spec = this.spec;
+        const day = utcDay(this.now());
+        const today = spec ? todaysGoals([...spec.missions.keys()], day) : [];
+        const s = id ? this.saved(id) : null;
+        const owned = s ? [...s.owned] : [];
+        const keeperIdx = this.keepers(id) ?? [];
+        return {
+            game: this.game,
+            kind: id ? "guest" : null,
+            wallet: null,
+            displayName: s?.displayName ?? null,
+            achievements: s ? [...s.achievements].map(([a, at]) => ({ id: a, at, source: "sim" })) : [],
+            keepers: spec ? keeperIdx.map((i) => spec.keepers[i]?.id ?? "").filter(Boolean) : [],
+            owned,
+            cosmetics: spec ? ownedCosmetics(spec, owned) : [0],
+            meta: s ? { ...s.meta } : {},
+            goals: { day, today, done: s ? [...(s.goals.get(day) ?? [])].filter((g) => today.includes(g)) : [] },
+            titles: s ? Object.fromEntries(s.titles) : {},
+            settings: s ? { ...s.settings } : {},
+            store: spec ? this.store(owned, s?.meta ?? {}) : [],
+            imported: false,
+            credit: 0,
+            totals: { achievements: s?.achievements.size ?? 0, titles: s ? [...s.titles.values()].reduce((a, b) => a + b, 0) : 0, games: s ? 1 : 0 },
+        };
+    }
+    store(owned, meta) {
+        const spec = this.spec;
+        if (!spec)
+            return [];
+        const have = new Set(owned);
+        const out = [];
+        for (const sku of spec.skus.values()) {
+            if (sku.kind === "consumable" || !sku.grants)
+                continue;
+            const g = sku.grants;
+            const mine = have.has(sku.id);
+            if ("cosmetic" in g)
+                out.push({ id: sku.id, kind: "cosmetic", coins: mine ? null : sku.coins, owned: mine, cosmetic: g.cosmetic });
+            else if ("keeper" in g)
+                out.push({ id: sku.id, kind: "unlock", coins: mine ? null : sku.coins, owned: mine, keeper: g.keeper });
+            else if ("gear" in g)
+                out.push({ id: sku.id, kind: "gear", coins: mine ? null : sku.coins, owned: mine, gear: g.gear, loseBelow: g.loseBelow });
+        }
+        for (const [id, def] of spec.meta) {
+            const level = meta[id] ?? 0;
+            out.push({ id, kind: "meta", coins: metaPrice(def, level), owned: level > 0, stat: def.stat, step: def.step, level, levels: def.levels, bonus: level * def.step });
+        }
+        return out;
+    }
+}

package/dist/host/room.d.ts

@@ -0,0 +1,37 @@
+import { Room, type Client } from "@colyseus/core";
+import { type ProfileSpec } from "@netforge/engine/game";
+import { type CreateOptions, type JoinOptions, type SimAdapter } from "@netforge/engine/net";
+import { type LocalAoi } from "./core.js";
+import { type LocalProfiles } from "./profile.js";
+/** What the host serves: one game, set once before the server listens. */
+export interface LocalGame {
+    readonly sim: SimAdapter<unknown, unknown>;
+    readonly template: string;
+    readonly place: string;
+    readonly instanceCap: number;
+    readonly aoi: LocalAoi;
+    readonly profile: ProfileSpec | null;
+    readonly profiles: LocalProfiles;
+    /** SKU ids the store sells for coins (play money here): the only commands a client may send. */
+    readonly storeCommands: ReadonlySet<string>;
+}
+export declare function setLocalGame(g: LocalGame): void;
+/** Why local play turns these down, in the words the client shows. */
+export declare const LOCAL_ONLY = "Local play uses play money only";
+export declare class LocalRoom extends Room {
+    private core;
+    private g;
+    private readonly seats;
+    private readonly clients_;
+    private unsubscribe;
+    onCreate(options: CreateOptions): void;
+    onJoin(client: Client, options?: JoinOptions): void;
+    onLeave(client: Client): void;
+    onDispose(): void;
+    private applyProfile;
+    private sendInfo;
+    private recordProgress;
+    private tickOnce;
+    /** The sim ended a run: a fresh world, as the hosted room does between runs. Players stay connected. */
+    private newRun;
+}