Tích hợp game/ứng dụng

Thêm hỗ trợ SignalRGB vào ứng dụng hoặc game của bạn rất nhanh chóng và đơn giản. Nếu dự án của bạn có thể gửi HTTP POST requests, nó có thể sử dụng nhiều loại thiết bị tương thích của SignalRGB.

Có hai cách chính để ứng dụng hoặc game của bạn có thể được tích hợp với SignalRGB: kích hoạt các hiệu ứng có sẵn hoặc giao tiếp với một hiệu ứng tùy chỉnh được phát triển đặc biệt. Tùy chọn đầu tiên đòi hỏi ít nỗ lực phát triển hơn đáng kể, nhưng bị giới hạn ở thư viện các hiệu ứng được tạo sẵn của chúng tôi. Cách tiếp cận thứ hai có thể tốn nhiều thời gian hơn, nhưng mở ra vô số khả năng về loại và số lượng hiệu ứng có thể tạo ra.

Cuối cùng, với tư cách là nhà phát triển, bạn có thể quyết định cách tiếp cận nào phù hợp nhất cho dự án của mình. Tuy nhiên, cả hai phương pháp đều có thể mang lại trải nghiệm ánh sáng tuyệt vời.

Thư viện hiệu ứng game

Nếu bạn không muốn phát triển các hiệu ứng ánh sáng của riêng mình, bạn có thể sử dụng thư viện hiệu ứng được tạo sẵn phong phú của chúng tôi. Thông qua URL ứng dụng SignalRGB, bạn có thể dễ dàng cài đặt và kích hoạt bất kỳ hiệu ứng ánh sáng công khai nào có sẵn để tải xuống trên SignalRGB.

Nên cài đặt trước các hiệu ứng ánh sáng mà ứng dụng hoặc game của bạn cần kích hoạt khi lần đầu chạy, để tất cả các hiệu ứng có thể được kích hoạt nhanh chóng.

Các tuyến API sau đây có sẵn cho mục đích này:

URI yêu cầu	Mục đích
signalrgb://effect/install/EffectName	Cài đặt hiệu ứng ánh sáng có tên EffectName
signalrgb://effect/apply/EffectName	Kích hoạt hiệu ứng ánh sáng có tên EffectName

Ghi chú

Tên hiệu ứng phân biệt chữ hoa chữ thường, và tất cả các ký tự đặc biệt phải được mã hóa URL. Ví dụ: dấu cách phải được thay thế bằng %20.

Nếu engine hoặc ngôn ngữ đã chọn không thể giao tiếp với các trình xử lý giao thức URL tùy chỉnh, phần này của SignalRGB API vẫn có thể được sử dụng. Để thực hiện điều này, chỉ cần chạy tệp thực thi SignalRgbLauncher.exe trong thư mục C:\Users\<username>\AppData\Local\VortxEngine với đối số --url đến đường dẫn tuyến API mong muốn. Để ngăn ứng dụng xuất hiện ở tiền cảnh, có thể thêm ?-silentlaunch-.

Ví dụ: để cài đặt hiệu ứng có tên Azure, tệp thực thi được chạy với đối số sau:

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

Unity

Unreal Engine

Lớp C++ sau đây có thể được sử dụng với Unreal Engine để cài đặt và kích hoạt bất kỳ hiệu ứng SignalRGB nào.

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

Nên cài đặt tất cả các hiệu ứng sẽ được sử dụng khi khởi động ứng dụng, để chúng có thể được kích hoạt nhanh chóng.

Ví dụ sau đây cho thấy cách một hiệu ứng có thể được cài đặt và kích hoạt bằng lớp SignalEffectApi.

#include "SignalEffectApi.h"

...
  // Effekt-API initialisieren.
  SignalEffectApi srgbEffect;

  // Name des zu installierenden Effekts festlegen.
  std::string effectName = "Azure";

  // Effekt installieren.
  srgbEffect.InstallEffect(effectName);

  // Effekt anwenden.
  srgbEffect.ApplyEffect(effectName);

...

Hiệu ứng tùy chỉnh

Giao tiếp trực tiếp với SignalRGB thông qua HTTP requests rất đơn giản để triển khai khi biết cấu trúc request. Cấu trúc request như sau:

Loại request: POST

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

Tất cả các request được gửi bởi ứng dụng phải sử dụng cùng một biến sender. Biến event chứa dữ liệu được truyền đến SignalRGB.

Trong hiệu ứng, tất cả dữ liệu được gửi thông qua hàm onCanvasApiEvent. Hàm này được sử dụng để kiểm soát cách hiệu ứng phản hồi với HTTP requests.

Ví dụ code

Ví dụ đơn giản này cho thấy cách game Unity hoặc Unreal Engine có thể giao tiếp với SignalRGB để kích hoạt các sự kiện trong hiệu ứng ánh sáng tùy chỉnh. Tuy nhiên, bất kỳ phương pháp nào để gửi HTTP requests đều có thể được sử dụng để kiểm soát hiệu ứng ánh sáng tùy chỉnh. Sự linh hoạt này có nghĩa là hỗ trợ SignalRGB có thể được thêm vào hầu hết bất kỳ game hoặc ứng dụng nào.

Hiệu ứng ánh sáng

Tất cả các sự kiện được gửi đến tuyến API được chuyển tiếp đến hiệu ứng ánh sáng thông qua hàm onCanvasApiEvent. Có nhiều cách để quản lý sự kiện, nhưng ví dụ sau đây đơn giản và dễ hiểu. Ai phát triển thứ gì đó phức tạp hơn với nhiều sự kiện nên xem xét phương pháp State Handler để theo dõi các sự kiện và các hiệu ứng ánh sáng tương ứng của chúng.

<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 zum Speichern des zuletzt empfangenen Ereignisses

  function onCanvasApiEvent(apiEvent) {
    if (apiEvent["sender"] == "apiTestApp") { // Nur auf API-Ereignisse mit dem Sender "apiTestApp" reagieren. Dies sollte auf den eigenen Sender-String geändert werden.
      activeEvent = apiEvent["event"]; // Die activeEvent-Variable auf die zuletzt empfangenen API-Ereignisdaten setzen.
    }
  }

  function update() {
    if (activeEvent == "allRed") { // Canvas bei einem allRed-Ereignis komplett rot färben
      ctx.fillStyle = '#FF0000';
      ctx.fillRect(0, 0, width, height);
    } else { // Andernfalls Canvas schwarz färben
      ctx.fillStyle = '#000000';
      ctx.fillRect(0, 0, width, height);
    }

    window.requestAnimationFrame(update);
  }

  window.requestAnimationFrame(update);
</script>

Unity

Hàm như sau cho phép Unity giao tiếp với SignalRGB. Tuy nhiên, bất kỳ phương pháp nào để gửi HTTP POST requests đều có thể được sử dụng.

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

Lớp C++ sau đây có thể được sử dụng với Unreal Engine để cho phép giao tiếp thông qua SignalRGB API. Đảm bảo rằng tham số sender của URI request khớp với tham số mà Lightscript sử dụng.

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

Để kích hoạt hiệu ứng ánh sáng trong code game, chỉ cần gọi hàm SendEvent với tên sự kiện mong muốn cũng như tên mà ứng dụng hoặc game tự nhận dạng với SignalRGB.

#include "SignalApi.h"

...
  // Sender-Variable festlegen.
  const std::string SAPI_APPNAME = "apiTestGame";
  // SignalApi-Klasse initialisieren.
  SignalApi sapi;
  // Namen des Ereignisses festlegen.
  std::string eventName = "weaponFired";
  // API-Ereignis an SignalRGB senden.
  sapi.SendEvent(SAPI_APPNAME, eventName);

...

Chú ý

Module Http phải được thêm vào các phụ thuộc build của Unreal Engine bằng cách sửa đổi ProjectName.Build.cs như sau:

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 PHẢI được thêm vào mảng này, nếu không build sẽ thất bại!
  }
}