Photon 플러그인 지침서

Photon 플러그인은 Enterprise Cloud 또는 자체 호스팅 된 Photon Server에만 사용할 수 있습니다.

"단계별 지침서"는 초보자용입니다.

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)

클라이언트 코드를 변경하지 않고 플러그인에서 보낸 이벤트 데이터와 클라이언트에서 보낸 사람 액터 번호를 검색할 수 있으려면 (Dictionary<byte, object>)eventData 대신에 다음과 같이 예상 이벤트 구조로 데이터를 전송합니다. new Dictionary<byte, object>(){ { 245, eventData },{ 254,senderActorNr } }. 다음의 헬퍼 또는 랩퍼 메소드 중 하나를 사용할 수 있습니다:

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`에 할당하여 요청 데이터를 추가할 수도 있습니다.
자세한 내용은 [JSON 포스트](#json) 예제를 참조하세요.

<div class="alert alert-info">
주목할 만한 점은 Photon에 배타적이고 플러그인 로직에 중요한 두 가지 속성이 있다는 것입니다:  
<ul>
<li> <code>Async</code>: 응답이 수신될 때까지 룸 로직의 정상적인 처리를 중단해야 하는지를 나타내는 플래그입니다.
룸 로직이 HTTP 응답에 따라 달라지는 경우 이 값은 false로 설정해야 합니다.
<li> <code>UserState</code>: 각 요청에 대해 Photon Server에 의해 저장되고 응답의 콜백으로 다시 전송되는 객체.
</ul>
</div>

또한 `HttpRequest` 클래스는 다음 서명을 가져야 하는 응답 콜백에 대한 참조를 포함해야 합니다:
`public delegate void HttpRequestCallback(IHttpResponse response, object userState)`.

요청 객체가 설정되면, `IPluginHost.HttpRequest(HttpRequest request, ICallInfo info)`를 호출하여 요청 객체를 전송할 수 있습니다.

<div class="alert alert-info">
동기 모드에서 HTTP 요청을 보내는 경우 HTTP 응답을 기다리지 않고 ICallInfo 객체를 바로 처리하는 것은 의미가 없습니다.
아무런 소득도 없이 룸 파이버를 차단하는 것입니다.
응답 콜백이 트리거 될 때까지 플러그인 호출만 처리하는 것이 좋습니다.
</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 codes).
• RequestTimeout (1): 엔드 포인트가 시간 내에 응답을 보내지 않음.
• QueueTimeout (2): HttpRequestQueue 내에서 요청이 타임아웃 됨.
  요청이 대기 중일 때 타이머가 시작됩니다. 이전 쿼리에 시간이 너무 많이 걸리면 시간이 초과됩니다.
• Offline (3): 애플리케이션의 해당 HttpRequestQueue가 오프라인 모드입니다.
  HttpRequestQueue가 재연결 하는 시간인 10초 동안 아무런 HttpRequest가 업습니다.
• 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)를 사용합니다.

예제: 지연 SetProperties

C#

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

반복 타이머

반복 타이머는 주기적으로 메소드를 호출합니다.
첫 번째 콜백의 실행 시간과 다음 연속 실행 사이의 간격을 정의할 수 있습니다.
이런 타이머를 생성하기 위해서는 다음의 메소드를 사용해야 합니다:
object CreateTimer(Action callback, int dueTimeMs, int intervalMs);
이러한 종류의 타이머는 실행 중이고 플러그인이 로드되어 있는 한(룸이 닫히지 않음) 해당 메소드를 계속 호출합니다.
void IPluginHost.StopTimer(object timer)를 사용하여 언제든지 중지할 수 있습니다.

예제: 예정된 이벤트

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

예제: 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

Enterprise Cloud 로깅 환경 구성

당사 서버의 로그 파일에 대한 접근 권한이 부여되지 않았기 때문에 로그 또는 알림은 외부 서비스를 사용해야 합니다.
Logentries 또는 Papertrail을 사용하는 것을 권장합니다.
따라서 Enterprise 고객들은 당사로 연락하여 원하는 로깅 서비스로 프라이빗 클라우드를 구성할 것을 요청드립니다.
Logentries를 사용하려면 구성된 로그 토큰을 제공하십시오.
Papertrail 사용하려는 경우사용자 지정 URL과 포트 번호를 제공해 주십시오.

자체 호스팅 된 서버 로깅 환경 구성

기본값으로, 로그 출력은 GameServer 로그 항목과 더불어 "GSGame.log" 파일에서 확인할 수 있습니다.
분리된 로그 파일을 사용하기 위해서는, 다음 코드를 GameServer의 log4net 환경 구성 파일에 추가하십시오:

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>

Enterprise Cloud에서의 플러그인 버전 관리

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 특정 플러그인

클라이언트 SDK로 PUN을 사용하고 PUN과 함께 작동하는 서버 측 플러그인을 구현하려면 다음을 알아야 합니다:

• PUN은 유니티 기본 클래스를 중심으로 일부 추가적인 사용자 지정 유형을 등록합니다.
  플러그인에서 이러한 사용자 지정 유형을 처리하려면 플러그인에서도 동일한 사용자 지정 유형을 등록해야 합니다.
  이러한 모든 사용자 지정 유형과 등록 방법은 PUN 패키지의 "CustomTypes.cs" 클래스에서 확인할 수 있습니다.
  일부 사용자 지정 유형을 등록하지 않으면 오류 또는 예기치 않은 동작이 발생할 수 있습니다.
  이러한 문제점들에 대해서 알림을 받기 위해서는 IGamePlugin.OnUnknownType 또는 IGamePlugin.ReportError을 구현해야 합니다.

• 모든 PUN의 높은 수준의 고유한 기능은 자세하게 살펴보면 RaiseEvent를 사용합니다.
  각 기능은 하나 이상의 이벤트 코드와 특수 이벤트 데이터 구조를 사용합니다.
  PUN에서 예약한 이벤트 목록을 가져오려면 PUN 패키지 내의 "PunClasses.cs" 파일에서 "PunEvent" 클래스를 확인하십시오.
  예를 들어 OnSerializeView 호출을 인터셉트하려면 OnRaiseEvent 콜백을 구현하고 해당 유형의 이벤트 코드(이 경우 "SendSerialize = 201")를 캐치해야 합니다.
  각 이벤트의 예상 콘텐츠를 확인하려면 PUN 코드에서 이벤트 데이터가 어떻게 구성되는지 살펴보거나 플러그인 내부의 수신 이벤트에서 해당 데이터를 검사하십시오.

• Photon 플러그인 내의 PhotonNetwork.ServerTimestamp를 받기 위해서는 Environment.TickCount를 사용하세요.

AuthCookie

보안 데이터라고도 하는 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: 활성 액터에서 AuthCookie의 취득
  예,

  C#

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

• 액터 별로 보안된 인증 쿠키를 업데이트를 하기 위해서 void IActor.UpdateSecure(string key, object value)를 사용하세요.