@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,10 +1,12 @@
1
- // Client → server messages. The SDK send path emits these; the room dispatches them through a
2
- // table keyed by ClientMessageType and validates every payload before mutating authoritative state
3
- // (the room owns runtime validation — this module is types + limits only, no validator, no deps).
4
- //
5
- // Tier 1 (lean authoritative, no server physics): the client predicts locally and sends its state
6
- // each tick (seq-tagged so the room can echo for reconciliation); the room validates bounds/rate and
7
- // writes the authoritative copy. Discrete intents (ability on/off) are their own message.
1
+ /**
2
+ * ADR-0003 World routes (item distributions with channel `world`). A seated player asks its room for a one-time
3
+ * acquisition capability for ONE route of the room's world; the room mints it against the backend with its room
4
+ * token and the SEAT's account, and answers only the asker. The capability then rides `POST /iwp/purchase`.
5
+ * Bare string names, deliberately outside ClientMessageType: the room owns this lane (helix-colyseus-server
6
+ * DISTRIBUTION_CAPABILITY_MESSAGE / _RESULT), and an older room simply never answers.
7
+ */
8
+ export const DISTRIBUTION_CAPABILITY_MESSAGE = 'distributionCapability';
9
+ export const DISTRIBUTION_CAPABILITY_RESULT = 'distributionCapabilityResult';
8
10
  export const ClientMessageType = {
9
11
  /** The player's predicted kinematic state for this tick (seq-tagged for reconciliation). */
10
12
  State: 'state',
@@ -12,6 +14,18 @@ export const ClientMessageType = {
12
14
  Ability: 'ability',
13
15
  /** A world-authored declared action (the generic extensibility channel — see ActionMessage). */
14
16
  Action: 'action',
17
+ /** Play/stop a gesture on this player's character (v19 — see GestureMessage; oneshots relay, loops sync as state). */
18
+ Gesture: 'gesture',
19
+ /** Replace this player's full prop-attachment set (v20 — see AttachmentsMessage; pure synced state, no relay). */
20
+ Attachments: 'attachments',
21
+ /** Forward a backend-minted purchase receipt to the room (v22 — see PurchaseReceiptMessage; opaque JWT, room-verified). */
22
+ PurchaseReceipt: 'purchaseReceipt',
23
+ /** Ask the room to re-resolve this player's avatar (v23 — see AvatarRefreshMessage; hint only, empty payload). */
24
+ AvatarRefresh: 'avatarRefresh',
25
+ /** Ask the room to re-resolve this player's emote set (v28 — see EmoteRefreshMessage; hint only, empty payload). */
26
+ EmoteRefresh: 'emoteRefresh',
27
+ /** Join (or leave) another player's paired emote (v28 — see EmoteJoinMessage; a request the room may refuse silently). */
28
+ EmoteJoin: 'emoteJoin',
15
29
  /** An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c — see EntityStateMessage). */
16
30
  EntityState: 'entityState',
17
31
  /**
@@ -29,10 +43,12 @@ export const ServerMessageType = {
29
43
  /** Reply to a Ping: the client's echoed timestamp + the server's current time, for offset estimation. */
30
44
  Pong: 'pong',
31
45
  /**
32
- * A2 reconnection ack — the player-seat divergence correction (spec §9). Sent ONLY to the uploading client and
33
- * ONLY when the movement gate REJECTED its `state` frame (the accepted case is silent — the accepted position is
34
- * already in synced state). The client snaps its local body to the anchored position and prunes its reconciliation
35
- * buffer through the echoed seq. See StateAckMessage.
46
+ * A2 reconnection ack — the player-seat divergence correction (spec §9). Sent ONLY to the uploading client, in
47
+ * two cases: the movement gate REJECTED its `state` frame, or a rule teleport/respawn re-anchored the seat (the
48
+ * proactive ack — the mover learns NOW instead of via its next rejected upload). The plain accepted case is
49
+ * silent — the accepted position is already in synced state. The client snaps its local body to the anchored
50
+ * position, prunes its reconciliation buffer through the echoed seq, and (v27) adopts the teleport epoch it
51
+ * carries. See StateAckMessage.
36
52
  */
37
53
  StateAck: 'stateAck',
38
54
  /**
@@ -42,14 +58,118 @@ export const ServerMessageType = {
42
58
  * EntityStateAckMessage.
43
59
  */
44
60
  EntityStateAck: 'entityStateAck',
61
+ /**
62
+ * Oneshot gesture relay (v19): player X played world-registered clip Y — broadcast to every client EXCEPT the
63
+ * sender (who already played it locally, client-predicted). Loops never use this channel — they sync via
64
+ * PlayerState.loopGesture so late joiners see them. See GestureEventMessage.
65
+ */
66
+ Gesture: 'gesture',
67
+ /** Authoritative transforms emitted when a declared physics group first reaches full rest. */
68
+ GroupRestSnapshot: 'groupRestSnapshot',
69
+ /** A module instance exhausted its per-activation work budget and was isolated. */
70
+ ModuleFused: 'moduleFused',
71
+ /** A sleeping/preloaded module began a fresh evaluation activation. */
72
+ ModuleWake: 'moduleWake',
73
+ /** An active/fused module became cold and left the active processing set. */
74
+ ModuleSleep: 'moduleSleep',
75
+ /** Result/revocation of an exclusive engaged-module authority request. */
76
+ ModuleEngagement: 'moduleEngagement',
77
+ /** Namespaced transient presentation emitted by a mounted module. */
78
+ ModuleEffect: 'moduleEffect',
79
+ /** A trusted root vehicle lifetime ended; recipients may retire its sparse action replay high-water. */
80
+ VehicleEntityRetired: '__helix:vehicleEntityRetired',
81
+ /** Server-authoritative accepted sparse-action fences, replayed after join/reconnect. */
82
+ VehicleActionFences: '__helix:vehicleActionFences',
83
+ /**
84
+ * A ticket to a `ticketed` room instance, sent PRIVATELY to each player an `openRoom` rule effect selected
85
+ * (room types, SPEC-U1). The client redeems it through the join API (`{ ticket }`) — see RoomTicketMessage.
86
+ * Like the `__helix:*` channels the name sits outside the declared-name grammar (':' and '-'), so a world
87
+ * event can never shadow it and it needs no RESERVED_MESSAGE_TYPES entry. Purely additive and server→client:
88
+ * a bundle frozen on an older SDK registers no handler and simply never hops, and no client→server type was
89
+ * added, so there is no room-before-republish ordering constraint and no CONTRACT_VERSION bump.
90
+ */
91
+ RoomTicket: 'helix:room-ticket',
92
+ };
93
+ /**
94
+ * Structural bounds on gesture clip names — enforced by the ROOM on GestureMessage (bounds/charset hygiene,
95
+ * never vocabulary: names are opaque world data) AND by the ENGINE's pose-DSL compiler at registration, so a
96
+ * name that registers is always a name that replicates. Identifier-ish charset: starts alphanumeric, then
97
+ * alphanumerics plus `_ - . :` — printable, unambiguous as a registry key, safe in synced state.
98
+ */
99
+ export const GESTURE_LIMITS = {
100
+ maxClipNameLength: 64,
101
+ clipNamePattern: /^[A-Za-z0-9][A-Za-z0-9_\-.:]*$/,
102
+ };
103
+ /**
104
+ * Structural bounds on the attachment set — enforced by the ROOM on AttachmentsMessage and mirrored by the
105
+ * ENGINE facade before sending, so a set that attaches locally is a set that replicates.
106
+ */
107
+ export const ATTACHMENT_LIMITS = {
108
+ maxAttachments: 8,
109
+ maxIdLength: 32,
110
+ idPattern: /^[A-Za-z0-9][A-Za-z0-9_\-.:]*$/,
111
+ maxAssetUrlLength: 512,
112
+ maxSocketNameLength: 64,
113
+ socketNamePattern: /^[A-Za-z0-9][A-Za-z0-9_\-.]*$/,
114
+ maxPresetLength: 32,
115
+ /** Per-axis |offset| bound, METERS — grip tuning, not teleportation. */
116
+ maxOffsetM: 2,
117
+ };
118
+ /**
119
+ * Structural bounds on a player's carried emote set (v28) — enforced by the ROOM when it writes the seat's
120
+ * PlayerState.emotes. Unlike ATTACHMENT_LIMITS these bound a SERVER-resolved set, not an inbound message: the
121
+ * platform is the source, and the room still bounds it so a bad catalog row can't put an unbounded string (or a
122
+ * url a secure page would refuse to load) into replicated state. A clip URL must be SERVABLE — https anywhere,
123
+ * plus http on loopback so a dev stack's own artifact URLs survive (the room mirrors the backend's
124
+ * isServableClipUrl). Over-count, over-length, unservable and unknown-slot entries are dropped silently, never
125
+ * fatally; an unservable `audio` costs only the sound, since the clip is the emote.
126
+ */
127
+ export const EMOTE_LIMITS = {
128
+ /** One per wheel slot ('r0'..'r7' + sit + lie) — the set cannot be larger than the wheel it plays from. */
129
+ maxEntries: 10,
130
+ /** 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. */
131
+ maxClipUrlLength: 512,
132
+ /** Bounds the wheel petal's display title. */
133
+ maxLabelLength: 64,
134
+ /**
135
+ * PAIRED emotes: per-axis |offset| bound on EmoteEntry.roles, METERS in the initiator-local frame. A pair is two
136
+ * people arm's length apart (a handshake, a hug, a high-five) — the room CLAMPS to this rather than dropping the
137
+ * roles, because an over-reaching catalog row should cost composition, not the whole paired emote.
138
+ */
139
+ maxPairOffsetM: 3,
140
+ /**
141
+ * Ceiling on EmoteEntry.roles.offerAtS, SECONDS — a sanity bound sitting far above any emote clip, since the
142
+ * REAL bound is the initiator clip's own length and only publish can know it (the room just clamps ≥ 0 to this).
143
+ */
144
+ maxOfferAtS: 600,
145
+ };
146
+ /**
147
+ * Plausibility bounds on the v21 IK targets — enforced by the ROOM on StateMessage (an out-of-bounds
148
+ * target invalidates the whole upload, like any other bad state field) and mirrored by the ENGINE facade
149
+ * before sending. Distances are measured from the SAME message's `position` (world METERS), so the bound
150
+ * tracks the player instead of being a useless absolute world-coordinate cap.
151
+ */
152
+ export const IK_LIMITS = {
153
+ /** Max |reach − position| — generous arm's length for any plausible rig scale. */
154
+ maxReachDistanceM: 3,
155
+ /** Max |lookTarget − position| — interaction gaze range, not a landmark stare. */
156
+ maxLookDistanceM: 50,
157
+ };
158
+ /**
159
+ * Structural bound on the forwarded receipt — MAX_MESSAGE_BYTES is otherwise the only ceiling, so without
160
+ * this an oversize receipt would be a mystery drop instead of a documented reject at the sender.
161
+ */
162
+ export const RECEIPT_LIMITS = {
163
+ maxReceiptLength: 4096,
45
164
  };
46
165
  /**
47
166
  * Wire message-type names a world's declared event/action names MUST NOT shadow — the fixed client→server
48
- * and server→client channels. The manifest validator rejects a declared name in this set so a `broadcast`
49
- * can't collide with `pong` (or confuse the fixed channels). Inlined in @hypersoniclabs/helix-manifest with
50
- * a cross-ref (the manifest takes no SDK dependency); keep the two in sync.
167
+ * and server→client channels that are themselves legal declared names. The manifest validator rejects a
168
+ * declared name in this set so a `broadcast` can't collide with `pong` (or confuse the fixed channels).
169
+ * Internal `__helix:*` channels are outside the declared-name grammar and need no reservation. Inlined in
170
+ * @hypersoniclabs/helix-manifest with a cross-ref (the manifest takes no SDK dependency); keep the two in sync.
51
171
  */
52
- export const RESERVED_MESSAGE_TYPES = ['state', 'ability', 'action', 'entityState', 'entityStateBatch', 'ping', 'pong', 'stateAck', 'entityStateAck'];
172
+ export const RESERVED_MESSAGE_TYPES = ['state', 'ability', 'action', 'gesture', 'attachments', 'purchaseReceipt', 'avatarRefresh', 'emoteRefresh', 'emoteJoin', 'entityState', 'entityStateBatch', 'ping', 'pong', 'stateAck', 'entityStateAck', 'groupRestSnapshot', 'moduleFused', 'moduleWake', 'moduleSleep', 'moduleEngagement', 'moduleEffect'];
53
173
  /**
54
174
  * Per-connection rate ceilings (messages/second) the room enforces; over-rate clients are dropped.
55
175
  * State is the throttled input channel (plan D3); ability is bursty but bounded.
@@ -64,6 +184,12 @@ export const MESSAGE_RATE = {
64
184
  stateHz: 10,
65
185
  abilityHz: 20,
66
186
  actionHz: 20,
187
+ gestureHz: 5, // human-paced by nature (a wave, a loop toggle) — bursty but never sustained; over-rate = drop, same as the rest
188
+ attachmentsHz: 4, // equip/unequip is human-paced; full-set replace is idempotent, so a dropped burst heals on the next send
189
+ purchaseReceiptHz: 2, // a purchase is far rarer than a gesture (and re-forwards dedupe server-side); over-rate = drop, same as the rest
190
+ avatarRefreshHz: 1, // a wardrobe change is the rarest human-paced intent, and each hint costs the room a platform re-resolve
191
+ emoteRefreshHz: 1, // v28: same channel shape, same cost (a platform re-resolve per hint) → the same ceiling as the avatar hint
192
+ emoteJoinHz: 2, // v28: join/leave is a human-paced tap on someone else's emote; over-rate DROPS (a hopeful double-tap is not a cheat)
67
193
  entityStateHz: 10, // owner-entity upload — same cadence as the player state channel (one bucket per connection)
68
194
  pingHz: 4, // clock-sync probe — a few per second is ample to track offset/RTT
69
195
  maxUploadHz: 20, // ceiling a world may raise stateHz/entityStateHz to (multiplayer.uploadHz:20); = SIM_HZ, above it buys nothing
@@ -1 +1 @@
1
- {"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/multiplayer-contract/messages.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,mGAAmG;AACnG,kGAAkG;AAClG,EAAE;AACF,kGAAkG;AAClG,qGAAqG;AACrG,0FAA0F;AAK1F,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,4FAA4F;IAC5F,KAAK,EAAE,OAAO;IACd,4FAA4F;IAC5F,OAAO,EAAE,SAAS;IAClB,gGAAgG;IAChG,MAAM,EAAE,QAAQ;IAChB,yHAAyH;IACzH,WAAW,EAAE,aAAa;IAC1B;;;;;OAKG;IACH,gBAAgB,EAAE,kBAAkB;IACpC,sGAAsG;IACtG,IAAI,EAAE,MAAM;CACJ,CAAC;AAGX,sGAAsG;AACtG,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,yGAAyG;IACzG,IAAI,EAAE,MAAM;IACZ;;;;;OAKG;IACH,QAAQ,EAAE,UAAU;IACpB;;;;;OAKG;IACH,cAAc,EAAE,gBAAgB;CACxB,CAAC;AA8LX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,CAAU,CAAC;AAmB/J;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,EAAE;IACX,SAAS,EAAE,EAAE;IACb,QAAQ,EAAE,EAAE;IACZ,aAAa,EAAE,EAAE,EAAE,6FAA6F;IAChH,MAAM,EAAE,CAAC,EAAE,mEAAmE;IAC9E,WAAW,EAAE,EAAE,EAAE,gHAAgH;CACzH,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,YAAY,EAAE,IAAI,EAAE,mJAAmJ;IACvK,8GAA8G;IAC9G,gHAAgH;IAChH,mHAAmH;IACnH,2GAA2G;IAC3G,iHAAiH;IACjH,kHAAkH;IAClH,gHAAgH;IAChH,uBAAuB,EAAE,GAAG;IAC5B,YAAY,EAAE,GAAG,EAAE,0IAA0I;IAC7J,0GAA0G;IAC1G,iHAAiH;IACjH,iHAAiH;IACjH,mHAAmH;IACnH,8GAA8G;IAC9G,yGAAyG;IACzG,UAAU,EAAE,CAAC,EAAE,uEAAuE;IACtF,OAAO,EAAE,GAAG,EAAE,wFAAwF;CAC9F,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC"}
1
+ {"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/multiplayer-contract/messages.ts"],"names":[],"mappings":"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"}
@@ -1,5 +1,5 @@
1
- import type { Vec3, Quat } from './state';
2
- import type { PlayerIdentity, PlayerReplicaState } from './state';
1
+ import type { Vec3, Quat } from './state.js';
2
+ import type { PlayerIdentity, PlayerReplicaState } from './state.js';
3
3
  /**
4
4
  * The runtime value vocabulary for declared custom state. A `ref`-typed var's value is the **id** of a live
5
5
  * member (a player's `playerKey` or an entity id) as a string, or `null` when unset/dangling — hence `null`
@@ -46,6 +46,12 @@ export interface PlayerState extends PlayerIdentity, PlayerReplicaState {
46
46
  * rendered MOTION. Monotonic per seat; only deltas are meaningful (origin = the sender's arbitrary clock base).
47
47
  */
48
48
  posT: number;
49
+ /**
50
+ * Server-owned monotonic avatar refresh revision (v33). The room increments this after each successful
51
+ * authoritative equipped-avatar read, including when the base GLB URL is unchanged but its composition changed.
52
+ * Older rooms omit the field; clients treat an absent value as 0.
53
+ */
54
+ avatarRevision: number;
49
55
  }
50
56
  /**
51
57
  * RESERVED (Tier 2): a server-spawned object (pickup, projectile, NPC). Empty in v1 — the shape is
@@ -56,6 +62,11 @@ export interface EntityState {
56
62
  id: string;
57
63
  /** Author-defined kind (e.g. 'flag', 'pickup'). */
58
64
  kind: string;
65
+ /**
66
+ * Server-owned logical seat occupancy for the opt-in dynamic Universal
67
+ * Vehicle ABI. Older/static Worlds omit this map and retain authored vars.
68
+ */
69
+ vehicleSeats?: Record<string, string>;
59
70
  position?: Vec3;
60
71
  /**
61
72
  * Physics state — present ONLY for a `physics` (dynamic-body) kind (networked-physics, plan Phase 0). A kinematic
@@ -79,8 +90,15 @@ export interface EntityState {
79
90
  * prior owner's in-flight frames after ownership moved). 0 at spawn; clients only read it.
80
91
  */
81
92
  authorityEpoch: number;
82
- /** Declared custom vars (same vocabulary as roomVars). */
83
- vars: RoomVars;
93
+ /**
94
+ * Declared custom vars (same vocabulary as roomVars). A root vehicle with a
95
+ * signed detach protocol also carries `vDetachBits`: a server-owned uint16
96
+ * whose permanent bits identify parts that have detached. Clients only read
97
+ * this value; detached-child expiry never clears it.
98
+ */
99
+ vars: RoomVars & {
100
+ readonly vDetachBits?: number;
101
+ };
84
102
  /**
85
103
  * Source-time stamp (ms) of this entity's current `position` — the server's apply-clock (owner-entity sender-time is
86
104
  * a follow-up; server-authoritative entities self-stamp each tick). Consumers space interpolation by `posT` deltas,
@@ -88,6 +106,29 @@ export interface EntityState {
88
106
  */
89
107
  posT: number;
90
108
  }
109
+ /** One synchronized module-instance chunk group. Local ids are meaningful only together with its module id. */
110
+ export interface ModuleState {
111
+ roomVars: RoomVars;
112
+ players: Record<string, {
113
+ vars: RoomVars;
114
+ }>;
115
+ entities: Record<string, EntityState>;
116
+ phase: string;
117
+ phaseStartTick: number;
118
+ timerDeadlines: Record<string, number>;
119
+ }
120
+ /**
121
+ * Fixed public wire for a module installed after a room's reflection handshake.
122
+ * The authoritative room keeps the full typed program/state privately and
123
+ * projects only creator-declared public scalar room vars into these maps.
124
+ */
125
+ export interface DynamicModuleState {
126
+ phase: string;
127
+ externalRevision: number;
128
+ booleans: Record<string, boolean>;
129
+ numbers: Record<string, number>;
130
+ strings: Record<string, string>;
131
+ }
91
132
  /** The authoritative shared state. Always carries all three collections (entities empty until Tier 2). */
92
133
  export interface RoomState {
93
134
  /** Per-player authoritative state, keyed by player id. Realized as a colyseus MapSchema. */
@@ -123,4 +164,14 @@ export interface RoomState {
123
164
  * without a per-tick countdown var. An entry is removed when the timer fires or is cancelled.
124
165
  */
125
166
  timerDeadlines: Record<string, number>;
167
+ /**
168
+ * S2 module-v1 instance groups, addressed by the transport key `m:<moduleId>`. Absent on every legacy world;
169
+ * use `room.module(id)` rather than indexing this transport container directly.
170
+ */
171
+ modules?: Record<string, ModuleState>;
172
+ /**
173
+ * Trusted runtime modules added after room creation. Present only for a
174
+ * dynamic-module ABI build; legacy Worlds retain their exact reflected shape.
175
+ */
176
+ dynamicModules?: Record<string, DynamicModuleState>;
126
177
  }
@@ -18,10 +18,18 @@ export declare const UNITS: {
18
18
  };
19
19
  /** Stable per-player identity (set at join from the room credential; not part of the per-tick churn). */
20
20
  export interface PlayerIdentity {
21
- /** Opaque per-connection room playerKey (= the state.players map key). NOT the credential `sub` — that stays server-side (§4). */
21
+ /** Opaque per-connection room playerKey (= the state.players map key). Gameplay state is keyed by THIS, never by `userId`. */
22
22
  id: string;
23
23
  /** Sanitized display name for nameplates (sanitized before it enters room state — see plan H4). */
24
24
  displayName: string;
25
+ /**
26
+ * The player's PLATFORM user id (the credential `sub`), so a roster UI can link a seat to a real
27
+ * profile (batch /api/v1/users lookup, profile drill-in). v18 deliberately supersedes the original §4
28
+ * stance that `sub` never replicates: user ids are already public directory data on the platform, so
29
+ * room-mates learn nothing new. Copied once at join from the verified credential, never client-supplied.
30
+ * '' when the room predates v18. Gameplay state stays keyed by the opaque per-connection `id`.
31
+ */
32
+ userId: string;
25
33
  /**
26
34
  * CDN URL of this player's equipped universal avatar (a converted single-file GLB on the
27
35
  * helix-humanoid rig), or '' when they have none — clients render the default body on ''.
@@ -31,6 +39,84 @@ export interface PlayerIdentity {
31
39
  */
32
40
  avatarUrl: string;
33
41
  }
42
+ /**
43
+ * One replicated prop attachment (v20). Exactly what a remote replica needs to render the prop: the
44
+ * asset URL (opaque world data — every client fetches the same CDN asset), the socket name, and the
45
+ * sender-RESOLVED socket-local offsets — the preset is applied at the sender, so replicas place the
46
+ * prop correctly across humanoid-character version skew. `preset` still rides the wire as a forward
47
+ * hook (Phase 3 pairs presets with grip finger poses); placement never depends on it.
48
+ */
49
+ export interface AttachmentEntry {
50
+ /** Client-generated id, unique within the seat (ATTACHMENT_LIMITS.idPattern); replicas diff + evict by it. */
51
+ id: string;
52
+ /** Prop GLB URL (https, room-sanitized, length-bounded). A failed/unknown asset no-ops on replicas. */
53
+ asset: string;
54
+ /** Socket name on the helix-humanoid rig (e.g. 'hand_r.grip'); a socket the replica's rig lacks no-ops. */
55
+ socket: string;
56
+ /** Socket-local offset, METERS. Vec3 like every other wire position (the room mirrors it as Vec3Schema). */
57
+ position: Vec3;
58
+ /** Socket-local orientation, DEGREES (XYZ euler order), as a Vec3 {x,y,z}. */
59
+ rotationEulerDeg: Vec3;
60
+ /** HELD_ITEM_PRESETS key or '' — the offsets above are already final. */
61
+ preset: string;
62
+ }
63
+ /**
64
+ * One emote the player CARRIES (v28) — an owned item, resolved onto the seat by the ROOM from the platform,
65
+ * never named by the client (the `avatarUrl` trust shape, not the `attachments` one). `slot` is the wheel
66
+ * position it plays from, `clip` the animation URL every client fetches for itself, `playback` how it runs.
67
+ */
68
+ export interface EmoteEntry {
69
+ /** Wheel position: 'r0'..'r7' are the eight radial slots, 'sit'/'lie' the two posture emotes. */
70
+ slot: 'r0' | 'r1' | 'r2' | 'r3' | 'r4' | 'r5' | 'r6' | 'r7' | 'sit' | 'lie';
71
+ /** The universal-item id this emote came from; replicas diff + evict by (slot, itemId). */
72
+ itemId: string;
73
+ /** Clip URL (servable, room-sanitized, EMOTE_LIMITS-bounded). A failed/unknown clip no-ops on replicas. */
74
+ clip: string;
75
+ /** How the clip runs once triggered: once through, or until it is stopped. */
76
+ playback: 'oneshot' | 'loop';
77
+ /**
78
+ * The emote's SOUND url, every client fetches it for itself exactly like `clip` and under the same servable
79
+ * rule. Absent when the emote is silent — audio is garnish, so a clip whose sound fails sanitization still
80
+ * lands, without it.
81
+ */
82
+ audio?: string;
83
+ /** The item's display title, for the wheel's petals. Nameplate-sanitized + capped at EMOTE_LIMITS.maxLabelLength; absent when the platform named it nothing. */
84
+ label?: string;
85
+ /**
86
+ * Optional ENTER transition: plays once and chains into `clip`. Same servable-url rule and the same
87
+ * EMOTE_LIMITS.maxClipUrlLength bound as `clip`. Never present with `roles`.
88
+ */
89
+ intro?: string;
90
+ /**
91
+ * Optional EXIT transition: plays on a deliberate end and on a oneshot's natural completion. Same servable-url
92
+ * rule and bound as `clip`. Never present with `roles`. It replicates through the v19 `gesture` relay under the
93
+ * suffixed name `emote.<slot>:outro` — the relay is name-opaque, so no new message channel exists for it.
94
+ */
95
+ outro?: string;
96
+ /**
97
+ * PAIRED emote (v28): the second role this emote offers, so another player can join it. Absent = a solo emote,
98
+ * and only an 'r0'..'r7' slot may carry it (the room strips it elsewhere) — the posture slots are stances, not
99
+ * invitations. The INITIATOR is whoever plays the emote; a joiner runs `joinerClip` at the offset below,
100
+ * which is expressed in the INITIATOR-LOCAL frame (+Z = the initiator's facing, +X their right) so the pair
101
+ * stays composed wherever the initiator stands. The offer itself is a HELD POSE (`offerAtS`), and a pair is
102
+ * strictly 1:1 — the room refuses a second joiner on an initiator that already has one.
103
+ */
104
+ roles?: {
105
+ /** The joiner's clip URL — same servable-url rule and same EMOTE_LIMITS.maxClipUrlLength bound as `clip`. */
106
+ joinerClip: string;
107
+ /**
108
+ * The OFFER freeze, SECONDS into the INITIATOR's own `clip`: the engine plays 0→offerAtS once as a wind-up, then
109
+ * HOLDS that pose until a joiner arrives or the initiator cancels. ≥ 0 (0 = the first frame), bounded by
110
+ * EMOTE_LIMITS.maxOfferAtS and independent of `playback`, which describes only the JOINED performance.
111
+ */
112
+ offerAtS: number;
113
+ /** Joiner offset from the initiator, METERS, initiator-local; each axis clamped to ±EMOTE_LIMITS.maxPairOffsetM. */
114
+ offsetX: number;
115
+ offsetZ: number;
116
+ /** The joiner's facing RELATIVE to the initiator's, DEGREES, normalized to [−180, 180] (180 = facing them). */
117
+ offsetYawDeg: number;
118
+ };
119
+ }
34
120
  /**
35
121
  * The per-tick replicated kinematic + animation parameters for one player. The room holds the
36
122
  * authoritative copy (a @colyseus/schema mirror of these fields); the NetworkDriver maps each field
@@ -52,10 +138,104 @@ export interface PlayerReplicaState {
52
138
  grounded: boolean;
53
139
  /** Crouch stance. → routes the locomotion anim graph to its crouched states. */
54
140
  crouched: boolean;
141
+ /**
142
+ * Physics owns this player's body (v25) — the death ragdoll, or a world's manual `character.ragdoll.enter()`.
143
+ * Client-authoritative cosmetic state like `crouched`: replicas mirror it into their OWN ragdoll driver, so a
144
+ * late joiner sees a limp player through STATE, not a missed event.
145
+ */
146
+ ragdolled: boolean;
147
+ /**
148
+ * The shove this ragdoll STARTED with (v26): unit horizontal direction × speed (m/s); all 0 when the body just
149
+ * crumpled. Held stable while `ragdolled` is true so a replica that observes the false→true EDGE re-creates the
150
+ * entry impulse on its own corpse. A late joiner reads state (not the edge) and must NOT re-apply it — the
151
+ * sender's followed position already encodes where the flight ended.
152
+ */
153
+ ragdollLaunchX: number;
154
+ ragdollLaunchZ: number;
155
+ ragdollSpeedMps: number;
55
156
  /** Aim yaw, DEGREES (world). → blackboard 'cameraYaw' (aim-additive source). */
56
157
  aimYawDeg: number;
57
158
  /** Aim pitch, DEGREES. → blackboard 'cameraPitch' (aim-additive source). */
58
159
  aimPitchDeg: number;
59
160
  /** Ability ids currently active (e.g. ['locomotion','fly']). Drives remote ability activation. */
60
161
  activeAbilities: string[];
162
+ /**
163
+ * The world-registered LOOPING gesture clip this player currently plays, '' when none (v19). Loops replicate
164
+ * as STATE — not events — so a late joiner starts them at replica spawn; oneshot gestures ride the transient
165
+ * `gesture` broadcast instead. The name is opaque world data: every client registered the same clips from the
166
+ * same bundle (registerAnimation), so only the name crosses the wire; an unknown name renders as no gesture.
167
+ */
168
+ loopGesture: string;
169
+ /**
170
+ * The props currently attached to this player (v20). Attachments are persistent, so they sync as STATE —
171
+ * a late joiner converges at replica spawn — never as events. Written whole by the `attachments` full-set
172
+ * replace message; bounded by ATTACHMENT_LIMITS.maxAttachments; [] when none (or the room predates v20).
173
+ */
174
+ attachments: AttachmentEntry[];
175
+ /**
176
+ * Live IK reach state (v21) — the WORLD-SPACE point each hand's procedural arm IK is holding (ik.reach:
177
+ * door handles, buttons, levers) and the interaction gaze point (ik.lookAt). Continuous per-tick data
178
+ * like position/aim, ridden in on the `state` upload (omitted field = inactive). Replicas feed the points
179
+ * into their OWN local solvers — no bone transforms ever cross the wire. When an `*Active` flag is false
180
+ * the paired vector just holds its last value (unwritten fields delta-encode to ~0 bytes) — always check
181
+ * the flag first. False/zero when the room predates v21.
182
+ */
183
+ reachLeftActive: boolean;
184
+ /** Left-hand reach target, world METERS. Meaningful only while reachLeftActive. */
185
+ reachLeft: Vec3;
186
+ reachRightActive: boolean;
187
+ /** Right-hand reach target, world METERS. Meaningful only while reachRightActive. */
188
+ reachRight: Vec3;
189
+ lookTargetActive: boolean;
190
+ /** Interaction gaze point, world METERS (beats replicated aim-follow gaze). Meaningful only while lookTargetActive. */
191
+ lookTarget: Vec3;
192
+ /**
193
+ * Gun state (v24) — weapon SIGNALS, not motion: replicas re-run the same local easing/FX off these fields.
194
+ * Absent when the sender carries no gun-control ability (or the room predates v24).
195
+ *
196
+ * `shotSeq` is a monotonic per-session shot counter, +1 per real shot. It is coalesced latest-wins at
197
+ * 10/20 Hz, so consumers react to the DELTA (never assume +1); it restarts at 0 on reconnect, and a
198
+ * non-positive delta means re-anchor (never replay).
199
+ */
200
+ shotSeq?: number;
201
+ /** Weapon drawn (vs holstered). */
202
+ gunDrawn?: boolean;
203
+ /** ADS intent, not an aim fraction — replicas ease locally with the same time constant. */
204
+ aiming?: boolean;
205
+ /** Reload in progress (wire-timed on replicas). */
206
+ reloading?: boolean;
207
+ /**
208
+ * The emote set this player CARRIES (v28) — resolved SERVER-SIDE from their equipped items at join and on the
209
+ * `emoteRefresh` hint, exactly like `avatarUrl` (v17): a client can never name the clip URLs that land on its
210
+ * own seat, so this is NOT the client-written `attachments` lane despite the matching array shape. Emotes are
211
+ * persistent → they sync as STATE, so a late joiner converges at replica spawn. Bounded by
212
+ * EMOTE_LIMITS.maxEntries; absent/[] when the player carries none, the world disabled emotes, or the room
213
+ * predates v28.
214
+ */
215
+ emotes?: EmoteEntry[];
216
+ /**
217
+ * The locomotion clip set this player MOVES on (v34), as ONE servable pack-manifest base URL — resolved
218
+ * SERVER-SIDE from their equipped locomotion pack at join and on the `avatarRefresh` hint, exactly like
219
+ * `avatarUrl` (v17): a client can never name the pack that lands on its own seat. A pack is persistent → it
220
+ * syncs as STATE, so a late joiner sees the right walk at replica spawn instead of a corrected one. '' or
221
+ * absent = the platform locomotion set, which is also what a room predating v34 replicates.
222
+ */
223
+ locomotionPack?: string;
224
+ /**
225
+ * PAIRED emotes (v28) — the pair this player JOINED, and never the one they offer: the initiator's own seat
226
+ * carries nothing (their offering is derivable — their `loopGesture` is `emote.<slot>` and that slot's entry
227
+ * has `roles`). ROOM-WRITTEN ONLY, like `avatarUrl`/`emotes` and unlike every other field here: the `emoteJoin`
228
+ * message is a request the room validates (liveness, range, the initiator actually offering and not already
229
+ * paired — a pair is strictly 1:1) and answers by writing — or by writing nothing — so a client can never seat
230
+ * itself in someone else's emote. The room also owns every clear (the initiator
231
+ * stops/changes/teleports/leaves/dies, the joiner dies or drifts away).
232
+ *
233
+ * '' = not paired; otherwise the INITIATOR's player id (the `players` map key, the id-space `activeAbilities`
234
+ * and every other ref use).
235
+ */
236
+ pairInitiator: string;
237
+ /** The initiator's slot being joined ('r0'..'r7'), so replicas read the roles off the right entry. '' = none. */
238
+ pairSlot: string;
239
+ /** Room clock (epoch ms, the `{op:now}` source) at pair creation, so replicas can phase-align. 0 = none. */
240
+ pairStartMs: number;
61
241
  }
@@ -1 +1 @@
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"}
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;AAQxE,0GAA0G;AAC1G,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,QAAQ,EAAE,QAAQ;IAClB,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,SAAS;CACT,CAAC"}
@@ -0,0 +1,32 @@
1
+ import { type FinalRestScope, FINAL_REST_REPLY, type FinalRestGrant, type FinalRestReply, type GroupRestSnapshotMessage, type RoomVarValue, type EntityStateBatchEntry } from './multiplayer-contract/index.js';
2
+ /** Room-scoped client state. Retries resend frozen bytes, never resample a settled body. */
3
+ export declare class FinalRestClient {
4
+ private readonly send;
5
+ private readonly nextSequence;
6
+ private request;
7
+ private readonly claiming;
8
+ private supported;
9
+ private moduleSupported;
10
+ private generations;
11
+ private lifecycle;
12
+ private readonly retiredGenerations;
13
+ private readonly snapshotGenerations;
14
+ private readonly moduleLifecycles;
15
+ private dead;
16
+ private readonly transactions;
17
+ private readonly revoked;
18
+ private readonly pending;
19
+ constructor(send: (type: string, payload: unknown) => void, nextSequence: () => number);
20
+ capability(payload: unknown): void;
21
+ receive(reply: FinalRestReply): void;
22
+ drop(): void;
23
+ reconnect(): void;
24
+ acceptSnapshot(snapshot: GroupRestSnapshotMessage): boolean;
25
+ invalidateModule(moduleId: string): void;
26
+ /** null means fenced; undefined is the unchanged legacy path. */
27
+ upload(id: string, moduleId?: string): string | null | undefined;
28
+ private rpc;
29
+ claim(action: string, group: string, args?: Record<string, RoomVarValue>, address?: FinalRestScope, engagementEpoch?: number): Promise<FinalRestGrant>;
30
+ commit(transactionId: string, states: readonly EntityStateBatchEntry[]): Promise<GroupRestSnapshotMessage>;
31
+ }
32
+ export { FINAL_REST_REPLY };