API reference

UniversalActionSurfaceOptions

Returns

boolean

dispose()

dispose(): Promise<void>

Returns

Promise<void>

has()

has(id): boolean

Parameters

id

string

Returns

boolean

pop()

pop(id?, aborted?): Promise<boolean>

Parameters

id?

string

aborted?

boolean

Returns

Promise<boolean>

push()

push<R>(mode, params?, options?): Promise<PushOutcome<R>>

Type Parameters

R

R = unknown

Parameters

mode

InteractionMode<R>

params?

Record<string, unknown>

options?

PushOptions<R>

Returns

Promise<PushOutcome<R>>

update()

update(dtSeconds): void

Parameters

dtSeconds

number

Returns

void

UniversalActionSurface

Portable DOM component for a proximity/list presentation.

It installs no keyboard, pointer-lock, gamepad, or raw touch listeners. A trusted mode host delivers the three semantic actions through handleVerb, while ordinary DOM activation keeps the rendered controls accessible.

Constructors

Constructor

new UniversalActionSurface(options): UniversalActionSurface

Parameters

options

Returns

UniversalActionSurface

Properties

element

readonly element: HTMLElement

Accessors

instanceId

Get Signature

get instanceId(): string | null

Returns

string | null

isOpen

Get Signature

get isOpen(): boolean

Returns

boolean

liveNumber

Get Signature

get liveNumber(): number | null

Returns

number | null

liveText

Get Signature

get liveText(): string | null

Returns

string | null

mode

Get Signature

get mode(): "number" | "text" | "browse" | "picker"

Returns

"number" | "text" | "browse" | "picker"

selectedAction

Get Signature

get selectedAction(): ActionSurfaceAction | null

Returns

ActionSurfaceAction | null

visibleActions

Get Signature

get visibleActions(): readonly ActionSurfaceAction[]

Returns

readonly ActionSurfaceAction[]

Methods

cancel()

cancel(): void

Back out of a sustained control; dismiss the proximity list at root.

Returns

void

confirm()

confirm(): void

Returns

void

dismiss()

dismiss(): void

Dismiss this proximity offer until the host explicitly rearms it.

Returns

void

dispose()

dispose(): void

Returns

void

endEngagement()

endEngagement(): void

Release modal focus without dismissing the still-valid proximity offer.

Returns

void

handleVerb()

handleVerb(verb, event): void

Semantic input entry point used by createActionSurfaceMode.

Parameters

verb

"navigate" | "activate" | "back"

event

VaultArtifactUnavailableError

Returns

void

hide()

hide(): void

Returns

void

move()

move(delta): void

Navigate one row/option or nudge a sustained number.

Parameters

delta

-1 | 1

Returns

void

observePointer()

observePointer(pointerType): void

Record pointer input that reaches the host's opener before this surface. This keeps the first rendered hints aligned with the input that opened it.

Parameters

pointerType

string

Returns

void

rearm()

rearm(): void

Returns

void

refreshHints()

refreshHints(): void

Refresh active-device/rebind text when the router has no subscription API.

Returns

void

setSnapshot()

setSnapshot(snapshot): void

Open or refresh the caller-scoped cache. Pass null to withdraw it.

Parameters

snapshot

ActionSurfaceSnapshot | null

Returns

void

VaultApiError

Extends

Error

Constructors

Constructor

new VaultApiError(status, url, responseBody): VaultApiError

Parameters

status

number

url

string

responseBody

string

Returns

VaultApiError

Overrides

Error.constructor

Properties

cause?

optional cause?: unknown

Inherited from

Error.cause

message

message: string

Inherited from

Error.message

name

name: string

Inherited from

Error.name

responseBody

readonly responseBody: string

stack?

optional stack?: string

Inherited from

Error.stack

status

readonly status: number

url

readonly url: string

VaultArtifactUnavailableError

Extends

Error

Constructors

Constructor

new VaultArtifactUnavailableError(handle): VaultArtifactUnavailableError

Parameters

handle

VaultAssetHandle

Returns

Overrides

Error.constructor

Properties

cause?

optional cause?: unknown

Inherited from

Error.cause

handle

readonly handle: VaultAssetHandle

message

message: string

Inherited from

Error.message

name

name: string

Inherited from

Error.name

stack?

optional stack?: string

Inherited from

Error.stack

VaultCapabilityUnavailableError

Extends

Error

Constructors

Constructor

new VaultCapabilityUnavailableError(capability): VaultCapabilityUnavailableError

Parameters

capability

"fetch" | "sha256"

Returns

VaultCapabilityUnavailableError

Overrides

Error.constructor

Properties

capability

readonly capability: "fetch" | "sha256"

cause?

optional cause?: unknown

Inherited from

Error.cause

message

message: string

Inherited from

Error.message

name

name: string

Inherited from

Error.name

stack?

optional stack?: string

Inherited from

Error.stack

VaultChecksumMismatchError

Extends

Error

Constructors

Constructor

new VaultChecksumMismatchError(expected, actual): VaultChecksumMismatchError

Parameters

expected

string

actual

string

Returns

VaultChecksumMismatchError

Overrides

Error.constructor

Properties

actual

readonly actual: string

cause?

optional cause?: unknown

Inherited from

Error.cause

expected

readonly expected: string

message

message: string

Inherited from

Error.message

name

name: string

Inherited from

Error.name

stack?

optional stack?: string

Inherited from

Error.stack

VaultUnsupportedRuntimeError

Extends

Error

Constructors

Constructor

new VaultUnsupportedRuntimeError(kind, mimeType, reason): VaultUnsupportedRuntimeError

Parameters

kind

mimeType

string

reason

string

Returns

VaultUnsupportedRuntimeError

Overrides

Error.constructor

Properties

cause?

optional cause?: unknown

Inherited from

Error.cause

kind

readonly kind: "audio" | "character" | "texture" | "prop" | "animation" | "material" | "environment" | "terrain" | "vfx" | "decal" | "sky" | "gaussian_splat" | "scene" | "unreal_package"

message

message: string

Inherited from

Error.message

mimeType

readonly mimeType: string

name

name: string

Inherited from

Error.name

stack?

optional stack?: string

Inherited from

Error.stack

VehicleSpecialtyRoomTransport

Binds a checksum-pinned Universal Vehicle specialty module to the normal HELIX room. State is hydrated immediately for late joiners, then assigned a client-local monotonic revision on every distinct authoritative patch.

Constructors

Constructor

new VehicleSpecialtyRoomTransport(room, binding): VehicleSpecialtyRoomTransport

Parameters

room

VehicleSpecialtyRoom

binding

VehicleSpecialtyRoomBinding

Returns

VehicleSpecialtyRoomTransport

Methods

detachActionIds()

detachActionIds(): readonly string[]

The exact detachable-part action ids admitted by this signed placement.

Returns

readonly string[]

dispose()

dispose(): void

Returns

void

invoke()

invoke(invocation): void

Parameters

invocation

VehicleSpecialtyInvocation

Returns

void

invokeComponent()

invokeComponent(invocation): boolean

Submit one server-authoritative component mutation using only the trusted constructor identity and entity. The room and server resolve live vehicle authority and admit the action against the signed component protocol.

Parameters

invocation

VehicleSpecialtyComponentInvocation

Returns

boolean

invokeDetach()

invokeDetach(invocation): boolean

Submit one admitted rigid-part detach intent with constructor-bound package identity. Unknown action ids fail closed without consuming a replay number.

Parameters

invocation

VehicleSpecialtyDetachInvocation

Returns

boolean

snapshot()

snapshot(): VehicleSpecialtyStateSnapshot | null

Returns

VehicleSpecialtyStateSnapshot | null

subscribeEffect()

subscribeEffect(subscriber): () => void

Parameters

subscriber

EffectSubscriber

Returns

() => void

subscribeState()

subscribeState(subscriber): () => void

Parameters

subscriber

StateSubscriber

Returns

() => void

WorldDeviceHost

Renderer-neutral World Device host. The world supplies its engine adapter; HELIX supplies immutable placement identity, authoritative room state/actions, server time, compatibility checks, and lifecycle.

Constructors

Constructor

new WorldDeviceHost(room, adapter, resolveDefinition): WorldDeviceHost

Parameters

room

Pick<HelixRoom, "state" | "module" | "onStateChange" | "sendAction">

Properties

adapter

readonly adapter: WorldDevicePresentationAdapter

now

now: () => number

Returns

number

resolveDefinition

readonly resolveDefinition: WorldDeviceDefinitionResolver

room

readonly room: Pick<HelixRoom, "state" | "module" | "onStateChange" | "sendAction">

Methods

dispose()

dispose(): Promise<void>

Returns

Promise<void>

mount()

mount(spawn): Promise<boolean>

Parameters

spawn

WorldDeviceMount

Returns

Promise<boolean>

Interfaces

AbilityMessage

Discrete ability activation intent.

Properties

ability

ability: string

Ability id (must be one the world's build declares).

active

active: boolean

true = activate, false = deactivate.

AccessorModuleState

Properties

entities?

optional entities?: KeyedBag<EntityBag>

phase?

optional phase?: string

players?

optional players?: KeyedBag<PlayerBag>

roomVars?

optional roomVars?: Record<string, unknown>

timerDeadlines?

optional timerDeadlines?: KeyedBag<number>

AccessorRoomState

The room-level state slice the accessors read (structural — the live RoomState satisfies it). Live state holds players as a MapSchema (Map-like, .get()); plain Records are admitted for fixtures.

Properties

dynamicModules?

optional dynamicModules?: KeyedBag<AccessorDynamicModuleState>

moduleChunks?

optional moduleChunks?: Record<string, Record<string, AccessorModuleState | undefined> | undefined>

Overflow modules follow the first 64 slots in consecutive c0, c1, ... wire chunks.

modules?

optional modules?: Record<string, AccessorModuleState | undefined>

phase?

optional phase?: string

players?

optional players?: { get: PlayerBag; } | Record<string, PlayerBag>

roomVars?

optional roomVars?: Record<string, unknown>

ActionMessage

A world-authored declared action — the generic extensibility channel (e.g. 'captureFlag', 'scorePoint'). The room validates name against the world's declared action set and args against that action's declared arg schema before mutating authoritative state (table-driven dispatch); this module carries the envelope + arg vocabulary only, never the per-world rules.

Properties

args?

optional args?: Record<string, RoomVarValue>

Primitive/Vec3 args, validated against the declared action's schema by the room.

bundleChecksumSha256?

optional bundleChecksumSha256?: string

engagement?

optional engagement?: "acquire" | "release"

Platform-owned engaged-module envelope. acquire requests the exclusive room grant for this declared action; release relinquishes the current grant. Ordinary semantic verbs omit it.

engagementEpoch?

optional engagementEpoch?: number

Room-issued authority epoch. The SDK stamps it on release and every post-grant semantic verb; authored item data never supplies or persists it.

engagementRequestId?

optional engagementRequestId?: number

SDK-generated correlation id, present only on acquire/release requests.

finalRest?

optional finalRest?: object

group

group: string

requestId

requestId: number

scope?

optional scope?: FinalRestProvenance

version

version: 1

itemInstanceId?

optional itemInstanceId?: string

Full mounted identity used by specialized item actions.

moduleId?

optional moduleId?: string

Optional module provenance; absent addresses the byte-compatible implicit world program.

moduleRevision?

optional moduleRevision?: number

name

name: string

Action name; must be one the world's build declares.

vehicleAction?

optional vehicleAction?: VehicleActionEnvelope

Optional strict vehicle-component fence on the existing action channel. Legacy actions omit it; a trusted vehicle placement that declares named component actions requires it and validates every field server-side.

ActionSurfaceAction

A caller-scoped, authority-resolved row.

Dynamic labels and enabled/visible expressions are evaluated before this value reaches the SDK. This list is an advisory presentation cache: every invocation must be re-authorized by the authority.

Properties

availability?

optional availability?: ActionSurfaceAvailability

call?

optional call?: string

enabled?

optional enabled?: boolean

id

id: string

inputMode?

optional inputMode?: "text" | "none" | "tel" | "url" | "email" | "numeric" | "decimal" | "search"

kind

kind: ActionSurfaceKind

label

label: string

max?

optional max?: number

maxLength?

optional maxLength?: number

min?

optional min?: number

options?

optional options?: readonly ActionSurfaceOption[]

choice or asset: caller-filtered concrete choices.

optionsFrom?

optional optionsFrom?: ActionSurfaceOptionsFrom

Describes where the authority obtained options; never resolved here.

placeholder?

optional placeholder?: string

text: native text-entry hints. Authority still validates submitted text.

reason?

optional reason?: string

socket?

optional socket?: string

step?

optional step?: number

unit?

optional unit?: string

value?

optional value?: string | number | null

number and picker actions: the current authoritative value.

var?

optional var?: string

number: the authority-backed variable this row writes.

visible?

optional visible?: boolean

ActionSurfaceAvailability

Properties

label?

optional label?: string

Player-readable state such as "In use by Mira". Never render an internal id.

state

state: "available" | "busy" | "occupied"

ActionSurfaceHintSource

Adapter over the trusted router's active-device and hint() surfaces.

Methods

activeDevice()

activeDevice(): ActionSurfaceDevice

Returns

ActionSurfaceDevice

hint()

hint(action): string

Parameters

action

"primary" | "move" | "cancel"

Returns

string

optional subscribe(listener): () => void

Optional active-device/rebind subscription.

Parameters

listener

() => void

Returns

() => void

ActionSurfaceModeOptions

Properties

id?

optional id?: string

suppression?

optional suppression?: Suppression

surface

surface: UniversalActionSurface

ActionSurfaceOption

Properties

disabled?

optional disabled?: boolean

label

label: string

reason?

optional reason?: string

value

value: string

ActionSurfaceOptionsFrom

Provenance for authority-resolved options. The presentation surface never executes these queries; it receives their filtered options result.

Properties

inventory?

optional inventory?: object

accepts

accepts: string

query?

optional query?: object

has

has: string

scope?

optional scope?: "world" | "room"

var?

optional var?: string

ActionSurfaceSnapshot

Properties

actions

actions: readonly ActionSurfaceAction[]

availability?

optional availability?: ActionSurfaceAvailability

instanceId

instanceId: string

title

title: string

AttachmentEntry

One replicated prop attachment (v20). Exactly what a remote replica needs to render the prop: the asset URL (opaque world data — every client fetches the same CDN asset), the socket name, and the sender-RESOLVED socket-local offsets — the preset is applied at the sender, so replicas place the prop correctly across humanoid-character version skew. preset still rides the wire as a forward hook (Phase 3 pairs presets with grip finger poses); placement never depends on it.

Properties

asset

asset: string

Prop GLB URL (https, room-sanitized, length-bounded). A failed/unknown asset no-ops on replicas.

id

id: string

Client-generated id, unique within the seat (ATTACHMENT_LIMITS.idPattern); replicas diff + evict by it.

position

position: Vec3

Socket-local offset, METERS. Vec3 like every other wire position (the room mirrors it as Vec3Schema).

preset

preset: string

HELD_ITEM_PRESETS key or '' — the offsets above are already final.

rotationEulerDeg

rotationEulerDeg: Vec3

Socket-local orientation, DEGREES (XYZ euler order), as a Vec3 {x,y,z}.

socket

socket: string

Socket name on the helix-humanoid rig (e.g. 'hand_r.grip'); a socket the replica's rig lacks no-ops.

AttachmentsMessage

Replace the sender's ENTIRE attachment set (v20). Full-set replace, idempotent — the desired set IS the message, so there is no attach/detach op ordering to get wrong and a lost message heals on the next send. Attachments are persistent → the room writes them to synced PlayerState.attachments (late joiners converge); no server relay channel exists. The room validates structurally only (ATTACHMENT_LIMITS + https on asset) — asset URLs and preset names are opaque world data, the gesture-name trust shape.

Properties

attachments

attachments: AttachmentEntry[]

CameraIntent

Properties

blendSeconds?

optional blendSeconds?: number

clamp?

optional clamp?: object

pitch?

optional pitch?: [number, number]

yaw?

optional yaw?: [number, number]

distance

distance: number

fov?

optional fov?: number

orbit?

optional orbit?: object

pitchDeg

pitchDeg: number

yawDeg

yawDeg: number

target

target: object

x

x: number

y

y: number

z

z: number

ClientMessagePayloads

Maps each client→server message type to its payload, so senders/handlers stay in lockstep.

Properties

ability

ability: AbilityMessage

action

action: ActionMessage

attachments

attachments: AttachmentsMessage

avatarRefresh

avatarRefresh: AvatarRefreshMessage

emoteJoin

emoteJoin: EmoteJoinMessage

emoteRefresh

emoteRefresh: EmoteRefreshMessage

entityState

entityState: EntityStateMessage

entityStateBatch

entityStateBatch: EntityStateBatchMessage

gesture

gesture: GestureMessage

ping

ping: PingMessage

purchaseReceipt

purchaseReceipt: PurchaseReceiptMessage

state

state: StateMessage

DeviceAppDefinitionV1

Engine-neutral app declaration. The SDK types the declared surface — which powers a package asks for and where its content may come from — and never how a renderer draws it.

Properties

allowedOrigins?

optional allowedOrigins?: string[]

entry?

optional entry?: string

Authored source or host renderer id. Optional for remoteImage; absent for ownerImage.

permissions?

optional permissions?: DeviceAppPermissionV1[]

type

type: DeviceAppTypeV1

DeviceBusBudgetsV1

Properties

maxDeliveriesPerLinkPerTick

maxDeliveriesPerLinkPerTick: number

maxGraphLinks

maxGraphLinks: number

maxHopsPerDelivery

maxHopsPerDelivery: number

maxLinksPerEndpoint

maxLinksPerEndpoint: number

maxQueuedDeliveriesPerTick

maxQueuedDeliveriesPerTick: number

replayWindow

replayWindow: number

DeviceBusEnvelopeV1

Host-authored delivery. Callers never provide an authorization role.

Type Parameters

T

T = unknown

Properties

deliveryId

deliveryId: string

hopCount

hopCount: number

hostSequence

hostSequence: number

kind

kind: DevicePortKindV1

linkId

linkId: string

payload?

optional payload?: T

schemaVersion

schemaVersion: 1

semantic

semantic: string

source

source: DevicePortAddressV1

stream?

optional stream?: object

handle?

optional handle?: DeviceStreamHandleV1

mediaKind

mediaKind: "audio" | "video"

status

status: DeviceStreamRoutabilityV1

target

target: DevicePortAddressV1

DeviceDefinitionV1

Indexable

[key: string]: unknown

Properties

apps?

optional apps?: Record<string, DeviceAppDefinitionV1>

Apps a screen component may bind to, keyed by the name it binds with.

capabilities?

optional capabilities?: string[]

Native powers granted by the host; unknown/ungranted powers refuse mount.

compatibility?

optional compatibility?: object

hosts

hosts: ("home" | "world")[]

requiredCapabilities?

optional requiredCapabilities?: string[]

format

format: "helix.device"

formatVersion

formatVersion: 1

id

id: string

interactions

interactions: object[]

control?

optional control?: { kind: "number"; max?: number; min?: number; stateKey: string; step?: number; unit?: string; } | { kind: "choice"; options: object[]; stateKey: string; } | { inputMode?: "text" | "none" | "tel" | "url" | "email" | "numeric" | "decimal" | "search"; kind: "text"; maxLength?: number; placeholder?: string; stateKey: string; }

Universal Action Surface control; omitted means a normal run row.

Union Members

Type Literal

{ kind: "number"; max?: number; min?: number; stateKey: string; step?: number; unit?: string; }

Type Literal

{ kind: "choice"; options: object[]; stateKey: string; }

Type Literal

{ inputMode?: "text" | "none" | "tel" | "url" | "email" | "numeric" | "decimal" | "search"; kind: "text"; maxLength?: number; placeholder?: string; stateKey: string; }

inputMode?

optional inputMode?: "text" | "none" | "tel" | "url" | "email" | "numeric" | "decimal" | "search"

kind

kind: "text"

Native text entry rendered by the Universal Action Surface.

maxLength?

optional maxLength?: number

placeholder?

optional placeholder?: string

The interaction label is the Action Surface label; these tune its input.

stateKey

stateKey: string

Typed Device state written after authority accepts the submission.

id

id: string

label

label: string

maxDistanceM?

optional maxDistanceM?: number

presentation?

optional presentation?: object

Viewer-local HUD for one declared web app; never a replicated state action.

presentation.app

app: string

presentation.kind

kind: "webPanel"

verb?

optional verb?: "open" | "sit" | "use" | "close" | "toggle" | "play" | "custom"

ports?

optional ports?: DevicePortV1[]

Public endpoints. Home/World composition owns concrete Links.

state

state: Record<string, { default?: string | number | boolean; persist?: boolean; type: "boolean" | "integer" | "float" | "string" | "enum"; }>

version

version: string

DevicePortAddressV1

Properties

instanceId

instanceId: string

port

port: string

DevicePortV1

Engine-neutral endpoint declaration. Concrete Links belong to the host.

Properties

authority?

optional authority?: DevicePortAuthorityV1

Signal authority lane. Legacy declarations inherit from Device authority.

autoPair?

optional autoPair?: boolean

dataType

dataType: DevicePortDataTypeV1

direction

direction: DevicePortDirectionV1

id

id: string

interface?

optional interface?: string

Exact compatibility identity, such as helix.audio/1.

kind

kind: DevicePortKindV1

maxLinks?

optional maxLinks?: number

routability?

optional routability?: DeviceStreamRoutabilityV1

Stream availability; meaningful only for stream outputs.

semantic?

optional semantic?: string

Stable event/command/stream meaning. Defaults to the port id for v1 devices.

stateKey?

optional stateKey?: string

DynamicModuleState

Fixed public wire for a module installed after a room's reflection handshake. The authoritative room keeps the full typed program/state privately and projects only creator-declared public scalar room vars into these maps.

Properties

booleans

booleans: Record<string, boolean>

externalRevision

externalRevision: number

numbers

numbers: Record<string, number>

phase

phase: string

strings

strings: Record<string, string>

EmoteEntry

One emote the player CARRIES (v28) — an owned item, resolved onto the seat by the ROOM from the platform, never named by the client (the avatarUrl trust shape, not the attachments one). slot is the wheel position it plays from, clip the animation URL every client fetches for itself, playback how it runs.

Properties

audio?

optional audio?: string

The emote's SOUND url, every client fetches it for itself exactly like clip and under the same servable rule. Absent when the emote is silent — audio is garnish, so a clip whose sound fails sanitization still lands, without it.

clip

clip: string

Clip URL (servable, room-sanitized, EMOTE_LIMITS-bounded). A failed/unknown clip no-ops on replicas.

intro?

optional intro?: string

Optional ENTER transition: plays once and chains into clip. Same servable-url rule and the same EMOTE_LIMITS.maxClipUrlLength bound as clip. Never present with roles.

itemId

itemId: string

The universal-item id this emote came from; replicas diff + evict by (slot, itemId).

label?

optional label?: string

The item's display title, for the wheel's petals. Nameplate-sanitized + capped at EMOTE_LIMITS.maxLabelLength; absent when the platform named it nothing.

outro?

optional outro?: string

Optional EXIT transition: plays on a deliberate end and on a oneshot's natural completion. Same servable-url rule and bound as clip. Never present with roles. It replicates through the v19 gesture relay under the suffixed name emote.<slot>:outro — the relay is name-opaque, so no new message channel exists for it.

playback

playback: "oneshot" | "loop"

How the clip runs once triggered: once through, or until it is stopped.

roles?

optional roles?: object

PAIRED emote (v28): the second role this emote offers, so another player can join it. Absent = a solo emote, and only an 'r0'..'r7' slot may carry it (the room strips it elsewhere) — the posture slots are stances, not invitations. The INITIATOR is whoever plays the emote; a joiner runs joinerClip at the offset below, which is expressed in the INITIATOR-LOCAL frame (+Z = the initiator's facing, +X their right) so the pair stays composed wherever the initiator stands. The offer itself is a HELD POSE (offerAtS), and a pair is strictly 1:1 — the room refuses a second joiner on an initiator that already has one.

joinerClip

joinerClip: string

The joiner's clip URL — same servable-url rule and same EMOTE_LIMITS.maxClipUrlLength bound as clip.

offerAtS

offerAtS: number

The OFFER freeze, SECONDS into the INITIATOR's own clip: the engine plays 0→offerAtS once as a wind-up, then HOLDS that pose until a joiner arrives or the initiator cancels. ≥ 0 (0 = the first frame), bounded by EMOTE_LIMITS.maxOfferAtS and independent of playback, which describes only the JOINED performance.

offsetX

offsetX: number

Joiner offset from the initiator, METERS, initiator-local; each axis clamped to ±EMOTE_LIMITS.maxPairOffsetM.

offsetYawDeg

offsetYawDeg: number

The joiner's facing RELATIVE to the initiator's, DEGREES, normalized to [−180, 180] (180 = facing them).

offsetZ

offsetZ: number

slot

slot: "r0" | "r1" | "r2" | "r3" | "r4" | "r5" | "r6" | "r7" | "sit" | "lie"

Wheel position: 'r0'..'r7' are the eight radial slots, 'sit'/'lie' the two posture emotes.

EmoteJoinMessage

Join another player's PAIRED emote, or leave the one you are in (v28). A REQUEST, not a command: the room validates it (the initiator is live, offering a roles emote right now, is not the sender, and is within reach) and answers by writing the sender's pair fields — or by writing nothing at all. There is no refusal message: the sender sees its own PlayerState.pairInitiator stay '' and its local preview simply ends, which is the same outcome a race with the initiator stopping produces anyway.

Properties

initiator

initiator: string

The initiator's player id (a players map key), or '' to LEAVE the pair this player is in (always allowed).

EntityState

RESERVED (Tier 2): a server-spawned object (pickup, projectile, NPC). Empty in v1 — the shape is reserved so adding server-spawned entities later is additive. Tier 2 gives these author-defined behavior; v1 only freezes the slot in RoomState.

Properties

angularVelocity?

optional angularVelocity?: Vec3

authorityEpoch

authorityEpoch: number

Monotonic authority epoch (Tier 2 Phase 4.5.12, spec §9), bumped on every controller handoff — host migration AND voluntary ownership transfer. A controller client mirrors this into each EntityStateMessage; the room rejects an upload whose epoch ≠ the current one, fencing a stale authority era (a still-connected prior owner's in-flight frames after ownership moved). 0 at spawn; clients only read it.

controller

controller: string

Who simulates this entity (Tier 2 Phase 4.6c, spec §9). '' = server-authoritative (deterministic kinematics). A player id (a state.players key) = an owner-authoritative entity that client simulates + uploads (the others render it); a client reads this to know which entities it should be uploading via uploadEntity.

id

id: string

kind

kind: string

Author-defined kind (e.g. 'flag', 'pickup').

orientation?

optional orientation?: Quat

position?

optional position?: Vec3

posT

posT: number

Source-time stamp (ms) of this entity's current position — the server's apply-clock (owner-entity sender-time is a follow-up; server-authoritative entities self-stamp each tick). Consumers space interpolation by posT deltas, not arrival time. Monotonic; deltas only. 0 before first move.

vars

vars: RoomVars & object

Declared custom vars (same vocabulary as roomVars). A root vehicle with a signed detach protocol also carries vDetachBits: a server-owned uint16 whose permanent bits identify parts that have detached. Clients only read this value; detached-child expiry never clears it.

Type Declaration

vDetachBits?

readonly optional vDetachBits?: number

vehicleSeats?

optional vehicleSeats?: Record<string, string>

Server-owned logical seat occupancy for the opt-in dynamic Universal Vehicle ABI. Older/static Worlds omit this map and retain authored vars.

velocity?

optional velocity?: Vec3

Physics state — present ONLY for a physics (dynamic-body) kind (networked-physics, plan Phase 0). A kinematic entity carries position only (these stay undefined; @colyseus/schema delta-encodes an unwritten field to ~0 bytes). Synced so a remote client extrapolates with the RIGHT velocities (research §2: without synced velocity, remote extrapolation pops) and reproduces orientation. Units: m/s (linear), rad/s (angular), unit quaternion.

EntityStateAckEntry

One entity's slot in an EntityStateAckMessage — compact short keys + a [x,y,z] tuple, mirroring EntityStateBatchEntry (the upload it answers).

Properties

e

e: string

Entity id (the state.entities map key).

lv?

optional lv?: [number, number, number]

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.

p

p: [number, number, number]

The room's authoritative anchored position [x, y, z], METERS — the host snaps its local sim to it.

q?

optional q?: [number, number, number, number]

Anchored orientation quaternion [x,y,z,w] — physics kinds only, so a reconciled body resets its spin. Omit for non-physics.

seq

seq: number

The last per-entity seq the room ACCEPTED for this entity — the host re-anchors/prunes through it.

EntityStateAckMessage

A2 owner-entity divergence ack (spec §9). Sent to ONE hosting client, BATCHED: one message per tick carries an entry for every entity this host uploaded whose position the gate rejected (mirrors the EntityStateBatch upload channel). The host re-anchors each entity's local sim to its anchor, so a sparse/throttled host stops being fenced by the gate — replacing the engine's prior conservative 0.83 × gate-reach guess with the room's actual accepted position.

Properties

acks

acks: EntityStateAckEntry[]

One entry per hosted entity whose upload the gate rejected this tick. Never empty (the room omits the message instead).

moduleId?

optional moduleId?: string

Module provenance for every local entity id in acks; absent means world entities.

EntityStateBatchEntry

One entity's slot in an EntityStateBatchMessage. Compact, short keys (sent verbatim in msgpack), with position as a 3-tuple instead of a {x,y,z} object — the same authoritative meaning as EntityStateMessage's per-entity fields. v/ep are omitted when unchanged/unobserved to keep the batch small.

Properties

av?

optional av?: [number, number, number]

Angular velocity [x,y,z], rad/s — physics kinds only. Omit when unchanged/non-physics.

e

e: string

Entity id (the state.entities map key). Rejected unless the sender is its controller.

ep?

optional ep?: number

Authority epoch this entity is simulated under (mirror its synced authorityEpoch). Omit before observed.

lv?

optional lv?: [number, number, number]

Linear velocity [x,y,z], m/s — physics kinds only; magnitude-clamped to the gate on ingest. Omit when unchanged/non-physics.

p

p: [number, number, number]

World position as [x, y, z], METERS — gated against the kind's declared maxSpeed.

q?

optional q?: [number, number, number, number]

Orientation quaternion [x,y,z,w] — physics kinds only; normalized (zero/non-finite → identity) on ingest. Omit when unchanged/non-physics.

transactionId?

optional transactionId?: string

v?

optional v?: Record<string, RoomVarValue>

Declared per-kind vars to set (clamped to declared type/bounds on ingest). Omit when unchanged this tick.

EntityStateBatchMessage

A batch of owner-authoritative entity uploads (Tier 2 Phase 4.10, spec §10.4) — every entity this connection hosts, in ONE message. The per-connection rate cap (MESSAGE_RATE.entityStateHz) counts messages, so batching lets a host refresh many entities per tick within one token instead of spending one token per entity. The room applies each entry exactly like a single EntityStateMessage (ownership + epoch + maxSpeed gate + var clamp).

Properties

finalRest?

optional finalRest?: object

group

group: string

requestId

requestId: number

scope?

optional scope?: FinalRestProvenance

transactionId

transactionId: string

version

version: 1

moduleId?

optional moduleId?: string

Optional module provenance shared by every local entity id in this batch.

seq

seq: number

Monotonic per-connection batch sequence; the room ignores a stale/out-of-order batch per entity (gate seq).

states

states: EntityStateBatchEntry[]

One entry per hosted entity changed this tick (bounded by the room's per-owner entity cap).

tMs?

optional tMs?: number

Sender send-time (the host's monotonic performance.now() ms when it sampled this batch) — ONE per batch (all entries are sampled the same frame); the server sanitizes it into each entity's synced posT. Optional.

EntityStateMessage

An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c, spec §9/§10.4). The client that the server marked as the entity's controller (see EntityState.controller) simulates the entity and uploads its transform + declared vars; the room sanity-validates (it owns this entity? movement within its declared maxSpeed? vars within their declared bounds?) and relays. Cross-player consequences still go through server-validated rules/actions — never this channel (the publish-time firewall enforces that).

Properties

angularVelocity?

optional angularVelocity?: Vec3

entity

entity: string

The entity id this upload is for (the state.entities map key). Rejected unless the sender is its controller.

epoch?

optional epoch?: number

The authority EPOCH the client is simulating under (Tier 2 Phase 4.5.12, spec §9). Mirror the entity's synced authorityEpoch; the room bumps it on every controller handoff (host migration AND voluntary ownership transfer) and rejects an upload whose epoch ≠ the entity's current one — fencing a revoked/stale authority era even from a still-connected prior owner whose sessionId would otherwise pass. Omit only for the very first frame before the field is observed; the room tolerates absence (sessionId ownership still gates).

moduleId?

optional moduleId?: string

Optional module provenance; when present, entity is local to this module instance.

orientation?

optional orientation?: Quat

position

position: Vec3

The entity's world position, METERS — gated against the kind's declared maxSpeed.

seq

seq: number

Monotonic per-entity sequence; the room ignores a stale/out-of-order frame.

tMs?

optional tMs?: number

Sender send-time (the owner's monotonic performance.now() ms at upload) — the server SANITIZES it into the entity's synced posT for source-time interpolation, exactly like the player's StateMessage.tMs. Optional.

transactionId?

optional transactionId?: string

vars?

optional vars?: Record<string, RoomVarValue>

Declared per-kind vars to set (same vocabulary as roomVars); each is clamped to its declared type/bounds on ingest.

velocity?

optional velocity?: Vec3

Physics state — uploaded ONLY for a physics (dynamic-body) kind (networked-physics, plan Phase 0). velocity is gated against the kind's maxSpeed (magnitude-clamped on ingest, widened during a collision-grace window); orientation is normalized (zero/non-finite → identity). Synced so remotes extrapolate with the right velocity

reproduce spin (research §2). Omit for a kinematic kind.

FinalRestGrant

Properties

group

group: string

members

members: FinalRestMember[]

requestId

requestId: number

scope?

optional scope?: FinalRestProvenance

status

status: "claimed"

transactionId

transactionId: string

version

version: 1

FinalRestMember

Properties

angularVelocity

angularVelocity: Vec3

epoch

epoch: number

id

id: string

orientation

orientation: Quat

position

position: Vec3

velocity

velocity: Vec3

FinalRestProvenance

Explicit opt-in module address. The SDK supplies runtime generation and engagement authority.

Extends

FinalRestScope

Properties

engagementEpoch?

optional engagementEpoch?: number

generation

generation: number

moduleId

moduleId: string

Inherited from

FinalRestScope.moduleId

FinalRestScope

Explicit opt-in module address. The SDK supplies runtime generation and engagement authority.

Extended by

FinalRestProvenance

Properties

moduleId

moduleId: string

GestureEventMessage

The oneshot relay payload (v19), broadcast on ServerMessageType.Gesture to every client except the sender. Receivers resolve clip against their own world-registered set and no-op (with a warn) on an unknown name.

Properties

clip

clip: string

The registered clip name to play as a oneshot on that player's replica.

player

player: string

The gesturing player's playerKey (a state.players map key).

GestureMessage

Play/stop a gesture on the sender's own character (v19). The clip name is OPAQUE to the room — gesture registration is client-side world data (every client compiled the same clips from the same bundle), so the room validates only structurally (play enum, name bounds — GESTURE_LIMITS) and never against a declared set. Routing by play: 'oneshot' → relayed as a ServerMessageType.Gesture broadcast (except sender); 'loop'/'stop' → written to the sender's synced PlayerState.loopGesture (no relay — schema sync carries it).

Properties

clip

clip: string

Registered clip name; '' is legal only with play:'stop' (stop clears whatever loop is active, no name match required).

play

play: GesturePlay

GroupRestSnapshotEntity

One member of an authoritative group-rest transform snapshot.

Properties

angularVelocity?

optional angularVelocity?: Vec3

epoch?

optional epoch?: number

Present on explicit final commits; legacy snapshots retain their shape.

id

id: string

pos

pos: Vec3

rot

rot: Quat

velocity?

optional velocity?: Vec3

GroupRestSnapshotMessage

Broadcast once when a declared physics group transitions to fully at rest, and sent directly to late joiners while that settled snapshot remains current. seq is monotonic within group for the room's lifetime.

Properties

commit?

optional commit?: object

requestId

requestId: number

transactionId

transactionId: string

version

version: 1

entities

entities: GroupRestSnapshotEntity[]

group

group: string

scope?

optional scope?: FinalRestProvenance

seq

seq: number

HelixRoom

The curated live-room surface handed to world authors. Colyseus's API, re-exposed under Helix.*.

STALE HANDLES. A handle belongs to ONE room. Once that room is no longer the current one — you left it, hopped away with switchRoom, or it dropped for good — the handle is stale, and it can never act on whatever room came after it:

leave() resolves and does nothing (it never leaves the NEW room).
sendState, sendAction, uploadEntity, uploadEntities, requestModuleEngagement and acknowledge are no-ops; the boolean-returning senders (sendModuleAction, sendVehicle*Action, releaseModuleEngagement) return false. These all stamp SDK-owned state (the coalesced state slot, sequence counters, engagement epochs) that now belongs to the next room.
the plain pass-through senders — sendAbility, sendGesture, sendAttachments, sendAvatarRefresh, sendEmoteRefresh, sendEmoteJoin — keep their long-standing guarantee: handed to the handle's OWN (now closed) room, never a throw, never delivered to another room.
claimPhysicsGroup, commitPhysicsGroup and requestDistributionCapability reject (not_in_room).
every subscription (onMessage, onTicket, onStateChange, onAdd/onRemove, onStateAck, onEntityStateAck, onModule*, onPhysicsGroupRest, onPlayerAvatarChanged, onDrop, onReconnect) registers nothing and never fires; existing ones stopped firing at the hop.
onLeave fires once for the handle's own room; registered after that, it never fires.
pendingInputs() is empty and moduleEngagement() is null.
roomId, sessionId, roomType, instanceKey, effectiveUploadHz keep their values, and state, vars, me, player(), phase(), currentTurn(), isMyTurn(), module() keep reading the last state that room replicated — a frozen snapshot, never the new room's.

Properties

effectiveUploadHz

readonly effectiveUploadHz: number

The clamped player-seat upload cadence (Hz) this connection flushes at — multiplayer.uploadHz resolved to [10,20]. The engine paces its hosted-entity (EntityScene) uploads to the SAME value so both channels match.

instanceKey

readonly instanceKey: string | null

The ticketed room instance id (the credential's instanceKey), or null for default and open-type rooms.

me

readonly me: VarsView

roomId

readonly roomId: string

roomType

readonly roomType: string | null

The named room type this room is an instance of, or null for the world's default room. Read it after a reload: a plain joinRoom() RESUMES the room the tab was in, which may be a typed room (see joinRoom).

sessionId

readonly sessionId: string

state

readonly state: RoomState

Authoritative shared state (a @colyseus/schema instance shaped like the contract RoomState).

vars

readonly vars: VarsView

Guarded, live-reading views over the DECLARED game state — the typed replacement for hand-rolled (vars as Record<string, unknown>)?.x casts and frame-0 guards. vars = room-level, me/player(id) = per-player; phase/currentTurn/isMyTurn read the state machine + turn-order conventions.

Methods

acknowledge()

acknowledge(seq): void

Prune the reconciliation buffer once the server confirms it processed up to seq (D4).

Parameters

seq

number

Returns

void

claimPhysicsGroup()

claimPhysicsGroup(action, group, args?, scope?): Promise<FinalRestGrant>

Positive authorized claim; rejects on old servers. Await before applying one impulse.

Parameters

action

string

group

string

args?

Record<string, RoomVarValue>

scope?

FinalRestScope

Returns

Promise<FinalRestGrant>

commitPhysicsGroup()

commitPhysicsGroup(transactionId, states): Promise<GroupRestSnapshotMessage>

Exact complete stopped batch, epochs from claim; SDK supplies the normal physics sequence and retries frozen bytes.

Parameters

transactionId

string

states

readonly EntityStateBatchEntry[]

Returns

Promise<GroupRestSnapshotMessage>

currentTurn()

currentTurn(): string

Returns

string

isMyTurn()

isMyTurn(): boolean

Returns

boolean

leave()

leave(): Promise<void>

Leave intentionally (no reconnection grace held server-side).

Returns

Promise<void>

module()

module(moduleId): ModuleAccessors

Guarded, live module-local room/player/entity state.

Parameters

moduleId

string

Returns

ModuleAccessors

moduleEngagement()

moduleEngagement(moduleId): ModuleEngagementLease | null

Read-only snapshot of the current room grant, or null after denial/release/revocation/drop.

Parameters

moduleId

string

Returns

ModuleEngagementLease | null

onAdd()

Call Signature

onAdd(collection, cb): void

Subscribe to a collection's adds (Tier-2 seam: players today, entities reserved). Fires for existing entries too.

Parameters

collection

"players"

cb

(player, id) => void

Returns

void

Call Signature

onAdd(collection, cb): void

Parameters

collection

"entities"

cb

(entity, id) => void

Returns

void

onDrop()

onDrop(cb): void

Connection dropped; the client is auto-reconnecting (built into @colyseus/sdk).

Parameters

cb

() => void

Returns

void

onEntityStateAck()

onEntityStateAck(cb): void

A2 (spec §9) the room's owner-hosted-entity divergence correction, BATCHED — the engine re-anchors each hosted entity's local sim to its anchor so a sparse/throttled host stops being fenced by the gate.

Parameters

cb

(ack) => void

Returns

void

onLeave()

onLeave(cb): void

Left for good — code is the close code, reason says WHO ended it:

'switch' this client hopped away with Helix.multiplayer.switchRoom. Do NOT auto-rejoin from here: the hop is already joining the next room (a joinRoom() now is refused, switch-in-progress).
'leave' this client left on purpose (room.leave() / the shell's Exit).
'dropped' nobody here asked for it: kicked, the room disposed, or the connection was lost for good. Fires at most once per handle. reason is additive — a callback that only takes code is unaffected.

Parameters

cb

(code, reason) => void

Returns

void

onMessage()

onMessage<Payload>(type, cb): () => void

A world-authored server→client message (the room broadcasts these for declared events).

Type Parameters

Payload

Payload = unknown

Parameters

type

string

cb

(payload) => void

Returns

() => void

onModuleEffect()

onModuleEffect(cb): void

Observe namespaced transient presentation without subscribing to every authored event name.

Parameters

cb

(effect) => void

Returns

void

onModuleEngagement()

onModuleEngagement(cb): () => void

Observe exclusive module grants, denials, releases, and server/drop revocations.

Parameters

cb

(event) => void

Returns

() => void

onModuleFused()

onModuleFused(cb): void

Typed module runtime diagnostics.

Parameters

cb

(event) => void

Returns

void

onModuleSleep()

onModuleSleep(cb): void

Parameters

cb

(event) => void

Returns

void

onModuleState()

onModuleState(cb): void

Observe authoritative mounted-module snapshots, including late-join state.

Parameters

cb

(snapshot) => void

Returns

void

onModuleWake()

onModuleWake(cb): void

Parameters

cb

(event) => void

Returns

void

onPhysicsGroupRest()

onPhysicsGroupRest(group, callback, scope?): void

Subscribe to one group's authoritative rest, explicitly selecting module-local delivery when scoped.

Parameters

group

string

callback

(snapshot) => void

scope?

FinalRestScope

Returns

void

onPlayerAvatarChanged()

onPlayerAvatarChanged(cb): () => void

A seat's replicated avatar changed mid-session (v23 — the room re-resolved it after an avatarRefresh hint), so the engine can re-skin that replica without a rejoin. Fires per changed seat, never on join (read state.players[id].avatarUrl for the initial value). Returns an unsubscribe.

Parameters

cb

(playerId, avatarUrl) => void

Returns

() => void

onReconnect()

onReconnect(cb): void

Auto-reconnection succeeded.

Parameters

cb

() => void

Returns

void

onRemove()

Call Signature

onRemove(collection, cb): void

Parameters

collection

"players"

cb

(player, id) => void

Returns

void

Call Signature

onRemove(collection, cb): void

Parameters

collection

"entities"

cb

(entity, id) => void

Returns

void

onStateAck()

onStateAck(cb): void

A2 (spec §9) the room's player-seat divergence correction — fires when the movement gate REJECTED an upload, or proactively when a rule teleport/respawn re-anchored the seat (the accepted case is silent). The engine snaps the local body to position; the SDK has already adopted the ack's teleport epoch (v27), dropped its coalesced pending frame on an epoch change, and pruned its reconciliation buffer through seq before this fires. SINGLE-SLOT: assigning a second consumer silently replaces the first.

Parameters

cb

(ack) => void

Returns

void

onStateChange()

onStateChange(cb): () => void

Fires after every applied patch from the server.

Parameters

cb

(state) => void

Returns

() => void

onTicket()

onTicket(cb): () => void

The room handed THIS player a ticket to a ticketed room instance (helix:room-ticket, sent privately to each player an openRoom rule selected). Redeem it with Helix.multiplayer.switchRoom({ ticket: ticket.ticketId }). expiresAt arrives normalised to epoch milliseconds; a malformed ticket is dropped. Tickets are not replayed: subscribe right after joining. Returns an unsubscribe.

Parameters

cb

(ticket) => void

Returns

() => void

pendingInputs()

pendingInputs(): readonly StateMessage[]

Sent-but-unacknowledged states — the reconciliation tail the engine NetworkDriver replays (D4).

Returns

readonly StateMessage[]

phase()

phase(): string

Returns

string

player()

player(id): VarsView

Parameters

id

string

Returns

VehicleComponentActionRequest

releaseModuleEngagement()

releaseModuleEngagement(moduleId, action, args?): boolean

Release the current grant through a declared action. False means this SDK holds no live grant.

Parameters

moduleId

string

action

string

args?

Record<string, RoomVarValue>

Returns

boolean

requestDistributionCapability()

requestDistributionCapability(ref): Promise<DistributionCapabilityGrant>

Ask the room for a one-time World acquisition capability for one World route of THIS world (ADR-0003): dkey:<key> or distribution:<uuid>. The room mints it for the signed-in seat and answers only this client; pass the result's capability to the purchase. Rejects with an Error whose message is the room's reason (sign_in_required, not_found, unavailable, …) or timeout when the room never answers.

Parameters

ref

string

Returns

Promise<DistributionCapabilityGrant>

requestModuleEngagement()

requestModuleEngagement(moduleId, action, args?): void

Request the exclusive grant for a declared action on an engaged module.

Parameters

moduleId

string

action

string

args?

Record<string, RoomVarValue>

Returns

void

sendAbility()

sendAbility(ability, active): void

Activate/deactivate a built-in ability (sent immediately; server enforces the rate ceiling).

Parameters

ability

string

active

boolean

Returns

void

sendAction()

sendAction(name, args?, moduleId?): void

A declared action. When this SDK holds a room engagement for moduleId, it automatically stamps the matching authority epoch; authored code never supplies that epoch.

Parameters

name

string

args?

Record<string, RoomVarValue>

moduleId?

string

Returns

void

sendAttachments()

sendAttachments(attachments): void

Replace this player's ENTIRE replicated attachment set (v20). Full-set replace, idempotent — the room writes it to synced PlayerState.attachments (no relay; schema sync fans out, late joiners converge). Entries carry sender-resolved socket-local offsets and must respect ATTACHMENT_LIMITS; the engine facade (CharacterMultiplayer.attach/detach) drives this for you.

Parameters

attachments

AttachmentEntry[]

Returns

void

sendAvatarRefresh()

sendAvatarRefresh(): void

Ask the room to re-resolve THIS player's avatar (v23) — a hint with an empty payload: the room re-reads the equipped avatar server-side and rewrites the seat's PlayerState.avatarUrl, so a client never names the URL.

Returns

void

sendEmoteJoin()

sendEmoteJoin(initiator): void

Join initiator's paired emote, or leave the current pair with '' (v28). A REQUEST the room may refuse by writing nothing — read the outcome off THIS player's state.pairInitiator, never off the send. The engine facade drives this for you; the room owns every clear (the initiator stops, either side dies, you drift off).

Parameters

initiator

string

Returns

void

sendEmoteRefresh()

sendEmoteRefresh(): void

Ask the room to re-resolve THIS player's carried emote set (v28) — the avatar hint's twin: an empty payload, because the room re-reads the equipped emotes server-side and replaces the seat's PlayerState.emotes whole, so a client never names a clip URL that lands on its own seat.

Returns

void

sendGesture()

sendGesture(clip, play): void

Play/stop a gesture on this player (v19). 'oneshot' relays to every OTHER client as a gesture broadcast (play locally first — the room never echoes it back); 'loop'/'stop' set/clear the seat's synced PlayerState.loopGesture so late joiners see active loops. clip is a world-registered gesture name ('' only with 'stop'); the engine facade (CharacterMultiplayer.playAnimation) drives this for you.

Parameters

clip

string

play

GesturePlay

Returns

void

sendModuleAction()

sendModuleAction(request): boolean

Send one identity-fenced action through the existing declared action channel.

Parameters

request

ModuleActionRequest

Returns

boolean

sendState()

sendState(input): void

Per-tick predicted state. Coalesced + flushed at MESSAGE_RATE.stateHz, seq-tagged (D3/D4).

Parameters

input

ReplicaInput

Returns

void

sendVehicleComponentAction()

sendVehicleComponentAction(request): boolean

Send one named vehicle component/panel intent through the existing action channel. false is a fail-closed refusal: nothing was sent and no sequence was advanced because identity/entity state was incomplete, the socket was closed, the sequence was exhausted, or reconnect-safe persistence failed. The caller may retry after authoritative state, transport, or storage recovers. true means submitted, not server-accepted; observe replicated state for confirmation. No caller-provided Build digest, epoch, or sequence is accepted.

Parameters

request

Returns

boolean

sendVehicleDetachAction()

sendVehicleDetachAction(request): boolean

Send one trusted detachable-part action on the same vehicle action lane. The request carries only the admitted action id and placement identity; the SDK stamps the live Build, authority epoch, and durable sequence. The wire deliberately has no targetBits because detachment spawns a separate authoritative entity instead of mutating the component bitfield.

Parameters

request

VehicleDetachActionRequest

Returns

boolean

uploadEntities()

uploadEntities(entities, moduleId?): void

Upload MANY owner-authoritative entities in ONE message (Tier 2 Phase 4.10). Prefer this over per-entity uploadEntity when hosting multiple entities: the per-connection rate cap counts messages, so N single uploads spend N tokens/tick and starve, while one batch spends one. Position is sent as a compact [x,y,z] tuple; each entry is gated/clamped server-side exactly like uploadEntity. Pass only entities this client controls.

Parameters

entities

readonly object[]

moduleId?

string

Returns

void

uploadEntity()

uploadEntity(entityId, input, moduleId?): void

Upload an owner-authoritative entity's client-simulated state (Tier 2 Phase 4.6c). Call only for an entity whose controller is this client (state.entities[id].controller === sessionId); the room rejects others. Sent immediately, per-entity seq-tagged; the room gates the position against the kind's maxSpeed + clamps vars.

Parameters

entityId

string

input

angularVelocity?

Vec3

epoch?

number

orientation?

Quat

position

Vec3

vars?

Record<string, RoomVarValue>

velocity?

Vec3

moduleId?

string

Returns

void

HelixVoiceAudioFeatures

Fixed-size, receiver-local speech features. These are derived from a subscribed playback track, never serialized, and intentionally contain no recoverable PCM or arbitrary channel data.

Properties

bands

bands: readonly [number, number, number, number, number]

Mean spectral energy in fixed speech bands: <350, 350-700, 700-1400, 1400-2800, 2800-5600 Hz.

rms

rms: number

Root-mean-square energy, normalized to 0..1.

zeroCrossingRate

zeroCrossingRate: number

Time-domain zero-crossing rate, normalized to 0..1.

InputLeaseHandle

Properties

enforced

readonly enforced: boolean

epoch

readonly epoch: number

Methods

release()

release(): void

Returns

void

InputLeaseRequest

Properties

actions

readonly actions: readonly StandardModeAction[]

ownerToken

readonly ownerToken: object

InteractionMode

Type Parameters

R

R = unknown

Properties

camera?

readonly optional camera?: CameraIntent

id

readonly id: string

input?

readonly optional input?: InputMap

suppress

readonly suppress: Suppression

updateWhileCovered?

readonly optional updateWhileCovered?: boolean

Covered modes do not tick unless they explicitly opt in. They never regain input.

Methods

enter()

enter(ctx): void | Promise<void>

Parameters

ctx

Returns

void | Promise<void>

exit()

exit(ctx): void | Promise<void>

Parameters

ctx

Returns

void | Promise<void>

onCovered()?

optional onCovered(ctx): void

Parameters

ctx

Returns

void

onRevealed()?

optional onRevealed(ctx): void

Parameters

ctx

Returns

void

update()?

optional update(dtSeconds, ctx): void

Parameters

dtSeconds

number

ctx

Returns

void

JoinRoomOptions

Options for joinRoom — only needed where the API base can't be derived from the token (local dev/tests).

Properties

apiBaseUrl?

optional apiBaseUrl?: string

Override the platform API base URL. Default: the world_session token's iss, else configure({ apiBaseUrl }).

reservationPath?

optional reservationPath?: string

Same-origin platform reservation route for a runtime that shares the HELIX room plane without being an InstantWorld row (for example a Home). Must be an absolute /api/v1/... path; cross-origin URLs are rejected so the world_session bearer can never be exfiltrated.

roomType?

optional roomType?: string

Join an OPEN named room type declared in the world's manifest (multiplayer.roomTypes.<name>) instead of the default room. Sent as the join request's JSON body ({ "roomType": "<name>" }); the backend answers 404 unknown-room-type for an undeclared name and 403 ticket-required for a ticketed type, both surfaced as a HelixRoomJoinError. Omit it (and ticket) for the default room — that request carries NO body and is byte-identical to what every earlier SDK sent.

A shell-provided ?instance= does NOT apply to a typed join: it names a room of the DEFAULT type, so a typed join ignores it entirely (no strict joinById, no helix:multiplayer-join-error).

ticket?

optional ticket?: string

Redeem a ticket to a ticketed room instance (delivered by room.onTicket). Sent as { "ticket": "<id>" }. Single-use and bound to the account it was issued to — an unknown, expired, already-used or foreign ticket is a HelixRoomJoinError with code ticket-invalid. Mutually exclusive with roomType (the ticket already names its type); passing both is refused before any request. Like roomType, it ignores ?instance=. Most worlds hop with Helix.multiplayer.switchRoom({ ticket }) rather than calling this directly.

uploadHz?

optional uploadHz?: number

State upload cadence (Hz) for the player-seat flush — from the world's multiplayer.uploadHz. Clamped to [MESSAGE_RATE.stateHz, MESSAGE_RATE.maxUploadHz] (10..20); absent ⇒ the 10 Hz default. The room derives its own ceiling from the trusted configUrl, so a lying client only throttles itself.

JoinVoiceOptions

Properties

apiBaseUrl?

optional apiBaseUrl?: string

Override the platform API base URL (same semantics as JoinRoomOptions.apiBaseUrl).

channel?

optional channel?: string

Initial exclusive voice channel (equivalent to calling setChannel before join).

pttKey?

optional pttKey?: string

Push-to-talk key (KeyboardEvent.key, compared lowercase). Default 'n', matching FiveM's standard push-to-talk control while B remains available for character pointing.

roomId?

optional roomId?: string

Override the paired Colyseus room id. Default: the currently joined multiplayer room.

tokenPath?

optional tokenPath?: string

Same-origin reservation adapter route for a non-World runtime.

ModeContext

Type Parameters

R

R = unknown

Properties

aborted

readonly aborted: boolean

covered

readonly covered: boolean

live

readonly live: boolean

params

readonly params: Record<string, unknown>

Methods

clearDiag()

clearDiag(...keys): void

Parameters

keys

...string[]

Returns

void

diag()

diag(patch): void

Parameters

patch

Record<string, unknown>

Returns

void

emit()

emit(event, payload?): void

Parameters

event

string

payload?

unknown

Returns

void

isVerbActive()

isVerbActive(verb): boolean

Parameters

verb

string

Returns

boolean

onVerb()

onVerb(verb, handler): () => void

Parameters

verb

string

handler

VerbHandler

Returns

() => void

release()

release(result?): void

Parameters

result?

R

Returns

void

setCamera()

setCamera(intent): void

Parameters

intent

CameraIntent | null

Returns

void

setInput()

setInput(input): void

Parameters

input

InputMap | null

Returns

void

ModeHost

Methods

applyCamera()

applyCamera(intent): void

Parameters

intent

CameraIntent | null

Returns

void

onError()?

optional onError(error, modeId, phase): void

Parameters

error

unknown

modeId

string

phase

ModePhase

Returns

void

onModeEvent()?

optional onModeEvent(modeId, event, payload): void

Parameters

modeId

string

event

string

payload

unknown

Returns

void

reportDiag()

reportDiag(modeId, patch): void

Parameters

modeId

string

patch

Record<string, unknown>

Returns

void

setSuppression()

setSuppression(effective): void

Parameters

effective

Required<Suppression>

Returns

void

setVerbs()

setVerbs(input, dispatch): void

Parameters

input

InputMap | null

dispatch

VerbSink | null

Returns

void

ModeResult

Type Parameters

R

R = unknown

Properties

aborted

aborted: boolean

error?

optional error?: unknown

reason

reason: ModeEndReason

value?

optional value?: R

ModuleAccessors

Properties

me

me: VarsView

This client's module-local player vars.

moduleId

readonly moduleId: string

vars

vars: VarsView

Module-local room vars.

Methods

entity()

entity(id): VarsView

One module-local entity's declared vars.

Parameters

id

string

Returns

phase()

phase(): string

Module-local state-machine phase.

Returns

string

player()

player(id): VarsView

Another player's module-local vars.

Parameters

id

string

Returns

PlayerReplicaState.activeAbilities

timerDeadline()

timerDeadline(name, key?): number

Absolute module-local timer deadline, or 0 while absent/sleeping.

Parameters

name

string

key?

string

Returns

number

ModuleActionRequest

Properties

action

action: string

args?

optional args?: Record<string, string | number | boolean>

engagement?

optional engagement?: "acquire" | "release"

identity

identity: ModuleIdentity

ModuleEffect

Properties

commandId

commandId: string

event

event: string

index

index: number

moduleId

moduleId: string

payload

payload: Readonly<Record<string, unknown>>

serverTick

serverTick: number

ModuleEffectMessage

Properties

commandId

commandId: string

event

event: string

index

index: number

moduleId

moduleId: string

payload

payload: Record<string, RoomVarValue>

serverTick

serverTick: number

ModuleEngagementMessage

Direct room response for one engaged-module authority transition. Grants are exclusive and carry the epoch the SDK must stamp on later verbs. Denials intentionally expose no competing holder.

Properties

action

action: string

epoch?

optional epoch?: number

Present for granted/released/revoked transitions; absent on denial.

moduleId

moduleId: string

requestId?

optional requestId?: number

Echoed for acquire/release responses; absent on an unsolicited server revocation.

status

status: ModuleEngagementStatus

ModuleFusedMessage

Properties

moduleId

moduleId: string

serverTick

serverTick: number

tickNodes

tickNodes: number

ModuleIdentity

Properties

bundleChecksumSha256

bundleChecksumSha256: string

itemInstanceId?

optional itemInstanceId?: string

Required for legacy/static owned-item modules; omitted for trusted live-placement modules.

moduleId

moduleId: string

revision

revision: number

ModuleSleepMessage

Properties

moduleId

moduleId: string

serverTick

serverTick: number

ModuleState

One synchronized module-instance chunk group. Local ids are meaningful only together with its module id.

Properties

entities

entities: Record<string, EntityState>

phase

phase: string

phaseStartTick

phaseStartTick: number

players

players: Record<string, { vars: RoomVars; }>

roomVars

roomVars: RoomVars

timerDeadlines

timerDeadlines: Record<string, number>

ModuleStateSnapshot

Properties

moduleId

moduleId: string

phase

phase: string

revision

revision: number

roomVars

roomVars: Readonly<Record<string, unknown>>

serverTick

serverTick: number

ModuleWakeMessage

Properties

moduleId

moduleId: string

reason

reason: ModuleWakeReason

serverTick

serverTick: number

PackageCustomizerContext

Properties

source

readonly source: Readonly<{ hostId: string; itemId: string; kind: "trial"; }> | null

subject

readonly subject: PackageCustomizerSubject | null

PingMessage

Clock-sync probe. The client sends its local send time; the room replies (Pong) with this value echoed plus its own clock, so the client estimates RTT (recv − send) and offset (serverTimeMs − send − RTT/2).

Properties

clientTimeMs

clientTimeMs: number

The client's local clock (epoch ms) at send — echoed verbatim in the Pong.

PlayerIdentity

Stable per-player identity (set at join from the room credential; not part of the per-tick churn).

Extended by

PlayerState

Properties

avatarUrl

avatarUrl: string

CDN URL of this player's equipped universal avatar (a converted single-file GLB on the helix-humanoid rig), or '' when they have none — clients render the default body on ''. Resolved and skeleton-gated SERVER-SIDE at join (backend → signed credential → room), never client-supplied — and it is item-keyed public catalog data, NOT the userId (which stays server-side, §4). Fixed for the seat's lifetime: equip changes apply on the next join. (v17)

displayName

displayName: string

Sanitized display name for nameplates (sanitized before it enters room state — see plan H4).

id

id: string

Opaque per-connection room playerKey (= the state.players map key). Gameplay state is keyed by THIS, never by userId.

userId

userId: string

The player's PLATFORM user id (the credential sub), so a roster UI can link a seat to a real profile (batch /api/v1/users lookup, profile drill-in). v18 deliberately supersedes the original §4 stance that sub never replicates: user ids are already public directory data on the platform, so room-mates learn nothing new. Copied once at join from the verified credential, never client-supplied. '' when the room predates v18. Gameplay state stays keyed by the opaque per-connection id.

PlayerReplicaState

The per-tick replicated kinematic + animation parameters for one player. The room holds the authoritative copy (a @colyseus/schema mirror of these fields); the NetworkDriver maps each field onto the named character blackboard param. FIRST DRAFT — the exact injected set is confirmed by spike S2 (engine headless-replica write-path); changing the field set bumps CONTRACT_VERSION.

Extended by

PlayerState

Properties

activeAbilities

activeAbilities: string[]

Ability ids currently active (e.g. ['locomotion','fly']). Drives remote ability activation.

aiming?

optional aiming?: boolean

ADS intent, not an aim fraction — replicas ease locally with the same time constant.

aimPitchDeg

aimPitchDeg: number

Aim pitch, DEGREES. → blackboard 'cameraPitch' (aim-additive source).

aimYawDeg

aimYawDeg: number

Aim yaw, DEGREES (world). → blackboard 'cameraYaw' (aim-additive source).

attachments

attachments: AttachmentEntry[]

The props currently attached to this player (v20). Attachments are persistent, so they sync as STATE — a late joiner converges at replica spawn — never as events. Written whole by the attachments full-set replace message; bounded by ATTACHMENT_LIMITS.maxAttachments; [] when none (or the room predates v20).

crouched

crouched: boolean

Crouch stance. → routes the locomotion anim graph to its crouched states.

emotes?

optional emotes?: EmoteEntry[]

The emote set this player CARRIES (v28) — resolved SERVER-SIDE from their equipped items at join and on the emoteRefresh hint, exactly like avatarUrl (v17): a client can never name the clip URLs that land on its own seat, so this is NOT the client-written attachments lane despite the matching array shape. Emotes are persistent → they sync as STATE, so a late joiner converges at replica spawn. Bounded by EMOTE_LIMITS.maxEntries; absent/[] when the player carries none, the world disabled emotes, or the room predates v28.

facingYawDeg

facingYawDeg: number

Body facing, DEGREES. The adapter converts to radians for body.setFacingYaw.

grounded

grounded: boolean

Ground contact. → blackboard 'isGrounded' (grounded/air transitions).

gunDrawn?

optional gunDrawn?: boolean

Weapon drawn (vs holstered).

locomotionPack?

optional locomotionPack?: string

The locomotion clip set this player MOVES on (v34), as ONE servable pack-manifest base URL — resolved SERVER-SIDE from their equipped locomotion pack at join and on the avatarRefresh hint, exactly like avatarUrl (v17): a client can never name the pack that lands on its own seat. A pack is persistent → it syncs as STATE, so a late joiner sees the right walk at replica spawn instead of a corrected one. '' or absent = the platform locomotion set, which is also what a room predating v34 replicates.

lookTarget

lookTarget: Vec3

Interaction gaze point, world METERS (beats replicated aim-follow gaze). Meaningful only while lookTargetActive.

lookTargetActive

lookTargetActive: boolean

loopGesture

loopGesture: string

The world-registered LOOPING gesture clip this player currently plays, '' when none (v19). Loops replicate as STATE — not events — so a late joiner starts them at replica spawn; oneshot gestures ride the transient gesture broadcast instead. The name is opaque world data: every client registered the same clips from the same bundle (registerAnimation), so only the name crosses the wire; an unknown name renders as no gesture.

moveDirectionDeg

moveDirectionDeg: number

Signed movement direction relative to facing, DEGREES (−180..180). → blackboard 'direction'.

pairInitiator

pairInitiator: string

PAIRED emotes (v28) — the pair this player JOINED, and never the one they offer: the initiator's own seat carries nothing (their offering is derivable — their loopGesture is emote.<slot> and that slot's entry has roles). ROOM-WRITTEN ONLY, like avatarUrl/emotes and unlike every other field here: the emoteJoin message is a request the room validates (liveness, range, the initiator actually offering and not already paired — a pair is strictly 1:1) and answers by writing — or by writing nothing — so a client can never seat itself in someone else's emote. The room also owns every clear (the initiator stops/changes/teleports/leaves/dies, the joiner dies or drifts away).

'' = not paired; otherwise the INITIATOR's player id (the players map key, the id-space activeAbilities and every other ref use).

pairSlot

pairSlot: string

The initiator's slot being joined ('r0'..'r7'), so replicas read the roles off the right entry. '' = none.

pairStartMs

pairStartMs: number

Room clock (epoch ms, the {op:now} source) at pair creation, so replicas can phase-align. 0 = none.

position

position: Vec3

World feet position, METERS. Interpolated by the remote replica.

ragdolled

ragdolled: boolean

Physics owns this player's body (v25) — the death ragdoll, or a world's manual character.ragdoll.enter(). Client-authoritative cosmetic state like crouched: replicas mirror it into their OWN ragdoll driver, so a late joiner sees a limp player through STATE, not a missed event.

ragdollLaunchX

ragdollLaunchX: number

The shove this ragdoll STARTED with (v26): unit horizontal direction × speed (m/s); all 0 when the body just crumpled. Held stable while ragdolled is true so a replica that observes the false→true EDGE re-creates the entry impulse on its own corpse. A late joiner reads state (not the edge) and must NOT re-apply it — the sender's followed position already encodes where the flight ended.

ragdollLaunchZ

ragdollLaunchZ: number

ragdollSpeedMps

ragdollSpeedMps: number

reachLeft

reachLeft: Vec3

Left-hand reach target, world METERS. Meaningful only while reachLeftActive.

reachLeftActive

reachLeftActive: boolean

Live IK reach state (v21) — the WORLD-SPACE point each hand's procedural arm IK is holding (ik.reach: door handles, buttons, levers) and the interaction gaze point (ik.lookAt). Continuous per-tick data like position/aim, ridden in on the state upload (omitted field = inactive). Replicas feed the points into their OWN local solvers — no bone transforms ever cross the wire. When an *Active flag is false the paired vector just holds its last value (unwritten fields delta-encode to ~0 bytes) — always check the flag first. False/zero when the room predates v21.

reachRight

reachRight: Vec3

Right-hand reach target, world METERS. Meaningful only while reachRightActive.

reachRightActive

reachRightActive: boolean

reloading?

optional reloading?: boolean

Reload in progress (wire-timed on replicas).

shotSeq?

optional shotSeq?: number

Gun state (v24) — weapon SIGNALS, not motion: replicas re-run the same local easing/FX off these fields. Absent when the sender carries no gun-control ability (or the room predates v24).

shotSeq is a monotonic per-session shot counter, +1 per real shot. It is coalesced latest-wins at 10/20 Hz, so consumers react to the DELTA (never assume +1); it restarts at 0 on reconnect, and a non-positive delta means re-anchor (never replay).

speed

speed: number

Horizontal planar speed, M/S. → blackboard 'speed' (blend-space input).

verticalVelocity

verticalVelocity: number

Vertical velocity, M/S (+up). → blackboard 'verticalVelocity' (jump/fall states).

PlayerState

Full authoritative per-player state: the FIXED character contract + identity + DECLARED game vars.

Extends

PlayerIdentity.PlayerReplicaState

Properties

active

active: boolean

Participation (Tier 2 P3-B2 elimination): false when this still-connected player has been removed from the ACTIVE set mid-match (eliminated / benched / a spectator). An inactive seat is excluded from the same gameplay reductions + spatial detection a disconnected seat is (forEachPlayer / playerCount / aggregate players / nearestPlayer / zone + contact), but it stays connected and keeps rendering, and broadcast still reaches it (so it can spectate). The room sets it via the eliminate/revive effects; defaults true. Clients may read it to render spectators (e.g. greyed out). (Distinct from connected, which is presence/reconnection-grace.)

activeAbilities

activeAbilities: string[]

Ability ids currently active (e.g. ['locomotion','fly']). Drives remote ability activation.

Inherited from

aiming?

optional aiming?: boolean

ADS intent, not an aim fraction — replicas ease locally with the same time constant.

Inherited from

PlayerReplicaState.aiming

aimPitchDeg

aimPitchDeg: number

Aim pitch, DEGREES. → blackboard 'cameraPitch' (aim-additive source).

Inherited from

PlayerReplicaState.aimPitchDeg

aimYawDeg

aimYawDeg: number

Aim yaw, DEGREES (world). → blackboard 'cameraYaw' (aim-additive source).

Inherited from

PlayerReplicaState.aimYawDeg

attachments

attachments: AttachmentEntry[]

Inherited from

PlayerReplicaState.attachments

avatarRevision

avatarRevision: number

Server-owned monotonic avatar refresh revision (v33). The room increments this after each successful authoritative equipped-avatar read, including when the base GLB URL is unchanged but its composition changed. Older rooms omit the field; clients treat an absent value as 0.

avatarUrl

avatarUrl: string

Inherited from

PlayerIdentity.avatarUrl

connected

connected: boolean

Presence (Tier 2 Phase 3, spec §8): false while this seat sits in the reconnection grace window after an unexpected drop — the seat (and its refs) persists, but the server excludes it from reductions. The seat is removed (an onRemove('players')) only at grace expiry; until then the engine should render the replica idle. This layers on Colyseus's own reconnection — it annotates the seat, it does not drive the reconnect handshake.

crouched

crouched: boolean

Crouch stance. → routes the locomotion anim graph to its crouched states.

Inherited from

PlayerReplicaState.crouched

displayName

displayName: string

Sanitized display name for nameplates (sanitized before it enters room state — see plan H4).

Inherited from

PlayerIdentity.displayName

emotes?

optional emotes?: EmoteEntry[]

Inherited from

PlayerReplicaState.emotes

facingYawDeg

facingYawDeg: number

Body facing, DEGREES. The adapter converts to radians for body.setFacingYaw.

Inherited from

PlayerReplicaState.facingYawDeg

grounded

grounded: boolean

Ground contact. → blackboard 'isGrounded' (grounded/air transitions).

Inherited from

PlayerReplicaState.grounded

gunDrawn?

optional gunDrawn?: boolean

Weapon drawn (vs holstered).

Inherited from

PlayerReplicaState.gunDrawn

id

id: string

Opaque per-connection room playerKey (= the state.players map key). Gameplay state is keyed by THIS, never by userId.

Inherited from

PlayerIdentity.id

locomotionPack?

optional locomotionPack?: string

Inherited from

PlayerReplicaState.locomotionPack

lookTarget

lookTarget: Vec3

Interaction gaze point, world METERS (beats replicated aim-follow gaze). Meaningful only while lookTargetActive.

Inherited from

PlayerReplicaState.lookTarget

lookTargetActive

lookTargetActive: boolean

Inherited from

PlayerReplicaState.lookTargetActive

loopGesture

loopGesture: string

Inherited from

PlayerReplicaState.loopGesture

moveDirectionDeg

moveDirectionDeg: number

Signed movement direction relative to facing, DEGREES (−180..180). → blackboard 'direction'.

Inherited from

PlayerReplicaState.moveDirectionDeg

pairInitiator

pairInitiator: string

'' = not paired; otherwise the INITIATOR's player id (the players map key, the id-space activeAbilities and every other ref use).

Inherited from

PlayerReplicaState.pairInitiator

pairSlot

pairSlot: string

The initiator's slot being joined ('r0'..'r7'), so replicas read the roles off the right entry. '' = none.

Inherited from

PlayerReplicaState.pairSlot

pairStartMs

pairStartMs: number

Room clock (epoch ms, the {op:now} source) at pair creation, so replicas can phase-align. 0 = none.

Inherited from

PlayerReplicaState.pairStartMs

position

position: Vec3

World feet position, METERS. Interpolated by the remote replica.

Inherited from

PlayerReplicaState.position

posT

posT: number

Source-time stamp (ms) of this seat's current position — the SANITIZED sender send-time (StateMessage.tMs), or the server's apply-clock when the upload carried none. Clients SPACE interpolation keyframes by posT deltas instead of local arrival time, so jitter in DELIVERY (network + 20 Hz-tick aliasing) stops becoming jitter in rendered MOTION. Monotonic per seat; only deltas are meaningful (origin = the sender's arbitrary clock base).

ragdolled

ragdolled: boolean

Inherited from

PlayerReplicaState.ragdolled

ragdollLaunchX

ragdollLaunchX: number

Inherited from

PlayerReplicaState.ragdollLaunchX

ragdollLaunchZ

ragdollLaunchZ: number

Inherited from

PlayerReplicaState.ragdollLaunchZ

ragdollSpeedMps

ragdollSpeedMps: number

Inherited from

PlayerReplicaState.ragdollSpeedMps

reachLeft

reachLeft: Vec3

Left-hand reach target, world METERS. Meaningful only while reachLeftActive.

Inherited from

PlayerReplicaState.reachLeft

reachLeftActive

reachLeftActive: boolean

Inherited from

PlayerReplicaState.reachLeftActive

reachRight

reachRight: Vec3

Right-hand reach target, world METERS. Meaningful only while reachRightActive.

Inherited from

PlayerReplicaState.reachRight

reachRightActive

reachRightActive: boolean

Inherited from

PlayerReplicaState.reachRightActive

reloading?

optional reloading?: boolean

Reload in progress (wire-timed on replicas).

Inherited from

PlayerReplicaState.reloading

shotSeq?

optional shotSeq?: number

Gun state (v24) — weapon SIGNALS, not motion: replicas re-run the same local easing/FX off these fields. Absent when the sender carries no gun-control ability (or the room predates v24).

Inherited from

PlayerReplicaState.shotSeq

speed

speed: number

Horizontal planar speed, M/S. → blackboard 'speed' (blend-space input).

Inherited from

PlayerReplicaState.speed

userId

userId: string

Inherited from

PlayerIdentity.userId

vars

vars: RoomVars

Declared per-player game state (e.g. team, health, score). Same vocabulary as roomVars; declared per-world.

verticalVelocity

verticalVelocity: number

Vertical velocity, M/S (+up). → blackboard 'verticalVelocity' (jump/fall states).

Inherited from

PlayerReplicaState.verticalVelocity

PongMessage

Reply to a Ping — the echoed client time + the server's clock at reply, for offset/RTT estimation.

Properties

clientTimeMs

clientTimeMs: number

finalRestModules?

optional finalRestModules?: Record<string, number>

finalRestVersion?

optional finalRestVersion?: 1

moduleFinalRestVersion?

optional moduleFinalRestVersion?: 1

serverTimeMs

serverTimeMs: number

PurchaseReceiptMessage

Forward a settled purchase's backend-minted receipt to the room (v22). The SDK treats the JWT as OPAQUE — it never parses it — and the room owns every runtime check: signature, audience (helix-purchase-receipt), worldId, and that the claimed sub is the sender's own seat. Re-forwarding is safe (the room dedupes by purchaseId), so a repeated getPurchase poll can send the same receipt again.

Properties

receipt

receipt: string

PushOptions

Type Parameters

R

R = unknown

Methods

onEvent()?

optional onEvent(event, payload): void

Parameters

event

string

payload

unknown

Returns

void

onResult()?

optional onResult(result): void

Parameters

result

ModeResult<R>

Returns

void

PushOutcome

Type Parameters

R

R = unknown

Properties

done

done: Promise<ModeResult<R>>

Always settles, including when a push is rejected.

error?

optional error?: unknown

ok

ok: boolean

RoomAccessors

Properties

me

me: VarsView

MY declared player vars — a live view over players[sessionId].vars.

vars

vars: VarsView

Declared room-level vars (multiplayer.state.roomVars).

Methods

currentTurn()

currentTurn(): string

The session id whose turn it is, off the turnOrder/turnIndex roomVars convention ('' when unused).

Returns

string

isMyTurn()

isMyTurn(): boolean

Whether it's THIS client's turn (the turn-order convention; always false when unused).

Returns

boolean

module()

module(moduleId): ModuleAccessors

Live, guarded access to one module instance. Local ids never escape this provenance boundary.

Parameters

moduleId

string

Returns

ModuleAccessors

phase()

phase(): string

The room state machine's current phase ('' when the world declares no states).

Returns

string

player()

player(id): VarsView

Any player's declared vars by session id (safe for ids not yet/no longer present).

Parameters

id

string

Returns

DeviceDefinitionReference

RoomCredentialClaims

Claims the backend signs (HS384) and the room verifies. Mirrors the world_session claim shape (sub/displayName/worldId/scopes/jti) plus the immutable buildId the room loads its config from.

Properties

aud

aud: "helix-instant-room"

Always ROOM_CREDENTIAL_AUDIENCE.

avatarUrl?

optional avatarUrl?: string | null

CDN URL of the user's equipped universal avatar, absent/null when they have none. The backend only mints it when the avatar's web asset is stamped skeleton: 'helix-humanoid' AND has a usable glbUrl — so a present claim is loadable by definition. The room copies it into PlayerState.avatarUrl (the ONLY identity-derived claim replicated besides displayName; sub never is). (v17)

baseBuildId?

optional baseBuildId?: string

Active published Build UUID used to resolve the fleet snapshot. Absent for Home and legacy credentials.

buildId

buildId: string

Immutable build the room loads its declarative config (allowed messages, room-var shape) from.

buildNumber

buildNumber: number

Monotonic per-world build counter (1, 2, 3 …) of the active build — telemetry + config cache key.

configUrl

configUrl: string

Signed URL of this build's multiplayer.json — the validated declarative config baked into the published bundle. Derived server-side from the build, NEVER client-supplied, so the room fetches its config from an authentic, immutable location and caches the parsed result by buildId. The room tolerates its absence (older credentials / a build with no declared config) by running the fixed schema.

displayName

displayName: string

Sanitized display name for nameplates.

exp

exp: number

iat

iat: number

instanceKey?

optional instanceKey?: string

Ticketed rooms only: the room instance id (a backend-minted uuid, world_room_instances.id). Unguessable, and minted only into credentials for holders of a ticket to that instance — it is what partitions one ticketed match from another of the same type. Absent for the default type and for open types.

iss

iss: string

jti

jti: string

maxPlayers

maxPlayers: number

Manifest maxPlayers (authoritative) → the room's maxClients cap, so it auto-locks + spills when full.

playerInit?

optional playerInit?: Record<string, RoomInitValue>

Initial values for THIS player's declared playerVars in the target type, evaluated per selected player by the openRoom effect. Applied at join; unknown keys or wrong scalar types are ignored with a warning.

roomInit?

optional roomInit?: Record<string, RoomInitValue>

Initial values for the target type's DECLARED roomVars, fixed by the openRoom effect that created the instance. Applied once, at room creation, from the creating credential; unknown keys or wrong scalar types are ignored by the room with a warning.

roomType?

optional roomType?: string

Named room type this credential admits to (manifest multiplayer.roomTypes.<name>). ABSENT = the world's default room type, which is what every credential minted before room types carries — so an older room server, which never reads the claim, keeps working. The room treats the client-supplied roomType join option as untrusted and rejects unless it equals this claim (absent on both sides = default), the same treatment as trial.id vs the trialId option. For a typed room maxPlayers is that TYPE's cap.

scopes

scopes: string[]

Scopes from manifest.permissions; must include 'multiplayer' to join a room.

sub

sub: string

Player/user id.

trial?

optional trial?: RoomTrialClaim

Server-minted, page-view-scoped marketplace trial carried into the reserved room.

worldId

worldId: string

World the room belongs to.

RoomState

The authoritative shared state. Always carries all three collections (entities empty until Tier 2).

Properties

dynamicModules?

optional dynamicModules?: Record<string, DynamicModuleState>

Trusted runtime modules added after room creation. Present only for a dynamic-module ABI build; legacy Worlds retain their exact reflected shape.

entities

entities: Record<string, EntityState>

RESERVED (Tier 2): server-spawned entities. Empty in v1.

modules?

optional modules?: Record<string, ModuleState>

S2 module-v1 instance groups, addressed by the transport key m:<moduleId>. Absent on every legacy world; use room.module(id) rather than indexing this transport container directly.

phase

phase: string

The current phase of the world's room-scoped state machine (Tier 2 Phase 3, spec §8), or '' when the world declares no states. Authored phase names; changed only by the server's transitionTo. A late-joiner reads it off synced state to know whether to spawn in or spectate (the join policy).

phaseStartTick

phaseStartTick: number

The serverTick at which the room entered its current phase. With serverTick/serverTimeMs a client computes time-in-phase locally (e.g. a round countdown) without a per-tick countdown var.

players

players: Record<string, PlayerState>

Per-player authoritative state, keyed by player id. Realized as a colyseus MapSchema.

roomVars

roomVars: RoomVars

Room-level declared game state (scores, timers, objectives). Names/types declared per-world.

serverTick

serverTick: number

Authoritative server clock: a monotonic counter advanced once per fixed-rate sim tick.

serverTimeMs

serverTimeMs: number

Authoritative server wall-clock (epoch ms) sampled at the last tick. Clients align to it (offset via the ping/pong echo, see messages.ts) and interpolate between patches, so timer/phase deadlines expressed against server time agree across clients without a per-tick countdown var.

timerDeadlines

timerDeadlines: Record<string, number>

Active timers (Tier 2 Phase 3, spec §8) → absolute deadline as serverTimeMs (epoch ms). The map key is the timer name for a room-scoped timer, or "<timer>|<playerKey>" for a per-player keyed timer (e.g. read your own cooldown at "cooldown|" + room.sessionId). A client computes the seconds remaining as (deadline − estimatedServerTimeMs) / 1000 using its ping/pong offset, so a countdown interpolates locally without a per-tick countdown var. An entry is removed when the timer fires or is cancelled.

RoomTicket

A ticket to a ticketed room instance, as handed to room.onTicket. The wire shape (RoomTicketMessage) carries expiresAt however the backend spelled it; here it is ALWAYS Unix epoch milliseconds, comparable with Date.now() — or NaN when the platform sent something unparseable, in which case treat the expiry as unknown (redemption is the authority either way).

expiresAt is the TICKET's deadline (a few minutes), not the room's: the ticket must be REDEEMED — switchRoom({ ticket }) — before it, or the redeem is refused (ticket-invalid). The room instance itself may live much longer; once inside, this timestamp no longer matters.

Properties

expiresAt

expiresAt: number

Redeem-by deadline of THIS ticket, Unix epoch MILLISECONDS (normalised from an ISO string / epoch seconds / epoch ms); NaN if unparseable. Not the lifetime of the room.

instanceId

instanceId: string

The room instance the ticket admits to.

roomType

roomType: string

ticketId

ticketId: string

Pass to Helix.multiplayer.switchRoom({ ticket: ticketId }).

RoomTicketMessage

helix:room-ticket — the room's private hand-off of one ticket to one selected player (SPEC-U1 openRoom). The ticket is redeemable ONLY by the account it was issued to (the backend's atomic redeem checks the user), so it is safe on the wire; redeem it with Helix.multiplayer.switchRoom({ ticket: ticketId }).

expiresAt is forwarded VERBATIM from the backend's instance-creation answer, which is why it is typed loosely: an ISO-8601 string or a Unix epoch number. The SDK normalises it to epoch milliseconds before a world sees it (HelixRoom.onTicket hands out a RoomTicket, not this wire shape).

Properties

expiresAt

expiresAt: string | number

THIS ticket's redeem-by deadline (about five minutes), as the backend returned it: ISO-8601 string or Unix epoch (seconds or milliseconds). It is the ticket's expiry, not the instance's — the room may live longer.

instanceId

instanceId: string

The room instance id (= the credential's instanceKey); also the rejoin endpoint's :instanceId.

roomType

roomType: string

The ticketed room type the instance was opened as.

ticketId

ticketId: string

Single-use ticket id — the join API's { ticket } body.

RoomTrialClaim

Properties

expiresAt

expiresAt: number

Trial expiry as Unix epoch seconds, sealed into the room credential.

id

id: string

itemId

itemId: string

kind

kind: "avatar" | "vehicle"

SealedDeviceDefinitionPin

Properties

manifestCid

manifestCid: string

packageId

packageId: string

version

version: string

SealedDeviceDefinitionProjection

One authored Device definition sealed into an authenticated World session.

Properties

definition

definition: DeviceDefinitionV1

definitionChecksumSha256

definitionChecksumSha256: string

SHA-256 of the canonical JSON representation of definition.

expiresAtEpochSeconds

expiresAtEpochSeconds: number

Session expiry as Unix epoch seconds.

pin: SealedDeviceDefinitionPin

Exact immutable Continuum identity retained separately from the definition digest.

SealedDeviceDefinitionResolver()

Extends

WorldDeviceDefinitionResolver

SealedDeviceDefinitionResolver(reference): Promise<DeviceDefinitionV1>

Parameters

reference

Returns

Promise<DeviceDefinitionV1>

Methods

dispose()

dispose(): void

Returns

void

SealedDeviceDefinitionResolverOptions

Properties

now?

optional now?: () => number

Current Unix time in milliseconds.

Returns

number

sha256?

optional sha256?: (bytes) => Promise<string>

Injected for runtimes without Web Crypto and for deterministic tests.

Parameters

bytes

ArrayBuffer

Returns

Promise<string>

ServerMessagePayloads

Maps each server→client message type to its payload.

Properties

__helix:vehicleActionFences

__helix:vehicleActionFences: VehicleActionFencesMessage

__helix:vehicleEntityRetired

__helix:vehicleEntityRetired: VehicleEntityRetiredMessage

entityStateAck

entityStateAck: EntityStateAckMessage

gesture

gesture: GestureEventMessage

groupRestSnapshot

groupRestSnapshot: GroupRestSnapshotMessage

helix:room-ticket

helix:room-ticket: RoomTicketMessage

moduleEffect

moduleEffect: ModuleEffectMessage

moduleEngagement

moduleEngagement: ModuleEngagementMessage

moduleFused

moduleFused: ModuleFusedMessage

moduleSleep

moduleSleep: ModuleSleepMessage

moduleWake

moduleWake: ModuleWakeMessage

pong

pong: PongMessage

stateAck

stateAck: StateAckMessage

StateAckMessage

A2 player-seat divergence ack (spec §9). Sent to ONE client when the room's movement gate rejected its state upload, OR proactively when a rule teleport/respawn re-anchored the seat (the mover must learn the move now, not via its next rejected frame). Under Tier-1 lean (no server physics) the correction is a thin SNAP: the client moves its local body to position (no input replay). The plain accepted case sends nothing — the accepted position is already in synced state; this fires only on divergence or a server-authored move.

Properties

position

position: Vec3

The room's authoritative position for this seat (the last ACCEPTED upload, or the teleport target) — the anchor the client snaps to.

seq

seq: number

The highest client seq the room has processed for this seat — the client prunes its reconciliation buffer through it.

teleportSeq?

optional teleportSeq?: number

The seat's current teleport epoch (v27), bumped by every rule teleport/respawn. The client adopts it ABSOLUTELY (it can go DOWN after a reconnect resets the seat) and clears its coalesced pending frame on change — a pre-snap position must never be stamped with the new epoch. Optional: an older room omits it.

StateMessage

Per-tick state upload. Units match PlayerReplicaState (position m; all angles degrees, see *Deg).

Properties

aiming?

optional aiming?: boolean

ADS intent, not an aim fraction — replicas ease locally with the same time constant.

aimPitchDeg

aimPitchDeg: number

aimYawDeg

aimYawDeg: number

crouched

crouched: boolean

facingYawDeg

facingYawDeg: number

grounded

grounded: boolean

gunDrawn?

optional gunDrawn?: boolean

Weapon drawn (vs holstered).

lookTarget?

optional lookTarget?: Vec3

moveDirectionDeg

moveDirectionDeg: number

position

position: Vec3

ragdolled?

optional ragdolled?: boolean

Physics owns the body (v25) — see PlayerReplicaState.ragdolled. OPTIONAL on the wire like the v24 gun fields: pre-v25 bundles omit it and must keep playing (the room leaves the schema default false).

ragdollLaunchX?

optional ragdollLaunchX?: number

The entry shove for THIS ragdoll (v26) — unit horizontal direction × m/s, meaningful only while ragdolled. OPTIONAL like ragdolled itself: pre-v26 bundles omit them and replicas crumple unshoved.

ragdollLaunchZ?

optional ragdollLaunchZ?: number

ragdollSpeedMps?

optional ragdollSpeedMps?: number

reachLeft?

optional reachLeft?: Vec3

Live IK reach targets (v21), world METERS — present only while the sender's arm/gaze IK is actually engaged (an inactive hand OMITS its field; the room then clears the seat's paired *Active flag). IK_LIMITS-bounded relative to this message's position: a hand can't plausibly reach past arm's length, a gaze point is capped at interaction range. Out-of-bounds drops the whole upload.

reachRight?

optional reachRight?: Vec3

reloading?

optional reloading?: boolean

Reload in progress (wire-timed on replicas).

seq

seq: number

Monotonic per-client sequence; the room echoes the last applied seq for client reconciliation.

shotSeq?

optional shotSeq?: number

Gun state (v24) — weapon SIGNALS, not motion: replicas re-run the same local easing/FX off these fields. Omitted entirely when the sender carries no gun-control ability; an invalid value drops the whole upload.

speed

speed: number

teleportSeq?

optional teleportSeq?: number

The last server teleport epoch this client has ADOPTED from a StateAck (v27). Stamped by the SDK at flush (like seq/tMs — worlds cannot supply it). The room drops a frame stamped BELOW the seat's current epoch: that frame was sampled before a teleport/respawn the client hadn't applied yet, and accepting it would silently undo the server's move (the in-flight-frame race). Strictly-below only — an unadopted HIGHER stamp (post-reconnect) passes. Optional: a pre-v27 bundle omits it and the fence skips, like epoch on entity uploads.

tMs?

optional tMs?: number

Sender send-time — the client's monotonic performance.now() ms when it sampled this frame. The server SANITIZES it into the synced PlayerState.posT (room.ts) for source-time interpolation: clients space keyframes by posT deltas, not arrival time, so delivery jitter stops becoming motion jitter. Only deltas matter (the origin is arbitrary). Optional — an older client omits it and the server falls back to its own apply-clock.

verticalVelocity

verticalVelocity: number

Suppression

Properties

cameraControl?

optional cameraControl?: boolean

defaultHud?

optional defaultHud?: boolean

interaction?

optional interaction?: boolean

locomotion?

optional locomotion?: boolean

TouchPresentation

Properties

group?

optional group?: string

kind

kind: TouchPresentationKind

order?

optional order?: number

zone

zone: TouchPresentationZone

UniversalActionSurfaceOptions

Properties

document?

optional document?: Document

hints

hints: ActionSurfaceHintSource

host

host: HTMLElement

Methods

now()?

optional now(): number

Returns

number

Deprecated

Navigation cadence is owned by the trusted mode host. Retained for source compatibility.

onDismiss()?

optional onDismiss(instanceId): void

Parameters

instanceId

string

Returns

void

onInvoke()

onInvoke(invocation): void

Parameters

invocation

ActionSurfaceInvocation

Returns

void

onOpenChange()?

optional onOpenChange(open): void

Parameters

open

boolean

Returns

void

VarsView

A guarded view over one declared vars bag. Safe before the first patch (fallbacks, never throws).

Methods

bool()

bool(name, fallback?): boolean

A declared boolean var; fallback (default false) when absent.

Parameters

name

string

fallback?

boolean

Returns

boolean

has()

has(name): boolean

Whether the declared var currently has a synced value (false before the first patch).

Parameters

name

string

Returns

boolean

list()

list<T>(name): T[]

A declared list var, materialized to a real Array each call (an ArraySchema is iterable but NOT an Array). Elements are the LIVE synced values — index/read them fresh, don't cache across frames.

Type Parameters

T

T = unknown

Parameters

name

string

Returns

T[]

names()

names(): string[]

The logical declared var names currently synced on the bag (transport chunk containers excluded).

Returns

string[]

num()

num(name, fallback?): number

A declared number var; fallback (default 0) before the first patch or when absent.

Parameters

name

string

fallback?

number

Returns

number

raw()

raw(name): unknown

The raw declared value, unconverted (escape hatch for declared names — transport keys stay hidden).

Parameters

name

string

Returns

unknown

str()

str(name, fallback?): string

A declared string var; fallback (default '') when absent. Refs read as the referenced session/entity id.

Parameters

name

string

fallback?

string

Returns

string

vec3()

vec3(name): Vec3 | null

A declared vec3 var (e.g. a saved checkpoint), or null when absent.

Parameters

name

string

Returns

Vec3 | null

VehicleActionEnvelope

SDK-owned replay/authority fence for one named Universal Vehicle component action. Authored item code supplies none of these values: the SDK resolves the live entity epoch and immutable Build identity, then owns the sequence.

Properties

authorityEpoch

authorityEpoch: number

Current room-issued entity authority era.

buildDigest

buildDigest: string

Immutable vehicle Build identity read from the entity's protected vBuild state.

entityId

entityId: string

Exact authoritative moving-entity identity from the signed placement.

seq

seq: number

Monotonic per-client/entity/authority-era action sequence.

targetBits?

optional targetBits?: number

Optional desired uint16 bits inside this action's trusted server mask. Omitted by legacy/toggle requests; when present the room validates and atomically replaces that masked field instead of toggling arrival state.

VehicleActionFencesMessage

Exact accepted sparse-action replay fences for this seat at one connection boundary.

Properties

entries

entries: object[]

authorityEpoch

authorityEpoch: number

entityId

entityId: string

seq

seq: number

VehicleComponentActionRequest

One named server-authoritative vehicle component or panel intent. The SDK derives the live Build/authority/sequence envelope; callers can only name the signed module identity, authoritative entity, action, and primitive args. sendVehicleComponentAction() returns false without sending or advancing its replay fence when transport or durable reconnect safety is unavailable.

Properties

action

action: string

args?

optional args?: Record<string, string | number | boolean>

entityId

entityId: string

identity

identity: ModuleIdentity

targetBits?

optional targetBits?: number

Optional desired uint16 bits inside the action's trusted server mask. This makes retries/idempotent set actions deterministic while legacy toggle requests continue to omit the field.

VehicleDetachActionDescriptor

One signed rigid-part spawn recipe admitted by a verified VehiclePackage.

Properties

allowedRoles

allowedRoles: VehicleRole[]

collider

collider: object

halfExtents

halfExtents: [number, number, number]

shape

shape: "box"

despawnAfterMs

despawnAfterMs: number

localTransform

localTransform: object

position

position: [number, number, number]

rotation

rotation: [number, number, number, number]

massKg

massKg: number

partId

partId: "hood"

settleAfterMs

settleAfterMs: number

stateBit

stateBit: number

Permanent bit in the root vehicle's server-owned vDetachBits uint16.

VehicleDetachActionRequest

One detachable-part intent. The action id is admitted by the trusted mount; the SDK derives every authority/build/replay field and never accepts a bit mutation because detachment creates a separate authoritative entity.

Properties

actionId

actionId: string

entityId

entityId: string

identity

identity: ModuleIdentity

VehicleDetachActions

Exact signed detachable-part protocol carried by the trusted runtime mount.

Properties

actions

actions: Record<string, VehicleDetachActionDescriptor>

version

version: 1

VehicleEntityRetiredMessage

Server-authenticated retirement of one root vehicle entity lifetime. Interest filtering never emits this.

Properties

authorityEpoch

authorityEpoch: number

entityId

entityId: string

VehiclePackageArtifact

Server-verified authored Universal Vehicle package carried by a World spawn.

Properties

checksumSha256

checksumSha256: string

format

format: 1

package

package: Record<string, unknown>

revision

revision: number

VehicleSpecialtyComponentInvocation

Properties

action

action: string

targetBits?

optional targetBits?: number

VehicleSpecialtyDetachInvocation

Properties

actionId

actionId: string

VehicleSpecialtyInvocation

Properties

args

args: Readonly<Record<string, unknown>>

bundleChecksumSha256?

optional bundleChecksumSha256?: string

functionName

functionName: string

itemInstanceId?

optional itemInstanceId?: string

Caller assertions are diagnostic only; the trusted constructor binding is always used.

moduleId?

optional moduleId?: string

VehicleSpecialtyPlacementBinding

Extends

VehicleSpecialtyRoomBinding

Properties

bundleChecksumSha256

bundleChecksumSha256: string

Inherited from

VehicleSpecialtyRoomBinding.bundleChecksumSha256

detachActions?

optional detachActions?: VehicleDetachActions | null

Full signed descriptor from the trusted runtime mount; null means this vehicle has no detachable part.

Inherited from

VehicleSpecialtyRoomBinding.detachActions

entityId

entityId: string

Present on trusted placement bindings; legacy specialty-only bindings omit it.

Overrides

VehicleSpecialtyRoomBinding.entityId

itemInstanceId?

optional itemInstanceId?: string

Required for legacy/static bindings; dynamic room modules have no public inventory UUID.

Inherited from

VehicleSpecialtyRoomBinding.itemInstanceId

moduleId

moduleId: string

Inherited from

VehicleSpecialtyRoomBinding.moduleId

placementId

placementId: string

revision

revision: number

Inherited from

VehicleSpecialtyRoomBinding.revision

stateVars

stateVars: readonly string[]

Inherited from

VehicleSpecialtyRoomBinding.stateVars

VehicleSpecialtyPlacementIdentity

Properties

bundleChecksumSha256

bundleChecksumSha256: string

bundleId

bundleId: string

detachActions?

optional detachActions?: VehicleDetachActions | null

Exact signed descriptor from the backend runtime mount.

itemInstanceId

itemInstanceId: string

placementId

placementId: string

revision

revision: number

stateVars

stateVars: readonly string[]

VehicleSpecialtyPresentationEffect

Properties

commandId

commandId: string

event

event: string

index

index: number

moduleId

moduleId: string

payload

payload: Readonly<Record<string, unknown>>

serverTick

serverTick: number

VehicleSpecialtyRoomBinding

Extended by

VehicleSpecialtyPlacementBinding

Properties

bundleChecksumSha256

bundleChecksumSha256: string

detachActions?

optional detachActions?: VehicleDetachActions | null

Full signed descriptor from the trusted runtime mount; null means this vehicle has no detachable part.

entityId?

optional entityId?: string

Present on trusted placement bindings; legacy specialty-only bindings omit it.

itemInstanceId?

optional itemInstanceId?: string

Required for legacy/static bindings; dynamic room modules have no public inventory UUID.

moduleId

moduleId: string

revision

revision: number

stateVars

stateVars: readonly string[]

VehicleSpecialtyStateSnapshot

Properties

bundleChecksumSha256

bundleChecksumSha256: string

itemInstanceId?

optional itemInstanceId?: string

moduleId

moduleId: string

revision

revision: number

serverTick

serverTick: number

vars

vars: Readonly<Record<string, unknown>>

VerbBinding

Properties

action

action: StandardModeAction

The canonical platform action. Modes never declare raw device bindings.

continuous?

optional continuous?: boolean

disabled?

optional disabled?: boolean

disabledReason?

optional disabledReason?: string

exclusiveGroup?

optional exclusiveGroup?: string

Verbs in the same non-empty group are mutually exclusive presentation states.

label

label: string

repeatMs?

optional repeatMs?: number

touch

touch: TouchPresentation

VerbEvent

Properties

at?

optional at?: object

x

x: number

y

y: number

heldMs?

optional heldMs?: number

phase

phase: VerbPhase

source

source: "key" | "pointer" | "touch" | "gamepad" | "ui" | "script"

value?

optional value?: number

vector?

optional vector?: object

x

x: number

y

y: number

WorldDevicePresentation

Methods

applyState()

applyState(state): void

Parameters

state

Readonly<Record<string, unknown>>

Returns

void

dispose()

dispose(): void | Promise<void>

Returns

void | Promise<void>

WorldDevicePresentationAdapter

Properties

capabilities

readonly capabilities: ReadonlySet<string>

Renderer powers only; room authority, typed state and time come from the host.

Methods

mount()

mount(input): WorldDevicePresentation | Promise<WorldDevicePresentation>

Parameters

input

definition

DeviceDefinitionV1

interact

(interactionId, args?) => void

Route a run/number/choice invocation into placement-scoped authority.

now

() => number

spawn

WorldDeviceMount

Returns

WorldDevicePresentation | Promise<WorldDevicePresentation>

WorldSpawn

One owned item instance currently standing in the active World.

Properties

deviceDefinition

deviceDefinition: { id: string; version: string; } | null

Same immutable Device definition used when this owned instance is in a Home.

instanceId

instanceId: string

itemId

itemId: string

kind

kind: string

modelUrl

modelUrl: string | null

name

name: string

ownerUserId

ownerUserId: string

ownerUsername

ownerUsername: string | null

placementId

placementId: string

spawnedAt

spawnedAt: string

state

state: Record<string, unknown>

thumbnailUrl

thumbnailUrl: string | null

transform

transform: Record<string, unknown>

usage

usage: string

vehiclePackage

vehiclePackage: VehiclePackageArtifact | null

worldId

worldId: string

Type Aliases

AccountVerificationLevel

AccountVerificationLevel = "basic" | "verified" | "identity_verified" | "business_verified"

AchievementListResult

AchievementListResult = object

Properties

achievements

achievements: AchievementSummary[]

earned

earned: number

total

total: number

AchievementMineResult

AchievementMineResult = object

Properties

achievements

achievements: AchievementSummary[]

AchievementSummary

AchievementSummary = object

Properties

description

description: string | null

earned

earned: boolean

earnPct

earnPct: number | null

hidden

hidden: boolean

iconUrl

iconUrl: string | null

id

id: string

key

key: string

name

name: string

points

points: number

rarityTier

rarityTier: string

ActionSurfaceDevice

ActionSurfaceDevice = "keyboard" | "gamepad" | "touch"

ActionSurfaceInvocation

ActionSurfaceInvocation = { action: ActionSurfaceAction; kind: "run" | "point" | "takeover"; } | { action: ActionSurfaceAction; kind: "number"; value: number; } | { action: ActionSurfaceAction; kind: "choice" | "asset" | "text"; value: string; }

ActionSurfaceKind

ActionSurfaceKind = "run" | "choice" | "number" | "text" | "point" | "asset" | "takeover"

The seven portable interaction forms owned by the universal surface.

AvatarComposition

AvatarComposition = object

Properties

appearance

appearance: object

colorOverrides

colorOverrides: Record<string, unknown>

hiddenSlotIds

hiddenSlotIds: string[]

materialOverrides

materialOverrides: Record<string, unknown>

appearanceDigest

appearanceDigest: string

base

base: object

continuumPackagePin?

optional continuumPackagePin?: AvatarPackagePin

itemId

itemId: string

modelUrl

modelUrl: string | null

compositionDigest

compositionDigest: string

hostKind

hostKind: "character"

instanceThumbnailUrl

instanceThumbnailUrl: string | null

materials

materials: Record<string, unknown>

visibleAddOns

visibleAddOns: object[]

continuumPackagePin?

optional continuumPackagePin?: AvatarPackagePin

fill?

optional fill?: "all" | "each"

itemId

itemId: string

modelUrl

modelUrl: string | null

mountSocket?

optional mountSocket?: string | null

slotId

slotId: string

visualOps

visualOps: unknown[]

AvatarLoadout

AvatarLoadout = object

Properties

baseShape

baseShape: AvatarBaseShape

body

body: UniversalAvatarBody

customAvatar

customAvatar: EquippedAvatar

equippedSlots

equippedSlots: AvatarLoadoutSlot[]

inventory

inventory: InventoryItem[]

updatedAt

updatedAt: string

version

version: 1

AvatarLoadoutPatch

AvatarLoadoutPatch = object

Properties

baseShape?

optional baseShape?: AvatarBaseShape

customAvatarInventoryItemId?

optional customAvatarInventoryItemId?: string | null

equippedSlots?

optional equippedSlots?: Record<string, string | null>

AvatarPackagePin

AvatarPackagePin = object

Properties

manifestCid

manifestCid: string

packageId

packageId: string

version

version: string

AvatarRefreshMessage

AvatarRefreshMessage = Record<string, never>

Ask the room to RE-RESOLVE this player's avatar (v23) — the seat's PlayerState.avatarUrl stops being fixed at join. A pure HINT: the payload carries no fields (a client can never name the URL replicated onto its seat), the room re-reads the equipped avatar from the platform under the sender's own credential, and a refresh that resolves to the same URL is a no-op. Rate-capped like the other human-paced channels (a wardrobe change).

Balance

Balance = object

Properties

coins

coins: number

lix

lix: number

updatedAt?

optional updatedAt?: string

BroadcastPayload

BroadcastPayload = Record<string, RoomVarValue>

A server→client broadcast event (Tier 2 Phase 2.5, spec §10.3). A world declares named events with a payload schema; a broadcast rule-effect sends one on the event's NAME (not a fixed ServerMessageType), received via room.onMessage(name, cb). Payload values are the declared fields; a ref field serializes to its playerKey string on the wire (so who:"self" and who:{aggregate argmax} are the same type).

CameraAim

CameraAim = object

Camera aim in degrees, relative to the avatar's facing.

Properties

pitch

pitch: number

yaw

yaw: number

CameraAspect

CameraAspect = "portrait" | "landscape" | "square" | "free"

CameraCapabilityFlag

CameraCapabilityFlag = Exclude<keyof HelixCameraCapability, "unavailableReason">

The ability flags, without the human line that explains a refusal.

unavailableReason is prose ABOUT the flags, not one of them, so anything that iterates or names a capability wants this instead of keyof HelixCameraCapability — which would let a refusal be reported as "camera.unavailableReason unavailable".

CameraControlTarget

CameraControlTarget = "camera" | "avatar"

Which body the player's look/move input drives while the camera is up.

CameraDroneLockMode

CameraDroneLockMode = "free" | "lock" | "orbit"

How the drone treats its subject: free flight, held framing, or a circling orbit.

CameraFilterId

CameraFilterId = "original" | "vivid" | "warm" | "cool" | "mono"

CameraFocusPoint

CameraFocusPoint = object

Tap-to-focus target in normalized viewport coordinates: 0,0 = top-left, 1,1 = bottom-right.

Properties

x

x: number

y

y: number

CameraLensPreset

CameraLensPreset = typeof CAMERA_LENS_PRESETS[number]

CameraMediaMode

CameraMediaMode = "photo" | "video"

CameraSessionState

CameraSessionState = "inactive" | "device-hold" | "rear" | "selfie" | "drone"

Where the camera currently is. device-hold is the avatar holding the phone before it is raised.

CameraSpatialMode

CameraSpatialMode = "rear" | "selfie" | "drone"

Where the camera sits in space. Distinct from CameraSessionState, which also carries inactive.

CameraTimerSeconds

CameraTimerSeconds = 0 | 3 | 10

Self-timer settings. 0 = no timer (the shutter commits on the press).

CameraVector3

CameraVector3 = object

Properties

x

x: number

y

y: number

z

z: number

Capability

Capability = ModeCapability

Deprecated

Use ModeCapability. Retained for the v0.2 migration release.

CaptureOptions

CaptureOptions = object

Properties

aspect?

optional aspect?: CameraAspect

quality?

optional quality?: number

type?

optional type?: string

ClientMessageType

ClientMessageType = typeof ClientMessageType[keyof typeof ClientMessageType]

ConsumeResult

ConsumeResult = object

Properties

applied

applied: boolean

balance

balance: number

reason?

optional reason?: "insufficient"

CropRect

CropRect = object

Properties

sh

sh: number

sw

sw: number

sx

sx: number

sy

sy: number

DataStoreListOptions

DataStoreListOptions = object

Properties

cursor?

optional cursor?: string

limit?

optional limit?: number

DataStoreListPage

DataStoreListPage = object

Properties

keys

keys: string[]

nextCursor?

optional nextCursor?: string

DataStoreListPayload

DataStoreListPayload = object

Properties

cursor?

optional cursor?: string

limit?

optional limit?: number

prefix?

optional prefix?: string

DataStoreWriteOptions

DataStoreWriteOptions = object

Properties

expectedVersion?

optional expectedVersion?: number

DebugLogEntry

DebugLogEntry = object

Properties

args

args: string[]

level

level: DebugLogLevel

t

t: number

DebugLogLevel

DebugLogLevel = "log" | "info" | "warn" | "error" | "debug"

DeviceAppPermissionV1

DeviceAppPermissionV1 = "web.content" | "network.fetch" | "web.externalNavigation" | "audio.media"

Permissions an app declaration may request from the host.

DeviceAppTypeV1

DeviceAppTypeV1 = "localWeb" | "remoteWeb" | "youtube" | "canvas" | "remoteImage" | "ownerImage"

App kinds a definition's screen components may bind to.

remoteImage is the narrowest kind: ONE external image the host draws, addressed by a URL held in typed string state rather than by entry. It is not a document, so network.fetch is its only legal permission and its entry may be omitted.

ownerImage is ONE image the owned copy's owner uploaded (the Custom Poster, capability app.image.owner). It names no source, origin or permission: the image is per-copy state on the owned instance and the HOST resolves it through the placement the viewer is entitled to see. A host without owned, placed copies (a Device Lab, an SDK-hosted world) does not grant app.image.owner, so mount() refuses it rather than showing a blank face.

DeviceDefinitionReference

DeviceDefinitionReference = object

Properties

id

id: string

version

version: string

DevicePortAuthorityV1

DevicePortAuthorityV1 = "local" | "server"

DevicePortDataTypeV1

DevicePortDataTypeV1 = "boolean" | "number" | "string" | "media.audio" | "media.video"

DevicePortDirectionV1

DevicePortDirectionV1 = "input" | "output" | "bidirectional"

DevicePortKindV1

DevicePortKindV1 = "value" | "event" | "command" | "stream"

DeviceStreamHandleV1

DeviceStreamHandleV1 = string & object

Opaque host registry token; it never contains media samples.

Type Declaration

__deviceStreamHandleV1

readonly __deviceStreamHandleV1: unique symbol

DeviceStreamRoutabilityV1

DeviceStreamRoutabilityV1 = "routable" | "embedded-only" | "unavailable"

DeviceTrialSpawn

DeviceTrialSpawn = Readonly<{ composition: unknown; definition: DeviceDefinitionV1; definitionChecksumSha256: string; deviceDefinition: Readonly<{ id: string; version: string; }>; expiresAt: number; functionalPin: Readonly<{ continuumManifestCid: string; continuumPackageId: string; continuumPackageVersion: string; }>; itemId: string; kind: "device"; modelUrl: string | null; name: string; placementId: string; transform: Readonly<{ position: readonly [number, number, number]; scale: number; yawDeg: number; }>; }>

One authenticated, session-only Device placement projected by Try Now.

DistributionCapabilityRequestMessage

DistributionCapabilityRequestMessage = object

dkey:<stable-key> or distribution:<uuid>; the room refuses anything else.

Properties

ref

ref: string

requestId

requestId: string

DistributionCapabilityResultMessage

DistributionCapabilityResultMessage = { capability: string; expiresAt: string; ref: string; requestId: string; } | { error: string; requestId: string; }

DreamerAudioArtifact

DreamerAudioArtifact = object

Properties

contentType

contentType: string

kind

kind: "audio"

sizeBytes

sizeBytes: number

url

url: string

DreamerAudioClient

DreamerAudioClient = object

Methods

generate()

generate(input, options?): Promise<DreamerAudioSucceededJob>

Parameters

input

DreamerAudioGenerateRequest

options?

DreamerAudioPollOptions

Returns

Promise<DreamerAudioSucceededJob>

generateAndResolve()

generateAndResolve(input, options?): Promise<DreamerGeneratedVaultAudio>

Generate, require default-on Vault publication, then resolve the same durable asset through the SDK's normal Vault consumption surface.

Parameters

input

DreamerAudioGenerateRequest

options?

DreamerAudioPollOptions

Returns

Promise<DreamerGeneratedVaultAudio>

get()

get(jobId): Promise<DreamerAudioJob>

Parameters

jobId

string

Returns

Promise<DreamerAudioJob>

start()

start(input): Promise<{ jobId: string; status: "queued"; }>

Parameters

input

DreamerAudioGenerateRequest

Returns

Promise<{ jobId: string; status: "queued"; }>

DreamerAudioClientOptions

DreamerAudioClientOptions = object

Properties

accessToken?

optional accessToken?: string | null | (() => string | null | Promise<string | null>)

apiBaseUrl

apiBaseUrl: string

HELIX API origin, or a full base ending in /api/v1/dreamer.

fetch?

optional fetch?: typeof fetch

pollIntervalMs?

optional pollIntervalMs?: number

timeoutMs?

optional timeoutMs?: number

DreamerAudioFailedJob

DreamerAudioFailedJob = DreamerAudioJobBase & object

Type Declaration

error?

optional error?: string

status

status: "failed"

DreamerAudioGenerateRequest

DreamerAudioGenerateRequest = DreamerSoundEffectRequest | DreamerMusicRequest | DreamerTextToSpeechRequest

DreamerAudioGenerationMode

DreamerAudioGenerationMode = "sound_effect" | "music" | "text_to_speech"

DreamerAudioJob

DreamerAudioJob = DreamerAudioPendingJob | DreamerAudioFailedJob | DreamerAudioSucceededJob

DreamerAudioPendingJob

DreamerAudioPendingJob = DreamerAudioJobBase & object

Type Declaration

status

status: "queued" | "running"

DreamerAudioPollOptions

DreamerAudioPollOptions = object

Properties

onProgress?

optional onProgress?: (job) => void

Parameters

job

DreamerAudioJob

Returns

void

pollIntervalMs?

optional pollIntervalMs?: number

timeoutMs?

optional timeoutMs?: number

DreamerAudioSucceededJob

DreamerAudioSucceededJob = DreamerAudioJobBase & object

Type Declaration

asset

asset: DreamerAudioArtifact

status

status: "succeeded"

DreamerAudioVoiceSettings

DreamerAudioVoiceSettings = object

Properties

similarityBoost?

optional similarityBoost?: number

speakerBoost?

optional speakerBoost?: boolean

speed?

optional speed?: number

stability?

optional stability?: number

style?

optional style?: number

DreamerGeneratedVaultAudio

DreamerGeneratedVaultAudio = object

Properties

job

job: DreamerAudioSucceededJob

loadPlan

loadPlan: Extract<VaultLoadPlan, { loader: "audio"; }>

resolved

resolved: VaultResolvedAsset<"audio">

DreamerMusicRequest

DreamerMusicRequest = DreamerAudioRequestBase & object

Type Declaration

audioMode

audioMode: "music"

durationSeconds?

optional durationSeconds?: number

forceInstrumental?

optional forceInstrumental?: boolean

prompt

prompt: string

DreamerSoundEffectRequest

DreamerSoundEffectRequest = DreamerAudioRequestBase & object

Type Declaration

audioMode

audioMode: "sound_effect"

durationSeconds?

optional durationSeconds?: number

loop?

optional loop?: boolean

prompt

prompt: string

promptInfluence?

optional promptInfluence?: number

DreamerTextToSpeechRequest

DreamerTextToSpeechRequest = DreamerAudioRequestBase & object

Type Declaration

audioMode

audioMode: "text_to_speech"

languageCode?

optional languageCode?: string

pronunciationDictionaryIds?

optional pronunciationDictionaryIds?: string[]

seed?

optional seed?: number

text

text: string

voiceId

voiceId: string

voiceSettings?

optional voiceSettings?: DreamerAudioVoiceSettings

EmoteRefreshMessage

EmoteRefreshMessage = Record<string, never>

Ask the room to RE-RESOLVE this player's carried emote set (v28) — the seat's PlayerState.emotes stops being fixed at join. A pure HINT with the same shape and the same reason as AvatarRefreshMessage: the payload carries no fields, because the room re-reads the equipped emotes from the platform under the sender's own credential and a client must never be able to name a clip URL that lands on its seat. Rate-capped like the avatar hint (a wheel change is the same human-paced wardrobe gesture, and each hint costs the room a platform re-resolve).

Entitlements

Entitlements = object

Properties

balances

balances: Record<string, number>

owned

owned: Record<string, number>

passes

passes: Record<string, { active: boolean; expiresAt: number | null; since: number; }>

v

v: 1

EquippedAvatar

EquippedAvatar = object

Properties

composition?

optional composition?: AvatarComposition | null

Immutable public render recipe for this configured avatar instance.

contentHash?

optional contentHash?: string | null

continuumPackagePin?

optional continuumPackagePin?: AvatarPackagePin

glbUrl

glbUrl: string | null

inventoryItemId?

optional inventoryItemId?: string | null

itemId

itemId: string | null

skeleton

skeleton: string | null

source

source: "equipped" | "auto" | "default" | "trial"

EquippedEmote

EquippedEmote = object

Properties

audio?

optional audio?: string

The emote's sound URL; absent when it is silent.

clip

clip: string

Animation clip URL the world fetches to play it.

itemId

itemId: string

The universal-item id this emote came from.

label?

optional label?: string

The item's display title for the wheel's petal; absent when the platform named it nothing.

playback

playback: "oneshot" | "loop"

slot

slot: "r0" | "r1" | "r2" | "r3" | "r4" | "r5" | "r6" | "r7" | "sit" | "lie"

Wheel position: 'r0'..'r7' are the eight radial slots, 'sit'/'lie' the two posture emotes.

EquippedEmotes

EquippedEmotes = object

Properties

emotes

emotes: EquippedEmote[]

EquippedLocomotionPack

EquippedLocomotionPack = object

Properties

pack

pack: string

Servable pack-manifest base URL the seat moves on; '' = the platform locomotion set.

FinalRestReply

FinalRestReply = FinalRestGrant | { entries?: object[]; group: string; reason: string; requestId: number; scope?: FinalRestProvenance; status: "rejected" | "invalidated"; transactionId?: string; version: 1; } | { group: string; requestId: number; scope?: FinalRestProvenance; snapshot: GroupRestSnapshotMessage; status: "committed"; transactionId: string; version: 1; }

GesturePlay

GesturePlay = "oneshot" | "loop" | "stop"

How a GestureMessage applies: a transient oneshot, a persistent loop, or stopping the current loop.

HelixCameraCapability

HelixCameraCapability = object

What THIS runtime can actually do, right now.

The runtime contract's runtimeBindings.*.availability is a STATIC claim about a method's existence; this is a LIVE one about a running instance, and it is the only thing that can answer "this build has photo but not video" or "the player just revoked the microphone, so world audio is gone". HELIX OS disables the controls this says are false — it must never grey out a control on a guess, and must never present a control whose call it knows will fail.

All-false is the correct answer for a runtime that has not reported yet: a capability is claimed, never assumed. unavailableReason is a human line the shell may show next to a disabled control ("this world ships photo only").

Properties

drone

drone: boolean

exposureBias

exposureBias: boolean

focusPoint

focusPoint: boolean

photo

photo: boolean

twoHandPose

twoHandPose: boolean

The avatar can hold the device in a two-handed pose (drives device-hold).

unavailableReason?

optional unavailableReason?: string

video

video: boolean

worldAudio

worldAudio: boolean

Video can record the world's audio bed, not just a silent picture.

HelixCameraControl

HelixCameraControl = object

A WORLD SCRIPT asking HELIX OS to change the camera — the one camera surface that is world-driven rather than player-driven, and the reason the camera.control manifest capability exists. Every field is optional; the shell applies the ones present and answers with the resulting state.

shutter: true requests ONE capture (it increments the sequence); it is not a level. recording is a level — set it false to stop.

Properties

aim?

optional aim?: CameraAim

controlTarget?

optional controlTarget?: CameraControlTarget

exposureBias?

optional exposureBias?: number

filter?

optional filter?: CameraFilterId

focusPoint?

optional focusPoint?: CameraFocusPoint

media?

optional media?: CameraMediaMode

recording?

optional recording?: boolean

session?

optional session?: CameraSessionState

shutter?

optional shutter?: boolean

spatial?

optional spatial?: CameraSpatialMode

timerSeconds?

optional timerSeconds?: CameraTimerSeconds

worldAudio?

optional worldAudio?: boolean

Record the world's audio bed with a video (requires capability.worldAudio).

zoom?

optional zoom?: number

HelixCameraDroneCommand

HelixCameraDroneCommand = object

A request to move the drone. Every field is optional; omitted fields are left alone.

Properties

interpolationSeconds?

optional interpolationSeconds?: number

lockMode?

optional lockMode?: CameraDroneLockMode

returnToAvatar?

optional returnToAvatar?: boolean

subjectUserId?

optional subjectUserId?: string

transform?

optional transform?: HelixCameraDroneTransform

velocity?

optional velocity?: CameraVector3

HelixCameraDroneState

HelixCameraDroneState = object

Phase-2 vocabulary. Contracted now so HELIX OS, the web engine and Unreal agree on the names before anyone implements them; camera.flyDrone is unavailable until the flight-authority question is answered (a drone is a second body in a shared world, so who may move it is not a client decision).

Properties

droneId

droneId: string

Stable per-session drone identity — a world may see more than one.

interpolationSeconds

interpolationSeconds: number

Seconds the runtime should smooth toward transform; 0 = snap.

lockMode

lockMode: CameraDroneLockMode

returnDistance

returnDistance: number

Metres between the drone and its return point.

returning

returning: boolean

True while the drone is flying itself back to its owner.

subjectUserId

subjectUserId: string

Platform userId the drone locks/orbits; '' while free-flying.

transform

transform: HelixCameraDroneTransform

velocity

velocity: CameraVector3

Metres per second, world axes.

HelixCameraDroneTransform

HelixCameraDroneTransform = object

Drone pose in world space. Rotation is degrees.

Properties

pitch

pitch: number

position

position: CameraVector3

roll

roll: number

yaw

yaw: number

HelixCameraShutter

HelixCameraShutter = object

The shutter as an EDGE, not a pulse.

sequence is monotonic and increments once per committed capture. A runtime fires on the CHANGE, so a duplicated or replayed helix:camera-state (the shell re-sends its snapshot after the handshake) cannot double-expose — which a boolean shutterPressed would do every single time.

Properties

recording

recording: boolean

True while a video recording is actually running.

sequence

sequence: number

timerRemainingSeconds

timerRemainingSeconds: number

Seconds left on the self-timer; 0 when no countdown is running.

HelixCameraState

HelixCameraState = object

The whole camera, as one shell-owned snapshot pushed to the runtime.

Sent WHOLE rather than as deltas: the shell re-sends it after helix:init so a runtime that booted mid-session is never left guessing, and a whole snapshot makes that replay idempotent (see HelixCameraShutter for the one field where that needed thought).

Properties

aim

aim: CameraAim

capability

capability: HelixCameraCapability

The capability the shell currently believes the runtime has (see reportCapability).

controlTarget

controlTarget: CameraControlTarget

drone?

optional drone?: HelixCameraDroneState

Absent for every handheld mode; present only while session is 'drone'.

exposureBias?

optional exposureBias?: number

Exposure compensation in stops. Absent whenever capability.exposureBias is false.

filter

filter: CameraFilterId

focusPoint?

optional focusPoint?: CameraFocusPoint

Absent until the player taps to focus, and whenever capability.focusPoint is false.

lens

lens: CameraLensPreset

The lens button that is lit — the preset nearest zoom, not the zoom itself.

media

media: CameraMediaMode

session

session: CameraSessionState

shutter

shutter: HelixCameraShutter

spatial

spatial: CameraSpatialMode

timerSeconds

timerSeconds: CameraTimerSeconds

zoom

zoom: number

Effective zoom, continuous within the preset range.

HelixDeviceFormFactor

HelixDeviceFormFactor = "phone" | "tablet"

HelixDeviceState

HelixDeviceState = object

Shell-owned Helix OS visibility mirrored into every embedded world.

Properties

form?

optional form?: HelixDeviceFormFactor

open

open: boolean

HelixInitResult

HelixInitResult = object

Properties

customizerSource

customizerSource: PackageCustomizerSource | null

Trial provenance retained when its subject expires or fails validation.

customizerSubject

customizerSubject: PackageCustomizerSubject | null

Validated, immutable local package configuration sealed into this trial session.

embedded

embedded: boolean

runtimeFidelity

runtimeFidelity: RuntimeFidelityIntent | null

Validated presentation intent frozen by the shell for this World load. Null means an older shell or invalid payload; resolve through engine Auto.

user

user: HelixUser | null

world

world: HelixWorldContext | null

HelixInteractionPrompt

HelixInteractionPrompt = object

Properties

actionLabel?

optional actionLabel?: string

description?

optional description?: string

id

id: string

input?

optional input?: object

button?

optional button?: string

key?

optional key?: string

label?

optional label?: string

priority?

optional priority?: number

state?

optional state?: HelixPromptState

title

title: string

HelixMatchmakingErrorCode

HelixMatchmakingErrorCode = "unknown-queue" | "already-queued" | "already-matched" | "not-party-leader" | "party-too-large" | "party-changed" | "guests-cannot-queue" | "rate-limited" | "missing-permission" | "unavailable" | "not-ready" | "invalid-argument" | "request-failed"

Why a matchmaking call failed. The backend's refusal code is what is matched, not the HTTP status alone.

unknown-queue the world's manifest declares no such queue.
already-queued this player (or their party) already holds a waiting ticket in THIS world. The call rejects, the SDK makes sure that ticket is being polled, and onStatus reports it. (A waiting ticket in another world is not an error: enqueueing here replaces it.)
already-matched a match already stands: cancel() came too late, or enqueue() was called while a match is unredeemed. error.match is the match and onMatch fires for it. From enqueue() it may be null: then the pending match belongs to another member of your party (the platform does not hand one member's room ticket to another; error.memberUserId names them), and your own status stays what it was.
not-party-leader in a party, only the leader queues.
party-too-large the party does not fit one team of this queue.
party-changed the party kept changing while the request ran. Nothing happened; safe to call again. The SDK has already retried it twice.
guests-cannot-queue the session is a guest; checked locally first, with no request.
rate-limited backend queue-rate-limit, or any 429.
missing-permission the world's manifest lacks the multiplayer permission (the platform's "Insufficient world scopes" 401). Final: asking again cannot help.
unavailable matchmaking is not enabled on this platform (matchmaking-disabled).
not-ready no world session, no world id, no API base, or the world was left — nothing was sent.
invalid-argument a bad argument — nothing was sent.
request-failed anything else: no answer within the timeout (status null), a 5xx, any other 401 (an expired or missing token), a 404 with no refusal code, or a refusal code this SDK does not know (backendCode has it).

HelixMaterialCatalog

HelixMaterialCatalog = object

Properties

materials

materials: HelixMaterialDefinition[]

pack

pack: object

slug

slug: string

version

version: string

resolutions?

optional resolutions?: HelixMaterialResolutionTier[]

schemaVersion

schemaVersion: number | string

Verbatim from the pack: 1, "1", 2, "2" are all valid spellings.

HelixMaterialDefinition

HelixMaterialDefinition = object

Indexable

[key: string]: unknown

Properties

defaultResolution?

optional defaultResolution?: string

Names which resolutions key maps mirrors.

glass?

optional glass?: object

color

color: number

opacity

opacity: number

transmission

transmission: number

id

id: string

kind

kind: HelixMaterialKind

maps?

optional maps?: HelixMaterialMapPaths

The default resolution's maps. Unchanged across schema versions.

metalness

metalness: number

name

name: string

normalScale

normalScale: number

repeatPerMeter

repeatPerMeter: number

resolutions?

optional resolutions?: Record<string, HelixMaterialResolutionVariant>

Every texture resolution this material carries.

roughness

roughness: number

source?

optional source?: object

Index Signature

[key: string]: unknown

assetId?

optional assetId?: string

license?

optional license?: string

provider?

optional provider?: string

sourceResolution?

optional sourceResolution?: string

url?

optional url?: string

swatch

swatch: string

tiling?

optional tiling?: object

Index Signature

[key: string]: unknown

accepted?

optional accepted?: boolean

bandAfter?

optional bandAfter?: number

measuredAt?

optional measuredAt?: string

technique?

optional technique?: string

wrap?

optional wrap?: number

wrapAfter?

optional wrapAfter?: number

wrapBefore?

optional wrapBefore?: number

water?

optional water?: object

color

color: number

opacity

opacity: number

roughness

roughness: number

transmission

transmission: number

waveScale?

optional waveScale?: number

waveSpeed?

optional waveSpeed?: number

HelixMaterialKind

HelixMaterialKind = "texture" | "glass" | "procedural_water"

HelixMaterialLibrary

HelixMaterialLibrary = object

Properties

assetBaseUrl

readonly assetBaseUrl: string

catalog

readonly catalog: HelixMaterialCatalog

catalogResolutions

readonly catalogResolutions: HelixMaterialResolutionTier[]

Tiers the pack declares catalog-wide; [] for a schemaVersion 1 pack.

Methods

get()

get(id): HelixMaterialDefinition | null

Parameters

id

string

Returns

HelixMaterialDefinition | null

list()

list(query?): HelixMaterialDefinition[]

Parameters

query?

HelixMaterialQuery

Returns

HelixMaterialDefinition[]

resolutions()

resolutions(id): HelixMaterialResolutionOption[]

Every resolution one material offers, with maps absolutized like resolve.

Parameters

id

string

Returns

HelixMaterialResolutionOption[]

resolve()

resolve(id, options?): ResolvedHelixMaterial | null

Throws when options.resolution names a key the material does not declare.

Parameters

id

string

options?

resolution?

string

Returns

ResolvedHelixMaterial | null

HelixMaterialMapPaths

HelixMaterialMapPaths = object

Properties

albedo

albedo: string

normal

normal: string

orm

orm: string

HelixMaterialQuery

HelixMaterialQuery = object

Properties

category?

optional category?: string

kind?

optional kind?: HelixMaterialKind

limit?

optional limit?: number

Palette budget for one world/scene. The global catalog remains unbounded.

query?

optional query?: string

HelixMaterialResolutionOption

HelixMaterialResolutionOption = object

One resolvable resolution of one material, normalized across schema versions.

Properties

key

key: string

maps

maps: HelixMaterialMapPaths

pixels

pixels: number | null

HelixMaterialResolutionTier

HelixMaterialResolutionTier = object

A resolution tier the pack declares catalog-wide (catalog schemaVersion 2+).

Properties

default?

optional default?: boolean

key

key: string

pixels?

optional pixels?: number

HelixMaterialResolutionVariant

HelixMaterialResolutionVariant = object

One texture-resolution variant a material declares (catalog schemaVersion 2+).

Properties

maps

maps: HelixMaterialMapPaths

pixels?

optional pixels?: number

HelixMultiplayerRosterEntry

HelixMultiplayerRosterEntry = object

Properties

avatarUrl

avatarUrl: string

Equipped-avatar GLB URL ('' = default body). NOT a profile picture — resolve those via userId.

connected

connected: boolean

False while the seat sits in the server's reconnection grace window.

displayName

displayName: string

isSelf

isSelf: boolean

sessionId

sessionId: string

Room-scoped seat key (the RoomState.players map key / colyseus sessionId).

userId

userId: string

Platform user id (PlayerState.userId, contract v18) — '' when the room predates v18.

HelixMultiplayerState

HelixMultiplayerState = object

Properties

maxPlayers

maxPlayers: number | null

The room's seat cap (credential maxPlayers), or null when unknown (e.g. resumed via reload).

playerCount

playerCount: number

players

players: HelixMultiplayerRosterEntry[]

roomId

roomId: string

The joined Colyseus room instance id — the platform's only true instance identity.

roomType?

optional roomType?: string

The room's type (manifest multiplayer.roomTypes). Absent for the default room.

sessionId

sessionId: string

This client's seat key (also flagged isSelf in players).

ticketed?

optional ticketed?: boolean

True when the room is a TICKETED instance: entered by redeeming a ticket, private to its ticket holders. Its roomId must not be offered as a public join target (?instance=). Absent otherwise.

HelixNotification

HelixNotification = object

Properties

actionHref?

optional actionHref?: string

actionLabel?

optional actionLabel?: string

kind

kind: HelixNotificationKind

message?

optional message?: string

timeoutMs?

optional timeoutMs?: number

title

title: string

HelixNotificationKind

HelixNotificationKind = "success" | "failure" | "notification" | "message"

HelixPartyErrorCode

HelixPartyErrorCode = "not-party-leader" | "cannot-invite" | "party-full" | "too-many-invites" | "already-in-party" | "party-changed" | "not-in-party" | "unknown-party-member" | "invite-not-found" | "invite-expired" | "code-not-found" | "guests-cannot-party" | "rate-limited" | "missing-permission" | "unavailable" | "not-ready" | "invalid-argument" | "request-failed"

Why a party call failed.

not-party-leader only the leader invites, kicks and promotes.
cannot-invite the target is not a friend, and is not invitable as a stranger either: that needs them to be in this world AND to have public presence with activity sharing on (the account default is friends-only). A block also gives this. Use a join code.
party-full no room left (inviting or accepting).
too-many-invites the party already has its limit of pending invites.
already-in-party you are in a party of two or more: leave it before accepting an invite or joining by code. From a party of one (your own invite or code created it) you are moved.
code-not-found no party has that join code (mistyped, expired or revoked).
party-changed the party kept changing while the request ran. Nothing happened; safe to call again. The SDK has already retried it twice.
not-in-party you are in no party (leave, kick, promote).
unknown-party-member that player is not in your party (kick, promote).
invite-not-found the invite does not exist (or is not yours).
invite-expired the invite ran out.
guests-cannot-party the session is a guest; checked locally first, with no request.
rate-limited backend invite-rate-limit, or any 429.
missing-permission the world's manifest lacks the multiplayer permission (the platform's "Insufficient world scopes" 401). Final: asking again cannot help.
unavailable parties are not enabled on this platform (parties-disabled).
not-ready / invalid-argument / request-failed as for HelixMatchmakingError.

HelixPresenceActivity

HelixPresenceActivity = object

Properties

details?

optional details?: string

Optional secondary detail line (≤128 chars).

image?

optional image?: string

Optional custom image (asset key/URL). Omit → world thumbnail.

joinable?

optional joinable?: boolean

Hint that this activity is joinable (gated on the MP instance runtime).

party?

optional party?: object

Optional party sizing shown on the presence card.

current

current: number

max

max: number

state

state: string

Short activity line (≤128 chars), e.g. "Racing — lap 3/5". Required.

HelixPromptState

HelixPromptState = "default" | "available" | "locked" | "busy"

HelixRoomJoinErrorCode

HelixRoomJoinErrorCode = "unknown-room-type" | "ticket-required" | "ticket-invalid" | "room-type-unavailable" | "instance-closed" | "rejoin-failed" | "invalid-target" | "not-ready" | "switch-in-progress" | "join-in-progress" | "cancelled" | "left" | "join-failed"

Why a join or a room hop failed, as a stable machine-readable code:

unknown-room-type the world's active build declares no such room type (or room types are off).
ticket-required the type is ticketed; it can only be entered by redeeming a ticket.
ticket-invalid the ticket is unknown, expired, already used, or was issued to someone else.
room-type-unavailable the platform answered a typed/ticket request with a DEFAULT-room reservation (a backend that predates room types ignores the body) — refused rather than seating the player in a room they did not ask for.
instance-closed the ticketed room instance has closed — the match is over. Answered by the rejoin endpoint (410) when resuming after a reload, and by a ticket redeem whose instance ended first. Final: the SDK forgets the instance and never retries.
rejoin-failed resuming a ticketed room failed for another reason. 403 and 404 (not this player's instance) are final and forgotten; a network failure, 5xx, 429 or 401 (the session may refresh) is RETRYABLE — the instance is kept, so the next joinRoom() asks again. status tells them apart (null = no answer).
invalid-target the caller passed an unusable target (both roomType and ticket, an empty id…).
not-ready switchRoom cannot even start: no Helix.init(), no world session, no world id or no resolvable API base.
switch-in-progress a switchRoom hop is still in flight (raised by a second switchRoom and by a joinRoom during the hop); the hop decides the outcome, this call changed nothing.
join-in-progress a joinRoom is still in flight: switchRoom was called under it, or a second joinRoom was (one join runs at a time); nothing changed.
cancelled leave() (or the shell's leave message) arrived while this join or hop was in flight. The caller is in NO room: a seat the call had already taken was released.
left the player has left this world (the shell's Exit / Back — see Helix.hasLeft()). Final for this world document: nothing was sent, and every later joinRoom() / switchRoom() is refused the same way. Checked before anything else.
join-failed anything else (transport, a refused seat reservation, an unmapped refusal).

The backend's own refusal code is what is matched (unknown-room-type, ticket-required, unknown-room-ticket, room-ticket-expired, room-ticket-used, room-instance-closed, unknown-room-instance) — never the HTTP status alone, so an unrelated 404 (world not found) stays join-failed instead of being misreported as a bad ticket.

HelixRoomLeaveReason

HelixRoomLeaveReason = "switch" | "leave" | "dropped"

Why a room handle's onLeave fired — see HelixRoom.onLeave.

HelixSession

HelixSession = object

Properties

expiresAt

expiresAt: string

scopes

scopes: string[]

token

token: string

trial?

optional trial?: HelixTrial

user

user: HelixUser

HelixUser

HelixUser = object

Properties

displayName

displayName: string | null

id

id: string

username

username: string

HelixVoiceDevice

HelixVoiceDevice = object

Properties

deviceId

deviceId: string

label

label: string

HelixVoiceMicMode

HelixVoiceMicMode = "ptt" | "open" | "muted"

HelixVoicePermission

HelixVoicePermission = "prompt" | "granted" | "denied"

HelixVoiceSettings

HelixVoiceSettings = object

Properties

micAutoSensitivity?

optional micAutoSensitivity?: boolean

True (default): no manual gate — transmit whatever the mic hears (browser noise suppression still applies).

micDeviceId?

optional micDeviceId?: string

Preferred audioinput deviceId — a hint; the world falls back to default when it no longer resolves.

micDeviceLabel?

optional micDeviceLabel?: string

The preferred mic's human label. deviceIds are origin-scoped, so when micDeviceId doesn't resolve where the mic is captured, the world re-targets the device whose label matches.

micMode

micMode: HelixVoiceMicMode

micSensitivity?

optional micSensitivity?: number

Manual input-sensitivity gate threshold in meter units (0..1): input below it is cut.

micVolume?

optional micVolume?: number

Outgoing mic gain, 0..2 (1 = as-captured, Discord-style 0–200%).

mutedUserIds

mutedUserIds: string[]

Platform userIds this player has locally muted. Always the full list, never a delta.

outputVolume?

optional outputVolume?: number

Incoming voice master gain, 0..2 (1 = as-received). Composes with the engine's proximity gain.

HelixVoiceState

HelixVoiceState = object

Properties

activeDeviceId?

optional activeDeviceId?: string

The device actually in use — may differ from the requested micDeviceId after fallback.

audioBlocked?

optional audioBlocked?: boolean

True until the one-time autoplay unlock gesture inside the world — while set, remote audio is silent AND the local microphone pipeline cannot run, so nothing is sent either.

available

available: boolean

False when this session has no voice (world lacks voice.* permission / no server configured).

channelId?

optional channelId?: string

The player's current exclusive voice channel (absent = the ambient space).

connected

connected: boolean

devices

devices: HelixVoiceDevice[]

error?

optional error?: string

micMode

micMode: HelixVoiceMicMode

permission

permission: HelixVoicePermission

pttKey?

optional pttKey?: string

Effective KeyboardEvent.key used by this world while push-to-talk is active.

speakingUserIds

speakingUserIds: string[]

Platform userIds currently speaking (muted-by-me and out-of-channel players never appear). Throttled world-side.

transmitting

transmitting: boolean

True while the local microphone's mode gate is open. In PTT this follows the held key; in open-mic mode it stays true. The live level remains the source of detected loudness.

HelixVoiceVec3

HelixVoiceVec3 = object

A world-space position/direction for spatial voice (three.js and WebAudio share right-handed axes).

Properties

x

x: number

y

y: number

z

z: number

HelixWorldContext

HelixWorldContext = object

Properties

id

id: string

slug

slug: string

title

title: string

InputMap

InputMap = Record<string, VerbBinding>

InventoryItem

InventoryItem = object

Properties

avatarSlot?

optional avatarSlot?: string | null

category?

optional category?: string

description?

optional description?: string | null

equipped?

optional equipped?: boolean

id?

optional id?: string

itemId

itemId: string

kind?

optional kind?: string

metadata?

optional metadata?: Record<string, unknown>

quantity

quantity: number

socket?

optional socket?: string | null

subCategory?

optional subCategory?: string | null

thumbnailUrl?

optional thumbnailUrl?: string | null

title

title: string

ItemEditionMode

ItemEditionMode = "standard" | "collectible"

LeaderboardEntry

LeaderboardEntry = object

Properties

displayName

displayName: string

score

score: number

source

source: string

subject

subject: string

updatedAt

updatedAt: string

LeaderboardOrder

LeaderboardOrder = "desc" | "asc"

LeaderboardPage

LeaderboardPage = object

Properties

entries

entries: LeaderboardEntry[]

truncated

truncated: boolean

LeaderboardSubmitOptions

LeaderboardSubmitOptions = object

Properties

order?

optional order?: LeaderboardOrder

LeaderboardSubmitResult

LeaderboardSubmitResult = object

Properties

best

best: number | null

updated

updated: boolean

LeaderboardTopOptions

LeaderboardTopOptions = object

Properties

limit?

optional limit?: number

order?

optional order?: LeaderboardOrder

ListenAdmissionResult

ListenAdmissionResult = object

Result of a listen host admitting one joiner's single-use join token. The player-owned host (profile listen) presents the joiner's token + a per-peer connection id; the shell holds the host capability and account JWT and performs the backend consume, returning this correlated result. The host admits the peer's connection ONLY when admitted is true.

Identity, not seat, is what admission certifies: on admitted: true the backend has verified the token and its ListenSeatRecord names the REAL HELIX user behind the join — returned here as joinerUserId. That field is REQUIRED when admitted is true, and a consuming runtime that receives an admitted receipt without it must FAIL CLOSED: treat the connection as unadmitted and never substitute an assumed identity (a seat id is not a user id). Refused receipts keep their shape — admitted: false + reason?, never a seatId or joinerUserId.

Properties

admitted

admitted: boolean

joinerUserId?

optional joinerUserId?: string

reason?

optional reason?: string

seatId?

optional seatId?: string

ListenCloseResult

ListenCloseResult = object

Result of a listen host closing its session (host departure closes the world; no migration).

Properties

closed

closed: boolean

releasedSeatIds

releasedSeatIds: string[]

ListenHeartbeatResult

ListenHeartbeatResult = object

Result of a listen host session heartbeat (session-level; the shell holds the capability).

Properties

expiresAt

expiresAt: string

status

status: "open" | "closed"

ListenReleaseResult

ListenReleaseResult = object

Result of a listen host reporting one admitted joiner's departure so the backend frees the seat. The shell authenticates the owning host and addresses the canonical disconnect route; released is the backend's verdict for THIS (seatId, connectionId) pair — false when the pair did not match an admission still standing (already departed, wrong connection, or session gone). Not an error: a departed peer is departed, and the host drops the peer either way.

Properties

released

released: boolean

MarketplaceListing

MarketplaceListing = object

Properties

category?

optional category?: string

description?

optional description?: string | null

isFree

isFree: boolean

itemId

itemId: string

kind?

optional kind?: string

listingId?

optional listingId?: string

Exact secondary listing capability used by purchaseListing().

priceLix

priceLix: number

thumbnailUrl?

optional thumbnailUrl?: string | null

title

title: string

MarketplaceQuery

MarketplaceQuery = object

Properties

category?

optional category?: string

kind?

optional kind?: string

limit?

optional limit?: number

search?

optional search?: string

MatchFound

MatchFound = object

A formed match: redeem ticketId with Helix.multiplayer.switchRoom({ ticket }) before expiresAt.

Properties

expiresAt

expiresAt: number

When the room ticket stops being redeemable, Unix epoch milliseconds in the PLATFORM's time (NaN if the backend's value is unreadable). The SDK judges it by the platform's clock as far as it knows it, not by the device clock alone; a device clock that is off makes Date.now() the wrong thing to compare it with.

instanceId

instanceId: string

roomType

roomType: string

ticketId

ticketId: string

The ROOM ticket to redeem — not the queue ticket.

ModeCapability

ModeCapability = "locomotion" | "cameraControl" | "defaultHud" | "interaction"

Portable interaction takeover primitive v0.3.

This module deliberately has no engine or renderer dependency. It owns stack ordering, validation, lifecycle, results and safety teardown; a trusted host owns the actual input, camera, locomotion and HUD integrations.

ModeEndReason

ModeEndReason = "released" | "popped" | "cleared" | "error"

ModePhase

ModePhase = "enter" | "exit" | "update" | "verb" | "covered" | "revealed"

ModuleEngagementStatus

ModuleEngagementStatus = "granted" | "denied" | "released" | "revoked"

ModuleWakeReason

ModuleWakeReason = "always-on" | "proximity" | "engagement" | "action" | "import" | "module" | "external"

NativeAvatarResourceProjection

NativeAvatarResourceProjection = object

Properties

descriptor

descriptor: Record<string, unknown>

kind

kind: NativeAvatarResourceRequest["kind"]

maxTextureSizes

maxTextureSizes: number[]

object

object: object

bytes

bytes: number

cid

cid: string

mediaType

mediaType: string

packagePin

packagePin: AvatarPackagePin

schema

schema: "helix.native-avatar-source-projection/1"

scratchContract

scratchContract: "finite-admission-required"

transport

transport: object

descriptor

descriptor: object

descriptor.bytes

bytes: number

descriptor.cid

cid: string

descriptor.mediaType

mediaType: string

grant?

optional grant?: object

grant.expiresAt

expiresAt: string

grant.packageRoot

packageRoot: AvatarPackagePin

grant.principalId

principalId: string

grant.sessionId

sessionId: string

grant.token

token: string

transportUrl

transportUrl: string

visibility

visibility: "public" | "private"

NativeAvatarResourceRequest

NativeAvatarResourceRequest = object & { objectCid: string; sourceUrl?: never; } | { objectCid?: never; sourceUrl: string; }

Server-measured source declarations; the native runtime still admits its decoder/parser allocations before reading the selected transport.

Type Declaration

kind

kind: "body" | "wardrobe" | "fallback" | "locomotion" | "emote" | "metadata"

maxTextureSizes

maxTextureSizes: number[]

packagePin

packagePin: AvatarPackagePin

PackageCustomizerSource

PackageCustomizerSource = Readonly<{ hostId: string; itemId: string; kind: "trial"; }>

Exact page-scoped vehicle trial identity; never an owned inventory identity.

PackageCustomizerSubject

PackageCustomizerSubject = object

Server-sealed, page-scoped package configuration for a local World customizer.

Properties

assignments

readonly assignments: Readonly<Record<string, string | null>>

Slot instance id to page-scoped package choice id; never inventory authority.

board

readonly board: Readonly<{ id: string; }>

equipBoard

readonly equipBoard: Readonly<Record<string, unknown>>

Existing shell EquipBoard projection, validated but intentionally not duplicated by the SDK.

hiddenSlotIds?

readonly optional hiddenSlotIds?: readonly string[]

hostId

readonly hostId: string

hostKind

readonly hostKind: string

kind

readonly kind: "package"

packageId

readonly packageId: string

renditions

readonly renditions: readonly Readonly<{ id: string; url: string; }>[]

version

readonly version: string

Party

Party = object

Properties

code?

optional code?: PartyCode

The party's current join code. Present only for the leader, and only while a code exists.

id

id: string

leaderId

leaderId: string

maxSize

maxSize: number

members

members: PartyMember[]

PartyCode

PartyCode = object

A code other players can type to join a party.

Properties

code

code: string

expiresAt

expiresAt: number

Unix epoch milliseconds (NaN if the backend's value is unreadable).

PartyInvite

PartyInvite = object

An invite this player has received and not yet answered.

Properties

expiresAt

expiresAt: number

Unix epoch milliseconds (NaN if the backend's value is unreadable).

from

from: PartyMember

id

id: string

partyId

partyId: string

PartyInviteReceipt

PartyInviteReceipt = object

What Helix.party.invite returns: the invite just sent.

Properties

expiresAt

expiresAt: number

Unix epoch milliseconds (NaN if the backend's value is unreadable).

inviteId

inviteId: string

PartyMember

PartyMember = object

Properties

displayName

displayName: string

userId

userId: string

PartyState

PartyState = object

The player's party (null when in none) and their pending incoming invites.

Properties

invites

invites: PartyInvite[]

party

party: Party | null

ProductGrant

ProductGrant = { itemId: string; kind: "item"; quantity?: number; } | { durationSeconds?: number; kind: "pass"; passKey?: string; } | { amount: number; code: string; display?: "wallet" | "uses"; kind: "currency"; }

PurchaseContext

PurchaseContext = object

Properties

balanceAfterLix

balanceAfterLix: number

balanceLix

balanceLix: number

creatorName?

optional creatorName?: string | null

description

description: string | null

distributionId?

optional distributionId?: string | null

editionMode?

optional editionMode?: ItemEditionMode

eligibilityStatus

eligibilityStatus: PurchaseStatus | null

eligible

eligible: boolean

endsAt?

optional endsAt?: string | null

grants?

optional grants?: ProductGrant[]

holdUntil?

optional holdUntil?: string | null

isFree

isFree: boolean

listingId?

optional listingId?: string | null

maxClaims?

optional maxClaims?: number | null

maxPerPlayer?

optional maxPerPlayer?: number | null

maxPerUser?

optional maxPerUser?: number | null

minted?

optional minted?: number | null

owned

owned: boolean

ownedCount

ownedCount: number

priceLix

priceLix: number

quantity?

optional quantity?: number

ref

ref: string

remaining?

optional remaining?: number | null

requiredVerificationLevel?

optional requiredVerificationLevel?: AccountVerificationLevel | null

resaleEligibleAt?

optional resaleEligibleAt?: string | null

sellerName?

optional sellerName?: string | null

serialNumber?

optional serialNumber?: number | null

startsAt?

optional startsAt?: string | null

supply?

optional supply?: number | null

thumbnailUrl

thumbnailUrl: string | null

title

title: string

totalPriceLix?

optional totalPriceLix?: number

unitPriceLix?

optional unitPriceLix?: number

verificationLevel?

optional verificationLevel?: AccountVerificationLevel

PurchaseOptions

PurchaseOptions = object

Properties

idempotencyKey?

optional idempotencyKey?: string

Stable caller-owned retry key. Omit to let the SDK persist one safely.

quantity?

optional quantity?: number

Whole-number quantity. Collectible listings always require exactly 1.

PurchaseResult

PurchaseResult = object

Properties

balanceAfterLix?

optional balanceAfterLix?: number

balanceLix?

optional balanceLix?: number

completed

completed: boolean

distributionId?

optional distributionId?: string | null

fulfilledQuantity?

optional fulfilledQuantity?: number

inventoryInstanceIds?

optional inventoryInstanceIds?: string[]

itemId?

optional itemId?: string | null

listingId?

optional listingId?: string | null

maxPerPlayer?

optional maxPerPlayer?: number | null

maxPerUser?

optional maxPerUser?: number | null

ownedCount?

optional ownedCount?: number

priceLix?

optional priceLix?: number

reason?

optional reason?: string

receipt?

optional receipt?: string

requestedQuantity?

optional requestedQuantity?: number

resaleEligibleAt?

optional resaleEligibleAt?: string | null

serialNumbers?

optional serialNumbers?: number[]

shortfallLix?

optional shortfallLix?: number

status

status: PurchaseStatus

PurchaseStatus

PurchaseStatus = "Pending" | "Granted" | "Claimed" | "AlreadyOwned" | "InsufficientFunds" | "MaxPerUserReached" | "ProductInactive" | "ProductNotFound" | "NotInWorld" | "Unauthorized" | "RateLimited" | "Cancelled" | "Failed" | "Timeout" | "NotFound" | "PriceChanged"

Quat

Quat = object

A rotation quaternion. Physics (dynamic-body) kinds only — kinematic kinds carry no orientation on the wire.

Properties

w

w: number

x

x: number

y

y: number

z

z: number

QueueEndReason

QueueEndReason = "cancelled" | "timeout" | "heartbeat-lapsed" | "member-absent" | "party-changed" | "build-changed" | "queue-removed" | "replaced" | "ended" | "heartbeat-lost" | "match-expired" | "refused" | "session-changed" | "left"

Why the queue ended. Absent on a none that never was a ticket, and after a match was redeemed.

Told by the platform (it says how the caller's ticket in this world closed, for 60 s afterwards):

cancelled cancelled by the player or a party member.
timeout the queue's own waiting limit ran out.
heartbeat-lapsed nobody on the ticket polled for 15 s.
member-absent one party member did not poll for 60 s (a closed or suspended tab).
party-changed the party changed while the ticket was waiting.
build-changed the world published a new build.
queue-removed the world no longer declares the queue.
replaced the player queued in another world, which replaces this ticket.
match-expired the match's room ticket ran out, or its room closed, before this player redeemed it. (The SDK also concludes this one itself: see below.)
ended a reason this SDK does not know; serverReason has the platform's word for it.

Concluded by the SDK, when the platform could not be asked (a platform reason is preferred when there is one):

heartbeat-lost no poll got through for 15 s, so the platform has cancelled the waiting ticket.
match-expired the match's room ticket ran out (by the platform's clock) without being redeemed.
refused the platform refused the poll for good (feature off, no permission, guest session).
session-changed the session ended or another player signed in.
left the world was left (the shell's leave message).

QueueStatus

QueueStatus = object

Where this player stands in matchmaking. none = not queued (never queued, cancelled, expired, or the match's room ticket was redeemed or ran out), with reason when the SDK concluded it. waiting carries queueId and, once the backend has reported it, waiting. matched carries match.

Properties

match?

optional match?: MatchFound

queueId?

optional queueId?: string

reason?

optional reason?: QueueEndReason

serverReason?

optional serverReason?: string

The platform's own reason, verbatim, whenever it gave one (also when reason recognised it).

status

status: "none" | "waiting" | "matched"

waiting?

optional waiting?: QueueWaiting

QueueWaiting

QueueWaiting = object

How full the forming match is.

Properties

needed

needed: number

Players the match needs.

players

players: number

Players currently eligible to be matched: those the matcher will actually use, i.e. whose every party member has polled recently. May be lower than the number of players who pressed the button.

ReplicaInput

ReplicaInput = Omit<StateMessage, "seq" | "tMs" | "teleportSeq">

ResolvedHelixMaterial

ResolvedHelixMaterial = HelixMaterialDefinition & object

Type Declaration

maps?

optional maps?: HelixMaterialMapPaths

Absolute URLs for the resolved resolution.

resolution?

optional resolution?: object

resolution.available

available: string[]

resolution.key

key: string

resolution.pixels

pixels: number | null

resolutions?

optional resolutions?: Record<string, HelixMaterialResolutionVariant>

Absolute URLs per declared variant, so a caller can switch tiers in place.

RoomInitValue

RoomInitValue = number | boolean | string

A scalar an openRoom effect may seed a declared roomVar / playerVar with (credential roomInit / playerInit).

RoomVarCollection

RoomVarCollection = number[] | string[] | boolean[] | RoomVarRecord[] | Record<string, number>

RoomVarRecord

RoomVarRecord = Record<string, number | string | boolean | Vec3>

Per-player/room/entity COLLECTION values (Tier 2 Phase 4.5.13 + P3 collections, spec §5). A list var reads as an ordered array — of a scalar element (number/string/boolean), a ref element (an id string), or a flat record ({field: scalar}, P3) — realized server-side as a colyseus ArraySchema; a counterMap var reads as a string→number record over its declared keys (a MapSchema). P3 also lets entities hold collections and broadcast payloads carry a collection snapshot. Mutated only via the dedicated effects (append/clear/addCount/removeAt/setField) + read via listLength/listAt/count — never a normal scalar expr/arg.

RoomVars

RoomVars = Record<string, RoomVarValue>

A declared bag of custom state — names + types are declared per-world; used for both room-level and per-player vars.

RoomVarValue

RoomVarValue = number | string | boolean | Vec3 | null | RoomVarCollection

The runtime value vocabulary for declared custom state. A ref-typed var's value is the id of a live member (a player's playerKey or an entity id) as a string, or null when unset/dangling — hence null is included. The DECLARATION vocabulary (VarType: number/string/boolean/vec3/ref + bounds) lives in @hypersoniclabs/helix-manifest (authored config, validated at publish); this is the wire value side.

RuntimeFidelityIntent

RuntimeFidelityIntent = object

Player presentation request frozen by the shell for one World load.

This intentionally carries no resolved tier, device capability, subsystem budget, physics setting, authority decision, tick rate, or network cadence. The engine resolves Auto and owns those policies.

Properties

renderScaleOverride

renderScaleOverride: RuntimeFidelityRenderScale | null

requestedVisualTier

requestedVisualTier: RuntimeFidelityVisualTier

runtimeProfileQuality

runtimeProfileQuality: RuntimeProfileQuality | null

version

version: typeof RUNTIME_FIDELITY_VERSION

RuntimeFidelityRenderScale

RuntimeFidelityRenderScale = typeof RUNTIME_FIDELITY_RENDER_SCALES[number]

RuntimeFidelityVisualTier

RuntimeFidelityVisualTier = typeof RUNTIME_FIDELITY_VISUAL_TIERS[number]

RuntimeProfileQuality

RuntimeProfileQuality = typeof RUNTIME_PROFILE_QUALITIES[number]

SavedPhoto

SavedPhoto = object

Properties

assetId

assetId: string

createdAt

createdAt: string

thumbnailUrl

thumbnailUrl: string

url

url: string

worldName

worldName: string

ServerMessageType

ServerMessageType = typeof ServerMessageType[keyof typeof ServerMessageType]

Server → client messages (the room sends these; SDK exposes them via room.onMessage(type, cb)).

StandardModeAction

StandardModeAction = "move" | "look" | "primary" | "secondary" | "tertiary" | "cancel"

SwitchRoomOptions

SwitchRoomOptions = Omit<JoinRoomOptions, "roomType" | "ticket">

The per-join knobs switchRoom forwards to the new room's join (everything joinRoom takes but the target).

SwitchRoomTarget

SwitchRoomTarget = { ticket: string; } | { preferInstanceId?: string; roomType?: string; }

Where Helix.multiplayer.switchRoom goes. Either a ticket to redeem, or a room type to matchmake into (omit roomType for the world's default room), optionally preferring one specific room instance.

Union Members

Type Literal

{ ticket: string; }

Type Literal

{ preferInstanceId?: string; roomType?: string; }

preferInstanceId?

optional preferInstanceId?: string

Try THIS room (a roomId) first, e.g. the lobby the player came from. Non-strict, unlike the shell's ?instance= on a first join: if the room is gone, full or locked the hop falls back to a normal matchmade join of the same type, and no helix:multiplayer-join-error is published.

roomType?

optional roomType?: string

An OPEN declared room type; omitted = the default room type.

TouchBinding

TouchBinding = TouchPresentation

Deprecated

Use TouchPresentation. Retained for the v0.2 consumer migration.

TouchKind

TouchKind = TouchPresentationKind

Deprecated

Use TouchPresentationKind. Retained for the v0.2 consumer migration.

TouchPresentationKind

TouchPresentationKind = "button" | "drag" | "tap" | "hold" | "stick" | "none"

TouchPresentationZone

TouchPresentationZone = "surface" | "primary" | "secondary" | "left" | "right"

VaultAnimationMetadata

VaultAnimationMetadata = VaultMetadataBase & object

Type Declaration

animation

animation: object

animation.clipCount

clipCount: number

animation.clips

clips: string[]

animation.durationSeconds

durationSeconds: number | null

animation.frameCount

frameCount: number | null

animation.framesPerSecond

framesPerSecond: number | null

animation.loop

loop: boolean

animation.rig

rig: string

animation.rootMotion

rootMotion: boolean

VaultArtifactMetadata

VaultArtifactMetadata = object

Properties

format

format: string

mimeType

mimeType: string

sourceBytes

sourceBytes: number

VaultArtifactReference

VaultArtifactReference = object

Properties

checksumSha256

checksumSha256: string | null

mimeType

mimeType: string

role

role: "primary" | string

sizeBytes

sizeBytes: number

url

url: string | null

VaultAssetDetail

VaultAssetDetail<K> = VaultAssetSummary<K> & object

Type Declaration

artifact

artifact: VaultResolvedArtifact

usedInWorlds

usedInWorlds: object[]

Type Parameters

K

K extends VaultAssetKind = VaultAssetKind

VaultAssetHandle

VaultAssetHandle = object

Properties

assetId

assetId: string

version

version: number

Immutable, one-based Vault version.

VaultAssetKind

VaultAssetKind = typeof VAULT_ASSET_KINDS[number]

VaultAssetSummary

VaultAssetSummary<K> = object

Type Parameters

K

K extends VaultAssetKind = VaultAssetKind

Properties

artifactMimeType

artifactMimeType: string | null

artifactSizeBytes

artifactSizeBytes: number | null

artifactUrl

artifactUrl: string | null

assetId

assetId: string

canonicalThumbnail

canonicalThumbnail: VaultCanonicalThumbnail | null

compatibility

compatibility: VaultCompatibility

contentRating

contentRating: string

contentRatingStatus

contentRatingStatus: string | null

createdAt

createdAt: string

creatorId

creatorId: string

currentVersion

currentVersion: number

description

description: string | null

kind

kind: K

lastUsedAt

lastUsedAt: string | null

license

license: "helix_standard" | "cc0" | "cc_by" | "all_rights_reserved"

metadata

metadata: VaultMetadataByKind[K]

origin

origin: "generated" | "uploaded"

selectionExplanation?

optional selectionExplanation?: VaultSelectionExplanation | null

slug

slug: string

source

source: "manual" | "dreamer" | "world_generation" | "import"

thumbnailGenerator

thumbnailGenerator: string | null

thumbnailUrl

thumbnailUrl: string | null

title

title: string

updatedAt

updatedAt: string

usageCount

usageCount: number

visibility

visibility: "public" | "private" | "held"

worldUsageCount

worldUsageCount: number

VaultAssetVersion

VaultAssetVersion = object

Properties

checksumSha256

checksumSha256: string | null

createdAt

createdAt: string

handle

handle: VaultAssetHandle

mimeType

mimeType: string

notes

notes: string | null

sizeBytes

sizeBytes: number

url

url: string | null

VaultAudioGenerationMode

VaultAudioGenerationMode = "sound_effect" | "music" | "text_to_speech"

Which ElevenLabs-backed mode produced this audio asset.

VaultAudioMetadata

VaultAudioMetadata = VaultMetadataBase & object

Type Declaration

audio

audio: object

Index Signature

[key: string]: unknown

audio.durationSeconds

durationSeconds: number | null

audio.format

format: string

audio.loop

loop: boolean

audio.measuredUsage?

optional measuredUsage?: object

Measured vendor usage/cost this specific generation was billed for.

audio.measuredUsage.creditsCharged

creditsCharged: number

audio.measuredUsage.measured

measured: boolean

audio.measuredUsage.providerCostUsd

providerCostUsd: number

audio.mode?

optional mode?: VaultAudioGenerationMode

Present on generated (ElevenLabs) assets; absent on uploads.

audio.model?

optional model?: string

audio.outputFormat?

optional outputFormat?: string

audio.voiceId?

optional voiceId?: string

Text-to-speech only.

VaultCanonicalThumbnail

VaultCanonicalThumbnail = object

Indexable

[key: string]: unknown

Properties

artifactChecksumSha256?

optional artifactChecksumSha256?: string

provenance?

optional provenance?: string

rendererVersion?

optional rendererVersion?: string

VaultCharacterMetadata

VaultCharacterMetadata = VaultMetadataBase & object

Type Declaration

character

character: object

character.boneCount

boneCount: number

character.meshCount

meshCount: number

character.skinned

skinned: boolean

character.triangleCount

triangleCount: number | null

VaultClient

VaultClient = object

Methods

createLoadPlan()

createLoadPlan(resolved): VaultLoadPlan

Parameters

resolved

VaultResolvedAsset

Returns

VaultLoadPlan

download()

download(handleOrAssetId, options?): Promise<VaultDownloadedArtifact>

Parameters

handleOrAssetId

string | VaultAssetHandle

options?

Pick<VaultInstallOptions, "verifyChecksum">

Returns

Promise<VaultDownloadedArtifact>

downloadArtifact()

downloadArtifact(reference, options?): Promise<VaultDownloadedArtifact>

Parameters

reference

VaultArtifactReference

options?

Pick<VaultInstallOptions, "verifyChecksum">

Returns

Promise<VaultDownloadedArtifact>

get()

get<K>(assetId): Promise<VaultAssetDetail<K>>

Type Parameters

K

Parameters

assetId

string

Returns

Promise<VaultAssetDetail<K>>

install()

install(handleOrAssetId, options?): Promise<VaultInstallResult>

Parameters

handleOrAssetId

string | VaultAssetHandle

options?

VaultInstallOptions

Returns

Promise<VaultInstallResult>

resolve()

resolve<K>(handleOrAssetId): Promise<VaultResolvedAsset<K>>

Type Parameters

K

Parameters

handleOrAssetId

string | VaultAssetHandle

Returns

Promise<VaultResolvedAsset<K>>

search()

search(query?): Promise<VaultSearchResult>

Parameters

query?

VaultSearchQuery

Returns

Promise<VaultSearchResult>

versions()

versions(assetId): Promise<VaultAssetVersion[]>

Parameters

assetId

string

Returns

Promise<VaultAssetVersion[]>

VaultClientOptions

VaultClientOptions = object

Properties

accessToken?

optional accessToken?: string | null | (() => string | null | Promise<string | null>)

apiBaseUrl

apiBaseUrl: string

HELIX API origin (the client appends /api/v1/vault) or a full Vault API base ending in /api/v1/vault.

fetch?

optional fetch?: typeof fetch

sha256?

optional sha256?: (bytes) => Promise<string>

Optional portable SHA-256 implementation; output must be lowercase hex.

Parameters

bytes

ArrayBuffer

Returns

Promise<string>

VaultCompatibility

VaultCompatibility = object

Properties

engines?

optional engines?: VaultRuntime[]

skeleton?

optional skeleton?: string

skeletonBonesMatched?

optional skeletonBonesMatched?: number

skeletonVerification?

optional skeletonVerification?: "verified" | "declared" | string

system?

optional system?: string

VaultDecalMetadata

VaultDecalMetadata = VaultMetadataBase & object

Type Declaration

decal

decal: object

decal.blendMode

blendMode: "normal" | "multiply" | "additive"

decal.heightMeters

heightMeters: number

decal.projection

projection: "planar" | "box"

decal.widthMeters

widthMeters: number

VaultDownloadedArtifact

VaultDownloadedArtifact = object

Properties

bytes

bytes: ArrayBuffer

checksumVerified

checksumVerified: boolean

reference

reference: VaultArtifactReference

VaultEnvironmentMetadata

VaultEnvironmentMetadata = VaultMetadataBase & object

Type Declaration

environment

environment: object

environment.dimensionsMeters?

optional dimensionsMeters?: [number, number, number] | null

environment.materialCount?

optional materialCount?: number

environment.meshCount?

optional meshCount?: number

environment.representation

representation: "mesh" | "gaussian-splat"

environment.scope?

optional scope?: "environment"

environment.triangleCount?

optional triangleCount?: number

gaussianSplat?

optional gaussianSplat?: VaultGaussianSplatMetadata["gaussianSplat"]

VaultGaussianSplatMetadata

VaultGaussianSplatMetadata = VaultMetadataBase & object

Type Declaration

gaussianSplat

gaussianSplat: object

gaussianSplat.boundsMeters

boundsMeters: [number, number, number] | null

gaussianSplat.capture

capture: object

gaussianSplat.capture.metersPerUnit

metersPerUnit: number

gaussianSplat.capture.provider

provider: unknown

gaussianSplat.capture.source

source: unknown

gaussianSplat.capture.upAxis

upAxis: "x" | "y" | "z"

gaussianSplat.compression

compression: object

gaussianSplat.compression.format

format: "spz"

gaussianSplat.compression.level

level: unknown

gaussianSplat.format

format: "spz"

gaussianSplat.lodCount

lodCount: number

gaussianSplat.performance

performance: object

gaussianSplat.performance.downloadBytes

downloadBytes: number

gaussianSplat.performance.memoryBytes

memoryBytes: number | null

gaussianSplat.pointCount

pointCount: number | null

gaussianSplat.pointDensityPerCubicMeter

pointDensityPerCubicMeter: number | null

gaussianSplat.quality

quality: "mobile" | "balanced" | "high" | "cinematic" | "unverified"

gaussianSplat.scope

scope: VaultSplatScope

gaussianSplat.sphericalHarmonicsDegree

sphericalHarmonicsDegree: number | null

VaultImmutableArtifactReference

VaultImmutableArtifactReference = VaultAssetHandle & object

Type Declaration

checksumSha256

checksumSha256: string

VaultInstallOptions

VaultInstallOptions = object

Properties

relatedRoles?

optional relatedRoles?: string[]

Related rendition roles to fetch. Omit to fetch no related artifacts.

verifyChecksum?

optional verifyChecksum?: boolean

Defaults to true whenever the server supplied a checksum.

VaultInstallResult

VaultInstallResult = object

Properties

asset

asset: VaultResolvedAsset

plan

plan: VaultLoadPlan

primary

primary: VaultDownloadedArtifact

related: VaultDownloadedArtifact[]

VaultLoadPlan

VaultLoadPlan = { handle: VaultAssetHandle; loader: "gltf"; primary: VaultArtifactReference; purpose: "prop" | "character" | "animation" | "environment" | "terrain"; related: VaultArtifactReference[]; } | { handle: VaultAssetHandle; loader: "image"; primary: VaultArtifactReference; purpose: "texture" | "decal"; related: VaultArtifactReference[]; } | { handle: VaultAssetHandle; loader: "audio"; primary: VaultArtifactReference; purpose: "audio"; related: VaultArtifactReference[]; } | { format: "hdr" | "exr"; handle: VaultAssetHandle; loader: "hdr-environment"; primary: VaultArtifactReference; purpose: "sky"; related: VaultArtifactReference[]; } | { format: "spz"; handle: VaultAssetHandle; loader: "gaussian-splat"; primary: VaultArtifactReference; purpose: "gaussian_splat" | "environment"; related: VaultArtifactReference[]; scope: VaultSplatScope; } | { handle: VaultAssetHandle; loader: "helix-descriptor"; primary: VaultArtifactReference; purpose: "material" | "scene" | "terrain" | "vfx" | "sky"; related: VaultArtifactReference[]; schema: "helix-material@1" | "helix-scene@1" | "helix-terrain@1" | "helix-vfx@1" | "helix-sky@1"; }

VaultMaterialMetadata

VaultMaterialMetadata = VaultMetadataBase & object

Type Declaration

material

material: object

material.mapSemantics

mapSemantics: string[]

material.materialId

materialId: string

material.materialType

materialType: "pbr" | "procedural_glass" | "procedural_water"

material.schemaVersion

schemaVersion: string

VaultMetadataByKind

VaultMetadataByKind = object

Properties

animation

animation: VaultAnimationMetadata

audio

audio: VaultAudioMetadata

character

character: VaultCharacterMetadata

decal

decal: VaultDecalMetadata

environment

environment: VaultEnvironmentMetadata

gaussian_splat

gaussian_splat: VaultGaussianSplatMetadata

material

material: VaultMaterialMetadata

prop

prop: VaultPropMetadata

scene

scene: VaultSceneMetadata

sky

sky: VaultSkyMetadata

terrain

terrain: VaultTerrainMetadata

texture

texture: VaultTextureMetadata

unreal_package

unreal_package: VaultUnrealPackageMetadata

vfx

vfx: VaultVfxMetadata

VaultPerformanceMetadata

VaultPerformanceMetadata = object

Properties

costScore

costScore: number | null

downloadBytes

downloadBytes: number

drawCalls?

optional drawCalls?: number

maxTextureEdge?

optional maxTextureEdge?: number

memoryBytes?

optional memoryBytes?: number | null

qualityScore

qualityScore: number | null

rankingSignals

rankingSignals: string[]

tier

tier: VaultPerformanceTier

triangles?

optional triangles?: number

VaultPerformanceTier

VaultPerformanceTier = "mobile" | "desktop" | "cinematic" | "unknown"

VaultPropMetadata

VaultPropMetadata = VaultMetadataBase & object

Type Declaration

prop

prop: object

Index Signature

[key: string]: unknown

prop.coordinateSystem

coordinateSystem: string

prop.dimensionsMeters

dimensionsMeters: [number, number, number]

prop.fileSizeBytes

fileSizeBytes: number

prop.limits

limits: object

Index Signature

[key: string]: unknown

prop.limits.generated

generated: boolean

prop.limits.maxFileBytes

maxFileBytes: number

prop.limits.maxTextureEdge

maxTextureEdge: number

prop.lods

lods: object[]

prop.materialCount

materialCount: number

prop.maxTextureEdge

maxTextureEdge: number

prop.static

static: true

prop.triangleCount

triangleCount: number

prop.units

units: "meters" | string

VaultRankMode

VaultRankMode = "relevance" | "performance" | "reuse"

VaultRelatedArtifact

VaultRelatedArtifact = object

Properties

checksumSha256

checksumSha256: string | null

mimeType

mimeType: string

role

role: string

sizeBytes

sizeBytes: number

url

url: string | null

VaultResolvedArtifact

VaultResolvedArtifact = object

Properties

assetId

assetId: string

checksumSha256

checksumSha256: string | null

mimeType

mimeType: string

relatedArtifacts

relatedArtifacts: VaultRelatedArtifact[]

sizeBytes

sizeBytes: number

url

url: string | null

urlKind

urlKind: "cdn" | "unavailable"

version

version: number

VaultResolvedAsset

VaultResolvedAsset<K> = object

Type Parameters

K

K extends VaultAssetKind = VaultAssetKind

Properties

artifact

artifact: VaultResolvedArtifact

asset

asset: VaultAssetDetail<K>

handle

handle: VaultAssetHandle

relatedArtifactsComplete

relatedArtifactsComplete: boolean

False only for a historical version: the backend currently exposes related artifacts on current-version detail, not version-history rows.

VaultRuntime

VaultRuntime = "web" | "unreal"

VaultSceneMetadata

VaultSceneMetadata = VaultMetadataBase & object

Type Declaration

scene

scene: object

scene.budget

budget: object

scene.budget.basis

basis: "server-resolved-immutable-artifacts"

scene.budget.costScore

costScore: number

scene.budget.derivedTotals

derivedTotals: object

scene.budget.derivedTotals.decodedTextureMemoryBytes

decodedTextureMemoryBytes: number

scene.budget.derivedTotals.drawCalls

drawCalls: number

scene.budget.derivedTotals.particles

particles: number

scene.budget.derivedTotals.triangles

triangles: number

scene.budget.derivedTotals.uniqueMaterials

uniqueMaterials: number

scene.budget.deviceTier

deviceTier: "mobile" | "desktop" | "cinematic"

scene.budget.limits

limits: object

scene.budget.limits.decodedTextureMemoryBytes

decodedTextureMemoryBytes: number

scene.budget.limits.drawCalls

drawCalls: number

scene.budget.limits.particles

particles: number

scene.budget.limits.triangles

triangles: number

scene.budget.limits.uniqueMaterials

uniqueMaterials: number

scene.budget.withinBudget

withinBudget: true

scene.nodeCount

nodeCount: number

scene.references

references: VaultImmutableArtifactReference & object[]

scene.runtimeBundles

runtimeBundles: object[]

scene.schemaVersion

schemaVersion: string

VaultSearchQuery

VaultSearchQuery = object

Properties

creatorId?

optional creatorId?: string

engine?

optional engine?: VaultRuntime

format?

optional format?: string

kind?

optional kind?: VaultAssetKind | VaultAssetKind[]

license?

optional license?: VaultAssetSummary["license"]

limit?

optional limit?: number

origin?

optional origin?: VaultAssetSummary["origin"]

page?

optional page?: number

performanceTier?

optional performanceTier?: VaultPerformanceTier

q?

optional q?: string

rank?

optional rank?: VaultRankMode

scope?

optional scope?: VaultSplatScope

skeleton?

optional skeleton?: "humanoid" | "quadruped"

source?

optional source?: VaultAssetSummary["source"]

subtype?

optional subtype?: string

VaultSearchResult

VaultSearchResult = object

Properties

items

items: VaultAssetSummary[]

totalItems

totalItems: number

VaultSelectionExplanation

VaultSelectionExplanation = object

Properties

availability

availability: object

performanceMeasured

performanceMeasured: boolean

qualityMeasured

qualityMeasured: boolean

reuseObserved

reuseObserved: boolean

hardFilters

hardFilters: Record<string, unknown>

lexical

lexical: object

matchedFields

matchedFields: string[]

matchedTerms

matchedTerms: string[]

performance

performance: object

costScore

costScore: number | null

qualityScore

qualityScore: number | null

tier

tier: VaultPerformanceTier | null

rankMode

rankMode: VaultRankMode

reuse

reuse: object

lastUsedAt

lastUsedAt: string | null

usageCount

usageCount: number

worldUsageCount

worldUsageCount: number

VaultSkyMetadata

VaultSkyMetadata = VaultMetadataBase & object

Type Declaration

sky

sky: object

sky.backdropRenditions

backdropRenditions: unknown[]

sky.channelsSeparated

channelsSeparated: true

sky.colorSpace

colorSpace: "linear-srgb" | "acescg"

sky.dynamicRangeStops

dynamicRangeStops: number

sky.exposureEv

exposureEv: number

sky.lightingRenditions

lightingRenditions: unknown[]

sky.projection

projection: "equirectangular" | "cubemap"

sky.resolution

resolution: object

sky.resolution.height

height: number

sky.resolution.width

width: number

sky.schemaVersion

schemaVersion: string

sky.sourceFormat

sourceFormat: "hdr" | "exr"

VaultSplatScope

VaultSplatScope = "object" | "environment"

VaultTerrainMetadata

VaultTerrainMetadata = VaultMetadataBase & object

Type Declaration

terrain

terrain: object

terrain.dimensionsMeters

dimensionsMeters: [number, number, number] | null

terrain.representation

representation: "heightmap" | "mesh"

terrain.schemaVersion?

optional schemaVersion?: string

terrain.sourceFormat?

optional sourceFormat?: "png16" | "raw16" | "exr" | "glb"

terrain.triangleCount?

optional triangleCount?: number | null

VaultTextureMetadata

VaultTextureMetadata = VaultMetadataBase & object

Type Declaration

texture

texture: object

texture.colorSpace

colorSpace: "srgb" | "linear" | "unspecified"

texture.semantic

semantic: "albedo" | "normal" | "roughness" | "metallic" | "ambient-occlusion" | "emissive" | "height" | "mask" | "unspecified"

VaultUnrealPackageMetadata

VaultUnrealPackageMetadata = VaultMetadataBase

VaultVfxMetadata

VaultVfxMetadata = VaultMetadataBase & object

Type Declaration

vfx

vfx: object

vfx.beam

beam: { blendMode: "alpha" | "additive" | "multiply"; lengthMeters: [number, number]; maxSegments: number; noiseAmplitudeMeters: number; textureRole: string; widthMeters: [number, number]; } | null

vfx.boundsMeters

boundsMeters: [number, number, number]

vfx.decodedTextureMemoryBytes

decodedTextureMemoryBytes: number

vfx.deviceTier

deviceTier: "mobile" | "desktop" | "cinematic"

vfx.drawCalls

drawCalls: number

vfx.effectType

effectType: "particle" | "beam" | "trail" | "flipbook"

vfx.flipbook

flipbook: { blendMode: "alpha" | "additive" | "multiply"; sizeMeters: [number, number]; textureRole: string; } | null

vfx.limits

limits: object

vfx.limits.beamLengthMeters

beamLengthMeters: number

vfx.limits.beamSegments

beamSegments: number

vfx.limits.boundsMeters

boundsMeters: number

vfx.limits.lifetimeSeconds

lifetimeSeconds: number

vfx.limits.maxParticles

maxParticles: number

vfx.limits.sizeMeters

sizeMeters: number

vfx.limits.spawnRatePerSecond

spawnRatePerSecond: number

vfx.limits.speedMetersPerSecond

speedMetersPerSecond: number

vfx.limits.trailPoints

trailPoints: number

vfx.loop

loop: boolean

vfx.maxParticles

maxParticles: number

vfx.particle

particle: { billboard: "camera" | "velocity" | "world"; blendMode: "alpha" | "additive" | "multiply"; lifetimeSeconds: [number, number]; shape: "point" | "sphere" | "box" | "cone"; sizeMeters: [number, number]; spawnRatePerSecond: number; speedMetersPerSecond: [number, number]; textureRole: string; } | null

vfx.portability

portability: "renderer-neutral-contract-draft"

vfx.runtimeCompatibility

runtimeCompatibility: VaultRuntime[]

vfx.schemaVersion

schemaVersion: string

vfx.textures

textures: object[]

vfx.trail

trail: { blendMode: "alpha" | "additive" | "multiply"; lifetimeSeconds: number; maxPoints: number; minVertexDistanceMeters: number; textureRole: string; widthMeters: [number, number]; } | null

Vec3

Vec3 = object

Properties

x

x: number

y

y: number

z

z: number

VehicleRole

VehicleRole = "owner" | "driver" | "occupant" | "nearby"

VerbHandler

VerbHandler = (event, verb) => void

Parameters

event

verb

string

Returns

void

VerbPhase

VerbPhase = "start" | "end" | "repeat"

VerbSink

VerbSink = (verb, event) => void

Parameters

verb

string

event

DeviceDefinitionReference

Returns

void

WorldDeviceDefinitionResolver

WorldDeviceDefinitionResolver = (reference) => Promise<DeviceDefinitionV1>

Parameters

reference

Returns

Promise<DeviceDefinitionV1>

Variables

ANY_VERB

const ANY_VERB: "*" = "*"

ATTACHMENT_LIMITS

const ATTACHMENT_LIMITS: object

Structural bounds on the attachment set — enforced by the ROOM on AttachmentsMessage and mirrored by the ENGINE facade before sending, so a set that attaches locally is a set that replicates.

Type Declaration

idPattern

readonly idPattern: RegExp

maxAssetUrlLength

readonly maxAssetUrlLength: 512

maxAttachments

readonly maxAttachments: 8

maxIdLength

readonly maxIdLength: 32

maxOffsetM

readonly maxOffsetM: 2

Per-axis |offset| bound, METERS — grip tuning, not teleportation.

maxPresetLength

readonly maxPresetLength: 32

maxSocketNameLength

readonly maxSocketNameLength: 64

socketNamePattern

readonly socketNamePattern: RegExp

CAMERA_CAPABILITY_FLAGS

const CAMERA_CAPABILITY_FLAGS: readonly CameraCapabilityFlag[]

CAMERA_LENS_PRESETS

const CAMERA_LENS_PRESETS: readonly [0.5, 1, 2, 3, 5]

The lens buttons, in the exact order HELIX OS renders them.

These are PRESETS, not the zoom domain: effective zoom is CONTINUOUS between the first and last entry, and a preset is only where a tap lands. A runtime that clamps to these five is wrong.

CAMERA_MAX_ZOOM

const CAMERA_MAX_ZOOM: number

CAMERA_MIN_ZOOM

const CAMERA_MIN_ZOOM: number

The continuous zoom range: everything between the first and last lens preset.

ClientMessageType

const ClientMessageType: object

Type Declaration

Ability

readonly Ability: "ability"

Activate or deactivate an ability on this player (the built-in, engine-level intent).

Action

readonly Action: "action"

A world-authored declared action (the generic extensibility channel — see ActionMessage).

Attachments

readonly Attachments: "attachments"

Replace this player's full prop-attachment set (v20 — see AttachmentsMessage; pure synced state, no relay).

AvatarRefresh

readonly AvatarRefresh: "avatarRefresh"

Ask the room to re-resolve this player's avatar (v23 — see AvatarRefreshMessage; hint only, empty payload).

EmoteJoin

readonly EmoteJoin: "emoteJoin"

Join (or leave) another player's paired emote (v28 — see EmoteJoinMessage; a request the room may refuse silently).

EmoteRefresh

readonly EmoteRefresh: "emoteRefresh"

Ask the room to re-resolve this player's emote set (v28 — see EmoteRefreshMessage; hint only, empty payload).

EntityState

readonly EntityState: "entityState"

An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c — see EntityStateMessage).

EntityStateBatch

readonly EntityStateBatch: "entityStateBatch"

A BATCH of owner-authoritative entity uploads for this tick — ALL the entities this connection hosts in one message (Tier 2 Phase 4.10 — see EntityStateBatchMessage). The per-connection rate cap counts MESSAGES, so a host of N entities must batch (one message/tick) instead of N single EntityState messages, or it starves its own upload budget. EntityScene uses this; the single EntityState stays for one-off uploads (e.g. a flag).

Gesture

readonly Gesture: "gesture"

Play/stop a gesture on this player's character (v19 — see GestureMessage; oneshots relay, loops sync as state).

Ping

readonly Ping: "ping"

Clock-sync probe: the client's local timestamp, which the room echoes in a Pong (RTT + offset).

PurchaseReceipt

readonly PurchaseReceipt: "purchaseReceipt"

Forward a backend-minted purchase receipt to the room (v22 — see PurchaseReceiptMessage; opaque JWT, room-verified).

State

readonly State: "state"

The player's predicted kinematic state for this tick (seq-tagged for reconciliation).

CONTRACT_VERSION

const CONTRACT_VERSION: 34

Wire format version. Bump on any incompatible change to PlayerReplicaState, the message table, the credential claims, or the realized declared-state shape (roomVars / per-player vars / entities).

The SDK sends this in its join options; the room compares it in onAuth and LOGS a mismatch (P1.C2) — it does NOT reject. The SDK is frozen into each published bundle, so a newer room must keep admitting older builds; rejecting on mismatch would brick every published world on a bump. The detection is for cross-version diagnostics, and contract changes are kept additive/forward so older clients still play.

That forward-compatibility is ONE-WAY: a NEWER client on an OLDER room is not safe when the bump added a client→server message type — Colyseus routes an unregistered type to __no_message_handler, which outside devMode leaves the sender (client.leave WITH_ERROR). Deploy the room BEFORE any world republishes on a newer SDK; a version whose bump is state/claims-only has no such ordering constraint.

DEFAULT_MATERIAL_PACK_SLUG

const DEFAULT_MATERIAL_PACK_SLUG: "helix-materials" = "helix-materials"

DEFAULT_PUSH_TO_TALK_KEY

const DEFAULT_PUSH_TO_TALK_KEY: "n" = "n"

Platform default for KeyboardEvent.key while push-to-talk is active.

DISTRIBUTION_CAPABILITY_MESSAGE

const DISTRIBUTION_CAPABILITY_MESSAGE: "distributionCapability" = "distributionCapability"

ADR-0003 World routes (item distributions with channel world). A seated player asks its room for a one-time acquisition capability for ONE route of the room's world; the room mints it against the backend with its room token and the SEAT's account, and answers only the asker. The capability then rides POST /iwp/purchase. Bare string names, deliberately outside ClientMessageType: the room owns this lane (helix-colyseus-server DISTRIBUTION_CAPABILITY_MESSAGE / _RESULT), and an older room simply never answers.

DISTRIBUTION_CAPABILITY_RESULT

const DISTRIBUTION_CAPABILITY_RESULT: "distributionCapabilityResult" = "distributionCapabilityResult"

DREAMER_AUDIO_TIMEOUT_MS

const DREAMER_AUDIO_TIMEOUT_MS: number

EMOTE_LIMITS

const EMOTE_LIMITS: object

Structural bounds on a player's carried emote set (v28) — enforced by the ROOM when it writes the seat's PlayerState.emotes. Unlike ATTACHMENT_LIMITS these bound a SERVER-resolved set, not an inbound message: the platform is the source, and the room still bounds it so a bad catalog row can't put an unbounded string (or a url a secure page would refuse to load) into replicated state. A clip URL must be SERVABLE — https anywhere, plus http on loopback so a dev stack's own artifact URLs survive (the room mirrors the backend's isServableClipUrl). Over-count, over-length, unservable and unknown-slot entries are dropped silently, never fatally; an unservable audio costs only the sound, since the clip is the emote.

Type Declaration

maxClipUrlLength

readonly maxClipUrlLength: 512

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.

maxEntries

readonly maxEntries: 10

One per wheel slot ('r0'..'r7' + sit + lie) — the set cannot be larger than the wheel it plays from.

maxLabelLength

readonly maxLabelLength: 64

Bounds the wheel petal's display title.

maxOfferAtS

readonly maxOfferAtS: 600

Ceiling on EmoteEntry.roles.offerAtS, SECONDS — a sanity bound sitting far above any emote clip, since the REAL bound is the initiator clip's own length and only publish can know it (the room just clamps ≥ 0 to this).

maxPairOffsetM

readonly maxPairOffsetM: 3

PAIRED emotes: per-axis |offset| bound on EmoteEntry.roles, METERS in the initiator-local frame. A pair is two people arm's length apart (a handshake, a hug, a high-five) — the room CLAMPS to this rather than dropping the roles, because an over-reaching catalog row should cost composition, not the whole paired emote.

FINAL_REST_REPLY

const FINAL_REST_REPLY: "__helix:finalRest" = "__helix:finalRest"

Additive opt-in on existing action/ping/entity channels; no manifest capability.

FINAL_REST_TIMEOUT_MS

const FINAL_REST_TIMEOUT_MS: 120000 = 120000

finalRestId

const finalRestId: (v) => v is string

Parameters

v

unknown

Returns

v is string

finalRestScopeKey

const finalRestScopeKey: (group, scope?) => string

Parameters

group

string

scope?

FinalRestScope

Returns

string

finalRestSequence

const finalRestSequence: (v) => v is number

Parameters

v

unknown

Returns

v is number

GESTURE_LIMITS

const GESTURE_LIMITS: object

Structural bounds on gesture clip names — enforced by the ROOM on GestureMessage (bounds/charset hygiene, never vocabulary: names are opaque world data) AND by the ENGINE's pose-DSL compiler at registration, so a name that registers is always a name that replicates. Identifier-ish charset: starts alphanumeric, then alphanumerics plus _ - . : — printable, unambiguous as a registry key, safe in synced state.

Type Declaration

clipNamePattern

readonly clipNamePattern: RegExp

maxClipNameLength

readonly maxClipNameLength: 64

Helix

const Helix: HelixSdk

IK_LIMITS

const IK_LIMITS: object

Plausibility bounds on the v21 IK targets — enforced by the ROOM on StateMessage (an out-of-bounds target invalidates the whole upload, like any other bad state field) and mirrored by the ENGINE facade before sending. Distances are measured from the SAME message's position (world METERS), so the bound tracks the player instead of being a useless absolute world-coordinate cap.

Type Declaration

maxLookDistanceM

readonly maxLookDistanceM: 50

Max |lookTarget − position| — interaction gaze range, not a landmark stare.

maxReachDistanceM

readonly maxReachDistanceM: 3

Max |reach − position| — generous arm's length for any plausible rig scale.

isCameraControlTarget

const isCameraControlTarget: (v) => v is CameraControlTarget

Parameters

v

unknown

Returns

v is CameraControlTarget

isCameraDroneLockMode

const isCameraDroneLockMode: (v) => v is CameraDroneLockMode

Parameters

v

unknown

Returns

v is CameraDroneLockMode

isCameraFilterId

const isCameraFilterId: (v) => v is CameraFilterId

Parameters

v

unknown

Returns

v is CameraFilterId

isCameraMediaMode

const isCameraMediaMode: (v) => v is CameraMediaMode

Parameters

v

unknown

Returns

v is CameraMediaMode

isCameraSessionState

const isCameraSessionState: (v) => v is CameraSessionState

Parameters

v

unknown

Returns

v is CameraSessionState

isCameraSpatialMode

const isCameraSpatialMode: (v) => v is CameraSpatialMode

Parameters

v

unknown

Returns

v is CameraSpatialMode

isCameraTimerSeconds

const isCameraTimerSeconds: (v) => v is CameraTimerSeconds

Parameters

v

unknown

Returns

v is CameraTimerSeconds

MAX_MESSAGE_BYTES

const MAX_MESSAGE_BYTES: 12288 = 12288

Hard payload bound the room rejects above (defense against oversized frames), measured on the JSON form (a cheap proxy; the msgpack wire is smaller). Sized (P1.B4) to admit a full EntityStateBatch — MAX_ENTITIES_PER_OWNER (128) entities with modest vars in one message (≈75 JSON bytes/entry) — so the byte cap and the per-owner entity cap don't disagree. MUST stay below the Colyseus transport maxPayload (16 KB, helix-colyseus-server src/index.ts) in WIRE terms, so the room's reject fires before the transport drops the frame / closes the socket. A var-heavy batch past this is a CLEAN DROP (the room's guard does not strike on an over-byte payload), never a kick.

MESSAGE_RATE

const MESSAGE_RATE: object

Per-connection rate ceilings (messages/second) the room enforces; over-rate clients are dropped. State is the throttled input channel (plan D3); ability is bursty but bounded.

stateHz/entityStateHz are the DEFAULT per-connection upload cadence. A world may raise BOTH to maxUploadHz via multiplayer.uploadHz: 20 — the room derives the actual ceiling from the trusted configUrl, the client from its bundled manifest, so they agree without a handshake (a client that lies is simply rate-limited). Sending under the cap is always legal, so this is purely a cap → no CONTRACT_VERSION bump. SYNC: the {10, 20} tier set mirrors the manifest's MULTIPLAYER_CAPS.uploadHzAllowed — widen in lockstep.

Type Declaration

abilityHz

readonly abilityHz: 20

actionHz

readonly actionHz: 20

attachmentsHz

readonly attachmentsHz: 4

avatarRefreshHz

readonly avatarRefreshHz: 1

emoteJoinHz

readonly emoteJoinHz: 2

emoteRefreshHz

readonly emoteRefreshHz: 1

entityStateHz

readonly entityStateHz: 10

gestureHz

readonly gestureHz: 5

maxUploadHz

readonly maxUploadHz: 20

pingHz

readonly pingHz: 4

purchaseReceiptHz

readonly purchaseReceiptHz: 2

stateHz

readonly stateHz: 10

MODULE_FINAL_REST_SNAPSHOT

const MODULE_FINAL_REST_SNAPSHOT: "__helix:moduleFinalRestSnapshot" = "__helix:moduleFinalRestSnapshot"

A separate channel prevents old global consumers from applying module-local transforms.

MOVEMENT_GATE

const MOVEMENT_GATE: object

Movement-plausibility gate — the canonical home for the bound the colyseus room ENFORCES and the engine's client-side upload clamp MIRRORS, so both compute the SAME bound from the SAME inputs and never disagree. A frame moving more than maxSpeed × Δt × toleranceMul from the last accepted position is implausible: the server holds + acks it, the client pre-clamps its upload to stay inside it. Δt is the SANITIZED real send-interval (the source-time posT delta — clamped, spoof-bounded; see nextSourceTime), NOT integer ticks — time-based so the gate is cadence-agnostic and a non-tick-aligned send rate can't quantize the budget away. This is a SANITY bound (anti-teleport), not cheat-proof movement (Tier 3). The room imports this; the standalone engine mirrors the two values (it takes no SDK build dep — same SYNC pattern as the declared-state mirror) → keep them in lockstep.

Type Declaration

graceMs

readonly graceMs: 250

impulseMul

readonly impulseMul: 6

maxCatchupMs

readonly maxCatchupMs: 300

ownerEntityToleranceMul

readonly ownerEntityToleranceMul: 3

toleranceMul

readonly toleranceMul: 1.25

RECEIPT_LIMITS

const RECEIPT_LIMITS: object

Structural bound on the forwarded receipt — MAX_MESSAGE_BYTES is otherwise the only ceiling, so without this an oversize receipt would be a mystery drop instead of a documented reject at the sender.

Type Declaration

maxReceiptLength

readonly maxReceiptLength: 4096

RESERVED_MESSAGE_TYPES

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"]

Wire message-type names a world's declared event/action names MUST NOT shadow — the fixed client→server and server→client channels that are themselves legal declared names. The manifest validator rejects a declared name in this set so a broadcast can't collide with pong (or confuse the fixed channels). Internal __helix:* channels are outside the declared-name grammar and need no reservation. Inlined in @hypersoniclabs/helix-manifest with a cross-ref (the manifest takes no SDK dependency); keep the two in sync.

ROOM_CREDENTIAL_AUDIENCE

const ROOM_CREDENTIAL_AUDIENCE: "helix-instant-room"

RUNTIME_FIDELITY_RENDER_SCALES

const RUNTIME_FIDELITY_RENDER_SCALES: readonly ["1.5", "1", "0.77", "0.59"]

RUNTIME_FIDELITY_VERSION

const RUNTIME_FIDELITY_VERSION: 1

Additive, versioned presentation intent carried on helix:init.

RUNTIME_FIDELITY_VISUAL_TIERS

const RUNTIME_FIDELITY_VISUAL_TIERS: readonly ["auto", "minimal", "low", "medium", "high", "ultra"]

RUNTIME_PROFILE_QUALITIES

const RUNTIME_PROFILE_QUALITIES: readonly ["minimum", "balanced", "high", "ultra"]

sameFinalRestScope

const sameFinalRestScope: (a?, b?) => boolean

Parameters

a?

FinalRestProvenance

b?

FinalRestProvenance

Returns

boolean

ServerMessageType

const ServerMessageType: object

Server → client messages (the room sends these; SDK exposes them via room.onMessage(type, cb)).

Type Declaration

EntityStateAck

readonly EntityStateAck: "entityStateAck"

A2 reconnection ack — the owner-hosted entity divergence correction (spec §9). Sent ONLY to the hosting client, BATCHED (one message per tick acks every hosted entity whose upload the gate rejected — mirrors EntityStateBatch). The host re-anchors each entity's local sim to the anchored position so its uploads stop being fenced. See EntityStateAckMessage.

Gesture

readonly Gesture: "gesture"

Oneshot gesture relay (v19): player X played world-registered clip Y — broadcast to every client EXCEPT the sender (who already played it locally, client-predicted). Loops never use this channel — they sync via PlayerState.loopGesture so late joiners see them. See GestureEventMessage.

GroupRestSnapshot

readonly GroupRestSnapshot: "groupRestSnapshot"

Authoritative transforms emitted when a declared physics group first reaches full rest.

ModuleEffect

readonly ModuleEffect: "moduleEffect"

Namespaced transient presentation emitted by a mounted module.

ModuleEngagement

readonly ModuleEngagement: "moduleEngagement"

Result/revocation of an exclusive engaged-module authority request.

ModuleFused

readonly ModuleFused: "moduleFused"

A module instance exhausted its per-activation work budget and was isolated.

ModuleSleep

readonly ModuleSleep: "moduleSleep"

An active/fused module became cold and left the active processing set.

ModuleWake

readonly ModuleWake: "moduleWake"

A sleeping/preloaded module began a fresh evaluation activation.

Pong

readonly Pong: "pong"

Reply to a Ping: the client's echoed timestamp + the server's current time, for offset estimation.

RoomTicket

readonly RoomTicket: "helix:room-ticket"

A ticket to a ticketed room instance, sent PRIVATELY to each player an openRoom rule effect selected (room types, SPEC-U1). The client redeems it through the join API ({ ticket }) — see RoomTicketMessage. Like the __helix:* channels the name sits outside the declared-name grammar (':' and '-'), so a world event can never shadow it and it needs no RESERVED_MESSAGE_TYPES entry. Purely additive and server→client: a bundle frozen on an older SDK registers no handler and simply never hops, and no client→server type was added, so there is no room-before-republish ordering constraint and no CONTRACT_VERSION bump.

StateAck

readonly StateAck: "stateAck"

A2 reconnection ack — the player-seat divergence correction (spec §9). Sent ONLY to the uploading client, in two cases: the movement gate REJECTED its state frame, or a rule teleport/respawn re-anchored the seat (the proactive ack — the mover learns NOW instead of via its next rejected upload). The plain accepted case is silent — the accepted position is already in synced state. The client snaps its local body to the anchored position, prunes its reconciliation buffer through the echoed seq, and (v27) adopts the teleport epoch it carries. See StateAckMessage.

VehicleActionFences

readonly VehicleActionFences: "__helix:vehicleActionFences"

Server-authoritative accepted sparse-action fences, replayed after join/reconnect.

VehicleEntityRetired

readonly VehicleEntityRetired: "__helix:vehicleEntityRetired"

A trusted root vehicle lifetime ended; recipients may retire its sparse action replay high-water.

UNITS

const UNITS: object

Pinned units. Linear in meters / meters-per-second; every angle is degrees (see the *Deg suffixes).

Type Declaration

angles

readonly angles: "degrees"

position

readonly position: "meters"

velocity

readonly velocity: "meters/second"

VAULT_ASSET_KINDS

const VAULT_ASSET_KINDS: readonly ["prop", "character", "animation", "audio", "texture", "material", "environment", "terrain", "vfx", "decal", "sky", "gaussian_splat", "scene", "unreal_package"]

Engine-agnostic access to durable HELIX Vault assets.

Persist VaultAssetHandle (assetId + immutable integer version), never an artifact URL. URLs are resolution results and may change when the serving host changes.

XR_INTERACTION_PROMPT_EVENT

const XR_INTERACTION_PROMPT_EVENT: "helix:interaction-prompt" = "helix:interaction-prompt"

Dispatched by the SDK when Helix.prompts.set/clear is called; the engine XR module draws it in-scene. detail: { prompt: { id: string; label: string; state?: 'default'|'available'|'locked'|'busy' } | null; source: 'helix-sdk' } Sticky store: document.__helixInteractionPrompt = detail

XR_SESSION_EVENT

const XR_SESSION_EVENT: "helix:xr-session" = "helix:xr-session"

Dispatched by the ENGINE XR module on every session state change; the SDK forwards it to the shell. detail: { state: 'unsupported'|'idle'|'entering'|'active'|'exiting'; reason?: string; source: 'humanoid-character' } Sticky store: document.__helixXrSession = { state, reason }

Functions

bindStackSafety()

bindStackSafety(stack, target?, visibilityTarget?): () => void

Bind browser lifecycle edges that otherwise strand held input or camera takeover.

visibilitychange is a Document event (and does not bubble to Window), so its target is deliberately separate from the window lifecycle target. Tests and non-browser hosts may pass an explicit visibility target; null disables only that binding. A focused child iframe can blur its parent Window without leaving the document, so preserve the takeover in that case. While an interaction holds child-frame focus, check document focus because departure may not blur the already-blurred parent again. Stack changes start/stop that check without an idle poll.

Parameters

stack

ModeStack

target?

EventTarget

visibilityTarget?

VisibilitySafetyTarget | null

Returns

() => void

cameraCapabilityGate()

cameraCapabilityGate(control, state): CameraCapabilityFlag | null

Parameters

control

HelixCameraControl

state

Returns

CameraCapabilityFlag | null

captureCanvas()

captureCanvas(source, opts?): Promise<Blob>

Parameters

source

HTMLCanvasElement

opts?

CaptureOptions

Returns

Promise<Blob>

clampCameraZoom()

clampCameraZoom(zoom): number

Clamp an arbitrary zoom into the continuous range. Non-finite input falls back to 1×.

Parameters

zoom

number

Returns

number

cloneCameraCapability()

cloneCameraCapability(capability): HelixCameraCapability

Parameters

capability

Returns

cloneCameraState()

cloneCameraState(state): HelixCameraState

Parameters

state

Returns

ActionSurfaceModeOptions

createActionSurfaceInputMap()

createActionSurfaceInputMap(): object

Fresh semantic map so hosts may safely decorate it per instance.

Returns

object

activate

activate: object

activate.action

action: "primary"

activate.label

label: string

activate.touch

touch: object

activate.touch.kind

kind: "tap"

activate.touch.zone

zone: "primary"

back

back: object

back.action

action: "cancel"

back.label

label: string

back.touch

touch: object

back.touch.kind

kind: "button"

back.touch.zone

zone: "secondary"

navigate

navigate: object

navigate.action

action: "move"

navigate.continuous

continuous: boolean

navigate.label

label: string

navigate.repeatMs

repeatMs: number

navigate.touch

touch: object

navigate.touch.kind

kind: "stick"

navigate.touch.zone

zone: "left"

createActionSurfaceMode()

createActionSurfaceMode(options): InteractionMode<void>

Opt-in engaged menu mode. Showing a proximity offer alone must not push it: callers engage explicitly, so merely walking near an item never captures the player. The mode uses the same stack/lease as every takeover.

Parameters

options

Returns

InteractionMode<void>

createDreamerAudioClient()

createDreamerAudioClient(options): DreamerAudioClient

Parameters

options

DreamerAudioClientOptions

Returns

DreamerAudioClient

createMaterialLibrary()

createMaterialLibrary(assetBaseUrl, catalog): HelixMaterialLibrary

Parameters

assetBaseUrl

string

catalog

HelixMaterialCatalog

Returns

HelixMaterialLibrary

createMaterialsNamespace()

createMaterialsNamespace(fetchCatalog?): object

Parameters

fetchCatalog?

(input, init?) => Promise<Response>

Returns

object

clearCache()

clearCache(): void

Returns

void

fromCatalog()

fromCatalog(assetBaseUrl, catalog): HelixMaterialLibrary

Parameters

assetBaseUrl

string

catalog

HelixMaterialCatalog

Returns

HelixMaterialLibrary

load()

load(assetBaseUrl): Promise<HelixMaterialLibrary>

Parameters

assetBaseUrl

string

Returns

Promise<HelixMaterialLibrary>

createModuleAccessors()

createModuleAccessors(sessionId, moduleId, state): ModuleAccessors

Build a guarded module-instance view over the flat and overflow module wire fields.

Parameters

sessionId

string

moduleId

string

state

() => AccessorRoomState | null | undefined

Returns

ModuleAccessors

createRoomAccessors()

createRoomAccessors(sessionId, state): RoomAccessors

Build the room-level accessor set over a live state getter + this client's session id.

Parameters

sessionId

string

state

() => AccessorRoomState | null | undefined

Returns

RoomAccessors

createSealedDeviceDefinitionResolver()

createSealedDeviceDefinitionResolver(projection, options?): SealedDeviceDefinitionResolver

Adapt a single server-sealed trial projection to WorldDeviceHost.

This never resolves inventory, follows mutable package aliases, fetches source, or converts room IR back into an authored Device definition.

Parameters

projection

SealedDeviceDefinitionProjection

options?

SealedDeviceDefinitionResolverOptions

Returns

SealedDeviceDefinitionResolver

createVarsView()

createVarsView(source): VarsView

Build a VarsView over a live bag getter — source() is re-read on every access (live semantics).

Parameters

source

() => VarsBag

Returns

createVaultClient()

createVaultClient(options): VaultClient

Parameters

options

VaultClientOptions

Returns

VaultClient

createVaultLoadPlan()

createVaultLoadPlan(resolved): VaultLoadPlan

Convert a resolved Vault artifact into a renderer-neutral loader handoff. The SDK never imports or guesses a rendering engine.

Parameters

resolved

VaultResolvedAsset

Returns

VaultLoadPlan

cropRectForAspect()

cropRectForAspect(w, h, aspect?): CropRect

Parameters

w

number

h

number

aspect?

CameraAspect

Returns

CropRect

defaultCameraCapability()

defaultCameraCapability(): HelixCameraCapability

Returns

defaultCameraState()

defaultCameraState(): HelixCameraState

The camera before anyone has touched it: put away, and admitting to no abilities.

Returns

intersectCameraCapability()

intersectCameraCapability(runtime, shell): HelixCameraCapability

The capability both sides agree on: what the runtime CLAIMED, narrowed by what the shell PERMITS.

Per-flag AND, deliberately asymmetric. The shell may REVOKE — platform policy, a parental control, a world not cleared for video — because it knows things the runtime does not. It may not GRANT: nothing the shell knows can give a runtime a rig it does not have, and a shell push that turned video back on would re-open the local gate in front of a runtime that already said it cannot serve it. That is the fake support this contract exists to forbid, so the runtime's own report is a CEILING the shell can only lower.

unavailableReason comes from a side that is ACTUALLY REFUSING SOMETHING, and never from one that is not. Taking the runtime's unconditionally put an unrelated runtime note next to a flag only the shell had revoked — HELIX OS would then show the player a policy refusal explained by a sentence about the rig. When both sides refuse, the runtime's wins: "this world ships photo only" is concrete where a policy line is not. When neither refuses, there is nothing to explain and no reason is carried.

This field is a SUMMARY over the whole set. The per-flag truth — which side refused THIS flag — is answered where it is needed, at the refusal itself (HelixSdk.cameraCapabilityRefusal).

Parameters

runtime

shell

Returns