JavaScript / TypeScript API
The public API matches src/vorivox.js and src/vorivox.d.ts. Underscore-prefixed methods are private implementation.
Construction and properties
new VorivoxClient(manifest, options) validates input. options.WebSocketImpl injects a test transport; authenticationTimeoutMs defaults to 5000. Properties: manifest, connectionState, sessionState, deviceState and capabilities. The manifest copy contains a secret and must never be logged.
Connection and subscriptions
connect(): Promise<Capabilities> resolves after an accepted hello. Concurrent calls share one connection; a used client never restores an old launch. on(name, listener) returns an unsubscribe function. Callbacks are synchronous; promises started inside require their own catch.
Readiness and results
ready(scene='Game') reports readiness after loading. updateScore({score,shots,hits,time_left_ms}) sends intermediate counters. complete({score,shots,hits,duration_ms,status,player_count}) requires an active session and matching player count; repeats return false. This sends a message, not a persistence acknowledgement.
Lighting
triggerLed(trigger='HIT'), setLedOverride({mode,r,g,b,w,duration_ms}), clearLedOverride(). Validates capabilities, integer channels 0…255 and nonnegative duration. The platform, not this library, defines supported hardware modes.
Diagnostics
log(level,text): debug/info/warning/error; text is bounded and the known session_token is redacted. disconnect() stops heartbeat and closes the connection. It is not game completion.
Events
connection, state, error, ignored; server.hello; session.start with player_count/mode/countdown_ms; session.pause and session.stop with reason; session.resume; device.state; target.hit with shot_id/x_mm/y_mm/nx/ny/source/demo; heartbeat. A hit can arrive outside active gameplay: state and shot_id filtering remains the game's responsibility.
Utilities
validateManifest(input) returns a normalized copy. toCanvasPoint(hit,{x,y,width,height}) maps bottom-left into a top-left viewport without clipping physical letterboxing. Separate mock.js exports createMockSdk({playerCount,gameId,locale}) → {sdk,controls}. It is explicit development tooling, not production fallback.