@netforge/kit-play 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NetNet Capital Management
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,13 @@
+@netforge/kit-play
+Copyright (c) 2026 NetNet Capital Management
+
+Dependencies (unmodified, via npm)
+- @colyseus/core 0.18.18 and @colyseus/ws-transport 0.18.4 (https://github.com/colyseus/colyseus), MIT, Endel Dreyer.
+- vite 6.4.3 (https://github.com/vitejs/vite), MIT.
+- esbuild 0.25.12 (https://github.com/evanw/esbuild), MIT.
+- The Net Forge engine packages (@netforge/engine, -sim, asset-library,
+  asset-library-files, tabletop, template-*); see each package's NOTICE.
+
+The local host (src/host) is written for this package on the engine's open
+netcode (@netforge/engine/net). It holds no code from the hosted room
+server or the referee.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @netforge/kit-play
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`kit play` runs a game you downloaded from Net Forge on your own computer,
+with play money.
+
+```sh
+cd my-game          # the folder from the Source download (netnet.json, src/game.ts)
+npm install         # its package.json lists the engine and kit-play
+npx kit play        # or: npm run play
+```
+
+It builds the template's browser client with your `src/game.ts` and
+`src/names.json` in place, starts a local room host for the same game
+module, and opens `http://127.0.0.1:4663`. Open the link in more tabs or
+windows for more players.
+
+| Flag | Default | |
+|---|---|---|
+| `--port <n>` | 4663 | the page and the room, one port |
+| `--host <addr>` | 127.0.0.1 | `0.0.0.0` lets devices on your network join |
+| `--players <n>` | 1 | browser tabs to open |
+| `--no-open` | | print the link only |
+| `--library-url <url>` | the installed library | load models and sounds from a mirror instead |
+
+## What it does not do
+
+- No wallet, no chain, no real tokens. Coins are play money in the page.
+- No calls to Net Forge servers. The page is built with no `VITE_*`
+  environment and talks only to the local host; sign-in, the referee and
+  every money route answer 403.
+- No stakes, pots or claims. Earn rules still fire, so you can see them,
+  and pay nothing.
+
+The local host is built from the engine's open simulation
+(`@netforge/engine`, `@netforge/engine-sim`). The hosted room
+server and the referee that decides real payouts are not part of it.
+Progress (achievements, looks bought with play money) lives in memory and
+is gone when `kit play` stops.
+
+kit play is not a sandbox: it runs the game's code (the room host in Node,
+the client in your browser) with your permissions. Play only games whose
+code you trust, as with any program you run.
+
+`src/game.ts` may import only `@netforge/engine`, as in the studio, so
+a game that plays here plays there. Send changes back with `/agent` in the
+studio (see your game's README).
+
+The build lands in `.netnet/play/` inside the game folder.

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export declare const HELP = "kit play: run a Net Forge game on this computer with play money.\n\nUsage: kit play [dir] [flags]     (inside the folder you downloaded from Net Forge)\n\n  --port <n>          Port for the page and the local room (default 4663).\n  --host <addr>       Interface to listen on (default 127.0.0.1, this computer only).\n                      Use 0.0.0.0 to let devices on your network join.\n  --players <n>       Browser tabs to open, one per local player (default 1).\n  --no-open           Print the link instead of opening a browser.\n  --library-url <u>   Load the asset library from this URL instead of the installed copy.\n\nNo wallet, no chain, no Net Forge servers: coins are play money and nothing pays out.\nkit play runs the game's own code on this computer with your permissions (it is not a\nsandbox): play only games whose code you trust.";
+export interface PlayCliIo {
+    out(s: string): void;
+    err(s: string): void;
+    cwd: string;
+}
+export declare function runPlayCli(argv: readonly string[], io: PlayCliIo): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// kit-play [dir] [--port 4663] [--host 127.0.0.1] [--players 1] [--no-open] [--library-url <url>]
+// Also reached as `kit play` through @netforge/kit.
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { play, PlayError } from "./play.js";
+export const HELP = `kit play: run a Net Forge game on this computer with play money.
+
+Usage: kit play [dir] [flags]     (inside the folder you downloaded from Net Forge)
+
+  --port <n>          Port for the page and the local room (default 4663).
+  --host <addr>       Interface to listen on (default 127.0.0.1, this computer only).
+                      Use 0.0.0.0 to let devices on your network join.
+  --players <n>       Browser tabs to open, one per local player (default 1).
+  --no-open           Print the link instead of opening a browser.
+  --library-url <u>   Load the asset library from this URL instead of the installed copy.
+
+No wallet, no chain, no Net Forge servers: coins are play money and nothing pays out.
+kit play runs the game's own code on this computer with your permissions (it is not a
+sandbox): play only games whose code you trust.`;
+export async function runPlayCli(argv, io) {
+    const flags = new Map();
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a.startsWith("--")) {
+            const [k, v] = a.slice(2).split("=", 2);
+            const next = argv[i + 1];
+            if (v !== undefined)
+                flags.set(k, v);
+            else if (k !== "no-open" && k !== "help" && next !== undefined && !next.startsWith("--"))
+                flags.set(k, argv[++i] ?? "");
+            else
+                flags.set(k, true);
+        }
+        else if (a === "-h")
+            flags.set("help", true);
+        else
+            positional.push(a);
+    }
+    if (flags.has("help")) {
+        io.out(HELP);
+        return 0;
+    }
+    const num = (k, d, min, max) => {
+        const v = flags.get(k);
+        if (v === undefined)
+            return d;
+        const n = Number(v);
+        if (!Number.isInteger(n) || n < min || n > max)
+            throw new PlayError(`--${k} must be a whole number from ${min} to ${max}`);
+        return n;
+    };
+    try {
+        const lib = flags.get("library-url");
+        if (lib !== undefined && (typeof lib !== "string" || !/^https?:\/\/[^\s]+$/.test(lib)))
+            throw new PlayError("--library-url must be an http(s) URL");
+        const host = flags.get("host");
+        const playing = await play({
+            dir: positional[0] ?? io.cwd,
+            port: num("port", 4663, 1, 65535),
+            host: typeof host === "string" && host.length > 0 ? host : "127.0.0.1",
+            open: !flags.has("no-open"),
+            players: num("players", 1, 1, 16),
+            libraryUrl: typeof lib === "string" ? lib.replace(/\/$/, "") : null,
+            log: io.out,
+        });
+        await new Promise((done) => {
+            const stop = () => {
+                void playing.close().finally(done);
+            };
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+        });
+        return 0;
+    }
+    catch (e) {
+        io.err(e instanceof PlayError ? e.message : e instanceof Error ? (e.stack ?? e.message) : String(e));
+        return 1;
+    }
+}
+const isMain = (() => {
+    try {
+        return process.argv[1] !== undefined && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+})();
+if (isMain) {
+    const code = await runPlayCli(process.argv.slice(2), { out: (s) => console.log(s), err: (s) => console.error(s), cwd: process.cwd() });
+    process.exit(code);
+}

package/dist/host/core.d.ts

@@ -0,0 +1,50 @@
+import { type Hitbox, type HitscanRequest, type PlayerId, type PlayerRights, type SimAdapter, type SimCommand, type SimEvent } from "@netforge/engine/net";
+/** What each player is sent: everything within `radius` of them (world units), nearest first, up to the caps. */
+export interface LocalAoi {
+    readonly radius: number;
+    readonly maxEntities: number;
+    /** Most entities of one kind (EntityKind number) a snapshot carries. */
+    readonly kindCaps?: Readonly<Record<number, number>>;
+    /** Kinds every player always receives (players, so the HUD sees teammates). */
+    readonly alwaysKinds?: readonly number[];
+}
+export declare const SNAPSHOT_HZ = 20;
+export interface LocalTick {
+    readonly tick: number;
+    readonly events: readonly SimEvent[];
+    readonly snapshots: ReadonlyMap<PlayerId, Uint8Array>;
+}
+/** Distance along a unit ray to a circle, or null. */
+export declare function rayCircle(ox: number, oy: number, ux: number, uy: number, cx: number, cy: number, r: number): number | null;
+/** The nearest hitbox a hitscan meets that the shooter does not own, or null. */
+export declare function resolveHitscan(boxes: readonly Hitbox[], req: HitscanRequest): Hitbox | null;
+export declare class LocalCore<W, I> {
+    private readonly sim;
+    private readonly aoi;
+    private worldRef;
+    private tickN;
+    private snapAccum;
+    private readonly conns;
+    private readonly rights;
+    private nextPlayer;
+    private readonly freeIds;
+    private boxes;
+    constructor(sim: SimAdapter<W, I>, aoi: LocalAoi, seed: number);
+    get world(): W;
+    get tick(): number;
+    get players(): PlayerId[];
+    addPlayer(): {
+        player: PlayerId;
+        entity: number;
+    };
+    removePlayer(player: PlayerId): void;
+    setRights(player: PlayerId, rights: PlayerRights | null): void;
+    command(player: PlayerId, cmd: SimCommand): boolean;
+    startRun(player: PlayerId): void;
+    receiveInput(player: PlayerId, bytes: Uint8Array): void;
+    step(): LocalTick;
+    /** A fresh world at a run boundary; every player is re-added under the same id. Returns the new entity ids. */
+    rebase(seed: number): Map<PlayerId, number>;
+    dispose(): void;
+    private buildSnapshots;
+}

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;
+}