Intégrations Jeux/Applications

Ajouter la prise en charge de SignalRGB à votre application ou jeu est rapide et facile. Si votre projet peut envoyer des requêtes HTTP POST, il peut tirer parti de la large gamme de périphériques compatibles avec SignalRGB.

Il existe deux façons principales pour votre application ou jeu de s’intégrer avec SignalRGB : déclencher des effets préexistants ou communiquer avec un effet personnalisé que vous développez. La première option nécessite beaucoup moins de temps de développement, mais est limitée à notre bibliothèque d’effets préfabriqués. La deuxième approche peut prendre plus de temps, mais elle ouvre des possibilités infinies en termes de types et de nombre d’effets que vous pouvez créer.

En fin de compte, c’est à vous en tant que développeur de décider quelle approche convient le mieux à votre projet. Cependant, les deux méthodes peuvent offrir des expériences d’éclairage fantastiques.

Bibliothèque d’Effets de Jeu

Si vous préférez ne pas développer vos propres effets d’éclairage, vous pouvez profiter de notre vaste bibliothèque d’effets préfabriqués. En utilisant les URL de l’application SignalRGB, vous pouvez facilement installer et activer tout effet d’éclairage public disponible en téléchargement depuis SignalRGB.

Il est recommandé d’installer les effets d’éclairage que votre application ou jeu activera lors de son premier lancement pour s’assurer que tous les effets se déclenchent rapidement.

Les routes API suivantes sont disponibles pour vous aider :

URI de requête	Objectif
signalrgb://effect/install/EffectName	Installe l’effet d’éclairage nommé EffectName
signalrgb://effect/apply/EffectName	Active l’effet d’éclairage nommé EffectName

Note

Les noms d’effets sont sensibles à la casse, et tous les caractères spéciaux doivent être encodés en URL. Par exemple, les espaces doivent être remplacés par %20.

Si votre moteur ou langage choisi ne peut pas communiquer avec des gestionnaires de protocole d’URL personnalisés, vous pouvez toujours utiliser cette partie de l’API SignalRGB. Il suffit de démarrer l’exécutable SignalRgbLauncher.exe situé dans C:\Users\<username>\AppData\Local\VortxEngine avec l’argument --url défini sur le chemin de la route API que vous souhaitez utiliser. Pour empêcher l’application d’être mise au premier plan, vous pouvez ajouter ?-silentlaunch-.

Par exemple, pour installer l’effet nommé Azure, vous lanceriez l’exécutable avec l’argument suivant :

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

Unity

Unreal Engine

La classe C++ suivante peut être utilisée avec Unreal Engine pour installer et activer tout effet 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);
};

Il est recommandé d’installer tous les effets que vous souhaitez utiliser au lancement de votre application afin que les effets puissent être déclenchés rapidement.

L’exemple suivant montre comment installer et activer un effet à l’aide de la classe 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);

...

Effets Personnalisés

Communiquer directement avec SignalRGB en utilisant des requêtes HTTP est facile à accomplir une fois que vous connaissez la structure des requêtes. La structure de la requête est la suivante :

Type de requête : POST

URI de requête : http://localhost:16034/canvas/event?sender=your-app-name&event=your-event

Toutes les commandes envoyées depuis votre application doivent utiliser la même variable sender. La variable event est l’endroit où les données transmises à SignalRGB doivent aller.

À l’intérieur de l’effet, toutes les données sont envoyées via la fonction onCanvasApiEvent. Utilisez cette fonction pour gérer la façon dont votre effet répond aux requêtes HTTP.

Exemple de Code

Cet exemple de base montre comment un jeu Unity ou Unreal Engine peut communiquer avec SignalRGB pour déclencher des événements dans un effet d’éclairage personnalisé. Cependant, toute méthode d’envoi de requêtes HTTP peut être utilisée pour contrôler l’effet d’éclairage personnalisé. Cette flexibilité signifie que la prise en charge de SignalRGB peut être ajoutée à presque n’importe quel jeu ou application.

Effet d’Éclairage

Tous les événements envoyés à la route API sont transmis à l’effet d’éclairage via la fonction onCanvasApiEvent. Il existe de nombreuses façons de gérer les événements, mais l’exemple suivant garde les choses simples et faciles à comprendre. Si vous développez quelque chose de plus complexe avec plusieurs événements, envisagez d’utiliser la méthode du gestionnaire d’état pour suivre les événements et leurs effets d’éclairage correspondants.

<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

Une fonction comme celle qui suit permettra à Unity de communiquer avec SignalRGB. Cependant, toute méthode d’envoi de requêtes HTTP POST peut être utilisée.

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

La classe C++ suivante peut être utilisée avec Unreal Engine pour activer la communication via l’API SignalRGB. Assurez-vous de modifier le paramètre sender de l’URI de requête pour qu’il corresponde à ce que votre lightscript utilise.

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

Pour déclencher un effet d’éclairage dans le code de votre jeu, appelez simplement la fonction SendEvent en spécifiant le nom de l’événement que vous souhaitez déclencher, ainsi que le nom que votre application ou jeu utilisera pour s’identifier auprès de 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);

...

Attention

Vous devez ajouter le module Http aux dépendances de build de votre Unreal Engine en modifiant ProjectName.Build.cs pour qu’il ressemble à ce qui suit :

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