Step by Step Guide

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.

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. Download a valid license and save it into the "{pluginsSdkFolder}\deploy\bin_Win64" folder.
5. 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.6.1" (or higher)

6. 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\net461\PhotonHivePlugin.dll"
   • Confirm with "OK"

7. 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.

   C#

   using Photon.Hive.Plugin;
   
       namespace MyFirstPlugin
       {
           public class MyFirstPlugin : PluginBase
           {
           }
       }
   

8. Set plugin name:

   C#

   public override string Name => "MyFirstPlugin";
   

   • The reserved plugin names are "Default" and "ErrorPlugin".

9. Override SetupInstance to create a logger:

   C#

   private IPluginLogger pluginLogger;
   
   public override bool SetupInstance(IPluginHost host, Dictionary<string, string> config, out string errorMsg)
   {
       this.pluginLogger = host.CreateLogger(this.Name);
       return base.SetupInstance(host, config, out errorMsg);
   }
   

10. Add a log message in a callback:

    C#

    public override void OnCreateGame(ICreateGameCallInfo info)
    {
        this.pluginLogger.InfoFormat("OnCreateGame {0} by user {1}", info.Request.GameId, info.UserId);
    }
    

11. Call one callback processing method:

    C#

    public override void OnCreateGame(ICreateGameCallInfo info)
    {
        this.pluginLogger.InfoFormat("OnCreateGame {0} by user {1}", info.Request.GameId, info.UserId);
        info.Continue(); // same as base.OnCreateGame(info);
    }
    

12. Add plugin factory class:

    • Add a new class named MyPluginFactory
    • Make it public

    C#

    using Photon.Hive.Plugin;
    
    namespace MyFirstPlugin
    {
        public class MyPluginFactory
        {
        }
    }
    

13. Extend class PluginFactoryBase:

    C#

    using Photon.Hive.Plugin;
    
    namespace MyFirstPlugin
    {
        public class MyPluginFactory : PluginFactoryBase
        {
            public override IGamePlugin Create(string pluginName)
            {
                throw new NotImplementedException();
            }
        }
    }
    

14. Create and return plugin:

    C#

    public override IGamePlugin Create(string pluginName)
    {
        return new MyFirstPlugin();
    }
    

15. Build solution (F6).

16. Update plugins configuration:

    • Open "{pluginsSdkFolder}\deploy\LoadBalancing\GameServer\bin\plugin.config"
    • Update "PluginSettings" node as follows:

    XML

    <Configuration>
      <PluginSettings Enabled="true">
        <Plugins>
          <Plugin
            Name="MyFirstPlugin"
            AssemblyName="MyFirstPlugin.dll"
            Type="MyFirstPlugin.MyPluginFactory" />
        </Plugins>
      </PluginSettings>
    </Configuration>
    

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

17. Copy binaries to expected path:

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

18. Open [PhotonControl].
    It can be found at "{pluginsSdkFolder}\bin_Win64\PhotonControl.exe".

19. Start Photon Server as an application:

20. Check the logs:

    You can directly open the logs from PhotonControl:

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

22. Create a room. Call the appropriate method for your SDK which implements the CreateRoom operation.

23. 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:

    Plain Old Text

    2021-05-24 16:03:19,734 [20] INFO  Photon.Hive.Plugin.PluginManager - Plugin successfully created:Type:MyFirstPlugin.MyPluginFactory, path:D:\ExitGames\SDKs\Plugins\photon-server-plugin-sdk_v5-0-12-24499-rc1\deploy\Plugins/MyFirstPlugin//bin/MyFirstPlugin.dll
    2021-05-24 16:03:19,760 [20] INFO  Plugin.MyFirstPlugin - OnCreateGame 81f04234-892d-4b14-ae17-3708e9f7fe5c by user 848140c0-a7fb-4d61-ba5f-5846184a9b78
    2021-05-24 16:03:19,761 [20] DEBUG Photon.Hive.Plugin.CreateGameCallInfo - Continue.
    

Debug Mode

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

1. Close the Visual Studio project and open it again but this time by double clicking on "{pluginsSdkFolder}\src-server\Plugins\MyFirstPlugin\MyFirstPlugin.sln" solution file.
   This step is important to be able to use paths relative to the solution folder path in step 3.

2. 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.

   Plain Old Text

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

3. 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":

     Plain Old Text

     ..\..\..\deploy\bin_Win64\PhotonSocketServer.exe
     

   • "Command line arguments":

     Plain Old Text

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

4. Add a breakpoint:

5. Stop Photon Server from [PhotonControl]:

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

7. Connect to Photon Server. Use any client SDK.
8. Create a room. Call the appropriate method for your SDK which implements the CreateRoom operation.
9. Wait for the breakpoint to be triggered:

PhotonControl