@netforge/engine 0.0.0-stage → 0.1.0

package/dist/net/client.js

@@ -0,0 +1,151 @@
+// Transport-agnostic game client: decodes snapshots, predicts the local
+// player, interpolates everyone else, and builds input packets. The browser
+// demo, the headless load bots and the netcode tests all drive this class;
+// the Colyseus wiring is only `send` and `receiveSnapshot`.
+import { encodeInputPacket, REDUNDANCY } from './input.js';
+import { InterpolationBuffer, ServerClock } from './interpolation.js';
+import { Predictor } from './prediction.js';
+import { dequantizeValues } from './schema.js';
+import { BaselineMissingError, decodeSnapshot, SnapshotHistory } from './snapshot.js';
+export const DEFAULT_CLIENT = { interpDelayMs: 100, inputBufferTarget: 2 };
+export class NetClient {
+    sim;
+    player;
+    selfEntity;
+    send;
+    opts;
+    history = new SnapshotHistory(64);
+    interp;
+    clock;
+    predictor;
+    latestTick = 0;
+    latestSelf;
+    lastRenderMs = 0;
+    tickMs;
+    /** Smoothed server input-queue depth from snapshot headers; null until reported. */
+    serverBuffer = null;
+    stats = {
+        snapshots: 0,
+        snapshotBytes: 0,
+        inputPackets: 0,
+        inputBytes: 0,
+        baselineMisses: 0,
+        staleSnapshots: 0,
+    };
+    constructor(sim, player, selfEntity, send, opts = DEFAULT_CLIENT) {
+        this.sim = sim;
+        this.player = player;
+        this.selfEntity = selfEntity;
+        this.send = send;
+        this.opts = opts;
+        this.tickMs = 1000 / sim.tickHz;
+        this.interp = new InterpolationBuffer(sim.schema);
+        this.clock = new ServerClock(this.tickMs);
+        this.predictor = new Predictor(sim, player, selfEntity, 0, opts.firstSeq ?? 1);
+    }
+    /** The seq the next input gets; pass as `firstSeq` to a client that replaces this one. */
+    get nextSeq() {
+        return this.predictor.upcomingSeq;
+    }
+    receiveSnapshot(bytes, nowMs) {
+        let snap;
+        try {
+            snap = decodeSnapshot(this.sim.schema, bytes, (t) => this.history.get(t));
+        }
+        catch (err) {
+            if (err instanceof BaselineMissingError) {
+                // Ask for a full snapshot by acking nothing until one arrives.
+                this.stats.baselineMisses++;
+                this.latestTick = 0;
+                return;
+            }
+            throw err;
+        }
+        this.stats.snapshots++;
+        this.stats.snapshotBytes += bytes.length;
+        const { header, entities } = snap;
+        if (header.tick <= this.latestTick) {
+            this.stats.staleSnapshots++;
+            return;
+        }
+        this.latestTick = header.tick;
+        if (header.inputBuffer !== undefined) {
+            this.serverBuffer = this.serverBuffer === null ? header.inputBuffer : this.serverBuffer + (header.inputBuffer - this.serverBuffer) * 0.1;
+        }
+        this.history.put(header.tick, entities);
+        this.clock.observe(header.tick, nowMs);
+        this.interp.push(header.tick, entities);
+        const self = entities.get(this.selfEntity);
+        this.latestSelf = self;
+        if (self)
+            this.predictor.reconcile(header.ackSeq, this.toState(self));
+    }
+    /** Call once per sim tick with the sampled input. Sends the input packet. */
+    tick(input, nowMs) {
+        const viewTick16 = Math.max(0, Math.round(this.renderTick(nowMs) * 16));
+        this.predictor.predict(input, viewTick16);
+        const pending = this.predictor.unacked();
+        const commands = pending.slice(Math.max(0, pending.length - REDUNDANCY));
+        const bytes = encodeInputPacket(this.sim.input, { ackTick: this.latestTick, commands });
+        this.stats.inputPackets++;
+        this.stats.inputBytes += bytes.length;
+        this.send(bytes);
+    }
+    /**
+     * Milliseconds until the next input tick. Equal to the sim tick when the
+     * server reports no input queue; otherwise up to 8% shorter when the
+     * server's queue for us runs below target (we are behind, so input would
+     * starve) and up to 8% longer when it runs above (added latency). This is
+     * the client clock adjustment for one-input-per-tick sims.
+     */
+    tickIntervalMs() {
+        if (this.serverBuffer === null)
+            return this.tickMs;
+        const target = this.opts.inputBufferTarget ?? 2;
+        const scale = 1 + Math.max(-0.08, Math.min(0.08, (this.serverBuffer - target) * 0.03));
+        return this.tickMs * scale;
+    }
+    /** Smoothed input-queue depth the server last reported, or null. */
+    get serverInputBuffer() {
+        return this.serverBuffer;
+    }
+    /** Server tick (fractional) that remote entities are drawn at. */
+    renderTick(nowMs) {
+        return this.clock.serverTick(nowMs) - this.opts.interpDelayMs / this.tickMs;
+    }
+    render(nowMs) {
+        const dt = this.lastRenderMs === 0 ? 0 : nowMs - this.lastRenderMs;
+        this.lastRenderMs = nowMs;
+        return {
+            self: this.predictor.renderState(dt),
+            others: this.interp.sample(this.renderTick(nowMs), this.selfEntity),
+        };
+    }
+    /** The newest server state of our own entity (what prediction is ahead of). */
+    authoritativeSelf() {
+        return this.latestSelf ? this.toState(this.latestSelf) : undefined;
+    }
+    /** Our own entity drawn like a remote one (what you'd see with no prediction). */
+    interpolatedSelf(nowMs) {
+        return this.interp.sample(this.renderTick(nowMs)).find((e) => e.id === this.selfEntity);
+    }
+    /** Exact predicted state (no smoothing). */
+    predicted() {
+        return this.predictor.state();
+    }
+    get ready() {
+        return this.predictor.isReady;
+    }
+    get corrections() {
+        return this.predictor.corrections;
+    }
+    get lastCorrection() {
+        return this.predictor.lastCorrection;
+    }
+    get pendingInputs() {
+        return this.predictor.unacked().length;
+    }
+    toState(e) {
+        return { id: e.id, kind: e.kind, owner: e.owner, values: dequantizeValues(this.sim.schema, e.q) };
+    }
+}

package/dist/net/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @netforge/engine/net: the client half of the netcode and everything
+ * the room server shares with it: the SimAdapter seam,
+ * schema-driven bit-packed delta snapshots, sequence-numbered input packets,
+ * prediction and reconciliation, interpolation, the server clock estimate,
+ * the room wire protocol, and the Colyseus room client.
+ *
+ * It lives in the engine so templates and the Net Forge site can use it
+ * without depending on the room server; the server-only parts (ServerCore,
+ * AoI, lag-compensation rewind) stay in the hosted Net Forge room server.
+ */
+export * from './bits.js';
+export * from './schema.js';
+export * from './snapshot.js';
+export * from './input.js';
+export * from './interpolation.js';
+export * from './prediction.js';
+export * from './client.js';
+export * from './sim-adapter.js';
+export * from './netsim.js';
+export * from './protocol.js';
+export * from './room-client.js';
+export * from "./profile-client.js";

package/dist/net/index.js

@@ -0,0 +1,23 @@
+/**
+ * @netforge/engine/net: the client half of the netcode and everything
+ * the room server shares with it: the SimAdapter seam,
+ * schema-driven bit-packed delta snapshots, sequence-numbered input packets,
+ * prediction and reconciliation, interpolation, the server clock estimate,
+ * the room wire protocol, and the Colyseus room client.
+ *
+ * It lives in the engine so templates and the Net Forge site can use it
+ * without depending on the room server; the server-only parts (ServerCore,
+ * AoI, lag-compensation rewind) stay in the hosted Net Forge room server.
+ */
+export * from './bits.js';
+export * from './schema.js';
+export * from './snapshot.js';
+export * from './input.js';
+export * from './interpolation.js';
+export * from './prediction.js';
+export * from './client.js';
+export * from './sim-adapter.js';
+export * from './netsim.js';
+export * from './protocol.js';
+export * from './room-client.js';
+export * from "./profile-client.js";

package/dist/net/input.d.ts

@@ -0,0 +1,49 @@
+import type { InputCodec } from './sim-adapter.js';
+export interface InputCommand<I> {
+    readonly seq: number;
+    /** Render tick the client was showing when it sampled this input, x16. */
+    readonly viewTick16: number;
+    readonly input: I;
+}
+export interface InputPacket<I> {
+    /** Highest snapshot tick the client has decoded (its delta baseline). */
+    readonly ackTick: number;
+    readonly commands: readonly InputCommand<I>[];
+}
+/** How many unacked commands each packet repeats. */
+export declare const REDUNDANCY = 4;
+export declare function encodeInputPacket<I>(codec: InputCodec<I>, p: InputPacket<I>): Uint8Array;
+export declare function decodeInputPacket<I>(codec: InputCodec<I>, bytes: Uint8Array): InputPacket<I>;
+export interface InputQueueOptions {
+    /** Most commands waiting at once; extra are dropped (client gets corrected). */
+    readonly maxQueue: number;
+    /** Credit bucket size: how far a player may catch up after a stall. */
+    readonly maxCredits: number;
+    /**
+     * Jitter buffer for one-input-per-tick sims: after the queue runs dry, hold
+     * input until this many commands are waiting, then resume one per tick.
+     * 0 (default) consumes as soon as anything arrives. Clients hold the depth
+     * near this target with `NetClient.tickIntervalMs()`.
+     */
+    readonly targetDepth?: number;
+}
+export declare const DEFAULT_INPUT_QUEUE: InputQueueOptions;
+/** Server-side per-player input queue with speed-hack protection. */
+export declare class InputQueue<I> {
+    private readonly opts;
+    private readonly queue;
+    private lastQueuedSeq;
+    private credits;
+    /** Highest seq applied by the sim; echoed to the client as ackSeq. */
+    lastAppliedSeq: number;
+    /** Commands dropped because the queue was full (telemetry). */
+    dropped: number;
+    /** Ticks the queue was empty when the sim needed a command (telemetry). */
+    starved: number;
+    private refilling;
+    constructor(opts?: InputQueueOptions);
+    receive(commands: readonly InputCommand<I>[]): void;
+    /** Commands to apply this tick (0..maxCredits of them). */
+    consume(): InputCommand<I>[];
+    get pending(): number;
+}

package/dist/net/input.js

@@ -0,0 +1,112 @@
+// Sequence-numbered input commands.
+//
+// The client produces one command per local tick and sends, every tick, all
+// commands the server has not yet acknowledged (capped at REDUNDANCY), so a
+// lost packet is covered by the next one. The server queues commands in
+// sequence order, ignores ones it already has, and consumes them at no more
+// than one per tick on average (a credit bucket), which is what stops a
+// modified client from moving faster by sending more inputs.
+import { BitReader, BitWriter } from './bits.js';
+/** How many unacked commands each packet repeats. */
+export const REDUNDANCY = 4;
+export function encodeInputPacket(codec, p) {
+    const w = new BitWriter(64);
+    w.writeBits(p.ackTick, 32);
+    w.writeVarUint(p.commands.length);
+    const first = p.commands[0];
+    if (first) {
+        w.writeBits(first.seq, 32);
+        w.writeBits(first.viewTick16, 32);
+    }
+    let prevView = first?.viewTick16 ?? 0;
+    for (let i = 0; i < p.commands.length; i++) {
+        const c = p.commands[i];
+        if (!c)
+            continue;
+        if (first && c.seq !== first.seq + i)
+            throw new Error('input commands must have consecutive seqs');
+        if (i > 0) {
+            w.writeSigned(c.viewTick16 - prevView, 16);
+            prevView = c.viewTick16;
+        }
+        codec.write(w, c.input);
+    }
+    return w.finish();
+}
+export function decodeInputPacket(codec, bytes) {
+    const r = new BitReader(bytes);
+    const ackTick = r.readBits(32);
+    const n = r.readVarUint();
+    if (n > 64)
+        throw new Error('input packet: too many commands');
+    const commands = [];
+    if (n > 0) {
+        const firstSeq = r.readBits(32);
+        let view = r.readBits(32);
+        for (let i = 0; i < n; i++) {
+            if (i > 0)
+                view += r.readSigned(16);
+            commands.push({ seq: firstSeq + i, viewTick16: view, input: codec.read(r) });
+        }
+    }
+    return { ackTick, commands };
+}
+export const DEFAULT_INPUT_QUEUE = { maxQueue: 16, maxCredits: 6 };
+/** Server-side per-player input queue with speed-hack protection. */
+export class InputQueue {
+    opts;
+    queue = [];
+    lastQueuedSeq = 0;
+    credits = 1;
+    /** Highest seq applied by the sim; echoed to the client as ackSeq. */
+    lastAppliedSeq = 0;
+    /** Commands dropped because the queue was full (telemetry). */
+    dropped = 0;
+    /** Ticks the queue was empty when the sim needed a command (telemetry). */
+    starved = 0;
+    refilling = true;
+    constructor(opts = DEFAULT_INPUT_QUEUE) {
+        this.opts = opts;
+    }
+    receive(commands) {
+        for (const c of commands) {
+            if (c.seq <= this.lastQueuedSeq)
+                continue;
+            if (this.queue.length >= this.opts.maxQueue) {
+                this.dropped++;
+                this.lastQueuedSeq = c.seq;
+                continue;
+            }
+            this.queue.push(c);
+            this.lastQueuedSeq = c.seq;
+        }
+    }
+    /** Commands to apply this tick (0..maxCredits of them). */
+    consume() {
+        const target = this.opts.targetDepth ?? 0;
+        if (target > 0) {
+            if (this.queue.length === 0) {
+                if (!this.refilling && this.lastAppliedSeq > 0)
+                    this.starved++;
+                this.refilling = true;
+                return [];
+            }
+            if (this.refilling && this.queue.length < target)
+                return [];
+            this.refilling = false;
+        }
+        this.credits = Math.min(this.credits + 1, this.opts.maxCredits);
+        const n = Math.min(this.queue.length, Math.floor(this.credits));
+        if (n === 0)
+            return [];
+        this.credits -= n;
+        const out = this.queue.splice(0, n);
+        const last = out[out.length - 1];
+        if (last)
+            this.lastAppliedSeq = last.seq;
+        return out;
+    }
+    get pending() {
+        return this.queue.length;
+    }
+}

package/dist/net/interpolation.d.ts

@@ -0,0 +1,37 @@
+import { type EntitySchema } from './schema.js';
+import type { QEntity } from './snapshot.js';
+export interface InterpolatedEntity {
+    readonly id: number;
+    readonly kind: number;
+    readonly owner: number;
+    readonly values: readonly number[];
+}
+/**
+ * Tracks server time from snapshot arrivals. The offset (server ms minus
+ * local ms) is taken from the freshest-looking arrival, eased toward later
+ * samples so jitter does not make the render time jump.
+ */
+export declare class ServerClock {
+    private readonly tickMs;
+    private offset;
+    constructor(tickMs: number);
+    observe(tick: number, localMs: number): void;
+    /** Estimated server tick (fractional) at local time. */
+    serverTick(localMs: number): number;
+    get ready(): boolean;
+}
+export declare class InterpolationBuffer {
+    private readonly schema;
+    private readonly capacity;
+    private readonly frames;
+    constructor(schema: EntitySchema, capacity?: number);
+    push(tick: number, entities: ReadonlyMap<number, QEntity>): void;
+    /**
+     * Entities at a fractional render tick. Entities present only in the
+     * newer frame pop in; ones only in the older frame are held until gone.
+     * Past the newest frame we hold the newest state (no extrapolation).
+     */
+    sample(renderTick: number, exclude?: number): InterpolatedEntity[];
+    get newestTick(): number;
+    private frameValues;
+}

package/dist/net/interpolation.js

@@ -0,0 +1,97 @@
+// Interpolation of remote entities ~100 ms in the past, and the client's
+// estimate of the server's clock that decides "the past".
+import { dequantizeValues, interpolateField } from './schema.js';
+/**
+ * Tracks server time from snapshot arrivals. The offset (server ms minus
+ * local ms) is taken from the freshest-looking arrival, eased toward later
+ * samples so jitter does not make the render time jump.
+ */
+export class ServerClock {
+    tickMs;
+    offset = null;
+    constructor(tickMs) {
+        this.tickMs = tickMs;
+    }
+    observe(tick, localMs) {
+        const sample = tick * this.tickMs - localMs;
+        if (this.offset === null || Math.abs(sample - this.offset) > 250) {
+            this.offset = sample;
+            return;
+        }
+        // Earlier-than-expected arrivals mean lower latency: move fast toward them.
+        // Late ones are jitter: move slowly.
+        const k = sample > this.offset ? 0.2 : 0.02;
+        this.offset += (sample - this.offset) * k;
+    }
+    /** Estimated server tick (fractional) at local time. */
+    serverTick(localMs) {
+        return this.offset === null ? 0 : (localMs + this.offset) / this.tickMs;
+    }
+    get ready() {
+        return this.offset !== null;
+    }
+}
+export class InterpolationBuffer {
+    schema;
+    capacity;
+    frames = [];
+    constructor(schema, capacity = 32) {
+        this.schema = schema;
+        this.capacity = capacity;
+    }
+    push(tick, entities) {
+        const last = this.frames[this.frames.length - 1];
+        if (last && tick <= last.tick)
+            return;
+        this.frames.push({ tick, entities });
+        while (this.frames.length > this.capacity)
+            this.frames.shift();
+    }
+    /**
+     * Entities at a fractional render tick. Entities present only in the
+     * newer frame pop in; ones only in the older frame are held until gone.
+     * Past the newest frame we hold the newest state (no extrapolation).
+     */
+    sample(renderTick, exclude) {
+        const n = this.frames.length;
+        if (n === 0)
+            return [];
+        let i = n - 1;
+        while (i > 0 && (this.frames[i]?.tick ?? 0) > renderTick)
+            i--;
+        const a = this.frames[i];
+        const b = this.frames[i + 1];
+        if (!a)
+            return [];
+        if (!b || renderTick <= a.tick)
+            return this.frameValues(a, exclude);
+        const t = (renderTick - a.tick) / (b.tick - a.tick);
+        const out = [];
+        for (const eb of b.entities.values()) {
+            if (eb.id === exclude)
+                continue;
+            const ea = a.entities.get(eb.id);
+            const vb = dequantizeValues(this.schema, eb.q);
+            if (!ea) {
+                out.push({ id: eb.id, kind: eb.kind, owner: eb.owner, values: vb });
+                continue;
+            }
+            const va = dequantizeValues(this.schema, ea.q);
+            const values = this.schema.fields.map((f, k) => interpolateField(f, va[k] ?? 0, vb[k] ?? 0, t));
+            out.push({ id: eb.id, kind: eb.kind, owner: eb.owner, values });
+        }
+        return out;
+    }
+    get newestTick() {
+        return this.frames[this.frames.length - 1]?.tick ?? 0;
+    }
+    frameValues(f, exclude) {
+        const out = [];
+        for (const e of f.entities.values()) {
+            if (e.id === exclude)
+                continue;
+            out.push({ id: e.id, kind: e.kind, owner: e.owner, values: dequantizeValues(this.schema, e.q) });
+        }
+        return out;
+    }
+}

package/dist/net/netsim.d.ts

@@ -0,0 +1,22 @@
+export interface LinkOptions {
+    /** Base one-way latency, ms. */
+    readonly latencyMs: number;
+    /** Uniform extra delay in [0, jitterMs). */
+    readonly jitterMs: number;
+    /** Probability a packet is dropped. */
+    readonly loss: number;
+}
+export declare class VirtualNet {
+    now: number;
+    private queue;
+    private seq;
+    private rng;
+    sent: number;
+    dropped: number;
+    constructor(seed?: number);
+    random(): number;
+    /** Sends over a link; `deliver` runs at arrival time unless dropped. */
+    send(link: LinkOptions, deliver: () => void): void;
+    /** Advances the clock to `t`, delivering everything due, in arrival order. */
+    advanceTo(t: number): void;
+}

package/dist/net/netsim.js

@@ -0,0 +1,52 @@
+// A deterministic simulated network for netcode tests: virtual clock,
+// one-way latency, jitter (so packets reorder), and random loss. Models the
+// unreliable-datagram case (WebTransport), which is strictly harder than the
+// WebSocket case (in order, no loss, latency spikes instead).
+export class VirtualNet {
+    now = 0;
+    queue = [];
+    seq = 0;
+    rng;
+    sent = 0;
+    dropped = 0;
+    constructor(seed = 12345) {
+        this.rng = seed;
+    }
+    random() {
+        this.rng = (this.rng + 0x6d2b79f5) | 0;
+        let t = this.rng;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    }
+    /** Sends over a link; `deliver` runs at arrival time unless dropped. */
+    send(link, deliver) {
+        this.sent++;
+        if (this.random() < link.loss) {
+            this.dropped++;
+            return;
+        }
+        const at = this.now + link.latencyMs + this.random() * link.jitterMs;
+        this.queue.push({ at, seq: this.seq++, deliver });
+    }
+    /** Advances the clock to `t`, delivering everything due, in arrival order. */
+    advanceTo(t) {
+        for (;;) {
+            let best = -1;
+            for (let i = 0; i < this.queue.length; i++) {
+                const q = this.queue[i];
+                const b = best >= 0 ? this.queue[best] : undefined;
+                if (q && q.at <= t && (!b || q.at < b.at || (q.at === b.at && q.seq < b.seq)))
+                    best = i;
+            }
+            if (best < 0)
+                break;
+            const [item] = this.queue.splice(best, 1);
+            if (!item)
+                break;
+            this.now = item.at;
+            item.deliver();
+        }
+        this.now = t;
+    }
+}

package/dist/net/prediction.d.ts

@@ -0,0 +1,31 @@
+import type { EntityState } from './schema.js';
+import type { InputCommand } from './input.js';
+import type { PlayerId, SimAdapter } from './sim-adapter.js';
+export declare class Predictor<W, I> {
+    private readonly sim;
+    private readonly player;
+    private readonly selfEntity;
+    private readonly world;
+    private pending;
+    private nextSeq;
+    private ready;
+    private offsetX;
+    private offsetY;
+    /** Magnitude of the last correction in world units (telemetry/tests). */
+    lastCorrection: number;
+    /** Count of reconciliations that moved the predicted entity. */
+    corrections: number;
+    constructor(sim: SimAdapter<W, I>, player: PlayerId, selfEntity: number, seed?: number, firstSeq?: number);
+    /** The seq the next predicted command gets (a rebased predictor continues from here). */
+    get upcomingSeq(): number;
+    get isReady(): boolean;
+    /** Applies one tick of input locally. Returns the command to send. */
+    predict(input: I, viewTick16: number): InputCommand<I> | null;
+    /** Unacknowledged commands, oldest first. */
+    unacked(): readonly InputCommand<I>[];
+    reconcile(ackSeq: number, serverSelf: EntityState): void;
+    /** The predicted entity, exact (what reconciliation converges on). */
+    state(): EntityState | undefined;
+    /** The predicted entity with the correction offset applied, for drawing. */
+    renderState(dtMs: number): EntityState | undefined;
+}