@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,4 +1,33 @@
1
+ import type { VehiclePackageArtifact } from './universal-vehicles.js';
2
+ import type { DeviceDefinitionV1 } from './devices.js';
1
3
  export declare const PROTOCOL_VERSION = 2;
4
+ /** Additive, versioned presentation intent carried on `helix:init`. */
5
+ export declare const RUNTIME_FIDELITY_VERSION: 1;
6
+ export declare const RUNTIME_FIDELITY_VISUAL_TIERS: readonly ["auto", "minimal", "low", "medium", "high", "ultra"];
7
+ export declare const RUNTIME_FIDELITY_RENDER_SCALES: readonly ["1.5", "1", "0.77", "0.59"];
8
+ export declare const RUNTIME_PROFILE_QUALITIES: readonly ["minimum", "balanced", "high", "ultra"];
9
+ export type RuntimeFidelityVisualTier = (typeof RUNTIME_FIDELITY_VISUAL_TIERS)[number];
10
+ export type RuntimeFidelityRenderScale = (typeof RUNTIME_FIDELITY_RENDER_SCALES)[number];
11
+ export type RuntimeProfileQuality = (typeof RUNTIME_PROFILE_QUALITIES)[number];
12
+ /**
13
+ * Player presentation request frozen by the shell for one World load.
14
+ *
15
+ * This intentionally carries no resolved tier, device capability, subsystem
16
+ * budget, physics setting, authority decision, tick rate, or network cadence.
17
+ * The engine resolves Auto and owns those policies.
18
+ */
19
+ export type RuntimeFidelityIntent = {
20
+ version: typeof RUNTIME_FIDELITY_VERSION;
21
+ requestedVisualTier: RuntimeFidelityVisualTier;
22
+ renderScaleOverride: RuntimeFidelityRenderScale | null;
23
+ runtimeProfileQuality: RuntimeProfileQuality | null;
24
+ };
25
+ /**
26
+ * Validate untrusted handshake data and copy it into SDK-owned launch state.
27
+ * Unknown versions, unexpected fields, or invalid members fail closed to null;
28
+ * consumers then use their engine's backward-compatible Auto policy.
29
+ */
30
+ export declare function normalizeRuntimeFidelityIntent(value: unknown): RuntimeFidelityIntent | null;
2
31
  export type HelixUser = {
3
32
  id: string;
4
33
  username: string;
@@ -9,10 +38,137 @@ export type HelixWorldContext = {
9
38
  slug: string;
10
39
  title: string;
11
40
  };
41
+ export type TrialAvatar = {
42
+ source: 'trial';
43
+ inventoryItemId: null;
44
+ itemId: string;
45
+ glbUrl: string;
46
+ contentHash: string | null;
47
+ skeleton: 'helix-humanoid';
48
+ };
49
+ /** Server-sealed, page-scoped package configuration for a local World customizer. */
50
+ export type PackageCustomizerSubject = {
51
+ readonly kind: 'package';
52
+ readonly hostKind: string;
53
+ readonly hostId: string;
54
+ readonly packageId: string;
55
+ readonly version: string;
56
+ readonly renditions: readonly Readonly<{
57
+ id: string;
58
+ url: string;
59
+ }>[];
60
+ readonly board: Readonly<{
61
+ id: string;
62
+ }>;
63
+ /** Slot instance id to page-scoped package choice id; never inventory authority. */
64
+ readonly assignments: Readonly<Record<string, string | null>>;
65
+ readonly hiddenSlotIds?: readonly string[];
66
+ /** Existing shell EquipBoard projection, validated but intentionally not duplicated by the SDK. */
67
+ readonly equipBoard: Readonly<Record<string, unknown>>;
68
+ };
69
+ /** Exact page-scoped vehicle trial identity; never an owned inventory identity. */
70
+ export type PackageCustomizerSource = Readonly<{
71
+ kind: 'trial';
72
+ hostId: string;
73
+ itemId: string;
74
+ }>;
75
+ export interface PackageCustomizerContext {
76
+ readonly source: PackageCustomizerSource | null;
77
+ readonly subject: PackageCustomizerSubject | null;
78
+ }
79
+ /** A universal item temporarily placed in the test grounds for this session. */
80
+ export type WorldSpawnedItem = {
81
+ placementId: string;
82
+ instanceId: string;
83
+ itemId: string;
84
+ worldId: string;
85
+ ownerUserId: string;
86
+ ownerUsername: string | null;
87
+ kind: string | null;
88
+ usage: string | null;
89
+ name: string;
90
+ thumbnailUrl: string | null;
91
+ modelUrl: string | null;
92
+ /** Checksum-bound authored Universal Vehicle package, when this is a vehicle. */
93
+ vehiclePackage: VehiclePackageArtifact | null;
94
+ transform: {
95
+ position: {
96
+ x: number;
97
+ y: number;
98
+ z: number;
99
+ };
100
+ rotationEulerDeg?: {
101
+ x: number;
102
+ y: number;
103
+ z: number;
104
+ };
105
+ scale?: number;
106
+ } | null;
107
+ spawnedAt: string;
108
+ /**
109
+ * THE INSTANCE IS OUT — the platform holds it at `location_type = 'equipped'`, so it is with a
110
+ * player somewhere rather than standing here. A world draws the placement as a faint ghost
111
+ * (0.4 opacity) instead of a solid object, for every viewer and not only its owner.
112
+ *
113
+ * It is a flag on the row rather than an absence from the list because the placement row is never
114
+ * deleted on activate: the bay stays yours while the thing is out, it keeps counting against slot
115
+ * limits, and the world still has to draw something there.
116
+ *
117
+ * OPTIONAL: a shell that predates the field omits it, and `undefined` reads as "not out" — which
118
+ * is exactly the behaviour every published world has today. Read it STRICTLY (`=== true`), the
119
+ * same rule the engine's `WorldSpawnedVehicle.equipped` applies.
120
+ */
121
+ equipped?: boolean;
122
+ /** True for a page-scoped Marketplace trial with no owned inventory instance. */
123
+ trial?: true;
124
+ /** Whether the shell should expose the owned-instance customizer for this row. */
125
+ canCustomize?: boolean;
126
+ /** Server-sealed package subject for a page-scoped trial; absent for ordinary owned rows. */
127
+ customizerSubject?: PackageCustomizerSubject;
128
+ };
129
+ /** One authenticated, session-only Device placement projected by Try Now. */
130
+ export type DeviceTrialSpawn = Readonly<{
131
+ placementId: string;
132
+ itemId: string;
133
+ kind: 'device';
134
+ name: string;
135
+ /** Optimized visual rendition; authored named-node behavior remains bound to definition.model. */
136
+ modelUrl: string | null;
137
+ transform: Readonly<{
138
+ position: readonly [number, number, number];
139
+ yawDeg: number;
140
+ scale: number;
141
+ }>;
142
+ /** Trial expiry as Unix epoch seconds. */
143
+ expiresAt: number;
144
+ deviceDefinition: Readonly<{
145
+ id: string;
146
+ version: string;
147
+ }>;
148
+ definition: DeviceDefinitionV1;
149
+ definitionChecksumSha256: string;
150
+ functionalPin: Readonly<{
151
+ continuumPackageId: string;
152
+ continuumPackageVersion: string;
153
+ continuumManifestCid: string;
154
+ }>;
155
+ /** Exact server-resolved add-on and appearance receipt, validated by the presentation adapter. */
156
+ composition: unknown;
157
+ }>;
158
+ export type HelixTrial = {
159
+ id: string;
160
+ itemId: string;
161
+ kind: 'avatar' | 'vehicle' | 'device';
162
+ /** Trial expiry as Unix epoch seconds. */
163
+ expiresAt: number;
164
+ avatar?: TrialAvatar;
165
+ spawnedItem?: WorldSpawnedItem | DeviceTrialSpawn;
166
+ };
12
167
  export type HelixSession = {
13
168
  token: string;
14
169
  expiresAt: string;
15
170
  scopes: string[];
171
+ trial?: HelixTrial;
16
172
  user: HelixUser;
17
173
  };
18
174
  export type DebugLogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
@@ -26,7 +182,12 @@ export type Balance = {
26
182
  coins: number;
27
183
  updatedAt?: string;
28
184
  };
29
- export type PurchaseStatus = 'Pending' | 'Granted' | 'Claimed' | 'AlreadyOwned' | 'InsufficientFunds' | 'MaxPerUserReached' | 'ProductInactive' | 'ProductNotFound' | 'NotInWorld' | 'Unauthorized' | 'RateLimited' | 'Cancelled' | 'Failed' | 'Timeout' | 'NotFound';
185
+ export type PurchaseStatus = 'Pending' | 'Granted' | 'Claimed' | 'AlreadyOwned' | 'InsufficientFunds' | 'MaxPerUserReached' | 'ProductInactive' | 'ProductNotFound' | 'NotInWorld' | 'Unauthorized' | 'RateLimited' | 'Cancelled' | 'Failed' | 'Timeout' | 'NotFound' | 'PriceChanged';
186
+ export type PurchaseStatusMeaning = {
187
+ money: 'charged' | 'not-charged' | 'unknown';
188
+ ownsAfter: boolean;
189
+ };
190
+ export declare const PURCHASE_STATUS_MEANING: Record<PurchaseStatus, PurchaseStatusMeaning>;
30
191
  export type PurchaseResult = {
31
192
  status: PurchaseStatus;
32
193
  completed: boolean;
@@ -37,8 +198,25 @@ export type PurchaseResult = {
37
198
  balanceLix?: number;
38
199
  shortfallLix?: number;
39
200
  ownedCount?: number;
201
+ maxPerPlayer?: number | null;
40
202
  maxPerUser?: number | null;
203
+ requestedQuantity?: number;
204
+ fulfilledQuantity?: number;
205
+ distributionId?: string | null;
206
+ listingId?: string | null;
207
+ inventoryInstanceIds?: string[];
208
+ serialNumbers?: number[];
209
+ resaleEligibleAt?: string | null;
210
+ receipt?: string;
41
211
  };
212
+ export type PurchaseOptions = {
213
+ /** Whole-number quantity. Collectible listings always require exactly 1. */
214
+ quantity?: number;
215
+ /** Stable caller-owned retry key. Omit to let the SDK persist one safely. */
216
+ idempotencyKey?: string;
217
+ };
218
+ export type ItemEditionMode = 'standard' | 'collectible';
219
+ export type AccountVerificationLevel = 'basic' | 'verified' | 'identity_verified' | 'business_verified';
42
220
  export type InventoryItem = {
43
221
  id?: string;
44
222
  itemId: string;
@@ -55,11 +233,58 @@ export type InventoryItem = {
55
233
  metadata?: Record<string, unknown>;
56
234
  };
57
235
  export type EquippedAvatar = {
58
- source: 'equipped' | 'auto' | 'default';
236
+ source: 'equipped' | 'auto' | 'default' | 'trial';
59
237
  inventoryItemId?: string | null;
60
238
  itemId: string | null;
61
239
  glbUrl: string | null;
240
+ contentHash?: string | null;
62
241
  skeleton: string | null;
242
+ /** Immutable public render recipe for this configured avatar instance. */
243
+ composition?: AvatarComposition | null;
244
+ };
245
+ export type AvatarComposition = {
246
+ compositionDigest: string;
247
+ appearanceDigest: string;
248
+ hostKind: 'character';
249
+ appearance: {
250
+ hiddenSlotIds: string[];
251
+ materialOverrides: Record<string, unknown>;
252
+ colorOverrides: Record<string, unknown>;
253
+ };
254
+ instanceThumbnailUrl: string | null;
255
+ base: {
256
+ itemId: string;
257
+ modelUrl: string | null;
258
+ };
259
+ materials: Record<string, unknown>;
260
+ visibleAddOns: Array<{
261
+ slotId: string;
262
+ itemId: string;
263
+ modelUrl: string | null;
264
+ visualOps: unknown[];
265
+ mountSocket?: string | null;
266
+ fill?: 'all' | 'each';
267
+ }>;
268
+ };
269
+ export type EquippedEmote = {
270
+ /** Wheel position: 'r0'..'r7' are the eight radial slots, 'sit'/'lie' the two posture emotes. */
271
+ slot: 'r0' | 'r1' | 'r2' | 'r3' | 'r4' | 'r5' | 'r6' | 'r7' | 'sit' | 'lie';
272
+ /** The universal-item id this emote came from. */
273
+ itemId: string;
274
+ /** Animation clip URL the world fetches to play it. */
275
+ clip: string;
276
+ playback: 'oneshot' | 'loop';
277
+ /** The emote's sound URL; absent when it is silent. */
278
+ audio?: string;
279
+ /** The item's display title for the wheel's petal; absent when the platform named it nothing. */
280
+ label?: string;
281
+ };
282
+ export type EquippedEmotes = {
283
+ emotes: EquippedEmote[];
284
+ };
285
+ export type EquippedLocomotionPack = {
286
+ /** Servable pack-manifest base URL the seat moves on; '' = the platform locomotion set. */
287
+ pack: string;
63
288
  };
64
289
  export type HelixPresenceActivity = {
65
290
  /** Short activity line (≤128 chars), e.g. "Racing — lap 3/5". Required. */
@@ -109,6 +334,8 @@ export type AvatarLoadoutPatch = {
109
334
  equippedSlots?: Record<string, string | null>;
110
335
  };
111
336
  export type MarketplaceListing = {
337
+ /** Exact secondary listing capability used by purchaseListing(). */
338
+ listingId?: string;
112
339
  itemId: string;
113
340
  title: string;
114
341
  description?: string | null;
@@ -138,6 +365,176 @@ export type SavedPhoto = {
138
365
  worldName: string;
139
366
  createdAt: string;
140
367
  };
368
+ /** Where the camera currently is. `device-hold` is the avatar holding the phone before it is raised. */
369
+ export type CameraSessionState = 'inactive' | 'device-hold' | 'rear' | 'selfie' | 'drone';
370
+ export type CameraMediaMode = 'photo' | 'video';
371
+ /** Where the camera sits in space. Distinct from CameraSessionState, which also carries `inactive`. */
372
+ export type CameraSpatialMode = 'rear' | 'selfie' | 'drone';
373
+ /** Which body the player's look/move input drives while the camera is up. */
374
+ export type CameraControlTarget = 'camera' | 'avatar';
375
+ /**
376
+ * The lens buttons, in the exact order HELIX OS renders them.
377
+ *
378
+ * These are PRESETS, not the zoom domain: effective zoom is CONTINUOUS between
379
+ * the first and last entry, and a preset is only where a tap lands. A runtime
380
+ * that clamps to these five is wrong.
381
+ */
382
+ export declare const CAMERA_LENS_PRESETS: readonly [0.5, 1, 2, 3, 5];
383
+ export type CameraLensPreset = (typeof CAMERA_LENS_PRESETS)[number];
384
+ export type CameraFilterId = 'original' | 'vivid' | 'warm' | 'cool' | 'mono';
385
+ /** Self-timer settings. 0 = no timer (the shutter commits on the press). */
386
+ export type CameraTimerSeconds = 0 | 3 | 10;
387
+ /** Camera aim in degrees, relative to the avatar's facing. */
388
+ export type CameraAim = {
389
+ yaw: number;
390
+ pitch: number;
391
+ };
392
+ /** Tap-to-focus target in normalized viewport coordinates: 0,0 = top-left, 1,1 = bottom-right. */
393
+ export type CameraFocusPoint = {
394
+ x: number;
395
+ y: number;
396
+ };
397
+ /**
398
+ * What THIS runtime can actually do, right now.
399
+ *
400
+ * The runtime contract's `runtimeBindings.*.availability` is a STATIC claim
401
+ * about a method's existence; this is a LIVE one about a running instance, and
402
+ * it is the only thing that can answer "this build has photo but not video" or
403
+ * "the player just revoked the microphone, so world audio is gone". HELIX OS
404
+ * disables the controls this says are false — it must never grey out a control
405
+ * on a guess, and must never present a control whose call it knows will fail.
406
+ *
407
+ * All-false is the correct answer for a runtime that has not reported yet: a
408
+ * capability is claimed, never assumed. `unavailableReason` is a human line the
409
+ * shell may show next to a disabled control ("this world ships photo only").
410
+ */
411
+ export type HelixCameraCapability = {
412
+ photo: boolean;
413
+ video: boolean;
414
+ drone: boolean;
415
+ /** The avatar can hold the device in a two-handed pose (drives `device-hold`). */
416
+ twoHandPose: boolean;
417
+ focusPoint: boolean;
418
+ exposureBias: boolean;
419
+ /** Video can record the world's audio bed, not just a silent picture. */
420
+ worldAudio: boolean;
421
+ unavailableReason?: string;
422
+ };
423
+ /**
424
+ * The shutter as an EDGE, not a pulse.
425
+ *
426
+ * `sequence` is monotonic and increments once per committed capture. A runtime
427
+ * fires on the CHANGE, so a duplicated or replayed helix:camera-state (the shell
428
+ * re-sends its snapshot after the handshake) cannot double-expose — which a
429
+ * boolean `shutterPressed` would do every single time.
430
+ */
431
+ export type HelixCameraShutter = {
432
+ sequence: number;
433
+ /** True while a video recording is actually running. */
434
+ recording: boolean;
435
+ /** Seconds left on the self-timer; 0 when no countdown is running. */
436
+ timerRemainingSeconds: number;
437
+ };
438
+ export type CameraVector3 = {
439
+ x: number;
440
+ y: number;
441
+ z: number;
442
+ };
443
+ /** Drone pose in world space. Rotation is degrees. */
444
+ export type HelixCameraDroneTransform = {
445
+ position: CameraVector3;
446
+ yaw: number;
447
+ pitch: number;
448
+ roll: number;
449
+ };
450
+ /** How the drone treats its subject: free flight, held framing, or a circling orbit. */
451
+ export type CameraDroneLockMode = 'free' | 'lock' | 'orbit';
452
+ /**
453
+ * Phase-2 vocabulary. Contracted now so HELIX OS, the web engine and Unreal
454
+ * agree on the names before anyone implements them; `camera.flyDrone` is
455
+ * `unavailable` until the flight-authority question is answered (a drone is a
456
+ * second body in a shared world, so who may move it is not a client decision).
457
+ */
458
+ export type HelixCameraDroneState = {
459
+ /** Stable per-session drone identity — a world may see more than one. */
460
+ droneId: string;
461
+ transform: HelixCameraDroneTransform;
462
+ /** Metres per second, world axes. */
463
+ velocity: CameraVector3;
464
+ /** Seconds the runtime should smooth toward `transform`; 0 = snap. */
465
+ interpolationSeconds: number;
466
+ lockMode: CameraDroneLockMode;
467
+ /** Platform userId the drone locks/orbits; '' while free-flying. */
468
+ subjectUserId: string;
469
+ /** True while the drone is flying itself back to its owner. */
470
+ returning: boolean;
471
+ /** Metres between the drone and its return point. */
472
+ returnDistance: number;
473
+ };
474
+ /** A request to move the drone. Every field is optional; omitted fields are left alone. */
475
+ export type HelixCameraDroneCommand = {
476
+ lockMode?: CameraDroneLockMode;
477
+ subjectUserId?: string;
478
+ transform?: HelixCameraDroneTransform;
479
+ velocity?: CameraVector3;
480
+ interpolationSeconds?: number;
481
+ returnToAvatar?: boolean;
482
+ };
483
+ /**
484
+ * The whole camera, as one shell-owned snapshot pushed to the runtime.
485
+ *
486
+ * Sent WHOLE rather than as deltas: the shell re-sends it after helix:init so a
487
+ * runtime that booted mid-session is never left guessing, and a whole snapshot
488
+ * makes that replay idempotent (see HelixCameraShutter for the one field where
489
+ * that needed thought).
490
+ */
491
+ export type HelixCameraState = {
492
+ session: CameraSessionState;
493
+ media: CameraMediaMode;
494
+ spatial: CameraSpatialMode;
495
+ controlTarget: CameraControlTarget;
496
+ /** The lens button that is lit — the preset nearest `zoom`, not the zoom itself. */
497
+ lens: CameraLensPreset;
498
+ /** Effective zoom, continuous within the preset range. */
499
+ zoom: number;
500
+ filter: CameraFilterId;
501
+ timerSeconds: CameraTimerSeconds;
502
+ aim: CameraAim;
503
+ shutter: HelixCameraShutter;
504
+ /** The capability the shell currently believes the runtime has (see reportCapability). */
505
+ capability: HelixCameraCapability;
506
+ /** Absent until the player taps to focus, and whenever capability.focusPoint is false. */
507
+ focusPoint?: CameraFocusPoint;
508
+ /** Exposure compensation in stops. Absent whenever capability.exposureBias is false. */
509
+ exposureBias?: number;
510
+ /** Absent for every handheld mode; present only while `session` is 'drone'. */
511
+ drone?: HelixCameraDroneState;
512
+ };
513
+ /**
514
+ * A WORLD SCRIPT asking HELIX OS to change the camera — the one camera surface
515
+ * that is world-driven rather than player-driven, and the reason the
516
+ * `camera.control` manifest capability exists. Every field is optional; the
517
+ * shell applies the ones present and answers with the resulting state.
518
+ *
519
+ * `shutter: true` requests ONE capture (it increments the sequence); it is not a
520
+ * level. `recording` is a level — set it false to stop.
521
+ */
522
+ export type HelixCameraControl = {
523
+ session?: CameraSessionState;
524
+ media?: CameraMediaMode;
525
+ spatial?: CameraSpatialMode;
526
+ controlTarget?: CameraControlTarget;
527
+ zoom?: number;
528
+ filter?: CameraFilterId;
529
+ timerSeconds?: CameraTimerSeconds;
530
+ aim?: CameraAim;
531
+ focusPoint?: CameraFocusPoint;
532
+ exposureBias?: number;
533
+ shutter?: boolean;
534
+ recording?: boolean;
535
+ /** Record the world's audio bed with a video (requires capability.worldAudio). */
536
+ worldAudio?: boolean;
537
+ };
141
538
  export type PurchaseContext = {
142
539
  ref: string;
143
540
  title: string;
@@ -149,12 +546,197 @@ export type PurchaseContext = {
149
546
  balanceAfterLix: number;
150
547
  owned: boolean;
151
548
  ownedCount: number;
152
- maxPerUser: number | null;
549
+ maxPerPlayer?: number | null;
550
+ maxPerUser?: number | null;
153
551
  eligible: boolean;
154
552
  eligibilityStatus: PurchaseStatus | null;
553
+ quantity?: number;
554
+ unitPriceLix?: number;
555
+ totalPriceLix?: number;
556
+ editionMode?: ItemEditionMode;
557
+ supply?: number | null;
558
+ minted?: number | null;
559
+ remaining?: number | null;
560
+ serialNumber?: number | null;
561
+ distributionId?: string | null;
562
+ listingId?: string | null;
563
+ creatorName?: string | null;
564
+ sellerName?: string | null;
565
+ maxClaims?: number | null;
566
+ startsAt?: string | null;
567
+ endsAt?: string | null;
568
+ verificationLevel?: AccountVerificationLevel;
569
+ requiredVerificationLevel?: AccountVerificationLevel | null;
570
+ resaleEligibleAt?: string | null;
571
+ holdUntil?: string | null;
572
+ grants?: ProductGrant[];
573
+ };
574
+ export type ProductGrant = {
575
+ kind: 'item';
576
+ itemId: string;
577
+ quantity?: number;
578
+ } | {
579
+ kind: 'pass';
580
+ passKey?: string;
581
+ durationSeconds?: number;
582
+ } | {
583
+ kind: 'currency';
584
+ code: string;
585
+ amount: number;
586
+ display?: 'wallet' | 'uses';
587
+ };
588
+ export type Entitlements = {
589
+ v: 1;
590
+ passes: Record<string, {
591
+ since: number;
592
+ expiresAt: number | null;
593
+ active: boolean;
594
+ }>;
595
+ balances: Record<string, number>;
596
+ owned: Record<string, number>;
597
+ };
598
+ export type ConsumeResult = {
599
+ applied: boolean;
600
+ balance: number;
601
+ reason?: 'insufficient';
602
+ };
603
+ export type DataStoreListPayload = {
604
+ prefix?: string;
605
+ cursor?: string;
606
+ limit?: number;
607
+ };
608
+ export type DataStoreListPage = {
609
+ keys: string[];
610
+ nextCursor?: string;
611
+ };
612
+ export type DataStoreWriteOptions = {
613
+ expectedVersion?: number;
614
+ };
615
+ export type DataStoreListOptions = {
616
+ cursor?: string;
617
+ limit?: number;
618
+ };
619
+ export type LeaderboardOrder = 'desc' | 'asc';
620
+ export type LeaderboardEntry = {
621
+ subject: string;
622
+ displayName: string;
623
+ score: number;
624
+ source: string;
625
+ updatedAt: string;
626
+ };
627
+ export type LeaderboardPage = {
628
+ entries: LeaderboardEntry[];
629
+ truncated: boolean;
630
+ };
631
+ export type LeaderboardSubmitOptions = {
632
+ order?: LeaderboardOrder;
633
+ };
634
+ export type LeaderboardTopOptions = {
635
+ limit?: number;
636
+ order?: LeaderboardOrder;
637
+ };
638
+ export type LeaderboardSubmitResult = {
639
+ best: number | null;
640
+ updated: boolean;
641
+ };
642
+ export type AchievementSummary = {
643
+ id: string;
644
+ key: string;
645
+ name: string;
646
+ description: string | null;
647
+ points: number;
648
+ hidden: boolean;
649
+ earned: boolean;
650
+ rarityTier: string;
651
+ earnPct: number | null;
652
+ iconUrl: string | null;
653
+ };
654
+ export type AchievementListResult = {
655
+ achievements: AchievementSummary[];
656
+ total: number;
657
+ earned: number;
658
+ };
659
+ export type AchievementMineResult = {
660
+ achievements: AchievementSummary[];
661
+ };
662
+ export type HelixRequestMethod = 'wallet.getBalance' | 'listen.consume' | 'listen.release' | 'listen.heartbeat' | 'listen.close' | 'marketplace.purchase' | 'marketplace.getListings' | 'inventory.hasItem' | 'inventory.getQuantity' | 'inventory.getMyItems' | 'inventory.equipItem' | 'avatar.getEquipped' | 'avatar.getLoadout' | 'avatar.updateLoadout' | 'avatar.openCreator' | 'emotes.openCustomizer' | 'emotes.getEquipped' | 'quickSlots.get' | 'quickSlots.patch' | 'quickSlots.activate' | 'quickSlots.deactivate' | 'quickSlots.openCustomizer' | 'quickSlots.browseAll' | 'iwp.getContext' | 'iwp.getPurchase' | 'iwp.getEntitlements' | 'iwp.consumeEntitlement' | 'dataStore.get' | 'dataStore.getEntry' | 'dataStore.set' | 'dataStore.delete' | 'dataStore.list' | 'leaderboard.submit' | 'leaderboard.top' | 'achievements.list' | 'achievements.mine' | 'camera.savePhoto' | 'camera.control';
663
+ export type HelixEvent = 'balance-changed' | 'inventory-changed' | 'entitlements-changed' | 'avatar-changed' | 'equipment-changed' | 'emotes-changed' | 'items-changed' | 'overlay-open' | 'overlay-closed';
664
+ export type HelixMultiplayerRosterEntry = {
665
+ /** Room-scoped seat key (the RoomState.players map key / colyseus sessionId). */
666
+ sessionId: string;
667
+ /** Platform user id (PlayerState.userId, contract v18) — '' when the room predates v18. */
668
+ userId: string;
669
+ displayName: string;
670
+ /** Equipped-avatar GLB URL ('' = default body). NOT a profile picture — resolve those via userId. */
671
+ avatarUrl: string;
672
+ isSelf: boolean;
673
+ /** False while the seat sits in the server's reconnection grace window. */
674
+ connected: boolean;
675
+ };
676
+ export type HelixMultiplayerState = {
677
+ /** The joined Colyseus room instance id — the platform's only true instance identity. */
678
+ roomId: string;
679
+ /** This client's seat key (also flagged isSelf in `players`). */
680
+ sessionId: string;
681
+ playerCount: number;
682
+ /** The room's seat cap (credential maxPlayers), or null when unknown (e.g. resumed via reload). */
683
+ maxPlayers: number | null;
684
+ players: HelixMultiplayerRosterEntry[];
685
+ /** The room's type (manifest `multiplayer.roomTypes`). Absent for the default room. */
686
+ roomType?: string;
687
+ /**
688
+ * True when the room is a TICKETED instance: entered by redeeming a ticket, private to its ticket holders.
689
+ * Its `roomId` must not be offered as a public join target (`?instance=`). Absent otherwise.
690
+ */
691
+ ticketed?: boolean;
692
+ };
693
+ export type HelixVoiceMicMode = 'ptt' | 'open' | 'muted';
694
+ export type HelixVoicePermission = 'prompt' | 'granted' | 'denied';
695
+ export type HelixVoiceDevice = {
696
+ deviceId: string;
697
+ label: string;
698
+ };
699
+ export type HelixVoiceSettings = {
700
+ micMode: HelixVoiceMicMode;
701
+ /** Preferred audioinput deviceId — a hint; the world falls back to default when it no longer resolves. */
702
+ micDeviceId?: string;
703
+ /** The preferred mic's human label. deviceIds are origin-scoped, so when micDeviceId doesn't resolve
704
+ * where the mic is captured, the world re-targets the device whose label matches. */
705
+ micDeviceLabel?: string;
706
+ /** Platform userIds this player has locally muted. Always the full list, never a delta. */
707
+ mutedUserIds: string[];
708
+ /** Outgoing mic gain, 0..2 (1 = as-captured, Discord-style 0–200%). */
709
+ micVolume?: number;
710
+ /** Incoming voice master gain, 0..2 (1 = as-received). Composes with the engine's proximity gain. */
711
+ outputVolume?: number;
712
+ /** True (default): no manual gate — transmit whatever the mic hears (browser noise suppression still applies). */
713
+ micAutoSensitivity?: boolean;
714
+ /** Manual input-sensitivity gate threshold in meter units (0..1): input below it is cut. */
715
+ micSensitivity?: number;
716
+ };
717
+ export type HelixVoiceState = {
718
+ /** False when this session has no voice (world lacks voice.* permission / no server configured). */
719
+ available: boolean;
720
+ connected: boolean;
721
+ micMode: HelixVoiceMicMode;
722
+ /** Effective KeyboardEvent.key used by this world while push-to-talk is active. */
723
+ pttKey?: string;
724
+ /** True while the local microphone's mode gate is open. In PTT this follows the held key; in
725
+ * open-mic mode it stays true. The live level remains the source of detected loudness. */
726
+ transmitting: boolean;
727
+ permission: HelixVoicePermission;
728
+ /** The device actually in use — may differ from the requested micDeviceId after fallback. */
729
+ activeDeviceId?: string;
730
+ devices: HelixVoiceDevice[];
731
+ /** Platform userIds currently speaking (muted-by-me and out-of-channel players never appear). Throttled world-side. */
732
+ speakingUserIds: string[];
733
+ /** The player's current exclusive voice channel (absent = the ambient space). */
734
+ channelId?: string;
735
+ /** True until the one-time autoplay unlock gesture inside the world — while set, remote audio is
736
+ * silent AND the local microphone pipeline cannot run, so nothing is sent either. */
737
+ audioBlocked?: boolean;
738
+ error?: string;
155
739
  };
156
- export type HelixRequestMethod = 'wallet.getBalance' | 'marketplace.purchase' | 'marketplace.getListings' | 'inventory.hasItem' | 'inventory.getQuantity' | 'inventory.getMyItems' | 'inventory.equipItem' | 'avatar.getEquipped' | 'avatar.getLoadout' | 'avatar.updateLoadout' | 'avatar.openCreator' | 'iwp.getContext' | 'iwp.getPurchase' | 'dataStore.get' | 'dataStore.set' | 'dataStore.delete' | 'dataStore.list' | 'camera.savePhoto';
157
- export type HelixEvent = 'balance-changed' | 'inventory-changed' | 'avatar-changed' | 'equipment-changed' | 'overlay-open' | 'overlay-closed';
158
740
  export type HelixNotificationKind = 'success' | 'failure' | 'notification' | 'message';
159
741
  export type HelixNotification = {
160
742
  kind: HelixNotificationKind;
@@ -166,6 +748,11 @@ export type HelixNotification = {
166
748
  };
167
749
  export type HelixPromptState = 'default' | 'available' | 'locked' | 'busy';
168
750
  export type HelixDeviceFormFactor = 'phone' | 'tablet';
751
+ /** Shell-owned Helix OS visibility mirrored into every embedded world. */
752
+ export type HelixDeviceState = {
753
+ open: boolean;
754
+ form?: HelixDeviceFormFactor;
755
+ };
169
756
  export type HelixInteractionPrompt = {
170
757
  id: string;
171
758
  title: string;
@@ -179,6 +766,18 @@ export type HelixInteractionPrompt = {
179
766
  state?: HelixPromptState;
180
767
  priority?: number;
181
768
  };
769
+ /**
770
+ * Dispatched by the ENGINE XR module on every session state change; the SDK forwards it to the shell.
771
+ * detail: { state: 'unsupported'|'idle'|'entering'|'active'|'exiting'; reason?: string; source: 'humanoid-character' }
772
+ * Sticky store: document.__helixXrSession = { state, reason }
773
+ */
774
+ export declare const XR_SESSION_EVENT = "helix:xr-session";
775
+ /**
776
+ * Dispatched by the SDK when Helix.prompts.set/clear is called; the engine XR module draws it in-scene.
777
+ * detail: { prompt: { id: string; label: string; state?: 'default'|'available'|'locked'|'busy' } | null; source: 'helix-sdk' }
778
+ * Sticky store: document.__helixInteractionPrompt = detail
779
+ */
780
+ export declare const XR_INTERACTION_PROMPT_EVENT = "helix:interaction-prompt";
182
781
  export type WorldToShellMessage = {
183
782
  type: 'helix:ready';
184
783
  protocolVersion: number;
@@ -191,6 +790,22 @@ export type WorldToShellMessage = {
191
790
  } | {
192
791
  type: 'helix:open-device';
193
792
  form?: HelixDeviceFormFactor;
793
+ } | {
794
+ type: 'helix:multiplayer-state';
795
+ state: HelixMultiplayerState | null;
796
+ } | {
797
+ type: 'helix:multiplayer-join-error';
798
+ instanceId: string;
799
+ message: string;
800
+ } | {
801
+ type: 'helix:voice-state';
802
+ state: HelixVoiceState | null;
803
+ } | {
804
+ type: 'helix:voice-level';
805
+ level: number;
806
+ } | {
807
+ type: 'helix:camera-capability';
808
+ capability: HelixCameraCapability;
194
809
  } | {
195
810
  type: 'helix:request';
196
811
  requestId: string;
@@ -205,6 +820,22 @@ export type WorldToShellMessage = {
205
820
  } | {
206
821
  type: 'helix:clear-interaction-prompt';
207
822
  promptId?: string;
823
+ } | {
824
+ type: 'helix:xr-session';
825
+ state: 'entering' | 'active' | 'exiting' | 'idle' | 'unsupported';
826
+ reason?: string;
827
+ }
828
+ /**
829
+ * ADR-0003: the answer to `helix:distribution-capability-request`, from the world's room. Either the minted
830
+ * single-use capability or the room's reason (`not_in_room` when this world never joined a room).
831
+ */
832
+ | {
833
+ type: 'helix:distribution-capability-result';
834
+ requestId: string;
835
+ capability?: string;
836
+ expiresAt?: string;
837
+ ref?: string;
838
+ error?: string;
208
839
  };
209
840
  export type ShellToWorldMessage = {
210
841
  type: 'helix:init';
@@ -212,6 +843,13 @@ export type ShellToWorldMessage = {
212
843
  world: HelixWorldContext;
213
844
  session: HelixSession | null;
214
845
  debug?: boolean;
846
+ instanceId?: string;
847
+ apiBaseUrl?: string | null;
848
+ /**
849
+ * Versioned presentation intent. Additive: older shells omit it and the
850
+ * SDK exposes null so the engine retains its Auto fallback.
851
+ */
852
+ runtimeFidelity?: RuntimeFidelityIntent;
215
853
  } | {
216
854
  type: 'helix:session';
217
855
  session: HelixSession | null;
@@ -226,9 +864,34 @@ export type ShellToWorldMessage = {
226
864
  ok: boolean;
227
865
  result?: unknown;
228
866
  error?: string;
867
+ errorCode?: string;
229
868
  } | {
230
869
  type: 'helix:event';
231
870
  event: HelixEvent;
232
871
  data?: unknown;
872
+ } | {
873
+ type: 'helix:voice-settings';
874
+ settings: HelixVoiceSettings;
875
+ } | {
876
+ type: 'helix:voice-ptt';
877
+ down: boolean;
878
+ } | {
879
+ type: 'helix:device-state';
880
+ open: boolean;
881
+ form?: HelixDeviceFormFactor;
882
+ } | {
883
+ type: 'helix:camera-state';
884
+ state: HelixCameraState;
885
+ } | {
886
+ type: 'helix:leave';
887
+ }
888
+ /**
889
+ * ADR-0003: the shell's confirmed Claim/Buy of a World route asks the world to obtain a one-time acquisition
890
+ * capability from its room (the only party that can mint one). Answered with helix:distribution-capability-result.
891
+ */
892
+ | {
893
+ type: 'helix:distribution-capability-request';
894
+ requestId: string;
895
+ ref: string;
233
896
  };
234
897
  export declare function isShellMessage(data: unknown): data is ShellToWorldMessage;