Spiel/App-Integrationen

Das Hinzufügen von SignalRGB-Unterstützung zu deiner App oder deinem Spiel ist schnell und einfach. Wenn dein Projekt HTTP-POST-Anfragen senden kann, kann es die breite Palette kompatibler Geräte von SignalRGB nutzen.

Es gibt zwei Hauptwege, wie deine App oder dein Spiel mit SignalRGB integriert werden kann: das Auslösen bereits vorhandener Effekte oder die Kommunikation mit einem eigens entwickelten benutzerdefinierten Effekt. Die erste Option erfordert deutlich weniger Entwicklungsaufwand, ist jedoch auf unsere Bibliothek vorgefertigter Effekte beschränkt. Der zweite Ansatz kann mehr Zeit in Anspruch nehmen, eröffnet jedoch endlose Möglichkeiten hinsichtlich Art und Anzahl der erstellbaren Effekte.

Letztendlich liegt es als Entwickler an dir zu entscheiden, welcher Ansatz für dein Projekt am besten geeignet ist. Beide Methoden können jedoch fantastische Beleuchtungserlebnisse liefern.

Spieleffekt-Bibliothek

Wenn du keine eigenen Beleuchtungseffekte entwickeln möchtest, kannst du unsere umfangreiche Bibliothek vorgefertigter Effekte nutzen. Über SignalRGB-App-URLs kannst du jeden öffentlichen Beleuchtungseffekt, der bei SignalRGB zum Download verfügbar ist, ganz einfach installieren und aktivieren.

Es wird empfohlen, die Beleuchtungseffekte, die deine App oder dein Spiel beim ersten Start aktivieren soll, vorab zu installieren, damit alle Effekte schnell ausgelöst werden können.

Die folgenden API-Routen stehen dafür zur Verfügung:

Anfrage-URI	Zweck
signalrgb://effect/install/EffectName	Installiert den Beleuchtungseffekt mit dem Namen EffectName
signalrgb://effect/apply/EffectName	Aktiviert den Beleuchtungseffekt mit dem Namen EffectName

Hinweis

Effektnamen sind Groß-/Kleinschreibung-sensitiv, und alle Sonderzeichen müssen URL-kodiert werden. Leerzeichen sollten beispielsweise durch %20 ersetzt werden.

Wenn die gewählte Engine oder Sprache nicht mit benutzerdefinierten URL-Protokoll-Handlern kommunizieren kann, ist dieser Teil der SignalRGB-API trotzdem nutzbar. Starte dazu einfach die ausführbare Datei SignalRgbLauncher.exe im Verzeichnis C:\Users\<username>\AppData\Local\VortxEngine mit dem Argument --url auf den Pfad der gewünschten API-Route. Um zu verhindern, dass die App in den Vordergrund gebracht wird, kann ?-silentlaunch- hinzugefügt werden.

Um beispielsweise den Effekt namens Azure zu installieren, wird die ausführbare Datei mit folgendem Argument gestartet:

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

Unity

Unreal Engine

Die folgende C++-Klasse kann mit Unreal Engine verwendet werden, um jeden SignalRGB-Effekt zu installieren und zu aktivieren.

#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);
};

Es wird empfohlen, alle Effekte, die verwendet werden sollen, beim App-Start zu installieren, damit sie schnell ausgelöst werden können.

Das folgende Beispiel zeigt, wie ein Effekt mithilfe der SignalEffectApi-Klasse installiert und aktiviert werden kann.

#include "SignalEffectApi.h"

...
  // Effekt-API initialisieren.
  SignalEffectApi srgbEffect;

  // Name des zu installierenden Effekts festlegen.
  std::string effectName = "Azure";

  // Effekt installieren.
  srgbEffect.InstallEffect(effectName);

  // Effekt anwenden.
  srgbEffect.ApplyEffect(effectName);

...

Benutzerdefinierte Effekte

Die direkte Kommunikation mit SignalRGB über HTTP-Anfragen ist einfach umzusetzen, sobald die Struktur der Anfragen bekannt ist. Die Struktur der Anfrage lautet wie folgt:

Anfragetyp: POST

Anfrage-URI: http://localhost:16034/canvas/event?sender=your-app-name&event=your-event

Alle von der App gesendeten Befehle sollten dieselbe sender-Variable verwenden. Die event-Variable enthält die Daten, die an SignalRGB übermittelt werden.

Im Effekt werden alle Daten über die Funktion onCanvasApiEvent gesendet. Mit dieser Funktion wird gesteuert, wie der Effekt auf HTTP-Anfragen reagiert.

Beispielcode

Dieses einfache Beispiel zeigt, wie ein Unity- oder Unreal-Engine-Spiel mit SignalRGB kommunizieren kann, um Ereignisse in einem benutzerdefinierten Beleuchtungseffekt auszulösen. Es kann jedoch jede Methode zum Senden von HTTP-Anfragen verwendet werden, um den benutzerdefinierten Beleuchtungseffekt zu steuern. Diese Flexibilität bedeutet, dass SignalRGB-Unterstützung zu nahezu jedem Spiel oder jeder Anwendung hinzugefügt werden kann.

Beleuchtungseffekt

Alle an die API-Route gesendeten Ereignisse werden über die Funktion onCanvasApiEvent an den Beleuchtungseffekt weitergeleitet. Es gibt viele Möglichkeiten, Ereignisse zu verwalten, aber das folgende Beispiel ist einfach und leicht verständlich gehalten. Wer etwas Komplexeres mit mehreren Ereignissen entwickelt, sollte die State-Handler-Methode in Betracht ziehen, um die Ereignisse und ihre entsprechenden Beleuchtungseffekte zu verfolgen.

<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 zum Speichern des zuletzt empfangenen Ereignisses

  function onCanvasApiEvent(apiEvent) {
    if (apiEvent["sender"] == "apiTestApp") { // Nur auf API-Ereignisse mit dem Sender "apiTestApp" reagieren. Dies sollte auf den eigenen Sender-String geändert werden.
      activeEvent = apiEvent["event"]; // Die activeEvent-Variable auf die zuletzt empfangenen API-Ereignisdaten setzen.
    }
  }

  function update() {
    if (activeEvent == "allRed") { // Canvas bei einem allRed-Ereignis komplett rot färben
      ctx.fillStyle = '#FF0000';
      ctx.fillRect(0, 0, width, height);
    } else { // Andernfalls Canvas schwarz färben
      ctx.fillStyle = '#000000';
      ctx.fillRect(0, 0, width, height);
    }

    window.requestAnimationFrame(update);
  }

  window.requestAnimationFrame(update);
</script>

Unity

Eine Funktion wie die folgende ermöglicht es Unity, mit SignalRGB zu kommunizieren. Es kann jedoch jede Methode zum Senden von HTTP-POST-Anfragen verwendet werden.

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

Die folgende C++-Klasse kann mit Unreal Engine verwendet werden, um die Kommunikation über die SignalRGB-API zu ermöglichen. Sicherstellen, dass der sender-Parameter der Anfrage-URI mit dem übereinstimmt, den das Lightscript verwendet.

#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);
};

Um einen Beleuchtungseffekt im Spielcode auszulösen, wird einfach die Funktion SendEvent mit dem Namen des gewünschten Ereignisses sowie dem Namen aufgerufen, mit dem sich die App oder das Spiel bei SignalRGB identifiziert.

#include "SignalApi.h"

...
  // Sender-Variable festlegen.
  const std::string SAPI_APPNAME = "apiTestGame";
  // SignalApi-Klasse initialisieren.
  SignalApi sapi;
  // Namen des Ereignisses festlegen.
  std::string eventName = "weaponFired";
  // API-Ereignis an SignalRGB senden.
  sapi.SendEvent(SAPI_APPNAME, eventName);

...

Achtung

Das Http-Modul muss den Unreal-Engine-Build-Abhängigkeiten hinzugefügt werden, indem ProjectName.Build.cs wie folgt angepasst wird:

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" }); // Http MUSS diesem Array hinzugefügt werden, sonst schlägt der Build fehl!
  }
}