Интеграции с играми и приложениями

Добавить поддержку SignalRGB в своё приложение или игру быстро и легко. Если ваш проект может отправлять HTTP POST-запросы, он может использовать широкий спектр совместимых устройств SignalRGB.

Существует два основных способа интеграции приложения или игры с SignalRGB: запуск готовых эффектов или взаимодействие с пользовательским эффектом, который вы разработаете. Первый вариант требует значительно меньше времени на разработку, но ограничен библиотекой готовых эффектов. Второй подход может занять больше времени, но открывает бесконечные возможности для типов и количества создаваемых эффектов.

В конечном счёте именно вы как разработчик решаете, какой подход лучше всего подходит для вашего проекта. Оба метода способны обеспечить фантастический опыт освещения.

Библиотека игровых эффектов

Если вы предпочитаете не разрабатывать собственные световые эффекты, можно воспользоваться обширной библиотекой готовых эффектов. С помощью URL-адресов приложения SignalRGB можно легко устанавливать и активировать любой публичный световой эффект, доступный для скачивания из SignalRGB.

Рекомендуется устанавливать световые эффекты, которые ваше приложение или игра будет активировать при первом запуске, чтобы все эффекты срабатывали быстро.

Доступны следующие маршруты API:

URI запроса	Назначение
signalrgb://effect/install/EffectName	Установить световой эффект с именем EffectName
signalrgb://effect/apply/EffectName	Активировать световой эффект с именем EffectName

Заметка

Имена эффектов чувствительны к регистру, а специальные символы должны быть URL-закодированы. Например, пробелы следует заменить на %20.

Если выбранный движок или язык программирования не может взаимодействовать с обработчиками пользовательских URL-протоколов, эту часть API SignalRGB всё равно можно использовать. Просто запустите исполняемый файл SignalRgbLauncher.exe, расположенный в C:\Users\<username>\AppData\Local\VortxEngine, с аргументом --url, указывающим на путь используемого маршрута API. Чтобы приложение не выходило на первый план, добавьте ?-silentlaunch-.

Например, для установки эффекта Azure:

SignalRgbLauncher.exe --url=effect/apply/Azure?-silentlaunch-

Unity

Unreal Engine

Следующий класс C++ можно использовать с Unreal Engine для установки и активации любого эффекта SignalRGB.

#include "SignalEffectApi.h"

void SignalEffectApi::ApplyEffect(const std::string& effect) {
  const TCHAR* appdataPath = FPlatformProcess::UserSettingsDir();
  const FString exePath = FString(appdataPath) + TEXT("\\VortxEngine\\SignalRgbLauncher.exe");
  const FString params = TEXT("--url=effect/apply/") + FString(effect.c_str()) + TEXT("?-silentlaunch-");
  FPlatformProcess::CreateProc(*exePath, *params, true, false, false, nullptr, 0, nullptr, nullptr);
}

void SignalEffectApi::InstallEffect(const std::string& effect) {
  const TCHAR* appdataPath = FPlatformProcess::UserSettingsDir();
  const FString exePath = FString(appdataPath) + TEXT("\\VortxEngine\\SignalRgbLauncher.exe");
  const FString params = TEXT("--url=effect/install/") + FString(effect.c_str()) + TEXT("?-silentlaunch-");
  FPlatformProcess::CreateProc(*exePath, *params, true, false, false, nullptr, 0, nullptr, nullptr);
}

#pragma once

#include "CoreMinimal.h"

class SignalEffectApi
{
public:
  void ApplyEffect(const std::string& effect);
  void InstallEffect(const std::string& effect);
};

Рекомендуется устанавливать все нужные эффекты при запуске приложения, чтобы они срабатывали быстро.

Следующий пример показывает, как установить и активировать эффект с помощью класса SignalEffectApi:

#include "SignalEffectApi.h"

...
  // Initialize effect API.
  SignalEffectApi srgbEffect;

  // Set the name of the effect you wish to install.
  std::string effectName = "Azure";

  // Install the effect.
  srgbEffect.InstallEffect(effectName);

  // Apply the effect.
  srgbEffect.ApplyEffect(effectName);

...

Пользовательские эффекты

Взаимодействие с SignalRGB напрямую через HTTP-запросы легко освоить, зная структуру запросов:

Тип запроса: POST

URI запроса: http://localhost:16034/canvas/event?sender=your-app-name&event=your-event

Все команды, отправляемые из приложения, должны использовать одну и ту же переменную sender. Переменная event — это место, куда помещаются данные, передаваемые SignalRGB.

Внутри эффекта все данные поступают через функцию onCanvasApiEvent. Используйте эту функцию для управления реакцией эффекта на HTTP-запросы.

Пример кода

Этот базовый пример показывает, как игра на Unity или Unreal Engine может взаимодействовать с SignalRGB для запуска событий в пользовательском световом эффекте. Однако любой метод отправки HTTP-запросов можно использовать для управления пользовательским световым эффектом. Это означает, что поддержку SignalRGB можно добавить практически в любую игру или приложение.

Световой эффект

Все события, отправленные на маршрут API, передаются в световой эффект через функцию onCanvasApiEvent. Существует много способов управления событиями, но следующий пример остаётся простым и понятным. При разработке более сложного проекта с несколькими событиями рекомендуется использовать метод обработчика состояний для отслеживания событий и соответствующих световых эффектов.

<head>
  <title>CustomApiEffect</title>
  <meta description="Effect description goes here." />
  <meta publisher="Your Name Here" />
</head>

<body style="margin: 0; padding: 0;">
  <canvas id="exCanvas" width="320" height="200"></canvas>
</body>

<script>
  var c = document.getElementById("exCanvas");
  var ctx = c.getContext("2d");
  var width = 320;
  var height = 200;

  var activeEvent = ""; // Variable to store most recent event

  function onCanvasApiEvent(apiEvent) {
    if (apiEvent["sender"] == "apiTestApp") { // Only respond to API events with the sender "apiTestApp". You should change this to the sender string your app uses.
      activeEvent = apiEvent["event"]; // Set the activeEvent variable to the most recent API event data.
    }
  }

  function update() {
    if (activeEvent == "allRed") { // Turn the canvas all red in response to an allRed event
      ctx.fillStyle = '#FF0000';
      ctx.fillRect(0, 0, width, height);
    } else { // Otherwise, make the canvas all black
      ctx.fillStyle = '#000000';
      ctx.fillRect(0, 0, width, height);
    }

    window.requestAnimationFrame(update);
  }

  window.requestAnimationFrame(update);
</script>

Unity

Следующая функция позволит Unity взаимодействовать с SignalRGB. Можно использовать любой другой метод отправки HTTP POST-запросов.

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
using System.Collections.Generic;

public class SendAllRedEventBehavior : MonoBehaviour
{
    void Start()
    {
        StartCoroutine(Upload());
    }

    IEnumerator Upload()
    {
        UnityWebRequest www = UnityWebRequest.Post("http://localhost:16034/canvas/event?sender=apiTestApp&event=allRed");
        yield return www.SendWebRequest();

        if (www.result != UnityWebRequest.Result.Success)
        {
            Debug.Log(www.error);
        }
        else
        {
            Debug.Log("Sent lighting event to SignalRGB!");
        }
    }
}

Unreal Engine

Следующий класс C++ можно использовать с Unreal Engine для взаимодействия через API SignalRGB. Убедитесь, что параметр sender URI запроса совпадает с тем, что использует ваш lightscript.

#include "SignalApi.h"

void SignalApi::SendEvent(const std::string& sender, const std::string& event) {
  Http = &FHttpModule::Get();
  TSharedRef<IHttpRequest> Request = Http->CreateRequest();
  std::string requestUri = "http://localhost:16034/canvas/event?sender="+ sender + "&event=" + event;
  Request->SetURL(requestUri.c_str());
  Request->SetVerb("GET");
  Request->SetHeader(TEXT("User-Agent"), "X-UnrealEngine-Agent");
  Request->SetHeader("Content-Type", TEXT("application/json"));
  Request->ProcessRequest();
}

#pragma once

#include "CoreMinimal.h"
#include "Runtime/Online/HTTP/Public/Http.h"

class SignalApi
{
public:
  FHttpModule* Http;
  void SendEvent(const std::string& sender,const std::string& event);
};

Для запуска светового эффекта в коде игры просто вызовите функцию SendEvent, указав имя нужного события и имя, которое ваше приложение или игра будет использовать для идентификации в SignalRGB.

#include "SignalApi.h"

...
  // Set the sender variable.
  const std::string SAPI_APPNAME = "apiTestGame";
  // Initialize SignalApi class.
  SignalApi sapi;
  // Set the name of the event.
  std::string eventName = "weaponFired";
  // Send API event to SignalRGB.
  sapi.SendEvent(SAPI_APPNAME, eventName);

...

Осторожно

Необходимо добавить модуль Http в зависимости сборки Unreal Engine, отредактировав ProjectName.Build.cs следующим образом:

using UnrealBuildTool;

public class SignalApiTest : ModuleRules
{
  public SignalApiTest(ReadOnlyTargetRules Target) : base(Target)
  {
    PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

    PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "HeadMountedDisplay", "EnhancedInput", "Http" }); // you MUST add Http to this array or the build will fail!
  }
}