Справочник API
Ниже собран структурированный справочник по основному классу SDK, его состояниям, событиям, методам и моделям данных.
VorivoxGameSdk — MonoBehaviour, который подключает игру к Launcher.
Обычно достаточно вызвать ConnectAsync(), затем ReadyAsync().
Попадания, пауза, остановка и смена состояний приходят через события SDK.
Класс VorivoxGameSdk
Размещается на объекте сцены и отвечает за загрузку manifest, соединение с Launcher по локальное WebSocket-соединение с Launcher и доставку событий игры в основной поток Unity.
Основные свойства и состояния
| Член | Описание |
|---|---|
Manifest | Загруженный launch manifest со сведениями о сеансе, дисплеях, профиль мишени и путях. |
Capabilities | Набор подтверждённых Launcher возможностей: LED trigger, LED override, pause/resume, raw events. |
ConnectionState | Состояние канала: Disconnected, Connecting, Authenticating, Connected, Ready, Failed. |
DeviceState | Состояние оборудования: Unknown, Ready, Degraded, ControllerLost, Busy. |
SessionState | Состояние сеанса: Idle, Starting, Running, Paused, Stopping, Completed. |
LastError | Последняя текстовая ошибка соединения или транспорта. |
IsMock | true, если SDK работает в mock-режиме без настоящего manifest. |
IsConnected | Удобный флаг для проверки активного соединения. |
IsReady | true после успешного ReadyAsync(). |
IsSessionRunning | true, когда активен реальный игровой сеанс. |
IsPaused | true, если сеанс поставлен на паузу. |
События
| Событие | Когда возникает |
|---|---|
ConnectionStateChanged | При каждом переходе состояния подключения. |
SessionStateChanged | При смене жизненного цикла сеанса. |
ServerAccepted | После успешного server.hello с capabilities Launcher. |
SessionStarted | Когда приходит session.start. |
SessionPaused | Когда приходит session.pause. |
SessionResumed | Когда пауза снята и игра может продолжить сеанс. |
SessionStopped | Когда оператор или система останавливает сеанс. |
HitReceived | При физическом попадании в акустическую мишень. |
DeviceStateChanged | Когда Launcher сообщает новое состояние оборудования. |
MessageIgnored | Когда входящее сообщение признано невалидным или неизвестным. |
Error | Когда SDK сообщает ошибку транспорта или логики. |
Методы
Подключение
Task ConnectAsync(CancellationToken cancellationToken = default)Загружает manifest, открывает WebSocket, отправляет client.hello и ждёт подтверждение Launcher.
Готовность игры
Task ReadyAsync(string scene = "Game", CancellationToken cancellationToken = default)Сообщает Launcher, что игра загрузилась и готова к началу сеанса.
Ожидание старта
Task<VorivoxSessionStart> WaitForSessionStartAsync(CancellationToken cancellationToken = default)Асинхронно ждёт сообщение session.start и возвращает параметры сеанса.
Промежуточный счёт
Task UpdateScoreAsync(VorivoxScore счёт, CancellationToken cancellationToken = default)Передаёт текущий счёт, число выстрелов, число попаданий и оставшееся время.
Завершение сеанса
Task CompleteAsync(VorivoxResult result, CancellationToken cancellationToken = default)Отправляет финальный результат. Повторный вызов для одного и того же сеанса игнорируется.
LED-триггер
Task TriggerLedAsync(string trigger = "HIT", CancellationToken cancellationToken = default)Отправляет запрос системного LED-триггера. Перед вызовом проверяйте Capabilities.LedTrigger.
LED override
Task SetLedOverrideAsync(string mode, int r, int g, int b, int w = 0, int durationMs = 0, CancellationToken cancellationToken = default)Отправляет запрос на временное управление подсветкой. Перед вызовом проверяйте Capabilities.LedOverride.
Сброс LED override
Task ClearLedOverrideAsync(CancellationToken cancellationToken = default)Возвращает подсветку в нормальный системный режим.
Сервисный лог
Task LogAsync(string level, string text, CancellationToken cancellationToken = default)Передаёт диагностическое сообщение в сторону Launcher.
Отключение
Task DisconnectAsync()Останавливает фоновые задачи, закрывает WebSocket и переводит SDK в состояние Disconnected.
Mock: старт сеанса
void InjectMockSessionStart(int playerCount = 0, string mode = null, int countdownMs = 0)Имитирует session.start в режиме локальной разработки.
Mock: пауза и продолжение
void InjectMockPause(string reason = "operator_requested")void InjectMockResume()
Имитирует постановку сеанса на паузу и его продолжение.
Mock: остановка и состояние устройства
void InjectMockStop(string reason = "operator_abort")void InjectMockDeviceState(VorivoxDeviceState state)
Имитирует остановку сеанса или изменение состояния оборудования.
Mock: попадание
void InjectMockHit(float normalizedX, float normalizedY, string shotId = null)Создаёт тестовое попадание в нормализованных координатах от 0 до 1.
Ключевые модели данных
| Модель | Назначение |
|---|---|
VorivoxHit | Данные одного попадания: ShotId, координаты в миллиметрах, нормализованные координаты, источник и флаг demo. Важные методы: ToScreenPixels(), ToCanvasLocal(). |
VorivoxScore | Промежуточный результат: Score, Shots, Hits, TimeLeftMs. |
VorivoxResult | Финальный результат сеанса: Status, Score, Shots, Hits, DurationMs, PlayerCount. |
VorivoxSessionStart | Параметры старта сеанса: PlayerCount, Mode, CountdownMs. |
VorivoxLaunchManifest | Полный manifest игры: bridge, display, профиль мишени, paths, session и metadata игры. |
Минимальный сценарий использования
private async Task StartGameAsync()
{
await sdk.ConnectAsync();
await sdk.ReadyAsync("Boot");
VorivoxSessionStart session = await sdk.WaitForSessionStartAsync();
StartRound(session);
}Изменения 1.8 и границы гарантий
CompleteAsync проверяет соответствие PlayerCount текущему manifest. ToTopLeftPixels(width,height) сохраняет поведение ToScreenPixels; ToUnityScreenPixels(width,height) не инвертирует Y. Автоматический mock — только Editor без заданного пути manifest. Pause/Resume не возвращают остановленный сеанс к игре. Отправка результата не является ACK его хранения.