server | v4 switch to v3  

Step by Step Guide

This guide was written and tested with Photon Plugins SDK version v4.0.29.11263.

Contents

Guide Intro

This guide's purpose is to show you how to create, configure and use your first Photon Server plugin.

This guide is intended for users who are discovering Photon Server plugins for the first time. This guide should be followed carefully step by step and in order.

This guide does not replace the manual.

Back To Top

Your First Plugin

In this first part we will create and deploy a minimal plugin.

  1. Create a Photon account.
  2. Download Photon Plugins SDK.
  3. Extract the SDK. The resulting folder path will be referred to as "{pluginsSdkFolder}" throught this guide.
  4. Create a new Visual Studio project (Visual Studio 2019 Community edition was used in this guide):

    • Add a new project of type "Class Library (.NET Framework)"
    • Project name: "MyFirstPlugin"
    • Location: "{pluginsSdkFolder}\src-server\Plugins"
    • Check: "Place solution and project in the same directory"
    • Framework: ".NET Framework 4"

    New Project Creation Window in Visual Studio 2019
    New Project Creation Window in Visual Studio 2019

  5. Add dependencies: Only one library is needed: "PhotonHivePlugin.dll". To add it from Visual Studio:

    • Right click on "References" from the project
    • Click "Add Reference.."
    • Choose "Browse"
    • Click "Browse" and choose "{pluginsSdkFolder}\src-server\Plugins\lib\PhotonHivePlugin.dll"
    • Confirm with "OK"
  6. Add plugin class:

    • Rename the class file automatically created by VS from "Class.cs" to "MyFirstPlugin.cs".
    • VS will suggest to rename the class also, accept. Otherwise rename the class yourself from Class to MyFirstPlugin.
    • Extend PluginBase.
        using Photon.Hive.Plugin;
    
    
        namespace MyFirstPlugin
        {
            public class MyFirstPlugin : PluginBase
            {
            }
        }
  7. Set plugin name:

        public override string Name
    {
        get { return "MyFirstPlugin"; }
    }
    • The reserved plugin names are "Default" and "ErrorPlugin".
  8. Add a log message in a callback:

        public override void OnCreateGame(ICreateGameCallInfo info)
    {
        this.PluginHost.LogInfo(string.Format("OnCreateGame {0} by user {1}", info.Request.GameId, info.UserId));
    }
  9. Call one callback processing method:

        public override void OnCreateGame(ICreateGameCallInfo info)
    {
        this.PluginHost.LogInfo(string.Format("OnCreateGame {0} by user {1}", info.Request.GameId, info.UserId));
        info.Continue(); // same as base.OnCreateGame(info);
    }
  10. Add plugin factory class:

    • Add a new class named MyPluginFactory
    • Make it public
        using System.Collections.Generic;
    using Photon.Hive.Plugin;
    
    
    namespace MyFirstPlugin
    {
        public class MyPluginFactory
        {
        }
    }
  11. Implement interface IPluginFactory:

        using System.Collections.Generic;
    using Photon.Hive.Plugin;
    
    
    namespace MyFirstPlugin
    {
        public class MyPluginFactory : IPluginFactory
        {
            public IGamePlugin Create(IPluginHost gameHost, string pluginName, Dictionary<string, string> config,
                out string errorMsg)
            {
                throw new NotImplementedException();
            }
        }
    }
  12. Create and return plugin:

        public IGamePlugin Create(IPluginHost gameHost, string pluginName, Dictionary<string, string> config,
        out string errorMsg)
    {
        MyFirstPlugin plugin = new MyFirstPlugin();
        if (plugin.SetupInstance(gameHost, config, out errorMsg))
        {
            return plugin;
        }
        return null;
    }
  13. Build solution (F6).

  14. Update plugins configuration:

    • Open "{pluginsSdkFolder}\deploy\LoadBalancing\GameServer\bin\Photon.LoadBalancing.dll.config"
    • Update "PluginSettings" node as follows:
        <PluginSettings Enabled="true">
        <Plugins>
            <Plugin
                Name="MyFirstPlugin"
                AssemblyName="MyFirstPlugin.dll"
                Type="MyFirstPlugin.MyPluginFactory" />
        </Plugins>
    </PluginSettings>

    Read more about plugins configuration on self-hosted Photon Server.

  15. Copy binaries to expected path:

    Copy everything from "{pluginsSdkFolder}\src-server\Plugins\MyFirstPlugin\bin\Debug\" to "{pluginsSdkFolder}\deploy\Plugins\MyFirstPlugin\bin\".

  16. Open PhotonControl. It can be found at "{pluginsSdkFolder}\bin_Win64\PhotonControl.exe".

  17. Start Photon Server as an application:

    Start LoadBalancing from PhotonControl
    Start LoadBalancing from PhotonControl

  18. Check the logs:

    You can directly open the logs from PhotonControl:

    Open Logs from PhotonControl
    Open Logs from PhotonControl

    In the "{pluginsSdkFolder}\deploy\log\GSGame.log" you should see the plugin configuration parsed and processed successfully:

        2019-07-04 15:18:40,272 [1] INFO  Photon.Hive.Plugin.PluginManager - Plugin configured: name=MyFirstPlugin
    2019-07-04 15:18:40,326 [1] INFO  Photon.Hive.Plugin.PluginManager - Loaded Assembly Name=MyFirstPlugin, Version=1.0.0.0, Culture=, PublicKey token=, Path=D:\ExitGames\SDKs\Plugins\Photon-OnPremise-Server-Plugin-SDK_v4-0-29-11263\deploy\Plugins\MyFirstPlugin\\bin\MyFirstPlugin.dll
    2019-07-04 15:18:40,327 [1] INFO  Photon.Hive.Plugin.PluginManager - Referenced Assembly Name=mscorlib, Version=4.0.0.0, Culture=, PublicKey token=B7-7A-5C-56-19-34-E0-89, Path=
    2019-07-04 15:18:40,329 [1] INFO  Photon.Hive.Plugin.PluginManager - Referenced Assembly Name=PhotonHivePlugin, Version=1.0.15.11060, Culture=, PublicKey token=, Path=
    2019-07-04 15:18:40,330 [1] INFO  Photon.Hive.Plugin.PluginManager - Plugin Type MyFirstPlugin.MyPluginFactory from assembly MyFirstPlugin, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null was successfuly created
    2019-07-04 15:18:40,331 [1] INFO  Photon.Hive.Plugin.PluginManager - Plugin manager (version=1.0.15.11060) is setup. type=MyFirstPlugin.MyPluginFactory;path=D:\ExitGames\SDKs\Plugins\Photon-OnPremise-Server-Plugin-SDK_v4-0-29-11263\deploy\Plugins\MyFirstPlugin\\bin\MyFirstPlugin.dll;version=1.0.15.11060
  19. Connect to Photon Server. Use any client SDK.

  20. Create a room. Call the appropriate method for your SDK which implements the CreateRoom operation.
  21. Recheck the logs: In the "{pluginsSdkFolder}\deploy\log\GSGame.log" you should see the plugin creation followed by your custom log message from the plugin callback:

        2019-07-04 15:25:40,540 [11] INFO  Photon.Hive.Plugin.PluginManager - Plugin successfully created:Type:MyFirstPlugin.MyPluginFactory, path:D:\ExitGames\SDKs\Plugins\Photon-OnPremise-Server-Plugin-SDK_v4-0-29-11263\deploy\Plugins\MyFirstPlugin\\bin\MyFirstPlugin.dll
    2019-07-04 15:25:42,435 [11] INFO  Photon.Hive.HiveGame.HiveHostGame.Plugin - OnCreateGame 870c3120-bcdd-4091-b072-8e92ea07bec5 by user 495fca21-b67e-4103-b1ce-c6ce945e6207

Back To Top

Debug Mode

In this second part we will show you our recommended workflow for plugins development.

  1. Update the plugin project's "Post-Build Events":

    The idea here is to automatically update plugins binaries by coping and pasting from project build output directory to expected path by the Photon configuration.

    Enter this command which does exactly this just after a successful build in the "Post-Build Events" text area as shown in the screenshot. We use relative paths for convenience and portability.

        xcopy /Y /Q "$(TargetDir)*.*" "$(SolutionDir)..\..\..\deploy\Plugins\MyFirstPlugin\bin\"

    Post Build Events
    Post Build Events

    Do not forget to save.

  2. Update the plugin project's "Debug" actions:

    The idea here is to automatically start Photon Server when debugging plugin starts and stopping when it stops.

    Configure the "Start action" and "Start options" as shown in the screenshot. We use relative paths for convenience and portability.

    • "Start external program":

              ..\..\..\deploy\bin_Win64\PhotonSocketServer.exe
    • "Command line arguments":

              /run LoadBalancing /configPath ..\..\..\..\..\deploy\bin_Win64

    Debug Start Action
    Debug Start Action

    Do not forget to save.

  3. Add a breakpoint:

    Breakpoint in MyFirstPlugin.OnCreateGame
    Breakpoint in MyFirstPlugin.OnCreateGame

  4. Stop Photon Server from PhotonControl:

    Stop LoadBalancing from PhotonControl
    Stop LoadBalancing from PhotonControl

  5. Start Photon Server from Visual Studio (F5):

    Photon Server debug started from Visual Studio
    Photon Server debug started from Visual Studio

    You can check the server is started using TaskManager. The process is named Photon.

  6. Connect to Photon Server. Use any client SDK.

  7. Create a room. Call the appropriate method for your SDK which implements the CreateRoom operation.
  8. Wait for the breakpoint to be triggered:

    Breakpoint Triggered
    Breakpoint Triggered

To Document Top