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 leverage SignalRGB's vast array of compatible devices.

There are two major ways your app or game can accomplish this: triggering pre-existing effects, or communicating with a custom effect you develop . The first option requires significantly less development time, but is limited to our library of premade effects. While the second approach might be more time consuming, the sky's the limit when it comes to the variety and number of effects you can create.

It is ultimately up to you as the developer to decide which approach is right for your project, but either method can be used to produce great lighting experiences.

Game Effect Library

If you'd rather not develop your own lighting effects, you can take advantage of our wide variety of pre-made effects. Using SignalRGB app URLs, it is possible to install and activate any public lighting effect available for download from SignalRGB.

It is recommended that you install any lighting effects your app or game will activate when it first opens, to ensure that all effects activate quickly.

The following API routes exist to help 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 the way that 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 onto the lighting effect via the onCanvasApiEvent function. There are many ways of managing events, but the following example keeps it simple and easy to understand. If you're building something more complex with many events, consider using the state handler method to keep track of the events and their associated lighting.

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

  }

}