UNITY · 1.8.1 candidate30.09.202638 topics

Internal VORIVOX development. Candidate package: remaining gates are listed under compatibility.

API reference

This page provides a structured overview of the main SDK class, its states, events, methods and data models.

Main class

VorivoxGameSdk is the MonoBehaviour that connects your game to Launcher.

Typical flow

In most games you call ConnectAsync() and then ReadyAsync().

Event stream

Hits, pause, stop and state changes are delivered through SDK events.

VorivoxGameSdk class

public sealed class VorivoxGameSdk : MonoBehaviour

Attach it to a scene object. It loads the manifest, connects to Launcher over the loopback WebSocket and dispatches game events on Unity's main thread.

Core properties and states

Member	Description
`Manifest`	The loaded launch manifest with session, display, target profile and path data.
`Capabilities`	The confirmed Launcher capabilities: LED trigger, LED override, pause/resume and raw events.
`ConnectionState`	Transport state: `Disconnected`, `Connecting`, `Authenticating`, `Connected`, `Ready`, `Failed`.
`DeviceState`	Hardware state: `Unknown`, `Ready`, `Degraded`, `ControllerLost`, `Busy`.
`SessionState`	Session lifecycle state: `Idle`, `Starting`, `Running`, `Paused`, `Stopping`, `Completed`.
`LastError`	The last connection or transport error as text.
`IsMock`	`true` when the SDK runs in mock mode without a real manifest.
`IsConnected`	Convenience flag for an active connection.
`IsReady`	`true` after a successful `ReadyAsync()`.
`IsSessionRunning`	`true` while an actual game session is running.
`IsPaused`	`true` when the session is paused.

Events

Event	When it fires
`ConnectionStateChanged`	On every connection state transition.
`SessionStateChanged`	When the session lifecycle changes.
`ServerAccepted`	After a successful `server.hello` with Launcher capabilities.
`SessionStarted`	When `session.start` arrives.
`SessionPaused`	When `session.pause` arrives.
`SessionResumed`	When a paused session is resumed.
`SessionStopped`	When the operator or system stops the session.
`HitReceived`	On a physical hit from the acoustic target.
`DeviceStateChanged`	When Launcher reports a new hardware state.
`MessageIgnored`	When an inbound message is invalid or unknown.
`Error`	When the SDK reports a transport or logic error.

Methods

Connect

Task ConnectAsync(CancellationToken cancellationToken = default)

Loads the manifest, opens the WebSocket, sends client.hello and waits for Launcher acceptance.

Ready

Task ReadyAsync(string scene = "Game", CancellationToken cancellationToken = default)

Tells Launcher that the game has finished loading and is ready for the session.

Wait for session start

Task<VorivoxSessionStart> WaitForSessionStartAsync(CancellationToken cancellationToken = default)

Asynchronously waits for session.start and returns the session parameters.

Update score

Task UpdateScoreAsync(VorivoxScore score, CancellationToken cancellationToken = default)

Sends the current score, shots, hits and remaining time.

Complete session

Task CompleteAsync(VorivoxResult result, CancellationToken cancellationToken = default)

Sends the final result. Repeated calls for the same session are ignored.

LED trigger

Task TriggerLedAsync(string trigger = "HIT", CancellationToken cancellationToken = default)

Sends a system LED trigger request. Check Capabilities.LedTrigger before calling it.

LED override

Task SetLedOverrideAsync(string mode, int r, int g, int b, int w = 0, int durationMs = 0, CancellationToken cancellationToken = default)

Requests temporary LED control. Check Capabilities.LedOverride before calling it.

Clear LED override

Task ClearLedOverrideAsync(CancellationToken cancellationToken = default)

Returns LED control to the default system behavior.

Service log

Task LogAsync(string level, string text, CancellationToken cancellationToken = default)

Sends a diagnostic message to Launcher.

Disconnect

Task DisconnectAsync()

Stops background tasks, closes the WebSocket and returns the SDK to Disconnected.

Mock: session start

void InjectMockSessionStart(int playerCount = 0, string mode = null, int countdownMs = 0)

Simulates session.start during local development.

Mock: pause and resume

void InjectMockPause(string reason = "operator_requested")
void InjectMockResume()

Simulates pausing and resuming a session.

Mock: stop and device state

void InjectMockStop(string reason = "operator_abort")
void InjectMockDeviceState(VorivoxDeviceState state)

Simulates session stop or a hardware state change.

Mock: hit

void InjectMockHit(float normalizedX, float normalizedY, string shotId = null)

Creates a test hit using normalized coordinates from 0 to 1.

Key data models

Model	Purpose
`VorivoxHit`	One hit event: `ShotId`, millimeter coordinates, normalized coordinates, source and demo flag. Important helpers: `ToScreenPixels()`, `ToCanvasLocal()`.
`VorivoxScore`	Intermediate score data: `Score`, `Shots`, `Hits`, `TimeLeftMs`.
`VorivoxResult`	Final session result: `Status`, `Score`, `Shots`, `Hits`, `DurationMs`, `PlayerCount`.
`VorivoxSessionStart`	Session start parameters: `PlayerCount`, `Mode`, `CountdownMs`.
`VorivoxLaunchManifest`	The full game manifest: bridge, display, target profile, paths, session and game metadata.

Minimal usage flow

private async Task StartGameAsync()
{
    await sdk.ConnectAsync();
    await sdk.ReadyAsync("Boot");

    VorivoxSessionStart session = await sdk.WaitForSessionStartAsync();
    StartRound(session);
}

1.8 changes and guarantee boundaries

CompleteAsync validates PlayerCount against the current manifest. ToTopLeftPixels(width,height) retains ToScreenPixels behaviour; ToUnityScreenPixels(width,height) does not invert Y. Automatic mock is Editor-only with no manifest path. Pause/Resume cannot revive a stopped session. Result sending is not a persistence ACK.