@hypersoniclabs/helix-sdk 0.1.2 → 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 (115) hide show
  1. package/README.md +859 -8
  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 +65 -1
  6. package/dist/camera.js +568 -0
  7. package/dist/camera.js.map +1 -1
  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 +272 -15
  39. package/dist/index.js +1401 -91
  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 +38 -0
  66. package/dist/multiplayer-contract/final-rest.d.ts +66 -0
  67. package/dist/multiplayer-contract/final-rest.js +38 -0
  68. package/dist/multiplayer-contract/final-rest.js.map +1 -0
  69. package/dist/multiplayer-contract/index.d.ts +11 -5
  70. package/dist/multiplayer-contract/index.js +16 -5
  71. package/dist/multiplayer-contract/index.js.map +1 -1
  72. package/dist/multiplayer-contract/messages.d.ts +461 -14
  73. package/dist/multiplayer-contract/messages.js +141 -15
  74. package/dist/multiplayer-contract/messages.js.map +1 -1
  75. package/dist/multiplayer-contract/room.d.ts +55 -4
  76. package/dist/multiplayer-contract/state.d.ts +181 -1
  77. package/dist/multiplayer-contract/state.js.map +1 -1
  78. package/dist/multiplayer-final-rest.d.ts +32 -0
  79. package/dist/multiplayer-final-rest.js +217 -0
  80. package/dist/multiplayer-final-rest.js.map +1 -0
  81. package/dist/multiplayer.d.ts +507 -16
  82. package/dist/multiplayer.js +2242 -73
  83. package/dist/multiplayer.js.map +1 -1
  84. package/dist/package.json +3 -0
  85. package/dist/protocol.d.ts +668 -5
  86. package/dist/protocol.js +101 -1
  87. package/dist/protocol.js.map +1 -1
  88. package/dist/runtime-contract/index.d.ts +15 -0
  89. package/dist/runtime-contract/index.js +12 -0
  90. package/dist/runtime-contract/index.js.map +1 -0
  91. package/dist/server-clock.d.ts +25 -0
  92. package/dist/server-clock.js +88 -0
  93. package/dist/server-clock.js.map +1 -0
  94. package/dist/tsconfig.build.tsbuildinfo +1 -1
  95. package/dist/universal-vehicles.d.ts +111 -0
  96. package/dist/universal-vehicles.js +2 -0
  97. package/dist/universal-vehicles.js.map +1 -0
  98. package/dist/vault.d.ts +562 -0
  99. package/dist/vault.js +365 -0
  100. package/dist/vault.js.map +1 -0
  101. package/dist/vehicle-specialty-placement.d.ts +28 -0
  102. package/dist/vehicle-specialty-placement.js +154 -0
  103. package/dist/vehicle-specialty-placement.js.map +1 -0
  104. package/dist/vehicle-specialty-transport.d.ts +78 -0
  105. package/dist/vehicle-specialty-transport.js +183 -0
  106. package/dist/vehicle-specialty-transport.js.map +1 -0
  107. package/dist/voice.d.ts +229 -0
  108. package/dist/voice.js +1348 -0
  109. package/dist/voice.js.map +1 -0
  110. package/generated/runtime-contract/helix-runtime-contract.json +13332 -0
  111. package/generated/runtime-contract/known-answer.json +20471 -0
  112. package/generated/runtime-contract/known-answer.schema.json +630 -0
  113. package/generated/runtime-contract/runtime-contract.schema.json +607 -0
  114. package/generated/runtime-contract/unreal/HelixRuntimeContract.generated.h +908 -0
  115. package/package.json +32 -6
@@ -1,5 +1,29 @@
1
- import type { Vec3, Quat } from './state';
2
- import type { RoomVarValue } from './room';
1
+ import type { FinalRestProvenance } from './final-rest.js';
2
+ import type { Vec3, Quat, AttachmentEntry } from './state.js';
3
+ import type { RoomVarValue } from './room.js';
4
+ /**
5
+ * ADR-0003 World routes (item distributions with channel `world`). A seated player asks its room for a one-time
6
+ * acquisition capability for ONE route of the room's world; the room mints it against the backend with its room
7
+ * token and the SEAT's account, and answers only the asker. The capability then rides `POST /iwp/purchase`.
8
+ * Bare string names, deliberately outside ClientMessageType: the room owns this lane (helix-colyseus-server
9
+ * DISTRIBUTION_CAPABILITY_MESSAGE / _RESULT), and an older room simply never answers.
10
+ */
11
+ export declare const DISTRIBUTION_CAPABILITY_MESSAGE = "distributionCapability";
12
+ export declare const DISTRIBUTION_CAPABILITY_RESULT = "distributionCapabilityResult";
13
+ /** `dkey:<stable-key>` or `distribution:<uuid>`; the room refuses anything else. */
14
+ export type DistributionCapabilityRequestMessage = {
15
+ requestId: string;
16
+ ref: string;
17
+ };
18
+ export type DistributionCapabilityResultMessage = {
19
+ requestId: string;
20
+ capability: string;
21
+ expiresAt: string;
22
+ ref: string;
23
+ } | {
24
+ requestId: string;
25
+ error: string;
26
+ };
3
27
  export declare const ClientMessageType: {
4
28
  /** The player's predicted kinematic state for this tick (seq-tagged for reconciliation). */
5
29
  readonly State: "state";
@@ -7,6 +31,18 @@ export declare const ClientMessageType: {
7
31
  readonly Ability: "ability";
8
32
  /** A world-authored declared action (the generic extensibility channel — see ActionMessage). */
9
33
  readonly Action: "action";
34
+ /** Play/stop a gesture on this player's character (v19 — see GestureMessage; oneshots relay, loops sync as state). */
35
+ readonly Gesture: "gesture";
36
+ /** Replace this player's full prop-attachment set (v20 — see AttachmentsMessage; pure synced state, no relay). */
37
+ readonly Attachments: "attachments";
38
+ /** Forward a backend-minted purchase receipt to the room (v22 — see PurchaseReceiptMessage; opaque JWT, room-verified). */
39
+ readonly PurchaseReceipt: "purchaseReceipt";
40
+ /** Ask the room to re-resolve this player's avatar (v23 — see AvatarRefreshMessage; hint only, empty payload). */
41
+ readonly AvatarRefresh: "avatarRefresh";
42
+ /** Ask the room to re-resolve this player's emote set (v28 — see EmoteRefreshMessage; hint only, empty payload). */
43
+ readonly EmoteRefresh: "emoteRefresh";
44
+ /** Join (or leave) another player's paired emote (v28 — see EmoteJoinMessage; a request the room may refuse silently). */
45
+ readonly EmoteJoin: "emoteJoin";
10
46
  /** An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c — see EntityStateMessage). */
11
47
  readonly EntityState: "entityState";
12
48
  /**
@@ -25,10 +61,12 @@ export declare const ServerMessageType: {
25
61
  /** Reply to a Ping: the client's echoed timestamp + the server's current time, for offset estimation. */
26
62
  readonly Pong: "pong";
27
63
  /**
28
- * A2 reconnection ack — the player-seat divergence correction (spec §9). Sent ONLY to the uploading client and
29
- * ONLY when the movement gate REJECTED its `state` frame (the accepted case is silent — the accepted position is
30
- * already in synced state). The client snaps its local body to the anchored position and prunes its reconciliation
31
- * buffer through the echoed seq. See StateAckMessage.
64
+ * A2 reconnection ack — the player-seat divergence correction (spec §9). Sent ONLY to the uploading client, in
65
+ * two cases: the movement gate REJECTED its `state` frame, or a rule teleport/respawn re-anchored the seat (the
66
+ * proactive ack — the mover learns NOW instead of via its next rejected upload). The plain accepted case is
67
+ * silent — the accepted position is already in synced state. The client snaps its local body to the anchored
68
+ * position, prunes its reconciliation buffer through the echoed seq, and (v27) adopts the teleport epoch it
69
+ * carries. See StateAckMessage.
32
70
  */
33
71
  readonly StateAck: "stateAck";
34
72
  /**
@@ -38,6 +76,37 @@ export declare const ServerMessageType: {
38
76
  * EntityStateAckMessage.
39
77
  */
40
78
  readonly EntityStateAck: "entityStateAck";
79
+ /**
80
+ * Oneshot gesture relay (v19): player X played world-registered clip Y — broadcast to every client EXCEPT the
81
+ * sender (who already played it locally, client-predicted). Loops never use this channel — they sync via
82
+ * PlayerState.loopGesture so late joiners see them. See GestureEventMessage.
83
+ */
84
+ readonly Gesture: "gesture";
85
+ /** Authoritative transforms emitted when a declared physics group first reaches full rest. */
86
+ readonly GroupRestSnapshot: "groupRestSnapshot";
87
+ /** A module instance exhausted its per-activation work budget and was isolated. */
88
+ readonly ModuleFused: "moduleFused";
89
+ /** A sleeping/preloaded module began a fresh evaluation activation. */
90
+ readonly ModuleWake: "moduleWake";
91
+ /** An active/fused module became cold and left the active processing set. */
92
+ readonly ModuleSleep: "moduleSleep";
93
+ /** Result/revocation of an exclusive engaged-module authority request. */
94
+ readonly ModuleEngagement: "moduleEngagement";
95
+ /** Namespaced transient presentation emitted by a mounted module. */
96
+ readonly ModuleEffect: "moduleEffect";
97
+ /** A trusted root vehicle lifetime ended; recipients may retire its sparse action replay high-water. */
98
+ readonly VehicleEntityRetired: "__helix:vehicleEntityRetired";
99
+ /** Server-authoritative accepted sparse-action fences, replayed after join/reconnect. */
100
+ readonly VehicleActionFences: "__helix:vehicleActionFences";
101
+ /**
102
+ * A ticket to a `ticketed` room instance, sent PRIVATELY to each player an `openRoom` rule effect selected
103
+ * (room types, SPEC-U1). The client redeems it through the join API (`{ ticket }`) — see RoomTicketMessage.
104
+ * Like the `__helix:*` channels the name sits outside the declared-name grammar (':' and '-'), so a world
105
+ * event can never shadow it and it needs no RESERVED_MESSAGE_TYPES entry. Purely additive and server→client:
106
+ * a bundle frozen on an older SDK registers no handler and simply never hops, and no client→server type was
107
+ * added, so there is no room-before-republish ordering constraint and no CONTRACT_VERSION bump.
108
+ */
109
+ readonly RoomTicket: "helix:room-ticket";
41
110
  };
42
111
  export type ServerMessageType = (typeof ServerMessageType)[keyof typeof ServerMessageType];
43
112
  /** Per-tick state upload. Units match PlayerReplicaState (position m; all angles degrees, see *Deg). */
@@ -51,6 +120,14 @@ export interface StateMessage {
51
120
  verticalVelocity: number;
52
121
  grounded: boolean;
53
122
  crouched: boolean;
123
+ /** Physics owns the body (v25) — see PlayerReplicaState.ragdolled. OPTIONAL on the wire like the v24 gun
124
+ * fields: pre-v25 bundles omit it and must keep playing (the room leaves the schema default false). */
125
+ ragdolled?: boolean;
126
+ /** The entry shove for THIS ragdoll (v26) — unit horizontal direction × m/s, meaningful only while
127
+ * `ragdolled`. OPTIONAL like `ragdolled` itself: pre-v26 bundles omit them and replicas crumple unshoved. */
128
+ ragdollLaunchX?: number;
129
+ ragdollLaunchZ?: number;
130
+ ragdollSpeedMps?: number;
54
131
  aimYawDeg: number;
55
132
  aimPitchDeg: number;
56
133
  /**
@@ -60,6 +137,39 @@ export interface StateMessage {
60
137
  * origin is arbitrary). Optional — an older client omits it and the server falls back to its own apply-clock.
61
138
  */
62
139
  tMs?: number;
140
+ /**
141
+ * The last server teleport epoch this client has ADOPTED from a StateAck (v27). Stamped by the SDK at flush
142
+ * (like seq/tMs — worlds cannot supply it). The room drops a frame stamped BELOW the seat's current epoch:
143
+ * that frame was sampled before a teleport/respawn the client hadn't applied yet, and accepting it would
144
+ * silently undo the server's move (the in-flight-frame race). Strictly-below only — an unadopted HIGHER stamp
145
+ * (post-reconnect) passes. Optional: a pre-v27 bundle omits it and the fence skips, like `epoch` on entity
146
+ * uploads.
147
+ */
148
+ teleportSeq?: number;
149
+ /**
150
+ * Live IK reach targets (v21), world METERS — present only while the sender's arm/gaze IK is actually
151
+ * engaged (an inactive hand OMITS its field; the room then clears the seat's paired *Active flag).
152
+ * IK_LIMITS-bounded relative to this message's `position`: a hand can't plausibly reach past arm's
153
+ * length, a gaze point is capped at interaction range. Out-of-bounds drops the whole upload.
154
+ */
155
+ reachLeft?: Vec3;
156
+ reachRight?: Vec3;
157
+ lookTarget?: Vec3;
158
+ /**
159
+ * Gun state (v24) — weapon SIGNALS, not motion: replicas re-run the same local easing/FX off these fields.
160
+ * Omitted entirely when the sender carries no gun-control ability; an invalid value drops the whole upload.
161
+ *
162
+ * `shotSeq` is a monotonic per-session shot counter, +1 per real shot. It is coalesced latest-wins at
163
+ * 10/20 Hz, so consumers react to the DELTA (never assume +1); it restarts at 0 on reconnect, and a
164
+ * non-positive delta means re-anchor (never replay).
165
+ */
166
+ shotSeq?: number;
167
+ /** Weapon drawn (vs holstered). */
168
+ gunDrawn?: boolean;
169
+ /** ADS intent, not an aim fraction — replicas ease locally with the same time constant. */
170
+ aiming?: boolean;
171
+ /** Reload in progress (wire-timed on replicas). */
172
+ reloading?: boolean;
63
173
  }
64
174
  /**
65
175
  * An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c, spec §9/§10.4). The
@@ -69,6 +179,9 @@ export interface StateMessage {
69
179
  * through server-validated rules/actions — never this channel (the publish-time firewall enforces that).
70
180
  */
71
181
  export interface EntityStateMessage {
182
+ transactionId?: string;
183
+ /** Optional module provenance; when present, `entity` is local to this module instance. */
184
+ moduleId?: string;
72
185
  /** The entity id this upload is for (the state.entities map key). Rejected unless the sender is its controller. */
73
186
  entity: string;
74
187
  /** Monotonic per-entity sequence; the room ignores a stale/out-of-order frame. */
@@ -106,6 +219,7 @@ export interface EntityStateMessage {
106
219
  * fields. `v`/`ep` are omitted when unchanged/unobserved to keep the batch small.
107
220
  */
108
221
  export interface EntityStateBatchEntry {
222
+ transactionId?: string;
109
223
  /** Entity id (the state.entities map key). Rejected unless the sender is its controller. */
110
224
  e: string;
111
225
  /** World position as [x, y, z], METERS — gated against the kind's declared maxSpeed. */
@@ -128,6 +242,15 @@ export interface EntityStateBatchEntry {
128
242
  * applies each entry exactly like a single EntityStateMessage (ownership + epoch + maxSpeed gate + var clamp).
129
243
  */
130
244
  export interface EntityStateBatchMessage {
245
+ finalRest?: {
246
+ scope?: FinalRestProvenance;
247
+ version: 1;
248
+ requestId: number;
249
+ group: string;
250
+ transactionId: string;
251
+ };
252
+ /** Optional module provenance shared by every local entity id in this batch. */
253
+ moduleId?: string;
131
254
  /** Monotonic per-connection batch sequence; the room ignores a stale/out-of-order batch per entity (gate seq). */
132
255
  seq: number;
133
256
  /** One entry per hosted entity changed this tick (bounded by the room's per-owner entity cap). */
@@ -145,6 +268,40 @@ export interface AbilityMessage {
145
268
  /** true = activate, false = deactivate. */
146
269
  active: boolean;
147
270
  }
271
+ /**
272
+ * SDK-owned replay/authority fence for one named Universal Vehicle component
273
+ * action. Authored item code supplies none of these values: the SDK resolves
274
+ * the live entity epoch and immutable Build identity, then owns the sequence.
275
+ */
276
+ export interface VehicleActionEnvelope {
277
+ /** Exact authoritative moving-entity identity from the signed placement. */
278
+ entityId: string;
279
+ /** Current room-issued entity authority era. */
280
+ authorityEpoch: number;
281
+ /** Monotonic per-client/entity/authority-era action sequence. */
282
+ seq: number;
283
+ /** Immutable vehicle Build identity read from the entity's protected vBuild state. */
284
+ buildDigest: string;
285
+ /**
286
+ * Optional desired uint16 bits inside this action's trusted server mask.
287
+ * Omitted by legacy/toggle requests; when present the room validates and
288
+ * atomically replaces that masked field instead of toggling arrival state.
289
+ */
290
+ targetBits?: number;
291
+ }
292
+ /** Server-authenticated retirement of one root vehicle entity lifetime. Interest filtering never emits this. */
293
+ export interface VehicleEntityRetiredMessage {
294
+ entityId: string;
295
+ authorityEpoch: number;
296
+ }
297
+ /** Exact accepted sparse-action replay fences for this seat at one connection boundary. */
298
+ export interface VehicleActionFencesMessage {
299
+ entries: Array<{
300
+ entityId: string;
301
+ authorityEpoch: number;
302
+ seq: number;
303
+ }>;
304
+ }
148
305
  /**
149
306
  * A world-authored declared action — the generic extensibility channel (e.g. 'captureFlag',
150
307
  * 'scorePoint'). The room validates `name` against the world's declared action set and `args` against
@@ -152,10 +309,181 @@ export interface AbilityMessage {
152
309
  * module carries the envelope + arg vocabulary only, never the per-world rules.
153
310
  */
154
311
  export interface ActionMessage {
312
+ finalRest?: {
313
+ scope?: FinalRestProvenance;
314
+ version: 1;
315
+ requestId: number;
316
+ group: string;
317
+ };
318
+ /** Optional module provenance; absent addresses the byte-compatible implicit world program. */
319
+ moduleId?: string;
320
+ /** Full mounted identity used by specialized item actions. */
321
+ itemInstanceId?: string;
322
+ bundleChecksumSha256?: string;
323
+ moduleRevision?: number;
324
+ /**
325
+ * Platform-owned engaged-module envelope. `acquire` requests the exclusive room grant for this
326
+ * declared action; `release` relinquishes the current grant. Ordinary semantic verbs omit it.
327
+ */
328
+ engagement?: 'acquire' | 'release';
329
+ /** SDK-generated correlation id, present only on acquire/release requests. */
330
+ engagementRequestId?: number;
331
+ /**
332
+ * Room-issued authority epoch. The SDK stamps it on release and every post-grant semantic verb;
333
+ * authored item data never supplies or persists it.
334
+ */
335
+ engagementEpoch?: number;
155
336
  /** Action name; must be one the world's build declares. */
156
337
  name: string;
157
338
  /** Primitive/Vec3 args, validated against the declared action's schema by the room. */
158
339
  args?: Record<string, RoomVarValue>;
340
+ /**
341
+ * Optional strict vehicle-component fence on the existing action channel.
342
+ * Legacy actions omit it; a trusted vehicle placement that declares named
343
+ * component actions requires it and validates every field server-side.
344
+ */
345
+ vehicleAction?: VehicleActionEnvelope;
346
+ }
347
+ /** How a GestureMessage applies: a transient oneshot, a persistent loop, or stopping the current loop. */
348
+ export type GesturePlay = 'oneshot' | 'loop' | 'stop';
349
+ /**
350
+ * Play/stop a gesture on the sender's own character (v19). The clip name is OPAQUE to the room — gesture
351
+ * registration is client-side world data (every client compiled the same clips from the same bundle), so the
352
+ * room validates only structurally (play enum, name bounds — GESTURE_LIMITS) and never against a declared set.
353
+ * Routing by `play`: 'oneshot' → relayed as a ServerMessageType.Gesture broadcast (except sender);
354
+ * 'loop'/'stop' → written to the sender's synced PlayerState.loopGesture (no relay — schema sync carries it).
355
+ */
356
+ export interface GestureMessage {
357
+ /** Registered clip name; '' is legal only with play:'stop' (stop clears whatever loop is active, no name match required). */
358
+ clip: string;
359
+ play: GesturePlay;
360
+ }
361
+ /**
362
+ * The oneshot relay payload (v19), broadcast on ServerMessageType.Gesture to every client except the sender.
363
+ * Receivers resolve `clip` against their own world-registered set and no-op (with a warn) on an unknown name.
364
+ */
365
+ export interface GestureEventMessage {
366
+ /** The gesturing player's playerKey (a state.players map key). */
367
+ player: string;
368
+ /** The registered clip name to play as a oneshot on that player's replica. */
369
+ clip: string;
370
+ }
371
+ /**
372
+ * Structural bounds on gesture clip names — enforced by the ROOM on GestureMessage (bounds/charset hygiene,
373
+ * never vocabulary: names are opaque world data) AND by the ENGINE's pose-DSL compiler at registration, so a
374
+ * name that registers is always a name that replicates. Identifier-ish charset: starts alphanumeric, then
375
+ * alphanumerics plus `_ - . :` — printable, unambiguous as a registry key, safe in synced state.
376
+ */
377
+ export declare const GESTURE_LIMITS: {
378
+ readonly maxClipNameLength: 64;
379
+ readonly clipNamePattern: RegExp;
380
+ };
381
+ /**
382
+ * Replace the sender's ENTIRE attachment set (v20). Full-set replace, idempotent — the desired set IS the
383
+ * message, so there is no attach/detach op ordering to get wrong and a lost message heals on the next send.
384
+ * Attachments are persistent → the room writes them to synced PlayerState.attachments (late joiners
385
+ * converge); no server relay channel exists. The room validates structurally only (ATTACHMENT_LIMITS +
386
+ * https on `asset`) — asset URLs and preset names are opaque world data, the gesture-name trust shape.
387
+ */
388
+ export interface AttachmentsMessage {
389
+ attachments: AttachmentEntry[];
390
+ }
391
+ /**
392
+ * Structural bounds on the attachment set — enforced by the ROOM on AttachmentsMessage and mirrored by the
393
+ * ENGINE facade before sending, so a set that attaches locally is a set that replicates.
394
+ */
395
+ export declare const ATTACHMENT_LIMITS: {
396
+ readonly maxAttachments: 8;
397
+ readonly maxIdLength: 32;
398
+ readonly idPattern: RegExp;
399
+ readonly maxAssetUrlLength: 512;
400
+ readonly maxSocketNameLength: 64;
401
+ readonly socketNamePattern: RegExp;
402
+ readonly maxPresetLength: 32;
403
+ /** Per-axis |offset| bound, METERS — grip tuning, not teleportation. */
404
+ readonly maxOffsetM: 2;
405
+ };
406
+ /**
407
+ * Structural bounds on a player's carried emote set (v28) — enforced by the ROOM when it writes the seat's
408
+ * PlayerState.emotes. Unlike ATTACHMENT_LIMITS these bound a SERVER-resolved set, not an inbound message: the
409
+ * platform is the source, and the room still bounds it so a bad catalog row can't put an unbounded string (or a
410
+ * url a secure page would refuse to load) into replicated state. A clip URL must be SERVABLE — https anywhere,
411
+ * plus http on loopback so a dev stack's own artifact URLs survive (the room mirrors the backend's
412
+ * isServableClipUrl). Over-count, over-length, unservable and unknown-slot entries are dropped silently, never
413
+ * fatally; an unservable `audio` costs only the sound, since the clip is the emote.
414
+ */
415
+ export declare const EMOTE_LIMITS: {
416
+ /** One per wheel slot ('r0'..'r7' + sit + lie) — the set cannot be larger than the wheel it plays from. */
417
+ readonly maxEntries: 10;
418
+ /** Bounds EVERY url on an entry — `clip`, `audio` and the optional `intro`/`outro` transitions: each is fetched by every client, so they share one bound. */
419
+ readonly maxClipUrlLength: 512;
420
+ /** Bounds the wheel petal's display title. */
421
+ readonly maxLabelLength: 64;
422
+ /**
423
+ * PAIRED emotes: per-axis |offset| bound on EmoteEntry.roles, METERS in the initiator-local frame. A pair is two
424
+ * people arm's length apart (a handshake, a hug, a high-five) — the room CLAMPS to this rather than dropping the
425
+ * roles, because an over-reaching catalog row should cost composition, not the whole paired emote.
426
+ */
427
+ readonly maxPairOffsetM: 3;
428
+ /**
429
+ * Ceiling on EmoteEntry.roles.offerAtS, SECONDS — a sanity bound sitting far above any emote clip, since the
430
+ * REAL bound is the initiator clip's own length and only publish can know it (the room just clamps ≥ 0 to this).
431
+ */
432
+ readonly maxOfferAtS: 600;
433
+ };
434
+ /**
435
+ * Plausibility bounds on the v21 IK targets — enforced by the ROOM on StateMessage (an out-of-bounds
436
+ * target invalidates the whole upload, like any other bad state field) and mirrored by the ENGINE facade
437
+ * before sending. Distances are measured from the SAME message's `position` (world METERS), so the bound
438
+ * tracks the player instead of being a useless absolute world-coordinate cap.
439
+ */
440
+ export declare const IK_LIMITS: {
441
+ /** Max |reach − position| — generous arm's length for any plausible rig scale. */
442
+ readonly maxReachDistanceM: 3;
443
+ /** Max |lookTarget − position| — interaction gaze range, not a landmark stare. */
444
+ readonly maxLookDistanceM: 50;
445
+ };
446
+ /**
447
+ * Forward a settled purchase's backend-minted receipt to the room (v22). The SDK treats the JWT as OPAQUE —
448
+ * it never parses it — and the room owns every runtime check: signature, audience (helix-purchase-receipt),
449
+ * worldId, and that the claimed `sub` is the sender's own seat. Re-forwarding is safe (the room dedupes by
450
+ * purchaseId), so a repeated getPurchase poll can send the same receipt again.
451
+ */
452
+ export interface PurchaseReceiptMessage {
453
+ receipt: string;
454
+ }
455
+ /**
456
+ * Structural bound on the forwarded receipt — MAX_MESSAGE_BYTES is otherwise the only ceiling, so without
457
+ * this an oversize receipt would be a mystery drop instead of a documented reject at the sender.
458
+ */
459
+ export declare const RECEIPT_LIMITS: {
460
+ readonly maxReceiptLength: 4096;
461
+ };
462
+ /**
463
+ * Ask the room to RE-RESOLVE this player's avatar (v23) — the seat's PlayerState.avatarUrl stops being fixed at
464
+ * join. A pure HINT: the payload carries no fields (a client can never name the URL replicated onto its seat),
465
+ * the room re-reads the equipped avatar from the platform under the sender's own credential, and a refresh that
466
+ * resolves to the same URL is a no-op. Rate-capped like the other human-paced channels (a wardrobe change).
467
+ */
468
+ export type AvatarRefreshMessage = Record<string, never>;
469
+ /**
470
+ * Ask the room to RE-RESOLVE this player's carried emote set (v28) — the seat's PlayerState.emotes stops being
471
+ * fixed at join. A pure HINT with the same shape and the same reason as AvatarRefreshMessage: the payload carries
472
+ * no fields, because the room re-reads the equipped emotes from the platform under the sender's own credential
473
+ * and a client must never be able to name a clip URL that lands on its seat. Rate-capped like the avatar hint (a
474
+ * wheel change is the same human-paced wardrobe gesture, and each hint costs the room a platform re-resolve).
475
+ */
476
+ export type EmoteRefreshMessage = Record<string, never>;
477
+ /**
478
+ * Join another player's PAIRED emote, or leave the one you are in (v28). A REQUEST, not a command: the room
479
+ * validates it (the initiator is live, offering a `roles` emote right now, is not the sender, and is within
480
+ * reach) and answers by writing the sender's pair fields — or by writing nothing at all. There is no refusal
481
+ * message: the sender sees its own PlayerState.pairInitiator stay '' and its local preview simply ends, which
482
+ * is the same outcome a race with the initiator stopping produces anyway.
483
+ */
484
+ export interface EmoteJoinMessage {
485
+ /** The initiator's player id (a `players` map key), or '' to LEAVE the pair this player is in (always allowed). */
486
+ initiator: string;
159
487
  }
160
488
  /**
161
489
  * Clock-sync probe. The client sends its local send time; the room replies (Pong) with this value echoed
@@ -167,20 +495,30 @@ export interface PingMessage {
167
495
  }
168
496
  /** Reply to a Ping — the echoed client time + the server's clock at reply, for offset/RTT estimation. */
169
497
  export interface PongMessage {
498
+ finalRestVersion?: 1;
499
+ moduleFinalRestVersion?: 1;
500
+ finalRestModules?: Record<string, number>;
170
501
  clientTimeMs: number;
171
502
  serverTimeMs: number;
172
503
  }
173
504
  /**
174
505
  * A2 player-seat divergence ack (spec §9). Sent to ONE client when the room's movement gate rejected its `state`
175
- * upload — the client's prediction diverged from authority, so it must correct. Under Tier-1 lean (no server
176
- * physics) the correction is a thin SNAP: the client moves its local body to `position` (no input replay). The
177
- * accepted case sends nothing — the accepted position is already in synced state; this fires only on divergence.
506
+ * upload, OR proactively when a rule teleport/respawn re-anchored the seat (the mover must learn the move now,
507
+ * not via its next rejected frame). Under Tier-1 lean (no server physics) the correction is a thin SNAP: the
508
+ * client moves its local body to `position` (no input replay). The plain accepted case sends nothing — the
509
+ * accepted position is already in synced state; this fires only on divergence or a server-authored move.
178
510
  */
179
511
  export interface StateAckMessage {
180
512
  /** The highest client `seq` the room has processed for this seat — the client prunes its reconciliation buffer through it. */
181
513
  seq: number;
182
- /** The room's authoritative position for this seat (the last ACCEPTED upload) — the anchor the client snaps to. */
514
+ /** The room's authoritative position for this seat (the last ACCEPTED upload, or the teleport target) — the anchor the client snaps to. */
183
515
  position: Vec3;
516
+ /**
517
+ * The seat's current teleport epoch (v27), bumped by every rule teleport/respawn. The client adopts it
518
+ * ABSOLUTELY (it can go DOWN after a reconnect resets the seat) and clears its coalesced pending frame on
519
+ * change — a pre-snap position must never be stamped with the new epoch. Optional: an older room omits it.
520
+ */
521
+ teleportSeq?: number;
184
522
  }
185
523
  /**
186
524
  * One entity's slot in an EntityStateAckMessage — compact short keys + a [x,y,z] tuple, mirroring EntityStateBatchEntry
@@ -205,9 +543,95 @@ export interface EntityStateAckEntry {
205
543
  * — replacing the engine's prior conservative `0.83 × gate-reach` guess with the room's actual accepted position.
206
544
  */
207
545
  export interface EntityStateAckMessage {
546
+ /** Module provenance for every local entity id in `acks`; absent means world entities. */
547
+ moduleId?: string;
208
548
  /** One entry per hosted entity whose upload the gate rejected this tick. Never empty (the room omits the message instead). */
209
549
  acks: EntityStateAckEntry[];
210
550
  }
551
+ /** One member of an authoritative group-rest transform snapshot. */
552
+ export interface GroupRestSnapshotEntity {
553
+ /** Present on explicit final commits; legacy snapshots retain their shape. */
554
+ epoch?: number;
555
+ velocity?: Vec3;
556
+ angularVelocity?: Vec3;
557
+ id: string;
558
+ pos: Vec3;
559
+ rot: Quat;
560
+ }
561
+ /**
562
+ * Broadcast once when a declared physics group transitions to fully at rest, and sent directly to late joiners
563
+ * while that settled snapshot remains current. `seq` is monotonic within `group` for the room's lifetime.
564
+ */
565
+ export interface GroupRestSnapshotMessage {
566
+ scope?: FinalRestProvenance;
567
+ commit?: {
568
+ version: 1;
569
+ transactionId: string;
570
+ requestId: number;
571
+ };
572
+ group: string;
573
+ seq: number;
574
+ entities: GroupRestSnapshotEntity[];
575
+ }
576
+ export type ModuleWakeReason = 'always-on' | 'proximity' | 'engagement' | 'action' | 'import' | 'module' | 'external';
577
+ export interface ModuleFusedMessage {
578
+ moduleId: string;
579
+ serverTick: number;
580
+ tickNodes: number;
581
+ }
582
+ export interface ModuleWakeMessage {
583
+ moduleId: string;
584
+ reason: ModuleWakeReason;
585
+ serverTick: number;
586
+ }
587
+ export interface ModuleSleepMessage {
588
+ moduleId: string;
589
+ serverTick: number;
590
+ }
591
+ export type ModuleEngagementStatus = 'granted' | 'denied' | 'released' | 'revoked';
592
+ /**
593
+ * Direct room response for one engaged-module authority transition. Grants are exclusive and carry
594
+ * the epoch the SDK must stamp on later verbs. Denials intentionally expose no competing holder.
595
+ */
596
+ export interface ModuleEngagementMessage {
597
+ moduleId: string;
598
+ action: string;
599
+ status: ModuleEngagementStatus;
600
+ /** Echoed for acquire/release responses; absent on an unsolicited server revocation. */
601
+ requestId?: number;
602
+ /** Present for granted/released/revoked transitions; absent on denial. */
603
+ epoch?: number;
604
+ }
605
+ export interface ModuleEffectMessage {
606
+ moduleId: string;
607
+ commandId: string;
608
+ index: number;
609
+ serverTick: number;
610
+ event: string;
611
+ payload: Record<string, RoomVarValue>;
612
+ }
613
+ /**
614
+ * `helix:room-ticket` — the room's private hand-off of one ticket to one selected player (SPEC-U1 `openRoom`).
615
+ * The ticket is redeemable ONLY by the account it was issued to (the backend's atomic redeem checks the user),
616
+ * so it is safe on the wire; redeem it with `Helix.multiplayer.switchRoom({ ticket: ticketId })`.
617
+ *
618
+ * `expiresAt` is forwarded VERBATIM from the backend's instance-creation answer, which is why it is typed
619
+ * loosely: an ISO-8601 string or a Unix epoch number. The SDK normalises it to epoch milliseconds before a
620
+ * world sees it (HelixRoom.onTicket hands out a `RoomTicket`, not this wire shape).
621
+ */
622
+ export interface RoomTicketMessage {
623
+ /** The ticketed room type the instance was opened as. */
624
+ roomType: string;
625
+ /** Single-use ticket id — the join API's `{ ticket }` body. */
626
+ ticketId: string;
627
+ /** The room instance id (= the credential's `instanceKey`); also the rejoin endpoint's `:instanceId`. */
628
+ instanceId: string;
629
+ /**
630
+ * THIS ticket's redeem-by deadline (about five minutes), as the backend returned it: ISO-8601 string or Unix
631
+ * epoch (seconds or milliseconds). It is the ticket's expiry, not the instance's — the room may live longer.
632
+ */
633
+ expiresAt: string | number;
634
+ }
211
635
  /**
212
636
  * A server→client broadcast event (Tier 2 Phase 2.5, spec §10.3). A world declares named events with a
213
637
  * payload schema; a `broadcast` rule-effect sends one on the event's NAME (not a fixed ServerMessageType),
@@ -217,16 +641,23 @@ export interface EntityStateAckMessage {
217
641
  export type BroadcastPayload = Record<string, RoomVarValue>;
218
642
  /**
219
643
  * Wire message-type names a world's declared event/action names MUST NOT shadow — the fixed client→server
220
- * and server→client channels. The manifest validator rejects a declared name in this set so a `broadcast`
221
- * can't collide with `pong` (or confuse the fixed channels). Inlined in @hypersoniclabs/helix-manifest with
222
- * a cross-ref (the manifest takes no SDK dependency); keep the two in sync.
644
+ * and server→client channels that are themselves legal declared names. The manifest validator rejects a
645
+ * declared name in this set so a `broadcast` can't collide with `pong` (or confuse the fixed channels).
646
+ * Internal `__helix:*` channels are outside the declared-name grammar and need no reservation. Inlined in
647
+ * @hypersoniclabs/helix-manifest with a cross-ref (the manifest takes no SDK dependency); keep the two in sync.
223
648
  */
224
- export declare const RESERVED_MESSAGE_TYPES: readonly ["state", "ability", "action", "entityState", "entityStateBatch", "ping", "pong", "stateAck", "entityStateAck"];
649
+ export declare const RESERVED_MESSAGE_TYPES: readonly ["state", "ability", "action", "gesture", "attachments", "purchaseReceipt", "avatarRefresh", "emoteRefresh", "emoteJoin", "entityState", "entityStateBatch", "ping", "pong", "stateAck", "entityStateAck", "groupRestSnapshot", "moduleFused", "moduleWake", "moduleSleep", "moduleEngagement", "moduleEffect"];
225
650
  /** Maps each client→server message type to its payload, so senders/handlers stay in lockstep. */
226
651
  export interface ClientMessagePayloads {
227
652
  [ClientMessageType.State]: StateMessage;
228
653
  [ClientMessageType.Ability]: AbilityMessage;
229
654
  [ClientMessageType.Action]: ActionMessage;
655
+ [ClientMessageType.Gesture]: GestureMessage;
656
+ [ClientMessageType.Attachments]: AttachmentsMessage;
657
+ [ClientMessageType.PurchaseReceipt]: PurchaseReceiptMessage;
658
+ [ClientMessageType.AvatarRefresh]: AvatarRefreshMessage;
659
+ [ClientMessageType.EmoteRefresh]: EmoteRefreshMessage;
660
+ [ClientMessageType.EmoteJoin]: EmoteJoinMessage;
230
661
  [ClientMessageType.EntityState]: EntityStateMessage;
231
662
  [ClientMessageType.EntityStateBatch]: EntityStateBatchMessage;
232
663
  [ClientMessageType.Ping]: PingMessage;
@@ -236,6 +667,16 @@ export interface ServerMessagePayloads {
236
667
  [ServerMessageType.Pong]: PongMessage;
237
668
  [ServerMessageType.StateAck]: StateAckMessage;
238
669
  [ServerMessageType.EntityStateAck]: EntityStateAckMessage;
670
+ [ServerMessageType.Gesture]: GestureEventMessage;
671
+ [ServerMessageType.GroupRestSnapshot]: GroupRestSnapshotMessage;
672
+ [ServerMessageType.ModuleFused]: ModuleFusedMessage;
673
+ [ServerMessageType.ModuleWake]: ModuleWakeMessage;
674
+ [ServerMessageType.ModuleSleep]: ModuleSleepMessage;
675
+ [ServerMessageType.ModuleEngagement]: ModuleEngagementMessage;
676
+ [ServerMessageType.ModuleEffect]: ModuleEffectMessage;
677
+ [ServerMessageType.VehicleEntityRetired]: VehicleEntityRetiredMessage;
678
+ [ServerMessageType.VehicleActionFences]: VehicleActionFencesMessage;
679
+ [ServerMessageType.RoomTicket]: RoomTicketMessage;
239
680
  }
240
681
  /**
241
682
  * Per-connection rate ceilings (messages/second) the room enforces; over-rate clients are dropped.
@@ -251,6 +692,12 @@ export declare const MESSAGE_RATE: {
251
692
  readonly stateHz: 10;
252
693
  readonly abilityHz: 20;
253
694
  readonly actionHz: 20;
695
+ readonly gestureHz: 5;
696
+ readonly attachmentsHz: 4;
697
+ readonly purchaseReceiptHz: 2;
698
+ readonly avatarRefreshHz: 1;
699
+ readonly emoteRefreshHz: 1;
700
+ readonly emoteJoinHz: 2;
254
701
  readonly entityStateHz: 10;
255
702
  readonly pingHz: 4;
256
703
  readonly maxUploadHz: 20;