Spel/App-integrationer

Att lägga till SignalRGB-stöd i din app eller ditt spel är snabbt och enkelt. Om ditt projekt kan skicka HTTP POST-förfrågningar kan det dra nytta av SignalRGB:s breda utbud av kompatibla enheter.

Det finns två huvudsakliga sätt som din app eller ditt spel kan integreras med SignalRGB: att utlösa befintliga effekter eller att kommunicera med en anpassad effekt du har utvecklat. Det första alternativet kräver mycket kortare utvecklingstid men är begränsat till vårt bibliotek av färdiga effekter. Det andra tillvägagångssättet kan ta mer tid, men erbjuder oändliga möjligheter vad gäller typen och antalet effekter du kan skapa.

I slutändan är det du som utvecklare som avgör vilket tillvägagångssätt som är bäst för ditt projekt. Men båda metoderna kan ge fantastiska ljussättningsupplevelser.

Speleffektbibliotek

Om du föredrar att inte utveckla egna ljussättningseffekter kan du använda vårt omfattande bibliotek av färdiga effekter. Med hjälp av SignalRGB-appens URL:er kan du enkelt ladda och aktivera vilken offentlig ljussättningseffekt som helst som kan laddas ned från SignalRGB.

Det rekommenderas att du laddar de ljussättningseffekter som din app eller ditt spel ska aktivera när det startas för första gången för att alla effekter ska kunna utlösas snabbt.

Följande API-sökvägar finns tillgängliga för att hjälpa till med detta:

Förfrågnings-URI	Syfte
signalrgb://effect/install/EffectName	Installerar ljussättningseffekten med namnet EffectName
signalrgb://effect/apply/EffectName	Aktiverar ljussättningseffekten med namnet EffectName

Note

Effektnamn är skiftlägeskänsliga och specialtecken måste vara URL-kodade. Till exempel ska mellanslag ersättas med %20.

Om din motor eller ditt språk inte kan kommunicera med anpassade URL-protokollhanterare kan du fortfarande använda den här delen av SignalRGB:s API. Starta bara den körbara filen SignalRgbLauncher.exe som finns på C:\Users\<username>\AppData\Local\VortxEngine med argumentet --url inställt på sökvägen till den API-sökväg du vill använda. Du kan lägga till ?-silentlaunch- för att förhindra att appen hamnar i förgrunden.

Till exempel, för att aktivera effekten Azure, startar du den körbara filen med följande argument:

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

Unity

Unreal Engine

Följande C++-klass kan användas med Unreal Engine för att ladda och aktivera valfri SignalRGB-effekt.

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

Det rekommenderas att du laddar de effekter du vill använda när din app startas så att effekterna kan utlösas snabbt.

Följande exempel visar hur man laddar och aktiverar en effekt med klassen SignalEffectApi.

#include "SignalEffectApi.h"

...
  // Initiera effekt-API:et.
  SignalEffectApi srgbEffect;

  // Ange namnet på effekten du vill ladda.
  std::string effectName = "Azure";

  // Ladda effekten.
  srgbEffect.InstallEffect(effectName);

  // Applicera effekten.
  srgbEffect.ApplyEffect(effectName);

...

Anpassade effekter

Att kommunicera direkt med SignalRGB via HTTP-förfrågningar kan enkelt utföras när du väl har lärt dig hur förfrågningarna är uppbyggda. Förfrågans struktur är följande:

Förfrågningstyp: POST

Förfrågnings-URI: http://localhost:16034/canvas/event?sender=your-app-name&event=your-event

Alla kommandon som skickas från din app ska använda samma sender-variabel. Variabeln event är dit data som ska vidarebefordras till SignalRGB skickas.

Inuti effekten vidarebefordras all data via funktionen onCanvasApiEvent. Använd den här funktionen för att hantera hur din effekt svarar på HTTP-förfrågningar.

Exempelkod

Det här grundläggande exemplet visar hur ett Unity- eller Unreal Engine-spel kan kommunicera med SignalRGB för att utlösa händelser i en anpassad ljussättningseffekt. Vilken metod som helst för att skicka HTTP POST-förfrågningar kan dock användas för att kontrollera den anpassade ljussättningseffekten. Den här flexibiliteten innebär att SignalRGB-stöd kan läggas till i nästan vilket spel eller vilken app som helst.

Ljussättningseffekt

Alla händelser som skickas till API-sökvägen vidarebefordras till ljussättningseffekten via funktionen onCanvasApiEvent. Det finns många sätt att hantera händelser, men exemplet nedan håller det enkelt och tydligt. Om du bygger något mer komplext med flera händelser kan du överväga att använda metoden med tillståndshanteraren för att hålla reda på händelser och deras motsvarande ljussättningseffekter.

<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 = ""; // Variabel för att lagra den senaste händelsen

  function onCanvasApiEvent(apiEvent) {
    if (apiEvent["sender"] == "apiTestApp") { // Svara bara på API-händelser med avsändaren "apiTestApp". Du bör ersätta detta med den avsändarsträng som ditt lightscript använder.
      activeEvent = apiEvent["event"]; // Sätt activeEvent-variabeln till de senaste API-händelsedata.
    }
  }

  function update() {
    if (activeEvent == "allRed") { // Gör canvas helt röd som svar på allRed-händelsen
      ctx.fillStyle = '#FF0000';
      ctx.fillRect(0, 0, width, height);
    } else { // Annars gör canvas helt svart
      ctx.fillStyle = '#000000';
      ctx.fillRect(0, 0, width, height);
    }

    window.requestAnimationFrame(update);
  }

  window.requestAnimationFrame(update);
</script>

Unity

En funktion som följande tillåter Unity att kommunicera med SignalRGB. Vilken metod som helst för att skicka HTTP POST-förfrågningar kan dock användas.

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

Följande C++-klass kan användas med Unreal Engine för att aktivera kommunikation via SignalRGB API. Se till att du ändrar parametern sender i förfrågnings-URI:n så att den matchar den som ditt lightscript använder.

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

För att utlösa en ljussättningseffekt i din spelkod anropar du bara funktionen SendEvent och anger namnet på den händelse du vill utlösa samt det namn som din app eller ditt spel använder för att identifiera sig för SignalRGB.

#include "SignalApi.h"

...
  // Ange sender-variabeln.
  const std::string SAPI_APPNAME = "apiTestGame";
  // Initiera SignalApi-klassen.
  SignalApi sapi;
  // Ange händelsenamnet.
  std::string eventName = "weaponFired";
  // Skicka API-händelsen till SignalRGB.
  sapi.SendEvent(SAPI_APPNAME, eventName);

...

Caution

Du måste lägga till Http-modulen i dina Unreal Engine-byggberoenden genom att redigera filen ProjectName.Build.cs enligt följande:

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" }); // Du MÅSTE lägga till Http i den här arrayen, annars misslyckas kompileringen!
  }
}