photon dotnet client documentation v6 2 0

8/10/2019 Photon DotNet Client Documentation v6 2 0

1/58


2/58


3/58


4/58

PhotonPeer.Listener Property 33

PhotonPeer.LocalMsTimestampDelegate Property 33

PhotonPeer.LocalTimeInMilliSeconds Property 33

PhotonPeer.PeerID Property 33

PhotonPeer.PeerState Property 34PhotonPeer.QueuedIncomingCommands Property 34

PhotonPeer.QueuedOutgoingCommands Property 34

PhotonPeer.RoundTripTime Property 34

PhotonPeer.RoundTripTimeVariance Property 34

PhotonPeer.SentCountAllowance Property 34

PhotonPeer.ServerAddress Property 35

PhotonPeer.ServerTimeInMilliSeconds Property 35

PhotonPeer.TimePingInterval Property 35

PhotonPeer.UseCommandActionQueue Property 35

PhotonPeer.UsedProtocol Property 36

PhotonPeer.WarningSize Property 36

PhotonPeer Delegates 36

PhotonPeer.GetLocalMsTimestampDelegate Delegate 36

SupportClass Class 36

SupportClass Classes 37

SupportClass.ThreadSafeRandom Class 37

SupportClass Methods 37

SupportClass.ByteArrayToString Method 37

SupportClass.DeserializeData Method 37

SupportClass.HashtableToString Method 38

NumberToByteArray Method 38

SupportClass.SerializeData Method 39

SupportClass.WriteStackTrace Method 39

Interfaces 39

IPhotonPeerListener Interface 39

IPhotonPeerListener Methods 40

IPhotonPeerListener.DebugReturn Method 40

IPhotonPeerListener.EventAction Method 40

IPhotonPeerListener.OperationResult Method 41

IPhotonPeerListener.PeerStatusCallback Method 41

Structs, Records, Enums 42

ConnectionProtocol Enumeration 43

DebugLevel Enumeration 43

LiteEventCode Enumeration 43

LiteEventKey Enumeration 44

LiteOpCode Enumeration 45

Photon DotNet Client Documentation

iv


5/58

LiteOpKey Enumeration 45

LitePropertyTypes Enumeration 46

PeerStateValue Enumeration 47

PhotonEventKey Enumeration 47

PhotonOpParameterKey Enumeration 48StatusCode Enumeration 48

Index a

Photon DotNet Client Documentation

v


6/58

1Overview

Photon is a development framework to build real-time multiplayer games and applications for various platforms. It consists of

a Server SDK and Client SDKs for several platforms.

This is the documentation and reference for the Photon Client Library for DotNet, including Unity and Silverlight. Additional

documentation and help is available online. Visit: developer.exitgames.com.com and forum.exitgames.com

Photon provides a low-latency communication-layer based on UDP (or alternatively TCP). This protocol allows reliable and

unreliable transfer of data in "commands". On top of this, an operation- and event-framework is established to ease

development of your own games. We developed several applications and included them in the server SDK as example and

code base.

Server-side, the "Lite" application offers the basic operations that we felt useful for most room-based multiplayer games. We

included it's operations and events ( see page 3)are part of of the client API. The MMO application focuses on seamless

worlds and it's client side api is available in source in the MMO application's code (as it shares code with the server side).

The following API is used on several platforms: DotNet for Windows, Mono but also Unity3D scripting and Silverlight.

1.1Photon Workflow

To get an impression of how to work on the client, we will use the server's Lite logic. This application defines rooms which

are created when users try to join them. Each user in a room becomes an actor with her own number.

A simplified workflow looks like this:

create a LitePeer ( see page 13)instance

from now on: regularly call Service() ( see page 31)to get events ( see page 3)and send commands (e.g. ten times asecond)

call Connect() ( see page 27)to connect the server

wait until the library calls IPhotonPeerListener.PeerStatusCallback ( see page 41)

the returned status int should equal StatusCode.Connect ( see page 48)

call OpJoin() ( see page 19)to get into a game

wait until the library calls OperationResult() ( see page 41)with opCode: LiteOpCode.Join ( see page 45)

send data in the game by calling OpRaiseEvent() ( see page 20)

receive events ( see page 3)in IPhotonPeerListener.EventAction() ( see page 40)of type "evCode" (you used some inOpRaiseEvent())

1.1 Photon Workflow Photon DotNet Client Documentation

1

1
http://developer.exitgames.com/http://forum.exitgames.com/http://forum.exitgames.com/http://developer.exitgames.com/


7/58

when you are done: call LitePeer.OpLeave ( see page 20)to quit/leave the game

wait for "leave" return in OperationResult() ( see page 41)with opCode: LiteOpCode.Leave ( see page 45)

disconnect with Disconnect() ( see page 28)

check "disconnect" return in PeerStatusCallback() ( see page 41)with statusCode: StatusCode.Disconnect ( seepage 48)

Combined with the server's Lite application, this simple workflow would allow you to use rooms and send your game's events( see page 3). The methods used could be broken down into three layers:

Low Level:Service, Connect, Disconnect and the StatusCallback are directly referring to the connection to the server.This level works with UDP/TCP packets which transport commands (which in turn carry your operations). It keeps yourconnection alive and organizes your RPC calls and events ( see page 3)into packages.

Logic Level:Operations ( see page 2), results and events ( see page 3)make up the logical level in Photon. Anyoperation defined on the server (think RPC call) and can have a result. Events ( see page 3)are incoming from theserver and update the client with some data.

Application Level:Made up by a specific application and its features. In this case we use the operations and logic of theLite application. In this specific case, we have rooms and actors and more. The LitePeer ( see page 13)is matching the

server side implementation and wraps it up for you.You don't have to manage the low level communication in most cases. However, it makes sense to know that everything that

goes from client to server (and the other way round) is put into "commands". Internally, commands are also used to establish

and keep the connection between client and server alive (without carrying additional data).

All methods that are operations (RPC calls) are prefixed with "Op" to tell them apart from anything else. Other server side

applications (like MMO or your own) will define different operations. These will have different parameters and return values.

These operations are not part of the client library but can be implemented by calling OpCustom().

The interface IPhotonPeerListener ( see page 39)must be implemented for callbacks. They are:

PeerStatusCallback ( see page 41)is for peer state-changes (connect, disconnect, errors, compare with StatusCodeEnumeration ( see page 48))

OperationResult ( see page 41)is the callback for operations (join, leave, etc.)

EventAction ( see page 40)as callback for events ( see page 3)coming in

DebugReturn ( see page 40)as callback to debug output (less frequently used by release builds)

The following properties in PhotonPeer ( see page 23)are of special interest:

TimePingInterval ( see page 35)sets the time between ping-operations

RoundTripTime ( see page 34)of reliable operations to the server and back

RoundTripTimeVariance ( see page 34)shows the variability of the roundtrip time

ServerTimeInMilliSeconds ( see page 35)is the continuously approximated server's time

1.2Operations

Operation is our term for remote procedure calls (RPC) on Photon. This in turn can be described as methods that are

implemented on the server-side and called by clients. As any method, they have parameters and return values. The Photon

development framework takes care of getting your RPC calls from clients to server and results back.

1.2 Operations Photon DotNet Client Documentation

2

1


8/58

Server-side, operations are part of an application running on top of Photon. The default application provided by Exit Games

is called "Lite Application" or simply Lite. The LitePeer ( see page 13)class extends the PhotonPeer ( see page 23)by

methods for each of the Lite Operations.

Examples for Lite Operations are "join" and "raise event". On the client side, they can be found in the LitePeer ( see page

13)class as methods: OpJoin and OpRaiseEvent. They can be used right away with the default implementation of Photon

and the Lite Application.

Custom Operations

Photon is extendable with features that are specific to your game. You could persist world states or double check information

from the clients. Any operation that is not in Lite or the MMO application logic is called Custom Operation. Creating those is

primarily a server-side task, of course, but the clients have to use new functions / operations of the server.

So Operations are methods that can be called from the client side. They can have any number of parameters and any name.

To preserve bandwidth, we assign byte-codes for every operation and each parameter. The definition is done server side.

Each Operation has its own, unique number to identify it, known as the operation code (opCode). An operation class defines

the expected parameters and assigns a parameter code for each. With this definition, the client side only has to fill in the

values and let the server know the opCode of the Operation.

Photon uses Hashtables to aggregate the opCode and all parameters. Use OpCustom() ( see page 29) to send your

Hashtable ( see page 11)and call any operation.

Client side, opCode and parameter-codes are currently of type byte (to minimize overhead). They need to match the

definition of the server side to successfully call your operation.

OpCodes: byte versus short

Currently, the server side uses the short-type to define opCodes and parameter keys while the client side uses bytes only.

This is a remainder of Neutron, essentially, where we implemented more values of opCodes. But using short for each

opCode and parameter is a lot of overhead in a realtime environment, so we decided to revert this in the protocol and just

send bytes. This simply save lots of bandwidth.

OpCodes and parameters are mapped by value, of course.

1.3Events

Unlike operations, events are "messages" that are rarely triggered by the client that receives them. Events come from

outside: the server or other clients.

They are created as side effect of operations (e.g. when you join a room) or raised as main purpose of the operation Raise

Event. Most events carry some form of data but in rare cases the type of event itself is the message.

Events are (once more) Hashtables with arbitrary content.

1.4Fragmentation and Channels

Fragmentation

Bigger data chunks of data (more than 1kB) are not fitting into a single package, so they are fragmented and reassembled

automatically. Depending on the data size, this takes up multiple packages.

1.4 Fragmentation and Channels Photon DotNet Client Documentation

3

1


9/58

Be aware that this might stall other commands. Call Service() or SendOutgoingCommands() more often than absolutely

necessary. You should check that PhotonPeer.QueuedOutgoingCommands ( see page 34)is becoming zero regularly to

make sure everything gets out. You can also check the debug output for "UDP package is full", which can happen from time

to time but should not happen permanently.

Sequencing

The sequencing of the protocol makes sure that any receiving client will Dispatch your actions in the order you sent them.

Unreliable data is considered replaceable and can be lost. Reliable events ( see page 3)and operations will be repeated

several times if needed but they will all be Dispatched in order without gaps. Unreliable actions are also related to the last

reliable action and not Dispatched before that reliable data was Dispatched first. This can be useful, if the events ( see

page 3)are related to each other.

Example: Your FPS sends out unreliable movement updates and reliable chat messages. A lost package with movement

updates would be left out as the next movement update is coming fast. An the receiving end, this would maybe show as a

small jump. If a package with a chat message is lost, this is repeated and would introduce lag, even to all movement updates

after the message was created. In this case, the data is unrelated and should be put into different channels.

Channels

The DotNet clients and server are now supporting "channels". This allows you to separate information into multiple channels,

each being sequenced independently. This means, that Events ( see page 3)of one channel will not be stalled because

events ( see page 3)of another channel are not available.

By default an PhotonPeer ( see page 23) has two channels and channel zero is the default to send operations. The

operations join and leave are always sent in channel zero (for simplicity). There is a "background" channel 255 used

internally for connect and disconnect messages. This is ignored for the channel count.

Channels are prioritized: the lowest channel number is put into a UDP package first. Data in a higher channel might be sent

later when a UDP package is already full.

Example: The chat messages can now be sent in channel one, while movement is sent in channel zero. They are not relatedand if a chat message is delayed, it will no longer affect movement in channel zero. Also, channel zero has higher priority

and is more likely to be sent (in case packages get filled up).

1.5Using TCP

A PhotonPeer ( see page 23)could be instanced with TCP as underlying protocol if necessary. This is not best practice but

some platforms don't support UDP sockets. This is why Silverlight and Flash use TCP in all cases.

The Photon Client API is the same for both cases but there are some differences in what goes on below.Everything sent over TCP is reliable. Automatically. And even if you call your operations as unreliable!

If you use only TCP clients

Simply send any operation unreliable. It saves some work (and bandwidth) in the underlying protocols.

If you have TCP and UDP clients

Anything you send between the TCP clients will always be transferred reliable. But as you communicate with some clients

that use UDP these will get your events ( see page 3)reliable or unreliable.

1.5 Using TCP Photon DotNet Client Documentation

4

1


10/58

Example:

A Silverlight client might send unreliable movement updates in channel # 1. This will be sent via TCP, which makes it

reliable. Photon however also has connections with UDP clients (like a 3D downloadable game client). It will use your

reliable / unreliable settings to forward your movement updates accordingly.

1.6Serializable Datatypes

Starting with Photon Server SDK 1.8.0 and DotNet SDK 5.6.0, the set of serializable datatypes is changed. The ArrayList (

see page 10) was removed but aside from Arrays and Hashtables every serializable type can also be sent as array (e.g.

String[], Float[]). Only one-dimensional arrays are supported currently.

Photon 1.8.0 and higher

String / string

Boolean / bool

Byte / byte (unsigned! can be cast to SByte / sbyte to be eqivalent to Java's byte)

Int16 / short (signed)

Int32 / int (signed)

Int64 / long

Single / float

Double / double

Array (of the types above, with a max number of Short.MaxValue enties).

Hashtable ( see page 11)(not available as array)

The following data types can be used within events ( see page 3)as keys and values on Neutron:

Photon 1.6.0 and lower

String

Boolean

Byte / byte (unsigned! can be cast to SByte / sbyte to be equivalent to Java's byte)

Int16 (equals Short in Java)

Int32 (equals Integer in Java)

Int64 (equals Long in Java)

ArrayList ( see page 10)(equals Vector in Java)

Hashtable ( see page 11)

sbyte[]

int[]

String[]

1.7 The Photon Server Photon DotNet Client Documentation

5

1


11/58

1.7The Photon Server

The Photon Server is the central hub for communication for all your clients. It is a service that can be run on any Windowsmachine, handling the UDP and TCP connections of clients and hosting a DotNet runtime layer with your own business

logic, called application.

The Photon Server SDK includes several applications in source and pre-built. You can run them out of the box or develop

your own server logic.

Get the Photon Server SDK at: photon.exitgames.com

1.8Lite ApplicationThe Lite Application is the example application for room-based games on Photon and (hopefully) a flexible basis for your

own games. It offers rooms, joining and leaving them, sending events ( see page 3) to the other players in a room and

handles properties.

The Lite Application is tightly integrated with the client libraries and used as example throughout most documentation.

1.8.1Properties on Photon

The Lite Application implements a general purpose mechanism to set and fetch key/value pairs on the server side (in

memory). They are associated to a room/game or a player within a room and can be fetched or updated by anyone in that

game.

Each entry in the properties Hashtable ( see page 11) is considered a separate property and can be overwritten

independently. The value of a property can be of any serializable datatype ( see page 5). The keys must be either of type

string or byte. Bytes are preferred, as they mean the less overhead.

To avoid confusion, don't mix string and byte as key-types. Mixed types of keys, require separate requests to fetch them.

Property broadcasting and events

Property changes in a game can be "broadcasted", which triggers events ( see page 3) for the other players to updatethem. The player who changed the property does not get the update (again).

Any change that uses the broadcast option will trigger a property update event. This event carries the changed properties

(only), who changed the properties and where the properties belong to.

Your clients need to "merge" the changes (if properties are cached at all).

Properties can be set by these methods:

LitePeer.OpSetPropertiesOfActor Method ( see page 22)sets a player's properties

LitePeer.OpSetPropertiesOfGame Method ( see page 22)sets a game's properties

LitePeer.OpJoin Method ( see page 19)also allows you to set properties if the game did not exist yet

1.8 Lite Application Photon DotNet Client Documentation Properties on Photon

6

1
http://photon.exitgames.com/http://photon.exitgames.com/


12/58

And fetched with these methods:

OpGetPropertiesOfActor

OpGetPropertiesOfGame

Broadcast Events

Any change that uses the broadcast option will trigger a property update event LiteEventCode.SetProperties ( see page

43). This event carries the properties as value of key LiteEventKey.Properties ( see page 44).

Additionally, there is information about who changed the properties in key LiteEventKey.ActorNr ( see page 44).

The key LiteEventKey.TargetActorNr ( see page 44)will only be available if the property-set belongs to a certain player. If

it's not present, the properties are game-properties.

Notes

The current Lite application is not able to delete properties and does not support wildcard characters in string keys to fetch

properties.

Other types of keys could be used but to keep things simple, we decided against adding those. If needed, we would help you

with the implementation.

The property handling is likely to be updated and extended in the future.

1.9Further Help

Developer Network

Visit: developer.exitgames.com

Developer Forum

Visit: forum.exitgames.com

Mail Support

Don't hesitate to mail us: [email protected]

1.9 Further Help Photon DotNet Client Documentation

7

1
http://www.developer.exitgames.com/http://forum.exitgames.com/http://forum.exitgames.com/http://www.developer.exitgames.com/


13/58

2DotNet Platforms

2.1Photon for Unity3D

This chapter addresses differences between the DotNet SDK and the one for Unity3D.

If you don't use Unity3D, skip this chapter.

1. Supported versions of Unity:

a) Currently supported and tested Unity platforms are Standalone and Web (both Windows and MacOS) and iOS. The

export to PS3, Wii and Android are not tested by us currently but should be working as well.

b) Photon works fine with Unity Standard, with Unity Pro. Export to iOS devices might require a special Unity license.

2. Unity 3 and policy file requests

Starting with Unity 3.0, web players will require a policy file to connect to a different URL than their originating server. Photon

supports this feature out of the box. By default the server opens the a port for policy file requests (TCP port 843) and maps it

to the "Policy Application". We included source for this but in general it should be fine to just use deploy the binaries.

3. How to add Photon to your Unity project:

a) To add the Photon .dll from the SDK to a Unity project, just copy it somewhere in the assets-folder of the project and

make sure that there are no duplicates (pay attention to old versions with different filenames).

b) Make sure to have the following line of code somewhere in your scripts, so the game runs even when in background:

Application.runInBackground = true; //without this Photon will loose connection if not focussed

c) For the iOS builds, you should set the "iPhone Stripping Level" to "Strip Bytecode" (Edit->Project Settings->Player). Also,

use the "DotNet 2.0 subset". If your project runs fine in IDE and you get an error message when building it for device, please

check this option.

d) Make sure to change the server address used in the client, as "localhost:5055" won't work on device.

2.2Photon for Silverlight

The Photon DotNet Client Library for Silverlight is based on the regular DotNet library (and shares its documentation).

Essential differences

No UDP

Silverlight does not support UDP sockets and thus all instanced PhotonPeers are using TCP. This affects Photon only.

No Port 5055

2.2 Photon for Silverlight Photon DotNet Client Documentation

8

2


14/58

Again a change for Photon usage: you cannot select just any port with Silverlight. It needs to connect to ports in the range of:

4502-4534. We selected 4530 as connection port. You also need to have a Policy File Server running on port 843. Both TCP

ports must be open to the general internet to reach your server. The Photon Server SDK provides the correct setup.

No Hashtable ( see page 11)or ArrayList ( see page 10)

Silverlight excludes non-generic data types. As those are used throughout the libraries, we added the substitutes for those

classes. They are located in a separate library, so you could use Photon with Neutron in one project. Usage of thosesubstitutes should be analog to the DotNet Hashtable ( see page 11)and ArrayList ( see page 10).

Additional lib needed

In the Silverlight SDKs, we needed to split some classes from the Photon (and Neutron) libraries into a separate file.

Because of this, Silverlight projects have to both provided libraries / dlls of the Photon SDK.

The Demos

As usual, the demos are plain and consist of the least amount of UI possible (it's not our focus).

The Silverlight Photon Demo has its entry point in the Page.xaml.cs but most of the Photon logic is wrapped by the

Game.cs class. The sample should be compatible with the Realtime Demo of the DotNet SDK and others. Those however

are expanded more often.

If you need any further Silverlight demos we will help you. We just need to know.

2.2 Photon for Silverlight Photon DotNet Client Documentation

9

2


15/58

3Symbol Reference

3.1Classes

The following table lists classes in this documentation.

Classes

Name Description

ArrayList ( see page 10) Silverlight only! This is a wrapper around a List as substitute forthe missing ArrayList class in Silverlight.

Hashtable ( see page 11) Silverlight only! This is a wrapper around a Dictionary as

substitute for the missing Hashtable class in Silverlight.LitePeer ( see page 13) A LitePeer is an extended PhotonPeer ( see page 23)and implements

the operations offered by the "Lite Application ( see page 6)" of thePhoton Server SDK.

PhotonPeer ( see page 23) Instances of the PhotonPeer class are used to connect to a Photonserver and communicate with it.

SupportClass ( see page 36) Contains conversion support elements such as classes, interfaces andstatic methods.

3.1.1ArrayList Class

Silverlight only! This is a wrapper around a List as substitute for the missing ArrayList class in Silverlight.

C#

publicclassArrayList: List;

Notes

Supplied in separate library dll!

See: Photon for Silverlight ( see page 8)

Methods

Name Description

ArrayList ( see page 11) This is ArrayList, a member of class ArrayList.ArrayList Fields

Name Description

SyncRoot ( see page 11) This is SyncRoot, a member of class ArrayList.

ArrayList Methods

Name Description

Synchronized ( see page 11) This is Synchronized, a member of class ArrayList.

3.1.1.1ArrayList Constructor

3.1 Classes Photon DotNet Client Documentation ArrayList Class

10

3


16/58

3.1.1.1.1ArrayList.ArrayList Constructor ()

C#

publicArrayList();

Description

This is ArrayList, a member of class ArrayList.

3.1.1.1.2ArrayList.ArrayList Constructor (int)

C#

publicArrayList(intx);

Description

This is ArrayList, a member of class ArrayList.

3.1.1.2ArrayList Fields

3.1.1.2.1ArrayList.SyncRoot Field

C#

publicObject SyncRoot= newObject();

Description

This is SyncRoot, a member of class ArrayList.

3.1.1.3ArrayList Methods

3.1.1.3.1ArrayList.Synchronized Method

C#

publicstaticArrayListSynchronized(ArrayListl);

Description

This is Synchronized, a member of class ArrayList.

3.1.2Hashtable Class

Silverlight only! This is a wrapper around a Dictionary as substitute for the missing Hashtable class in

Silverlight.

C#

publicclassHashtable: Dictionary;

Notes

Supplied in separate library dll!

See: Photon for Silverlight ( see page 8)

3.1 Classes Photon DotNet Client Documentation Hashtable Class

11

3


17/58


18/58

3.1.2.2.3Hashtable.ToString Method

C#

publicnewString ToString();

Description

This is ToString, a member of class Hashtable.

3.1.3LitePeer Class

A LitePeer is an extended PhotonPeer ( see page 23)and implements the operations offered by the "Lite Application (

see page 6)" of the Photon Server SDK.

C#

publicclassLitePeer: PhotonPeer;

Remarks

This class is used by our samples and allows rapid development of simple games. You can use rooms and properties and

send events ( see page 3). For many games, this is a good start.

Methods

Name Description

PhotonPeer ( see page 26) Creates a new PhotonPeer instance to communicate with Photon.

Connection is UDP based, except for Silverlight.

LitePeer Class

Name Description

LitePeer ( see page 16) Creates a LitePeer instance to connect and communicate with a Photonserver.

Uses UDP as protocol (except in the Silverlight library).

PhotonPeer Delegates

Name Description

GetLocalMsTimestampDelegate ( see page 36) This is nested type PhotonPeer.GetLocalMsTimestampDelegate.

PhotonPeer Fields

Name Description

PhotonPort ( see page 27) The default port used with Photon as string. DotNet and Unity: "5055"."4530" for Silverlight.

PhotonPeer Methods

Name Description

Connect ( see page 27) This method does a DNS lookup (if necessary) and connects to the givenserverAddress.

The return value gives you feedback if the address has the correctformat. If so, this starts the process to establish the connection itself,which might take a few seconds.

When the connection is established, a callback toIPhotonPeerListener.PeerStatusCallback ( see page 41)will be done. Ifthe connection can't be established, despite having a valid address, thePeerStatusCallback is called with an error-value.

The appID defines the application logic to use server-side and it shouldmatch the name of one of the apps in your server's config.

By default,... more ( see page 27)

3.1 Classes Photon DotNet Client Documentation LitePeer Class

13

3


19/58

DeriveSharedKey ( see page 28) This method must be called with the OperationResult ofOpExchangeKeysForEncryption ( see page 30)to establish a sharedsecret with the server and enable encryption.

If this is successful, the property IsEncryptionAvailable ( see page 33)becomes true.

In OperationResult use this code to derive the shared secret: case

(byte)LiteOpCode.ExchangeKeysForEncryption://this.DebugReturn("OpExchangeKeysForEncryption ( see page 30)response: " + SupportClass.HashtableToString ( see page38)(returnValues)); if (returnCode == 0)this.peer.DeriveSharedKey((byte[])returnValues[(byte)LiteOpKey.ServerKey]);break;

Disconnect ( see page 28) This method disconnects from the Photon Server which will endcommunication (if any).

Disconnect is also a command on the Server. The callback is a call tonPeerReturn() ( see page 41)with a returnCode ofstatusCode.Disconnect ( see page 48)and an operationCode ofLiteOpCode.Blank ( see page 45). If the client is disconnected alreadyor the connection thread is stopped, then there is no callback.

Disconnecting will also leave the joined game (if any) and trigger therespective event (LiteEventCode.Leave ( see page 43)) for theremaining players.

DispatchIncomingCommands (see page 28)

This method directly causes the callbacks for events ( see page 3),responses and state changes within a IPhotonPeerListener ( see page39). DispatchIncomingCommands only executes a single receivedcommand per call. If a command was dispatched, the return value is trueand the method should be called again. This method is called by Service( see page 31)() until currently available commands are dispatched.

FetchServerTimestamp ( seepage 28)

This will fetch the server's timestamp and update the approximation forproperty ServerTimeInMilliseconds.

The server time approximation will NOT become more accurate byrepeated calls. Accuracy currently depends on a single roundtrip which is

done as fast as possible.The command used for this is immediately acknowledged by the server.This makes sure the roundtrip time is low and the timestamp +rountriptime / 2 is close to the original value.

OpCustom ( see page 29) Channel-less wrapper for OpCustom().

OpExchangeKeysForEncryption (see page 30)

This method creates a public key for this client and exchanges it with theserver.

Encryption is not instantly available after calling this method. The fetchedserver's public-key is provided by callback to OperationResult. SeeDeriveSharedKey ( see page 28)how to go on after this operation.

SendOutgoingCommands ( seepage 30)

This method creates a UDP/TCP package for outgoing commands(operations and acknowledgements) and sends them to the server. Thismethod is also called by Service ( see page 31)().

Service ( see page 31) This method excutes the internal send- and dispatch-processes in thecontext/thread of an application.

StopThread ( see page 31) This method immediately closes a connection (pure client side). If theconnections was open, this will trigger a disconnect callback toPeerStatusCallback() with a returnCode of statusCode.Disconnect ( seepage 48)and an operationCode of LiteOpCode.Blank ( see page 45).

LitePeer Class

Name Description

OpGetProperties ( see page 17) Gets all properties of the game and each actor.

OpGetPropertiesOfActor ( seepage 17)

Gets selected properties of an actor.


14

3


20/58

OpGetPropertiesOfGame ( seepage 18)

Gets selected properties of current game.

OpJoin ( see page 19) This operation will join an existing room by name or create one if thename is not in use yet.

Rooms (or games) are simply identified by name. We assume that usersalways want to get into a room - no matter if it existed before or not, so it

might be a new one. If you want to make sure a room is created (new,empty), the client side might come up with a unique name for it (makesure the name was not taken yet).

The application "Lite Lobby" lists room names and effectively allows theuser to... more ( see page 19)

OpLeave ( see page 20) Leave operation of the Lite Application (also in Lite Lobby). Leaves aroom / game, but keeps the connection. This operations triggers theevent LiteEventCode.Leave ( see page 43)for the remaining clients.The event includes the actorNumber of the player who left in keyLiteEventKey.ActorNr ( see page 44).

OpRaiseEvent ( see page 20) Wrapper for OpRaiseEvent() without channel-parameter (will use channel= 0).

OpSetPropertiesOfActor ( see

page 22)

Attaches or updates properties of an actor.

OpSetPropertiesOfGame ( seepage 22)

Attaches or updates properties of the current game.

PhotonPeer Properties

Name Description

BytesIn ( see page 31) Count of all bytes coming in (including headers, excluding UDP/TCPoverhead)

BytesOut ( see page 32) Count of all bytes going out (including headers, excluding UDP/TCPoverhead)

ChannelCount ( see page 32) Gets / sets the number of channels available in UDP connections withPhoton. Photon Channels are only supported for UDP. The defaultChannelCount is 2.

CommandBufferSize ( see page32)

length of buffer - might be changed later on?!

DebugOut ( see page 32) Sets the level of debug output which is returned by the library (inDebugReturn ( see page 40)).

Use the PhotonPeer.DebugLevel ( see page 43)enumeration. Default:Error.

debugTimeForDeriveSharedKey (see page 32)

(Temporary property) Count of milliseconds that deriving the shared keytook. Available after OpExchangeKeysForEncryption ( see page 30)and DeriveSharedKey ( see page 28)was called.

debugTimeForDiffieHellman ( seepage 32)

(Temporary property) Count of milliseconds that the Diffie Hellmanalgorithm needed to create the keys and provide a byte array of those.Available after a call to OpExchangeKeysForEncryption ( see page 30).

DisconnectTimeout ( see page 33) Milliseconds after which a reliable UDP command triggers a timeoutdisconnect, unless acknowledged by server. This value currently onlyaffects UDP connections. The actual timeout might happen later,depending on the connection. Commands that are sent while having abad roundtrip time and variance are checked less often for re-sending!

DisconnectTimeout and SentCountAllowance ( see page 34)arecompeting settings: either might trigger a disconnect on the client first,depending on the values and Rountrip Time. Default: 10000 ms.

IsEncryptionAvailable ( see page33)

This property is set by OpExchangeKeysForEncryption ( see page 30)()and DeriveSharedKey ( see page 28)(). While it's true, encryption canbe used for operations.

Listener ( see page 33) Gets the IPhotonPeerListener ( see page 39)of this instance (set inconstructor). Can be used in derived classes for Listener.DebugReturn().


15

3


21/58

LocalMsTimestampDelegate ( seepage 33)

This setter for a timestamp delegate which then replaces the defaultEnvironment.TickCount with any equal function.

LocalTimeInMilliSeconds ( seepage 33)

Gets a local timestamp in milliseconds by calling theGetLocalMsTimestampDelegate ( see page 36). SeeLocalMsTimestampDelegate ( see page 33).

PeerID ( see page 33) This peer's ID as assigned by the server or 0 if not using UDP. Will be

0xFFFF before the client connects.PeerState ( see page 34) This is the (low level) state of the connection to the server of a

PhotonPeer ( see page 23). It is managed internally and read-only.

QueuedIncomingCommands (see page 34)

Returns the sum of all currently received but not-yet-Dispatched reliablecommands (events ( see page 3)and operation results) from allchannels.

QueuedOutgoingCommands (see page 34)

Sum of all commands currently queued as outgoing, including allchannels and reliable, unreliable.

RoundTripTime ( see page 34) Time until a reliable command is acknowledged by the server.

The value measures network latency and for UDP it includes the server'sACK-delay (setting in config). In TCP, there is no ACK-delay, so thevalue is slightly lower (if you use default settings for Photon).

RoundTripTime is updated constantly. Every reliable command willcontribute a fraction to this value.

This is also the approximate time until a raised event reaches anotherclient or until an operation result is available.

RoundTripTimeVariance ( seepage 34)

Changes of the roundtriptime as variance value. Gives a hint about howmuch the time is changing.

SentCountAllowance ( see page34)

Number of send retries before a peer is considered lost/disconnected.Default: 5. The initial timeout countdown of a command is calculated bythe current roundTripTime + 4 * roundTripTimeVariance. Please note thatthe timeout span until a command will be resent is not constant, butbased on the roundtrip time at the initial sending, which will be doubledwith every failed retry.

DisconnectTimeout ( see page 33)and SentCountAllowance arecompeting settings: either might trigger a disconnect on the client first,

depending on the values and Rountrip Time.

ServerAddress ( see page 35) The server address which was used in PhotonPeer.Connect ( seepage 27)() or null (before Connect ( see page 27)() was called).

ServerTimeInMilliSeconds ( seepage 35)

Approximated Environment.TickCount value of server (while connected).

TimePingInterval ( see page 35) Sets the milliseconds without reliable command before a ping command(reliable) will be sent (Default: 1000ms). The ping command is used tokeep track of the connection in case the client does not send reliablecommands by itself. A ping (or reliable commands) will update theRoundTripTime ( see page 34)calculation.

UseCommandActionQueue ( seepage 35)

This is UseCommandActionQueue, a member of class PhotonPeer.

UsedProtocol ( see page 36) The protocol this Peer uses to connect to Photon.

WarningSize ( see page 36) The WarningSize allows the PhotonPeer ( see page 23)class to testeach individual queue for congestion (in and out, reliable and unreliable).If there are more commands than WarningSize in a queue, PhotonPeer( see page 23)will call the PhotonPeerListener.PeerStatusCallback()callback with a respective StatusCode ( see page 48).

3.1.3.1LitePeer Constructor

3.1.3.1.1LitePeer.LitePeer Constructor (IPhotonPeerListener)

Creates a LitePeer instance to connect and communicate with a Photon server.


16

3


22/58


23/58


24/58

C#

publicvirtualshortOpGetPropertiesOfGame(string[]properties,bytechannelId);

Parameters

Parameters Description

string[] properties array of property keys to fetchbyte channelId channel 0 or higher

Returns

Consecutive invocationID of the OP. Will throw Exception if not connected or channelId >= channelCount.

Description

Please read the general description of Properties on Photon ( see page 6).

3.1.3.2.4OpJoin Method

3.1.3.2.4.1LitePeer.OpJoin Method (string)This operation will join an existing room by name or create one if the name is not in use yet.

Rooms (or games) are simply identified by name. We assume that users always want to get into a room - no matter if it

existed before or not, so it might be a new one. If you want to make sure a room is created (new, empty), the client side

might come up with a unique name for it (make sure the name was not taken yet).

The application "Lite Lobby" lists room names and effectively allows the user to select a distinct one.

Each actor (a.k.a. player) in a room will get events ( see page 3)that are raised for the room by any player.

To distinguish the actors, each gets a consecutive actornumber. This is used in events ( see page 3)to mark who triggered

the event. A client finds out it's own actornumber in the return callback for operation Join. Number 1 is the lowest

actornumber in each room and the client with that actornumber created the room.

Each client could easily send custom data around. If the data should be available to newcomers, it makes sense to use

Properties.

Joining a room will trigger the event LiteEventCode.Join ( see page 43), which contains the list of actorNumbers of current

players inside the room (LiteEventKey.ActorList ( see page 44)). This also gives you a count of current players.

C#

publicvirtualshortOpJoin(stringgameName);

Parameters


string gameName Any identifying name for a room / game.

Returns

Consecutive invocationID of the OP. Will throw Exception if not connected.

3.1.3.2.4.2LitePeer.OpJoin Method (string, Hashtable, Hashtable, bool)

This operation will join an existing room by name or create one if the name is not in use yet.

Rooms (or games) are simply identified by name. We assume that users always want to get into a room - no matter if it

existed before or not, so it might be a new one. If you want to make sure a room is created (new, empty), the client side

might come up with a unique name for it (make sure the name was not taken yet).

The application "Lite Lobby" lists room names and effectively allows the user to select a distinct one.

Each actor (a.k.a. player) in a room will get events ( see page 3)that are raised for the room by any player.


19

3


25/58

To distinguish the actors, each gets a consecutive actornumber. This is used in events ( see page 3)to mark who triggered

the event. A client finds out it's own actornumber in the return callback for operation Join. Number 1 is the lowest

actornumber in each room and the client with that actornumber created the room.

Each client could easily send custom data around. If the data should be available to newcomers, it makes sense to use

Properties.

Joining a room will trigger the event LiteEventCode.Join ( see page 43), which contains the list of actorNumbers of currentplayers inside the room (LiteEventKey.ActorList ( see page 44)). This also gives you a count of current players.

C#

publicvirtualshortOpJoin(stringgameName, HashtablegameProperties, Hashtable

actorProperties,boolbroadcastActorProperties);

Parameters


string gameName Any identifying name for a room / game.

Hashtable gameProperties optional, set of game properties, by convention: only used ifgame is new/created

Hashtable actorProperties optional, set of actor properties

bool broadcastActorProperties optional, broadcast actor proprties in join-event

Returns


3.1.3.2.5OpLeave Method

3.1.3.2.5.1LitePeer.OpLeave Method ()

Leave operation of the Lite Application (also in Lite Lobby). Leaves a room / game, but keeps the connection. This

operations triggers the event LiteEventCode.Leave ( see page 43) for the remaining clients. The event includes the

actorNumber of the player who left in key LiteEventKey.ActorNr ( see page 44).

C#

publicvirtualshortOpLeave();

Returns


3.1.3.2.5.2LitePeer.OpLeave Method (String)

Deprecated. Please use OpLeave() without the gameName parameter (it's not checked server side).

C#

publicvirtualshortOpLeave(String gameName);

Returns


3.1.3.2.6OpRaiseEvent Method

3.1.3.2.6.1LitePeer.OpRaiseEvent Method (byte, Hashtable, bool)

Wrapper for OpRaiseEvent() without channel-parameter (will use channel = 0).

C#

publicvirtualshortOpRaiseEvent(byteeventCode, HashtableevData,boolsendReliable);


20

3


26/58

Parameters


byte eventCode

Hashtable evData

bool sendReliable

Returns


3.1.3.2.6.2LitePeer.OpRaiseEvent Method (byte, Hashtable, bool, byte)

This method raises an event which is sent to the other players of a game.

C#

publicvirtualshortOpRaiseEvent(byteeventCode, HashtableevData,boolsendReliable,byte

channelId);

Parameters


byte eventCode the eventCode (used in callbackIPhotonPeerListener.EventAction ( see page 40)) onreceiving parties

Hashtable evData the event's data in form of a Hashtable ( see page 11)

bool sendReliable true sends the event reliable, false sends unreliable

byte channelId number of channel to use (starting with 0)

Returns


Remarks

RaiseEvent can be used reliable or unreliable. Both result in ordered events ( see page 3)but the unreliable ones might belost and allow gaps in the resulting event sequence. On the other hand, they cause less overhead and are optimal for data

that is replaced soon. Sending is not done immediately but in intervals of Service ( see page 31)calls.

The parameter eventCode defines the event's type and eventCode-value on the receiving clients. The parameter "evData" is

a Hashtable ( see page 11)which can have any number of keys and values of the serializable datatypes ( see page 5). It

will be copied to the resulting event Hashtable ( see page 11)as value of key: LiteEventKey.Data ( see page 44).

It is recommended to keep keys (and data) as simple as possible (e.g. Byte or Short as key and byte[] as value), as the data

is typically sent multiple times per second. This would add up to a huge amount of data in itself otherwise.

Example

//send some position data: HashtableevInfo = new Hashtable();

Player local = (Player)players[playerLocalID]; evInfo.Add((Object)STATUS_PLAYER_POS_X, (Int32)local.posX);

evInfo.Add((Object)STATUS_PLAYER_POS_Y, (Int32)local.posY);

peer.OpRaiseEvent(EV_MOVE, evInfo, true); //EV_MOVE = 101

//receive said data in eventAction(): Hashtabledata = (Hashtable)photonEvent[LiteEventKey.Data];

switch(eventCode) {

caseEV_MOVE: //101 in this sample p = (Player)players[actorNr];

if(p != null) {

p.posX = (int)data[(Byte)STATUS_PLAYER_POS_X];

p.posY = (int)data[(Byte)STATUS_PLAYER_POS_Y]; }

break;

Events ( see page 3)from the Photon Server are not pushed through the regular Protocol library. Instead they are received


21

3


27/58

and internally buffered until they are Dispatched ( see page 28).

3.1.3.2.6.3LitePeer.OpRaiseEvent Method (byte, Hashtable, bool, byte, int[])

Extended Operation Raise Event ( see page 3)with optional target actor list.

C#

publicvirtualshortOpRaiseEvent(byteeventCode, HashtableevData,boolsendReliable,byte

channelId, int[] targetActors);

Parameters


byte eventCode the eventCode (used in callbackIPhotonPeerListener.EventAction ( see page 40)) onreceiving parties

Hashtable evData the event's data in form of a Hashtable ( see page 11)

bool sendReliable true sends the event reliable, false sends unreliable

int[] targetActors list of actorNumbers which should receive this event. if null,ALL OTHER players in room will get the event.

Returns


Remarks

This variant works like the regular OpRaiseEvent methods. Please read the documentation of these ( see page 21). This

variant has an optional list of target actors. If set, the server will send the event only to the room's actors defined by the list.

This can be used to implement private messages inside a room or similar.

3.1.3.2.7LitePeer.OpSetPropertiesOfActor Method

Attaches or updates properties of an actor.

C#

publicvirtualshortOpSetPropertiesOfActor(intactorNr, Hashtableproperties,bool

broadcast,bytechannelId);

Parameters


int actorNr the actorNr is used to identify a player/peer in a game

Hashtable properties hashtable containing the properties to add or overwrite

bool broadcast true will trigger an event LiteEventKey.SetProperties with theupdated properties in it

byte channelId channel 0 or higher

Returns


Description


3.1.3.2.8LitePeer.OpSetPropertiesOfGame Method

Attaches or updates properties of the current game.

C#

publicvirtualshortOpSetPropertiesOfGame(Hashtableproperties,boolbroadcast,byte

channelId);


22

3


28/58

Parameters


Hashtable properties hashtable containing the properties to add or overwrite

bool broadcast true will trigger an event LiteEventKey.SetProperties with theupdated properties in it

byte channelId channel 0 or higher

Returns


Description


3.1.4PhotonPeer Class

Instances of the PhotonPeer class are used to connect to a Photon server and communicate with it.

C#

publicclassPhotonPeer;

Remarks

A PhotonPeer instance allows communication with the Photon Server, which in turn distributes messages to other

PhotonPeer clients.

An application can use more than one PhotonPeer instance, which are treated as separate users on the server. Each should

have its own listener instance, to separate the operations, callbacks and events ( see page 3).

Methods

Name DescriptionPhotonPeer ( see page 26) Creates a new PhotonPeer instance to communicate with Photon.


PhotonPeer Delegates

Name Description

GetLocalMsTimestampDelegate ( see page 36) This is nested type PhotonPeer.GetLocalMsTimestampDelegate.

PhotonPeer Fields

Name Description

PhotonPort ( see page 27) The default port used with Photon as string. DotNet and Unity: "5055"."4530" for Silverlight.

3.1 Classes Photon DotNet Client Documentation PhotonPeer Class

23

3


29/58

PhotonPeer Methods

Name Description

Connect ( see page 27) This method does a DNS lookup (if necessary) and connects to the givenserverAddress.

The return value gives you feedback if the address has the correct

format. If so, this starts the process to establish the connection itself,which might take a few seconds.

When the connection is established, a callback toIPhotonPeerListener.PeerStatusCallback ( see page 41)will be done. Ifthe connection can't be established, despite having a valid address, thePeerStatusCallback is called with an error-value.

The appID defines the application logic to use server-side and it shouldmatch the name of one of the apps in your server's config.

By default,... more ( see page 27)

DeriveSharedKey ( see page 28) This method must be called with the OperationResult ofOpExchangeKeysForEncryption ( see page 30)to establish a sharedsecret with the server and enable encryption.


In OperationResult use this code to derive the shared secret: case(byte)LiteOpCode.ExchangeKeysForEncryption://this.DebugReturn("OpExchangeKeysForEncryption ( see page 30)response: " + SupportClass.HashtableToString ( see page38)(returnValues)); if (returnCode == 0)this.peer.DeriveSharedKey((byte[])returnValues[(byte)LiteOpKey.ServerKey]);break;

Disconnect ( see page 28) This method disconnects from the Photon Server which will endcommunication (if any).

Disconnect is also a command on the Server. The callback is a call tonPeerReturn() ( see page 41)with a returnCode ofstatusCode.Disconnect ( see page 48)and an operationCode of

LiteOpCode.Blank ( see page 45). If the client is disconnected alreadyor the connection thread is stopped, then there is no callback.

Disconnecting will also leave the joined game (if any) and trigger therespective event (LiteEventCode.Leave ( see page 43)) for theremaining players.

DispatchIncomingCommands (see page 28)

This method directly causes the callbacks for events ( see page 3),responses and state changes within a IPhotonPeerListener ( see page39). DispatchIncomingCommands only executes a single receivedcommand per call. If a command was dispatched, the return value is trueand the method should be called again. This method is called by Service( see page 31)() until currently available commands are dispatched.

FetchServerTimestamp ( seepage 28)

This will fetch the server's timestamp and update the approximation forproperty ServerTimeInMilliseconds.

The server time approximation will NOT become more accurate byrepeated calls. Accuracy currently depends on a single roundtrip which isdone as fast as possible.

The command used for this is immediately acknowledged by the server.This makes sure the roundtrip time is low and the timestamp +rountriptime / 2 is close to the original value.

OpCustom ( see page 29) Channel-less wrapper for OpCustom().

OpExchangeKeysForEncryption (see page 30)

This method creates a public key for this client and exchanges it with theserver.

Encryption is not instantly available after calling this method. The fetchedserver's public-key is provided by callback to OperationResult. SeeDeriveSharedKey ( see page 28)how to go on after this operation.


24

3


30/58

SendOutgoingCommands ( seepage 30)

This method creates a UDP/TCP package for outgoing commands(operations and acknowledgements) and sends them to the server. Thismethod is also called by Service ( see page 31)().

Service ( see page 31) This method excutes the internal send- and dispatch-processes in thecontext/thread of an application.

StopThread ( see page 31) This method immediately closes a connection (pure client side). If the

connections was open, this will trigger a disconnect callback toPeerStatusCallback() with a returnCode of statusCode.Disconnect ( seepage 48)and an operationCode of LiteOpCode.Blank ( see page 45).

PhotonPeer Properties

Name Description

BytesIn ( see page 31) Count of all bytes coming in (including headers, excluding UDP/TCPoverhead)

BytesOut ( see page 32) Count of all bytes going out (including headers, excluding UDP/TCPoverhead)

ChannelCount ( see page 32) Gets / sets the number of channels available in UDP connections withPhoton. Photon Channels are only supported for UDP. The defaultChannelCount is 2.

CommandBufferSize ( see page32)


DebugOut ( see page 32) Sets the level of debug output which is returned by the library (inDebugReturn ( see page 40)).

Use the PhotonPeer.DebugLevel ( see page 43)enumeration. Default:Error.

debugTimeForDeriveSharedKey (see page 32)

(Temporary property) Count of milliseconds that deriving the shared keytook. Available after OpExchangeKeysForEncryption ( see page 30)and DeriveSharedKey ( see page 28)was called.

debugTimeForDiffieHellman ( seepage 32)

(Temporary property) Count of milliseconds that the Diffie Hellmanalgorithm needed to create the keys and provide a byte array of those.Available after a call to OpExchangeKeysForEncryption ( see page 30).

DisconnectTimeout ( see page 33) Milliseconds after which a reliable UDP command triggers a timeoutdisconnect, unless acknowledged by server. This value currently onlyaffects UDP connections. The actual timeout might happen later,depending on the connection. Commands that are sent while having abad roundtrip time and variance are checked less often for re-sending!

DisconnectTimeout and SentCountAllowance ( see page 34)arecompeting settings: either might trigger a disconnect on the client first,depending on the values and Rountrip Time. Default: 10000 ms.

IsEncryptionAvailable ( see page33)

This property is set by OpExchangeKeysForEncryption ( see page 30)()and DeriveSharedKey ( see page 28)(). While it's true, encryption canbe used for operations.

Listener ( see page 33) Gets the IPhotonPeerListener ( see page 39)of this instance (set inconstructor). Can be used in derived classes for Listener.DebugReturn().

LocalMsTimestampDelegate ( seepage 33) This setter for a timestamp delegate which then replaces the defaultEnvironment.TickCount with any equal function.

LocalTimeInMilliSeconds ( seepage 33)

Gets a local timestamp in milliseconds by calling theGetLocalMsTimestampDelegate ( see page 36). SeeLocalMsTimestampDelegate ( see page 33).

PeerID ( see page 33) This peer's ID as assigned by the server or 0 if not using UDP. Will be0xFFFF before the client connects.

PeerState ( see page 34) This is the (low level) state of the connection to the server of aPhotonPeer. It is managed internally and read-only.

QueuedIncomingCommands (see page 34)

Returns the sum of all currently received but not-yet-Dispatched reliablecommands (events ( see page 3)and operation results) from allchannels.

QueuedOutgoingCommands (

see page 34)

Sum of all commands currently queued as outgoing, including all

channels and reliable, unreliable.


25

3


31/58

RoundTripTime ( see page 34) Time until a reliable command is acknowledged by the server.

The value measures network latency and for UDP it includes the server'sACK-delay (setting in config). In TCP, there is no ACK-delay, so thevalue is slightly lower (if you use default settings for Photon).

RoundTripTime is updated constantly. Every reliable command willcontribute a fraction to this value.

This is also the approximate time until a raised event reaches anotherclient or until an operation result is available.

RoundTripTimeVariance ( seepage 34)

Changes of the roundtriptime as variance value. Gives a hint about howmuch the time is changing.

SentCountAllowance ( see page34)

Number of send retries before a peer is considered lost/disconnected.Default: 5. The initial timeout countdown of a command is calculated bythe current roundTripTime + 4 * roundTripTimeVariance. Please note thatthe timeout span until a command will be resent is not constant, butbased on the roundtrip time at the initial sending, which will be doubledwith every failed retry.

DisconnectTimeout ( see page 33)and SentCountAllowance arecompeting settings: either might trigger a disconnect on the client first,depending on the values and Rountrip Time.

ServerAddress ( see page 35) The server address which was used in PhotonPeer.Connect ( seepage 27)() or null (before Connect ( see page 27)() was called).

ServerTimeInMilliSeconds ( seepage 35)


TimePingInterval ( see page 35) Sets the milliseconds without reliable command before a ping command(reliable) will be sent (Default: 1000ms). The ping command is used tokeep track of the connection in case the client does not send reliablecommands by itself. A ping (or reliable commands) will update theRoundTripTime ( see page 34)calculation.

UseCommandActionQueue ( seepage 35)


UsedProtocol ( see page 36) The protocol this Peer uses to connect to Photon.

WarningSize ( see page 36) The WarningSize allows the PhotonPeer class to test each individual

queue for congestion (in and out, reliable and unreliable). If there aremore commands than WarningSize in a queue, PhotonPeer will call thePhotonPeerListener.PeerStatusCallback() callback with a respectiveStatusCode ( see page 48).

3.1.4.1PhotonPeer Constructor

3.1.4.1.1PhotonPeer.PhotonPeer Constructor (IPhotonPeerListener)

Creates a new PhotonPeer instance to communicate with Photon.


C#

publicPhotonPeer(IPhotonPeerListenerlistener);

Parameters


IPhotonPeerListener listener a IPhotonPeerListener ( see page 39)implementation

3.1.4.1.2PhotonPeer.PhotonPeer Constructor (IPhotonPeerListener,ConnectionProtocol)

Creates a new PhotonPeer instance to communicate with Photon and selects either UDP or TCP as protocol. We


26

3


32/58

recommend UDP.

C#

publicPhotonPeer(IPhotonPeerListenerlistener, ConnectionProtocolprotocolType);

Parameters


IPhotonPeerListener listener a IPhotonPeerListener ( see page 39)implementation

ConnectionProtocol protocolType Protocol to use to connect to Photon.

3.1.4.1.3PhotonPeer.PhotonPeer Constructor (IPhotonPeerListener, bool)

Deprecated. Please use: PhotonPeer(IPhotonPeerListener ( see page 39) listener, ConnectionProtocol ( see page 43)

protocolType).

C#

publicPhotonPeer(IPhotonPeerListenerlistener,booluseTcp);

3.1.4.2PhotonPeer Fields

3.1.4.2.1PhotonPeer.PhotonPort Field

The default port used with Photon as string. DotNet and Unity: "5055". "4530" for Silverlight.

C#

publicstaticreadonlystringPhotonPort= "4530";

3.1.4.3PhotonPeer Methods

3.1.4.3.1PhotonPeer.Connect Method

This method does a DNS lookup (if necessary) and connects to the given serverAddress.

The return value gives you feedback if the address has the correct format. If so, this starts the process to establish the

connection itself, which might take a few seconds.

When the connection is established, a callback to IPhotonPeerListener.PeerStatusCallback ( see page 41)will be done. If

the connection can't be established, despite having a valid address, the PeerStatusCallback is called with an error-value.

The appID defines the application logic to use server-side and it should match the name of one of the apps in your server's

config.

By default, the appId / name is "Lite" but other samples use "LiteLobby" and "MmoDemo" in Connect(). You can setup yourown application and name it any way you like.

C#

publicvirtualboolConnect(String serverAddress, String appID);

Parameters


String serverAddress Address of the Photon server. Format: ip:port (e.g.127.0.0.1:5055) or hostname:port (e.g. localhost:5055)

String appID The name of the application to use within Photon. Thisshould match a "Name" for an application, which are setup inyour server's config.


27

3


33/58

Returns

true if IP is available (DNS name is resolved) and server is being connected. false on error.

3.1.4.3.2PhotonPeer.DeriveSharedKey Method

This method must be called with the OperationResult of OpExchangeKeysForEncryption ( see page 30) to establish a

shared secret with the server and enable encryption.


In OperationResult use this code to derive the shared secret: case (byte)LiteOpCode.ExchangeKeysForEncryption:

//this.DebugReturn("OpExchangeKeysForEncryption ( see page 30)response: " + SupportClass.HashtableToString ( see

page 38)(returnValues)); if (returnCode == 0) this.peer.DeriveSharedKey((byte[])returnValues[(byte)LiteOpKey.ServerKey]);

break;

C#

publicvoidDeriveSharedKey(byte[] serverPublicKey);

Parameters


byte[] serverPublicKey

3.1.4.3.3PhotonPeer.Disconnect Method

This method disconnects from the Photon Server which will end communication (if any).

Disconnect is also a command on the Server. The callback is a call to nPeerReturn() ( see page 41)with a returnCode of

statusCode.Disconnect ( see page 48) and an operationCode of LiteOpCode.Blank ( see page 45). If the client is

disconnected already or the connection thread is stopped, then there is no callback.

Disconnecting will also leave the joined game (if any) and trigger the respective event (LiteEventCode.Leave ( see page

43)) for the remaining players.

C#

publicvirtualvoidDisconnect();

3.1.4.3.4PhotonPeer.DispatchIncomingCommands Method

This method directly causes the callbacks for events ( see page 3), responses and state changes within a

IPhotonPeerListener ( see page 39). DispatchIncomingCommands only executes a single received command per call. If a

command was dispatched, the return value is true and the method should be called again. This method is called by Service

( see page 31)() until currently available commands are dispatched.

C#

publicvirtualboolDispatchIncomingCommands();

Remarks

In general, this method should be called until it returns false. In a few cases, it might make sense to pause dispatching (if a

certain state is reached and the app needs to load data, before it should handle new events ( see page 3)).

The callbacks to the peer's IPhotonPeerListener ( see page 39) are executed in the same thread that is calling

DispatchIncomingCommands. This makes things easier in a game loop: Event ( see page 3)execution won't clash with

painting objects or the game logic.

3.1.4.3.5PhotonPeer.FetchServerTimestamp Method

This will fetch the server's timestamp and update the approximation for property ServerTimeInMilliseconds.


28

3


34/58

The server time approximation will NOT become more accurate by repeated calls. Accuracy currently depends on a single

roundtrip which is done as fast as possible.

The command used for this is immediately acknowledged by the server. This makes sure the roundtrip time is low and the

timestamp + rountriptime / 2 is close to the original value.

C#

publicvirtualvoidFetchServerTimestamp();

3.1.4.3.6OpCustom Method

3.1.4.3.6.1PhotonPeer.OpCustom Method (byte, Hashtable, bool)

Channel-less wrapper for OpCustom().

C#

publicvirtualshortOpCustom(bytecustomOpCode, HashtablecustomOpParameters,bool

sendReliable);

Parameters


byte customOpCode

Hashtable customOpParameters

bool sendReliable

Returns


3.1.4.3.6.2PhotonPeer.OpCustom Method (byte, Hashtable, bool, byte)

Allows the client to send any operation to the Photon Server by setting any opCode and the operation's parameters. Photon

can be extended with new operations which are identified by a single byte, defined server side and known as operation code(opCode). Similarly, the operation's parameters are defined server side as byte keys of values, which a client sends as

customOpParameters accordingly.

This is explained in more detail as "Custom Operations ( see page 2)".

C#

publicvirtualshortOpCustom(bytecustomOpCode, HashtablecustomOpParameters,bool

sendReliable,bytechannelId);

Parameters


byte customOpCode Operations ( see page 2)are handled by their byte-typedcode. The codes of the "Lite" application are in the structLiteOpCode ( see page 45).

Hashtable customOpParameters A Hashtable ( see page 11)containing parameters askey-value pair. The key is byte-typed, while the value is anyserializable datatype.

bool sendReliable Selects if the operation must be acknowledged or not. Iffalse, the operation is not guaranteed to reach the server.

byte channelId The channel in which this operation should be sent.

Returns



29

3


35/58

3.1.4.3.6.3PhotonPeer.OpCustom Method (byte, Hashtable, bool, byte, bool)

Variant of OpCustom with encryption parameter. To be used after OpExchangeKeysForEncryption ( see page 30) and

DeriveSharedKey ( see page 28).

C#

publicvirtualshortOpCustom(bytecustomOpCode, HashtablecustomOpParameters,boolsendReliable,bytechannelId,boolencrypt);

Parameters


byte customOpCode Operations ( see page 2)are handled by their byte-typedcode. The codes of the "Lite" application are in the structLiteOpCode ( see page 45).

Hashtable customOpParameters A Hashtable ( see page 11)containing parameters askey-value pair. The key is byte-typed, while the value is anyserializable datatype.

bool sendReliable Selects if the operation must be acknowledged or not. Iffalse, the operation is not guaranteed to reach the server.

byte channelId The channel in which this operation should be sent.

bool encrypt Can only be true, while IsEncryptionAvailable ( see page33)is true, too.

3.1.4.3.7PhotonPeer.OpExchangeKeysForEncryption Method

This method creates a public key for this client and exchanges it with the server.

Encryption is not instantly available after calling this method. The fetched server's public-key is provided by callback to

OperationResult. See DeriveSharedKey ( see page 28)how to go on after this operation.

C#

publicshortOpExchangeKeysForEncryption();

Returns

Invocation ID or -1 if it failed (not connected).

Remarks

This method must be called before the "encrypt" parameter of OpCustom ( see page 29)can be used. When you call this

method, the property IsEncryptionAvailable ( see page 33)becomes false.

3.1.4.3.8PhotonPeer.SendOutgoingCommands Method

This method creates a UDP/TCP package for outgoing commands (operations and acknowledgements) and sends them to

the server. This method is also called by Service ( see page 31)().

C#

publicvirtualvoidSendOutgoingCommands();

Remarks

As the Photon library does not create any UDP/TCP packages by itself. Instead, the application fully controls how many

packages are sent and when. A tradeoff, an application will lose connection, if it is no longer calling

SendOutgoingCommands or Service ( see page 31).

If multiple operations and ACKs are waiting to be sent, they will be aggregated into one package. The package fills in this

order: ACKs for received commands A "Ping" - only if no reliable data was sent for a while Starting with the lowest

Channel-Nr: Reliable Commands in channel Unreliable Commands in channel

This gives a higher priority to lower channels.


30

3


36/58

A longer interval between sends will lower the overhead per sent operation but increase the internal delay (which adds "lag").

Call this 2..20 times per second (depending on your target platform).

3.1.4.3.9PhotonPeer.Service Method

This method excutes the internal send- and dispatch-processes in the context/thread of an application.

C#

publicvirtualvoidService();

Remarks

The Photon client libraries are designed to fit easily into a game or application. The application is in control of the context

(thread) in which incoming events ( see page 3) and responses are executed and has full control of the creation of

UDP/TCP packages.

Sending packages and dispatching received messages are two separate tasks. Service combines them into one method at

the cost of control. It calls DispatchIncomingCommands ( see page 28)and SendOutgoingCommands ( see page 30).

Call this method regularly (2..20 times a second).

This will Dispatch ANY remaining buffered responses and events ( see page 3) AND will send queued outgoing

commands. Fewer calls might be more effective if a device cannot send many packets per second, as multiple operations

might be combined into one package.

See Also

PhotonPeer.DispatchIncomingCommands ( see page 28), PhotonPeer.SendOutgoingCommands ( see page 30)

Example

You could replace Service by:

while (DispatchIncomingCommands ( see page 28)()); //Dispatch until everything is Dispatched...

SendOutgoingCommands ( see page 30)(); //Send a UDP/TCP package with outgoing messages

3.1.4.3.10PhotonPeer.StopThread Method

This method immediately closes a connection (pure client side). If the connections was open, this will trigger a disconnect

callback to PeerStatusCallback() with a returnCode of statusCode.Disconnect ( see page 48) and an operationCode of

LiteOpCode.Blank ( see page 45).

C#

publicvirtualvoidStopThread();

Todo

change description to include the closing of the connection! alternative: use disconnect

3.1.4.4PhotonPeer Properties

3.1.4.4.1PhotonPeer.BytesIn Property

Count of all bytes coming in (including headers, excluding UDP/TCP overhead)

C#

publiclongBytesIn;


31

3


37/58

3.1.4.4.2PhotonPeer.BytesOut Property

Count of all bytes going out (including headers, excluding UDP/TCP overhead)

C#

publiclongBytesOut;

3.1.4.4.3PhotonPeer.ChannelCount Property

Gets / sets the number of channels available in UDP connections with Photon. Photon Channels are only supported for

UDP. The default ChannelCount is 2.

C#

publicbyteChannelCount;

3.1.4.4.4PhotonPeer.CommandBufferSize Property

C#

publicintCommandBufferSize;

Description


3.1.4.4.5PhotonPeer.DebugOut Property

Sets the level of debug output which is returned by the library (in DebugReturn ( see page 40)).

Use the PhotonPeer.DebugLevel ( see page 43)enumeration. Default: Error.

C#

publicDebugLevelDebugOut;

3.1.4.4.6PhotonPeer.debugTimeForDeriveSharedKey Property

(Temporary property) Count of milliseconds that deriving the shared key took. Available after

OpExchangeKeysForEncryption ( see page 30)and DeriveSharedKey ( see page 28)was called.

C#

publicintdebugTimeForDeriveSharedKey;

Remarks

This temporary property might be removed in upcoming SDK releases.

3.1.4.4.7PhotonPeer.debugTimeForDiffieHellman Property

(Temporary property) Count of milliseconds that the Diffie Hellman algorithm needed to create the keys and provide a byte

array of those. Available after a call to OpExchangeKeysForEncryption ( see page 30).

C#

publicintdebugTimeForDiffieHellman;

Remarks

This temporary property might be removed in upcoming SDK releases.


32

3


38/58


39/58

C#

publicushortPeerID;

Remarks

Used for debugging only. This value is not useful in everyday Photon usage.

3.1.4.4.14PhotonPeer.PeerState Property

This is the (low level) state of the connection to the server of a PhotonPeer ( see page 23). It is managed internally and

read-only.

C#

publicPeerStateValuePeerState;

Remarks

Don't mix this up with the StatusCode ( see page 48) provided in IPhotonListener.PeerStatusCallback(). Applications

should use the StatusCode ( see page 48)of PeerStatusCallback() to track their state, as it also covers the higher level

initialization between a client and Photon.

3.1.4.4.15PhotonPeer.QueuedIncomingCommands Property

Returns the sum of all currently received but not-yet-Dispatched reliable commands (events ( see page 3) and operation

results) from all channels.

C#

publicintQueuedIncomingCommands;

3.1.4.4.16PhotonPeer.QueuedOutgoingCommands Property

Sum of all commands currently queued as outgoing, including all channels and reliable, unreliable.

C#

publicintQueuedOutgoingCommands;

3.1.4.4.17PhotonPeer.RoundTripTime Property

Time until a reliable command is acknowledged by the server.

The value measures network latency and for UDP it includes the server's ACK-delay (setting in config). In TCP, there is no

ACK-delay, so the value is slightly lower (if you use default settings for Photon).

RoundTripTime is updated constantly. Every reliable command will contribute a fraction to this value.

This is also the approximate time until a raised event reaches another client or until an operation result is available.

C#

publicintRoundTripTime;

3.1.4.4.18PhotonPeer.RoundTripTimeVariance Property

Changes of the roundtriptime as variance value. Gives a hint about how much the time is changing.

C#

publicintRoundTripTimeVariance;

3.1.4.4.19PhotonPeer.SentCountAllowance Property

Number of send retries before a peer is considered lost/disconnected. Default: 5. The initial timeout countdown of a


34

3


40/58

command is calculated by the current roundTripTime + 4 * roundTripTimeVariance. Please note that the timeout span until a

command will be resent is not constant, but based on the roundtrip time at the initial sending, which will be doubled with

every failed retry.

DisconnectTimeout ( see page 33)and SentCountAllowance are competing settings: either might trigger a disconnect on

the client first, depending on the values and Rountrip Time.

C#

publicintSentCountAllowance;

3.1.4.4.20PhotonPeer.ServerAddress Property

The server address which was used in PhotonPeer.Connect ( see page 27)() or null (before Connect ( see page 27)()

was called).

C#

publicstringServerAddress;

3.1.4.4.21PhotonPeer.ServerTimeInMilliSeconds Property


C#

publicintServerTimeInMilliSeconds;

Description

0 until connected. While connected, the value is an approximation of the server's current timestamp.

Remarks

UDP: The server's timestamp is automatically fetched after connecting (once). This is done internally by a command which is

acknowledged immediately by the server. TCP: The server's timestamp fetched with each ping but set only after connecting

(once).

The approximation will be off by +/- 10ms in most cases. Per peer/client and connection, the offset will be constant (unless

FetchServerTimestamp ( see page 28)() is used). A constant offset should be better to adjust for. Unfortunately there is no

way to find out how much the local value differs from the original.

The approximation adds RoundtripTime / 2 and uses this.LocalTimeInMilliSeconds ( see page 33)to calculate in-between

values (this property returns a new value per tick).

The value sent by Photon equals Environment.TickCount in the logic layer (e.g. Lite).

3.1.4.4.22PhotonPeer.TimePingInterval Property

Sets the milliseconds without reliable command before a ping command (reliable) will be sent (Default: 1000ms). The ping

command is used to keep track of the connection in case the client does not send reliable commands by itself. A ping (or

reliable commands) will update the RoundTripTime ( see page 34)calculation.

C#

publicintTimePingInterval;

3.1.4.4.23PhotonPeer.UseCommandActionQueue Property

C#

publicboolUseCommandActionQueue;

Description



35

3


41/58

3.1.4.4.24PhotonPeer.UsedProtocol Property

The protocol this Peer uses to connect to Photon.

C#

publicConnectionProtocolUsedProtocol;

3.1.4.4.25PhotonPeer.WarningSize Property

The WarningSize allows the PhotonPeer ( see page 23)class to test each individual queue for congestion (in and out,

reliable and unreliable). If there are more commands than WarningSize in a queue, PhotonPeer ( see page 23)will call the

PhotonPeerListener.PeerStatusCallback() callback with a respective StatusCode ( see page 48).

C#

publicintWarningSize;

3.1.4.5PhotonPeer Delegates

3.1.4.5.1PhotonPeer.GetLocalMsTimestampDelegate Delegate

C#

publicdelegateintGetLocalMsTimestampDelegate();

Description

This is nested type PhotonPeer.GetLocalMsTimestampDelegate.

3.1.5SupportClass ClassContains conversion support elements such as classes, interfaces and static methods.

C#

publicclassSupportClass;

SupportClass Classes

Name Description

ThreadSafeRandom ( see page37)

Class to wrap static access to the random.Next ( see page 37)() call ina thread safe manner.

SupportClass Methods

Name Description

ByteArrayToString ( see page 37) Converts a byte-array to string (for debuggin output).

DeserializeData ( see page 37) Reversion function of SerializeData ( see page 39)to restore theHashtable ( see page 11)of serialized data.

HashtableToString ( see page 38) This method returns a string, representing the content of the givenhashtable. Returns null, if the parameter was null.

NumberToByteArray ( see page38)

Inserts the number's value into the byte array, using Big-Endian order(a.k.a. Network-byte-order).

SerializeData ( see page 39) Uses the internal serialization methods to create a byte-array from thedata supplied.

WriteStackTrace ( see page 39) Writes the exception's stack trace to the received stream.

3.1 Classes Photon DotNet Client Documentation SupportClass Class

36

3


42/58

3.1.5.1SupportClass Classes

3.1.5.1.1SupportClass.ThreadSafeRandom Class

Class to wrap static access to the random.Next ( see page 37)() call in a thread safe manner.

C#

publicclassThreadSafeRandom;

ThreadSafeRandom Methods

Name Description

Next ( see page 37) This is Next, a member of class ThreadSafeRandom.

3.1.5.1.1.1ThreadSafeRandom Methods

3.1.5.1.1.1.1SupportClass.ThreadSafeRandom.Next MethodC#

publicstaticintNext();

Description

This is Next, a member of class ThreadSafeRandom.

3.1.5.2SupportClass Methods

3.1.5.2.1SupportClass.ByteArrayToString Method

Converts a byte-array to string (for deb

photon dotnet client documentation v6 2 0

Documents