This page is a work in progress and could be pending updates.
server | v5 switch to v4  

Photon Plugins FAQs

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

Contents

Configuration

Does Photon Support Multiple Plugins?

Only one plugins assembly (DLL) or plugins factory can be configured at a time per application. In this DLL you can have as many plugins as you want. Only one plugin will be loaded and instantiated upon room creation. There is a 1 to 1 relationship between room and instance of a plugin - so each room has its own instance of a plugin.

The following configuration is not allowed:

<PluginSettings Enabled="true">
    <Plugins>
        <Plugin …/>
        <Plugin …/>
    </Plugins>
</PluginSettings>

Back To Top

How To Choose Which Plugin To Use When Creating A Room?

Our plugin model uses a factory pattern. Plugins are instantiated by name on demand.

Client creates rooms requesting a plugin setup using roomOptions.Plugins. roomOptions.Plugins is of type string[] where the first string (roomOptions.Plugins[0]) should be a plugin name that will be passed to the factory.

Examples:
roomOptions.Plugins = new string[] { "NameOfYourPlugin" };
or
roomOptions.Plugins = new string[] { "NameOfOtherPlugin" };

If the client doesn't send anything, the server will either use the default (when nothing is configured) or whatever the plugin factory returns on create if it is configured.

In the factory just use the name to load the corresponding plugin as follows:

public class PluginFactory : IPluginFactory 
{
    public IGamePlugin Create(IPluginHost gameHost, string pluginName, Dictionary<string, string> config, out string errorMsg) 
    {
        var 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;
    }
}

If the name of the returned plugin in PluginFactory.Create does not match the one requested by client. Then the plugin will be unloaded and the client's create or join operation will fail with PluginMismatch (32757) error.

Back To Top

I'd Like To Read Files From Disk On Runtime. Do Plugins Have Access To The File System? Do I Need To Download The Files From An External Server?

You can upload extra files along with the ones essential to the plugin. The path to the files can then be retrieved using typeof(yourplugin).Assembly.Location.

Back To Top

Do Dependency Modules (DLLs) Get Automatically Loaded With The Main Plugins DLL? Why Am I Getting A System.TypeLoadException?

Using external modules should work by referencing the DLLs or projects in the plugins solution. You need to make sure all referenced dependencies' modules get deployed to the same directory as the plugin DLL in order for them to get loaded and linked.

Back To Top

Callbacks

What Methods Are Called When A Player Tries To Enter A Room?

In order to answer this question, we need to understand that there are four different scenarios that involves a player trying to enter a room either by creating, joining or rejoining it.

In general the structures of JoinRoom and CreateRoom operations are very similar. It might help to see them as one logical Join operation with different JoinMode values:

  1. Create: OpCreateRoom: error is returned if the room already exist
  2. Join: OpJoinRoom (JoinMode.Default or not set), OpJoinRandomRoom: error is returned if the room doesn't exist
  3. CreateIfNotExists: OpJoinRoom (JoinMode.CreateIfNotExist): create room if it doesn't exist
  4. RejoinOnly: OpJoinRoom (JoinMode.RejoinOnly): error if actor does not exist in room already

If the room is in memory 2) to 4) will trigger a BeforeJoin and assuming you call {ICallInfo}.Continue(), OnJoin will be called.

OnCreateGame is called right after the room creation, once the plugin is setup and just before the actor is added to the room. This can be triggered by 1), 3) and 4). The latter can happen only if saving and loading the state is being handled properly. This happens when a player asks to rejoin and the room that was removed from servers memory. Photon will create it anyway and setup the plugin. The plugin is then expected to retrieve the serialized state from a database or an external service and call SetSerializedGameState. The state will contain a list of actors, all in inactive state. The rejoin reactivates the rejoining actor.

Back To Top

How To Get The Actor Number In Plugin Callbacks?

Here is how to get ActorNr in plugins hooks:

1. OnCreateGame, Info.IsJoin == False:

ActorNr = 1: The first actor of the game, the one who creates it, will always have the actor number set to 1.

Back To Top

2. OnCreateGame, Info.IsJoin == True:

A. Before Info.Continue();

Get ActorNr by UserId from list of inactive actors: In case the room is being "recreated" by loading its game state. Then you need to find the actor number in your game state by looping over ActorList from the loaded room state and comparing with the UserId. (UserId may not be available which will make rejoin fail, this requires creating rooms with CheckUserOnJoin and unique UserId per Actor)

// load State from webservice or database or re-construct it
if (this.PluginHost.SetGameState(state)) 
{
    int actorNr = 0;
    foreach (var actor in PluginHost.GameActorsInactive)
    {
        if (actor.UserId == info.UserId)
        {
            actorNr = actor.ActorNr;
            break;
        }
     }
     if (actorNr == 0) 
     {
         if (!asyncJoin) 
         {
             // error, join will fail with 
             // ErrorCode.JoinFailedWithRejoinerNotFound = 32748, // 0x7FFF - 19,
         } 
         else 
         {
             actorNr = PluginHost.GetSerializableGameState().ActorCounter + 1;
         }
   }
}

Otherwise, if you send the "correct" ActorNr from client in JoinRoom operation, you can get it from info.Request.ActorNr.

Back To Top

B. After Info.Continue();

Get ActorNr by UserId from list of active actors.

int actorNr;
foreach (var actor in PluginHost.GameActorsActive)
{
    if (actor.UserId == info.UserId)
    {
        actorNr = actor.ActorNr;
        break;
    }
}

Back To Top

3. BeforeJoin

A. Before Info.Continue();
int actorNr = 0;
switch (info.Request.JoinMode)
{
    case JoinModeConstants.JoinOnly:
    case JoinModeConstants.CreateIfNotExists:
        actorNr = PluginHost.GetSerializableGameState().ActorCounter + 1;
        break;
    case JoinModeConstants.RejoinOnly:
        foreach (var actor in PluginHost.GameActorsInactive)
        {
            if (actor.UserId == info.UserId)
            {
                actorNr = actor.ActorNr;
                break;
             }
         }
         if (actorNr == 0)
         {
             // error, join will fail with 
             // ErrorCode.JoinFailedWithRejoinerNotFound = 32748, // 0x7FFF - 19,
          }
          break;
      case JoinModeConstants.RejoinOrJoin:
          foreach (var actor in PluginHost.GameActorsInactive)
          {
              if (actor.UserId == info.UserId)
              {
                  actorNr = actor.ActorNr;
                  break;
              }
           }
           if (actorNr == 0)
           {
               actorNr = PluginHost.GetSerializableGameState().ActorCounter + 1;
           }
           break;
}

Otherwise, if you send the "correct" ActorNr from client in JoinRoom operation, you can get it from info.Request.ActorNr.

Back To Top

B. After Info.Continue();

Get ActorNr by UserId from list of active actors.

int actorNr;
foreach (var actor in this.PluginHost.GameActorsActive)
{
    if (actor.UserId == info.UserId)
    {
         actorNr = actor.ActorNr;
         break;
    }
}

Back To Top

4. OnJoin, OnRaiseEvent, BeforeSetProperties, OnSetProperties, OnLeave:

Use the available info.ActorNr.

Back To Top

5. BeforeCloseGame, OnCloseGame:

No way to get ActorNr as the hook is triggered by server and not by client operation.

Back To Top

Is It Possible To Create Rooms From The Server?

No it is not possible to do so.

Back To Top

Is It Possible To Remove Rooms From The Server?

No it is not possible to do so.

Back To Top

What Is The Best Way To Know What Data Is Available In The Plugin Events?

In general, the ICallInfo callback parameter of the event should expose what it is needed. For most cases, actual operation request parameters can be retrieved through the {ICallInfo}.OperationRequest (or Request) property.

Back To Top

What Does UseStrictMode Do?

The idea of the plugin is that you hook into the "normal" Photon flow before we process the incoming request or after.

Initially we did not enforce that you had to call anything. Which essentially was the same as canceling default processing of received request. This makes the developer responsible of implementing whatever it is required from scratch without making use of any of the default callbacks logic. This has caused some unexpected issues. Canceling is not always what the developer wanted to do. So we introduced the strict mode - which now expects a decision by the developer. Now you are expected to call Continue, Fail or Cancel only once (any of them).

Back To Top

When Overriding Callback Methods Of PluginBase, Do I Need To Call base.XXX()?

All callback methods inside PluginBase include a call to Continue() at the end. The idea is that by inheriting from the PluginBase you only have to override the methods you are interested in. Sometimes you just need to add extra code after or before base.XXX() and sometimes you need to change the default behavior completely. In the first case, you should not add any call to the ICallInfo processing methods. In the second case, you should not call base.XXX(), make your own implementation of the method from scratch then add a call to one of the available ICallInfo processing methods. There is one exception though, which is PluginBase.OnLeave. This method will handle MasterClient change in case the current one is leaving.

Back To Top

Why Is ILeaveGameCallInfo.ActorNr == -1 In OnLeave?

This could happen when the client fails to enter the room (create or join). Basically ILeaveGameCallInfo.ActorNr == -1 means the client was not added to the room in the first place and was not given an actor number. OnLeave(ILeaveGameCallInfo.ActorNr == -1) is then a result of calling info.Continue() in OnCreateGame or BeforeJoin. When OnLeave is triggered, the server will not find an actor inside the room for the respective client, that's why the ActorNr value is default -1 (could be read as "actor not found"). The ILeaveGameCallInfo.Reason, here, should always be 3: LeaveReason.ServerDisconnect.

Here is a sample plugin that can detect and log ILeaveGameCallInfo.ActorNr == -1:

using System.Collections.Generic;
using System.Linq;

namespace Photon.Plugins.Samples
{
    public class JoinFailureDetection : PluginBase
    {
        private static readonly Dictionary<string, ICallInfo> pendingJoin = new Dictionary<string, ICallInfo>();

        public override void OnCreateGame(ICreateGameCallInfo info)
        {
            this.PluginHost.LogInfo(string.Format("OnCreateGame UserId={0} GameId={1}", info.UserId, info.Request.GameId));
            this.AddPendingJoin(info.UserId, info);
            info.Continue(); // in case of join failure this will call OnLeave inside w/ ActorNr == -1
            this.CheckJoinSuccess(info.UserId, info);
        }

        public override void BeforeJoin(IBeforeJoinGameCallInfo info)
        {
            this.PluginHost.LogInfo(string.Format("BeforeJoin UserId={0} GameId={1}", info.UserId, info.Request.GameId));
            this.AddPendingJoin(info.UserId, info);
            info.Continue(); // in case of join failure this will call OnLeave inside w/ ActorNr == -1
            this.CheckJoinSuccess(info.UserId, info);
        }

        public override void OnLeave(ILeaveGameCallInfo info)
        {
            this.PluginHost.LogInfo(string.Format("OnLeave UserId={0} GameId={1}", info.UserId, this.PluginHost.GameId));
            this.CheckJoinFailure(info);
            info.Continue();
        }

        private void AddPendingJoin(string userId, ICallInfo info)
        {
            if (string.IsNullOrEmpty(userId))
            {
                this.PluginHost.LogError("UserId is null or empty");
            }
            else
            {
                this.PluginHost.LogInfo(string.Format("User with ID={0} is trying to enter room {1}, ({2})", userId, this.PluginHost.GameId, info.GetType()));
                pendingJoin[userId] = info;
            }
        }

        private void CheckJoinFailure(ILeaveGameCallInfo info)
        {
            if (info.ActorNr == -1)
            {
                this.PluginHost.LogWarning(string.Format("ILeaveGameCallInfo.ActorNr == -1, UserId = {0} Reason = {1} ({2}) GameId = {3} Details = {4}", info.UserId, info.Reason, LeaveReason.ToString(info.Reason), this.PluginHost.GameId, info.Details));
            }
            if (string.IsNullOrEmpty(info.UserId))
            {
                this.PluginHost.LogError("ILeaveGameCallInfo.UserId is null or empty");
                return;
            }
            if (pendingJoin.ContainsKey(info.UserId))
            {
                this.PluginHost.LogError(string.Format("User with ID={0} failed to enter room {1}, removing pending request {2}", info.UserId, this.PluginHost.GameId, pendingJoin[info.UserId]));
                pendingJoin.Remove(info.UserId);
            }
            else
            {
                this.PluginHost.LogError(string.Format("no previous pending join for UserID = {0} GameId = {1}", info.UserId, this.PluginHost.GameId));
            }
        }

        private void CheckJoinSuccess(string userId, ICallInfo info)
        {
            if (info.IsSucceeded)
            {
                if (string.IsNullOrEmpty(userId))
                {
                    this.PluginHost.LogError("userId is null or empty");
                    return;
                }
                if (this.PluginHost.GameActorsActive.Any(u => userId.Equals(u.UserId)))
                {
                    if (pendingJoin.ContainsKey(userId))
                    {
                        this.PluginHost.LogInfo(string.Format("User with ID={0} succeeded to enter room {1}, removing pending request {2}", userId, this.PluginHost.GameId, pendingJoin[userId]));
                        pendingJoin.Remove(userId);
                    }
                    else
                    {
                        this.PluginHost.LogDebug(string.Format("no previous pending join for UserID = {0} GameId = {1}", userId, this.PluginHost.GameId));
                    }
                }
            }
        }

        public override void OnCloseGame(ICloseGameCallInfo info)
        {
            info.Continue();
            foreach (var pair in pendingJoin)
            {
                this.PluginHost.LogError(string.Format("Room {0} is being removed, unexpected leftover pending join UserID = {1} ICallInfo = {2}", this.PluginHost.GameId, pair.Key, pair.Value));
            }
        }
    }
}

Some example join failures (you can take a look at client error codes for Create or Join room operations):

  • A user tries to rejoin a room while there is no inactive actor with the same UserID there. The client will get error code JoinFailedWithRejoinerNotFound = 32748.
  • A user tries to join a room while there is an active actor with the same UserID there. The client will get error code JoinFailedFoundActiveJoiner = 32746.
  • A user tries to join a room while there is an inactive actor with the same UserID there. The client will get error code JoinFailedFoundInactiveJoiner = 32749.

In case the ILeaveGameCallInfo.ActorNr == -1 is not a result of a join failure then it's an anomaly, so either there is an exception in custom user plugin code or in the internal server code. In any case, from the plugin side, you can catch this early and log the stack trace. Also ILeaveGameCallInfo.ActorNr should change before and after ILeaveGameCallInfo.Continue, you can still detect this and report it. You can catch exceptions in the code by implementing ReportError method or overriding it if extending from PluginBase.

Back To Top

Events

What Does The HttpForward Property And WebFlags Class Do?

These are WebHooks related features. WebFlags are introduced in WebHooks v1.2 plugin. Go to this page to read more about WebFlags. HttpForward is a property that indicates the value of the corresponding webflag.

Although they are initially made for WebHooks and WebRPC, you may want to use them in your plugin.

Back To Top

How To Send Events From Plugins?

PluginHost.BroadcastEvent should be used for this purpose. It works in the same way as if you're sending event from client with the main difference, that you can set the sender actor number to 0 to represent the server.

For more information, read the "Sending Events from Plugins" section in the Plugins Manual.

Back To Top

Why Does PluginHost.BroadcastEvent Never Succeed In Sending Events To Client When Called Inside OnJoin Callback Unlike When Done From OnRaiseEvent?

In OnRaiseEvent the client is already joined so it's able to receive events. In OnJoin, the client is not fully joined unless the request is processed using {ICallInfo}.Continue().

So if PluginHost.BroadcastEvent is called after {ICallInfo}.Continue(), the event should be received by the target clients.

The plugin hooks work in this way: you trigger Photon's normal processing with the call to {ICallInfo}.Continue(). In this case sending an event after the join is fully completed makes more sense.

Back To Top

Why Clients Can't Receive Event Data Sent From Plugins?

This is a known issue. Clients expect events to have a certain predefined structure with well known key codes. 245 for event data and 254 for actor number. To fix this, simply do a minor change in the way you send events data from plugins: instead of (Dictionary<byte,object>)eventData send new Dictionary<byte,object>(){{245,eventData},{254,senderActorNr}}.

Back To Top

Does Plugins Support Custom Operations?

No, plugins do not support custom operations. Photon plugins offer callbacks only for a set of operations (Create, Join, SetProperties, RaiseEvent and Leave). You can't intercept custom operations added in a self-hosted Photon Server or extend new ones using Plugins SDK.

However, you can achieve the same results by exchanging 2-ways events:

  • From client to plugins by calling LoadBalancingClient.OpRaiseEvent.
  • From plugins to client by calling PluginHost.BroadcastEvent.

Back To Top

Game State

What Distinguishes An "active" User And An "inactive" User?

Once a player disconnects photon usually cleans up and the actor is removed, but you can define a PlayerTTL in CreateOptions on the client when creating the room. If it is strictly positive, Photon waits for that amount of time (which is defined in milliseconds) before cleaning up. Meanwhile, the actor is considered inactive and can rejoin the game. If that is successfully done, the player is active again.

The feature is useful if you want to save the game state and allow players to continue or for instance RTS games where players can get disconnected due to bad connectivity but it's OK for a short time (minutes) to allow them to return.

PluginHost.GameActorsActive contains all actors inside a room (joined) and PluginHost.GameActorsInActive contains all actors who left the room (without abandoning).

Back To Top

Is It Possible To Make An Actor Leave A Room From A Plugin? If So How?

Yes that is possible. From the plugin class, you should call PluginHost.RemoveActor(int actorNr, string reasonDetails). You can set the reason by calling the method overload that accepts three parameters: PluginHost.RemoveActor(int actorNr, byte reason, string reasonDetails).

Back To Top

How To Persist The Room State?

To save a room state:

  1. call PluginHost.GetGameState and get a SerializableGamestate.
  2. serialize the state (JSON for instance).
  3. save the state to your data store.

To load a room state:

  1. retrieve the state from your data store.
  2. desrialize your state.
  3. call PluginHost.SetGameState.

Note: you are only allowed to call PluginHost.SetGameState in OnCreateGame before calling {ICallInfo}.Continue().

Back To Top

I Can't Find Some Custom Room Properties Inside The SerializableGameState? Only Lobby Properties Why Is That?

In the serializable game state, we don't provide access to all custom properties by design. Only those you share with the Lobby are exposed and it is only for "viewing" purposes. All properties combined are contained in binary arrays. This allows to serialize to JSON and not lose the type information when deserializing back. This feature was designed mainly for the Save/Load scenario. We may change this behaviour in the future.

Back To Top

How To Access Room Properties (MaxPlayers, IsVisible, IsOpen, Etc.) From Plugins?

All room properties can be accessed from PluginHost.GameProperties which is of type Hashtable. Those properties include the "native" or "well-known" ones. They have byte keys:

  • MaxPlayers: 255
  • IsVisible: 254
  • IsOpen: 253
  • PropsListedInLobby: 250
  • CleanupCacheOnLeave: 249
  • MasterClientId: 248
  • ExpectedUsers: 247
  • PlayerTtl: 246
  • EmptyRoomTtl: 245

Just make sure that you do cast keys to byte from int (e.g. MaxPlayers = (byte)255).

PluginHost.GameProperties also contains custom room properties. Those should have string keys and are handled by you.

On the other hand, only the custom properties visible to the lobby are stored in PluginHost.CustomGameProperties which is a Dictionary<string, object>. This property should be treated as readonly.

You can access (read and write) room and actor properties from plugins as follows:

Some helper methods to get properties:

private bool TryGetRoomProperty<T>(byte key, out T property)
{
    property = default;
    if (this.PluginHost.GameProperties.ContainsKey(key))
    {
        property = (T)this.PluginHost.GameProperties[key];
    }
    return false;
}

private bool TryGetCustomRoomProperty<T>(string key, out T property)
{
    property = default;
    if (this.PluginHost.GameProperties.ContainsKey(key))
    {
        property = (T)this.PluginHost.GameProperties[key];
    }
    return false;
}

private bool TryGetActorByNumber(int actorNr, out IActor actor)
{
    actor = this.PluginHost.GameActors.FirstOrDefault(a => a.ActorNr == actorNr);
    return actor == default;
}

private bool TryGetActorProperty<T>(int actorNr, byte key, out T property)
{
    property = default;
    if (this.TryGetActorByNumber(actorNr, out IActor actor) && actor.Properties.TryGetValue(key, out object temp))
    {
        property = (T)temp;
    }
    return false;
}

private bool TryGetCustomActorProperty<T>(int actorNr, string key, out T property)
{
    property = default;
    if (this.TryGetActorByNumber(actorNr, out IActor actor) && actor.Properties.TryGetValue(key, out object temp))
    {
        property = (T)temp;
    }
    return false;
}

Writing examples:

PluginHost.SetProperties(actorNr: 0, properties: new Hashtable { { "map", "america" } }, expected: null, broadcast: false); // actor=0 for Room properties
PluginHost.SetProperties(actorNr: 1, properties: new Hashtable { { "health", 100 } }, expected: null, broadcast: true);

Back To Top

Threading

More details about the threading requirements of the .NET Plugin component

How Many Threads Are Running On A Single Photon Server?

The use of threads is split:

  1. Native - 9 threads
  2. Managed - based on .Net ThreadPool which uses .NET default settings

This setup has been tested quite intensively and works very well for a great variety of load profiles.

The use of managed threads (as reported by the .NET Windows Performance counters) varies:

a) ~12 on a typical Photon cloud RealTime load
b) 35 (and more) as an example of a customer cloud running a plugin with inter-plugin communication (locking), causing some higher contention (as opposed to our code)

Note: If necessary, .Net ThreadPool settings can be adjusted. So far we've had good results with the defaults, although they may be different for each version.

Back To Top

Is The Photon Host Free Threaded? Can Any Thread Access Any Room At Any Time?

We have a message passing architecture: your plugin will be called only by one thread at a time. However, the thread may not be the same in each call since we use a thread pool.

Back To Top

Are There Any Thread Safety Concerns With Writing A Plugin?

In general it's safe to assume all calls into the plugin are serialized (virtually on one thread / not necessarily on the same physical thread).

Back To Top

Enterprise Cloud

Questions related to the runtime environment of the Enterprise Cloud.

How To Configure Plugins?

For Photon Enterprise Cloud:
You should add a new plugin by going to the Photon dashboard, then the management page of the application. Once there you should click on the "Create a new Plugin" button on bottom of the page. Now you can configure the plugin by adding key/value entries. AssemblyName, Version, Path and Type are required ones.

Back To Top

What Is The Pipeline Process In Making Photon Plugins?

The pipeline process of making Photon plugins is simple:

  1. Download the required SDKs and server binaries.
  2. Code and build a plugin assembly.
  3. Deploy and test it.
  4. Upload it.
  5. Configure it.

The environment setup for Photon plugins could be:

  • Development: local machine.
  • Test: in your local network.
  • Staging: separate AppId in our cloud.
  • Production: live AppId in our cloud.

Back To Top

Is The Plugin Upload Automated?

Yes, we provide PowerShell scripts for Enterprise customers to help them manage their private cloud. Check out the plugins upload online guide for full details.

Back To Top

How To Monitor Performance Of Plugins?

We track a bunch of counters that are available in our Dashboard.
Additionally, we can add custom counters for you or you could integrate an external tool for counters as well (e.g. New Relic) If you require those services, a consulting agreement needs to be arranged.

Back To Top

Is There A Way To Have Any Plugins' Logs?

Access to log files on our servers is not granted. So an external service should be used for logs or alerts. We recommend using Logentries or Papertrail. So we ask our Enterprise Customers to get in touch with us to configure their private cloud with the logging service of their choice. If you want to use Logentries provide the configured log token. If you want to use Papertrail provide your custom URL with the port.

Back To Top

How Do I Get The Logentries Token?

Create a Logentries account and follow these steps:

  1. Select "Logs"/"Add New Log".
  2. Select "Libraries"/".NET".
  3. Enter a name for your log set.
  4. Click "Create Log Token".
  5. Click "Finish & View Log".
  6. Select your new log set and choose the "Setting" tab. You can view the token now.
  7. Send us that token via email.

Back To Top

How Do I Get The Papertrail URL?

Create a Papertrail account and follow these steps:

  1. Add "System"
  2. On top of the next page, you will see something like "Your logs will go to logs6.papertrailapp.com:12345 and appear in Events."
  3. Send us that URL via email.

Back To Top

What Is The Recommended Way To Roll Out New Plugins Versions?

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.

Another possible, yet more advanced, technique:

You could build a plugin DLL that has the core server update loop while the actual game logic is from another DLL that will be loaded explicitly. The core plugin DLL should not be updated while the game logic should have more than one DLL per version. The core plugin DLL will load the appropriate game logic DLL based on the client version. It is like mapping server side code with client side code for a full compatibility. This allows for a version compatible updates of plugins: This way you do not need to force client updates, when a new plugin version is rolled out. You could put the game logic DLLs in separate folders per version or inside the same folder but with different names per version.

Back To Top

Can We Use Static Fields Inside A Plugin?

Same plugins assembly will be shared across rooms and applications. Static fields of same plugin class will be shared as well. If you cannot avoid using static fields, here is what you could do to avoid using same plugins assembly in two applications:

  1. Upload same plugin files under two different plugin names:

    a- Upload plugin archive with name X
    b- Upload plugin archive with name Y

  2. Same configuration for two apps except "Path":

    a- Configure app A to use plugin X: "Path": "{customerName}\X"
    b- Configure app B to use plugin Y: "Path": "{customerName}\Y"

Back To Top

Miscellaneous

How To Retrieve reason Given When The Plugin Executes RemoveActor?

Currently, we don't send the reason (code byte or message string) to the client. You can use a custom event to inform the client before disconnecting it. For instance, you could send a custom event with the reason and schedule the RemoveActor 200ms later using a timer.

You could make use of these helper methods:

private const int RemoveActorEventCode = 199;
private const int RemoveActorTimerDelay = 200;

private void RemoveActor(ICallInfo callInfo, int actorNr, string reason)
{
    this.PluginHost.BroadcastEvent(new List<int> { actorNr }, 0, RemoveActorEventCode, 
        new Dictionary<byte, object> { { 254, 0 }, { 245, reason }}, 0);
    this.PluginHost.CreateOneTimeTimer(callInfo, () => this.PluginHost.RemoveActor(actorNr, reason),
        RemoveActorTimerDelay);
}

private void RemoveActor(ICallInfo callInfo, int actorNr, byte reasonCode, string reason)
{
    this.PluginHost.BroadcastEvent(new List<int> { actorNr }, 0, RemoveActorEventCode, 
        new Dictionary<byte, object> { { 254, 0 }, { 245, new { reasonCode, reason } }}, 0);
    this.PluginHost.CreateOneTimeTimer(callInfo, () => this.PluginHost.RemoveActor(actorNr, reason),
        RemoveActorTimerDelay);
}

private void RemoveActor(int actorNr, string reason)
{
    this.PluginHost.BroadcastEvent(new List<int> { actorNr }, 0, RemoveActorEventCode, 
        new Dictionary<byte, object> { { 254, 0 }, { 245, reason }}, 0);
    var fiber = this.PluginHost.GetRoomFiber();
    fiber.CreateOneTimeTimer(() => this.PluginHost.RemoveActor(actorNr, reason), RemoveActorTimerDelay);
}

private void RemoveActor(int actorNr, byte reasonCode, string reason)
{
    this.PluginHost.BroadcastEvent(new List<int> { actorNr }, 0, RemoveActorEventCode, 
        new Dictionary<byte, object> { { 254, 0 }, { 245, new { reasonCode, reason } }}, 0);
    var fiber = this.PluginHost.GetRoomFiber();
    fiber.CreateOneTimeTimer(() => this.PluginHost.RemoveActor(actorNr, reasonCode, reason), RemoveActorTimerDelay);
}

Back To Top

Client SDKs Support Extending Serialization By Registering Custom Types. How Would I Deserialize Those Types On The Server?

You can register custom types just like in client SDKs, as follows:

PluginHost.TryRegisterType(type: typeof (CustomPluginType), typeCode: 1, serializeFunction: SerializeFunction, deserializeFunction: DeserializeFunction);

For more information please read the "Custom Type" section in the Plugins Manual.

Back To Top

Is There A Limit On The File Size Of The Plugins .DLL?

No, but we think it should not be that big.

Back To Top

How To Get PUN's PhotonNetwork.ServerTimestamp In A Photon Plugin?

Use Environment.TickCount.

To Document Top