@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,237 @@
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';
10
+ export const ClientMessageType = {
11
+ /** The player's predicted kinematic state for this tick (seq-tagged for reconciliation). */
12
+ State: 'state',
13
+ /** Activate or deactivate an ability on this player (the built-in, engine-level intent). */
14
+ Ability: 'ability',
15
+ /** A world-authored declared action (the generic extensibility channel — see ActionMessage). */
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',
29
+ /** An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c — see EntityStateMessage). */
30
+ EntityState: 'entityState',
31
+ /**
32
+ * A BATCH of owner-authoritative entity uploads for this tick — ALL the entities this connection hosts in one
33
+ * message (Tier 2 Phase 4.10 — see EntityStateBatchMessage). The per-connection rate cap counts MESSAGES, so a
34
+ * host of N entities must batch (one message/tick) instead of N single EntityState messages, or it starves its
35
+ * own upload budget. EntityScene uses this; the single EntityState stays for one-off uploads (e.g. a flag).
36
+ */
37
+ EntityStateBatch: 'entityStateBatch',
38
+ /** Clock-sync probe: the client's local timestamp, which the room echoes in a Pong (RTT + offset). */
39
+ Ping: 'ping',
40
+ };
41
+ /** Server → client messages (the room sends these; SDK exposes them via room.onMessage(type, cb)). */
42
+ export const ServerMessageType = {
43
+ /** Reply to a Ping: the client's echoed timestamp + the server's current time, for offset estimation. */
44
+ Pong: 'pong',
45
+ /**
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.
52
+ */
53
+ StateAck: 'stateAck',
54
+ /**
55
+ * A2 reconnection ack — the owner-hosted entity divergence correction (spec §9). Sent ONLY to the hosting client,
56
+ * BATCHED (one message per tick acks every hosted entity whose upload the gate rejected — mirrors EntityStateBatch).
57
+ * The host re-anchors each entity's local sim to the anchored position so its uploads stop being fenced. See
58
+ * EntityStateAckMessage.
59
+ */
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,
164
+ };
165
+ /**
166
+ * Wire message-type names a world's declared event/action names MUST NOT shadow — the fixed client→server
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.
171
+ */
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'];
173
+ /**
174
+ * Per-connection rate ceilings (messages/second) the room enforces; over-rate clients are dropped.
175
+ * State is the throttled input channel (plan D3); ability is bursty but bounded.
176
+ *
177
+ * `stateHz`/`entityStateHz` are the DEFAULT per-connection upload cadence. A world may raise BOTH to `maxUploadHz`
178
+ * via `multiplayer.uploadHz: 20` — the room derives the actual ceiling from the trusted configUrl, the client from
179
+ * its bundled manifest, so they agree without a handshake (a client that lies is simply rate-limited). Sending under
180
+ * the cap is always legal, so this is purely a cap → no CONTRACT_VERSION bump.
181
+ * SYNC: the {10, 20} tier set mirrors the manifest's MULTIPLAYER_CAPS.uploadHzAllowed — widen in lockstep.
182
+ */
183
+ export const MESSAGE_RATE = {
184
+ stateHz: 10,
185
+ abilityHz: 20,
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)
193
+ entityStateHz: 10, // owner-entity upload — same cadence as the player state channel (one bucket per connection)
194
+ pingHz: 4, // clock-sync probe — a few per second is ample to track offset/RTT
195
+ maxUploadHz: 20, // ceiling a world may raise stateHz/entityStateHz to (multiplayer.uploadHz:20); = SIM_HZ, above it buys nothing
196
+ };
197
+ /**
198
+ * Movement-plausibility gate — the canonical home for the bound the colyseus room ENFORCES and the engine's
199
+ * client-side upload clamp MIRRORS, so both compute the SAME bound from the SAME inputs and never disagree. A
200
+ * frame moving more than `maxSpeed × Δt × toleranceMul` from the last accepted position is implausible: the
201
+ * server holds + acks it, the client pre-clamps its upload to stay inside it. `Δt` is the SANITIZED real
202
+ * send-interval (the source-time `posT` delta — clamped, spoof-bounded; see nextSourceTime), NOT integer ticks —
203
+ * time-based so the gate is cadence-agnostic and a non-tick-aligned send rate can't quantize the budget away.
204
+ * This is a SANITY bound (anti-teleport), not cheat-proof movement (Tier 3). The room imports this; the
205
+ * standalone engine mirrors the two values (it takes no SDK build dep — same SYNC pattern as the declared-state
206
+ * mirror) → keep them in lockstep.
207
+ */
208
+ export const MOVEMENT_GATE = {
209
+ toleranceMul: 1.25, // accepted displacement = maxSpeed × Δt × this; the small clock-skew margin that replaces the old client 0.83 / server 2.0 tick-quantization fudge
210
+ // A client-HOSTED owner-authority ENTITY (a rolling ball, a car, any owner-hosted body — physics OR kinematic
211
+ // transport) can live AT maxSpeed continuously, so the player tolerance (1.25×) leaves it riding the exact gate
212
+ // edge — cadence/clock jitter then false-rejects legitimate motion and the client pre-clamp crawls the auth behind
213
+ // the sim (the fence → reanchor "slingshot" + remote extrapolation chop). Owner-entity uploads get a wider
214
+ // STEADY-STATE budget: enough to clear maxSpeed motion + the render-delay lag + the cadence quantum, while still
215
+ // catching a real teleport (a sanity bound, not Tier-3 anti-cheat). Used by the server entity gate AND the engine
216
+ // #clampToGate for ALL owner-hosted entity uploads. (Players keep `toleranceMul`; their gate is MAX_SPEED_MPS.)
217
+ ownerEntityToleranceMul: 3.0,
218
+ maxCatchupMs: 300, // ceiling on the Δt credited since the last ACCEPTED frame, so a long silence can't bank a teleport (was MAX_GATE_CATCHUP_TICKS 6 × 50ms)
219
+ // ── Collision-grace exception (networked-physics, plan Phase 3.3) ──────────────────────────────────────
220
+ // A collision impulse legitimately spikes a physics body's velocity past maxSpeed × Δt for an instant; the plain
221
+ // gate would reject that frame. On a SERVER-DETECTED contact involving an owner physics entity the room stamps a
222
+ // short grace window during which the gate budget is multiplied by `impulseMul`; the engine's #clampToGate mirrors
223
+ // the same widened bound so it never pre-clamps a real collision frame. Bounded by graceMs + only opened by a
224
+ // server-detected contact (a soft anti-cheat spot, documented in tuning.ts — visuals-first, not Tier-3).
225
+ impulseMul: 6, // gate multiplier while a collision-grace window is open on the entity
226
+ graceMs: 250, // grace duration (ms) after a server-detected contact involving an owner physics entity
227
+ };
228
+ /**
229
+ * Hard payload bound the room rejects above (defense against oversized frames), measured on the JSON form (a
230
+ * cheap proxy; the msgpack wire is smaller). Sized (P1.B4) to admit a full EntityStateBatch — MAX_ENTITIES_PER_OWNER
231
+ * (128) entities with modest vars in one message (≈75 JSON bytes/entry) — so the byte cap and the per-owner entity
232
+ * cap don't disagree. MUST stay below the Colyseus transport `maxPayload` (16 KB, helix-colyseus-server src/index.ts)
233
+ * in WIRE terms, so the room's reject fires before the transport drops the frame / closes the socket. A var-heavy
234
+ * batch past this is a CLEAN DROP (the room's guard does not strike on an over-byte payload), never a kick.
235
+ */
236
+ export const MAX_MESSAGE_BYTES = 12288;
237
+ //# sourceMappingURL=messages.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/multiplayer-contract/messages.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,177 @@
1
+ import type { Vec3, Quat } from './state.js';
2
+ import type { PlayerIdentity, PlayerReplicaState } from './state.js';
3
+ /**
4
+ * The runtime value vocabulary for declared custom state. A `ref`-typed var's value is the **id** of a live
5
+ * member (a player's `playerKey` or an entity id) as a string, or `null` when unset/dangling — hence `null`
6
+ * is included. The DECLARATION vocabulary (`VarType`: number/string/boolean/vec3/ref + bounds) lives in
7
+ * `@hypersoniclabs/helix-manifest` (authored config, validated at publish); this is the wire value side.
8
+ */
9
+ export type RoomVarValue = number | string | boolean | Vec3 | null | RoomVarCollection;
10
+ /**
11
+ * Per-player/room/entity COLLECTION values (Tier 2 Phase 4.5.13 + P3 collections, spec §5). A `list` var reads as
12
+ * an ordered array — of a scalar element (`number`/`string`/`boolean`), a **ref** element (an id `string`), or a
13
+ * flat **record** (`{field: scalar}`, P3) — realized server-side as a colyseus ArraySchema; a `counterMap` var
14
+ * reads as a string→number record over its declared keys (a MapSchema<number>). P3 also lets entities hold
15
+ * collections and broadcast payloads carry a collection snapshot. Mutated only via the dedicated effects
16
+ * (append/clear/addCount/removeAt/setField) + read via listLength/listAt/count — never a normal scalar expr/arg.
17
+ */
18
+ export type RoomVarRecord = Record<string, number | string | boolean | Vec3>;
19
+ export type RoomVarCollection = number[] | string[] | boolean[] | RoomVarRecord[] | Record<string, number>;
20
+ /** A declared bag of custom state — names + types are declared per-world; used for both room-level and per-player vars. */
21
+ export type RoomVars = Record<string, RoomVarValue>;
22
+ /** Full authoritative per-player state: the FIXED character contract + identity + DECLARED game vars. */
23
+ export interface PlayerState extends PlayerIdentity, PlayerReplicaState {
24
+ /** Declared per-player game state (e.g. team, health, score). Same vocabulary as roomVars; declared per-world. */
25
+ vars: RoomVars;
26
+ /**
27
+ * Presence (Tier 2 Phase 3, spec §8): `false` while this seat sits in the reconnection grace window after an
28
+ * unexpected drop — the seat (and its refs) persists, but the server excludes it from reductions. The seat is
29
+ * removed (an `onRemove('players')`) only at grace expiry; until then the engine should render the replica idle.
30
+ * This layers on Colyseus's own reconnection — it annotates the seat, it does not drive the reconnect handshake.
31
+ */
32
+ connected: boolean;
33
+ /**
34
+ * Participation (Tier 2 P3-B2 elimination): `false` when this still-connected player has been removed from the
35
+ * ACTIVE set mid-match (eliminated / benched / a spectator). An inactive seat is excluded from the same gameplay
36
+ * reductions + spatial detection a disconnected seat is (forEachPlayer / playerCount / aggregate players /
37
+ * nearestPlayer / zone + contact), but it stays `connected` and keeps rendering, and `broadcast` still reaches it
38
+ * (so it can spectate). The room sets it via the `eliminate`/`revive` effects; defaults `true`. Clients may read it
39
+ * to render spectators (e.g. greyed out). (Distinct from `connected`, which is presence/reconnection-grace.)
40
+ */
41
+ active: boolean;
42
+ /**
43
+ * Source-time stamp (ms) of this seat's current `position` — the SANITIZED sender send-time (`StateMessage.tMs`), or
44
+ * the server's apply-clock when the upload carried none. Clients SPACE interpolation keyframes by `posT` deltas
45
+ * instead of local arrival time, so jitter in DELIVERY (network + 20 Hz-tick aliasing) stops becoming jitter in
46
+ * rendered MOTION. Monotonic per seat; only deltas are meaningful (origin = the sender's arbitrary clock base).
47
+ */
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;
55
+ }
56
+ /**
57
+ * RESERVED (Tier 2): a server-spawned object (pickup, projectile, NPC). Empty in v1 — the shape is
58
+ * reserved so adding server-spawned entities later is additive. Tier 2 gives these author-defined
59
+ * behavior; v1 only freezes the slot in RoomState.
60
+ */
61
+ export interface EntityState {
62
+ id: string;
63
+ /** Author-defined kind (e.g. 'flag', 'pickup'). */
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>;
70
+ position?: Vec3;
71
+ /**
72
+ * Physics state — present ONLY for a `physics` (dynamic-body) kind (networked-physics, plan Phase 0). A kinematic
73
+ * entity carries position only (these stay undefined; @colyseus/schema delta-encodes an unwritten field to ~0 bytes).
74
+ * Synced so a remote client extrapolates with the RIGHT velocities (research §2: without synced velocity, remote
75
+ * extrapolation pops) and reproduces orientation. Units: m/s (linear), rad/s (angular), unit quaternion.
76
+ */
77
+ velocity?: Vec3;
78
+ angularVelocity?: Vec3;
79
+ orientation?: Quat;
80
+ /**
81
+ * Who simulates this entity (Tier 2 Phase 4.6c, spec §9). '' = server-authoritative (deterministic kinematics).
82
+ * A player id (a state.players key) = an owner-authoritative entity that client simulates + uploads (the others
83
+ * render it); a client reads this to know which entities it should be uploading via uploadEntity.
84
+ */
85
+ controller: string;
86
+ /**
87
+ * Monotonic authority epoch (Tier 2 Phase 4.5.12, spec §9), bumped on every controller handoff — host
88
+ * migration AND voluntary ownership transfer. A controller client mirrors this into each EntityStateMessage;
89
+ * the room rejects an upload whose epoch ≠ the current one, fencing a stale authority era (a still-connected
90
+ * prior owner's in-flight frames after ownership moved). 0 at spawn; clients only read it.
91
+ */
92
+ authorityEpoch: number;
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
+ };
102
+ /**
103
+ * Source-time stamp (ms) of this entity's current `position` — the server's apply-clock (owner-entity sender-time is
104
+ * a follow-up; server-authoritative entities self-stamp each tick). Consumers space interpolation by `posT` deltas,
105
+ * not arrival time. Monotonic; deltas only. 0 before first move.
106
+ */
107
+ posT: number;
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
+ }
132
+ /** The authoritative shared state. Always carries all three collections (entities empty until Tier 2). */
133
+ export interface RoomState {
134
+ /** Per-player authoritative state, keyed by player id. Realized as a colyseus MapSchema. */
135
+ players: Record<string, PlayerState>;
136
+ /** Room-level declared game state (scores, timers, objectives). Names/types declared per-world. */
137
+ roomVars: RoomVars;
138
+ /** RESERVED (Tier 2): server-spawned entities. Empty in v1. */
139
+ entities: Record<string, EntityState>;
140
+ /** Authoritative server clock: a monotonic counter advanced once per fixed-rate sim tick. */
141
+ serverTick: number;
142
+ /**
143
+ * Authoritative server wall-clock (epoch ms) sampled at the last tick. Clients align to it (offset via the
144
+ * ping/pong echo, see messages.ts) and interpolate between patches, so timer/phase deadlines expressed
145
+ * against server time agree across clients without a per-tick countdown var.
146
+ */
147
+ serverTimeMs: number;
148
+ /**
149
+ * The current phase of the world's room-scoped state machine (Tier 2 Phase 3, spec §8), or `''` when the
150
+ * world declares no `states`. Authored phase names; changed only by the server's `transitionTo`. A
151
+ * late-joiner reads it off synced state to know whether to spawn in or spectate (the join policy).
152
+ */
153
+ phase: string;
154
+ /**
155
+ * The `serverTick` at which the room entered its current `phase`. With `serverTick`/`serverTimeMs` a client
156
+ * computes time-in-phase locally (e.g. a round countdown) without a per-tick countdown var.
157
+ */
158
+ phaseStartTick: number;
159
+ /**
160
+ * Active timers (Tier 2 Phase 3, spec §8) → absolute deadline as `serverTimeMs` (epoch ms). The map key is
161
+ * the timer name for a room-scoped timer, or `"<timer>|<playerKey>"` for a per-player **keyed** timer (e.g.
162
+ * read your own cooldown at `"cooldown|" + room.sessionId`). A client computes the seconds remaining as
163
+ * `(deadline − estimatedServerTimeMs) / 1000` using its ping/pong offset, so a countdown interpolates locally
164
+ * without a per-tick countdown var. An entry is removed when the timer fires or is cancelled.
165
+ */
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>;
177
+ }
@@ -0,0 +1,17 @@
1
+ // The authoritative room state shape — the FRAMEWORK for what a world syncs. The room holds this as
2
+ // @colyseus/schema (the Record<string, T> maps below are realized as MapSchema); the SDK exposes it as
3
+ // room.state. Two layers, and the distinction is the whole answer to "how does an agent sync more?":
4
+ //
5
+ // • players — FIXED. Each player is the engine's character contract (PlayerReplicaState) + identity.
6
+ // Universal across every world; an agent never changes its fields.
7
+ // • roomVars / per-player vars / entities — DECLARED PER-WORLD. This is where an agent's game state
8
+ // lives (scores, timers, teams, objectives). The agent DECLARES names + types in the
9
+ // world's multiplayer config (loaded by buildId at onCreate); the one generic HelixRoom
10
+ // interprets the declaration — no agent-authored server code (Tier 1).
11
+ //
12
+ // Tier-1 vocabulary is intentionally bounded (primitives + Vec3). Rich/nested custom state and
13
+ // author-defined entity behavior are Tier 2 (a reflection-based dynamic schema + behavior DSL),
14
+ // deferred — the `entities` collection and this declared-bag shape are the reserved seams that keep
15
+ // Tier 2 additive rather than a rewrite.
16
+ export {};
17
+ //# sourceMappingURL=room.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"room.js","sourceRoot":"","sources":["../../src/multiplayer-contract/room.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,uGAAuG;AACvG,qGAAqG;AACrG,EAAE;AACF,wGAAwG;AACxG,kFAAkF;AAClF,sGAAsG;AACtG,oGAAoG;AACpG,uGAAuG;AACvG,sFAAsF;AACtF,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,oGAAoG;AACpG,yCAAyC"}