تكاملات الألعاب/التطبيقات

إضافة دعم SignalRGB إلى تطبيقك أو لعبتك أمر سريع وسهل. إذا كان مشروعك قادرًا على إرسال طلبات HTTP POST، فيمكنه الاستفادة من المجموعة الواسعة من الأجهزة المتوافقة مع SignalRGB.

هناك طريقتان رئيسيتان يمكن لتطبيقك أو لعبتك التكامل بهما مع SignalRGB: تشغيل تأثيرات موجودة مسبقًا، أو التواصل مع تأثير مخصص تطوّره بنفسك. يتطلب الخيار الأول وقت تطوير أقل بكثير، لكنه يقتصر على مكتبتنا من التأثيرات الجاهزة. أما الطريقة الثانية فقد تستغرق وقتًا أطول، لكنها تفتح أمامك إمكانيات لا حصر لها من حيث أنواع التأثيرات التي يمكنك إنشاؤها وعددها.

في النهاية، الأمر متروك لك كمطوّر لتحديد الطريقة الأنسب لمشروعك. ومع ذلك، يمكن لكلتا الطريقتين تقديم تجارب إضاءة رائعة.

مكتبة تأثيرات الألعاب

إذا كنت تفضل عدم تطوير تأثيرات الإضاءة الخاصة بك، فيمكنك الاستفادة من مكتبتنا الواسعة من التأثيرات الجاهزة. باستخدام روابط تطبيق SignalRGB، يمكنك بسهولة تثبيت وتفعيل أي تأثير إضاءة عام متاح للتنزيل من SignalRGB.

يُوصى بتثبيت تأثيرات الإضاءة التي سيفعّلها تطبيقك أو لعبتك عند تشغيله لأول مرة، لضمان تشغيل جميع التأثيرات بسرعة.

مسارات API التالية متاحة للمساعدة في ذلك:

عنوان 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 الذي تريد استخدامه. ولمنع إحضار التطبيق إلى الواجهة، يمكنك إضافة ?-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

عنوان 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 إلى تأثير الإضاءة عبر الدالة 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 في عنوان 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 إلى تبعيات البناء في 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!
  }
}