Migrating To 3.1

Migrating The Plugin SDK From 3.0 To 3.1

The Quantum Plugin SDK 3.1 has to be used together with the Quantum SDK 3.1, a 3.0 plugin does not work with 3.1 clients. Upgrade the Unity project first, see the Quantum 3.1 Migration Guide.

Overview

• Custom plugin projects target net10.0 instead of netcoreapp3.1, install the .NET 10 SDK.
• The local Photon Server was upgraded to 6.0.19.36800.
• The deploy_win folder was removed from the Photon Server folder, all server files are located directly inside Photon.Server.
• The plugin publish folder was renamed from QuantumPlugin3.0 to QuantumPlugin3.1.
• Quantum.Deterministic.dll was merged into Quantum.Engine.dll.
• PhotonHivePlugin.dll and Photon.Plugins.Common.dll are no longer shipped in the Lib folder, they are referenced from Photon.Server/LoadBalancing/Master/bin.
• The Quantum library references were moved into Quantum.Plugin.Shared.csproj.include.
• The session context and the session runner are created by a new server session factory (DeterministicPluginFactory.CreateSessionFactory()) instead of being passed to the DeterministicServer constructor.
• The LUT files (assets/LUT) are not required anymore, FPMath no longer uses lookup tables. The PathToLUTFolder plugin setting is ignored.

Folder Layout

Migration Steps

• Stop all running PhotonServer processes.
• Back up the plugin SDK folder, at least the custom plugin projects, the license file and plugin.config.
• Download the Quantum Plugin SDK 3.1 zip.
• Delete the Photon.Server and Lib folders of the 3.0 plugin SDK. This also removes the old plugin output including its LUT files (bin/assets/LUT), which are not required anymore.
• Unzip the 3.1 zip into the plugin SDK folder, keep your custom plugin projects (or copy them over from the backup).
  Unzipping overwrites the sample projects (Quantum.Plugin.Custom.* folders) and Quantum.Plugin.Custom.sln. If you modified a sample project in place, restore it from the backup afterwards and migrate it as described below.
• Restore the license file into Photon.Server/bin.
• The Upgrade-Server.ps1 script cannot be used for this migration, it only upgrades the Photon Server of an installed Quantum Plugin SDK 3.1, see Upgrading The Photon Server.
• The plugin.config in the plugin SDK root folder is the local plugin configuration. It is copied to Photon.Server/LoadBalancing/GameServer/bin when building any of the plugin projects, so edit the root file instead of the copy. Apply local changes of the old deploy_win/LoadBalancing/GameServer/bin/plugin.config to it and make sure the plugin is named Name="QuantumPlugin3.1".
• Migrate the custom plugin projects, see below.
• In Unity run Tools > Quantum > Export > Plugin SDK - Sync Server Simulation (or Sync on the QuantumDotnetBuildSettings asset) to rebuild Lib/Quantum.Simulation.dll against the 3.1 engine and to export the Quantum DB to Photon.Server/Plugins/QuantumPlugin3.1/bin/assets.
• Build the plugin project and start the Photon Server.

Migrating Custom Plugin Projects

Project Files

• Change the target framework from <TargetFramework>netcoreapp3.1</TargetFramework> to <TargetFrameworks>net10.0</TargetFrameworks>.
• Change <PluginPublishFolder>QuantumPlugin3.0</PluginPublishFolder> to QuantumPlugin3.1.
• Remove the references to Quantum.Deterministic, Quantum.Engine, Quantum.Log, Quantum.Deterministic.Plugin, Quantum.Deterministic.Server, Quantum.Deterministic.Server.Interface, PhotonHivePlugin and Photon.Plugins.Common, they are now added by Quantum.Plugin.Shared.csproj.include. Only project specific references like Quantum.Json and Quantum.Simulation remain in the project.
• In Properties/launchSettings.json remove deploy_win from the executable path and the working directory:

  JSON

  "executablePath": "$(ProjectDir)/../Photon.Server/bin/PhotonServer.exe",
  "workingDirectory": "$(ProjectDir)/../Photon.Server/bin"
  

Plugin Factory

The CreateDeterministicPlugin() overload with the IPluginLogger parameter is obsolete and no longer virtual, override the overload without logger. Log through Quantum.Log instead of the Photon IPluginLogger.

C#

// 3.0
public override DeterministicPlugin CreateDeterministicPlugin(IPluginHost gameHost, String pluginName, Dictionary<String, String> config, IPluginLogger logger, ref String errorMsg) {
  return new DeterministicPlugin(new DeterministicServer());
}

// 3.1
public override DeterministicPlugin CreateDeterministicPlugin(IPluginHost gameHost, String pluginName, Dictionary<String, String> config, ref String errorMsg) {
  return new DeterministicPlugin(new DeterministicServer());
}

Session Context And Server Simulation

The DeterministicServer constructors that take a session context or a session runner are obsolete (compile error). Plugins that use the session context (e.g. to access SessionContext.CommandSerializer) or run the server simulation override DeterministicPluginFactory.CreateSessionFactory() and return a ServerSessionFactory. The asset database is then loaded once per plugin factory instead of once per room.

DotNetSessionContext and DotNetSessionRunner were replaced by ServerSessionContext and ServerSessionRunner (located in Assets/Photon/Quantum/Simulation/Server of the Unity project and compiled into Quantum.Simulation.dll).

C#

// 3.0
public override DeterministicPlugin CreateDeterministicPlugin(IPluginHost gameHost, String pluginName, Dictionary<String, String> config, IPluginLogger logger, ref String errorMsg) {
  var sessionContext = new DotNetSessionContext { AssetSerializer = new QuantumJsonSerializer() };
  var sessionRunner = new DotNetSessionRunner { AssetSerializer = new QuantumJsonSerializer() };
  return new DeterministicPlugin(new DeterministicServer(sessionContext, sessionRunner));
}

// 3.1
public override IDeterministicSessionFactory CreateSessionFactory() =>
  new ServerSessionFactory(
    assetSerializer: new QuantumJsonSerializer(),
    runServerSimulation: true); // false to only create the session context

public override DeterministicPlugin CreateDeterministicPlugin(IPluginHost gameHost, String pluginName, Dictionary<String, String> config, ref String errorMsg) =>
  new DeterministicPlugin(new QuantumCustomServer());

Subscribe to simulation events and callbacks when the session starts. DeterministicServer.SessionRunner is null when the server simulation is disabled (dashboard, ServerSimulationPercent or a failed start).

C#

public class QuantumCustomServer : DeterministicServer {
  public override void OnDeterministicStartSession() {
    if (SessionRunner is ServerSessionRunner sessionRunner) {
      sessionRunner.CallbackDispatcher.Subscribe<CallbackGameStarted>(this, c => Log.Info("Game Started"));
      sessionRunner.EventDispatcher.Subscribe<EventFoo>(this, OnEventFoo);
    }
  }
}

DeterministicServer API

• DeterministicServer.Setup(IHost, IEventSender, IWebhookHost, Dictionary<string, string>) is no longer virtual, override Setup(IHost, IEventSender, IWebhookHost, Dictionary<string, string>, object sessionFactory) instead and pass sessionFactory to the base method.
• DeterministicServer.PluginLocation is now static.

Commands

Clients send their commands in a DeterministicCommandWrapper, which can hold multiple commands per frame (see the AddCommand() API change in the Quantum SDK 3.1).

• Overriding OnDeterministicCommand(DeterministicPluginClient client, Protocol.Command cmd) and decoding the data as a single DeterministicCommand no longer works. Decode a DeterministicCommandWrapper and iterate its Commands instead.
• Or override the new OnDeterministicCommand(DeterministicPluginClient client, DeterministicCommand command), which is called for each deserialized command and returns Accept, Discard or Modified.
• Use SendDeterministicCommand(DeterministicCommand command) to send commands from the server.

C#

public override OnDeterministicCommandResult OnDeterministicCommand(DeterministicPluginClient client, DeterministicCommand command) {
  if (command is MyCommand myCmd) {
    myCmd.Foo = 42;
    return OnDeterministicCommandResult.Modified;
  }
  return OnDeterministicCommandResult.Accept;
}

Other Changes

• Logs from the Quantum plugin are emitted through Quantum.Log and prefixed with Quantum: , the Photon IPluginLogger is deprecated.
• Fixed ServerSimulationPercent enabling the server simulation for the inverse percentage of rooms. Projects that configured a value below 100 run the server simulation for a different share of rooms after upgrading.
• New dashboard configuration values:
  • InputFlushMode (Default, Never, Last, Always) to configure the message flush behaviour of the input sent to clients. DeterministicPlugin can also change it at runtime.
  • ForceSnapshotsForAllJoiners to make all subsequent clients use snapshots even when arriving early.
  • SnapshotUploadTimeoutInSec, SnapshotDownloadTimeoutInSec and SnapshotCacheDurationInSec to configure buddy snapshot timings.
• DeterministicPlugin.UpdateRateMs overrides the server update rate per room.
• The game result webhook includes ActorNr and AuthCookie of the clients, and a game result response callback was added.
• The LeaveGameRequest webhook has the new property FailedOnCreate.

Last updated on 05/11/2026