Photon Plugins Manual

Photon Plugins are available only for Enterprise Cloud or self-hosted Photon Server.

A "Step by Step Guide" is available for beginners.

namespace MyCompany.MyProject.HivePlugin
{
  public class CustomPlugin : PluginBase
  {
    public override string Name
    {
        get
        {
            return "CustomPlugin"; // anything other than "Default" or "ErrorPlugin"
        }
    }
  }
}

namespace MyCompany.MyProject.HivePlugin
{
  public class PluginFactory : PluginFactoryBase
  {
    public override IGamePlugin Create(string pluginName)
    {
        return new CustomPlugin();
    }
  }
}

<Configuration>
  <PluginSettings Enabled="true">
    <Plugins>
      <Plugin
          Name="{pluginName}"
          Version="{pluginVersion}"
          AssemblyName="{pluginDllFileName}.dll"
          Type="{pluginNameSpace}.{pluginFactoryClassName}"
      />
    </Plugins>
  </PluginSettings>
</Configuration>

using System.Collections.Generic;

public class PluginFactory : IPluginFactory
{

    public IGamePlugin Create(IPluginHost gameHost, string pluginName, Dictionary<string, string> config, out string errorMsg)
    {
        IGamePlugin plugin = new DefaultPlugin(); // default
        switch(pluginName)
        {
            case "Default":
                // name not allowed, throw error
            break;
            case "NameOfYourPlugin":
                plugin = new NameOfYourPlugin();
            break;
            case "NameOfOtherPlugin":
                plugin = new NameOfOtherPlugin();
            break;
            default:
                //plugin = new DefaultPlugin();
            break;
        }
        if (plugin.SetupInstance(gameHost, config, out errorMsg))
        {
            return plugin;
        }
        return null;
    }
}

void IPluginHost.BroadcastEvent(byte target, int senderActor, byte targetGroup, byte evCode, Dictionary<byte, object> data, byte cacheOp, SendParameters sendParameters = null);

void IPluginHost.BroadcastEvent(IList<int> recieverActors, int senderActor, byte evCode, Dictionary<byte, object> data, byte cacheOp, SendParameters sendParameters = null);

protected void BroadcastEvent(byte code, Dictionary<byte, object> data)

In order to be able to retrieve event data sent from plugins and the sender actor number from clients without changing client code, send the data in the expected events structure as follows new Dictionary<byte, object>(){ { 245, eventData },{ 254,senderActorNr } } instead of (Dictionary<byte, object>)eventData. You could use one of the following helper or wrapper methods:

C#

public void RaiseEvent(byte eventCode, object eventData,
    byte receiverGroup = ReciverGroup.All,
    int senderActorNumber = 0,
    byte cachingOption = CacheOperations.DoNotCache,
    byte interestGroup = 0,
    SendParameters sendParams = default(SendParameters))
{
    Dictionary<byte, object> parameters = new Dictionary<byte, object>();
    parameters.Add(245, eventData);
    parameters.Add(254, senderActorNumber);
    PluginHost.BroadcastEvent(receiverGroup, senderActorNumber, interestGroup, eventCode, parameters, cachingOption, sendParams);
}

public void RaiseEvent(byte eventCode, object eventData, IList<int> targetActorsNumbers,
    int senderActorNumber = 0,
    byte cachingOption = CacheOperations.DoNotCache,
    SendParameters sendParams = default(SendParameters))
{
    Dictionary<byte, object> parameters = new Dictionary<byte, object>();
    parameters.Add(245, eventData);
    parameters.Add(254, senderActorNumber);
    PluginHost.BroadcastEvent(targetActorsNumbers, senderActorNumber, eventCode, parameters, cachingOption, sendParams);
}
```</div>

### 外向HTTP調用

`HttpRequest` 是一個用於構造HTTP請求的輔助類。
使用此類，您可以設置URL和HTTP方法（默認為 "GET"），所需的`Accept`和`ContentType`標頭。
這些屬性的值應該被[HttpWebRequest](https://msdn.microsoft.com/en-us/library/system.net.httpwebrequest(v=vs.110).aspx)所支持。
此外，您可以將其他自定義HTTP標頭指定為一個`IDictionary<string, string>`並將其分配給`HttpRequest.CustomHeaders`。
您也可以通過先將請求數據轉換為`MemoryStream`對象，然后將其賦值給`HttpRequest.DataStream`來添加請求數據。
參見[Post JSON](#json)的例子，了解更多關於如何執行。

`HttpRequest`類也應該持有對響應回調的引用，它應該有以下簽名：
`public delegate void HttpRequestCallback(IHttpResponse response, object userState)`。

一旦請求對象被設置好，您可以通過調用`IPluginHost.HttpRequest(HttpRequest request, ICallInfo info)`來發送它。

<div class="alert alert-info">
What's worth noting, is that there are two properties that are exclusive to Photon and important in the plugins logic:  
<ul>
<li> <code>Async</code>: a flag that indicates if the normal processing of the room logic should be interrupted until the response is received or not.
This should be set to false if the room logic depends on the HTTP response.
<li> <code>UserState</code>: an object that will be saved by Photon Server for each request and sent back in the response's callback.
</ul>
</div>

`HttpRequest`類也應該持有對響應回調的引用，它應該有以下簽名：
`public delegate void HttpRequestCallback(IHttpResponse response, object userState)`.

一旦請求對象被設置完成，您可以通過調用 `IPluginHost.HttpRequest(HttpRequest request, ICallInfo info)`來發送它。

<div class="alert alert-info">
If you send a HTTP Request in synchronous mode, it does not make sense to process the ICallInfo object right away without waiting for the HTTP response.
You would be blocking the room fiber for nothing.
We recommend that you process the plugin call only until the response callback is triggered.
</div>

#### 非同步HTTP請求

您可以延遲處理一個掛鉤，直到收到一個HTTP響應：
```csharp
HttpRequest request = new HttpRequest()
{
  Callback = OnHttpResponse,
  Url = yourCustomUrl,
  Async = true,
  UserObject = yourOptionalUserObject
};
PluginHost.HttpRequest(request, info);

當收到響應時，如果需要，您應該決定如何處理ICallInfo。

C#

private void OnHttpResponse(IHttpResponse response, object userState)
{
  ICallInfo info = response.CallInfo;
  ProcessCallInfoIfNeeded(info);

處理HTTP響應

在響應回調中，首先要檢查的是IHttpResponse.Status。
它可以採取以下HttpRequestQueueResult值之一。

• Success (0)：端點返回一個成功的HTTP狀態代碼。(即2xx代碼)。
• RequestTimeout (1)：該端點沒有及時返回響應。
• QueueTimeout (2)：請求在HttpRequestQueue中超時。
  當一個請求排隊時，計時器就開始了。當之前的查詢花費了太多時間時，它就會超時。
• Offline (3)：應用程序各自的HttpRequestQueue處於離線模式。
  在10秒內不應該進行HttpRequest，這是HttpRequestQueue重新連接的時間。
• QueueFull (4)：HttpRequestQueue已經達到了各自應用程序的某個閾值。
• Error (5)：請求的URL不能被解析，或者主機名不能被解析，或者端點無法到達。
  如果端點返回一個錯誤的HTTP狀態代碼，也可能發生這種情況。(例如：400:BAD REQUEST)

如果結果不是 Success (0)，您可以通過以下屬性獲得更多關於出錯的細節：

• Reason: 錯誤的可讀形式。
  當IHttpResponse.Status等於HttpRequestQueueResult.Error時很有用。
• WebStatus：包含WebExceptionStatus的代碼。
  這表明任何最終的WebException。
• HttpCode：包含返回的HTTP狀態代碼。

下面是一個關於如何在代碼中執行的例子：

C#

private void OnHttpResponse(IHttpResponse response, object userState)
{
  switch(response.Status)
    {
    case HttpRequestQueueResult.Success:
      // on success logic
      break;
    case HttpRequestQueueResult.Error:
      if (response.HttpCode <= 0)
      {
        PluginHost.BroadcastErrorInfoEvent(
          string.Format("Error on web service level: WebExceptionStatus={0} Reason={1}",
          (WebExceptionStatus)response.WebStatus, response.Reason));
      }
      else
      {
        PluginHost.BroadcastErrorInfoEvent(
          string.Format("Error on endpoint level: HttpCode={0} Reason={1}",
          response.HttpCode, response.Reason));
      }
      break;
    default:
      PluginHost.BroadcastErrorInfoEvent(
        string.Format("Error on HttpQueue level: {0}", response.Status));
      break;
  }
}

下面是一個關於如何在代碼中執行的例子：

為了方便使用，Photon插件SDK提供了兩種從HTTP響應中獲取數據的方法。
在執行IHttpResponse的類中暴露了兩個屬性。

• ResponseData: 響應體的字節數。如果收到的數據不是文本的，它就會很有用。
• ResponseText: 響應體的UTF8字符串版本。如果收到的數據是文本的，它可能很有用。

響應類也持有對相應的HttpRequest的引用，以防以後需要。
它可以在IHttpResponse.Request中使用。

計時器

計時器是可以設置的對象，其目的是在特定的時間段後調用一個方法。
一旦計時器被創建，倒計時就會自動開始。
它是安排或推遲插件執行代碼的最佳方式。

Photon插件SDK根據不同的使用情況提供兩種不同的計時器：

一次性計時器

一次性計時器是指在一定時間內觸發一個方法。
為了創建這樣的計時器，您需要使用以下方法：
object CreateOneTimeTimer(ICallInfo callInfo, Action callback, int dueTimeMs);
您不需要停止這種計時器，除非您想在預定動作發生之前取消它。
若是如此，您應該使用void IPluginHost.StopTimer(object Timer)。

Example: delaying SetProperties

C#

public override void BeforeSetProperties(IBeforeSetPropertiesCallInfo info)
{
  PluginHost.CreateOneTimeTimer(
                info,
                () => info.Continue(),
                1000);
}

重復計時器

一個重復的計時器會定期調用一個方法。
您可以定義第一個回調的執行時間和下面連續執行的時間間隔。
為了創建這樣的計時器，您需要使用以下方法：
對象CreateTimer(Action callback, int dueTimeMs, int intervalMs);
這種計時器將一直調用相應的方法，只要它在運行，並且插件在加載（房間沒有關閉）。
它可以在任何時候使用void IPluginHost.StopTimer(object Timer)來停止。

Example: scheduled events

C#

private object timer;
public override void OnCreateGame(ICreateGameCallInfo info)
{
  info.Continue();
  timer = PluginHost.CreateTimer(
        ScheduledEvent,
        1000,
        2000);
}
private void ScheduledEvent()
{
  BroadcastEvent(1, new Dictionary<byte, string>() { { 245, "Time is up" } });
}
public override void BeforeCloseGame(IBeforeCloseGameCallInfo info)
{
  PluginHost.StopTimer(timer);
  info.Continue();
}

自定義類型

如果您希望Photon支持您的自定義類的序列化，那麼您需要注冊它們的類型。
您需要為每個類型手動分配一個代碼（字節），並提供該類的字段和屬性的序列化和序列化方法。
注冊新類型的代碼也應該用在客戶端。
然後為了完成注冊，您需要調用以下方法：

C#

bool IPluginHost.TryRegisterType(Type type, byte typeCode, Func<object, byte[]> serializeFunction, Func<byte[], object> deserializeFunction);

Example: Registering CustomPluginType

下面是自定義類型注冊的例子：

C#

class CustomPluginType
{
  public int intField;
  public byte byteField;
  public string stringField;
}

序列化方法應該將自定義類型的對象轉換成字節數組。
請注意，您應該先將該對象轉換為預期的類型（CustomPluginType）。

C#

private byte[] SerializeCustomPluginType(object o)
{
  CustomPluginType customObject = o as CustomPluginType;
  if (customObject == null) { return null; }
  using (var s = new MemoryStream())
    {
    using (var bw = new BinaryWriter(s))
    {
      bw.Write(customObject.intField);
      bw.Write(customObject.byteField);
      bw.Write(customObject.stringField);
      return s.ToArray();
    }
  }
}

解除方法應做反向執行。
它將自定義類型的對象從字節數組中構造回來。

C#

private object DeserializeCustomPluginType(byte[] bytes)
{
  CustomPluginType customObject = new CustomPluginType();
  using (var s = new MemoryStream(bytes))
    {
    using (var br = new BinaryReader(s))
    {
      customObject.intField = br.ReadInt32();
      customObject.byteField = br.ReadByte();
      customObject.stringField = br.ReadString();
    }
  }
  return customobject;
}

最後，我們需要注冊CustomPluginType。
一旦插件在SetupInstance中被初始化，我們就可以這樣做：

C#

public override bool SetupInstance(IPluginHost host, Dictionary<string, string> config, out string errorMsg)
{
  host.TryRegisterType(typeof(CustomPluginType), 1,
    SerializeCustomPluginType,
    DeserializeCustomPluginType);
  return base.SetupInstance(host, config, out errorMsg);
}

記錄

為每個插件實例創建一個新的IPluginLogger對象，用它來記錄插件的一切：

C#

public const string PluginName = "MyPlugin";

private IPluginLogger pluginLogger;

public override bool SetupInstance(IPluginHost host, Dictionary<string, string> config, out string errorMsg)
{
    pluginLogger = host.CreateLogger(PluginName);
    // ...
}

// ...

this.pluginLogger.LogDebug("debug");
this.pluginLogger.LogWarning("warning");
this.pluginLogger.LogError("error");
this.pluginLogger.LogFatal("fatal");

當設置日志記錄器的名稱（傳遞給IPluginHost.CreateLogger(loggerName)）時，我們在日志記錄器的名稱前面加上Plugin.。
例如，如果您設置MyPlugin.MyClass，它將被記錄為Plugin.MyPlugin.MyClass。
上面的代碼片段將在日誌級別被設置為最大級別的情況下生成這些日誌條目：

2020-01-31 17:10:07,394 [1] DEBUG  Plugin.MyPLugin - debug
2020-01-31 17:10:07,901 [1] WARN  Plugin.MyPLugin - warning
2020-01-31 17:10:08,152 [1] ERROR  Plugin.MyPLugin - error
2020-01-31 17:10:08,724 [1] FATAL  Plugin.MyPLugin - fatal

企業雲端日誌配置

由於不允許訪問我們伺服器上的日誌文件，所以應該使用外部服務來獲取日誌或警報。
我們推薦使用Logentries或Papertrail。
所以我們要求我們的企業客戶與我們聯系，用他們選擇的日誌服務配置他們的私有雲端。
如果您想使用Logentries提供配置的日誌令牌。
如果您想使用Papertrail提供您的自定義URL與端口。

自有伺服器的日誌配置

默認情況下，日誌輸出可以在 "GSGame.log "文件中與GameServer日誌條目一起被檢索。
要使用單獨的日誌文件，請在GameServer的log4net配置文件（"log4net.config"）中添加以下片段：

XML

<!-- "plugin" log file appender -->
<appender name="PluginLogFileAppender" type="log4net.Appender.RollingFileAppender">
    <file type="log4net.Util.PatternString" value="%property{Photon:ApplicationLogPath}\\Plugins.log" />
    <param name="AppendToFile" value="true" />
    <param name="MaxSizeRollBackups" value="20" />
    <param name="MaximumFileSize" value="10MB" />
    <param name="RollingStyle" value="Size" />
    <param name="LockingModel" type="log4net.Appender.FileAppender+MinimalLock" />
    <layout type="log4net.Layout.PatternLayout">
        <param name="ConversionPattern" value="%d [%t] %-5p %c - %m%n" />
    </layout>
</appender>
<!-- CUSTOM PLUGINS:  -->
<logger name="Photon.Hive.HiveGame.HiveHostGame.Plugin" additivity="false">
    <level value="DEBUG" />
    <appender-ref ref="PluginLogFileAppender" />
</logger>

企業雲端中的插件版本管理

Currently Photon Plugins support only side-by-side assembly versioning: one plugin DLL version per AppId.

Here are two methods we recommend for rolling out new plugins versions:

A. "Compatible" plugins deploy: does not require new client version

1. Upload new version of plugins assembly.
2. On a staging AppId: test to verify that new version works as expected. (recommended)
3. Update production AppId configuration to use new plugins assembly version.

B. "Incompatible" plugins deploy: requires new client version

1. Upload new version of plugins assembly.
2. Setup a new production AppId.
3. Configure the new production AppId to use new plugins assembly version.

PUN特定的插件

如果您使用PUN作為一個客戶端SDK，並想執行一個與之配合的伺服器端插件，您應該知道以下幾點：

• PUN注冊了一些額外的自定義類型，主要是Unity基本類。
  如果您想從插件中處理這些，您也需從插件中注冊同樣的自定義類型。
  您可以在PUN包內的 "CustomTypes.cs "類中找到所有這些自定義類型和如何注冊它們。
  如果不注冊一些自定義類型，可能會導致錯誤或意外的行為。
  您應該執行IGamePlugin.OnUnknownType或IGamePlugin.ReportError以獲得此類問題的通知。

• 所有PUN的進階和獨特的功能都在內部使用RaiseEvent。
  每個功能都使用一個或多個事件代碼和特殊的事件數據結構。
  要獲得PUN保留的事件列表，請看PUN包內 "PunClasses.cs "文件中的 "PunEvent "類。
  例如，為了攔截OnSerializeView的調用，您需要執行 "OnRaiseEvent "回調並捕捉相應類型的事件代碼，在此例子中是 "SendSerialize = 201"。
  要知道每個事件的預期內容，看看它的事件數據是如何在PUN的代碼中構建的，或者從插件內部的傳入事件中檢查它。

• 要在Photon插件中獲得PUN的PhotonNetwork.ServerTimestamp，請使用Environment.TickCount。

AuthCookie

也稱為安全數據，是由設置為認証提供者的網絡服務返回的可選JSON對象。
這個對象將不能從客戶端訪問。
更多信息請訪問自定義認証文檔頁面。

從插件中，您可以按以下方式訪問AuthCookie。

• ICallInfo.AuthCookie：獲取觸發掛鉤的當前角色的AuthCookie。
  然而，在OnBeforeCloseGame和OnCloseGame中，IBeforeCloseGameCallInfo.AuthCookie和ICloseGameCallInfo.AuthCookie分別不會有任何值，因為這些是在用戶之外觸發的。
  例如：

  C#

  public void OnCreateGame(ICreateGameCallInfo info)
  {
      Dictionary<string, object> authCookie = info.AuthCookie;
  

• IActor.Secure: 獲取任何活動actor的AuthCookie。
  例如：

  C#

  foreach (var actor in this.PluginHost.GameActorsActive)
  {
      var authCookie = actor.Secure as Dictionary<string, object>;
  }
  

• 使用void IActor.UpdateSecure(string key, object value)更新每個角色的安全認証cookie。