Integracje z grami/aplikacjami

Dodanie obsługi SignalRGB do twojej aplikacji lub gry jest szybkie i łatwe. Jeśli twój projekt potrafi wysyłać żądania HTTP POST, może skorzystać z szerokiej gamy kompatybilnych urządzeń SignalRGB.

Istnieją dwa główne sposoby integracji twojej aplikacji lub gry z SignalRGB: aktywowanie istniejących efektów lub komunikacja z niestandardowym efektem, który sam opracowujesz. Pierwsza opcja wymaga znacznie mniej czasu deweloperskiego, ale jest ograniczona do naszej biblioteki gotowych efektów. Drugie podejście może zająć więcej czasu, ale oferuje nieograniczone możliwości co do typów i liczby efektów, które możesz tworzyć.

Ostatecznie to do ciebie jako dewelopera należy decyzja, które podejście jest najlepsze dla twojego projektu. Obie metody mogą jednak zapewnić fantastyczne doświadczenia z oświetleniem.

Biblioteka efektów gier

Jeśli wolisz nie tworzyć własnych efektów oświetlenia, możesz skorzystać z naszej rozbudowanej biblioteki gotowych efektów. Za pomocą adresów URL aplikacji SignalRGB możesz łatwo instalować i aktywować dowolny publiczny efekt oświetlenia dostępny do pobrania w SignalRGB.

Zaleca się instalowanie efektów oświetlenia, które twoja aplikacja lub gra będzie aktywować podczas pierwszego uruchomienia, dzięki czemu wszystkie efekty są szybko aktywowane.

Dostępne są następujące trasy API:

URI żądania	Cel
signalrgb://effect/install/NazwaEfektu	Zainstaluj efekt oświetlenia o nazwie NazwaEfektu
signalrgb://effect/apply/NazwaEfektu	Aktywuj efekt oświetlenia o nazwie NazwaEfektu

Notatka

Nazwy efektów rozróżniają wielkość liter, a znaki specjalne muszą być zakodowane w URL. Na przykład spacje należy zastąpić %20.

Jeśli twój wybrany silnik lub język programowania nie może komunikować się z niestandardowymi procedurami obsługi protokołów URL, nadal możesz korzystać z tej części API SignalRGB. Po prostu uruchom plik wykonywalny SignalRgbLauncher.exe w C:\Users\<nazwa_użytkownika>\AppData\Local\VortxEngine z argumentem --url ustawionym na ścieżkę trasy API, której chcesz użyć. Aby zapobiec przenoszeniu aplikacji na pierwszy plan, możesz dodać ?-silentlaunch-.

Na przykład, jeśli chcesz zainstalować efekt Azure, uruchamiasz plik wykonywalny z następującym argumentem:

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

Unity

Unreal Engine

Następująca klasa C++ może być używana z Unreal Engine do instalowania i aktywowania dowolnego efektu 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);
};

Zaleca się instalowanie efektów, których chcesz używać, podczas uruchamiania aplikacji, aby efekty mogły być szybko aktywowane.

Poniższy przykład pokazuje, jak instalować i aktywować efekt za pomocą klasy 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);

...

Niestandardowe efekty

Bezpośrednia komunikacja z SignalRGB za pomocą żądań HTTP jest łatwa do zrealizowania, gdy już wiesz, jak zbudowane są żądania. Struktura żądania jest następująca:

Typ żądania: POST

URI żądania: http://localhost:16034/canvas/event?sender=twoja-nazwa-aplikacji&event=twoje-zdarzenie

Wszystkie polecenia wysyłane z twojej aplikacji powinny używać tej samej zmiennej sender. Zmienna event jest miejscem, gdzie trafiają dane przekazywane do SignalRGB.

W ramach efektu wszystkie dane są wysyłane przez funkcję onCanvasApiEvent. Użyj tej funkcji, aby określić, jak twój efekt reaguje na żądania HTTP.

Przykładowy kod

Ten podstawowy przykład pokazuje, jak gra Unity lub Unreal Engine może komunikować się z SignalRGB, aby aktywować zdarzenia w niestandardowym efekcie oświetlenia. Jednak do sterowania niestandardowym efektem oświetlenia można użyć dowolnej metody wysyłania żądań HTTP. Ta elastyczność umożliwia dodanie obsługi SignalRGB do niemal każdej gry lub aplikacji.

Efekt oświetlenia

Wszystkie zdarzenia wysyłane do trasy API są przekazywane do efektu oświetlenia przez funkcję onCanvasApiEvent. Istnieje wiele sposobów zarządzania zdarzeniami, ale poniższy przykład jest prosty i zrozumiały. Jeśli tworzysz coś bardziej złożonego z wieloma zdarzeniami, rozważ użycie metody procedury obsługi stanu do śledzenia zdarzeń i powiązanych efektów oświetlenia.

<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

Funkcja taka jak poniższa umożliwia Unity komunikację z SignalRGB. Jednak do wysyłania żądań HTTP POST można użyć dowolnej metody.

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

Następująca klasa C++ może być używana z Unreal Engine, aby umożliwić komunikację przez API SignalRGB. Pamiętaj, aby dostosować parametr sender w URI żądania tak, aby pasował do tego, czego używa twój 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);
};

Aby aktywować efekt oświetlenia w kodzie gry, po prostu wywołaj funkcję SendEvent, podając nazwę zdarzenia, które chcesz aktywować, wraz z nazwą, której twoja aplikacja lub gra używa do identyfikacji w 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);

...

Uwaga

Musisz dodać moduł Http do zależności budowania Unreal Engine, edytując NazwaProjektu.Build.cs w następujący sposób:

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!
  }
}