Game/App Integrations

Adding SignalRGB support to your app or game is quick and easy. If your project can send HTTP POST requests, it can take advantage of SignalRGB's wide range of compatible devices.

There are two main ways your app or game can integrate with SignalRGB: triggering pre-existing effects or communicating with a custom effect you develop. The first option requires much less development time but is limited to our library of premade effects. The second approach may take more time, but it opens up endless possibilities for the types and number of effects you can create.

Ultimately, it’s up to you as the developer to decide which approach is best for your project. However, both methods can deliver fantastic lighting experiences..

Game Effect Library

If you prefer not to develop your own lighting effects, you can take advantage of our extensive library of pre-made effects. Using SignalRGB app URLs, you can easily install and activate any public lighting effect available for download from SignalRGB.

It’s recommended that you install the lighting effects your app or game will activate when it first launches to ensure all effects are triggered quickly.

The following API routes are available to assist with this:

If your chosen engine or language cannot communicate with custom URL protocol handlers, you can still use this portion of the SignalRGB API. Simply start the SignalRgbLauncher.exe executable located in C:\Users\<username>\AppData\Local\VortxEngine with --url argument set to the path of the API route you'd like to use. To prevent the app from being brought to the foreground, you can add ?-silentlaunch-.

For example, to install the effect named Azure, you would launch the executable with the following argument:

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

Unity

Unreal Engine

The following C++ class can be used with Unreal Engine to install and activate any SignalRGB effect.

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

}

It is recommended that you install any effects you wish to use when your app launches so that effects can be triggered quickly.

The following example shows how you can install and activate an effect using the SignalEffectApi class.

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

​

...

Custom Effects

Communicating with SignalRGB directly using HTTP requests is easy to accomplish once you know how the requests are structured. The structure of the request is as follows:

Request type: POST

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

All commands sent from your app should use the same sender variable. The event variable is where the data being passed to SignalRGB should go.

Inside the effect, all data is sent through the onCanvasApiEvent function. Use this function to handle how your effect responds to HTTP requests.

Example Code

This basic example shows how a Unity or Unreal Engine game can communicate with SignalRGB to trigger events in a custom lighting effect. However, any method of sending HTTP requests can be used to control the custom lighting effect. This flexibility means that SignalRGB support can be added to almost any game or application.

Lighting Effect

All events sent to the API route are passed to the lighting effect through the onCanvasApiEvent function. There are many ways to manage events, but the following example keeps things simple and easy to understand. If you’re developing something more complex with multiple events, consider using the state handler method to track the events and their corresponding lighting effects.

<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

A function like the following will allow Unity to communicate with SignalRGB. However, any method of sending HTTP POST requests can be used.

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

The following C++ class can be used with Unreal Engine to enable communication via the SignalRGB API. Make sure to change the sender parameter of the request URI to match what your lightscript is using.

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

}

To trigger a lighting effect in your game's code, simply call the SendEvent function specifying the name of the event you'd like to trigger, along with the name your app or game will use to identify itself to 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);

​

...

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!

  }

}