@netforge/engine 0.0.0-stage → 0.2.0

package/dist/net/snapshot.js

@@ -0,0 +1,301 @@
+// Delta-compressed, bit-packed snapshots.
+//
+// The server keeps, per client, the quantized entity sets it sent for the
+// last N snapshot ticks. Each new snapshot is encoded against the most recent
+// one the client acknowledged (its "baseline"):
+//
+//   - entities in the baseline but not in this snapshot are listed as removed
+//     (destroyed, or left the client's area of interest),
+//   - every other baseline entity costs one "changed?" bit, in id order (no
+//     ids on the wire for a crowd); changed ones send a per-field changed
+//     mask (or one bit when it repeats the previous changed entity's mask),
+//     and each changed field goes either as a small signed delta or in full,
+//   - entities absent from the baseline are sent in full ("new") by id gap.
+//
+// Both sides compare QUANTIZED integers, so the client's reconstruction is
+// bit-identical to what the server believes it sent. With no acked baseline
+// (first snapshot, or the ack fell out of history) the snapshot is full.
+import { BitReader, BitWriter } from './bits.js';
+import { fieldBits, fieldDeltaBits } from './schema.js';
+export class BaselineMissingError extends Error {
+    baselineTick;
+    constructor(baselineTick) {
+        super(`snapshot baseline ${baselineTick} not in history`);
+        this.baselineTick = baselineTick;
+    }
+}
+const ANGLE_MOD = 65536;
+/**
+ * Encodes `current` (any order) against `baseline` (null for a full snapshot).
+ */
+export function encodeSnapshot(schema, header, current, baseline) {
+    const w = new BitWriter(512);
+    w.writeBits(header.tick, 32);
+    w.writeBits(baseline ? header.baselineTick : 0, 32);
+    w.writeBits(header.ackSeq, 32);
+    w.writeBits(header.self, 16);
+    w.writeBool(header.inputBuffer !== undefined);
+    if (header.inputBuffer !== undefined)
+        w.writeBits(Math.max(0, Math.min(255, Math.round(header.inputBuffer))), 8);
+    const sorted = [...current].sort((a, b) => a.id - b.id);
+    const fields = schema.fields;
+    // Removed: in the baseline and gone now, or replaced by a different
+    // entity under the same id (kind or owner changed: removed, then new).
+    const removed = [];
+    const fresh = [];
+    const kept = new Map();
+    if (baseline) {
+        const live = new Map();
+        for (const e of sorted)
+            live.set(e.id, e);
+        for (const [id, b] of baseline) {
+            const e = live.get(id);
+            if (!e || e.kind !== b.kind || e.owner !== b.owner)
+                removed.push(id);
+            else
+                kept.set(id, e);
+        }
+        removed.sort((x, y) => x - y);
+        for (const e of sorted)
+            if (!kept.has(e.id))
+                fresh.push(e);
+    }
+    else {
+        fresh.push(...sorted);
+    }
+    w.writeVarUint(removed.length);
+    let prev = 0;
+    for (const id of removed) {
+        w.writeVarUint(id - prev);
+        prev = id;
+    }
+    // Kept entities: one bit each, in baseline id order (changed or not), so a
+    // crowd costs a bit per entity for "which ones", never an id. Changed ones
+    // follow with a field mask (or one bit when it repeats the previous mask).
+    if (baseline) {
+        const keptIds = [...kept.keys()].sort((x, y) => x - y);
+        let lastMask = -1;
+        let lastMaskLen = -1;
+        for (const id of keptIds) {
+            const e = kept.get(id);
+            const base = baseline.get(id);
+            const idx = kindFieldIndices(schema, e.kind);
+            let mask = 0;
+            for (let j = 0; j < idx.length; j++) {
+                const i = idx[j];
+                if (e.q[i] !== base.q[i])
+                    mask |= 1 << j;
+            }
+            w.writeBool(mask !== 0);
+            if (mask === 0)
+                continue;
+            if (mask === lastMask && idx.length === lastMaskLen) {
+                w.writeBool(true);
+            }
+            else {
+                w.writeBool(false);
+                w.writeBits(mask, idx.length);
+                lastMask = mask;
+                lastMaskLen = idx.length;
+            }
+            for (let j = 0; j < idx.length; j++) {
+                if ((mask & (1 << j)) === 0)
+                    continue;
+                const i = idx[j];
+                const f = fieldAt(fields, i);
+                const v = e.q[i] ?? 0;
+                const db = fieldDeltaBits(f);
+                if (db > 0) {
+                    const d = fieldDelta(f, base.q[i] ?? 0, v);
+                    if (fitsSigned(d, db)) {
+                        w.writeBool(true);
+                        w.writeSigned(d, db);
+                        continue;
+                    }
+                    w.writeBool(false);
+                }
+                writeFull(w, f, v);
+            }
+        }
+    }
+    // New entities, in full, by id gap.
+    w.writeVarUint(fresh.length);
+    prev = 0;
+    for (const e of fresh) {
+        w.writeVarUint(e.id - prev);
+        prev = e.id;
+        w.writeBits(e.kind, 8);
+        w.writeBits(e.owner, 16);
+        for (const i of kindFieldIndices(schema, e.kind))
+            writeFull(w, fieldAt(fields, i), e.q[i] ?? 0);
+    }
+    return w.finish();
+}
+/**
+ * Decodes a snapshot. `baselineFor` returns the client's stored entity set
+ * for a tick it previously decoded.
+ */
+export function decodeSnapshot(schema, bytes, baselineFor) {
+    const r = new BitReader(bytes);
+    const tick = r.readBits(32);
+    const baselineTick = r.readBits(32);
+    const ackSeq = r.readBits(32);
+    const self = r.readBits(16);
+    const header = r.readBool() ? { tick, baselineTick, ackSeq, self, inputBuffer: r.readBits(8) } : { tick, baselineTick, ackSeq, self };
+    let base;
+    if (baselineTick !== 0) {
+        base = baselineFor(baselineTick);
+        if (!base)
+            throw new BaselineMissingError(baselineTick);
+    }
+    const out = new Map(base ?? []);
+    const removedCount = r.readVarUint();
+    const removed = [];
+    let prev = 0;
+    for (let i = 0; i < removedCount; i++) {
+        const id = prev + r.readVarUint();
+        prev = id;
+        removed.push(id);
+        out.delete(id);
+    }
+    const fields = schema.fields;
+    const nf = fields.length;
+    if (base) {
+        const keptIds = [...out.keys()].sort((x, y) => x - y);
+        let lastMask = -1;
+        let lastMaskLen = -1;
+        for (const id of keptIds) {
+            if (!r.readBool())
+                continue;
+            const prevE = out.get(id);
+            const idx = kindFieldIndices(schema, prevE.kind);
+            let mask;
+            if (r.readBool()) {
+                if (idx.length !== lastMaskLen)
+                    throw new Error('snapshot: repeated mask for a different field set');
+                mask = lastMask;
+            }
+            else {
+                mask = r.readBits(idx.length);
+                lastMask = mask;
+                lastMaskLen = idx.length;
+            }
+            const q = [...prevE.q];
+            for (let j = 0; j < idx.length; j++) {
+                if ((mask & (1 << j)) === 0)
+                    continue;
+                const i = idx[j];
+                const f = fieldAt(fields, i);
+                const db = fieldDeltaBits(f);
+                if (db > 0 && r.readBool()) {
+                    q[i] = applyDelta(f, prevE.q[i] ?? 0, r.readSigned(db));
+                }
+                else {
+                    q[i] = readFull(r, f);
+                }
+            }
+            out.set(id, { id, kind: prevE.kind, owner: prevE.owner, q });
+        }
+    }
+    const count = r.readVarUint();
+    prev = 0;
+    for (let n = 0; n < count; n++) {
+        const id = prev + r.readVarUint();
+        prev = id;
+        const kind = r.readBits(8);
+        const owner = r.readBits(16);
+        const q = new Array(nf).fill(0);
+        for (const i of kindFieldIndices(schema, kind))
+            q[i] = readFull(r, fieldAt(fields, i));
+        out.set(id, { id, kind, owner, q });
+    }
+    return { header, entities: out, removed };
+}
+/**
+ * Per-client history of what was sent, keyed by tick, so the next snapshot
+ * can be encoded against whatever the client last acked.
+ */
+export class SnapshotHistory {
+    capacity;
+    byTick = new Map();
+    order = [];
+    constructor(capacity = 64) {
+        this.capacity = capacity;
+    }
+    put(tick, entities) {
+        const m = entities instanceof Map ? entities : new Map(entities.map((e) => [e.id, e]));
+        if (!this.byTick.has(tick))
+            this.order.push(tick);
+        this.byTick.set(tick, m);
+        while (this.order.length > this.capacity) {
+            const old = this.order.shift();
+            if (old !== undefined)
+                this.byTick.delete(old);
+        }
+    }
+    get(tick) {
+        return this.byTick.get(tick);
+    }
+    /** Drop entries older than `tick` (they can never be a baseline again). */
+    pruneBefore(tick) {
+        while (this.order.length > 0 && (this.order[0] ?? Infinity) < tick) {
+            const old = this.order.shift();
+            if (old !== undefined)
+                this.byTick.delete(old);
+        }
+    }
+    get size() {
+        return this.order.length;
+    }
+}
+const allIndices = new WeakMap();
+/** Field indices carried on the wire for an entity kind (all fields unless the schema narrows that kind). */
+export function kindFieldIndices(schema, kind) {
+    const narrowed = schema.kindFields?.[kind];
+    if (narrowed)
+        return narrowed;
+    let all = allIndices.get(schema);
+    if (!all) {
+        all = schema.fields.map((_, i) => i);
+        allIndices.set(schema, all);
+    }
+    return all;
+}
+function fieldAt(fields, i) {
+    const f = fields[i];
+    if (f === undefined)
+        throw new Error(`schema has no field ${i}`);
+    return f;
+}
+function writeFull(w, f, v) {
+    if (f.kind === 'int')
+        w.writeSigned(v, f.bits);
+    else
+        w.writeBits(v, fieldBits(f));
+}
+function readFull(r, f) {
+    if (f.kind === 'int')
+        return r.readSigned(f.bits);
+    return r.readBits(fieldBits(f));
+}
+function fieldDelta(f, from, to) {
+    if (f.kind === 'angle16') {
+        let d = (to - from) % ANGLE_MOD;
+        if (d >= ANGLE_MOD / 2)
+            d -= ANGLE_MOD;
+        if (d < -ANGLE_MOD / 2)
+            d += ANGLE_MOD;
+        return d;
+    }
+    return to - from;
+}
+function applyDelta(f, from, d) {
+    if (f.kind === 'angle16')
+        return (((from + d) % ANGLE_MOD) + ANGLE_MOD) % ANGLE_MOD;
+    return from + d;
+}
+function fitsSigned(d, bits) {
+    // zigzag(d) must fit in `bits` bits
+    const z = d >= 0 ? d * 2 : -d * 2 - 1;
+    return z < 2 ** bits;
+}

package/dist/rules/adapter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The SimAdapter for board genres (rules/kit.ts): the room server steps a
+ * genre's rules on a fixed tick; the client predicts only its own avatar.
+ *
+ * The adapter, not the genre, owns what makes a game pay fairly, the same
+ * way GameRunner does for the action templates:
+ *  - earn rules counted per player per run (EarnTracker), seat bots never
+ *    earn, unpaid events pay nobody, and world progress never pays a run
+ *    that started after this world began;
+ *  - store upgrades and losable gear as recorded room commands (a replay
+ *    applies them at the same tick), capped at each upgrade's maxLevel;
+ *  - cosmetics on the avatar;
+ *  - the end screen, then `run.reset` so the room rebuilds the world and
+ *    starts every seat's next referee run.
+ */
+import { EarnTracker } from "../game/earn.js";
+import type { GameManifest } from "../api/registry.js";
+import type { PlayerId, SimAdapter } from "../net/sim-adapter.js";
+import type { Avatar, RulesGenre, RulesInput, RunOutcome } from "./kit.js";
+export interface RulesWorld<S = unknown> {
+    readonly role: "server" | "client";
+    /** The genre's state (server only). */
+    state: S | null;
+    readonly avatars: Map<PlayerId, Avatar>;
+    tick: number;
+    /** Ticks into the run (0 until the first step). */
+    runTick: number;
+    phase: "playing" | "ended";
+    outcome: RunOutcome | null;
+    endTick: number;
+    readonly earn: EarnTracker | null;
+    /** Players whose referee run started after this world made progress. */
+    readonly late: Set<PlayerId>;
+    /** World or fight progress (any event that is not a player's own act) has happened in this world. */
+    progressed: boolean;
+    /** Store upgrade levels per player: upgrade id -> level. */
+    readonly upgrades: Map<PlayerId, Map<string, number>>;
+    /** Earn rules paid this run, per player (HUD). */
+    readonly paid: Map<PlayerId, Set<string>>;
+    /** Seat bots present. */
+    readonly bots: Set<PlayerId>;
+    /** Total earn awards this world (harness). */
+    awards: number;
+}
+export interface RulesAdapterOptions {
+    readonly name: string;
+    readonly version: string;
+}
+/** The SimAdapter for a board genre built from a game manifest. */
+export declare function rulesAdapter<S>(genre: RulesGenre<S>, manifest: GameManifest, opts: RulesAdapterOptions): SimAdapter<RulesWorld<S>, RulesInput> & {
+    readonly genre: RulesGenre<S>;
+    readonly manifest: GameManifest;
+};

package/dist/rules/adapter.js

@@ -0,0 +1,261 @@
+/**
+ * The SimAdapter for board genres (rules/kit.ts): the room server steps a
+ * genre's rules on a fixed tick; the client predicts only its own avatar.
+ *
+ * The adapter, not the genre, owns what makes a game pay fairly, the same
+ * way GameRunner does for the action templates:
+ *  - earn rules counted per player per run (EarnTracker), seat bots never
+ *    earn, unpaid events pay nobody, and world progress never pays a run
+ *    that started after this world began;
+ *  - store upgrades and losable gear as recorded room commands (a replay
+ *    applies them at the same tick), capped at each upgrade's maxLevel;
+ *  - cosmetics on the avatar;
+ *  - the end screen, then `run.reset` so the room rebuilds the world and
+ *    starts every seat's next referee run.
+ */
+import { EarnTracker } from "../game/earn.js";
+import { avatarEntity, IDLE_INPUT, isRulesBot, RF, RULES_BOT_BASE, RULES_SCHEMA, rulesInputCodec, RulesKind } from "./kit.js";
+/** The SimAdapter for a board genre built from a game manifest. */
+export function rulesAdapter(genre, manifest, opts) {
+    const upgrades = manifest.upgrades;
+    const skus = manifest.skus;
+    const gear = new Set([...skus.values()].flatMap((s) => (s.grants && "gear" in s.grants ? [s.grants.gear] : [])));
+    const endTicks = Math.max(1, Math.round(genre.endSeconds * genre.tickRate));
+    const ctxOf = (w) => ({
+        bonus(player, stat) {
+            const mine = w.upgrades.get(player);
+            if (!mine)
+                return 0;
+            let b = 0;
+            for (const [id, lvl] of mine) {
+                const u = upgrades.get(id);
+                if (u && u.stat === stat)
+                    b += u.step * lvl;
+            }
+            return b;
+        },
+        isBot: (p) => isRulesBot(p),
+    });
+    /** Earn credits people only; unpaid events pay nobody; world progress skips late runs. */
+    const record = (w, ev, out) => {
+        if (!w.earn)
+            return;
+        if (ev.own !== true && !ev.unpaid)
+            w.progressed = true;
+        if (ev.unpaid)
+            return;
+        const late = ev.own === true || w.late.size === 0 ? null : w.late;
+        const players = ev.players.filter((p) => !isRulesBot(p) && w.avatars.has(p) && !(late?.has(p) ?? false));
+        if (players.length === 0)
+            return;
+        for (const a of w.earn.record({ name: ev.name, players })) {
+            out.push({ type: "earn", player: a.player, rule: a.rule, units: a.units });
+            let set = w.paid.get(a.player);
+            if (!set)
+                w.paid.set(a.player, (set = new Set()));
+            set.add(a.rule);
+            w.awards++;
+        }
+    };
+    const addAvatar = (w, player) => {
+        const at = genre.spawn(w.state, player);
+        w.avatars.set(player, { x: at.x, z: at.z, yaw: 0, cosmetic: 0, flags: 0 });
+        if (w.state)
+            genre.join(w.state, player);
+        return player;
+    };
+    const removeAvatar = (w, player) => {
+        if (!w.avatars.delete(player))
+            return;
+        if (w.state)
+            genre.leave(w.state, player);
+        w.earn?.forget(player);
+        w.upgrades.delete(player);
+        w.paid.delete(player);
+        w.late.delete(player);
+        w.bots.delete(player);
+    };
+    /** Seat bots: as many as the genre wants with the people present, one change a tick, only while a person is here. */
+    const fillSeats = (w) => {
+        if (!genre.seats || !w.state)
+            return;
+        let humans = 0;
+        for (const p of w.avatars.keys())
+            if (!isRulesBot(p))
+                humans++;
+        const want = humans > 0 ? Math.max(0, genre.seats(w.state, humans)) : 0;
+        if (w.bots.size < want) {
+            let id = RULES_BOT_BASE;
+            while (w.bots.has(id))
+                id++;
+            w.bots.add(id);
+            addAvatar(w, id);
+        }
+        else if (w.bots.size > want) {
+            const id = Math.max(...w.bots);
+            removeAvatar(w, id);
+        }
+    };
+    const level = (w, player, id) => {
+        const u = upgrades.get(id);
+        if (!u || !w.avatars.has(player))
+            return false;
+        let mine = w.upgrades.get(player);
+        if (!mine)
+            w.upgrades.set(player, (mine = new Map()));
+        const now = mine.get(id) ?? 0;
+        if (now >= u.maxLevel)
+            return false;
+        mine.set(id, now + 1);
+        return true;
+    };
+    return {
+        name: opts.name,
+        version: opts.version,
+        tickHz: genre.tickRate,
+        schema: RULES_SCHEMA,
+        input: rulesInputCodec,
+        maxInputsPerTick: 1,
+        infoEveryTicks: genre.infoEveryTicks,
+        genre,
+        manifest,
+        createWorld(seed, role) {
+            const w = {
+                role,
+                state: null,
+                avatars: new Map(),
+                tick: 0,
+                runTick: 0,
+                phase: "playing",
+                outcome: null,
+                endTick: 0,
+                earn: role === "server" ? new EarnTracker(manifest.earnRules) : null,
+                late: new Set(),
+                progressed: false,
+                upgrades: new Map(),
+                paid: new Map(),
+                bots: new Set(),
+                awards: 0,
+            };
+            if (role === "server")
+                w.state = genre.create(seed >>> 0, ctxOf(w));
+            return w;
+        },
+        addPlayer(w, player) {
+            return addAvatar(w, player);
+        },
+        removePlayer(w, player) {
+            removeAvatar(w, player);
+        },
+        step(w, inputsByPlayer) {
+            w.tick++;
+            const out = [];
+            const s = w.state;
+            // The client predicts its own avatar only.
+            if (!s) {
+                for (const [p, list] of inputsByPlayer) {
+                    const a = w.avatars.get(p);
+                    const i = list[0];
+                    if (a && i)
+                        genre.moveAvatar(a, i);
+                }
+                return out;
+            }
+            fillSeats(w);
+            const emit = (e) => record(w, e, out);
+            for (const [p, a] of w.avatars) {
+                const i = isRulesBot(p) ? genre.bot(s, p, a, w.tick, 0.8) : (inputsByPlayer.get(p)?.[0] ?? IDLE_INPUT);
+                genre.moveAvatar(a, i);
+                if (w.phase === "playing" && i.act !== 0)
+                    genre.act(s, p, i, a, emit);
+                if (w.phase === "playing")
+                    genre.tend?.(s, p, a, emit);
+            }
+            if (w.phase === "playing") {
+                genre.step(s, emit);
+                w.runTick++;
+                const o = genre.outcome(s);
+                if (o) {
+                    w.phase = "ended";
+                    w.outcome = o;
+                    w.endTick = w.tick + endTicks;
+                }
+            }
+            else if (w.tick >= w.endTick) {
+                out.push({ type: "run.reset" });
+                // The room rebuilds the world at its safe point; until then nothing moves.
+                w.endTick = Number.MAX_SAFE_INTEGER;
+            }
+            return out;
+        },
+        snapshot(w) {
+            const out = [];
+            for (const [p, a] of w.avatars)
+                out.push(avatarEntity(p, a));
+            if (w.state)
+                genre.entities(w.state, out);
+            return out;
+        },
+        applySnapshot(w, entities) {
+            for (const e of entities) {
+                if (e.kind !== RulesKind.Avatar)
+                    continue;
+                const v = e.values;
+                const yaw = Math.round(((v[RF.yaw] ?? 0) / (Math.PI * 2)) * 65536) & 0xffff;
+                const a = w.avatars.get(e.owner);
+                if (a) {
+                    a.x = Math.round(v[RF.x] ?? 0);
+                    a.z = Math.round(v[RF.z] ?? 0);
+                    a.yaw = yaw;
+                    a.flags = Math.round(v[RF.flags] ?? 0);
+                    a.cosmetic = Math.round(v[RF.value] ?? 0);
+                }
+                else {
+                    w.avatars.set(e.owner, { x: Math.round(v[RF.x] ?? 0), z: Math.round(v[RF.z] ?? 0), yaw, cosmetic: Math.round(v[RF.value] ?? 0), flags: Math.round(v[RF.flags] ?? 0) });
+                }
+            }
+        },
+        info(w) {
+            if (!w.state)
+                return null;
+            return { ...genre.view(w.state, null), phase: w.phase, outcome: w.outcome, endsIn: w.phase === "ended" ? Math.max(0, (w.endTick - w.tick) / genre.tickRate) : null };
+        },
+        infoFor(w, player) {
+            if (!w.state)
+                return null;
+            const progress = [...manifest.earnRules].map(([id, r]) => ({ id, when: r.when, n: r.n, have: Math.min(r.n, w.earn?.count(player, r.when) ?? 0), paid: w.paid.get(player)?.has(id) ?? false }));
+            const ups = Object.fromEntries(w.upgrades.get(player) ?? []);
+            return {
+                ...genre.view(w.state, player),
+                you: player,
+                phase: w.phase,
+                outcome: w.outcome,
+                endsIn: w.phase === "ended" ? Math.max(0, Math.round(((w.endTick - w.tick) / genre.tickRate) * 10) / 10) : null,
+                earn: progress,
+                upgrades: ups,
+                late: w.late.has(player),
+            };
+        },
+        startRun(w, player) {
+            w.earn?.forget(player);
+            w.paid.delete(player);
+            // A run that starts after the world made progress is never paid for that progress. A run that starts
+            // before any (the first player's sign-in lands a few ticks after the world begins) is not late.
+            if (w.progressed)
+                w.late.add(player);
+        },
+        command(w, player, cmd) {
+            const a = w.avatars.get(player);
+            if (!a)
+                return false;
+            if (cmd.name === "cosmetic") {
+                a.cosmetic = Math.max(0, Math.min(255, Math.round(cmd.value ?? 0)));
+                return true;
+            }
+            // A store upgrade (a SKU named after a declared upgrade) or gear the room issues at a staked run's start: one level.
+            if (upgrades.has(cmd.name) && (skus.has(cmd.name) || gear.has(cmd.name)))
+                return level(w, player, cmd.name);
+            return false;
+        },
+    };
+}