@netforge/engine 0.0.0-stage → 0.1.0

package/dist/net/room-client.js

@@ -0,0 +1,144 @@
+// Browser and Node client for a room: asks the world service for a seat,
+// connects, and wires the Colyseus room to a NetClient. Used by the Vite
+// demo and the headless load bots.
+import { Client } from '@colyseus/sdk';
+import { DEFAULT_CLIENT, NetClient } from './client.js';
+import { MSG_INPUT, MSG_SNAPSHOT, } from './protocol.js';
+export async function joinRoom(sim, p) {
+    const res = await fetch(`${p.endpoint}/world/join`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            place: p.place,
+            template: p.template,
+            ...(p.wallet ? { wallet: p.wallet } : {}),
+            ...(p.session ? { session: p.session } : {}),
+            ...(p.guest ? { guest: p.guest } : {}),
+            ...(p.friendRoomId ? { friendRoomId: p.friendRoomId } : {}),
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`world/join ${res.status}: ${await res.text()}`);
+    const body = (await res.json());
+    const reservation = body.reservations[0];
+    if (!reservation)
+        throw new Error('no reservation');
+    return connectReservation(sim, p.endpoint, reservation);
+}
+export async function connectReservation(sim, endpoint, reservation) {
+    const client = new Client(endpoint);
+    const room = await client.consumeSeatReservation(reservation);
+    let bytes = 0;
+    let msgs = 0;
+    const early = [];
+    let net = null;
+    room.onMessage(MSG_SNAPSHOT, (payload) => {
+        bytes += payload.length;
+        msgs++;
+        if (net)
+            net.receiveSnapshot(payload, performance.now());
+        else
+            early.push(payload);
+    });
+    const earnCbs = [];
+    room.onMessage('earn', (e) => earnCbs.forEach((cb) => cb(e)));
+    let run = null;
+    const runCbs = [];
+    room.onMessage('run', (info) => {
+        run = info;
+        runCbs.forEach((cb) => cb(info));
+    });
+    const runIdCbs = [];
+    room.onMessage('run-id', (m) => runIdCbs.forEach((cb) => cb(m)));
+    const rebaseCbs = [];
+    room.onMessage('rebase', (m) => {
+        // Same player, possibly a new entity; seqs continue (the server's queue ignores old ones).
+        if (net)
+            net = new NetClient(sim, net.player, m.entity, (b) => room.sendBytes(MSG_INPUT, b), { ...DEFAULT_CLIENT, firstSeq: net.nextSeq });
+        rebaseCbs.forEach((cb) => cb(m));
+    });
+    let profile = null;
+    const profileCbs = [];
+    room.onMessage('profile', (p) => {
+        profile = p;
+        profileCbs.forEach((cb) => cb(p));
+    });
+    let stakeMsg = null;
+    const stakeCbs = [];
+    room.onMessage('stake', (m) => {
+        stakeMsg = m;
+        stakeCbs.forEach((cb) => cb(m));
+    });
+    let potMsg = null;
+    const potCbs = [];
+    room.onMessage('pot', (m) => {
+        potMsg = m;
+        potCbs.forEach((cb) => cb(m));
+    });
+    const signIns = [];
+    room.onMessage('sign-in-result', (r) => signIns.shift()?.(r));
+    const pending = [];
+    room.onMessage('command-result', (r) => pending.shift()?.(r));
+    room.onMessage('pong', () => undefined);
+    const welcome = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('no welcome')), 5000);
+        room.onMessage('welcome', (w) => {
+            clearTimeout(timer);
+            resolve(w);
+        });
+    });
+    const nc = new NetClient(sim, welcome.player, welcome.entity, (b) => room.sendBytes(MSG_INPUT, b));
+    net = nc;
+    for (const b of early)
+        nc.receiveSnapshot(b, performance.now());
+    return {
+        room,
+        get net() {
+            return net ?? nc;
+        },
+        welcome,
+        roomId: room.roomId,
+        bytesIn: () => bytes,
+        messagesIn: () => msgs,
+        onEarn: (cb) => earnCbs.push(cb),
+        onRun: (cb) => runCbs.push(cb),
+        latestRun: () => run,
+        onRunId: (cb) => runIdCbs.push(cb),
+        onRebase: (cb) => rebaseCbs.push(cb),
+        signIn: (session) => new Promise((resolve) => {
+            signIns.push(resolve);
+            room.send('sign-in', { session });
+        }),
+        onProfile: (cb) => {
+            profileCbs.push(cb);
+            if (profile)
+                cb(profile);
+        },
+        latestProfile: () => profile,
+        stake: (amount) => room.send('stake', amount !== undefined ? { amount } : {}),
+        onStake: (cb) => {
+            stakeCbs.push(cb);
+            if (stakeMsg)
+                cb(stakeMsg);
+        },
+        latestStake: () => stakeMsg,
+        pot: () => room.send('pot', {}),
+        onPot: (cb) => {
+            potCbs.push(cb);
+            if (potMsg)
+                cb(potMsg);
+        },
+        command: (cmd) => new Promise((resolve) => {
+            pending.push(resolve);
+            room.send('command', cmd);
+        }),
+        claim: () => new Promise((resolve) => {
+            room.onMessage('attest', resolve);
+            room.onMessage('attest-error', resolve);
+            room.send('claim');
+        }),
+        leave: async () => {
+            await room.leave(true);
+        },
+    };
+}

package/dist/net/schema.d.ts

@@ -0,0 +1,78 @@
+export type FieldSpec = 
+/** Integer in [0, 2^bits). Positions in fixed-point sub-units use this. */
+{
+    readonly name: string;
+    readonly kind: 'uint';
+    readonly bits: number;
+    readonly interp?: Interp;
+    readonly deltaBits?: number;
+}
+/** Signed integer, zigzag-packed in `bits` bits. */
+ | {
+    readonly name: string;
+    readonly kind: 'int';
+    readonly bits: number;
+    readonly interp?: Interp;
+    readonly deltaBits?: number;
+}
+/** Float quantized linearly into [min, max] with `bits` bits of precision. */
+ | {
+    readonly name: string;
+    readonly kind: 'quant';
+    readonly min: number;
+    readonly max: number;
+    readonly bits: number;
+    readonly interp?: Interp;
+    readonly deltaBits?: number;
+}
+/** Angle in radians packed into 16 bits (0..2π). Interpolates the short way. */
+ | {
+    readonly name: string;
+    readonly kind: 'angle16';
+    readonly deltaBits?: number;
+}
+/** One bit. Never interpolated. */
+ | {
+    readonly name: string;
+    readonly kind: 'bool';
+};
+export type Interp = 'lerp' | 'step';
+export interface EntitySchema {
+    readonly fields: readonly FieldSpec[];
+    /** Index of the field holding x, used by area-of-interest and rewind. */
+    readonly xField: number;
+    /** Index of the field holding y. */
+    readonly yField: number;
+    /** Units of x/y per world unit (e.g. 32 for 1/32 fixed point). */
+    readonly unitsPerWorld: number;
+    /**
+     * Optional per-kind field subsets, ascending field indices. An entity of a
+     * listed kind carries only those fields on the wire (its change mask is
+     * that many bits) and decodes with the rest as 0. Crowds of simple
+     * entities (2,000 enemies) cost a few bits each this way. At most 32 per kind.
+     */
+    readonly kindFields?: Readonly<Record<number, readonly number[]>>;
+}
+/** One entity as the sim reports it: values are real (dequantized) numbers. */
+export interface EntityState {
+    readonly id: number;
+    readonly kind: number;
+    /** Player id that owns it, 0 for none. */
+    readonly owner: number;
+    readonly values: readonly number[];
+}
+export declare function fieldBits(f: FieldSpec): number;
+/** Default bit width for a "small change" delta of a field, or 0 for none. */
+export declare function fieldDeltaBits(f: FieldSpec): number;
+/** Real value to the integer the wire carries. */
+export declare function quantize(f: FieldSpec, v: number): number;
+/** Wire integer back to the real value. */
+export declare function dequantize(f: FieldSpec, q: number): number;
+/** Interpolate one field between a and b (real values). */
+export declare function interpolateField(f: FieldSpec, a: number, b: number, t: number): number;
+/**
+ * Quantize an entity's values. With `only` (the kind's wire fields), the
+ * other fields are left 0: they never go on the wire for that kind.
+ */
+export declare function quantizeEntity(schema: EntitySchema, e: EntityState, only?: readonly number[]): number[];
+export declare function dequantizeValues(schema: EntitySchema, q: readonly number[]): number[];

package/dist/net/schema.js

@@ -0,0 +1,121 @@
+// Per-entity field schema: how each networked value is quantized, packed and
+// interpolated. A game (via its SimAdapter) declares one schema; the snapshot
+// codec, the interpolation buffer and area-of-interest all read it.
+const TWO_PI = Math.PI * 2;
+export function fieldBits(f) {
+    switch (f.kind) {
+        case 'uint':
+        case 'int':
+        case 'quant':
+            return f.bits;
+        case 'angle16':
+            return 16;
+        case 'bool':
+            return 1;
+    }
+}
+/** Default bit width for a "small change" delta of a field, or 0 for none. */
+export function fieldDeltaBits(f) {
+    if (f.kind === 'bool')
+        return 0;
+    if (f.deltaBits !== undefined)
+        return f.deltaBits;
+    const b = fieldBits(f);
+    return b >= 8 ? Math.max(4, Math.ceil(b / 2)) : 0;
+}
+/** Real value to the integer the wire carries. */
+export function quantize(f, v) {
+    switch (f.kind) {
+        case 'uint': {
+            const max = 2 ** f.bits - 1;
+            return clamp(Math.round(v), 0, max);
+        }
+        case 'int': {
+            const lim = 2 ** (f.bits - 1);
+            return clamp(Math.round(v), -lim, lim - 1);
+        }
+        case 'quant': {
+            const steps = 2 ** f.bits - 1;
+            const t = (clamp(v, f.min, f.max) - f.min) / (f.max - f.min);
+            return Math.round(t * steps);
+        }
+        case 'angle16': {
+            const a = ((v % TWO_PI) + TWO_PI) % TWO_PI;
+            return Math.round((a / TWO_PI) * 65536) & 0xffff;
+        }
+        case 'bool':
+            return v ? 1 : 0;
+    }
+}
+/** Wire integer back to the real value. */
+export function dequantize(f, q) {
+    switch (f.kind) {
+        case 'uint':
+        case 'int':
+        case 'bool':
+            return q;
+        case 'quant': {
+            const steps = 2 ** f.bits - 1;
+            return f.min + (q / steps) * (f.max - f.min);
+        }
+        case 'angle16':
+            return (q / 65536) * TWO_PI;
+    }
+}
+/** Interpolate one field between a and b (real values). */
+export function interpolateField(f, a, b, t) {
+    switch (f.kind) {
+        case 'bool':
+            return t < 1 ? a : b;
+        case 'angle16': {
+            let d = (b - a) % TWO_PI;
+            if (d > Math.PI)
+                d -= TWO_PI;
+            if (d < -Math.PI)
+                d += TWO_PI;
+            return a + d * t;
+        }
+        default:
+            if (f.interp === 'step')
+                return t < 1 ? a : b;
+            return a + (b - a) * t;
+    }
+}
+/**
+ * Quantize an entity's values. With `only` (the kind's wire fields), the
+ * other fields are left 0: they never go on the wire for that kind.
+ */
+export function quantizeEntity(schema, e, only) {
+    const n = schema.fields.length;
+    if (only && only.length < n) {
+        const out = new Array(n).fill(0);
+        for (const i of only) {
+            const f = schema.fields[i];
+            if (f === undefined)
+                throw new Error('schema field missing');
+            out[i] = quantize(f, e.values[i] ?? 0);
+        }
+        return out;
+    }
+    const out = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const f = schema.fields[i];
+        if (f === undefined)
+            throw new Error('schema field missing');
+        out[i] = quantize(f, e.values[i] ?? 0);
+    }
+    return out;
+}
+export function dequantizeValues(schema, q) {
+    const out = new Array(schema.fields.length);
+    for (let i = 0; i < schema.fields.length; i++) {
+        const f = schema.fields[i];
+        if (f === undefined)
+            throw new Error('schema field missing');
+        out[i] = dequantize(f, q[i] ?? 0);
+    }
+    return out;
+}
+function clamp(v, lo, hi) {
+    return v < lo ? lo : v > hi ? hi : v;
+}

package/dist/net/sim-adapter.d.ts

@@ -0,0 +1,134 @@
+import type { BitReader, BitWriter } from './bits.js';
+import type { EntitySchema, EntityState } from './schema.js';
+/** Small integer assigned by the room to each connected player (1..65535). */
+export type PlayerId = number;
+export interface InputCodec<I> {
+    write(w: BitWriter, input: I): void;
+    read(r: BitReader): I;
+    /** The input a player is assumed to send when idle. */
+    readonly idle: I;
+}
+/** Something the authoritative sim says a player earned. */
+export interface EarnEvent {
+    readonly type: 'earn';
+    readonly player: PlayerId;
+    /** Earn rule name, as declared in the game's earn rules. */
+    readonly rule: string;
+    /** Units earned (the referee converts units to token amount per rule). */
+    readonly units: number;
+}
+/** The sim started a fresh run in place (game over or victory screen ended). Referee runs restart. */
+export interface RunResetEvent {
+    readonly type: 'run.reset';
+}
+/**
+ * The sim says a player reached something their profile keeps: an achievement, one of today's goals,
+ * or an end-screen title. The room writes it to the player's profile on
+ * the server; the browser never grants these.
+ */
+export interface ProgressEvent {
+    readonly type: 'progress';
+    readonly player: PlayerId;
+    readonly kind: 'achievement' | 'goal' | 'title';
+    /** The declared achievement, mission or title id. */
+    readonly id: string;
+}
+export type SimEvent = EarnEvent | RunResetEvent | ProgressEvent;
+/** What a player's profile lets them choose (the room checks it on every input). */
+export interface PlayerRights {
+    /** Keeper indices this player may pick; null when the game has no keepers. */
+    readonly keepers: readonly number[] | null;
+}
+/** A room-level command from a player (store hooks): a paid revive, a cosmetic. */
+export interface SimCommand {
+    readonly name: string;
+    readonly value?: number;
+}
+/** A hitscan the sim wants resolved against lag-compensated hitboxes. */
+export interface HitscanRequest {
+    readonly shooter: PlayerId;
+    readonly ox: number;
+    readonly oy: number;
+    readonly dx: number;
+    readonly dy: number;
+    readonly range: number;
+}
+export interface Hitbox {
+    readonly entity: number;
+    readonly owner: PlayerId;
+    readonly x: number;
+    readonly y: number;
+    readonly r: number;
+}
+export interface SimAdapter<W, I> {
+    readonly name: string;
+    /** Content version of the logic module (hot swap compares these). */
+    readonly version: string;
+    readonly tickHz: number;
+    readonly schema: EntitySchema;
+    readonly input: InputCodec<I>;
+    /**
+     * Most inputs one player may apply in one tick. Omit for "drain" sims
+     * where each input is one tick of motion and catching up after a stall is
+     * exact (the movers test sim). Set 1 for physics sims whose state moves
+     * without input (engine-sim: `step(world, Map<PlayerId, InputCommand>)`
+     * takes exactly one command per player per tick).
+     */
+    readonly maxInputsPerTick?: number;
+    /**
+     * A fresh world. The server's is authoritative ('server'); the client's
+     * ('client') holds only what it predicts, so it must not spawn world
+     * entities of its own.
+     */
+    createWorld(seed: number, role: 'server' | 'client'): W;
+    /** Spawns the player's entity, returns its entity id. */
+    addPlayer(world: W, player: PlayerId): number;
+    removePlayer(world: W, player: PlayerId): void;
+    /** Advances one tick. Inputs per player are applied in order. */
+    step(world: W, inputsByPlayer: ReadonlyMap<PlayerId, readonly I[]>): readonly SimEvent[];
+    /** Every networked entity, real values in schema field order. */
+    snapshot(world: W): readonly EntityState[];
+    /**
+     * Overwrites world entities with these states (creating any missing).
+     * The client uses it to reset its predicted entity to the server's state.
+     */
+    applySnapshot(world: W, entities: readonly EntityState[]): void;
+    /** Lag compensation hook: hitscans requested by this tick's inputs. */
+    hitscans?(world: W, player: PlayerId, input: I): HitscanRequest | null;
+    /** Current hitboxes, recorded each tick into the rewind buffer. */
+    hitboxes?(world: W): readonly Hitbox[];
+    /** Resolution of a lag-compensated hitscan; may emit earn events. */
+    applyHit?(world: W, shooter: PlayerId, target: Hitbox): readonly SimEvent[];
+    /**
+     * Run state for the room to broadcast a few times a second (JSON-safe):
+     * phase, timer, wave, boss health. Kept out of snapshots on purpose.
+     */
+    info?(world: W): unknown;
+    /**
+     * Run state for one player (JSON-safe), sent to that player only, in
+     * place of `info`: what only they may see (a hand of cards, their own
+     * gold). A sim with hidden information implements this and keeps every
+     * secret out of `snapshot` and `info`. The room sends it when it changed.
+     */
+    infoFor?(world: W, player: PlayerId): unknown;
+    /** Ticks between run-state sends (default: the room's, 2 Hz at 30 Hz). Board games send more often. */
+    readonly infoEveryTicks?: number;
+    /**
+     * Rewrites an input so it chooses only what the player's profile allows
+     * (a locked keeper becomes the first open one). The room applies it as
+     * inputs arrive, before they are recorded, so a replay sees the same.
+     */
+    restrictInput?(input: I, rights: PlayerRights): I;
+    /** Apply a room-level command (already verified by the room). Returns false if it did nothing. */
+    command?(world: W, player: PlayerId, cmd: SimCommand): boolean;
+    /**
+     * A referee run starts for this player now (sign-in, or a new round): the
+     * player's earn progress starts over, so a run is paid only for what it
+     * did itself (never for counts made as a guest or in an earlier run). The
+     * room records it in the run log, so a replay applies it at the same
+     * point. Optional: a sim without earn progress leaves it out.
+     */
+    startRun?(world: W, player: PlayerId): void;
+    /** Free native memory (Rapier) when the room disposes. */
+    disposeWorld?(world: W): void;
+}

package/dist/net/sim-adapter.js

@@ -0,0 +1,22 @@
+// The narrow seam between the netcode and a game's simulation.
+//
+// The room server and the client both drive a SimAdapter: the server steps
+// the authoritative world, the client steps a local copy that holds only its
+// own predicted entity. Until `@netforge/engine-sim` lands on main, the
+// room runs the built-in test sim (`src/sim/movers.ts`) behind this
+// interface; swapping in the shared sim is a change to `src/sim/index.ts`.
+//
+// Contract the netcode relies on (and the engine-sim adapter must keep):
+//
+//   1. Each input command is ONE tick of the owning player's motion. `step`
+//      applies a player's queued inputs in order, then runs world systems
+//      once. A player with no input this tick does not move by input.
+//   2. A player's own predicted fields depend only on that player's inputs
+//      and on static world state, so replaying unacknowledged inputs on top
+//      of the server's state reproduces the server exactly (reconciliation
+//      converges to zero error). Interactions that break this (being pushed
+//      by others) are corrected by the next snapshot and smoothed.
+//   3. `snapshot` values are real numbers; the schema quantizes them. A sim
+//      that keeps its state on the quantization grid (fixed-point) gets
+//      bit-exact prediction.
+export {};

package/dist/net/snapshot.d.ts

@@ -0,0 +1,61 @@
+import { type EntitySchema } from './schema.js';
+/** One entity on the wire, values already quantized. */
+export interface QEntity {
+    readonly id: number;
+    readonly kind: number;
+    readonly owner: number;
+    readonly q: readonly number[];
+}
+export interface SnapshotHeader {
+    /** Server tick this snapshot describes. */
+    readonly tick: number;
+    /** Tick of the baseline it was encoded against; 0 means full. */
+    readonly baselineTick: number;
+    /** Highest input sequence number the server has applied for this client. */
+    readonly ackSeq: number;
+    /** The receiving player's own entity id (0 if none). */
+    readonly self: number;
+    /**
+     * Inputs waiting in the server's queue for this client after this tick
+     * (one-input-per-tick sims). The client speeds up or slows its input clock
+     * to hold it near a small target. Absent from older encoders.
+     */
+    readonly inputBuffer?: number;
+}
+export interface DecodedSnapshot {
+    readonly header: SnapshotHeader;
+    /** The FULL reconstructed entity set for this tick (baseline + delta). */
+    readonly entities: ReadonlyMap<number, QEntity>;
+    /** Ids that were in the baseline and are gone now. */
+    readonly removed: readonly number[];
+}
+export declare class BaselineMissingError extends Error {
+    readonly baselineTick: number;
+    constructor(baselineTick: number);
+}
+/**
+ * Encodes `current` (any order) against `baseline` (null for a full snapshot).
+ */
+export declare function encodeSnapshot(schema: EntitySchema, header: SnapshotHeader, current: readonly QEntity[], baseline: ReadonlyMap<number, QEntity> | null): Uint8Array;
+/**
+ * Decodes a snapshot. `baselineFor` returns the client's stored entity set
+ * for a tick it previously decoded.
+ */
+export declare function decodeSnapshot(schema: EntitySchema, bytes: Uint8Array, baselineFor: (tick: number) => ReadonlyMap<number, QEntity> | undefined): DecodedSnapshot;
+/**
+ * Per-client history of what was sent, keyed by tick, so the next snapshot
+ * can be encoded against whatever the client last acked.
+ */
+export declare class SnapshotHistory {
+    private readonly capacity;
+    private readonly byTick;
+    private readonly order;
+    constructor(capacity?: number);
+    put(tick: number, entities: readonly QEntity[] | ReadonlyMap<number, QEntity>): void;
+    get(tick: number): ReadonlyMap<number, QEntity> | undefined;
+    /** Drop entries older than `tick` (they can never be a baseline again). */
+    pruneBefore(tick: number): void;
+    get size(): number;
+}
+/** Field indices carried on the wire for an entity kind (all fields unless the schema narrows that kind). */
+export declare function kindFieldIndices(schema: EntitySchema, kind: number): readonly number[];