Integrasi Permainan/Aplikasi

Menambah sokongan SignalRGB kepada aplikasi atau permainan Anda adalah pantas dan mudah. Jika projek Anda boleh menghantar permintaan HTTP POST, ia boleh memanfaatkan pelbagai peranti yang serasi dengan SignalRGB.

Terdapat dua cara utama aplikasi atau permainan Anda boleh mengintegrasikan dengan SignalRGB: mencetuskan kesan sedia ada atau berkomunikasi dengan kesan tersuai yang Anda bangunkan. Pilihan pertama memerlukan masa pembangunan yang jauh lebih sedikit tetapi terhad kepada pustaka kesan buatan kami. Pendekatan kedua mungkin memerlukan lebih banyak masa, tetapi ia membuka kemungkinan yang tidak terhingga untuk jenis dan bilangan kesan yang boleh Anda cipta.

Pada akhirnya, terpulang kepada Anda sebagai pembangun untuk memutuskan pendekatan mana yang terbaik untuk projek Anda. Namun, kedua-dua kaedah boleh memberikan pengalaman pencahayaan yang hebat.

Pustaka Kesan Permainan

Jika Anda lebih suka tidak membangunkan kesan pencahayaan Anda sendiri, Anda boleh memanfaatkan pustaka kesan buatan kami yang luas. Menggunakan URL aplikasi SignalRGB, Anda boleh memasang dan mengaktifkan dengan mudah sebarang kesan pencahayaan awam yang tersedia untuk muat turun dari SignalRGB.

Adalah disyorkan agar Anda memasang kesan pencahayaan yang akan diaktifkan oleh aplikasi atau permainan Anda apabila ia pertama kali dilancarkan untuk memastikan semua kesan dicetuskan dengan cepat.

Laluan API berikut tersedia untuk membantu dengan ini:

URI Permintaan	Tujuan
signalrgb://effect/install/EffectName	Pasang kesan pencahayaan bernama EffectName
signalrgb://effect/apply/EffectName	Aktifkan kesan pencahayaan bernama EffectName

Note

Nama kesan adalah sensitif terhadap huruf besar-kecil, dan sebarang aksara khas mesti dikod URL. Sebagai contoh, sebarang ruang harus digantikan dengan %20.

Jika enjin atau bahasa yang dipilih tidak dapat berkomunikasi dengan pengendali protokol URL tersuai, Anda masih boleh menggunakan bahagian API SignalRGB ini. Hanya mulakan boleh laksana SignalRgbLauncher.exe yang terletak di C:\Users\<username>\AppData\Local\VortxEngine dengan argumen --url ditetapkan ke laluan laluan API yang ingin Anda gunakan. Untuk mencegah aplikasi dibawa ke latar depan, Anda boleh menambah ?-silentlaunch-.

Sebagai contoh, untuk memasang kesan bernama Azure, Anda akan melancarkan boleh laksana dengan argumen berikut:

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

Unity

Unreal Engine

Kelas C++ berikut boleh digunakan dengan Unreal Engine untuk memasang dan mengaktifkan sebarang kesan 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);
};

Adalah disyorkan agar Anda memasang sebarang kesan yang ingin Anda gunakan apabila aplikasi Anda dilancarkan supaya kesan boleh dicetuskan dengan cepat.

Contoh berikut menunjukkan cara Anda boleh memasang dan mengaktifkan kesan menggunakan kelas 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);

...

Kesan Tersuai

Berkomunikasi dengan SignalRGB secara langsung menggunakan permintaan HTTP adalah mudah untuk dilaksanakan setelah Anda tahu bagaimana permintaan itu disusun. Struktur permintaan adalah seperti berikut:

Jenis permintaan: POST

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

Semua arahan yang dihantar dari aplikasi Anda harus menggunakan pemboleh ubah sender yang sama. Pemboleh ubah event adalah tempat data yang dihantar ke SignalRGB harus pergi.

Di dalam kesan, semua data dihantar melalui fungsi onCanvasApiEvent. Gunakan fungsi ini untuk mengendalikan cara kesan Anda bertindak balas terhadap permintaan HTTP.

Kod Contoh

Contoh asas ini menunjukkan cara permainan Unity atau Unreal Engine boleh berkomunikasi dengan SignalRGB untuk mencetuskan peristiwa dalam kesan pencahayaan tersuai. Namun, sebarang kaedah pengiriman permintaan HTTP boleh digunakan untuk mengawal kesan pencahayaan tersuai. Fleksibiliti ini bermakna sokongan SignalRGB boleh ditambah ke hampir mana-mana permainan atau aplikasi.

Kesan Pencahayaan

Semua peristiwa yang dihantar ke laluan API dihantar ke kesan pencahayaan melalui fungsi onCanvasApiEvent. Terdapat banyak cara untuk menguruskan peristiwa, tetapi contoh berikut memastikan perkara mudah dan mudah difahami. Jika Anda membangunkan sesuatu yang lebih kompleks dengan berbilang peristiwa, pertimbangkan untuk menggunakan kaedah pengendali keadaan untuk menjejak peristiwa dan kesan pencahayaan yang sepadan.

<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

Fungsi seperti berikut akan membolehkan Unity berkomunikasi dengan SignalRGB. Namun, sebarang kaedah pengiriman permintaan HTTP POST boleh digunakan.

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

Kelas C++ berikut boleh digunakan dengan Unreal Engine untuk membolehkan komunikasi melalui API SignalRGB. Pastikan untuk mengubah parameter sender URI permintaan agar sepadan dengan apa yang digunakan lightscript Anda.

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

Untuk mencetuskan kesan pencahayaan dalam kod permainan Anda, hanya panggil fungsi SendEvent yang menentukan nama peristiwa yang ingin Anda cetuskan, bersama nama yang akan digunakan aplikasi atau permainan Anda untuk mengenal pasti dirinya kepada 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);

...

Caution

Anda mesti menambah modul Http ke dependensi binaan Unreal Engine Anda dengan mengedit ProjectName.Build.cs agar menyerupai yang berikut:

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