@helix3/helix-sdk 0.1.1-helix3.20

package/dist/multiplayer-contract/room.d.ts

@@ -0,0 +1,126 @@
+import type { Vec3, Quat } from './state';
+import type { PlayerIdentity, PlayerReplicaState } from './state';
+/**
+ * The runtime value vocabulary for declared custom state. A `ref`-typed var's value is the **id** of a live
+ * member (a player's `playerKey` or an entity id) as a string, or `null` when unset/dangling — hence `null`
+ * is included. The DECLARATION vocabulary (`VarType`: number/string/boolean/vec3/ref + bounds) lives in
+ * `@hypersoniclabs/helix-manifest` (authored config, validated at publish); this is the wire value side.
+ */
+export type RoomVarValue = number | string | boolean | Vec3 | null | RoomVarCollection;
+/**
+ * Per-player/room/entity COLLECTION values (Tier 2 Phase 4.5.13 + P3 collections, spec §5). A `list` var reads as
+ * an ordered array — of a scalar element (`number`/`string`/`boolean`), a **ref** element (an id `string`), or a
+ * flat **record** (`{field: scalar}`, P3) — realized server-side as a colyseus ArraySchema; a `counterMap` var
+ * reads as a string→number record over its declared keys (a MapSchema<number>). P3 also lets entities hold
+ * collections and broadcast payloads carry a collection snapshot. Mutated only via the dedicated effects
+ * (append/clear/addCount/removeAt/setField) + read via listLength/listAt/count — never a normal scalar expr/arg.
+ */
+export type RoomVarRecord = Record<string, number | string | boolean | Vec3>;
+export type RoomVarCollection = number[] | string[] | boolean[] | RoomVarRecord[] | Record<string, number>;
+/** A declared bag of custom state — names + types are declared per-world; used for both room-level and per-player vars. */
+export type RoomVars = Record<string, RoomVarValue>;
+/** Full authoritative per-player state: the FIXED character contract + identity + DECLARED game vars. */
+export interface PlayerState extends PlayerIdentity, PlayerReplicaState {
+    /** Declared per-player game state (e.g. team, health, score). Same vocabulary as roomVars; declared per-world. */
+    vars: RoomVars;
+    /**
+     * Presence (Tier 2 Phase 3, spec §8): `false` while this seat sits in the reconnection grace window after an
+     * unexpected drop — the seat (and its refs) persists, but the server excludes it from reductions. The seat is
+     * removed (an `onRemove('players')`) only at grace expiry; until then the engine should render the replica idle.
+     * This layers on Colyseus's own reconnection — it annotates the seat, it does not drive the reconnect handshake.
+     */
+    connected: boolean;
+    /**
+     * Participation (Tier 2 P3-B2 elimination): `false` when this still-connected player has been removed from the
+     * ACTIVE set mid-match (eliminated / benched / a spectator). An inactive seat is excluded from the same gameplay
+     * reductions + spatial detection a disconnected seat is (forEachPlayer / playerCount / aggregate players /
+     * nearestPlayer / zone + contact), but it stays `connected` and keeps rendering, and `broadcast` still reaches it
+     * (so it can spectate). The room sets it via the `eliminate`/`revive` effects; defaults `true`. Clients may read it
+     * to render spectators (e.g. greyed out). (Distinct from `connected`, which is presence/reconnection-grace.)
+     */
+    active: boolean;
+    /**
+     * Source-time stamp (ms) of this seat's current `position` — the SANITIZED sender send-time (`StateMessage.tMs`), or
+     * the server's apply-clock when the upload carried none. Clients SPACE interpolation keyframes by `posT` deltas
+     * instead of local arrival time, so jitter in DELIVERY (network + 20 Hz-tick aliasing) stops becoming jitter in
+     * rendered MOTION. Monotonic per seat; only deltas are meaningful (origin = the sender's arbitrary clock base).
+     */
+    posT: number;
+}
+/**
+ * RESERVED (Tier 2): a server-spawned object (pickup, projectile, NPC). Empty in v1 — the shape is
+ * reserved so adding server-spawned entities later is additive. Tier 2 gives these author-defined
+ * behavior; v1 only freezes the slot in RoomState.
+ */
+export interface EntityState {
+    id: string;
+    /** Author-defined kind (e.g. 'flag', 'pickup'). */
+    kind: string;
+    position?: Vec3;
+    /**
+     * Physics state — present ONLY for a `physics` (dynamic-body) kind (networked-physics, plan Phase 0). A kinematic
+     * entity carries position only (these stay undefined; @colyseus/schema delta-encodes an unwritten field to ~0 bytes).
+     * Synced so a remote client extrapolates with the RIGHT velocities (research §2: without synced velocity, remote
+     * extrapolation pops) and reproduces orientation. Units: m/s (linear), rad/s (angular), unit quaternion.
+     */
+    velocity?: Vec3;
+    angularVelocity?: Vec3;
+    orientation?: Quat;
+    /**
+     * Who simulates this entity (Tier 2 Phase 4.6c, spec §9). '' = server-authoritative (deterministic kinematics).
+     * A player id (a state.players key) = an owner-authoritative entity that client simulates + uploads (the others
+     * render it); a client reads this to know which entities it should be uploading via uploadEntity.
+     */
+    controller: string;
+    /**
+     * Monotonic authority epoch (Tier 2 Phase 4.5.12, spec §9), bumped on every controller handoff — host
+     * migration AND voluntary ownership transfer. A controller client mirrors this into each EntityStateMessage;
+     * the room rejects an upload whose epoch ≠ the current one, fencing a stale authority era (a still-connected
+     * prior owner's in-flight frames after ownership moved). 0 at spawn; clients only read it.
+     */
+    authorityEpoch: number;
+    /** Declared custom vars (same vocabulary as roomVars). */
+    vars: RoomVars;
+    /**
+     * Source-time stamp (ms) of this entity's current `position` — the server's apply-clock (owner-entity sender-time is
+     * a follow-up; server-authoritative entities self-stamp each tick). Consumers space interpolation by `posT` deltas,
+     * not arrival time. Monotonic; deltas only. 0 before first move.
+     */
+    posT: number;
+}
+/** The authoritative shared state. Always carries all three collections (entities empty until Tier 2). */
+export interface RoomState {
+    /** Per-player authoritative state, keyed by player id. Realized as a colyseus MapSchema. */
+    players: Record<string, PlayerState>;
+    /** Room-level declared game state (scores, timers, objectives). Names/types declared per-world. */
+    roomVars: RoomVars;
+    /** RESERVED (Tier 2): server-spawned entities. Empty in v1. */
+    entities: Record<string, EntityState>;
+    /** Authoritative server clock: a monotonic counter advanced once per fixed-rate sim tick. */
+    serverTick: number;
+    /**
+     * Authoritative server wall-clock (epoch ms) sampled at the last tick. Clients align to it (offset via the
+     * ping/pong echo, see messages.ts) and interpolate between patches, so timer/phase deadlines expressed
+     * against server time agree across clients without a per-tick countdown var.
+     */
+    serverTimeMs: number;
+    /**
+     * The current phase of the world's room-scoped state machine (Tier 2 Phase 3, spec §8), or `''` when the
+     * world declares no `states`. Authored phase names; changed only by the server's `transitionTo`. A
+     * late-joiner reads it off synced state to know whether to spawn in or spectate (the join policy).
+     */
+    phase: string;
+    /**
+     * The `serverTick` at which the room entered its current `phase`. With `serverTick`/`serverTimeMs` a client
+     * computes time-in-phase locally (e.g. a round countdown) without a per-tick countdown var.
+     */
+    phaseStartTick: number;
+    /**
+     * Active timers (Tier 2 Phase 3, spec §8) → absolute deadline as `serverTimeMs` (epoch ms). The map key is
+     * the timer name for a room-scoped timer, or `"<timer>|<playerKey>"` for a per-player **keyed** timer (e.g.
+     * read your own cooldown at `"cooldown|" + room.sessionId`). A client computes the seconds remaining as
+     * `(deadline − estimatedServerTimeMs) / 1000` using its ping/pong offset, so a countdown interpolates locally
+     * without a per-tick countdown var. An entry is removed when the timer fires or is cancelled.
+     */
+    timerDeadlines: Record<string, number>;
+}

package/dist/multiplayer-contract/room.js

@@ -0,0 +1,17 @@
+// The authoritative room state shape — the FRAMEWORK for what a world syncs. The room holds this as
+// @colyseus/schema (the Record<string, T> maps below are realized as MapSchema); the SDK exposes it as
+// room.state. Two layers, and the distinction is the whole answer to "how does an agent sync more?":
+//
+//   • players  — FIXED. Each player is the engine's character contract (PlayerReplicaState) + identity.
+//                Universal across every world; an agent never changes its fields.
+//   • roomVars / per-player vars / entities — DECLARED PER-WORLD. This is where an agent's game state
+//                lives (scores, timers, teams, objectives). The agent DECLARES names + types in the
+//                world's multiplayer config (loaded by buildId at onCreate); the one generic HelixRoom
+//                interprets the declaration — no agent-authored server code (Tier 1).
+//
+// Tier-1 vocabulary is intentionally bounded (primitives + Vec3). Rich/nested custom state and
+// author-defined entity behavior are Tier 2 (a reflection-based dynamic schema + behavior DSL),
+// deferred — the `entities` collection and this declared-bag shape are the reserved seams that keep
+// Tier 2 additive rather than a rewrite.
+export {};
+//# sourceMappingURL=room.js.map

package/dist/multiplayer-contract/room.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"room.js","sourceRoot":"","sources":["../../src/multiplayer-contract/room.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,uGAAuG;AACvG,qGAAqG;AACrG,EAAE;AACF,wGAAwG;AACxG,kFAAkF;AAClF,sGAAsG;AACtG,oGAAoG;AACpG,uGAAuG;AACvG,sFAAsF;AACtF,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,oGAAoG;AACpG,yCAAyC"}

package/dist/multiplayer-contract/state.d.ts

@@ -0,0 +1,61 @@
+export type Vec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/** A rotation quaternion. Physics (dynamic-body) kinds only — kinematic kinds carry no orientation on the wire. */
+export type Quat = {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+};
+/** Pinned units. Linear in meters / meters-per-second; every angle is degrees (see the *Deg suffixes). */
+export declare const UNITS: {
+    readonly position: "meters";
+    readonly velocity: "meters/second";
+    readonly angles: "degrees";
+};
+/** Stable per-player identity (set at join from the room credential; not part of the per-tick churn). */
+export interface PlayerIdentity {
+    /** Opaque per-connection room playerKey (= the state.players map key). NOT the credential `sub` — that stays server-side (§4). */
+    id: string;
+    /** Sanitized display name for nameplates (sanitized before it enters room state — see plan H4). */
+    displayName: string;
+    /**
+     * CDN URL of this player's equipped universal avatar (a converted single-file GLB on the
+     * helix-humanoid rig), or '' when they have none — clients render the default body on ''.
+     * Resolved and skeleton-gated SERVER-SIDE at join (backend → signed credential → room), never
+     * client-supplied — and it is item-keyed public catalog data, NOT the userId (which stays
+     * server-side, §4). Fixed for the seat's lifetime: equip changes apply on the next join. (v17)
+     */
+    avatarUrl: string;
+}
+/**
+ * The per-tick replicated kinematic + animation parameters for one player. The room holds the
+ * authoritative copy (a @colyseus/schema mirror of these fields); the NetworkDriver maps each field
+ * onto the named character blackboard param. FIRST DRAFT — the exact injected set is confirmed by
+ * spike S2 (engine headless-replica write-path); changing the field set bumps CONTRACT_VERSION.
+ */
+export interface PlayerReplicaState {
+    /** World feet position, METERS. Interpolated by the remote replica. */
+    position: Vec3;
+    /** Body facing, DEGREES. The adapter converts to radians for body.setFacingYaw. */
+    facingYawDeg: number;
+    /** Horizontal planar speed, M/S. → blackboard 'speed' (blend-space input). */
+    speed: number;
+    /** Signed movement direction relative to facing, DEGREES (−180..180). → blackboard 'direction'. */
+    moveDirectionDeg: number;
+    /** Vertical velocity, M/S (+up). → blackboard 'verticalVelocity' (jump/fall states). */
+    verticalVelocity: number;
+    /** Ground contact. → blackboard 'isGrounded' (grounded/air transitions). */
+    grounded: boolean;
+    /** Crouch stance. → routes the locomotion anim graph to its crouched states. */
+    crouched: boolean;
+    /** Aim yaw, DEGREES (world). → blackboard 'cameraYaw' (aim-additive source). */
+    aimYawDeg: number;
+    /** Aim pitch, DEGREES. → blackboard 'cameraPitch' (aim-additive source). */
+    aimPitchDeg: number;
+    /** Ability ids currently active (e.g. ['locomotion','fly']). Drives remote ability activation. */
+    activeAbilities: string[];
+}

package/dist/multiplayer-contract/state.js

@@ -0,0 +1,15 @@
+// Replicated player state — the parameters the room broadcasts and the engine's NetworkDriver feeds
+// into the character blackboard. We replicate PARAMETERS, never bone transforms: animation runs fully
+// client-side off these values (see character-architecture §3).
+//
+// ALL ANGLES ARE DEGREES — every angular field is suffixed *Deg. One unit on the wire, so there is no
+// radians/degrees ambiguity to forget. The engine mixes units internally (the body is radians, the
+// animation params are degrees); the engine adapter owns the single deg↔rad conversion at the body
+// boundary (body.setFacingYaw) — the contract itself stays all-degrees.
+/** Pinned units. Linear in meters / meters-per-second; every angle is degrees (see the *Deg suffixes). */
+export const UNITS = {
+    position: 'meters',
+    velocity: 'meters/second',
+    angles: 'degrees',
+};
+//# sourceMappingURL=state.js.map

package/dist/multiplayer-contract/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/multiplayer-contract/state.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,sGAAsG;AACtG,gEAAgE;AAChE,EAAE;AACF,sGAAsG;AACtG,mGAAmG;AACnG,mGAAmG;AACnG,wEAAwE;AAOxE,0GAA0G;AAC1G,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,QAAQ,EAAE,QAAQ;IAClB,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,SAAS;CACT,CAAC"}

package/dist/multiplayer.d.ts

@@ -0,0 +1,133 @@
+import { type StateMessage, type StateAckMessage, type EntityStateAckMessage, type RoomState, type PlayerState, type EntityState, type RoomVarValue, type Vec3, type Quat } from './multiplayer-contract';
+export type ReplicaInput = Omit<StateMessage, 'seq' | 'tMs'>;
+/** Options for joinRoom — only needed where the API base can't be derived from the token (local dev/tests). */
+export interface JoinRoomOptions {
+    /** Override the platform API base URL. Default: the world_session token's `iss`, else configure({ apiBaseUrl }). */
+    apiBaseUrl?: string;
+    /**
+     * State upload cadence (Hz) for the player-seat flush — from the world's `multiplayer.uploadHz`. Clamped to
+     * [MESSAGE_RATE.stateHz, MESSAGE_RATE.maxUploadHz] (10..20); absent ⇒ the 10 Hz default. The room derives its
+     * own ceiling from the trusted configUrl, so a lying client only throttles itself.
+     */
+    uploadHz?: number;
+}
+/** The curated live-room surface handed to world authors. Colyseus's API, re-exposed under Helix.*. */
+export interface HelixRoom {
+    readonly roomId: string;
+    readonly sessionId: string;
+    /**
+     * The clamped player-seat upload cadence (Hz) this connection flushes at — `multiplayer.uploadHz` resolved to
+     * [10,20]. The engine paces its hosted-entity (EntityScene) uploads to the SAME value so both channels match.
+     */
+    readonly effectiveUploadHz: number;
+    /** Authoritative shared state (a @colyseus/schema instance shaped like the contract RoomState). */
+    readonly state: RoomState;
+    /** Fires after every applied patch from the server. */
+    onStateChange(cb: (state: RoomState) => void): void;
+    /** Subscribe to a collection's adds (Tier-2 seam: players today, entities reserved). Fires for existing entries too. */
+    onAdd(collection: 'players', cb: (player: PlayerState, id: string) => void): void;
+    onAdd(collection: 'entities', cb: (entity: EntityState, id: string) => void): void;
+    onRemove(collection: 'players', cb: (player: PlayerState, id: string) => void): void;
+    onRemove(collection: 'entities', cb: (entity: EntityState, id: string) => void): void;
+    /** A world-authored server→client message (the room broadcasts these for declared events). */
+    onMessage<Payload = unknown>(type: string, cb: (payload: Payload) => void): void;
+    /**
+     * A2 (spec §9) the room's player-seat divergence correction — fires ONLY when the movement gate REJECTED an
+     * upload (the accepted case is silent). The engine snaps the local body to `position`; the SDK has already
+     * pruned its reconciliation buffer through `seq` before this fires.
+     */
+    onStateAck(cb: (ack: StateAckMessage) => void): void;
+    /**
+     * A2 (spec §9) the room's owner-hosted-entity divergence correction, BATCHED — the engine re-anchors each
+     * hosted entity's local sim to its anchor so a sparse/throttled host stops being fenced by the gate.
+     */
+    onEntityStateAck(cb: (ack: EntityStateAckMessage) => void): void;
+    /** Per-tick predicted state. Coalesced + flushed at MESSAGE_RATE.stateHz, seq-tagged (D3/D4). */
+    sendState(input: ReplicaInput): void;
+    /** Activate/deactivate a built-in ability (sent immediately; server enforces the rate ceiling). */
+    sendAbility(ability: string, active: boolean): void;
+    /** A world-authored declared action (the generic extensibility channel). */
+    sendAction(name: string, args?: Record<string, RoomVarValue>): void;
+    /**
+     * Upload an owner-authoritative entity's client-simulated state (Tier 2 Phase 4.6c). Call only for an entity
+     * whose `controller` is this client (state.entities[id].controller === sessionId); the room rejects others.
+     * Sent immediately, per-entity seq-tagged; the room gates the position against the kind's maxSpeed + clamps vars.
+     */
+    uploadEntity(entityId: string, input: {
+        position: Vec3;
+        velocity?: Vec3;
+        angularVelocity?: Vec3;
+        orientation?: Quat;
+        vars?: Record<string, RoomVarValue>;
+        epoch?: number;
+    }): void;
+    /**
+     * Upload MANY owner-authoritative entities in ONE message (Tier 2 Phase 4.10). Prefer this over per-entity
+     * uploadEntity when hosting multiple entities: the per-connection rate cap counts messages, so N single uploads
+     * spend N tokens/tick and starve, while one batch spends one. Position is sent as a compact [x,y,z] tuple; each
+     * entry is gated/clamped server-side exactly like uploadEntity. Pass only entities this client controls.
+     */
+    uploadEntities(entities: ReadonlyArray<{
+        id: string;
+        position: Vec3;
+        velocity?: Vec3;
+        angularVelocity?: Vec3;
+        orientation?: Quat;
+        vars?: Record<string, RoomVarValue>;
+        epoch?: number;
+    }>): void;
+    /** Sent-but-unacknowledged states — the reconciliation tail the engine NetworkDriver replays (D4). */
+    pendingInputs(): readonly StateMessage[];
+    /** Prune the reconciliation buffer once the server confirms it processed up to `seq` (D4). */
+    acknowledge(seq: number): void;
+    /** Connection dropped; the client is auto-reconnecting (built into @colyseus/sdk). */
+    onDrop(cb: () => void): void;
+    /** Auto-reconnection succeeded. */
+    onReconnect(cb: () => void): void;
+    /** Left for good (kicked, room disposed, or after we leave) — `code` is the close code. */
+    onLeave(cb: (code: number) => void): void;
+    /** Leave intentionally (no reconnection grace held server-side). */
+    leave(): Promise<void>;
+}
+export interface MultiplayerHost {
+    isInitialized(): boolean;
+    getToken(): string | null;
+    getWorldId(): string | null;
+}
+export declare class HelixMultiplayer {
+    private readonly host;
+    private apiBaseUrl;
+    private room;
+    private callbacks;
+    private seq;
+    private entitySeq;
+    private entityBatchSeq;
+    private pendingInput;
+    private flushTimer;
+    private effectiveUploadHz;
+    private inputBuffer;
+    private worldId;
+    private onStateAckCb;
+    private onEntityStateAckCb;
+    private nlSend;
+    private nlPatch;
+    constructor(host: MultiplayerHost);
+    configure(options: {
+        apiBaseUrl: string;
+    }): void;
+    resolveApiBase(token: string | null): string | null;
+    joinRoom(worldId?: string, options?: JoinRoomOptions): Promise<HelixRoom>;
+    private requestJoin;
+    private makeHandle;
+    private startFlush;
+    private flush;
+    private nlOnPatch;
+    private nlTick;
+    private persistReconnect;
+    private readReconnect;
+    private reconnectWsUrl;
+    private clearReconnect;
+    private tryReconnect;
+    private leave;
+    private teardown;
+}