@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.
- package/README.md +954 -2
- package/dist/action-surface.d.ts +182 -0
- package/dist/action-surface.js +1032 -0
- package/dist/action-surface.js.map +1 -0
- package/dist/camera.d.ts +78 -0
- package/dist/camera.js +640 -0
- package/dist/camera.js.map +1 -0
- package/dist/dev-shell/criteria.d.ts +46 -0
- package/dist/dev-shell/criteria.js +98 -0
- package/dist/dev-shell/criteria.js.map +1 -0
- package/dist/dev-shell/index.d.ts +189 -0
- package/dist/dev-shell/index.js +287 -0
- package/dist/dev-shell/index.js.map +1 -0
- package/dist/dev-shell/keys.d.ts +14 -0
- package/dist/dev-shell/keys.js +78 -0
- package/dist/dev-shell/keys.js.map +1 -0
- package/dist/dev-shell/simulator.d.ts +436 -0
- package/dist/dev-shell/simulator.js +1634 -0
- package/dist/dev-shell/simulator.js.map +1 -0
- package/dist/dev-shell/state.d.ts +148 -0
- package/dist/dev-shell/state.js +196 -0
- package/dist/dev-shell/state.js.map +1 -0
- package/dist/device-definition-resolver.d.ts +34 -0
- package/dist/device-definition-resolver.js +172 -0
- package/dist/device-definition-resolver.js.map +1 -0
- package/dist/device-trial.d.ts +3 -0
- package/dist/device-trial.js +132 -0
- package/dist/device-trial.js.map +1 -0
- package/dist/devices.d.ts +228 -0
- package/dist/devices.js +198 -0
- package/dist/devices.js.map +1 -0
- package/dist/dreamerAudio.d.ts +126 -0
- package/dist/dreamerAudio.js +135 -0
- package/dist/dreamerAudio.js.map +1 -0
- package/dist/generated/runtime-contract.d.ts +15529 -0
- package/dist/generated/runtime-contract.js +20470 -0
- package/dist/generated/runtime-contract.js.map +1 -0
- package/dist/index.d.ts +364 -3
- package/dist/index.js +1954 -13
- package/dist/index.js.map +1 -1
- package/dist/interaction-mode.d.ts +172 -0
- package/dist/interaction-mode.js +553 -0
- package/dist/interaction-mode.js.map +1 -0
- package/dist/internal/avatar-pose.d.ts +25 -0
- package/dist/internal/avatar-pose.js +46 -0
- package/dist/internal/avatar-pose.js.map +1 -0
- package/dist/internal/keyed-collection.d.ts +2 -0
- package/dist/internal/keyed-collection.js +12 -0
- package/dist/internal/keyed-collection.js.map +1 -0
- package/dist/internal/vehicle-detach-action.d.ts +2 -0
- package/dist/internal/vehicle-detach-action.js +6 -0
- package/dist/internal/vehicle-detach-action.js.map +1 -0
- package/dist/matchmaking.d.ts +433 -0
- package/dist/matchmaking.js +1487 -0
- package/dist/matchmaking.js.map +1 -0
- package/dist/materials.d.ts +122 -0
- package/dist/materials.js +217 -0
- package/dist/materials.js.map +1 -0
- package/dist/multiplayer-accessors.d.ts +100 -0
- package/dist/multiplayer-accessors.js +200 -0
- package/dist/multiplayer-accessors.js.map +1 -0
- package/dist/multiplayer-contract/avatar-pose.d.ts +112 -0
- package/dist/multiplayer-contract/avatar-pose.js +250 -0
- package/dist/multiplayer-contract/avatar-pose.js.map +1 -0
- package/dist/multiplayer-contract/credential.d.ts +80 -0
- package/dist/multiplayer-contract/credential.js +5 -0
- package/dist/multiplayer-contract/credential.js.map +1 -0
- package/dist/multiplayer-contract/final-rest.d.ts +66 -0
- package/dist/multiplayer-contract/final-rest.js +38 -0
- package/dist/multiplayer-contract/final-rest.js.map +1 -0
- package/dist/multiplayer-contract/index.d.ts +20 -0
- package/dist/multiplayer-contract/index.js +41 -0
- package/dist/multiplayer-contract/index.js.map +1 -0
- package/dist/multiplayer-contract/messages.d.ts +731 -0
- package/dist/multiplayer-contract/messages.js +237 -0
- package/dist/multiplayer-contract/messages.js.map +1 -0
- package/dist/multiplayer-contract/room.d.ts +177 -0
- package/dist/multiplayer-contract/room.js +17 -0
- package/dist/multiplayer-contract/room.js.map +1 -0
- package/dist/multiplayer-contract/state.d.ts +241 -0
- package/dist/multiplayer-contract/state.js +15 -0
- package/dist/multiplayer-contract/state.js.map +1 -0
- package/dist/multiplayer-final-rest.d.ts +32 -0
- package/dist/multiplayer-final-rest.js +217 -0
- package/dist/multiplayer-final-rest.js.map +1 -0
- package/dist/multiplayer.d.ts +624 -0
- package/dist/multiplayer.js +2503 -0
- package/dist/multiplayer.js.map +1 -0
- package/dist/package.json +3 -0
- package/dist/protocol.d.ts +859 -1
- package/dist/protocol.js +117 -5
- package/dist/protocol.js.map +1 -1
- package/dist/runtime-contract/index.d.ts +15 -0
- package/dist/runtime-contract/index.js +12 -0
- package/dist/runtime-contract/index.js.map +1 -0
- package/dist/server-clock.d.ts +25 -0
- package/dist/server-clock.js +88 -0
- package/dist/server-clock.js.map +1 -0
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/dist/universal-vehicles.d.ts +111 -0
- package/dist/universal-vehicles.js +2 -0
- package/dist/universal-vehicles.js.map +1 -0
- package/dist/vault.d.ts +562 -0
- package/dist/vault.js +365 -0
- package/dist/vault.js.map +1 -0
- package/dist/vehicle-specialty-placement.d.ts +28 -0
- package/dist/vehicle-specialty-placement.js +154 -0
- package/dist/vehicle-specialty-placement.js.map +1 -0
- package/dist/vehicle-specialty-transport.d.ts +78 -0
- package/dist/vehicle-specialty-transport.js +183 -0
- package/dist/vehicle-specialty-transport.js.map +1 -0
- package/dist/voice.d.ts +229 -0
- package/dist/voice.js +1348 -0
- package/dist/voice.js.map +1 -0
- package/generated/runtime-contract/helix-runtime-contract.json +13332 -0
- package/generated/runtime-contract/known-answer.json +20471 -0
- package/generated/runtime-contract/known-answer.schema.json +630 -0
- package/generated/runtime-contract/runtime-contract.schema.json +607 -0
- package/generated/runtime-contract/unreal/HelixRuntimeContract.generated.h +908 -0
- package/package.json +44 -5
|
@@ -0,0 +1,731 @@
|
|
|
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
|
+
};
|
|
27
|
+
export declare const ClientMessageType: {
|
|
28
|
+
/** The player's predicted kinematic state for this tick (seq-tagged for reconciliation). */
|
|
29
|
+
readonly State: "state";
|
|
30
|
+
/** Activate or deactivate an ability on this player (the built-in, engine-level intent). */
|
|
31
|
+
readonly Ability: "ability";
|
|
32
|
+
/** A world-authored declared action (the generic extensibility channel — see ActionMessage). */
|
|
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";
|
|
46
|
+
/** An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c — see EntityStateMessage). */
|
|
47
|
+
readonly EntityState: "entityState";
|
|
48
|
+
/**
|
|
49
|
+
* A BATCH of owner-authoritative entity uploads for this tick — ALL the entities this connection hosts in one
|
|
50
|
+
* message (Tier 2 Phase 4.10 — see EntityStateBatchMessage). The per-connection rate cap counts MESSAGES, so a
|
|
51
|
+
* host of N entities must batch (one message/tick) instead of N single EntityState messages, or it starves its
|
|
52
|
+
* own upload budget. EntityScene uses this; the single EntityState stays for one-off uploads (e.g. a flag).
|
|
53
|
+
*/
|
|
54
|
+
readonly EntityStateBatch: "entityStateBatch";
|
|
55
|
+
/** Clock-sync probe: the client's local timestamp, which the room echoes in a Pong (RTT + offset). */
|
|
56
|
+
readonly Ping: "ping";
|
|
57
|
+
};
|
|
58
|
+
export type ClientMessageType = (typeof ClientMessageType)[keyof typeof ClientMessageType];
|
|
59
|
+
/** Server → client messages (the room sends these; SDK exposes them via room.onMessage(type, cb)). */
|
|
60
|
+
export declare const ServerMessageType: {
|
|
61
|
+
/** Reply to a Ping: the client's echoed timestamp + the server's current time, for offset estimation. */
|
|
62
|
+
readonly Pong: "pong";
|
|
63
|
+
/**
|
|
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.
|
|
70
|
+
*/
|
|
71
|
+
readonly StateAck: "stateAck";
|
|
72
|
+
/**
|
|
73
|
+
* A2 reconnection ack — the owner-hosted entity divergence correction (spec §9). Sent ONLY to the hosting client,
|
|
74
|
+
* BATCHED (one message per tick acks every hosted entity whose upload the gate rejected — mirrors EntityStateBatch).
|
|
75
|
+
* The host re-anchors each entity's local sim to the anchored position so its uploads stop being fenced. See
|
|
76
|
+
* EntityStateAckMessage.
|
|
77
|
+
*/
|
|
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";
|
|
110
|
+
};
|
|
111
|
+
export type ServerMessageType = (typeof ServerMessageType)[keyof typeof ServerMessageType];
|
|
112
|
+
/** Per-tick state upload. Units match PlayerReplicaState (position m; all angles degrees, see *Deg). */
|
|
113
|
+
export interface StateMessage {
|
|
114
|
+
/** Monotonic per-client sequence; the room echoes the last applied seq for client reconciliation. */
|
|
115
|
+
seq: number;
|
|
116
|
+
position: Vec3;
|
|
117
|
+
facingYawDeg: number;
|
|
118
|
+
speed: number;
|
|
119
|
+
moveDirectionDeg: number;
|
|
120
|
+
verticalVelocity: number;
|
|
121
|
+
grounded: boolean;
|
|
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;
|
|
131
|
+
aimYawDeg: number;
|
|
132
|
+
aimPitchDeg: number;
|
|
133
|
+
/**
|
|
134
|
+
* Sender send-time — the client's monotonic `performance.now()` ms when it sampled this frame. The server
|
|
135
|
+
* SANITIZES it into the synced `PlayerState.posT` (room.ts) for source-time interpolation: clients space keyframes
|
|
136
|
+
* by `posT` deltas, not arrival time, so delivery jitter stops becoming motion jitter. Only deltas matter (the
|
|
137
|
+
* origin is arbitrary). Optional — an older client omits it and the server falls back to its own apply-clock.
|
|
138
|
+
*/
|
|
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;
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c, spec §9/§10.4). The
|
|
176
|
+
* client that the server marked as the entity's `controller` (see EntityState.controller) simulates the entity
|
|
177
|
+
* and uploads its transform + declared vars; the room sanity-validates (it owns this entity? movement within
|
|
178
|
+
* its declared `maxSpeed`? vars within their declared bounds?) and relays. Cross-player consequences still go
|
|
179
|
+
* through server-validated rules/actions — never this channel (the publish-time firewall enforces that).
|
|
180
|
+
*/
|
|
181
|
+
export interface EntityStateMessage {
|
|
182
|
+
transactionId?: string;
|
|
183
|
+
/** Optional module provenance; when present, `entity` is local to this module instance. */
|
|
184
|
+
moduleId?: string;
|
|
185
|
+
/** The entity id this upload is for (the state.entities map key). Rejected unless the sender is its controller. */
|
|
186
|
+
entity: string;
|
|
187
|
+
/** Monotonic per-entity sequence; the room ignores a stale/out-of-order frame. */
|
|
188
|
+
seq: number;
|
|
189
|
+
/** The entity's world position, METERS — gated against the kind's declared maxSpeed. */
|
|
190
|
+
position: Vec3;
|
|
191
|
+
/**
|
|
192
|
+
* Physics state — uploaded ONLY for a `physics` (dynamic-body) kind (networked-physics, plan Phase 0). `velocity`
|
|
193
|
+
* is gated against the kind's maxSpeed (magnitude-clamped on ingest, widened during a collision-grace window);
|
|
194
|
+
* `orientation` is normalized (zero/non-finite → identity). Synced so remotes extrapolate with the right velocity
|
|
195
|
+
* + reproduce spin (research §2). Omit for a kinematic kind.
|
|
196
|
+
*/
|
|
197
|
+
velocity?: Vec3;
|
|
198
|
+
angularVelocity?: Vec3;
|
|
199
|
+
orientation?: Quat;
|
|
200
|
+
/** Declared per-kind vars to set (same vocabulary as roomVars); each is clamped to its declared type/bounds on ingest. */
|
|
201
|
+
vars?: Record<string, RoomVarValue>;
|
|
202
|
+
/**
|
|
203
|
+
* The authority EPOCH the client is simulating under (Tier 2 Phase 4.5.12, spec §9). Mirror the entity's synced
|
|
204
|
+
* `authorityEpoch`; the room bumps it on every controller handoff (host migration AND voluntary ownership
|
|
205
|
+
* transfer) and rejects an upload whose epoch ≠ the entity's current one — fencing a revoked/stale authority
|
|
206
|
+
* era even from a still-connected prior owner whose sessionId would otherwise pass. Omit only for the very
|
|
207
|
+
* first frame before the field is observed; the room tolerates absence (sessionId ownership still gates).
|
|
208
|
+
*/
|
|
209
|
+
epoch?: number;
|
|
210
|
+
/**
|
|
211
|
+
* Sender send-time (the owner's monotonic `performance.now()` ms at upload) — the server SANITIZES it into the
|
|
212
|
+
* entity's synced `posT` for source-time interpolation, exactly like the player's `StateMessage.tMs`. Optional.
|
|
213
|
+
*/
|
|
214
|
+
tMs?: number;
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* One entity's slot in an EntityStateBatchMessage. Compact, short keys (sent verbatim in msgpack), with position
|
|
218
|
+
* as a 3-tuple instead of a {x,y,z} object — the same authoritative meaning as EntityStateMessage's per-entity
|
|
219
|
+
* fields. `v`/`ep` are omitted when unchanged/unobserved to keep the batch small.
|
|
220
|
+
*/
|
|
221
|
+
export interface EntityStateBatchEntry {
|
|
222
|
+
transactionId?: string;
|
|
223
|
+
/** Entity id (the state.entities map key). Rejected unless the sender is its controller. */
|
|
224
|
+
e: string;
|
|
225
|
+
/** World position as [x, y, z], METERS — gated against the kind's declared maxSpeed. */
|
|
226
|
+
p: [number, number, number];
|
|
227
|
+
/** Linear velocity [x,y,z], m/s — physics kinds only; magnitude-clamped to the gate on ingest. Omit when unchanged/non-physics. */
|
|
228
|
+
lv?: [number, number, number];
|
|
229
|
+
/** Angular velocity [x,y,z], rad/s — physics kinds only. Omit when unchanged/non-physics. */
|
|
230
|
+
av?: [number, number, number];
|
|
231
|
+
/** Orientation quaternion [x,y,z,w] — physics kinds only; normalized (zero/non-finite → identity) on ingest. Omit when unchanged/non-physics. */
|
|
232
|
+
q?: [number, number, number, number];
|
|
233
|
+
/** Declared per-kind vars to set (clamped to declared type/bounds on ingest). Omit when unchanged this tick. */
|
|
234
|
+
v?: Record<string, RoomVarValue>;
|
|
235
|
+
/** Authority epoch this entity is simulated under (mirror its synced authorityEpoch). Omit before observed. */
|
|
236
|
+
ep?: number;
|
|
237
|
+
}
|
|
238
|
+
/**
|
|
239
|
+
* A batch of owner-authoritative entity uploads (Tier 2 Phase 4.10, spec §10.4) — every entity this connection
|
|
240
|
+
* hosts, in ONE message. The per-connection rate cap (MESSAGE_RATE.entityStateHz) counts messages, so batching
|
|
241
|
+
* lets a host refresh many entities per tick within one token instead of spending one token per entity. The room
|
|
242
|
+
* applies each entry exactly like a single EntityStateMessage (ownership + epoch + maxSpeed gate + var clamp).
|
|
243
|
+
*/
|
|
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;
|
|
254
|
+
/** Monotonic per-connection batch sequence; the room ignores a stale/out-of-order batch per entity (gate seq). */
|
|
255
|
+
seq: number;
|
|
256
|
+
/** One entry per hosted entity changed this tick (bounded by the room's per-owner entity cap). */
|
|
257
|
+
states: EntityStateBatchEntry[];
|
|
258
|
+
/**
|
|
259
|
+
* Sender send-time (the host's monotonic `performance.now()` ms when it sampled this batch) — ONE per batch (all
|
|
260
|
+
* entries are sampled the same frame); the server sanitizes it into each entity's synced `posT`. Optional.
|
|
261
|
+
*/
|
|
262
|
+
tMs?: number;
|
|
263
|
+
}
|
|
264
|
+
/** Discrete ability activation intent. */
|
|
265
|
+
export interface AbilityMessage {
|
|
266
|
+
/** Ability id (must be one the world's build declares). */
|
|
267
|
+
ability: string;
|
|
268
|
+
/** true = activate, false = deactivate. */
|
|
269
|
+
active: boolean;
|
|
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
|
+
}
|
|
305
|
+
/**
|
|
306
|
+
* A world-authored declared action — the generic extensibility channel (e.g. 'captureFlag',
|
|
307
|
+
* 'scorePoint'). The room validates `name` against the world's declared action set and `args` against
|
|
308
|
+
* that action's declared arg schema before mutating authoritative state (table-driven dispatch); this
|
|
309
|
+
* module carries the envelope + arg vocabulary only, never the per-world rules.
|
|
310
|
+
*/
|
|
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;
|
|
336
|
+
/** Action name; must be one the world's build declares. */
|
|
337
|
+
name: string;
|
|
338
|
+
/** Primitive/Vec3 args, validated against the declared action's schema by the room. */
|
|
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;
|
|
487
|
+
}
|
|
488
|
+
/**
|
|
489
|
+
* Clock-sync probe. The client sends its local send time; the room replies (Pong) with this value echoed
|
|
490
|
+
* plus its own clock, so the client estimates RTT (recv − send) and offset (serverTimeMs − send − RTT/2).
|
|
491
|
+
*/
|
|
492
|
+
export interface PingMessage {
|
|
493
|
+
/** The client's local clock (epoch ms) at send — echoed verbatim in the Pong. */
|
|
494
|
+
clientTimeMs: number;
|
|
495
|
+
}
|
|
496
|
+
/** Reply to a Ping — the echoed client time + the server's clock at reply, for offset/RTT estimation. */
|
|
497
|
+
export interface PongMessage {
|
|
498
|
+
finalRestVersion?: 1;
|
|
499
|
+
moduleFinalRestVersion?: 1;
|
|
500
|
+
finalRestModules?: Record<string, number>;
|
|
501
|
+
clientTimeMs: number;
|
|
502
|
+
serverTimeMs: number;
|
|
503
|
+
}
|
|
504
|
+
/**
|
|
505
|
+
* A2 player-seat divergence ack (spec §9). Sent to ONE client when the room's movement gate rejected its `state`
|
|
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.
|
|
510
|
+
*/
|
|
511
|
+
export interface StateAckMessage {
|
|
512
|
+
/** The highest client `seq` the room has processed for this seat — the client prunes its reconciliation buffer through it. */
|
|
513
|
+
seq: number;
|
|
514
|
+
/** The room's authoritative position for this seat (the last ACCEPTED upload, or the teleport target) — the anchor the client snaps to. */
|
|
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;
|
|
522
|
+
}
|
|
523
|
+
/**
|
|
524
|
+
* One entity's slot in an EntityStateAckMessage — compact short keys + a [x,y,z] tuple, mirroring EntityStateBatchEntry
|
|
525
|
+
* (the upload it answers).
|
|
526
|
+
*/
|
|
527
|
+
export interface EntityStateAckEntry {
|
|
528
|
+
/** Entity id (the state.entities map key). */
|
|
529
|
+
e: string;
|
|
530
|
+
/** The last per-entity `seq` the room ACCEPTED for this entity — the host re-anchors/prunes through it. */
|
|
531
|
+
seq: number;
|
|
532
|
+
/** The room's authoritative anchored position [x, y, z], METERS — the host snaps its local sim to it. */
|
|
533
|
+
p: [number, number, number];
|
|
534
|
+
/** Anchored linear velocity [x,y,z], m/s — physics kinds only, so a reconciled body resets its velocity too (else a stale spin/drift survives). Omit for non-physics. */
|
|
535
|
+
lv?: [number, number, number];
|
|
536
|
+
/** Anchored orientation quaternion [x,y,z,w] — physics kinds only, so a reconciled body resets its spin. Omit for non-physics. */
|
|
537
|
+
q?: [number, number, number, number];
|
|
538
|
+
}
|
|
539
|
+
/**
|
|
540
|
+
* A2 owner-entity divergence ack (spec §9). Sent to ONE hosting client, BATCHED: one message per tick carries an entry
|
|
541
|
+
* for every entity this host uploaded whose position the gate rejected (mirrors the EntityStateBatch upload channel).
|
|
542
|
+
* The host re-anchors each entity's local sim to its anchor, so a sparse/throttled host stops being fenced by the gate
|
|
543
|
+
* — replacing the engine's prior conservative `0.83 × gate-reach` guess with the room's actual accepted position.
|
|
544
|
+
*/
|
|
545
|
+
export interface EntityStateAckMessage {
|
|
546
|
+
/** Module provenance for every local entity id in `acks`; absent means world entities. */
|
|
547
|
+
moduleId?: string;
|
|
548
|
+
/** One entry per hosted entity whose upload the gate rejected this tick. Never empty (the room omits the message instead). */
|
|
549
|
+
acks: EntityStateAckEntry[];
|
|
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
|
+
}
|
|
635
|
+
/**
|
|
636
|
+
* A server→client broadcast event (Tier 2 Phase 2.5, spec §10.3). A world declares named events with a
|
|
637
|
+
* payload schema; a `broadcast` rule-effect sends one on the event's NAME (not a fixed ServerMessageType),
|
|
638
|
+
* received via `room.onMessage(name, cb)`. Payload values are the declared fields; a `ref` field serializes
|
|
639
|
+
* to its `playerKey` string on the wire (so `who:"self"` and `who:{aggregate argmax}` are the same type).
|
|
640
|
+
*/
|
|
641
|
+
export type BroadcastPayload = Record<string, RoomVarValue>;
|
|
642
|
+
/**
|
|
643
|
+
* Wire message-type names a world's declared event/action names MUST NOT shadow — the fixed client→server
|
|
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.
|
|
648
|
+
*/
|
|
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"];
|
|
650
|
+
/** Maps each client→server message type to its payload, so senders/handlers stay in lockstep. */
|
|
651
|
+
export interface ClientMessagePayloads {
|
|
652
|
+
[ClientMessageType.State]: StateMessage;
|
|
653
|
+
[ClientMessageType.Ability]: AbilityMessage;
|
|
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;
|
|
661
|
+
[ClientMessageType.EntityState]: EntityStateMessage;
|
|
662
|
+
[ClientMessageType.EntityStateBatch]: EntityStateBatchMessage;
|
|
663
|
+
[ClientMessageType.Ping]: PingMessage;
|
|
664
|
+
}
|
|
665
|
+
/** Maps each server→client message type to its payload. */
|
|
666
|
+
export interface ServerMessagePayloads {
|
|
667
|
+
[ServerMessageType.Pong]: PongMessage;
|
|
668
|
+
[ServerMessageType.StateAck]: StateAckMessage;
|
|
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;
|
|
680
|
+
}
|
|
681
|
+
/**
|
|
682
|
+
* Per-connection rate ceilings (messages/second) the room enforces; over-rate clients are dropped.
|
|
683
|
+
* State is the throttled input channel (plan D3); ability is bursty but bounded.
|
|
684
|
+
*
|
|
685
|
+
* `stateHz`/`entityStateHz` are the DEFAULT per-connection upload cadence. A world may raise BOTH to `maxUploadHz`
|
|
686
|
+
* via `multiplayer.uploadHz: 20` — the room derives the actual ceiling from the trusted configUrl, the client from
|
|
687
|
+
* its bundled manifest, so they agree without a handshake (a client that lies is simply rate-limited). Sending under
|
|
688
|
+
* the cap is always legal, so this is purely a cap → no CONTRACT_VERSION bump.
|
|
689
|
+
* SYNC: the {10, 20} tier set mirrors the manifest's MULTIPLAYER_CAPS.uploadHzAllowed — widen in lockstep.
|
|
690
|
+
*/
|
|
691
|
+
export declare const MESSAGE_RATE: {
|
|
692
|
+
readonly stateHz: 10;
|
|
693
|
+
readonly abilityHz: 20;
|
|
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;
|
|
701
|
+
readonly entityStateHz: 10;
|
|
702
|
+
readonly pingHz: 4;
|
|
703
|
+
readonly maxUploadHz: 20;
|
|
704
|
+
};
|
|
705
|
+
/**
|
|
706
|
+
* Movement-plausibility gate — the canonical home for the bound the colyseus room ENFORCES and the engine's
|
|
707
|
+
* client-side upload clamp MIRRORS, so both compute the SAME bound from the SAME inputs and never disagree. A
|
|
708
|
+
* frame moving more than `maxSpeed × Δt × toleranceMul` from the last accepted position is implausible: the
|
|
709
|
+
* server holds + acks it, the client pre-clamps its upload to stay inside it. `Δt` is the SANITIZED real
|
|
710
|
+
* send-interval (the source-time `posT` delta — clamped, spoof-bounded; see nextSourceTime), NOT integer ticks —
|
|
711
|
+
* time-based so the gate is cadence-agnostic and a non-tick-aligned send rate can't quantize the budget away.
|
|
712
|
+
* This is a SANITY bound (anti-teleport), not cheat-proof movement (Tier 3). The room imports this; the
|
|
713
|
+
* standalone engine mirrors the two values (it takes no SDK build dep — same SYNC pattern as the declared-state
|
|
714
|
+
* mirror) → keep them in lockstep.
|
|
715
|
+
*/
|
|
716
|
+
export declare const MOVEMENT_GATE: {
|
|
717
|
+
readonly toleranceMul: 1.25;
|
|
718
|
+
readonly ownerEntityToleranceMul: 3;
|
|
719
|
+
readonly maxCatchupMs: 300;
|
|
720
|
+
readonly impulseMul: 6;
|
|
721
|
+
readonly graceMs: 250;
|
|
722
|
+
};
|
|
723
|
+
/**
|
|
724
|
+
* Hard payload bound the room rejects above (defense against oversized frames), measured on the JSON form (a
|
|
725
|
+
* cheap proxy; the msgpack wire is smaller). Sized (P1.B4) to admit a full EntityStateBatch — MAX_ENTITIES_PER_OWNER
|
|
726
|
+
* (128) entities with modest vars in one message (≈75 JSON bytes/entry) — so the byte cap and the per-owner entity
|
|
727
|
+
* cap don't disagree. MUST stay below the Colyseus transport `maxPayload` (16 KB, helix-colyseus-server src/index.ts)
|
|
728
|
+
* in WIRE terms, so the room's reject fires before the transport drops the frame / closes the socket. A var-heavy
|
|
729
|
+
* batch past this is a CLEAN DROP (the room's guard does not strike on an over-byte payload), never a kick.
|
|
730
|
+
*/
|
|
731
|
+
export declare const MAX_MESSAGE_BYTES = 12288;
|