Module core.PhotonPeer
Instances of the PhotonPeer class are used to connect to a Photon server and communicate with it.
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.
Functions
-
new ()
-
Creates instance of PhotonPeer.
-
instance:getResentReliableCommands ()
-
Count of commands that got repeated (due to local repeat-timing before an ACK was received).
-
instance:addPeerStatusListener (statusCode, callback)
-
Registers mListener for peer status change.
Parameters:
- statusCode
StatusCode
Status change to this value will be listening.
- callback
function
The listener function that processes the status change. This function don't accept Object parameters.
-
instance:addPhotonEventListener (eventCode, callback)
-
Registers mListener for custom event.
Parameters:
- eventCode
byte
Custom event code.
- callback
function
The listener function that processes the event. This function may accept object with event content.
-
instance:addResponseListener (operationCode, callback)
-
Registers mListener for operation response.
Parameters:
- operationCode
byte
Operation code.
- callback
function
The listener function that processes the event. This function may accept object with operation response content.
-
instance:sendOperation (code, data, sendReliable, channelId, encrypt)
-
Sends operation to the Photon Server.
Parameters:
- code
number
Code of operation.
- data
table
Parameters of operation as key-value pairs.
- sendReliable
boolean
Selects if the operation must be acknowledged or not. If false, the operation is not guaranteed to reach the server. Default is true.
- channelId
number
The logical channel. Default is 0.
- encrypt
boolean
true = encrypt message; false = no encryption. Default is false.
-
instance:setLogLevel (level)
-
Sets peer logger level.
Parameters:
-
instance:onUnhandledEvent (eventData)
-
Called if no listener found for received custom event.
Override to relay unknown event to user's code or handle known events without listener registration.
Parameters:
-
instance:onUnhandledResponse (operationResponse)
-
Called if no listener found for received operation response event.
Override to relay unknown response to user's code or handle known responses without listener registration.
Parameters:
-
instance:service (dispatchIncomingCommands)
-
Executes the PhotonPeer internal processes. Call this regularly!
This function is meant to be called frequently, like once per gameloop. It handles the internal calls for keeping the PhotonPeer communication alive, and will take care of sending all
local outgoing acknowledgements and messages, as well as dispatching incoming messages to the application, firing the corresponding callbacks. Internally service() calls the
following functions:
1. serviceBasic()
2. dispatchIncomingCommands() (called withing a loop until all incoming commands have been dispatched.)
3. sendOutgoingCommands()
service() is provided for convenience. If you need to tweak the performance, you can ignore service() and call its three subfunctions directly with individual time
intervals, to gain more control over the internal communication process. For instance, calling sendOutgoingCommands() more rarely will result in less
packets to be generated, as more commands will be accumulated into a single packet.
For situations where you want to keep the connection alive, but can't process incoming messages (e.g. when loading ingame data), you can temporarily pass false for dispatchIncomingCommands parameter
to skip the calls to dispatchIncomingCommands(). Incoming commands will be store in the incoming queue until they are dispatched again.
Parameters:
-
instance:serviceBasic ()
-
Takes care of exchanging data with the system's network layer. Measures roundtrip time.
You only need to call this function in case you choose not to use service(), but call the subfunctions of service() directly.
serviceBasic() is called from within service(). If you decide not to use service(), then serviceBasic() needs to be called frequently, like once per game loop.
Roundtrip time precision is defined by period of time between subsequent serviceBasic() calls.
see also:
-
instance:dispatchIncomingCommands ()
-
Checks for incoming commands waiting in the queue, and dispatches a single command to the application.
Dispatching means, that if the command is an operation response or an event, the callback function will be called.
dispatchIncomingCommands() will also take care of generating and queuing acknowledgments for incoming reliable commands. Please note that this function will only dispatch one command per
all. If you want to dispatch every single command which is waiting in the queue, call dispatchIncomingCommands() within a while loop, until its return code is false.
While service() is calling serviceBasic() implicitly, you will have to regularly call it yourself explictly, when you use sendOutgoingCommands() and dispatchIncomingCommands() directly
instead.
Returns:
boolean
true if it has successfully dispatched a command, false otherwise (for example, when there has not been any command left in the queue, waiting for dispatching).
see also:
-
instance:sendOutgoingCommands ()
-
Initiates the transmission of outgoing commands.
Any Photon function that generates messages will store these messages as a "command" in an outgoing queue for later transmission. Commands can either be explicitly created operations
generated for example by sendOperation() or internally generated messages like acknowledgements for reliable messages from other players. sendOutgoingCommands()
will initiate the data transmission by passing the outgoing commands to the system's sockets for immediate transmission.
In case of UDP sendOutgoingCommands() will also split the commands into multiple packets if needed and/of aggregate multiple commands together into one packet, if possible. Because of the
latter calling sendOutgoingCommands() more rarely will result in less overhead, as there will be fewer packets for the clients to be sent and processed. The underlying platform can also
limit the frequency in which outgoing packets can be sent and received. The downside of lower sending frequencies is a higher latency, until messages are exchanged and acknowledged, which
may lead to a jerky gameplay.
While service() is calling serviceBasic() implicitly, you will have to regularly call it yourself explictly , when you use sendOutgoingCommands() and dispatchIncomingCommands() directly
instead.
Usually you don't have to call sendOutgoingCommands() this explicitly, as this is done within service().
see also:
-
instance:getRoundTripTime ()
-
Returns the time in milliseconds until a reliable command is acknowledged by the server.
This is, what is commonly called a ping time or just a ping.
Measurement precision depends on serviceBasic() call frequency.
Returns:
number
Roundtrip time in milliseconds.
see also:
-
instance:getRoundTripTimeVariance ()
-
Returns the variance of the roundtrip time in milliseconds.
Gives a hint about how much the net latency is varying.
Returns:
number
Variance of the roundtrip time in milliseconds.
see also:
-
instance:setTrafficStatsEnabled (enabled)
-
Enables or disables the traffic statistics of a peer. Stats are disabled by default.
Parameters:
- enabled
bool
True to enable.
see also:
-
instance:getTrafficStatsEnabled ()
-
Returns true if traffic statistics of a peer is enabled.
Returns:
bool
True if enabled.
-
instance:getTrafficStatsEnabledTime ()
-
Returns the count of seconds the stats are enabled for tracking.
Returns:
number
Seconds.
-
instance:resetTrafficStats ()
-
Clears all stats and disables stats if enabled
-
instance:resetTrafficStatsMaximumCounters ()
-
Resets traffic stats values that can be maxed out.
Tables
-
StatusCodes
-
Enum for peer status codes.
Use to subscribe to status changes.
Fields:
- Connecting
Is connecting to server.
- Connect
Connected to server.
- Disconnect
Disconnected from server.
- EncryptionEstablished
Encryption established.
- Error
General connection error.
- ConnectFailed
Connection to server failed.
- ConnectClosed
Connection closed by server.
- Timeout
Disconnected from server for timeout.
- EncryptionEstablishError
Encryption establishing error.
Fields
-
self.trafficStatsIncoming
-
(table) Statistic of incoming "low level" messages, which are either Enet Commands or Tcp Messages. These include all headers, except those of the underlying internet protocol Udp or Tcp.
-
self.trafficStatsOutgoing
-
(table) Statistic of outgoing "low level" messages, which are either Enet Commands or Tcp Messages. These include all headers, except those of the underlying internet protocol Udp or Tcp.
-
self.trafficStatsGameLevel
-
(table) Statistic of incoming and outgoing traffic, split by operation, operation-result and event. Operations are outgoing traffic, results and events are incoming. Includes the per-command header sizes (Udp: Enet Command Header or Tcp: Message Header).