Game/app-integraties

SignalRGB-ondersteuning toevoegen aan uw app of game is snel en eenvoudig. Als uw project HTTP POST-verzoeken kan verzenden, kan het profiteren van het brede scala aan compatibele apparaten van SignalRGB.

Er zijn twee belangrijke manieren waarop uw app of game kan integreren met SignalRGB: het activeren van bestaande effecten of communiceren met een aangepast effect dat u zelf ontwikkelt. De eerste optie vereist veel minder ontwikkeltijd maar is beperkt tot onze bibliotheek van kant-en-klare effecten. De tweede aanpak kan meer tijd kosten, maar biedt eindeloze mogelijkheden voor de soorten en het aantal effecten dat u kunt maken.

Uiteindelijk is het aan u als ontwikkelaar om te beslissen welke aanpak het beste is voor uw project. Beide methoden kunnen echter fantastische verlichtingservaringen bieden.

Bibliotheeк van game-effecten

Als u liever geen eigen verlichtingseffecten ontwikkelt, kunt u gebruikmaken van onze uitgebreide bibliotheek van kant-en-klare effecten. Via SignalRGB-app-URL’s kunt u eenvoudig elk openbaar verlichtingseffect installeren en activeren dat beschikbaar is voor download in SignalRGB.

Het wordt aanbevolen om de verlichtingseffecten die uw app of game zal activeren te installeren wanneer deze voor het eerst wordt gestart, zodat alle effecten snel worden geactiveerd.

De volgende API-routes zijn beschikbaar:

Verzoek-URI	Doel
signalrgb://effect/install/EffectName	Installeer het verlichtingseffect met de naam EffectName
signalrgb://effect/apply/EffectName	Activeer het verlichtingseffect met de naam EffectName

Opmerking

Effectnamen zijn hoofdlettergevoelig en speciale tekens moeten URL-gecodeerd zijn. Spaties moeten bijvoorbeeld worden vervangen door %20.

Als uw gekozen engine of programmeertaal niet kan communiceren met aangepaste URL-protocolhandlers, kunt u dit deel van de SignalRGB API nog steeds gebruiken. Start gewoon het uitvoerbare bestand SignalRgbLauncher.exe in C:\Users\<gebruikersnaam>\AppData\Local\VortxEngine met het argument --url ingesteld op het pad van de API-route die u wilt gebruiken. Om te voorkomen dat de app naar de voorgrond wordt gebracht, kunt u ?-silentlaunch- toevoegen.

Als u bijvoorbeeld het effect Azure wilt installeren, start u het uitvoerbare bestand met het volgende argument:

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

Unity

Unreal Engine

De volgende C++-klasse kan worden gebruikt met Unreal Engine om elk SignalRGB-effect te installeren en activeren.

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

Het wordt aanbevolen om de effecten die u wilt gebruiken te installeren wanneer uw app wordt gestart, zodat effecten snel kunnen worden geactiveerd.

Het volgende voorbeeld laat zien hoe u een effect kunt installeren en activeren met de klasse 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);

...

Aangepaste effecten

Directe communicatie met SignalRGB via HTTP-verzoeken is eenvoudig te realiseren zodra u weet hoe de verzoeken zijn opgebouwd. De structuur van het verzoek is als volgt:

Verzoektype: POST

Verzoek-URI: http://localhost:16034/canvas/event?sender=uw-app-naam&event=uw-event

Alle opdrachten die vanuit uw app worden verzonden, moeten dezelfde sender-variabele gebruiken. De variabele event is waar de gegevens die aan SignalRGB worden doorgegeven naartoe gaan.

Binnen het effect worden alle gegevens verzonden via de functie onCanvasApiEvent. Gebruik deze functie om te bepalen hoe uw effect reageert op HTTP-verzoeken.

Voorbeeldcode

Dit basisvoorbeeld laat zien hoe een Unity- of Unreal Engine-game kan communiceren met SignalRGB om events te activeren in een aangepast verlichtingseffect. Elke methode voor het verzenden van HTTP-verzoeken kan echter worden gebruikt om het aangepaste verlichtingseffect te besturen. Dankzij deze flexibiliteit kan SignalRGB-ondersteuning aan bijna elk spel of elke applicatie worden toegevoegd.

Verlichtingseffect

Alle events die naar de API-route worden verzonden, worden via de functie onCanvasApiEvent doorgegeven aan het verlichtingseffect. Er zijn veel manieren om events te beheren, maar het volgende voorbeeld houdt het eenvoudig en begrijpelijk. Als u iets complexers ontwikkelt met meerdere events, overweeg dan de methode met de toestandshandler te gebruiken om events en bijbehorende verlichtingseffecten bij te houden.

<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

Een functie zoals de volgende stelt Unity in staat te communiceren met SignalRGB. Elke methode voor het verzenden van HTTP POST-verzoeken kan echter worden gebruikt.

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

De volgende C++-klasse kan worden gebruikt met Unreal Engine om communicatie via de SignalRGB API mogelijk te maken. Zorg ervoor dat u de parameter sender in de verzoek-URI aanpast zodat deze overeenkomt met wat uw lightscript gebruikt.

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

Om een verlichtingseffect te activeren in de code van uw game, roept u eenvoudig de functie SendEvent aan en geeft u de naam op van het event dat u wilt activeren, samen met de naam die uw app of game gebruikt om zichzelf bij SignalRGB te identificeren.

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

...

Opgepast

U moet de Http-module toevoegen aan de buildafhankelijkheden van Unreal Engine door ProjectNaam.Build.cs als volgt te bewerken:

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