murow 0.0.73 → 0.1.1

package/dist/netcode/types/packets/harness.d.ts

@@ -0,0 +1,103 @@
+import { World, type Entity } from 'murow/ecs';
+import { GameLoop } from 'murow/game';
+import { SimpleRNG } from 'murow/core/simple-rng';
+import { GameServer } from '../server/game-server';
+import { GameClient } from '../client/game-client';
+import type { Peer } from '../ctx';
+import { JitterConfig, VirtualNetwork, VirtualServerTransport } from './virtual-network';
+export declare const MOVE_SPEED = 4;
+export declare const TICK_RATE = 24;
+export declare const STEP_SEC: number;
+export declare const FIXED_DT: number;
+export declare const Position: import("murow/ecs").Component<{
+    x: number;
+    z: number;
+} & object, {
+    x: import("murow/core").Field<number, Float32Array<ArrayBufferLike>>;
+    z: import("murow/core").Field<number, Float32Array<ArrayBufferLike>>;
+}>;
+export declare function buildSchema(): {
+    intents: import("..").DefinedIntents<{
+        move: {
+            dx: import("murow/core").Field<number, Float32Array<ArrayBufferLike>>;
+            dz: import("murow/core").Field<number, Float32Array<ArrayBufferLike>>;
+        };
+    }>;
+    rpcs: import("..").DefinedRpcs<{}>;
+    predictions: import("..").DefinedPredictions<{
+        move: {
+            dx: import("murow/core").Field<number, Float32Array<ArrayBufferLike>>;
+            dz: import("murow/core").Field<number, Float32Array<ArrayBufferLike>>;
+        };
+    }>;
+};
+export interface PeerSim {
+    id: number;
+    client: GameClient<any, any>;
+    world: World;
+    loop: GameLoop<'manual-client'>;
+    peer: Peer;
+    serverEntity: Entity;
+    localEntity: Entity | null;
+    dx: number;
+    dz: number;
+    sentIntents: number;
+    serverAppliedIntents: number;
+    reconciles: number;
+    /** Largest correction magnitude observed across all reconciles. */
+    maxCorrection: number;
+    /** Largest replay depth observed across all reconciles. */
+    maxReplayDepth: number;
+    /** Total number of snapshots received. */
+    snapshotsReceived: number;
+    /** Snapshots whose tick was not strictly greater than the previous. */
+    staleSnapshots: number;
+    /** Highest snapshot tick observed. */
+    lastSnapshotTick: number;
+    /** Predicted position captured the moment a snapshot frame arrives. */
+    _preReconcilePos: {
+        x: number;
+        z: number;
+    } | null;
+}
+export interface Harness {
+    rng: SimpleRNG;
+    vnet: VirtualNetwork;
+    transport: VirtualServerTransport;
+    serverLoop: GameLoop<'manual-server'>;
+    serverWorld: World;
+    server: GameServer<any, any>;
+    sims: PeerSim[];
+    serverIntentsByPeer: Map<string, number>;
+}
+export interface HarnessOptions {
+    seed: number;
+    numClients: number;
+    jitter: JitterConfig;
+    /** Override per-client unit movement direction. Defaults to evenly-spaced ring. */
+    direction?: (i: number, n: number, rng: SimpleRNG) => {
+        dx: number;
+        dz: number;
+    };
+    /** Override client GameClient options. */
+    interpDelayMs?: number;
+}
+export declare function makeHarness(opts: HarnessOptions): Harness;
+/**
+ * Run a no-loss bootstrap so every client receives its assignment, then
+ * (optionally) flip back to the jittery config for steady-state traffic.
+ * `bootstrap` defaults to "same config but lossChance=0".
+ *
+ * If `warmupTicks` is set, each client steps a random number of ticks in
+ * [0, warmupTicks] BEFORE the main scenario, so clients enter with
+ * different `localTick` values (simulating staggered join times).
+ */
+export declare function bootstrap(h: Harness, steadyState: JitterConfig, opts?: {
+    warmupTicks?: number;
+}): void;
+/** Drain pending packets with loss disabled so post-conditions can settle. */
+export declare function drain(h: Harness, jitter: JitterConfig, ticks?: number): void;
+/** Snapshot per-peer server-applied intent counts into each sim. */
+export declare function captureServerCounts(h: Harness): void;
+/** FNV-1a 32-bit hash over Position fields. Determinism probe. */
+export declare function hashPositions(world: World, entities: Entity[]): number;

package/dist/netcode/types/packets/index.d.ts

@@ -0,0 +1,2 @@
+export * from './virtual-network';
+export * from './harness';

package/dist/netcode/types/packets/intermittent-intents.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/netcode/types/packets/pathological.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/netcode/types/packets/peer-interpolation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/netcode/types/packets/reordering.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/netcode/types/packets/virtual-network.d.ts

@@ -0,0 +1,65 @@
+import { SimpleRNG } from 'murow/core/simple-rng';
+import type { TransportAdapter, ServerTransportAdapter } from 'murow/net';
+export interface JitterConfig {
+    baseLatencyMs: number;
+    jitterMs: number;
+    lossChance: number;
+    /**
+     * Chance per packet of having its arrival time perturbed enough to
+     * overtake or fall behind nearby packets. Real networks reorder; this
+     * stresses the netcode's resilience to out-of-order delivery.
+     */
+    reorderChance?: number;
+    /** Magnitude of the reorder skew, in ms. */
+    reorderSkewMs?: number;
+}
+export declare class VirtualNetwork {
+    private now;
+    private slots;
+    private seq;
+    nowMs(): number;
+    schedule(latencyMs: number, fn: () => void): void;
+    advance(ms: number): void;
+    pending(): number;
+}
+export declare class VirtualPeerTransport implements TransportAdapter {
+    readonly peerId: string;
+    private vnet;
+    private rng;
+    private cfg;
+    serverOnMessage: ((data: Uint8Array) => void) | null;
+    clientOnMessage: ((data: Uint8Array) => void) | null;
+    serverOnClose: (() => void) | null;
+    clientOnClose: (() => void) | null;
+    clientOnOpen: (() => void) | null;
+    closed: boolean;
+    constructor(peerId: string, vnet: VirtualNetwork, rng: SimpleRNG, cfg: JitterConfig);
+    setConfig(cfg: JitterConfig): void;
+    private schedule;
+    send(data: Uint8Array): void;
+    onOpen(_handler: () => void): void;
+    onMessage(handler: (data: Uint8Array) => void): void;
+    onClose(handler: () => void): void;
+    close(): void;
+    clientView(): TransportAdapter;
+    openClient(): void;
+}
+export declare class VirtualServerTransport implements ServerTransportAdapter<VirtualPeerTransport> {
+    private vnet;
+    private rng;
+    cfg: JitterConfig;
+    private peers;
+    private connectionHandler;
+    private nextId;
+    constructor(vnet: VirtualNetwork, rng: SimpleRNG, cfg: JitterConfig);
+    setConfig(cfg: JitterConfig): void;
+    onConnection(handler: (peer: VirtualPeerTransport, peerId: string) => void): void;
+    onDisconnection(_handler: (peerId: string) => void): void;
+    getPeer(peerId: string): VirtualPeerTransport | undefined;
+    getPeerIds(): string[];
+    close(): void;
+    connectClient(): {
+        client: TransportAdapter;
+        peerId: string;
+    };
+}

package/dist/netcode/types/predictions/define-predictions.d.ts

@@ -0,0 +1,45 @@
+import type { DefinedIntents, IntentPayload, IntentSchemaMap } from '../intents/define-intents';
+import type { PredictionContext } from '../ctx';
+/**
+ * A single prediction function. Pure deterministic logic that mutates
+ * `ctx.world` given a typed intent payload. The same function runs on
+ * the server as the authoritative apply and on the client as the
+ * predicted apply (plus rollback replay during reconciliation).
+ */
+export type PredictionFn<P> = (payload: P, ctx: PredictionContext) => void;
+/**
+ * Bundle of predictions keyed by intent name. Partial: not every intent
+ * needs a prediction. Intents without an entry here are server-only and
+ * should register through `defineHandlers` instead.
+ */
+export type PredictionMap<I extends IntentSchemaMap> = {
+    [K in keyof I]?: PredictionFn<IntentPayload<I, K>>;
+};
+/**
+ * Tagged bundle returned by `definePredictions`. Pass to both
+ * `server.use(predictions)` and `client.use(predictions)`.
+ */
+export interface DefinedPredictions<I extends IntentSchemaMap> {
+    readonly __kind: 'predictions';
+    readonly intents: DefinedIntents<I>;
+    readonly map: PredictionMap<I>;
+}
+/**
+ * Bundle predictions for an intent schema. The same module is used on
+ * both sides; the server applies authoritatively, the client predicts
+ * locally and rolls back on disagreement.
+ *
+ * Predictions must be deterministic: no `Math.random`, no `Date.now`, no
+ * I/O. Use `ctx.rng`, `ctx.tick`, `ctx.deltaTime`.
+ *
+ * @example
+ * const predictions = definePredictions(intents, {
+ *   move: ({ dx, dy }, ctx) => {
+ *     ctx.world.update(ctx.entity, Velocity, { vx: dx, vy: dy });
+ *   },
+ * });
+ *
+ * server.use(predictions);
+ * client.use(predictions);
+ */
+export declare function definePredictions<I extends IntentSchemaMap>(intents: DefinedIntents<I>, map: PredictionMap<I>): DefinedPredictions<I>;

package/dist/netcode/types/predictions/define-predictions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/netcode/types/predictions/index.d.ts

@@ -0,0 +1 @@
+export * from './define-predictions';

package/dist/netcode/types/reconciliation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/netcode/types/rpcs/define-rpcs.d.ts

@@ -0,0 +1,44 @@
+import { RpcRegistry, defineRPC } from 'murow/protocol';
+/**
+ * User-supplied schema map for `defineRpcs`. Each entry maps an RPC
+ * method name to its field schema.
+ */
+export type RpcSchemaMap = Record<string, Record<string, any>>;
+/** Payload type for a named RPC, inferred from its schema. */
+export type RpcPayload<R extends RpcSchemaMap, K extends keyof R> = {
+    [P in keyof R[K]]: R[K][P] extends {
+        read(dv: DataView, o: number): infer T;
+    } ? T : never;
+};
+/**
+ * Result of `defineRpcs`. `registry` plugs into `GameServer`/`GameClient`
+ * via the `protocol` option; `__payloads` is a phantom used purely for
+ * type inference on `sendRpc`/`broadcastRpc` call sites.
+ */
+export interface DefinedRpcs<R extends RpcSchemaMap> {
+    /** Underlying `DefinedRPC` objects keyed by method name. */
+    readonly defs: {
+        readonly [K in keyof R]: ReturnType<typeof defineRPC<R[K]>>;
+    };
+    /** Pre-populated registry ready to plug into the network layer. */
+    readonly registry: RpcRegistry;
+    /** Phantom field for type inference, never read at runtime. */
+    readonly __payloads: {
+        [K in keyof R]: RpcPayload<R, K>;
+    };
+}
+/**
+ * Declare every RPC the game uses in one map. RPCs are bidirectional;
+ * the same registry serves `server.sendRpc`/`server.broadcastRpc` and
+ * `client.sendRpc`.
+ *
+ * @example
+ * const rpcs = defineRpcs({
+ *   matchStart: { countdownSec: u8 },
+ *   buyItem:    { itemId: string(32) },
+ * });
+ *
+ * server.broadcastRpc('matchStart', { countdownSec: 3 });
+ * client.on('rpc', ({ name, payload }) => { ... });
+ */
+export declare function defineRpcs<R extends RpcSchemaMap>(rpcs: R): DefinedRpcs<R>;

package/dist/netcode/types/rpcs/define-rpcs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/netcode/types/rpcs/index.d.ts

@@ -0,0 +1 @@
+export * from './define-rpcs';

package/dist/netcode/types/server/game-server.d.ts

@@ -0,0 +1,77 @@
+import type { Entity, World } from 'murow/ecs';
+import type { GameLoop } from 'murow/game';
+import type { ServerTransportAdapter, TransportAdapter } from 'murow/net';
+import { Network } from '../network/base';
+import type { DefinedIntents, IntentSchemaMap } from '../intents/define-intents';
+import type { DefinedRpcs, RpcPayload, RpcSchemaMap } from '../rpcs/define-rpcs';
+import type { DefinedPredictions } from '../predictions/define-predictions';
+import type { DefinedHandlers } from '../handlers/define-handlers';
+import type { ServerPlugin } from './plugins/plugin';
+import { type Peer } from '../ctx';
+export interface GameServerOptions<I extends IntentSchemaMap, R extends RpcSchemaMap> {
+    world: World;
+    loop: GameLoop<any>;
+    transport: ServerTransportAdapter<TransportAdapter>;
+    protocol: {
+        intents: DefinedIntents<I>;
+        rpcs: DefinedRpcs<R>;
+    };
+    snapshot?: {
+        /** Snapshots per second. Clamped to tickRate. Default 20. */
+        rate?: number;
+    };
+    kick?: {
+        /** Ms before forcing transport close after a kick. Default 2000. */
+        ackTimeout?: number;
+    };
+    /** Optional schema fingerprint for component-layout drift checks. */
+    schemaFingerprint?: string;
+}
+export declare class GameServer<I extends IntentSchemaMap = IntentSchemaMap, R extends RpcSchemaMap = RpcSchemaMap> extends Network<'server', R> {
+    readonly world: World;
+    readonly loop: GameLoop<any>;
+    readonly transport: ServerTransportAdapter<TransportAdapter>;
+    readonly intents: DefinedIntents<I>;
+    readonly rpcs: DefinedRpcs<R>;
+    private peers;
+    private predictionMap;
+    private handlerMap;
+    private plugins;
+    private lagComp;
+    private syncedComponents;
+    private syncedNumMaskWords;
+    private snapshotEvery;
+    private tickCounter;
+    private kickAckTimeout;
+    private rng;
+    private scratch;
+    private lastDt;
+    constructor(opts: GameServerOptions<I, R>);
+    private discoverSyncedComponents;
+    private wireTransport;
+    private handleDisconnect;
+    private wireLoop;
+    private drainIntentQueues;
+    private sendSnapshots;
+    private anyNeedsBaseline;
+    private handleIncoming;
+    private handleIntent;
+    private handleRpc;
+    use(bundle: DefinedPredictions<I>): this;
+    use(bundle: DefinedHandlers<I>): this;
+    use(plugin: ServerPlugin): this;
+    /**
+     * Bind an entity to a peer. Fills `ctx.entity` for the peer's intents
+     * and pushes a MSG_ASSIGN_ENTITY frame so the client knows which
+     * entity it owns.
+     */
+    assignEntity(peer: Peer, entityId: Entity): void;
+    sendRpc<K extends keyof R & string>(peer: Peer, name: K, payload: RpcPayload<R, K>): void;
+    broadcastRpc<K extends keyof R & string>(name: K, payload: RpcPayload<R, K>): void;
+    /**
+     * Soft-kick: send KICK frame, wait `kick.ackTimeout` for the client's
+     * ack, then force the transport closed.
+     */
+    kick(peer: Peer, reason: string): void;
+    private completeKick;
+}

package/dist/netcode/types/server/index.d.ts

@@ -0,0 +1,2 @@
+export * from './game-server';
+export * from './plugins';

package/dist/netcode/types/server/plugins/aoi-grid.d.ts

@@ -0,0 +1,34 @@
+import type { Component, Entity, World } from 'murow/ecs';
+import type { Peer } from '../../ctx';
+import type { ServerPlugin } from './plugin';
+export interface AoiGridOptions {
+    /** Plugin identifier; matches `sync.interest` strings on components. Default `'aoi'`. */
+    name?: string;
+    /** Reserved for grid acceleration. v1 does a naive radius scan. */
+    cellSize: number;
+    /** AOI radius around each peer (world units). */
+    radius: number;
+    /** Extra slack on the despawn boundary. Default 0. */
+    hysteresisRadius?: number;
+    /** Component holding `{ x, y }` positions used to compute distance. */
+    positionComponent: Component<{
+        x: number;
+        y: number;
+    }>;
+}
+/**
+ * Spatial interest plugin. Per-tick, filters dirty entities to those
+ * within `radius + hysteresisRadius` of each peer's assigned entity.
+ *
+ * v1 is O(peers * dirty). A grid accelerator can slot in without
+ * changing the public surface.
+ */
+export declare class AoiGrid implements ServerPlugin {
+    readonly name: string;
+    readonly cellSize: number;
+    readonly radius: number;
+    readonly hysteresisRadius: number;
+    private positionComponent;
+    constructor(opts: AoiGridOptions);
+    filterSnapshot(peer: Peer, world: World, dirtyEntities: ReadonlyArray<Entity>, out: Entity[]): void;
+}

package/dist/netcode/types/server/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export * from './plugin';
+export * from './aoi-grid';
+export * from './lag-compensation';

package/dist/netcode/types/server/plugins/lag-compensation.d.ts

@@ -0,0 +1,34 @@
+import type { Component, World } from 'murow/ecs';
+import type { ServerPlugin } from './plugin';
+export interface LagCompensationOptions {
+    /** Plugin identifier. Default `'lag-compensation'`. */
+    name?: string;
+    /** How far back to keep state history (ms). Default 500. */
+    historyMs?: number;
+    /** Tick rate of the simulation; used to size the ring buffer. */
+    tickRate: number;
+    /** Components whose history is recorded for rewind. */
+    components: Component<any>[];
+}
+/**
+ * Records the configured components every tick for `historyMs` worth of
+ * frames. `rewind(clientTick, fn)` overlays the historical state for the
+ * duration of `fn`, then restores. Used inside server-only handlers for
+ * hit detection that's fair across players with different pings.
+ */
+export declare class LagCompensation implements ServerPlugin {
+    readonly name: string;
+    readonly historyMs: number;
+    readonly tickRate: number;
+    private components;
+    private componentIndices;
+    private ringBuffer;
+    private ringSize;
+    private ringHead;
+    private currentTick;
+    private world;
+    constructor(opts: LagCompensationOptions);
+    onMount(server: any): void;
+    onTick(_world: World, _dt: number): void;
+    rewind<T>(clientTick: number, fn: () => T): T;
+}

package/dist/netcode/types/server/plugins/plugin.d.ts

@@ -0,0 +1,24 @@
+import type { Entity, World } from 'murow/ecs';
+import type { Peer, ServerHandlerContext } from '../../ctx';
+export interface ServerPlugin {
+    readonly name: string;
+    onMount?(server: any): void;
+    onUnmount?(server: any): void;
+    onTick?(world: World, deltaTime: number): void;
+    /** Observe-only. Return value is ignored. */
+    onIntent?(peer: Peer, kind: number, name: string, payload: unknown, ctx: ServerHandlerContext): void;
+    /**
+     * Filter `dirtyEntities` down to those visible to `peer`. Push
+     * visible entities onto `out` (pre-cleared by the engine). Plugins
+     * compose in registration order on the same scratch array.
+     */
+    filterSnapshot?(peer: Peer, world: World, dirtyEntities: ReadonlyArray<Entity>, out: Entity[]): void;
+    onDisconnect?(peer: Peer): void;
+}
+export interface ClientPlugin {
+    readonly name: string;
+    onMount?(client: any): void;
+    onUnmount?(client: any): void;
+    onTick?(world: World, deltaTime: number): void;
+    onSnapshot?(tick: number): void;
+}

package/dist/netcode/types/tick-rate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/netcode/types/transports/index.d.ts

@@ -0,0 +1 @@
+export * from './memory-transport';

package/dist/netcode/types/transports/memory-transport.d.ts

@@ -0,0 +1,51 @@
+import type { TransportAdapter, ServerTransportAdapter } from 'murow/net';
+/**
+ * In-process transport pair for tests. Wires a server adapter and one or
+ * more client adapters together via microtask delivery. No queueing, no
+ * latency simulation; `send` schedules a microtask to deliver to the
+ * matching `onMessage`.
+ */
+export declare class MemoryServerTransport implements ServerTransportAdapter<MemoryPeerTransport> {
+    private peers;
+    private connectionHandler;
+    private disconnectionHandler;
+    private nextPeerId;
+    onConnection(handler: (peer: MemoryPeerTransport, peerId: string) => void): void;
+    onDisconnection(handler: (peerId: string) => void): void;
+    getPeer(peerId: string): MemoryPeerTransport | undefined;
+    getPeerIds(): string[];
+    /**
+     * Simulate a client connection. Returns the client-side adapter and
+     * the server-assigned peer id. Fires the server's connection handler
+     * synchronously; the client's `onOpen` fires on the next microtask.
+     */
+    connectClient(): {
+        client: TransportAdapter;
+        peerId: string;
+    };
+    /** Called by a peer when it disconnects. */
+    _peerClosed(peerId: string): void;
+    close(): void;
+}
+/**
+ * Internal server-side adapter, one per connected peer. `send` goes to
+ * the client; `onMessage` fires when the client sends.
+ */
+export declare class MemoryPeerTransport implements TransportAdapter {
+    readonly peerId: string;
+    private server;
+    private serverMessageHandler;
+    private serverCloseHandler;
+    private clientMessageHandler;
+    private clientCloseHandler;
+    private clientOpenHandler;
+    constructor(peerId: string, server: MemoryServerTransport);
+    send(data: Uint8Array): void;
+    onOpen(_handler: () => void): void;
+    onMessage(handler: (data: Uint8Array) => void): void;
+    onClose(handler: () => void): void;
+    close(): void;
+    /** Client-side adapter view: sends to the server, observes server messages. */
+    clientView(): TransportAdapter;
+    _openClient(): void;
+}

package/dist/netcode/types/types.test.d.ts

@@ -0,0 +1 @@
+export {};