Integrasi Game/Aplikasi

Menambahkan dukungan SignalRGB ke aplikasi atau game Anda sangat cepat dan mudah. Jika proyek Anda dapat mengirim permintaan HTTP POST, proyek tersebut dapat memanfaatkan berbagai perangkat yang kompatibel dengan SignalRGB.

Ada dua cara utama aplikasi atau game Anda dapat berintegrasi dengan SignalRGB: memicu efek yang sudah ada atau berkomunikasi dengan efek kustom yang Anda kembangkan. Opsi pertama membutuhkan waktu pengembangan yang jauh lebih sedikit tetapi terbatas pada perpustakaan efek buatan kami. Pendekatan kedua mungkin membutuhkan lebih banyak waktu, tetapi membuka kemungkinan tak terbatas untuk jenis dan jumlah efek yang dapat Anda buat.

Pada akhirnya, terserah Anda sebagai pengembang untuk memutuskan pendekatan mana yang terbaik untuk proyek Anda. Namun, kedua metode ini dapat memberikan pengalaman pencahayaan yang luar biasa.

Game Effect Library

Jika Anda lebih memilih untuk tidak mengembangkan efek pencahayaan sendiri, Anda dapat memanfaatkan perpustakaan efek buatan kami yang luas. Menggunakan URL aplikasi SignalRGB, Anda dapat dengan mudah menginstal dan mengaktifkan efek pencahayaan publik apa pun yang tersedia untuk diunduh dari SignalRGB.

Disarankan agar Anda menginstal efek pencahayaan yang akan diaktifkan oleh aplikasi atau game Anda saat pertama kali diluncurkan untuk memastikan semua efek dipicu dengan cepat.

Rute API berikut tersedia untuk membantu hal ini:

Request URI	Tujuan
signalrgb://effect/install/EffectName	Menginstal efek pencahayaan bernama EffectName
signalrgb://effect/apply/EffectName	Mengaktifkan efek pencahayaan bernama EffectName

Catatan

Nama efek bersifat case-sensitive, dan karakter khusus apa pun harus di-encode URL. Misalnya, spasi harus diganti dengan %20.

Jika mesin atau bahasa yang Anda pilih tidak dapat berkomunikasi dengan penangan protokol URL kustom, Anda masih dapat menggunakan bagian SignalRGB API ini. Cukup jalankan executable SignalRgbLauncher.exe yang terletak di C:\Users\<username>\AppData\Local\VortxEngine dengan argumen --url yang disetel ke jalur rute API yang ingin Anda gunakan. Untuk mencegah aplikasi dibawa ke latar depan, Anda dapat menambahkan ?-silentlaunch-.

Misalnya, untuk menginstal efek bernama Azure, Anda akan menjalankan executable dengan argumen berikut:

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

Unity

Unreal Engine

Kelas C++ berikut dapat digunakan dengan Unreal Engine untuk menginstal dan mengaktifkan efek SignalRGB apa pun.

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

Disarankan agar Anda menginstal efek yang ingin Anda gunakan saat aplikasi diluncurkan agar efek dapat dipicu dengan cepat.

Contoh berikut menunjukkan cara Anda dapat menginstal dan mengaktifkan efek 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);

...

Custom Effects

Berkomunikasi dengan SignalRGB secara langsung menggunakan permintaan HTTP mudah dilakukan setelah Anda mengetahui cara permintaan tersebut disusun. Struktur permintaan adalah sebagai berikut:

Tipe permintaan: POST

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

Semua perintah yang dikirim dari aplikasi Anda harus menggunakan variabel sender yang sama. Variabel event adalah tempat data yang diteruskan ke SignalRGB harus ditempatkan.

Di dalam efek, semua data dikirim melalui fungsi onCanvasApiEvent. Gunakan fungsi ini untuk menangani cara efek Anda merespons permintaan HTTP.

Contoh Kode

Contoh dasar ini menunjukkan cara game Unity atau Unreal Engine dapat berkomunikasi dengan SignalRGB untuk memicu event dalam efek pencahayaan kustom. Namun, metode pengiriman permintaan HTTP POST apa pun dapat digunakan untuk mengontrol efek pencahayaan kustom. Fleksibilitas ini berarti dukungan SignalRGB dapat ditambahkan ke hampir semua game atau aplikasi.

Efek Pencahayaan

Semua event yang dikirim ke rute API diteruskan ke efek pencahayaan melalui fungsi onCanvasApiEvent. Ada banyak cara untuk mengelola event, tetapi contoh berikut menjaga segalanya tetap sederhana dan mudah dipahami. Jika Anda mengembangkan sesuatu yang lebih kompleks dengan beberapa event, pertimbangkan untuk menggunakan metode state handler untuk melacak event dan efek pencahayaan yang sesuai.

<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 memungkinkan Unity berkomunikasi dengan SignalRGB. Namun, metode pengiriman permintaan HTTP POST apa pun dapat 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 dapat digunakan dengan Unreal Engine untuk mengaktifkan komunikasi melalui SignalRGB API. Pastikan untuk mengubah parameter sender dari URI permintaan agar sesuai dengan 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 memicu efek pencahayaan dalam kode game Anda, cukup panggil fungsi SendEvent dengan menentukan nama event yang ingin Anda picu, bersama dengan nama yang akan digunakan aplikasi atau game Anda untuk mengidentifikasi diri ke 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);

...

Perhatian

Anda harus menambahkan modul Http ke dependensi build Unreal Engine Anda dengan mengedit ProjectName.Build.cs agar menyerupai berikut ini:

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