遊戲/應用程式整合

為您的應用程式或遊戲添加 SignalRGB 支援既快速又簡單。如果您的專案可以發送 HTTP POST 請求，它就可以利用 SignalRGB 廣泛的相容裝置範圍。

您的應用程式或遊戲與 SignalRGB 整合有兩種主要方式：觸發預先存在的特效，或與您開發的自訂特效通訊。第一個選項需要的開發時間少得多，但僅限於我們的預製特效庫。第二種方式可能需要更多時間，但它為您可以建立的特效類型和數量提供了無限的可能性。

最終，作為開發者，您需要決定哪種方法最適合您的專案。但是，兩種方法都能提供出色的燈光體驗。

遊戲特效庫

如果您不想開發自己的燈光特效，您可以利用我們豐富的預製特效庫。使用 SignalRGB 應用程式 URL，您可以輕鬆安裝和啟動任何可從 SignalRGB 下載的公開燈光特效。

建議您在應用程式或遊戲首次啟動時安裝燈光特效，以確保所有特效都能快速觸發。

以下 API 路由可用於協助：

請求 URI	用途
signalrgb://effect/install/EffectName	安裝名為 `EffectName` 的燈光特效
signalrgb://effect/apply/EffectName	啟動名為 `EffectName` 的燈光特效

如果您選擇的引擎或語言無法與自訂 URL 協定處理器通訊，您仍然可以使用 SignalRGB API 的這部分。只需使用 --url 參數啟動位於 C:\Users\<username>\AppData\Local\VortxEngine 的 SignalRgbLauncher.exe 可執行檔，並將其設定為您想使用的 API 路由路徑。要防止應用程式被帶到前台，您可以添加 ?-silentlaunch-。

例如，要安裝名為 Azure 的特效，您需要使用以下參數啟動可執行檔：

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

Unity

Unreal Engine

以下 C++ 類別可以與 Unreal Engine 一起使用以安裝和啟動任何 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);
};

建議您在應用程式啟動時安裝您希望使用的任何特效，以便可以快速觸發特效。

以下範例展示如何使用 SignalEffectApi 類別安裝和啟動特效。

#include "SignalEffectApi.h"

...
  // 初始化特效 API。
  SignalEffectApi srgbEffect;

  // 設定您希望安裝的特效名稱。
  std::string effectName = "Azure";

  // 安裝特效。
  srgbEffect.InstallEffect(effectName);

  // 套用特效。
  srgbEffect.ApplyEffect(effectName);

...

自訂特效

使用 HTTP 請求直接與 SignalRGB 通訊，一旦您了解請求的結構後就很容易實現。請求的結構如下：

請求類型： POST

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

從您的應用程式發送的所有命令應使用相同的 sender 變數。event 變數是應傳遞給 SignalRGB 的資料所在的位置。

在特效內部，所有資料都透過 onCanvasApiEvent 函式發送。使用此函式來處理您的特效如何響應 HTTP 請求。

範例程式碼

此基本範例展示 Unity 或 Unreal Engine 遊戲如何與 SignalRGB 通訊以在自訂燈光特效中觸發事件。但是，任何發送 HTTP POST 請求的方法都可以用來控制自訂燈光特效。這種靈活性意味著幾乎任何遊戲或應用程式都可以添加 SignalRGB 支援。

燈光特效

發送到 API 路由的所有事件都透過 onCanvasApiEvent 函式傳遞給燈光特效。管理事件有很多方法，但以下範例保持簡單易懂。如果您正在開發包含多個事件的更複雜的內容，請考慮使用狀態處理器方法來追蹤事件及其對應的燈光特效。

<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 = ""; // 儲存最近事件的變數

  function onCanvasApiEvent(apiEvent) {
    if (apiEvent["sender"] == "apiTestApp") { // 只響應 sender 為 "apiTestApp" 的 API 事件。您應該將此更改為您的應用程式使用的 sender 字串。
      activeEvent = apiEvent["event"]; // 將 activeEvent 變數設定為最近的 API 事件資料。
    }
  }

  function update() {
    if (activeEvent == "allRed") { // 響應 allRed 事件，將 canvas 全部設為紅色
      ctx.fillStyle = '#FF0000';
      ctx.fillRect(0, 0, width, height);
    } else { // 否則，將 canvas 設為全黑
      ctx.fillStyle = '#000000';
      ctx.fillRect(0, 0, width, height);
    }

    window.requestAnimationFrame(update);
  }

  window.requestAnimationFrame(update);
</script>

Unity

以下函式將允許 Unity 與 SignalRGB 通訊。但是，任何發送 HTTP POST 請求的方法都可以使用。

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

以下 C++ 類別可以與 Unreal Engine 一起使用以啟用透過 SignalRGB API 的通訊。確保將請求 URI 的 sender 參數更改為與您的 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);
};

要在遊戲程式碼中觸發燈光特效，只需呼叫 SendEvent 函式，指定您想觸發的事件名稱，以及您的應用程式或遊戲用於向 SignalRGB 標識自身的名稱。

#include "SignalApi.h"

...
  // 設定 sender 變數。
  const std::string SAPI_APPNAME = "apiTestGame";
  // 初始化 SignalApi 類別。
  SignalApi sapi;
  // 設定事件名稱。
  std::string eventName = "weaponFired";
  // 向 SignalRGB 發送 API 事件。
  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" }); // 您必須將 Http 添加到此陣列，否則建置將失敗！
  }
}