Photon Realtime

The Photon Realtime plugin is specifically to implement realtime multiplayer features through the Photon Engine and PlayFab, for games built using Construct 3 and Construct 2.


It is a fork or improvement from the official Photon plugins, although additions and changes are gradually added and appended, including PlayFab integration, where a realtime multiplayer system is integrated with an account management and networking system.

The Photon Realtime plugin has full PlayFab integration, taking advantage of all features from the PlayFab Master Collection. This integration creates a unified and complete feature set for turnbased, realtime and massive online multiplayer, from simple to highly advanced games.

PlayFab API v2.png

Introduction

Step 1.png

The Construct Master Collection supports the full and easy integration of the PlayFab service for both Construct 3 and Construct 2.


Please click here to learn more about PlayFab.

Features


Here are some of the features of the PlayFab service:

  • Realtime multiplayer

  • Massive online multiplayer

  • Turn based multiplayer

  • Account system integration

  • Account management

  • Profile management

  • Social connect

  • Friend management

  • Cloud script and functions

  • Webhooks

  • Global time features

  • Server sync timing

  • Find match

  • Create rooms

  • Join rooms

  • Lobbies

  • Multiple region support

  • Security features with server scripting.

  • Organized request and update features.


For more information about all the integrated PlayFab service features, please click here to learn the introductory lessons to PlayFab.


Network Services


Here are some of the platform services that can be linked:

  • PlayFab

  • Google Play

  • Game Center

  • Facebook

  • Facebook Instant Games

  • Steam

  • Xbox Live

  • Instant Games (Android Studio port)

  • Nintendo Switch (3rd party porting services)

  • PS4 (3rd party porting services)

  • Nintendo Switch (3rd party porting services)


Editor Features


Here are some of the features in the Construct editor:

  • All platforms support, including web, mobile and desktop.

  • Construct 3

  • Construct 2

 
 

How to use?

It is easy to use the Photon Realtime plugin, you will only need to follow the steps below.

  1. Set up the PlayFab API plugin, please click to visit the documentation. This includes creating a PlayFab account, studio and title.

  2. Set up the Authentication plugin, please click to visit the documentation.

  3. Finally, you can now use the Photon Realtime object, and include more PlayFab addons for more features.

  4. To start the Photon Realtime, create an account on Photon Engine. Then, create a Photon Realtime application.



5. Retrieve the App ID of your realtime application, labeled below.

6. Once you have the App ID, input it into the AppId property field of the Photon Realtime.



7. Set your AppVersion, preferably similar to your game application's version. Only users with the same app version will be able to play together.

8. If you are using Construct 2, set the protocol to ws since preview is ran locally, However, if you are using Construct 3, then use the wss protocol.

9. Set the target Region of application.

We have a sample Cloud Script implementation for this feature, in the Game Projects documentation section.

10. Set HostType to Photon Cloud if you don't use use Photon On-Premise.

11. If self-hosted through On-Premise, set the server hosting address.

12. Lastly, set the Log Level you want Photon Realtime to use.

 
 

Documentation

There is currently nothing to show, we will add more in the future.



PlayFab Server Setup


PlayFab server-side integration with Photon Realtime is quick and easy. To get started you need to create both a PlayFab and Photon Engine account. Once you have both accounts, you need to create a title (game) in any studio of your PlayFab account. Then, create a Photon Realtime game application project in your Photon Engine account.

Afterwards, proceed below and the guide will walk you through the process of setting up your PlayFab and Photon Realtime integration.



Step 1 : From the PlayFab Dashboard, select the Add-ons menu option. It will show the item group of PlayFab partner services. Select Photon in the Multiplayer addons group.



Step 2 : PlayFab's Photon Cloud integration description will show, please read this first and then proceed to the next step after you are done.



Step 3 : Install the Photon addon if not yet installed, then fill the credential forms if there are any. Required credentials are needed to link your PlayFab title (game) and your Photon Realtime game application project, to initiate full integration.


Step 4 : Take note of the Photon Secret key and input your Photon Realtime App ID. This is the same App ID you've inputted in the Photon Realtime plugin from Construct 3 or Construct 2.



Step 5 : You are almost done in completely integrating your PlayFab title (game) with your Photon Realtime game application project. You just need to follow the instructions in the image to configure your Photon Console.



Step 6 : You have now finished your PlayFab and Photon Realtime integration setup. For more optional features, please proceed below.


Step 7 : There is also an optional feature called Photon Realtime Webhooks and WebRPC with the PlayFab integration. This feature allows you to extend Photon Realtime with PlayFab's automation features including scripting, scheduled tasks and rules. Listening to Photon events while the game is running allows you to run scripts during the game session. PlayFab being a complete network system with account management features allows you to reflect their game session data automatically into their account, statistics and leaderboards, and the analytics, global data and system. This is one of the reasons why PlayFab integration with Photon Cloud is highly advantageous for developers to implement realtime multiplayer games with automation and scripting that transforms the Photon Realtime from a realtime multiplayer network to a complete network system, with account management features.



Related Plugins


  • Photon Chat - is a plugin that implements a dedicated network chat feature for your game applications, although this is mainly only for online chat or messaging and not recommended for realtime data synchronization. The Photon Realtime is the plugin that syncs the game data in realtime for the use of all the players in a game.



Scripting Interface


The Photon Realtime has basic support for Construct 3's scripting feature. Click to learn more about the scripting feature. Also, check out Photon's official documentation to take advantage of all its features.

  • Context - Returns the Photon Realtime's instance context. Example: const self = runtime.objects.PhotonRealtime.getFirstInstance()Context;

  • Client - Returns the Photon Realtime instance's load balancing client. Example: const LoadBalancingClient = runtime.objects.PhotonRealtime.getFirstInstance().Client;

  • Photon - Returns the global Photon object. Example: const Photon = runtime.objects.PhotonRealtime.getFirstInstance().Photon;

For the complete guide and API documentation, please click to visit the full documentation.

 

Actions, Conditions & Expressions

Actions

press to zoom

press to zoom

press to zoom

press to zoom
1/4

The following action groups:

  • Connection

  • Time

  • Lobby

  • Room

  • Lobby & Room

  • Actor

  • Common

  • PlayFab

Connection

  • Set user id - Set optional user id (required by some cloud services).

  • UserId - User id.


  • Set custom authentication - Enable custom authentication and set it's parameters.

  • AuthParameters - Parameters expected by the used authentication service.

  • AuthType - The type of custom authentication provider that should be used.


  • Set hosting type - Set hosting type.

  • HostType - Choose hosting type.


  • Set Self Hosted address - Set Self Hosted address.

  • SelfHostedAddress - Self Hosted address.


  • Set region - Set Master server region.

  • Region - Region.


  • Set app id - Set app id.

  • App id - App id.


  • Set app version - Set app version.

  • App version - App version.


  • Connect - Connect to the name server.

  • Lobby Name - The name of the lobby.

  • Keep connection - Don't disconnect from Master server after joining room.


  • Disconnect - Disconnect from all servers.


  • Suspend room - Disconnect client from Game server keeping player in room (to rejoin later) and connect to Master server if not connected.


  • Leave room - Leave room and connect to Master server if not connected.



Time

  • Sync server time - Fetches server time from the game server and updates the base value used for extrapolation in 'GetServerTime()'.


  • Update Round Trip Time - Triggers game server Round Trip Time measurement for 'GetRoundTripTime()'.



Lobby

  • Create room - Crate room.

  • Room - Room name.

  • LobbyName - Lobby name.

  • LobbyType - Lobby type.


  • Join room - Join room.

  • Room - Room name.

  • Rejoin - Rejoin by current userId

  • CreateIfNotExists - Create room if it does not exist

  • LobbyName - Lobby name.

  • LobbyType - Lobby type.


  • Join random room - Join random room.

  • MatchMyRoom - Use my room MaxPlayer and custom properties for matchmaking.

  • MatchmakingMode - Matchmaking mode

  • LobbyName - Lobby name.

  • LobbyType - Lobby type.

  • SqlLobbyFilter - SqlLobby filter.


  • Join random or create room - Join random room.

  • MatchMyRoom - Use my room MaxPlayer and custom properties for matchmaking.

  • MatchmakingMode - Matchmaking mode

  • LobbyName - Lobby name.

  • LobbyType - Lobby type.

  • SqlLobbyFilter - SqlLobby filter.

  • Room - The name of the room to create.


  • Find friends - Request Master server for friends online status and joined rooms (FindFriends).

  • Friends - Comma-separated list of friends user id's


  • Request lobby stats - Request Master server for lobbies statistics.



Room

  • Raise event - Raise game event.

  • Code - Identifies this type of event.

  • Data - Custom data you want to send along.

  • InterestGroup - The ID of the interest group this event goes to.

  • Cache - Caching options for events.

  • Receivers - Defines to which group of players the event is passed on.

  • TargetActors - Comma-separated list of target actors (who should receive the event) id's. Use only for small target groups. Send to all if empty.

  • WebForward - Forward to web hook.


  • Change groups - Change client's interest group.

  • Action - Group action.

  • Group - Group to add or remove.


  • Set property of my room - Set custom property of my room.

  • PropName - Property Name.

  • Value - Property value.

  • WebForward - Forward to web hook.

  • CheckAndSet - Set only if old equals to expected.

  • ExpectedValue - Expected property value.


  • Set props listed in lobby - Set properties listed in lobby.

  • PropNames - Comma-separated list of properties mames to be listed in lobby.


  • Set my room is visible - Set rooms visibility in the lobby's room list.

  • IsVisible - New visibility value.


  • Set my room is open - Set if this room can be joined.

  • IsOpen - New property value.


  • Set my room max players - Set max players before room is considered full.

  • MaxPlayers - New max players value.


  • Set empty room live time - Set room live time in the server room cache after all clients have left the room.

  • EmptyRoomLiveTime - New live time value in ms.


  • Set suspended player live time - Set time in ms indicating how long suspended player will be kept in the room.

  • SuspendedPlayerLiveTime - New live time value in ms.


  • Set unique userid check - Activates user id checks on joining if set to true.

  • Unique - New property value.


  • Set expected server plugins - Set expected server plugins.

  • Plugins - Comma-separated list of expected server plugins.


  • Set master actor - Asks the server to assign another player as Master Client of your current room.

  • ActorNr - New Master Client actor ID.



Lobby & Room

  • Call WebRpc - Call remote procedure (WebRPC).

  • UriPath - Remote procedure uri path.

  • Parameters - Remote procedure parameters.

  • ParametersType - Parameters type.



Actor

  • Set my actor name - Set name of local actor.

  • Name - Actor name.


  • Set property of actor by nr - Set custom property of actor.

  • ActorNr - Actor number.

  • PropName - Property Name.

  • Value - Property value.

  • WebForward - Forward to web hook.

  • CheckAndSet - Set only if old equals to expected.

  • ExpectedValue - Expected property value.



Common

  • Reset - Disconnects and creates new client instance.



PlayFab

  • PlayFab Authenticate - Authenticate with PlayFab. A variety of custom authentication.

  • PlayFab ID - The PlayFab ID you can get from the PlayFab Master Collection.

  • Photon Token : - The PlayFab Photon Token you can get from the "Get Photon Token" action.


  • Get Photon Token - Gets a Photon custom authentication token that can be used to securely join the player into a Photon room.

Conditions

The following condition groups:

  • Connection

  • Lobby

  • Room

  • Lobby & Room

  • PlayFab

  • Client

press to zoom

press to zoom

press to zoom

press to zoom
1/3

Connection

  • Is connected to Nameserver - True if client connected to Nameserver.


  • Is connected to Master server - True if client connected to Master server.


  • Is connected to a lobby - True if client connected to a lobby.


  • Is joined to a room - True if client joined to a room.



Lobby

  • On room list - Triggered on room list receive.


  • On room list update - Triggered on room list update.


  • On FindFriends result - Triggered when FindFriends request completed.


  • On lobbies statistics update - Triggered when lobbies statistics update received.


  • On application statistics update - Triggered when application statistics update received.


  • On join lobby - Triggered on client joins lobby.


  • On joinRandomRoom no match found - Triggered when joinRandomRoom called and no match found.



Room

  • On event - Triggered on custom event with specific code.

  • Code - Event code.


  • On any event - Triggered on any custom event.


  • On actor properties change - Triggered when actor properties changed.


  • On my room properties change - Triggered when my room properties changed.


  • On join room - Triggered when client joins room.


  • On creator joined room - Trigger fires when the an actor joins the room, compare here if the actor is the room creator or not.

  • Actor Type - Whether the room creator or other actor joined the room.


  • On actor join - Triggered when new actor joins the room.


  • On actor leave - Triggered when actor leaves the room.


  • On actor suspend - Triggered when actor suspended in the room.



Lobby & Room

  • On WebRPC result - Triggered when WebRPC request completed.



PlayFab

  • On Get Photon Token - Triggers when the request to get the photon authentication token has succeeded.


  • On Get Photon Token Failed - Triggers when the request to get the photon authentication token has failed.



Client

  • On error - Triggered on error.


  • On state change - Triggered on client state change.


  • On disconnect - Triggered when client gets disconnected from all servers.

Expressions

press to zoom

press to zoom

press to zoom

press to zoom
1/3

The following expression groups:

  • Connection

  • Time

  • Lobby

  • Room

  • PlayFab

  • Client

Connection

  • State - Current client state.


  • StateString - Current client state string.


  • UserId - Previously set user id.



Time

  • GetRoundTripTime - Returns the latest measurement of game server Round Trip Time. RTT is measured once on connection and then on each "Update Round Trip Time" action.


  • GetServerTime - Returns game server time extrapolation in milliseconds based on the server time fetched on connection or on "Sync server time" action. The server time is a signed 32 bit integer making a full cycle in 49.71 days.



Lobby

  • MyRoomName - Currently my room name.


  • RoomCount - Count of rooms available.


  • RoomNameAt - Name of room at index.

  • Index - Room index.


  • RoomMaxPlayers - Max players before room is considered full

  • Name - Room name.


  • RoomIsOpen - Defines if this room can be joined.

  • Name - Room name.


  • RoomPlayerCount - Count of player currently in room.

  • Name - Room name.


  • RoomProperty - Room property.

  • Name - Room name.

  • PropName - Property name.


  • FriendOnline - True if friend is online.

  • Name - Friend name.


  • FriendRoom - Currently joined room name or empyt string.

  • Name - Friend name.


  • LobbyStatsCount - Count of lobbies statistics entries.


  • LobbyStatsNameAt - Lobby name.

  • Index - Lobby index.


  • LobbyStatsTypeAt - Lobby type.

  • Index - Lobby index.


  • LobbyStatsPeerCountAt - Number of players in the lobby (on Master, not playing).

  • Index - Lobby index.


  • LobbyStatsGameCountAt - Number of games in the lobby.

  • Index - Lobby index.


  • AppStatsPeerCount - Count of players currently online on Game servers.


  • AppStatsMasterPeerCount - Count of players on Master server (looking for game).


  • AppStatsGameCount - Count of games currently in use (includes invisible and full rooms, so it doesn't match lobby list).



Room :

  • MyActorNr - Local actor number.


  • EventCode - Last Photon event code.


  • EventData - Last Photon event data.


  • ActorNr - Actor number.


  • PropertyOfMyRoom - Property of my room.

  • PropName - Property name.


  • ActorCount - Count of actors in room.


  • ActorNrAt - Actor number of actor at index.

  • Index - Actor index.


  • ActorNameByNr - Name of actor by number.

  • Index - Actor index.


  • PropertyOfActorByNr - Property of actor by number.

  • ActorNr - Actor number.

  • PropName - Property name


  • ChangedPropertiesCount - Changed properties count.


  • ChangedPropertyNameAt - Changed property name at index.

  • Index - Property index.


  • MasterActorNr - Actor number of room master.


  • WebRpcUriPath - Request path of WrbRpc which triggered OnWebRpc condition.


  • WebRpcResultCode - Result code returned by remote procedure.


  • WebRpcData - Data returned by remote procedure.



PlayFab

  • PhotonToken - Return the "Photon Token" on "Get Photon Token".



Client

  • ErrorCode - Last error code.


  • ErrorMessage - Last error message.

Object   Properties

Plugin Properties

press to zoom

press to zoom
1/1

The following properties groups:

  • Default

  • AppId - Application id.

  • AppVersion - Application version.

  • Protocol - Connection protocol.

  • ws

  • wss

  • Region - Master server region.

  • eu

  • us

  • asia

  • jp

  • au

  • usw

  • sa

  • cae

  • kr

  • in

  • cn

  • ru

  • rue


  • HostType - Hosting type.

  • Photon Cloud

  • Self Hosted


  • SelfHostedAddress - Self Hosted server address.

  • LogLevel - Logging level.

  • DEBUG

  • INFO

  • WARN

  • ERROR

  • OFF


 
 

Showcase