@hypersoniclabs/helix-sdk 0.1.1 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +954 -2
  2. package/dist/action-surface.d.ts +182 -0
  3. package/dist/action-surface.js +1032 -0
  4. package/dist/action-surface.js.map +1 -0
  5. package/dist/camera.d.ts +78 -0
  6. package/dist/camera.js +640 -0
  7. package/dist/camera.js.map +1 -0
  8. package/dist/dev-shell/criteria.d.ts +46 -0
  9. package/dist/dev-shell/criteria.js +98 -0
  10. package/dist/dev-shell/criteria.js.map +1 -0
  11. package/dist/dev-shell/index.d.ts +189 -0
  12. package/dist/dev-shell/index.js +287 -0
  13. package/dist/dev-shell/index.js.map +1 -0
  14. package/dist/dev-shell/keys.d.ts +14 -0
  15. package/dist/dev-shell/keys.js +78 -0
  16. package/dist/dev-shell/keys.js.map +1 -0
  17. package/dist/dev-shell/simulator.d.ts +436 -0
  18. package/dist/dev-shell/simulator.js +1634 -0
  19. package/dist/dev-shell/simulator.js.map +1 -0
  20. package/dist/dev-shell/state.d.ts +148 -0
  21. package/dist/dev-shell/state.js +196 -0
  22. package/dist/dev-shell/state.js.map +1 -0
  23. package/dist/device-definition-resolver.d.ts +34 -0
  24. package/dist/device-definition-resolver.js +172 -0
  25. package/dist/device-definition-resolver.js.map +1 -0
  26. package/dist/device-trial.d.ts +3 -0
  27. package/dist/device-trial.js +132 -0
  28. package/dist/device-trial.js.map +1 -0
  29. package/dist/devices.d.ts +228 -0
  30. package/dist/devices.js +198 -0
  31. package/dist/devices.js.map +1 -0
  32. package/dist/dreamerAudio.d.ts +126 -0
  33. package/dist/dreamerAudio.js +135 -0
  34. package/dist/dreamerAudio.js.map +1 -0
  35. package/dist/generated/runtime-contract.d.ts +15529 -0
  36. package/dist/generated/runtime-contract.js +20470 -0
  37. package/dist/generated/runtime-contract.js.map +1 -0
  38. package/dist/index.d.ts +364 -3
  39. package/dist/index.js +1954 -13
  40. package/dist/index.js.map +1 -1
  41. package/dist/interaction-mode.d.ts +172 -0
  42. package/dist/interaction-mode.js +553 -0
  43. package/dist/interaction-mode.js.map +1 -0
  44. package/dist/internal/avatar-pose.d.ts +25 -0
  45. package/dist/internal/avatar-pose.js +46 -0
  46. package/dist/internal/avatar-pose.js.map +1 -0
  47. package/dist/internal/keyed-collection.d.ts +2 -0
  48. package/dist/internal/keyed-collection.js +12 -0
  49. package/dist/internal/keyed-collection.js.map +1 -0
  50. package/dist/internal/vehicle-detach-action.d.ts +2 -0
  51. package/dist/internal/vehicle-detach-action.js +6 -0
  52. package/dist/internal/vehicle-detach-action.js.map +1 -0
  53. package/dist/matchmaking.d.ts +433 -0
  54. package/dist/matchmaking.js +1487 -0
  55. package/dist/matchmaking.js.map +1 -0
  56. package/dist/materials.d.ts +122 -0
  57. package/dist/materials.js +217 -0
  58. package/dist/materials.js.map +1 -0
  59. package/dist/multiplayer-accessors.d.ts +100 -0
  60. package/dist/multiplayer-accessors.js +200 -0
  61. package/dist/multiplayer-accessors.js.map +1 -0
  62. package/dist/multiplayer-contract/avatar-pose.d.ts +112 -0
  63. package/dist/multiplayer-contract/avatar-pose.js +250 -0
  64. package/dist/multiplayer-contract/avatar-pose.js.map +1 -0
  65. package/dist/multiplayer-contract/credential.d.ts +80 -0
  66. package/dist/multiplayer-contract/credential.js +5 -0
  67. package/dist/multiplayer-contract/credential.js.map +1 -0
  68. package/dist/multiplayer-contract/final-rest.d.ts +66 -0
  69. package/dist/multiplayer-contract/final-rest.js +38 -0
  70. package/dist/multiplayer-contract/final-rest.js.map +1 -0
  71. package/dist/multiplayer-contract/index.d.ts +20 -0
  72. package/dist/multiplayer-contract/index.js +41 -0
  73. package/dist/multiplayer-contract/index.js.map +1 -0
  74. package/dist/multiplayer-contract/messages.d.ts +731 -0
  75. package/dist/multiplayer-contract/messages.js +237 -0
  76. package/dist/multiplayer-contract/messages.js.map +1 -0
  77. package/dist/multiplayer-contract/room.d.ts +177 -0
  78. package/dist/multiplayer-contract/room.js +17 -0
  79. package/dist/multiplayer-contract/room.js.map +1 -0
  80. package/dist/multiplayer-contract/state.d.ts +241 -0
  81. package/dist/multiplayer-contract/state.js +15 -0
  82. package/dist/multiplayer-contract/state.js.map +1 -0
  83. package/dist/multiplayer-final-rest.d.ts +32 -0
  84. package/dist/multiplayer-final-rest.js +217 -0
  85. package/dist/multiplayer-final-rest.js.map +1 -0
  86. package/dist/multiplayer.d.ts +624 -0
  87. package/dist/multiplayer.js +2503 -0
  88. package/dist/multiplayer.js.map +1 -0
  89. package/dist/package.json +3 -0
  90. package/dist/protocol.d.ts +859 -1
  91. package/dist/protocol.js +117 -5
  92. package/dist/protocol.js.map +1 -1
  93. package/dist/runtime-contract/index.d.ts +15 -0
  94. package/dist/runtime-contract/index.js +12 -0
  95. package/dist/runtime-contract/index.js.map +1 -0
  96. package/dist/server-clock.d.ts +25 -0
  97. package/dist/server-clock.js +88 -0
  98. package/dist/server-clock.js.map +1 -0
  99. package/dist/tsconfig.build.tsbuildinfo +1 -1
  100. package/dist/universal-vehicles.d.ts +111 -0
  101. package/dist/universal-vehicles.js +2 -0
  102. package/dist/universal-vehicles.js.map +1 -0
  103. package/dist/vault.d.ts +562 -0
  104. package/dist/vault.js +365 -0
  105. package/dist/vault.js.map +1 -0
  106. package/dist/vehicle-specialty-placement.d.ts +28 -0
  107. package/dist/vehicle-specialty-placement.js +154 -0
  108. package/dist/vehicle-specialty-placement.js.map +1 -0
  109. package/dist/vehicle-specialty-transport.d.ts +78 -0
  110. package/dist/vehicle-specialty-transport.js +183 -0
  111. package/dist/vehicle-specialty-transport.js.map +1 -0
  112. package/dist/voice.d.ts +229 -0
  113. package/dist/voice.js +1348 -0
  114. package/dist/voice.js.map +1 -0
  115. package/generated/runtime-contract/helix-runtime-contract.json +13332 -0
  116. package/generated/runtime-contract/known-answer.json +20471 -0
  117. package/generated/runtime-contract/known-answer.schema.json +630 -0
  118. package/generated/runtime-contract/runtime-contract.schema.json +607 -0
  119. package/generated/runtime-contract/unreal/HelixRuntimeContract.generated.h +908 -0
  120. package/package.json +44 -5
@@ -0,0 +1,624 @@
1
+ import type { FinalRestScope, FinalRestGrant, EntityStateBatchEntry, GroupRestSnapshotMessage } from './multiplayer-contract/index.js';
2
+ import { type StateMessage, type GesturePlay, type AttachmentEntry, type StateAckMessage, type EntityStateAckMessage, type ModuleFusedMessage, type ModuleWakeMessage, type ModuleSleepMessage, type ModuleEngagementMessage, type RoomState, type PlayerState, type EntityState, type RoomVarValue, type Vec3, type Quat } from './multiplayer-contract/index.js';
3
+ import type { ModuleActionRequest, VehicleComponentActionRequest, VehicleDetachActionRequest, ModuleEffect, ModuleStateSnapshot } from './universal-vehicles.js';
4
+ import { type ModuleAccessors, type VarsView } from './multiplayer-accessors.js';
5
+ import type { HelixMultiplayerState } from './protocol.js';
6
+ import type { ServerClock } from './server-clock.js';
7
+ export type ReplicaInput = Omit<StateMessage, 'seq' | 'tMs' | 'teleportSeq'>;
8
+ /** Current room authority for one engaged module. The epoch is room-issued and SDK-stamped on verbs. */
9
+ export interface ModuleEngagementLease {
10
+ readonly moduleId: string;
11
+ readonly action: string;
12
+ readonly epoch: number;
13
+ }
14
+ /** Options for joinRoom — only needed where the API base can't be derived from the token (local dev/tests). */
15
+ export interface JoinRoomOptions {
16
+ /** Override the platform API base URL. Default: the world_session token's `iss`, else configure({ apiBaseUrl }). */
17
+ apiBaseUrl?: string;
18
+ /**
19
+ * State upload cadence (Hz) for the player-seat flush — from the world's `multiplayer.uploadHz`. Clamped to
20
+ * [MESSAGE_RATE.stateHz, MESSAGE_RATE.maxUploadHz] (10..20); absent ⇒ the 10 Hz default. The room derives its
21
+ * own ceiling from the trusted configUrl, so a lying client only throttles itself.
22
+ */
23
+ uploadHz?: number;
24
+ /**
25
+ * Same-origin platform reservation route for a runtime that shares the HELIX
26
+ * room plane without being an InstantWorld row (for example a Home).
27
+ * Must be an absolute `/api/v1/...` path; cross-origin URLs are rejected so
28
+ * the world_session bearer can never be exfiltrated.
29
+ */
30
+ reservationPath?: string;
31
+ /**
32
+ * Join an OPEN named room type declared in the world's manifest (`multiplayer.roomTypes.<name>`) instead of
33
+ * the default room. Sent as the join request's JSON body (`{ "roomType": "<name>" }`); the backend answers
34
+ * 404 `unknown-room-type` for an undeclared name and 403 `ticket-required` for a `ticketed` type, both
35
+ * surfaced as a HelixRoomJoinError. Omit it (and `ticket`) for the default room — that request carries NO
36
+ * body and is byte-identical to what every earlier SDK sent.
37
+ *
38
+ * A shell-provided `?instance=` does NOT apply to a typed join: it names a room of the DEFAULT type, so a
39
+ * typed join ignores it entirely (no strict joinById, no helix:multiplayer-join-error).
40
+ */
41
+ roomType?: string;
42
+ /**
43
+ * Redeem a ticket to a `ticketed` room instance (delivered by `room.onTicket`). Sent as `{ "ticket": "<id>" }`.
44
+ * Single-use and bound to the account it was issued to — an unknown, expired, already-used or foreign ticket
45
+ * is a HelixRoomJoinError with code `ticket-invalid`. Mutually exclusive with `roomType` (the ticket already
46
+ * names its type); passing both is refused before any request. Like `roomType`, it ignores `?instance=`.
47
+ * Most worlds hop with `Helix.multiplayer.switchRoom({ ticket })` rather than calling this directly.
48
+ */
49
+ ticket?: string;
50
+ }
51
+ /**
52
+ * Where `Helix.multiplayer.switchRoom` goes. Either a ticket to redeem, or a room type to matchmake into
53
+ * (omit `roomType` for the world's default room), optionally preferring one specific room instance.
54
+ */
55
+ export type SwitchRoomTarget = {
56
+ ticket: string;
57
+ } | {
58
+ /** An OPEN declared room type; omitted = the default room type. */
59
+ roomType?: string;
60
+ /**
61
+ * Try THIS room (a `roomId`) first, e.g. the lobby the player came from. Non-strict, unlike the shell's
62
+ * `?instance=` on a first join: if the room is gone, full or locked the hop falls back to a normal
63
+ * matchmade join of the same type, and no helix:multiplayer-join-error is published.
64
+ */
65
+ preferInstanceId?: string;
66
+ };
67
+ /** The per-join knobs `switchRoom` forwards to the new room's join (everything joinRoom takes but the target). */
68
+ export type SwitchRoomOptions = Omit<JoinRoomOptions, 'roomType' | 'ticket'>;
69
+ /**
70
+ * A ticket to a `ticketed` room instance, as handed to `room.onTicket`. The wire shape (RoomTicketMessage)
71
+ * carries `expiresAt` however the backend spelled it; here it is ALWAYS Unix epoch milliseconds, comparable
72
+ * with `Date.now()` — or NaN when the platform sent something unparseable, in which case treat the expiry as
73
+ * unknown (redemption is the authority either way).
74
+ *
75
+ * `expiresAt` is the TICKET's deadline (a few minutes), not the room's: the ticket must be REDEEMED —
76
+ * `switchRoom({ ticket })` — before it, or the redeem is refused (`ticket-invalid`). The room instance itself
77
+ * may live much longer; once inside, this timestamp no longer matters.
78
+ */
79
+ export interface RoomTicket {
80
+ roomType: string;
81
+ /** Pass to `Helix.multiplayer.switchRoom({ ticket: ticketId })`. */
82
+ ticketId: string;
83
+ /** The room instance the ticket admits to. */
84
+ instanceId: string;
85
+ /**
86
+ * Redeem-by deadline of THIS ticket, Unix epoch MILLISECONDS (normalised from an ISO string / epoch seconds /
87
+ * epoch ms); NaN if unparseable. Not the lifetime of the room.
88
+ */
89
+ expiresAt: number;
90
+ }
91
+ /**
92
+ * Why a join or a room hop failed, as a stable machine-readable code:
93
+ * - `unknown-room-type` the world's active build declares no such room type (or room types are off).
94
+ * - `ticket-required` the type is `ticketed`; it can only be entered by redeeming a ticket.
95
+ * - `ticket-invalid` the ticket is unknown, expired, already used, or was issued to someone else.
96
+ * - `room-type-unavailable` the platform answered a typed/ticket request with a DEFAULT-room reservation (a
97
+ * backend that predates room types ignores the body) — refused rather than seating
98
+ * the player in a room they did not ask for.
99
+ * - `instance-closed` the ticketed room instance has closed — the match is over. Answered by the
100
+ * rejoin endpoint (410) when resuming after a reload, and by a ticket redeem whose
101
+ * instance ended first. Final: the SDK forgets the instance and never retries.
102
+ * - `rejoin-failed` resuming a ticketed room failed for another reason. 403 and 404 (not this
103
+ * player's instance) are final and forgotten; a network failure, 5xx, 429 or 401
104
+ * (the session may refresh) is RETRYABLE — the instance is kept, so the next
105
+ * `joinRoom()` asks again. `status` tells them apart (null = no answer).
106
+ * - `invalid-target` the caller passed an unusable target (both `roomType` and `ticket`, an empty id…).
107
+ * - `not-ready` `switchRoom` cannot even start: no Helix.init(), no world session, no world id or
108
+ * no resolvable API base.
109
+ * - `switch-in-progress` a `switchRoom` hop is still in flight (raised by a second `switchRoom` and by a
110
+ * `joinRoom` during the hop); the hop decides the outcome, this call changed nothing.
111
+ * - `join-in-progress` a `joinRoom` is still in flight: `switchRoom` was called under it, or a second
112
+ * `joinRoom` was (one join runs at a time); nothing changed.
113
+ * - `cancelled` `leave()` (or the shell's leave message) arrived while this join or hop was in
114
+ * flight. The caller is in NO room: a seat the call had already taken was released.
115
+ * - `left` the player has left this world (the shell's Exit / Back — see `Helix.hasLeft()`).
116
+ * Final for this world document: nothing was sent, and every later `joinRoom()` /
117
+ * `switchRoom()` is refused the same way. Checked before anything else.
118
+ * - `join-failed` anything else (transport, a refused seat reservation, an unmapped refusal).
119
+ *
120
+ * The backend's own refusal `code` is what is matched (`unknown-room-type`, `ticket-required`,
121
+ * `unknown-room-ticket`, `room-ticket-expired`, `room-ticket-used`, `room-instance-closed`,
122
+ * `unknown-room-instance`) — never the HTTP status alone, so an unrelated 404 (world not found) stays
123
+ * `join-failed` instead of being misreported as a bad ticket.
124
+ */
125
+ export type HelixRoomJoinErrorCode = 'unknown-room-type' | 'ticket-required' | 'ticket-invalid' | 'room-type-unavailable' | 'instance-closed' | 'rejoin-failed' | 'invalid-target' | 'not-ready' | 'switch-in-progress' | 'join-in-progress' | 'cancelled' | 'left' | 'join-failed';
126
+ /**
127
+ * The typed failure of `joinRoom`'s platform request and of every `switchRoom` rejection. It IS an Error with
128
+ * the same `Helix.multiplayer: join failed — …` message earlier SDKs threw, so code that only reads `.message`
129
+ * is unaffected; `code` is what new code should branch on, `status` the HTTP status when there was one.
130
+ */
131
+ export declare class HelixRoomJoinError extends Error {
132
+ readonly code: HelixRoomJoinErrorCode;
133
+ readonly status: number | null;
134
+ constructor(code: HelixRoomJoinErrorCode, message: string, status?: number | null, cause?: unknown);
135
+ }
136
+ /** Why a room handle's `onLeave` fired — see HelixRoom.onLeave. */
137
+ export type HelixRoomLeaveReason = 'switch' | 'leave' | 'dropped';
138
+ /**
139
+ * The curated live-room surface handed to world authors. Colyseus's API, re-exposed under Helix.*.
140
+ *
141
+ * STALE HANDLES. A handle belongs to ONE room. Once that room is no longer the current one — you left it,
142
+ * hopped away with `switchRoom`, or it dropped for good — the handle is stale, and it can never act on
143
+ * whatever room came after it:
144
+ * - `leave()` resolves and does nothing (it never leaves the NEW room).
145
+ * - `sendState`, `sendAction`, `uploadEntity`, `uploadEntities`, `requestModuleEngagement` and
146
+ * `acknowledge` are no-ops; the boolean-returning senders (`sendModuleAction`, `sendVehicle*Action`,
147
+ * `releaseModuleEngagement`) return `false`. These all stamp SDK-owned state (the coalesced state slot,
148
+ * sequence counters, engagement epochs) that now belongs to the next room.
149
+ * - the plain pass-through senders — `sendAbility`, `sendGesture`, `sendAttachments`, `sendAvatarRefresh`,
150
+ * `sendEmoteRefresh`, `sendEmoteJoin` — keep their long-standing guarantee: handed to the handle's OWN
151
+ * (now closed) room, never a throw, never delivered to another room.
152
+ * - `claimPhysicsGroup`, `commitPhysicsGroup` and `requestDistributionCapability` reject (`not_in_room`).
153
+ * - every subscription (`onMessage`, `onTicket`, `onStateChange`, `onAdd`/`onRemove`, `onStateAck`,
154
+ * `onEntityStateAck`, `onModule*`, `onPhysicsGroupRest`, `onPlayerAvatarChanged`, `onDrop`,
155
+ * `onReconnect`) registers nothing and never fires; existing ones stopped firing at the hop.
156
+ * - `onLeave` fires once for the handle's own room; registered after that, it never fires.
157
+ * - `pendingInputs()` is empty and `moduleEngagement()` is null.
158
+ * - `roomId`, `sessionId`, `roomType`, `instanceKey`, `effectiveUploadHz` keep their values, and `state`,
159
+ * `vars`, `me`, `player()`, `phase()`, `currentTurn()`, `isMyTurn()`, `module()` keep reading the last
160
+ * state that room replicated — a frozen snapshot, never the new room's.
161
+ */
162
+ export interface HelixRoom {
163
+ /** Positive authorized claim; rejects on old servers. Await before applying one impulse. */
164
+ claimPhysicsGroup(action: string, group: string, args?: Record<string, RoomVarValue>, scope?: FinalRestScope): Promise<FinalRestGrant>;
165
+ /** Exact complete stopped batch, epochs from claim; SDK supplies the normal physics sequence and retries frozen bytes. */
166
+ commitPhysicsGroup(transactionId: string, states: readonly EntityStateBatchEntry[]): Promise<GroupRestSnapshotMessage>;
167
+ /** Subscribe to one group's authoritative rest, explicitly selecting module-local delivery when scoped. */
168
+ onPhysicsGroupRest(group: string, callback: (snapshot: GroupRestSnapshotMessage) => void, scope?: FinalRestScope): void;
169
+ readonly roomId: string;
170
+ readonly sessionId: string;
171
+ /**
172
+ * The named room type this room is an instance of, or null for the world's default room. Read it after a
173
+ * reload: a plain `joinRoom()` RESUMES the room the tab was in, which may be a typed room (see joinRoom).
174
+ */
175
+ readonly roomType: string | null;
176
+ /** The ticketed room instance id (the credential's `instanceKey`), or null for default and open-type rooms. */
177
+ readonly instanceKey: string | null;
178
+ /**
179
+ * The clamped player-seat upload cadence (Hz) this connection flushes at — `multiplayer.uploadHz` resolved to
180
+ * [10,20]. The engine paces its hosted-entity (EntityScene) uploads to the SAME value so both channels match.
181
+ */
182
+ readonly effectiveUploadHz: number;
183
+ /** Authoritative shared state (a @colyseus/schema instance shaped like the contract RoomState). */
184
+ readonly state: RoomState;
185
+ /** Fires after every applied patch from the server. */
186
+ onStateChange(cb: (state: RoomState) => void): () => void;
187
+ /** Subscribe to a collection's adds (Tier-2 seam: players today, entities reserved). Fires for existing entries too. */
188
+ onAdd(collection: 'players', cb: (player: PlayerState, id: string) => void): void;
189
+ onAdd(collection: 'entities', cb: (entity: EntityState, id: string) => void): void;
190
+ onRemove(collection: 'players', cb: (player: PlayerState, id: string) => void): void;
191
+ onRemove(collection: 'entities', cb: (entity: EntityState, id: string) => void): void;
192
+ /**
193
+ * A seat's replicated avatar changed mid-session (v23 — the room re-resolved it after an `avatarRefresh`
194
+ * hint), so the engine can re-skin that replica without a rejoin. Fires per changed seat, never on join
195
+ * (read state.players[id].avatarUrl for the initial value). Returns an unsubscribe.
196
+ */
197
+ onPlayerAvatarChanged(cb: (playerId: string, avatarUrl: string) => void): () => void;
198
+ /** A world-authored server→client message (the room broadcasts these for declared events). */
199
+ onMessage<Payload = unknown>(type: string, cb: (payload: Payload) => void): () => void;
200
+ /**
201
+ * The room handed THIS player a ticket to a `ticketed` room instance (`helix:room-ticket`, sent privately to
202
+ * each player an `openRoom` rule selected). Redeem it with `Helix.multiplayer.switchRoom({ ticket:
203
+ * ticket.ticketId })`. `expiresAt` arrives normalised to epoch milliseconds; a malformed ticket is dropped.
204
+ * Tickets are not replayed: subscribe right after joining. Returns an unsubscribe.
205
+ */
206
+ onTicket(cb: (ticket: RoomTicket) => void): () => void;
207
+ /** Typed module runtime diagnostics. */
208
+ onModuleFused(cb: (event: ModuleFusedMessage) => void): void;
209
+ onModuleWake(cb: (event: ModuleWakeMessage) => void): void;
210
+ onModuleSleep(cb: (event: ModuleSleepMessage) => void): void;
211
+ /** Observe exclusive module grants, denials, releases, and server/drop revocations. */
212
+ onModuleEngagement(cb: (event: ModuleEngagementMessage) => void): () => void;
213
+ /** Observe authoritative mounted-module snapshots, including late-join state. */
214
+ onModuleState(cb: (snapshot: ModuleStateSnapshot) => void): void;
215
+ /** Observe namespaced transient presentation without subscribing to every authored event name. */
216
+ onModuleEffect(cb: (effect: ModuleEffect) => void): void;
217
+ /**
218
+ * A2 (spec §9) the room's player-seat divergence correction — fires when the movement gate REJECTED an
219
+ * upload, or proactively when a rule teleport/respawn re-anchored the seat (the accepted case is silent).
220
+ * The engine snaps the local body to `position`; the SDK has already adopted the ack's teleport epoch (v27),
221
+ * dropped its coalesced pending frame on an epoch change, and pruned its reconciliation buffer through `seq`
222
+ * before this fires. SINGLE-SLOT: assigning a second consumer silently replaces the first.
223
+ */
224
+ onStateAck(cb: (ack: StateAckMessage) => void): void;
225
+ /**
226
+ * A2 (spec §9) the room's owner-hosted-entity divergence correction, BATCHED — the engine re-anchors each
227
+ * hosted entity's local sim to its anchor so a sparse/throttled host stops being fenced by the gate.
228
+ */
229
+ onEntityStateAck(cb: (ack: EntityStateAckMessage) => void): void;
230
+ /** Per-tick predicted state. Coalesced + flushed at MESSAGE_RATE.stateHz, seq-tagged (D3/D4). */
231
+ sendState(input: ReplicaInput): void;
232
+ /** Activate/deactivate a built-in ability (sent immediately; server enforces the rate ceiling). */
233
+ sendAbility(ability: string, active: boolean): void;
234
+ /**
235
+ * A declared action. When this SDK holds a room engagement for `moduleId`, it automatically stamps
236
+ * the matching authority epoch; authored code never supplies that epoch.
237
+ */
238
+ sendAction(name: string, args?: Record<string, RoomVarValue>, moduleId?: string): void;
239
+ /** Send one identity-fenced action through the existing declared action channel. */
240
+ sendModuleAction(request: ModuleActionRequest): boolean;
241
+ /**
242
+ * Send one named vehicle component/panel intent through the existing action
243
+ * channel. `false` is a fail-closed refusal: nothing was sent and no sequence
244
+ * was advanced because identity/entity state was incomplete, the socket was
245
+ * closed, the sequence was exhausted, or reconnect-safe persistence failed.
246
+ * The caller may retry after authoritative state, transport, or storage recovers.
247
+ * `true` means submitted, not server-accepted; observe replicated state for
248
+ * confirmation. No caller-provided Build digest, epoch, or sequence is accepted.
249
+ */
250
+ sendVehicleComponentAction(request: VehicleComponentActionRequest): boolean;
251
+ /**
252
+ * Send one trusted detachable-part action on the same vehicle action lane.
253
+ * The request carries only the admitted action id and placement identity;
254
+ * the SDK stamps the live Build, authority epoch, and durable sequence. The
255
+ * wire deliberately has no targetBits because detachment spawns a separate
256
+ * authoritative entity instead of mutating the component bitfield.
257
+ */
258
+ sendVehicleDetachAction(request: VehicleDetachActionRequest): boolean;
259
+ /** Request the exclusive grant for a declared action on an `engaged` module. */
260
+ requestModuleEngagement(moduleId: string, action: string, args?: Record<string, RoomVarValue>): void;
261
+ /** Release the current grant through a declared action. False means this SDK holds no live grant. */
262
+ releaseModuleEngagement(moduleId: string, action: string, args?: Record<string, RoomVarValue>): boolean;
263
+ /** Read-only snapshot of the current room grant, or null after denial/release/revocation/drop. */
264
+ moduleEngagement(moduleId: string): ModuleEngagementLease | null;
265
+ /**
266
+ * Play/stop a gesture on this player (v19). 'oneshot' relays to every OTHER client as a `gesture`
267
+ * broadcast (play locally first — the room never echoes it back); 'loop'/'stop' set/clear the seat's
268
+ * synced PlayerState.loopGesture so late joiners see active loops. `clip` is a world-registered gesture
269
+ * name ('' only with 'stop'); the engine facade (CharacterMultiplayer.playAnimation) drives this for you.
270
+ */
271
+ sendGesture(clip: string, play: GesturePlay): void;
272
+ /**
273
+ * Replace this player's ENTIRE replicated attachment set (v20). Full-set replace, idempotent — the room
274
+ * writes it to synced PlayerState.attachments (no relay; schema sync fans out, late joiners converge).
275
+ * Entries carry sender-resolved socket-local offsets and must respect ATTACHMENT_LIMITS; the engine
276
+ * facade (CharacterMultiplayer.attach/detach) drives this for you.
277
+ */
278
+ sendAttachments(attachments: AttachmentEntry[]): void;
279
+ /**
280
+ * Ask the room to re-resolve THIS player's avatar (v23) — a hint with an empty payload: the room re-reads the
281
+ * equipped avatar server-side and rewrites the seat's PlayerState.avatarUrl, so a client never names the URL.
282
+ */
283
+ sendAvatarRefresh(): void;
284
+ /**
285
+ * Ask the room to re-resolve THIS player's carried emote set (v28) — the avatar hint's twin: an empty payload,
286
+ * because the room re-reads the equipped emotes server-side and replaces the seat's PlayerState.emotes whole,
287
+ * so a client never names a clip URL that lands on its own seat.
288
+ */
289
+ sendEmoteRefresh(): void;
290
+ /**
291
+ * Ask the room for a one-time World acquisition capability for one World route of THIS world (ADR-0003):
292
+ * `dkey:<key>` or `distribution:<uuid>`. The room mints it for the signed-in seat and answers only this
293
+ * client; pass the result's `capability` to the purchase. Rejects with an Error whose message is the room's
294
+ * reason (`sign_in_required`, `not_found`, `unavailable`, …) or `timeout` when the room never answers.
295
+ */
296
+ requestDistributionCapability(ref: string): Promise<DistributionCapabilityGrant>;
297
+ /**
298
+ * Join `initiator`'s paired emote, or leave the current pair with '' (v28). A REQUEST the room may refuse by
299
+ * writing nothing — read the outcome off THIS player's state.pairInitiator, never off the send. The engine
300
+ * facade drives this for you; the room owns every clear (the initiator stops, either side dies, you drift off).
301
+ */
302
+ sendEmoteJoin(initiator: string): void;
303
+ /**
304
+ * Upload an owner-authoritative entity's client-simulated state (Tier 2 Phase 4.6c). Call only for an entity
305
+ * whose `controller` is this client (state.entities[id].controller === sessionId); the room rejects others.
306
+ * Sent immediately, per-entity seq-tagged; the room gates the position against the kind's maxSpeed + clamps vars.
307
+ */
308
+ uploadEntity(entityId: string, input: {
309
+ position: Vec3;
310
+ velocity?: Vec3;
311
+ angularVelocity?: Vec3;
312
+ orientation?: Quat;
313
+ vars?: Record<string, RoomVarValue>;
314
+ epoch?: number;
315
+ }, moduleId?: string): void;
316
+ /**
317
+ * Upload MANY owner-authoritative entities in ONE message (Tier 2 Phase 4.10). Prefer this over per-entity
318
+ * uploadEntity when hosting multiple entities: the per-connection rate cap counts messages, so N single uploads
319
+ * spend N tokens/tick and starve, while one batch spends one. Position is sent as a compact [x,y,z] tuple; each
320
+ * entry is gated/clamped server-side exactly like uploadEntity. Pass only entities this client controls.
321
+ */
322
+ uploadEntities(entities: ReadonlyArray<{
323
+ id: string;
324
+ position: Vec3;
325
+ velocity?: Vec3;
326
+ angularVelocity?: Vec3;
327
+ orientation?: Quat;
328
+ vars?: Record<string, RoomVarValue>;
329
+ epoch?: number;
330
+ }>, moduleId?: string): void;
331
+ /** Sent-but-unacknowledged states — the reconciliation tail the engine NetworkDriver replays (D4). */
332
+ pendingInputs(): readonly StateMessage[];
333
+ /** Prune the reconciliation buffer once the server confirms it processed up to `seq` (D4). */
334
+ acknowledge(seq: number): void;
335
+ /** Connection dropped; the client is auto-reconnecting (built into @colyseus/sdk). */
336
+ onDrop(cb: () => void): void;
337
+ /** Auto-reconnection succeeded. */
338
+ onReconnect(cb: () => void): void;
339
+ /**
340
+ * Left for good — `code` is the close code, `reason` says WHO ended it:
341
+ * - `'switch'` this client hopped away with `Helix.multiplayer.switchRoom`. Do NOT auto-rejoin from here:
342
+ * the hop is already joining the next room (a `joinRoom()` now is refused, `switch-in-progress`).
343
+ * - `'leave'` this client left on purpose (`room.leave()` / the shell's Exit).
344
+ * - `'dropped'` nobody here asked for it: kicked, the room disposed, or the connection was lost for good.
345
+ * Fires at most once per handle. `reason` is additive — a callback that only takes `code` is unaffected.
346
+ */
347
+ onLeave(cb: (code: number, reason: HelixRoomLeaveReason) => void): void;
348
+ /** Leave intentionally (no reconnection grace held server-side). */
349
+ leave(): Promise<void>;
350
+ /**
351
+ * Guarded, live-reading views over the DECLARED game state — the typed replacement for hand-rolled
352
+ * `(vars as Record<string, unknown>)?.x` casts and frame-0 guards. `vars` = room-level, `me`/`player(id)` =
353
+ * per-player; `phase`/`currentTurn`/`isMyTurn` read the state machine + turn-order conventions.
354
+ */
355
+ readonly vars: VarsView;
356
+ readonly me: VarsView;
357
+ player(id: string): VarsView;
358
+ phase(): string;
359
+ currentTurn(): string;
360
+ isMyTurn(): boolean;
361
+ /** Guarded, live module-local room/player/entity state. */
362
+ module(moduleId: string): ModuleAccessors;
363
+ }
364
+ interface ColyseusStateSignal {
365
+ (cb: (state: unknown) => void): unknown;
366
+ remove(cb: (state: unknown) => void): void;
367
+ }
368
+ interface ColyseusRoom {
369
+ roomId: string;
370
+ sessionId: string;
371
+ reconnectionToken: string;
372
+ /**
373
+ * 0.17 internals: send() BUFFERS into a small drop-oldest ring (never throws) on a non-OPEN socket, so this is the
374
+ * only way to tell a delivered message from an enqueued one. Optional so a colyseus rename degrades to "always open".
375
+ */
376
+ readonly connection?: {
377
+ readonly isOpen: boolean;
378
+ close?(code?: number, reason?: string): void;
379
+ /** What the Room's auto-reconnection calls to open a NEW socket for the same seat (see abandonRoom). */
380
+ reconnect?(queryParams: unknown): void;
381
+ };
382
+ /**
383
+ * 0.17 Room.reconnection — the public auto-reconnection config. `enabled: false` is the documented way to
384
+ * turn it off ("Set to `false` to disable automatic reconnection entirely"). Optional so a colyseus shape
385
+ * change degrades to closing the socket only.
386
+ */
387
+ readonly reconnection?: {
388
+ enabled: boolean;
389
+ maxRetries?: number;
390
+ retryCount?: number;
391
+ isReconnecting?: boolean;
392
+ /** A drop this soon after the join is not reconnected at all (0.17 default 5000 ms). See followReconnectGrace. */
393
+ minUptime?: number;
394
+ /** The delay before retry `attempt` (0.17: 2^attempt x delay, then clamped to [minDelay, maxDelay]). */
395
+ backoff?: (attempt: number, delay: number) => number;
396
+ };
397
+ readonly state: unknown;
398
+ onStateChange: ColyseusStateSignal;
399
+ onMessage(type: string, cb: (payload: unknown) => void): unknown;
400
+ onLeave(cb: (code: number, reason?: string) => void): unknown;
401
+ onError(cb: (code: number, message?: string) => void): unknown;
402
+ onDrop(cb: (code: number, reason?: string) => void): unknown;
403
+ onReconnect(cb: () => void): unknown;
404
+ send(type: string, payload?: unknown): void;
405
+ leave(consented?: boolean): Promise<number>;
406
+ /** Drops every listener registered on the room (0.17). Optional so a rename degrades to the context guard alone. */
407
+ removeAllListeners?(): void;
408
+ }
409
+ /**
410
+ * How long ANY leave — `leave()`, the shell's helix:leave, a room hop — waits for the room's consented leave
411
+ * before detaching it by force. Colyseus only
412
+ * settles leave() when the socket's close arrives, a LEAVE written to an already-closed socket is silently
413
+ * lost, and a send while CONNECTING throws — so on a dropped or reconnecting room an unbounded await is a hop
414
+ * that never returns — and `isOpen` is no help, because a black-holed socket still reports open. 3 s is far
415
+ * beyond a healthy leave round-trip (tens of ms) and still short enough that a player watching a "joining
416
+ * match…" screen is not left wondering; past it the seat is the server's to reap through its ordinary
417
+ * drop/grace path.
418
+ */
419
+ export declare const ROOM_LEAVE_TIMEOUT_MS = 3000;
420
+ /** @deprecated The bound now covers every leave, not only a hop's — use ROOM_LEAVE_TIMEOUT_MS. */
421
+ export declare const ROOM_SWITCH_LEAVE_TIMEOUT_MS = 3000;
422
+ /**
423
+ * How long the room holds a dropped seat for its owner to reconnect, counted from when the SERVER notices the
424
+ * drop: the room server's reconnection grace (helix-colyseus-server `RECONNECT_GRACE_SEC`, 20 s; the room does
425
+ * not advertise it). See ROOM_RECONNECT_WINDOW_MS for what the SDK's automatic reconnect makes of it.
426
+ */
427
+ export declare const ROOM_RECONNECT_GRACE_MS = 20000;
428
+ /**
429
+ * How long after the CLIENT sees a drop the server may still not have noticed it, so that its grace has not
430
+ * even started. The common drops are client-first (a wifi switch, a network change, the browser going
431
+ * `offline`: Colyseus closes the socket at once), and the server only notices them on its ping timeout. The
432
+ * room server runs @colyseus/ws-transport with its defaults, a ping every 3 s and termination at the tick
433
+ * after 2 unanswered ones: up to 3 x 3 s = 9 s after the last answered ping.
434
+ */
435
+ export declare const ROOM_SERVER_DROP_DETECTION_MS: number;
436
+ /**
437
+ * How long the SDK's automatic reconnect keeps scheduling attempts after the drop it saw: the grace plus the
438
+ * server's detection time (29 s). A seat may be held until then, so giving up earlier loses players the room
439
+ * would still have taken back. Ending sooner when the seat really is gone is the server's job: it refuses a
440
+ * reconnection token it no longer holds with 4003, which ends the reconnect at once (`onLeave(4003)`).
441
+ */
442
+ export declare const ROOM_RECONNECT_WINDOW_MS: number;
443
+ /**
444
+ * An attempt still connecting when the window closes gets this much longer to finish its handshake; then it is
445
+ * closed and the reconnect gives up (`onLeave(4003, 'dropped')` at the latest 31 s after the drop).
446
+ */
447
+ export declare const ROOM_RECONNECT_ATTEMPT_ALLOWANCE_MS = 2000;
448
+ /**
449
+ * Make Colyseus's automatic reconnection follow the room's grace instead of its own defaults. Left alone, a
450
+ * 0.17 Room (a) does not reconnect at all when the socket drops within 5 s of the join (`minUptime`): the seat
451
+ * is still held, but the world is told the room is gone; and (b) when the network stays down, retries 15 times
452
+ * with an exponential backoff capped at 5 s, about a minute, long after the seat is gone. (A server that is
453
+ * reachable already ends it sooner: it refuses a token whose seat it gave away with 4003, and that close is
454
+ * not one Colyseus retries.)
455
+ *
456
+ * So: any drop is reconnected, however soon after the join; retries keep Colyseus's own backoff, but none is
457
+ * scheduled past `windowMs` after the drop the client saw (ROOM_RECONNECT_WINDOW_MS: the grace plus the time
458
+ * the server may take to notice the drop); a retry that fails after the window ends the reconnect; and an
459
+ * attempt still connecting ROOM_RECONNECT_ATTEMPT_ALLOWANCE_MS after it is closed, which ends it too. The end
460
+ * is Colyseus's own: `onLeave` with 4003 (FAILED_TO_RECONNECT). The server's own 4003 refusal still ends it as
461
+ * soon as it arrives. Each new drop (after a successful reconnect) gets a fresh window. Times are measured on a
462
+ * monotonic clock. Only the Room's public `reconnection` config, `onDrop`, `onReconnect` and `onLeave` are
463
+ * used; a Room without that config is left as it is.
464
+ */
465
+ export declare function followReconnectGrace(room: ColyseusRoom, windowMs?: number): void;
466
+ export interface MultiplayerHost {
467
+ isInitialized(): boolean;
468
+ getToken(): string | null;
469
+ getWorldId(): string | null;
470
+ /** Optional shell-provided join target (the play URL's ?instance= → helix:init instanceId): a fresh
471
+ * join is scoped to exactly that room — joinById, with NO matchmaker fallback (see joinRoom). */
472
+ getInstanceId?(): string | null;
473
+ /** Optional shell publish hook (helix:multiplayer-join-error): an instance-scoped join failed and
474
+ * did NOT fall back — the shell surfaces it so the player can choose back / fresh join explicitly. */
475
+ publishInstanceJoinError?(instanceId: string, message: string): void;
476
+ /**
477
+ * Optional shell publish hook: the SDK singleton forwards the joined room's live status to the
478
+ * embedding shell (helix:multiplayer-state) so shell UI (the tablet's Server Details panel) can render
479
+ * the REAL roomId + roster. Called on join, on roster changes, and with null on leave/teardown.
480
+ */
481
+ publishRoomState?(state: HelixMultiplayerState | null): void;
482
+ /**
483
+ * Optional voice hand-off for a room hop (switchRoom). Voice pairs 1:1 with a room instance
484
+ * (v:{worldId}:{roomId}), so it cannot follow a hop by itself: this leaves the voice room paired to the room
485
+ * being left and resolves a `resume` that re-joins voice against whatever room is current when it is called,
486
+ * with the same join options (push-to-talk key, API base / token path) — the channel, mic mode and mutes
487
+ * already survive a voice teardown. Resolves null when voice is not joined, or is pinned to an explicit
488
+ * roomId and therefore was never following the multiplayer room.
489
+ */
490
+ detachVoice?(): Promise<(() => Promise<unknown>) | null>;
491
+ /**
492
+ * Optional: true once the player has left this world (the shell's helix:leave — see `Helix.hasLeft()`).
493
+ * While it is, joinRoom() and switchRoom() reject `left` before doing anything. Absent = never left.
494
+ */
495
+ hasLeft?(): boolean;
496
+ /**
497
+ * Optional: the platform clock the SDK judges expiries by (Helix.matchmaking, Helix.party). Fed the room
498
+ * server's clock (`RoomState.serverTimeMs`) on every state patch of the joined room.
499
+ */
500
+ clock?: Pick<ServerClock, 'observe'>;
501
+ }
502
+ /** A capability the room minted for one World route (single use, ~60 s). */
503
+ export type DistributionCapabilityGrant = {
504
+ capability: string;
505
+ expiresAt: string;
506
+ ref: string;
507
+ };
508
+ /** How long a capability request waits for the room before giving up (the mint is one backend round trip). */
509
+ export declare const DISTRIBUTION_CAPABILITY_TIMEOUT_MS = 10000;
510
+ export declare class HelixMultiplayer {
511
+ private readonly host;
512
+ private finalRestClient;
513
+ private apiBaseUrl;
514
+ private shellApiBaseUrl;
515
+ private room;
516
+ private distributionCapabilitySeq;
517
+ private readonly pendingDistributionCapabilities;
518
+ private callbacks;
519
+ private seq;
520
+ private teleportSeq;
521
+ private entitySeq;
522
+ private entityBatchSeq;
523
+ private vehicleActionSeq;
524
+ private vehicleActionReconnectBaseline;
525
+ private retiredVehicleActionEpochs;
526
+ private vehicleActionManifestPersistTimer;
527
+ private reconnectCache;
528
+ private activeRoomCache;
529
+ private sessionIdentity;
530
+ private entering;
531
+ private joining;
532
+ private pendingInput;
533
+ private internalAvatarPose;
534
+ private flushTimer;
535
+ private effectiveUploadHz;
536
+ private inputBuffer;
537
+ private worldId;
538
+ private reconnectScope;
539
+ private roomType;
540
+ private instanceKey;
541
+ private ctx;
542
+ private switching;
543
+ private roomMaxPlayers;
544
+ private rosterSig;
545
+ private pendingReceipts;
546
+ private onStateAckCb;
547
+ private onEntityStateAckCb;
548
+ private engagementRequestSeq;
549
+ private moduleEngagements;
550
+ private moduleEngagementCbs;
551
+ private avatarChangedCbs;
552
+ private avatarListeners;
553
+ private nlSend;
554
+ private nlPatch;
555
+ constructor(host: MultiplayerHost);
556
+ configure(options: {
557
+ apiBaseUrl: string;
558
+ }): void;
559
+ adoptShellApiBase(url: string): void;
560
+ /**
561
+ * ADR-0003: ask the joined room for a one-time World acquisition capability (see HelixRoom's method of the same
562
+ * name). Also what the shell's Store/confirm flow reaches through `helix:distribution-capability-request`.
563
+ */
564
+ requestDistributionCapability(ref: string, timeoutMs?: number): Promise<DistributionCapabilityGrant>;
565
+ private settleDistributionCapability;
566
+ private rejectDistributionCapabilities;
567
+ currentRoomId(): string | null;
568
+ localLocomotionPack(): string | null;
569
+ sendPurchaseReceipt(receipt: string): boolean;
570
+ private stashReceipt;
571
+ private flushPendingReceipts;
572
+ sendEmoteRefresh(): boolean;
573
+ resolveApiBase(token: string | null): string | null;
574
+ joinRoom(worldId?: string, options?: JoinRoomOptions): Promise<HelixRoom>;
575
+ private refuseIfLeft;
576
+ private beginEntering;
577
+ private abandonEntered;
578
+ private abandonable;
579
+ private releaseLateRoom;
580
+ private forgetCancelledTarget;
581
+ switchRoom(target: SwitchRoomTarget, options?: SwitchRoomOptions): Promise<HelixRoom>;
582
+ private joinRoomInternal;
583
+ private connectOrForget;
584
+ private settleLeave;
585
+ private detachCurrentRoom;
586
+ private leaveBounded;
587
+ private abandonRoom;
588
+ private forceDetach;
589
+ private requestJoin;
590
+ private requestRejoin;
591
+ private makeHandle;
592
+ private watchAvatar;
593
+ private unwatchAvatar;
594
+ private adoptModuleEngagement;
595
+ private revokeModuleEngagements;
596
+ private publishRoomState;
597
+ private startFlush;
598
+ private flush;
599
+ private nlOnPatch;
600
+ private nlTick;
601
+ private persistReconnect;
602
+ private readReconnect;
603
+ private persistCurrentReconnect;
604
+ private persistVehicleActionSequence;
605
+ private retireVehicleActionSequence;
606
+ /** Adopt the server's exact accepted fences for the reconnect baseline without clobbering actions submitted
607
+ * after this connection opened. This repairs retirements missed while the seat was disconnected. */
608
+ private adoptVehicleActionFences;
609
+ private flushVehicleActionManifest;
610
+ private migrateLegacyVehicleActionSequences;
611
+ private clearReconnect;
612
+ private removePersistedReconnectMetadata;
613
+ private readActiveRoom;
614
+ private writeActiveRoom;
615
+ private clearActiveRoom;
616
+ private clearOtherTypedSlots;
617
+ private forgetReconnectSlots;
618
+ private tryReconnect;
619
+ leave(): Promise<void>;
620
+ private leaveRoom;
621
+ private teardown;
622
+ }
623
+ export declare function epochMsOf(raw: unknown): number;
624
+ export {};