Spil/App-integrationer

Tilføjelse af SignalRGB-understøttelse til din app eller dit spil er hurtigt og enkelt. Hvis dit projekt kan sende HTTP-POST-anmodninger, kan det drage nytte af SignalRGBs brede vifte af kompatible enheder.

Der er to primære måder, din app eller dit spil kan integreres med SignalRGB: udløsning af allerede eksisterende effekter eller kommunikation med en særligt udviklet brugerdefineret effekt. Den første mulighed kræver betydeligt mindre udviklingsarbejde, men er begrænset til vores bibliotek af præfabrikerede effekter. Den anden tilgang kan tage mere tid, men åbner uendelige muligheder med hensyn til type og antal effekter der kan skabes.

I sidste ende er det op til dig som udvikler at afgøre, hvilken tilgang der passer bedst til dit projekt. Begge metoder kan dog levere fantastiske lysoplevelser.

Spillets effektbibliotek

Hvis du ikke ønsker at udvikle dine egne lyseffekter, kan du bruge vores store bibliotek af præfabrikerede effekter. Via SignalRGB-app-URL’er kan du nemt installere og aktivere enhver offentlig lyseffekt der er tilgængelig til download på SignalRGB.

Det anbefales at forudinstallere de lyseffekter som din app eller dit spil skal aktivere ved første opstart, så alle effekter hurtigt kan udløses.

Følgende API-ruter er tilgængelige til dette formål:

Anmodnings-URI	Formål
signalrgb://effect/install/EffectName	Installerer lyseffekten med navnet EffectName
signalrgb://effect/apply/EffectName	Aktiverer lyseffekten med navnet EffectName

Note

Effektnavne skelner mellem store og små bogstaver, og alle specialtegn skal URL-koderes. Mellemrum bør for eksempel erstattes med %20.

Hvis den valgte engine eller det valgte sprog ikke kan kommunikere med brugerdefinerede URL-protokolhåndterere, er denne del af SignalRGBs API stadig brugbar. Start blot den eksekverbare fil SignalRgbLauncher.exe i mappen C:\Users\<brugernavn>\AppData\Local\VortxEngine med argumentet --url pegende på stien til den ønskede API-rute. For at forhindre at appen bringes i forgrunden kan ?-silentlaunch- tilføjes.

For eksempel, for at installere effekten med navnet Azure, startes den eksekverbare fil med følgende argument:

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

Unity

Unreal Engine

Følgende C++-klasse kan bruges med Unreal Engine til at installere og aktivere enhver 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 anbefales at installere alle effekter der skal bruges ved app-start, så de hurtigt kan udløses.

Det følgende eksempel viser, hvordan en effekt installeres og aktiveres ved hjælp af SignalEffectApi-klassen.

#include "SignalEffectApi.h"

...
  // Initialiser effekt-API.
  SignalEffectApi srgbEffect;

  // Angiv navnet på den effekt der skal installeres.
  std::string effectName = "Azure";

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

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

...

Brugerdefinerede effekter

Direkte kommunikation med SignalRGB via HTTP-anmodninger er enkel at implementere, når strukturen for anmodningerne er klarlagt. Anmodningsstrukturen er som følger:

Anmodningstype: POST

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

Alle kommandoer sendt fra appen bør bruge den samme sender-variabel. event-variablen indeholder de data der overføres til SignalRGB.

I effekten sendes alle data via funktionen onCanvasApiEvent. Med denne funktion styres, hvordan effekten reagerer på HTTP-anmodninger.

Eksempelkode

Dette enkle eksempel viser, hvordan et Unity- eller Unreal Engine-spil kan kommunikere med SignalRGB for at udløse hændelser i en brugerdefineret lyseffekt. Det kan dog bruges enhver metode til at sende HTTP-anmodninger til at styre den brugerdefinerede lyseffekt. Denne fleksibilitet betyder, at SignalRGB-understøttelse kan tilføjes til næsten ethvert spil eller enhver applikation.

Lyseffekten

Alle hændelser sendt til API-ruten videresendes til lyseffekten via funktionen onCanvasApiEvent. Der er mange måder at håndtere hændelser på, men det følgende eksempel holdes enkelt og letforståeligt. Hvis du udvikler noget mere komplekst med flere hændelser, bør du overveje State-handler-metoden til at spore hændelserne og deres tilsvarende lyseffekter.

<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 til at gemme den sidst modtagne hændelse

  function onCanvasApiEvent(apiEvent) {
    if (apiEvent["sender"] == "apiTestApp") { // Reagér kun på API-hændelser med senderen "apiTestApp". Dette bør ændres til din egen sender-streng.
      activeEvent = apiEvent["event"]; // Sæt activeEvent-variablen til de sidst modtagne API-hændelsesdata.
    }
  }

  function update() {
    if (activeEvent == "allRed") { // Farv canvas helt rødt ved en allRed-hændelse
      ctx.fillStyle = '#FF0000';
      ctx.fillRect(0, 0, width, height);
    } else { // Ellers farv canvas sort
      ctx.fillStyle = '#000000';
      ctx.fillRect(0, 0, width, height);
    }

    window.requestAnimationFrame(update);
  }

  window.requestAnimationFrame(update);
</script>

Unity

En funktion som den følgende gør det muligt for Unity at kommunikere med SignalRGB. Dog kan enhver metode til at sende HTTP-POST-anmodninger bruges.

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ølgende C++-klasse kan bruges med Unreal Engine til at muliggøre kommunikation via SignalRGB-API’en. Sørg for at sender-parameteren i anmodnings-URI’en matcher den der bruges i 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);
};

For at udløse en lyseffekt i spillets kode kaldes blot funktionen SendEvent med navnet på den ønskede hændelse samt det navn som appen eller spillet identificerer sig med hos SignalRGB.

#include "SignalApi.h"

...
  // Angiv sender-variablen.
  const std::string SAPI_APPNAME = "apiTestGame";
  // Initialiser SignalApi-klassen.
  SignalApi sapi;
  // Angiv hændelsens navn.
  std::string eventName = "weaponFired";
  // Send API-hændelse til SignalRGB.
  sapi.SendEvent(SAPI_APPNAME, eventName);

...

Bemærk

Http-modulet skal tilføjes til Unreal Engine-byggeafhængighederne ved at tilpasse ProjectName.Build.cs som følger:

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 SKAL tilføjes til dette array, ellers vil bygningen mislykkes!
  }
}