การผสานรวมกับเกม/แอป

การเพิ่มการรองรับ SignalRGB ให้กับแอปหรือเกมของคุณนั้นรวดเร็วและง่ายดาย หากโปรเจกต์ของคุณสามารถส่งคำขอ HTTP POST ได้ ก็จะใช้ประโยชน์จากอุปกรณ์ที่รองรับจำนวนมากของ SignalRGB ได้

แอปหรือเกมของคุณสามารถผสานรวมกับ SignalRGB ได้สองวิธีหลัก ได้แก่ การเรียกใช้เอฟเฟกต์ที่มีอยู่แล้ว หรือการสื่อสารกับเอฟเฟกต์แบบกำหนดเองที่คุณพัฒนาขึ้น ตัวเลือกแรกใช้เวลาพัฒนาน้อยกว่ามาก แต่จำกัดอยู่เพียงคลังเอฟเฟกต์สำเร็จรูปของเรา ส่วนวิธีที่สองอาจใช้เวลามากกว่า แต่เปิดโอกาสไม่สิ้นสุดทั้งในแง่ประเภทและจำนวนของเอฟเฟกต์ที่คุณสร้างได้

ท้ายที่สุดแล้ว คุณในฐานะนักพัฒนาเป็นผู้ตัดสินใจว่าวิธีใดเหมาะกับโปรเจกต์ของคุณที่สุด อย่างไรก็ตาม ทั้งสองวิธีสามารถมอบประสบการณ์แสงที่ยอดเยี่ยมได้

คลังเอฟเฟกต์เกม

หากคุณไม่ต้องการพัฒนาเอฟเฟกต์แสงของคุณเอง คุณสามารถใช้ประโยชน์จากคลังเอฟเฟกต์สำเร็จรูปจำนวนมากของเราได้ ด้วย URL ของแอป SignalRGB คุณสามารถติดตั้งและเปิดใช้งานเอฟเฟกต์แสงสาธารณะใดก็ได้ที่มีให้ดาวน์โหลดจาก SignalRGB ได้อย่างง่ายดาย

แนะนำให้ติดตั้งเอฟเฟกต์แสงที่แอปหรือเกมของคุณจะเปิดใช้งานตั้งแต่ตอนเปิดใช้งานครั้งแรก เพื่อให้มั่นใจว่าเอฟเฟกต์ทั้งหมดจะถูกเรียกใช้ได้อย่างรวดเร็ว

API route ต่อไปนี้พร้อมให้ใช้งานเพื่อช่วยในเรื่องนี้:

Request URI	วัตถุประสงค์
signalrgb://effect/install/EffectName	ติดตั้งเอฟเฟกต์แสงชื่อ EffectName
signalrgb://effect/apply/EffectName	เปิดใช้งานเอฟเฟกต์แสงชื่อ EffectName

หมายเหตุ

ชื่อเอฟเฟกต์คำนึงถึงตัวพิมพ์เล็ก-ใหญ่ และอักขระพิเศษใด ๆ ต้องผ่านการ เข้ารหัส URL ตัวอย่างเช่น ช่องว่างทั้งหมดควรแทนที่ด้วย %20

หากเอนจินหรือภาษาที่คุณเลือกไม่สามารถสื่อสารกับตัวจัดการโปรโตคอล URL แบบกำหนดเองได้ คุณก็ยังใช้ส่วนนี้ของ SignalRGB API ได้ เพียงเรียกใช้ไฟล์ปฏิบัติการ SignalRgbLauncher.exe ที่อยู่ใน C:\Users\<username>\AppData\Local\VortxEngine พร้อมอาร์กิวเมนต์ --url ที่ตั้งค่าเป็นพาธของ API route ที่คุณต้องการใช้ หากไม่ต้องการให้แอปถูกนำขึ้นมาแสดงด้านหน้า คุณสามารถเพิ่ม ?-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"

...
  // 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);

...

เอฟเฟกต์แบบกำหนดเอง

การสื่อสารกับ SignalRGB โดยตรงด้วยคำขอ HTTP ทำได้ง่ายเมื่อคุณรู้ว่าคำขอมีโครงสร้างอย่างไร โครงสร้างของคำขอมีดังนี้:

ประเภทคำขอ: POST

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

คำสั่งทั้งหมดที่ส่งจากแอปของคุณควรใช้ตัวแปร sender เดียวกัน ส่วนตัวแปร event คือที่สำหรับใส่ข้อมูลที่จะส่งไปยัง SignalRGB

ภายในเอฟเฟกต์ ข้อมูลทั้งหมดจะถูกส่งผ่านฟังก์ชัน onCanvasApiEvent ใช้ฟังก์ชันนี้เพื่อจัดการว่าเอฟเฟกต์ของคุณจะตอบสนองต่อคำขอ HTTP อย่างไร

โค้ดตัวอย่าง

ตัวอย่างพื้นฐานนี้แสดงวิธีที่เกม Unity หรือ Unreal Engine สามารถสื่อสารกับ SignalRGB เพื่อเรียกใช้เหตุการณ์ในเอฟเฟกต์แสงแบบกำหนดเอง อย่างไรก็ตาม คุณสามารถใช้วิธีส่งคำขอ HTTP แบบใดก็ได้เพื่อควบคุมเอฟเฟกต์แสงแบบกำหนดเอง ความยืดหยุ่นนี้หมายความว่าสามารถเพิ่มการรองรับ SignalRGB ให้กับเกมหรือแอปพลิเคชันได้แทบทุกตัว

เอฟเฟกต์แสง

เหตุการณ์ทั้งหมดที่ส่งไปยัง API route จะถูกส่งต่อไปยังเอฟเฟกต์แสงผ่านฟังก์ชัน 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 = ""; // 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

ฟังก์ชันลักษณะดังต่อไปนี้จะช่วยให้ 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 อย่าลืมเปลี่ยนพารามิเตอร์ sender ของ request URI ให้ตรงกับที่ 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"

...
  // 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);

...

คำเตือน

คุณต้องเพิ่มโมดูล Http ลงใน build dependencies ของ Unreal Engine โดยแก้ไข ProjectName.Build.cs ให้มีลักษณะดังนี้:

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