@pylonsync/realtime 0.14.0

package/README.md

@@ -0,0 +1,30 @@
+# @pylonsync/realtime
+
+The Pylon shard client with no framework: the wire protocol, the entity
+replication decoder, and the pieces a game's render loop needs.
+
+- `connectShardGame(shardId, options)`: a connection that applies each
+  replication frame and places entities for a render frame
+  (`game.frame(now)`), with interpolation, a server clock estimate,
+  prediction for the local player, the input round trip, and reconnects
+  with a full frame.
+- `connectShard(shardId, options)`: the connection alone.
+- `EntityTable`: applies replication frames.
+- `EntityInterpolator`, `ShardClock`, `Predictor`: the parts on their own.
+
+```ts
+import { connectShardGame } from "@pylonsync/realtime";
+
+const game = connectShardGame<Input>("zone-1", { subscriberId, ticket, tickRate: 20 });
+
+function frame(now: number) {
+  game.frame(now);
+  for (const id of game.left) removeMesh(id);
+  for (const id of game.entered) addMesh(id);
+  for (const e of game.entities.values()) moveMesh(e.id, e.x, e.y, e.z);
+  requestAnimationFrame(frame);
+}
+requestAnimationFrame(frame);
+```
+
+See the shards guide: https://docs.pylonsync.com/concepts/shards

package/dist/clock.d.ts

@@ -0,0 +1,74 @@
+/**
+ * An estimate of the shard's current tick, from the ticks in the frames it
+ * sends and when they arrive.
+ *
+ * Each frame carries the tick it was built on. The frame that arrived
+ * soonest after it was built (lowest delay) anchors the estimate, so
+ * network jitter only ever makes a frame look late. The tick length is the
+ * shard's tick rate when the client knows it, or else the median slope of
+ * arrival time against tick.
+ *
+ * The estimate is continuous: when a new frame moves it, the change is
+ * spread over time instead of jumping (from `slew` of real time for small
+ * changes up to all of it). A step forward larger than `snapMs` applies at
+ * once. A step back larger than that applies only as far as the newest
+ * tick received, so it never goes back past a tick a frame carried.
+ *
+ * After three frames in a row arrive more than `snapMs` late and spaced
+ * like ticks (a shard that stalled), the older frames are dropped and the
+ * clock follows the new schedule. Frames that arrive together (a network
+ * burst) do not count.
+ */
+export interface ShardClockOptions {
+    /** The shard's tick rate in ticks per second, when the client knows it. */
+    tickRate?: number;
+    /** Frames the estimate uses. Default 64. */
+    window?: number;
+    /** The least fraction of real time the estimate speeds up or slows
+     *  down by to absorb a correction. Default 0.05. */
+    slew?: number;
+    /** A step forward larger than this (ms) applies at once, and a
+     *  correction this large or larger runs at full rate. Default 250. */
+    snapMs?: number;
+}
+export declare class ShardClock {
+    private readonly fixedTickMs;
+    private readonly window;
+    private readonly slew;
+    private readonly snapMs;
+    private samples;
+    private measuredTickMs;
+    /** The newest tick seen, and the estimated arrival time of a frame for
+     *  it with the lowest delay seen. */
+    private anchorTick;
+    private anchorAt;
+    /** Ticks the displayed estimate is ahead of the raw one; decays to 0. */
+    private offset;
+    private slewedTo;
+    /** Frames in a row that arrived more than `snapMs` after the anchor
+     *  predicted. */
+    private late;
+    constructor(options?: ShardClockOptions);
+    /** True once a frame has arrived. */
+    get ready(): boolean;
+    /** The newest tick a frame carried, or -1. */
+    get latestTick(): number;
+    /** Milliseconds per tick: the configured rate, or the measured one. */
+    get tickMs(): number;
+    /** Forget everything (a new shard). */
+    reset(): void;
+    /** Record a frame for `tick` that arrived at `at` (ms, monotonic). */
+    observe(tick: number, at: number): void;
+    /**
+     * The estimated tick the shard is on at `now` (ms, same clock as
+     * `observe`), with a fraction. Before the first frame, -1.
+     */
+    serverTick(now: number): number;
+    private raw;
+    /**
+     * The median slope of arrival time against tick over every pair of
+     * samples (Theil-Sen): frames that arrive together in a burst are a
+     * minority of pairs and do not pull it.
+     */
+    private fitTickMs;
+}

package/dist/connection.d.ts

@@ -0,0 +1,95 @@
+/**
+ * A shard connection with no framework: one WebSocket, reconnected with
+ * backoff, that decodes frames, applies replication frames to an
+ * `EntityTable`, and sends inputs. `useShard` in `@pylonsync/react` and
+ * `connectShardGame` build on it.
+ */
+import { ShardClock } from "./clock";
+import { EntityTable, type ReplicationSummary } from "./replication";
+import { type ShardInputRejection, type ShardPayloadDecoder } from "./wire";
+export interface ShardConnectOptions {
+    /** Subscriber ID (usually the logged-in user ID). Required for multiplayer. */
+    subscriberId: string;
+    /**
+     * Auth token. Sent as a `bearer.<token>` WebSocket subprotocol, which
+     * keeps it out of URLs (proxy logs, devtools, and error telemetry record
+     * URLs, not subprotocols).
+     */
+    token?: string;
+    /**
+     * Shard ticket from a server function (`ctx.shards.ticket(...)`). Sent as
+     * a `ticket.<ticket>` WebSocket subprotocol. The shard checks it names
+     * this shard and `subscriberId`, and passes its claims to the game's
+     * authorization hooks.
+     *
+     * Tickets expire. Pass a function to get a new one for each connection
+     * attempt, so a reconnect after the expiry still gets in.
+     */
+    ticket?: string | (() => string | Promise<string>);
+    /** Host (and port) of the Pylon server. Defaults to `window.location.host`. */
+    baseUrl?: string;
+    /**
+     * Connect to the dedicated shard port instead of `/shard` on the main
+     * port (the dedicated port is the HTTP port + 3, e.g. 4324).
+     */
+    wsPort?: number;
+    /** Explicit WebSocket URL. Overrides baseUrl/wsPort. */
+    wsUrl?: string;
+    /** Reconnect on unexpected close (default: true). */
+    autoReconnect?: boolean;
+    /** First reconnect delay in ms (default 500; doubles to at most 10 000). */
+    reconnectBackoffMs?: number;
+    /**
+     * Decoder for a payload codec the client does not know: bincode (`2`) or
+     * a game's own codec (`3`). JSON and MessagePack are built in.
+     */
+    decode?: ShardPayloadDecoder;
+    /** The shard's tick rate, when known; otherwise the clock measures it. */
+    tickRate?: number;
+    /** Monotonic time in ms. Default `performance.now()`. */
+    now?: () => number;
+}
+export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
+    /** `ack` is the highest `send()` sequence number the shard has processed. */
+    onSnapshot: (fn: (snapshot: TSnapshot, tick: number, ack: number) => void) => void;
+    /** Called when the shard refuses an input (see `ShardInputRejection.code`). */
+    onInputRejected: (fn: (rejection: ShardInputRejection) => void) => void;
+    /**
+     * For a shard that replicates entities: called after each frame is
+     * applied to `entities`, with what it changed.
+     */
+    onReplication: (fn: (entities: EntityTable, summary: ReplicationSummary, tick: number, ack: number) => void) => void;
+    /**
+     * The entities a replicating shard has sent this client. Read it each
+     * frame (a render loop); it changes in place as frames arrive.
+     */
+    readonly entities: EntityTable;
+    /** The shard's current tick, estimated from frame arrivals. */
+    readonly clock: ShardClock;
+    /** The tick of the last frame, or -1. */
+    readonly tick: number;
+    /** The ack of the last frame. */
+    readonly ack: number;
+    /**
+     * Smoothed time from sending an input to the first frame that
+     * acknowledges it (ms), or null before one has. It includes the wait for
+     * the shard's next tick.
+     */
+    readonly rttMs: number | null;
+    onError: (fn: (err: Error) => void) => void;
+    onOpen: (fn: () => void) => void;
+    onClose: (fn: () => void) => void;
+    /**
+     * Send an input. Returns its sequence number, which later frames
+     * acknowledge, or 0 when the connection is not open (the input is not
+     * sent, and `onError` hears why).
+     */
+    send: (input: TInput) => number;
+    close: () => void;
+    readonly connected: boolean;
+}
+/**
+ * Connect to a shard without React. Returns a client you can wire into any
+ * framework or render loop.
+ */
+export declare function connectShard<TSnapshot = unknown, TInput = unknown>(shardId: string, options: ShardConnectOptions): ShardClient<TSnapshot, TInput>;

package/dist/game.d.ts

@@ -0,0 +1,80 @@
+/**
+ * A shard client for a game's render loop: the connection, the clock,
+ * interpolated entities, and prediction, with no framework and no
+ * re-render per frame.
+ *
+ * ```ts
+ * const game = connectShardGame("zone-1", { subscriberId, ticket, tickRate: 20 });
+ * const me = game.predict<Vec3>((p, input) => move(p, input));
+ *
+ * function frame(now: number) {
+ *   game.frame(now); // places game.entities at the render tick
+ *   for (const e of game.entities.values()) draw(e.id, e.x, e.y, e.z);
+ *   requestAnimationFrame(frame);
+ * }
+ * requestAnimationFrame(frame);
+ *
+ * game.onReplication((table, _summary, _tick, ack) => {
+ *   const mine = table.get(myEntityId);
+ *   if (mine) local = me.reconcile({ x: mine.x, y: mine.y, z: mine.z }, ack);
+ * });
+ * onKey((input) => {
+ *   // 0: not sent (the connection is down), so do not predict it.
+ *   if (game.send(input)) local = move(local, input);
+ * });
+ * ```
+ */
+import type { ShardClock } from "./clock";
+import { type ShardClient, type ShardConnectOptions } from "./connection";
+import { type InterpolatedEntity, type InterpolationOptions } from "./interpolation";
+import { Predictor, type PredictorOptions } from "./prediction";
+import type { EntityTable, ReplicationSummary } from "./replication";
+import type { ShardInputRejection } from "./wire";
+export interface ShardGameOptions extends ShardConnectOptions {
+    /**
+     * How far behind the shard's estimated current tick entities are drawn,
+     * in ms. It must cover the time between frames plus network jitter.
+     * Default 100.
+     */
+    interpolationDelayMs?: number;
+    interpolation?: InterpolationOptions;
+}
+export interface ShardGame<TInput = unknown> {
+    /** The underlying connection. */
+    readonly connection: ShardClient<unknown, TInput>;
+    readonly clock: ShardClock;
+    /** Entities placed at the render tick by the last `frame` call. */
+    readonly entities: ReadonlyMap<number, InterpolatedEntity>;
+    /** Ids the last `frame` added to and removed from `entities`. */
+    readonly entered: readonly number[];
+    readonly left: readonly number[];
+    /** The newest state the shard sent, not interpolated. */
+    readonly latest: EntityTable;
+    readonly tick: number;
+    readonly ack: number;
+    readonly rttMs: number | null;
+    readonly connected: boolean;
+    /**
+     * Place `entities` for a render frame at `now` (ms, default
+     * `performance.now()`). Returns the render tick, or -1 before the first
+     * frame.
+     */
+    frame(now?: number): number;
+    /** Send an input; every predictor made by `predict` records it. Returns
+     *  its sequence number, or 0 when it was not sent. */
+    send(input: TInput): number;
+    /**
+     * A predictor that records every input `send` sends, forgets inputs the
+     * shard refuses, and resets when the connection reopens. Call
+     * `reconcile` with the local entity's server state after each frame.
+     */
+    predict<S>(step: (state: S, input: TInput) => S, options?: PredictorOptions): Predictor<S, TInput>;
+    onReplication(fn: (entities: EntityTable, summary: ReplicationSummary, tick: number, ack: number) => void): void;
+    onInputRejected(fn: (rejection: ShardInputRejection) => void): void;
+    onOpen(fn: () => void): void;
+    onClose(fn: () => void): void;
+    onError(fn: (err: Error) => void): void;
+    close(): void;
+}
+/** Connect to a replicating shard for a render loop. */
+export declare function connectShardGame<TInput = unknown>(shardId: string, options: ShardGameOptions): ShardGame<TInput>;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./wire";
+export * from "./replication";
+export * from "./clock";
+export * from "./interpolation";
+export * from "./prediction";
+export * from "./connection";
+export * from "./game";

package/dist/interpolation.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Entity interpolation for render loops.
+ *
+ * Record every replication frame with the tick it was built on; each render
+ * frame, call `update` with a tick a little behind the server's (see
+ * `ShardClock`). Each entity is then drawn between the two samples around
+ * that tick, so motion is smooth even though frames arrive at the tick rate
+ * and with jitter. Spawns, despawns, and component changes appear at the
+ * tick they happened, in step with the positions.
+ */
+import type { EntityTable, ReplicationSummary } from "./replication";
+export interface InterpolationOptions {
+    /**
+     * A move longer than this (world units) between two samples is a
+     * teleport: the entity jumps instead of sliding. Default: no limit.
+     */
+    snapDistance?: number;
+    /**
+     * Treat an entity that sent no update as not moving, so its next move
+     * starts from the tick before it arrives. Default true. Set false for a
+     * shard with a byte budget (`max_bytes_per_tick`), where updates can
+     * wait for later ticks.
+     */
+    holdWhenQuiet?: boolean;
+    /** Samples kept per entity. Default 32. */
+    maxSamples?: number;
+}
+/** An entity's state at one tick. */
+export interface EntitySample {
+    readonly tick: number;
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    /** Component id to bytes. Shared between samples; do not change it. */
+    readonly components: ReadonlyMap<number, Uint8Array>;
+}
+/** One entity as drawn at the render tick. The object is reused. */
+export interface InterpolatedEntity {
+    readonly id: number;
+    x: number;
+    y: number;
+    z: number;
+    /** Components as of the sample at or before the render tick. */
+    components: ReadonlyMap<number, Uint8Array>;
+    /**
+     * The samples around the render tick and the fraction between them, to
+     * interpolate game data kept in components (a heading, a health bar).
+     * `from` and `to` are the same sample when there is no later one.
+     */
+    from: EntitySample;
+    to: EntitySample;
+    t: number;
+}
+export declare class EntityInterpolator {
+    /** Entities that exist at the last `update`'s render tick. */
+    readonly entities: Map<number, InterpolatedEntity>;
+    /**
+     * Ids the last `update` added to `entities`. An id in both `left` and
+     * `entered` names a new entity that reused the id: rebuild what you
+     * drew for it.
+     */
+    readonly entered: number[];
+    /** Ids the last `update` removed from `entities`. */
+    readonly left: number[];
+    private readonly lives;
+    /** The life each entry in `entities` shows. */
+    private readonly shown;
+    private readonly snapDistance;
+    private readonly holdWhenQuiet;
+    private readonly maxSamples;
+    private lastTick;
+    /** The newest tick the last `update` drew; a render tick never goes
+     *  below it. */
+    private floor;
+    /** Lives that ended, oldest first, so `record` can drop them when
+     *  `update` does not run (a hidden tab keeps receiving frames). */
+    private ended;
+    constructor(options?: InterpolationOptions);
+    /** The newest tick recorded, or -1. */
+    get latestTick(): number;
+    /** Forget everything. The next `update` removes every entity. */
+    clear(): void;
+    /**
+     * Record the table after a replication frame for `tick` applied, with the
+     * summary `EntityTable.apply` returned.
+     */
+    record(table: EntityTable, summary: ReplicationSummary, tick: number): void;
+    /**
+     * Place every entity at `renderTick` (fractional). A render tick below
+     * one already drawn is raised to it, so nothing drawn goes back in time.
+     */
+    update(renderTick: number): void;
+    private end;
+    /**
+     * Forget lives that ended long before `tick`. `update` removes them
+     * when it runs; this bounds them when it does not.
+     */
+    private dropEnded;
+    private openLife;
+    private spawn;
+    private push;
+    private place;
+    private remove;
+}

package/dist/prediction.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Client-side prediction for the local player.
+ *
+ * Apply each input locally as it is sent, and keep it until the shard
+ * acknowledges it. When a frame arrives with the server's state and its
+ * `ack` (the highest input sequence number the shard has processed), start
+ * from the server's state and apply the inputs it has not processed yet.
+ * The result is where the local player is after every input, corrected by
+ * whatever the server decided.
+ *
+ * `step` must be deterministic and must match what the shard does with an
+ * input closely enough that the replayed state agrees with the server's.
+ * It must not change `state` in place; return a new one.
+ */
+export interface PredictorOptions {
+    /**
+     * Inputs kept while waiting for an ack. Past this the oldest are
+     * dropped (the prediction then misses them). Default 256.
+     */
+    maxPending?: number;
+}
+export declare class Predictor<S, I> {
+    private readonly step;
+    private pending;
+    private readonly maxPending;
+    constructor(step: (state: S, input: I) => S, options?: PredictorOptions);
+    /** Inputs sent and not yet acknowledged. */
+    get size(): number;
+    /** Record an input sent with sequence number `seq`. A `seq` of 0 (not
+     *  sent) is ignored. */
+    push(seq: number, input: I): void;
+    /** The shard refused input `seq`: it will never apply. */
+    reject(seq: number | null): void;
+    /**
+     * The predicted state: `server` (the shard's state as of a frame) with
+     * every input after `ack` applied. Inputs up to `ack` are dropped.
+     */
+    reconcile(server: S, ack: number): S;
+    /**
+     * Drop every pending input. Call it when the connection reopens: inputs
+     * sent on the old connection either applied before it closed (and are
+     * in the server's state) or never will.
+     */
+    reset(): void;
+}

package/dist/replication.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Entity replication frames (see `pylon_replication::frame` in Rust).
+ *
+ * A shard that replicates entities sends each subscriber, per tick, the
+ * entities that left its view (despawn), came into view (spawn, full
+ * state), or changed (update: only the axes that moved, as a quantized
+ * difference, and the components that changed or were removed).
+ * {@link EntityTable} applies them; after each frame it holds what the
+ * server says this subscriber sees.
+ *
+ * ```text
+ * u8      version (1)
+ * u8      flags: bit 0 FULL: clear the table first
+ * f32 LE  precision
+ * varint  despawn count, ids (first absolute, then differences; ascending)
+ * varint  spawn count, per entity: id, x, y, z (zigzag, quantized), components
+ * varint  update count, per entity: id, u8 mask (1 x, 2 y, 4 z, 8 components),
+ *         changed axes (zigzag differences), components if bit 8
+ * components: varint count, per component: u8 id, varint (length + 1),
+ *         bytes; length field 0 means removed
+ * ```
+ *
+ * JavaScript numbers hold integers exactly up to 2^53. Entity ids and
+ * quantized positions must stay below that; a frame that exceeds it is
+ * refused rather than rounded.
+ */
+export declare const REPLICATION_VERSION = 1;
+export declare class ReplicationError extends Error {
+    constructor(message: string);
+}
+/** One entity as the client sees it. */
+export interface ReplicatedEntity {
+    readonly id: number;
+    /** Quantized position; `x/y/z` are these times the frame precision. */
+    qx: number;
+    qy: number;
+    qz: number;
+    x: number;
+    y: number;
+    z: number;
+    /** Component id to bytes, in the game's own encoding. */
+    components: Map<number, Uint8Array>;
+}
+/** What one frame did. */
+export interface ReplicationSummary {
+    full: boolean;
+    spawned: number[];
+    updated: number[];
+    despawned: number[];
+}
+/**
+ * The entities one subscriber has been told about. Apply every
+ * replication frame in order; a frame that fails to apply means the
+ * connection is out of sync and should be reopened (the server then sends
+ * a full frame).
+ */
+export declare class EntityTable {
+    readonly entities: Map<number, ReplicatedEntity>;
+    /** World units per quantization step, from the last frame. */
+    precision: number;
+    get size(): number;
+    get(id: number): ReplicatedEntity | undefined;
+    clear(): void;
+    apply(frame: Uint8Array): ReplicationSummary;
+}

package/dist/wire.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The shard wire protocol, version 2 (see `pylon_realtime::wire` in Rust).
+ *
+ * A client asks for it with `?v=2` on the shard WebSocket URL. Each server
+ * message is a binary frame with an 18-byte header:
+ *
+ *   0   1  frame kind: 1 snapshot, 2 input rejected, 3 entity replication
+ *   1   1  codec: 0 JSON, 1 MessagePack, 2 bincode, 3 custom, 4 replication
+ *   2   8  tick (u64 big-endian)
+ *   10  8  ack: highest client_seq the shard processed for this subscriber (0 = none)
+ *   18  .. payload in the codec
+ *
+ * Inputs go up as `{ input, client_seq }`: JSON in a text frame, or the
+ * shard's codec in a binary frame.
+ */
+export declare const SHARD_PROTOCOL_VERSION = 2;
+export declare const SHARD_HEADER_LEN = 18;
+export declare const ShardFrameKind: {
+    readonly Snapshot: 1;
+    readonly InputRejected: 2;
+    /** An entity replication frame: apply it to an `EntityTable`. */
+    readonly Replication: 3;
+};
+export declare const ShardCodec: {
+    readonly Json: 0;
+    readonly MessagePack: 1;
+    readonly Bincode: 2;
+    readonly Custom: 3;
+    /** The replication frame format (frame kind 3). */
+    readonly Replication: 4;
+};
+export interface ShardFrame {
+    kind: number;
+    codec: number;
+    tick: number;
+    ack: number;
+    payload: Uint8Array;
+}
+/** Why an input did not take effect. */
+export interface ShardInputRejection {
+    clientSeq: number | null;
+    /** `unauthorized`, `rate_limited`, `queue_full`, `invalid`, `stopped`, or `apply_failed`. */
+    code: string;
+    message: string;
+}
+/**
+ * Decode a payload in a codec the JS client does not know (bincode, or a
+ * game's own codec `3`).
+ */
+export type ShardPayloadDecoder = (payload: Uint8Array, codec: number) => unknown;
+/** Split a version 2 frame into its header fields and payload. */
+export declare function parseShardFrame(data: ArrayBuffer): ShardFrame;
+/** Decode a payload. JSON and MessagePack are built in. */
+export declare function decodeShardPayload(codec: number, payload: Uint8Array, custom?: ShardPayloadDecoder): unknown;
+/** The payload of an input-rejected frame, with camelCase fields. */
+export declare function decodeShardRejection(codec: number, payload: Uint8Array, custom?: ShardPayloadDecoder): ShardInputRejection;
+/**
+ * Encode an input envelope. MessagePack shards get a binary frame; every
+ * other codec (and a connection that has not seen a frame yet) gets JSON
+ * text, which the server always accepts.
+ */
+export declare function encodeShardInput(codec: number | null, input: unknown, clientSeq: number): string | Uint8Array;

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@pylonsync/realtime",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.14.0",
+  "description": "Pylon realtime shard client pieces with no framework: the wire protocol, codecs, and the entity replication decoder and table.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.3"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ]
+}