This document is about: QUANTUM 3
SWITCH TO

Webhooks

Overview

Webhooks are primarily used to have a trusted source of game configurations and room compositions and can greatly contribute to the safety of an online application.

The default cloud plugin has support for different hooks defined via the AppID Dashboard. Once configured and enabled, the Photon Cloud will send WebRequests (HTTP POST) to a custom backend and will use the response data (Json) for various configurations on the Photon rooms and game sessions.

Setup

Webhooks are enabled per AppId on the Photon Dashboard.

  1. Navigate to the Photon Dashboard and log in.
  2. Find the AppId and click Manage.
  3. Scroll down to Plugins and click Edit.
  4. Click Add New Pair and add keys and values (the maximum length allowed for each setting value is 1024 chars).
  5. Press Save and wait up to one minute for changes to take effect.
Photon Dashboard Properties

Dashboard Configurations

Key Type Example Description
WebHookBaseUrl string https://localhost:3581 The base url of the custom backend. Webhook paths will be appended, for example: {WebHookBaseUrl}/game/create

Must always be set.
WebHookIntegration string Default The selected webhook integration (default is Default).

Default, PlayFab
WebHookSecret string ********** This will be send with each web request and can be used to authenticate the request.
WebHookCustomHttpHeaders Dictionary <string, string> {"A": "Foo", "B": "100" } A JSON dictionary. All entries will be added to the custom web request headers.
WebHookEnableOnCreate bool true If set to true, the CreateGame webhook will be fired when a client is creating a Game Session.
WebHookEnableOnClose bool false If set to true, the CloseGame webhook will be fired when the Game Session was closed.
WebHookEnableOnJoin bool true If set to true, the JoinGame webhook will be fired when any client tries to join a Game Session.
WebHookEnableOnLeave bool false If set to true, the LeaveGame webhook will be fired when any client leaves a Game Session

Quantum Dashboard Configurations

Key Type Example Description
WebHookEnableGameConfigs bool false If set to true, the GameConfigs webhook will be fired when a client uploaded the game configs RuntimeConfig and SessionConfig using the StartRequest operation.
WebHookEnableGameResult bool false If set to true, the GameResult webhook will be invoked.
WebHookEnableAddPlayer bool false If set to true, the client operation AddPlayer will invoke the AddPlayer web request.
WebHookEnablePlayerAdded bool false If set to true, the PlayerAdded web request is invoked after a player has been successfully added to the Quantum online game.
WebHookEnablePlayerRemoved bool false If set to true, the PlayerRemoved web request is invoked after a player was removed from the Quantum game.
WebHookEnableReplay bool false Setting this to true will enable the replay streaming based on the ReplayStart and ReplayChunk web requests.

Webhook API

Webhooks send Json content and only accept Json content as a response. UTF-8 charset for Json is mandatory.

Webhooks expect HTTP response codes 200 or 400:

  • 200: successful request.
  • 400: error or operation has been denied (e.g. a client cannot create a room/game session).

The Photon server retries webhooks after transportation errors three times as well as after receiving StatusCode 503 (Service Unavailable) with delay of 400ms, 1600ms and 6400ms. The timeout before the request fails and is not retried is 10 seconds.

Fill out the WebhookError definition to return information of the nature of an error back to the Photon plugin. It can be used for:

  • Logging;
  • Returning information to the client;
  • A custom plugin to add further custom error handling;

Common Request Headers

These common request headers are added to every web request.

Name Type Content Description
Accept string application/json Webhooks only accept JSON as a response body
Accept-Charset string utf-8 Webhooks only accept utf-8 as response body charset
Content-Type string application/json Webhooks all send JSON body data
X-SecretKey string ********** This key should only be know to the custom backend and should be used to authenticate the incoming web request. This is set on the Photon Dashboard as WebHookSecret.
X-Origin string Photon Will always be set to "Photon"

CreateGame

This webhook is called before the room/game session is created on the Photon Server. The creation is blocked until the webhook receives a response, which will affect the time clients require to create a connection.

A CreateGame webhook is always a JoinGame request for the user that initiates the room/game session creation. There will be no subsequent JoinGame webhook for this user. This webhook shares the data from the JoinGame webhook.

Requires WebHookBaseUrl and WebHookEnableCreateGame to be set on the Photon dashboard.

JavaScript

POST https://{WebHookBaseUrl}/game/create

CreateGame Request

Name Type Example Description
AppId string d1f67eec-51fb-45c1 The Photon AppId.
AppVersion string 1.0-live The AppVersion used when creating the room/game session.
Region string eu The Region code of the Game Server that the room/game session was created in.
Cloud string 1 The Cloud Id of that the Game Server is running on.
UserId string db757806-8570-45aa The UserId of the client that creates the room/game session.
RoomName string e472a861-a1e2-49f7 The room/game session Name.
GameId string 0:eu:e472a861-a1e2-49f7 A unique GameId which is composed of {Cloud:}{Region:}RoomName. Can be overwritten in the response.
EnterRoomParams EnterRoomParams JSON: See EnterRoomParam section The Photon room/game session Options sent by the client.

Json Example:

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "AppVersion": "1.0-live",
  "Region": "eu",
  "Cloud": "1",
  "UserId": "db757806-8570-45aa",
  "RoomName": "e472a861-a1e2-49f7",
  "GameId": "0:eu:e472a861-a1e2-49f7",
  "EnterRoomParams": {
    "RoomOptions": {
      "IsVisible": true,
      "IsOpen": true
    }
  }
}

HTTP Response Codes

Name Type Description
200 OK CreateGame Response room/game session creation can commence, config data from the response will overwrite data sent by the client.
400 Bad Request WebhookError room/game session creation is not allowed and will be canceled. The client will receive an error.

CreateGame Response

Name Type Description
GameId string Overwrites the GameId used in subsequent web requests. Can be null or omitted.
EnterRoomParams EnterRoomParams Enforce selected Room Options during its creation. The JSON object does not have to include all members, only the ones that should be overwritten.

Only the initial options are protected by sending EnterRoomParams. Most of them can be changed by clients sending Photon Room properties. To block this enable the Photon dashboard property BlockRoomProperties. Can be null or omitted.
Name Type Description
SessionConfig SessionConfig Return a SessionConfig object that is used by the game. Game configs sent by clients will be ignored.
RuntimeConfig RuntimeConfig Return a RuntimeConfig object that is used by the game. Game configs sent by clients will be ignored.
RuntimePlayer RuntimePlayer Return a RuntimePlayer object that will be used for the client that created this room/session.

This only overwrites the first AddPlayer data sent for player slot 0. MaxPlayerSlots should be set to 1.
MaxPlayerSlots int The maximum number of player slots this client can acquire:
0 = only spectating
1..255 = specific number
-1 = unlimited

If this response is sent but this value is not set MaxPlayerSlots will default to 1.

Players requesting an invalid player slot number or more slots than allowed will be disconnected.
SnapshotsBlocked bool This player will not be selected for sending game snapshots to other players if there are other clients available.
StartPropertyBlockedTimeSec int Minimum delay in seconds before starting Quantum inside a room after its creation, ensuring players have enough time to join. A value greater than zero activates this feature.
StartPropertyForcedTimeSec int Maximum delay in seconds before starting Quantum inside a room after its creation. Exceeding this time auto-activates "StartQuantum" if not already set. A value greater than zero activates this feature.
HideRoomAfterStartSec int Number of seconds after which the room will be hidden from public listings once Quantum starts within the room. A value greater than zero activates this feature.
CloseRoomAfterStartSec int Number of seconds after which the room will be closed following the start of Quantum inside the room, preventing new players from joining. A value greater than zero activates this feature.

Json Example:

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "GameId": "0:eu:db757806-8570-45aa",
  "EnterRoomParams": {
    "RoomOptions": {
      "IsVisible": true,
      "IsOpen": true
    }
  },
  "SessionConfig": {
    "PlayerCount": 8,
    "ChecksumCrossPlatformDeterminism": false,
    "UpdateFPS": 30
  },
  "RuntimeConfig": {
    "Map": {
      "Id": {
        "Value": 94358348534
      }
    }
  },
  "RuntimePlayer": {
    "Name": "player1"
  },
  "MaxPlayerSlots": 2,
  "SnapshotsBlocked": true
}

JoinGame

The JoinGame webhook is send before a client joins an existing room/game session. Return 200 to allow or 400 to cancel the joining.

Requires WebHookBaseUrl and WebHookEnableOnJoin to be set on the Photon AppId Dashboard.

JavaScript

POST https://{WebHookBaseUrl}/game/join

JoinGame Request

Name Type Example Description
AppId string d1f67eec-51fb-45c1 The Photon AppId
GameId string 0:eu:db757806-8570-45aa Unique GameId
UserId string db757806-8570-45aa Photon UserId

Json Example:

JSON

{
  "GameId": "0:eu:db757806-8570-45aa",
  "UserId": "db757806-8570-45aa"
}

HTTP Response Codes

Name Type Description
200 OK JoinGame Response The client will join the room.
400 Bad Request WebhookError Joining the room will fail.

JoinGame Response

Name Type Description
RuntimePlayer RuntimePlayer Return a RuntimePlayer object that will be used for the client that created this room/session.

This only overwrites the first AddPlayer data sent for player slot 0. MaxPlayerSlots should be set to 1.
MaxPlayerSlots int The maximum number of player slots this client can acquire:
0 = only spectating
1..255 = specific number
-1 = unlimited

If this response is send but this value is not set MaxPlayerSlots will default to 1.

Players requesting an invalid player slot number or more slots than allowed will be disconnected.

Json Example:

JSON

{
  "RuntimePlayer": {
    "Name": "player1"
  },
  "MaxPlayerSlots": 1
}

Hint

Rather use AddPlayer to return the RuntimePlayer data, because its request will includes a RuntimePlayer client object sent by the client.

Also consider using the CreateGame response to reserve player slots for users (if they are already known at that time).

LeaveGame

The LeaveGame webhook is send after the client leaves an existing room/game session.

Requires WebHookBaseUrl and WebHookEnableOnLeave to be set on the Photon AppId Dashboard.

JavaScript

POST https://{WebHookBaseUrl}/game/leave

LeaveGame Request

Name Type Example Description
AppId string d1f67eec-51fb-45c1 The Photon AppId
GameId string 0:eu:db757806-8570-45aa Unique GameId
UserId string db757806-8570-45aa Photon UserId

Json Example:

JSON

{
  "GameId": "0:eu:db757806-8570-45aa",
  "UserId": "db757806-8570-45aa"
}

HTTP Response Codes

Name Type Description
200 OK LeaveGame Response Just a confirmation of receipt.
400 Bad Request WebhookError Error is ignored, it will just be logged on the Photon Cloud.

LeaveGame Response

Json Example:

JSON

{
  // empty
}

CloseGame

The CloseGame webhook is sent when the room/game session is closed after all clients have left.

Requires WebHookBaseUrl and WebHookEnableOnClose to be set on the Photon dashboard.

JavaScript

POST https://{WebHookBaseUrl}/game/close

CloseGame Request

Name Type Example Description
AppId string d1f67eec-51fb-45c1 The Photon AppId
GameId string 0:eu:db757806-8570-45aa Unique game id
CloseReason int (CloseReason) 0 The reason why this room/session has been closed.

Json Example:

JSON

{
  "GameId": "0:eu:db757806-8570-45aa",
  "CloseReason": 0
}

HTTP Response Codes

Name Type Description
200 OK Confirmation of receipt.

CloseReason

Name Value Description
Ok 0 Session was closed without errors.
FailedOnCreate 1 Session was closed because it failed to Create.

GameConfigs

The GameConfigs webhook is sent when a player sent a StartRequest operation attached with the game configs RuntimeConfig and SessionConfig. Both config files are attached to the request body as Json objects.

This webhook is only send once per room upon the first arrival of any clients start operation.

Requires WebHookBaseUrl and WebHookEnableGameConfigs to be set on the Photon dashboard.

JavaScript

POST https://{WebHookBaseUrl}/game/configs

GameConfigs Request

Name Type Example Description
AppId string d1f67eec-51fb-45c1 The Photon AppId
GameId string 0:eu:db757806-8570-45aa Unique game id
UserId string db757806-8570-45aa Photon UserId
RuntimeConfig RuntimeConfig { "Level": 1 } The RuntimeConfig object sent by the client to the plugin. Can be null.
SessionConfig SessionConfig { "PlayerCount": 8, .. } The SessionConfig object sent by the client to the plugin. Can be null.

Json Example:

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "GameId": "0:eu:db757806-8570-45aa",
  "UserId": "db757806-8570-45aa",    
  "RuntimeConfig": {
    "Map": {
      "Id": {
        "Value": 94358348534
      }
    }
  },
  "SessionConfig": {
    "PlayerCount": 8,
    "ChecksumCrossPlatformDeterminism": false,
    "LockstepSimulation": false,
    //..  
  }
}

HTTP Response Codes

Name Type Description
200 OK GameConfigs Response The game start sequence can continue. Game configs attached to response should be overwritten.
400 Bad Request WebhookError The game will be terminated and all clients are disconnected.

GameConfigs Response

Both objects on the response can be null to accept the configs that the client sent. Otherwise they will be overwritten.

Name Type Description
RuntimeConfig RuntimeConfig The RuntimeConfig object to overwrite the one the client sent.
SessionConfig SessionConfig The SessionConfig object to overwrite the one the client sent.

Json Example:

JSON

{
  "RuntimeConfig": {
    "Map": {
      "Id": {
        "Value": 94358348534
      }
    }
  },
  "SessionConfig": {
    "PlayerCount": 8,
    "ChecksumCrossPlatformDeterminism": false,
    "LockstepSimulation": false,
    //..  
  }
}

AddPlayer

The AddPlayer webhook is sent when a client tries to add a player to the Quantum online game using the AddPlayer operation.

Adding a player to the online game can still fail after this webhook returns when no player slot is free then. Use the PlayerAdded webhook to track the player online status.

Requires WebHookBaseUrl and WebHookEnableAddPlayer to be set on the Photon dashboard.

JavaScript

POST https://{WebHookBaseUrl}/player/add

AddPlayer Request

Name Type Example Description
AppId string d1f67eec-51fb-45c1 The Photon AppId
GameId string 0:eu:db757806-8570-45aa Unique game id
UserId string db757806-8570-45aa Photon UserId or ClientId
PlayerSlot int 0 Player slot requested. Usually is 0.
RuntimePlayer RuntimePlayer { "Foo": 222 } The RuntimePlayer object sent by the client to the plugin. Can be null.

Json Example:

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "GameId": "0:eu:db757806-8570-45aa",
  "UserId": "db757806-8570-45aa", 
  "PlayerSlot": 0,
  "RuntimePlayer": {
    "Name": "player1"
  }
}

HTTP Response Codes

Name Type Description
200 OK AddPlayer Response The client can add a player to the selected player slot and optionally received a RuntimePlayer object from the backend.
400 Bad Request WebhookError The client cannot add the player and will receive an error protocol message and callback: OnLocalPlayerAddFailed.

AddPlayer Response

Name Type Description
RuntimePlayer object The RuntimePlayer object to overwrite the RuntimePlayer that the client sent. If null the clients RuntimePlayer will be accepted.

Json Example:

JSON

{
  "RuntimePlayer": {
    "Name": "player1"
  }
}

PlayerAdded

The PlayerAdded webhook is send after a client successfully added a player to the online game.

Requires WebHookBaseUrl and WebHookEnablePlayerAdded to be set on the Photon dashboard.

JavaScript

POST https://{WebHookBaseUrl}/player/added

PlayerAdded Request

Name Type Example Description
AppId string d1f67eec-51fb-45c1 The Photon AppId
GameId string 0:eu:db757806-8570-45aa Unique game id
UserId string db757806-8570-45aa Photon UserId or ClientId
PlayerSlot int 0 The (local) player slot that the client reserved.
Player int 21 The (global) Player id that the client received.

Json Example:

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "GameId": "0:eu:db757806-8570-45aa",
  "UserId": "db757806-8570-45aa",
  "PlayerSlot": 0,
  "Player": 21
}

HTTP Response Codes

Name Type Description
200 OK Confirmation of receipt.

PlayerRemoved

The PlayerRemoved webhook is sent when a client was removed from the online game.

Requires WebHookBaseUrl and WebHookEnablePlayerRemoved to be set on the Photon dashboard.

JavaScript

POST https://{WebHookBaseUrl}/player/removed

PlayerRemoved Request

Name Type Example Description
AppId string d1f67eec-51fb-45c1 The Photon AppId
GameId string 0:eu:db757806-8570-45aa Unique game id
UserId string db757806-8570-45aa Photon UserId or ClientId
PlayerSlot int 0 The (local) player slot.
Player int 21 The (global) Player id.
Reason int 0 The reason why the player was removed from the game.

0 = Requested
1 = ClientDisconnected
2 = Error

Json Example:

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "GameId": "0:eu:db757806-8570-45aa",
  "UserId": "db757806-8570-45aa",
  "PlayerSlot": 0,
  "Player": 21,
  "Reason": 0
}

HTTP Response Codes

Name Type Description
200 OK Confirmation of receipt.

GameResult

Using the GameResult Quantum event in the simulation will trigger the upload of a GameResult instance by clients to the Quantum server once per game.

The results are aggregated and forwarded as the GameResult webhook when the game/room is closed.

Requires WebHookBaseUrl and WebHookEnableGameResult to be set on the Photon dashboard.

If the server is running the simulation the webhooks are executed immediately from the server simulation and can be used as a reliable and trusted source of game results.

JavaScript

POST https://{WebHookBaseUrl}/game/result

GameResult Request

Name Type Example Description
AppId string d1f67eec-51fb-45c1 The Photon AppId
GameId string 0:eu:db757806-8570-45aa Unique game id
Results GameResultInfo[] see below The aggregated game results

Json Example:

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "GameId": "0:eu:db757806-8570-45aa",
  "Results": [
      {
          "Clients": [
              {
                  "UserId": "FJEH43FL56FSDR",
                  "Players": [
                      0
                  ],
                  "GameTime": 63.3636703
              }
          ],
          "Result": {
              "$type": "Quantum.GameResult, Quantum.Simulation",
              "Frame": 12010
              "Winner": 2
          },
          "IsServerResult": false
      }
  ],
  "UserId": "0"
}

HTTP Response Codes

Name Description
200 OK Confirmation of receipt

GameResultInfo

Name Type Description
Result GameResult The game specific game result Json object that the listed clients sent
Clients GameResultClientInfo[] The list of clients that generated this result
IsServerResult bool Has this result been generated by server simulation

GameResultClientInfo

Name Type Description
UserId string The Photon user id
Players int[] The list of players that this user controls
GameTime float The timestamp when the result reached the server

ReplayStart

The ReplayStart webhook is sent when the simulation and the input recording is starting on the server. It's is a trusted source for capturing the game replay directly from the server instead of relying on clients to send it to a developers backend.

This webhook has to be answered with the ReplayStartResponse which can signal the replay streaming to be skipped for this particular game session.

A response has to be received by the Quantum server before it is sending its first replay slice or the replay recording will be canceled.

Requires WebHookBaseUrl and WebHookEnableReplay to be set on the Photon dashboard.

JavaScript

POST https://{WebHookBaseUrl}/replay/start

ReplayStart Request

Name Type Description
AppId string The Photon AppId.
AppVersion string The AppVersion used when creating the room/game session.
Region string The Region code of the Game Server that the room/game session was created in.
Cloud string The Cloud Id of that the Game Server is running on.
RoomName string The room/game session Name.
GameId string A unique GameId which is composed of {Cloud:}{Region:}RoomName.
SessionConfig SessionConfig The SessionConfig that the simulation started with.
RuntimeConfig byte[] The GZipped Json of the RuntimeConfig that the simulation started with.

Json Example:

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "AppVersion": "1.0-live",
  "Region": "eu",
  "Cloud": "0:",
  "UserId": "db757806-8570-45aa",
  "GameId": "0:eu:e472a861-a1e2-49f7",
  "SessionConfig": { },
  "RuntimeConfig": "H4sIAAAAAAAACnWNPQvCMBCG/4ocjkWuyeX6sXZycNCCe8AogSYtNBlK6X/3UHQR4Zb35X2eW2GflslBC+dsY8rhcMkx+eC6Md79o9h96t6HPNjkxwgF9M7doMUCTnaCdoWjpBWudshiUkxYsVHacE11KWe2TZiv4K3+4YjQkECKNJcVMuoXtszJhfkPI1tUVc1sqFGN1g3Kr+0J+3ktedUAAAA="
}

HTTP Response Codes

Name Type Description
200 OK ReplayStart Response The replay streaming can start or be disabled when the Skip property is set.
400 Bad Request WebhookError In this case an error is logged on the server and the replay streaming is stopped.

ReplayStart Response

Name Type Description
Skip bool The replay streaming is disabled for this game session.

Json Example:

JSON

{
  "Skip": true
}

ReplayChunk

The ReplayChunk webhook is sent in intervals and it contains the delta compressed input history of a part of the simulation.

Requires WebHookBaseUrl and WebHookEnableReplay to be set on the Photon dashboard.

JavaScript

POST https://{WebHookBaseUrl}/replay/chunk

There are additional dashboard variables that configure the replay input streaming.

Dashboard Variable Type Description Default
WebHookReplayUseBinaryRequests bool The web request are not send as JSON content but as binary data. false
WebHookReplayUseCompression bool The input data on the chunks is zip compressed. false
WebHookReplaySendIntervalInSec int The chunk send interval in seconds (min = 2, max = 40). 20

ReplayChunk Request

If WebHookReplayUseBinaryRequests is selected, then the following properties are part of the web request Headers instead of a JSON body. The body then will include the binary Input.

Name Type Description
AppId string d1f67eec-51fb-45c1 The Photon AppId
GameId string The game id to identify the replay chunk.
ChunkNumber int The incrementing chunk number.
IsLast bool A flag that indicates that the last chunk has been send. Usually when a room closes.
LastTick int The oldest tick of input on this chunk.
TickCount int The number of ticks of input on this chunk.
TickCountTotal int The total incrementing number of ticks in the whole replay.
IsCompressed bool A flag indicating the input is zip compressed.
Input byte[] The binary delta compressed input that needs to be appended to the complete input stream for this replay. The input for each tick has a leading int describing the data length. It can be stored in the ReplayFile.InputHistoryRaw field to be readable with the QuantumRunnerLocalReplay script in Unity.

Json Example:

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "GameId": ":eu:e472a861-a1e2-49f7",
  "ChunkNumber": 0,
  "IsLast": false,
  "LastTick": 302,
  "TickCount": 243,
  "TickCountTotal": 243,
  "IsCompressed": false,
  "Input": "JQAAADwAAAAIAAMKFsCUwYDggOB/UCAAAPgfDMhgEoAHA////4PRBwATAAAAPQAAAAgAA2PaSK"
}

HTTP Response Codes

Name Type Description
200 OK Confirmation of receipt.

WebhookError

Name Type Description
Status int HTTP status code
Error string Error name
Message string Error message

Json example:

JSON

{
  "Status": 400,
  "Error": "PlayerNotAllowed",
  "Message": "LoremIpsum"
}

Quantum Classes

RuntimeConfig

Quantum 3 runtime configuration files RuntimeConfig and RuntimePlayer are uploaded by the clients using Json serialization. This way it is possible to send configurations to the Quantum public cloud game servers while it does not know the implementation and serialization details.

When RuntimeConfig or RuntimePlayer are used in a webhook response they need to be complete because the configs send by clients are completely replaced.

Json data sent by the custom backend has to be deterministically deserializable on every client.

Quantum internal classes usually operate with fields, make sure that the Json serialization and deserialization code needs to IncludeFields = true and IgnoreReadOnlyProperties = true.

A simple example of the RuntimeConfig class. Additionally to the partial declaration the base class adds a couple properties as well (Seed, Map, SimulationConfig, SystemsConfig).

The $type property is required for deserialization on the standalone or custom plugin.

C#

namespace Quantum {
  public partial class RuntimeConfig {
    public int GameMode;
  }
}

Json Example:

JSON

{
  "$type": "Quantum.RuntimeConfig, Quantum.Simulation",
  "GameMode": 1,
  "Seed": 0,
  "Map": {
    "Id": {
      "Value":2640765235684814815
      }
  },
  "SimulationConfig": {
    "Id": { 
      "Value":440543562436170603
    }
  },
  "SystemsConfig": {
    "Id": { 
      "Value":2430278665492933905
    }
  }
}

RuntimePlayer

C#

namespace Quantum {
  public partial class RuntimePlayer {
    public AssetRef<GearConfig> Loadout;
  }
}

Json Example:

JSON

{
  "$type":"Quantum.RuntimePlayer, Quantum.Simulation",
  "Loadout": {
    "Id": {
      "Value": 440543562436170603
    }
  },
  "PlayerAvatar": {
    "Id": {
      "Value": 2430278665492933905
    }
  },
  "PlayerNickname": "foo"
}

SessionConfig

SessionConfig is the abbreviation of the DeterministicSessionConfig class.

When a SessionConfig is returned by an webhook it needs to be complete because single values are not replaced.

The current SessionConfig asset can be exported in Unity using this menu entry:

Unity Editor > Quantum > Export > SessionConfig (Json)

When serializing the class on netcoreapp3.1 either use Newtonsoft or use DeterministicSessionConfigJsonConverter for Text.Json. Because "including fields" is a feature of net5.

Json Example:

JSON

{
  "PlayerCount": 8,
  "ChecksumCrossPlatformDeterminism": false,
  "LockstepSimulation": false,
  "InputDeltaCompression": true,
  "UpdateFPS": 60,
  "ChecksumInterval": 60,
  "RollbackWindow": 60,
  "InputHardTolerance": 8,
  "InputRedundancy": 3,
  "InputRepeatMaxDistance": 10,
  "SessionStartTimeout": 1,
  "TimeCorrectionRate": 4,
  "MinTimeCorrectionFrames": 1,
  "MinOffsetCorrectionDiff": 1,
  "TimeScaleMin": 100,
  "TimeScalePingMin": 100,
  "TimeScalePingMax": 300,
  "InputDelayMin": 0,
  "InputDelayMax": 60,
  "InputDelayPingStart": 100,
  "InputFixedSizeEnabled": true,
  "InputFixedSize": 24
}

GameResult Event

The GameResult class can be extended by adding fields using the partial class declaration inside the GameResult.User.cs script. It will be Json serialized on the client and send to the Quantum server.

C#

namespace Quantum {
  public partial class GameResult {
    public int Winner;
  }
}

Json Example:

JSON

{
  "$type":"Quantum.GameResult, Quantum.Simulation",
  "Frame": 200,
  "Winner": 2
}

The game result event can be invoked once per game by each client, which is triggered from inside the simulation by calling the GameResult Quantum event. The actual webhook is launched when the room is disbanded and closed.

C#

f.Events.GameResult(new GameResult { WinnerId = 3 });

When running an enterprise Photon Quantum cloud with server simulation this will be transparently send by the server for a trusted source of game results.

Photon Realtime Classes

EnterRoomParams

This definitions is designed to be similar to the EnterRoomParams class in Photon Realtime. It includes all options that can be set by the CreateGame webhook. When composing the Json Response every member is optional and can be null or not set.

Name Type Description
RoomOptions RoomOptions RoomOptions object
ExpectedUsers string[] A list of UserIds that are permitted to enter the room/session (additionally to the user creating the room). If MaxPlayers is greater than the number ExpectedUsers listed, any player may join and fill the unreserved slots.

Works only for RoomJoin() not JoinRandom().

Json example:

JSON

{
  "RoomOptions": {
    "IsVisible": true,
    "IsOpen": true,
    "MaxPlayers": 8,
    "PlayerTtl": null,
    "EmptyRoomTtl": 10000,
    "CustomRoomProperties": {
      "Foo": "bar",
      "PlayerClass": 1
    },
    "CustomRoomPropertiesForLobby": [
      "Foo"
    ],
    "SuppressRoomEvents": null,
    "SuppressPlayerInfo": null,
    "PublishUserId": null,
    "DeleteNullProperties": null,
    "BroadcastPropsChangeToAll": null,
    "CleanupCacheOnLeave": null,
    "CheckUserOnJoin": null
  },
  "ExpectedUsers": [
    "A",
    "B",
    "C"
  ]
}

RoomOptions

All values are nullable types and can be set to null or be omitted when sending back to the Quantum server, in which case this response will not alter the nulled or omitted room property and will remain the default or the value send by the client when creating the room.

Name Type Description
IsVisible bool Defines if this room is listed in the Photon matchmaking.
IsOpen bool Defines if this room can be joined by other clients.
MaxPlayers byte Max number of players that can be in the room at any time. 0 means "no limit".
PlayerTtl int Time To Live (TTL) for an 'actor' in a room. If a client disconnects, this actor is inactive first and removed after this timeout. In milliseconds.
EmptyRoomTtl int Time To Live (TTL) for a room when the last player leaves. Keeps room in memory for case a player re-joins soon. In milliseconds.
CustomRoomProperties Dictionary <string, object> The room's custom properties to set during creation.
CustomRoomPropertiesForLobby string[] Defines which of the custom room properties get listed in the lobby.

Value type of the properties has to be bool, byte, short, int, longor string.

Max number of properties is 3.

The max length for string value is 64.

Key restrictions can also be enforced by the Photon dashboard property: AllowedLobbyProperties.
SuppressRoomEvents bool Tells the server to skip room events for joining and leaving players.

Default is false.
SuppressPlayerInfo bool Disables events join and leave from the server as well as property broadcasts in a room (to minimize traffic).

Default is false.
PublishUserId bool Defines if the UserIds of players get "published" in the room. Useful for FindFriends, if players want to play another game together.

Default is false.
DeleteNullProperties bool Optionally, properties get deleted, when null gets assigned as value.

Default is false.

PlayFab

To enable the PlayFab integration add the WebHookIntegration dashboard variable and set it to PlayFab.

  • All slashes from all paths will be substituted with an underscore: game/create => game_create
  • All webhook requests will automatically add the AppId property (if missing) controlled by WebHooksConfig.AppId
  • All webhook requests will automatically add the UserId property (if missing) "0"
  • Webhook responses will handle the following Json result body and cause the webhooks to fail on ResultCode != 0. The Message is copied on errors to WebHookError.Message.

JSON

{
    "ResultCode": 0,
    "Message": "success"
}

Photon Cloud Web Request Limitations

There are global limitations on the Photon Server per room/session. If they are hit web requests and reponse can be dropped.

  • HttpRequestTimeout: 30000
  • LimitHttpResponseMaxSize: 200000
  • MaxQueuedRequests: 5000
Back to top