Data Types

RealtimeValue

A value is anything the Photon wire protocol carries. Values are both the self-describing payload form of custom events and the value type of room and player custom properties. The Structured Payloads page covers event usage and Custom Properties covers property usage.

In C++ a value is a RealtimeValue, a variant over every wire type, declared in RealtimeValue.h. In JavaScript a value is a plain JavaScript value: the package infers its wire type, or takes it from a helper such as byte(); see Values.

None of the types on this page cross the C API as objects. RealtimeValue, Player, RoomListing, LobbyStats, RegionInfo and FriendInfo each have a documented byte layout instead; see The Blob Format. In JavaScript every structured type on this page is a plain object with the same fields in camelCase.

ValueType names the wire type of a value. In C++ Type() returns it for the alternative a RealtimeValue holds; JavaScript exports the same names and numbers as ValueType. The JavaScript column shows what to send for each wire type and, where it differs, what a read returns.

ValueType	C++ type	JavaScript
Null	std::monostate	null; undefined also sends null
Bool	bool	boolean
Byte	uint8_t	byte(n); reads as a number
Int16	int16_t	int16(n); reads as a number
Int32	int32_t	An integer number within 32 bits, or int32(n)
Int64	int64_t	A bigint, or int64(n); reads as a bigint
Float	float	float(n); reads as a number
Double	double	Any other number, or double(n)
String	StringType	string
ByteArray	std::vector<uint8_t>	Uint8Array
Int16Array	std::vector<int16_t>	Int16Array
Int32Array	std::vector<int32_t>	Int32Array
Int64Array	std::vector<int64_t>	BigInt64Array
FloatArray	std::vector<float>	Float32Array
DoubleArray	std::vector<double>	Float64Array
BoolArray	std::vector<bool>	bools([...]); reads as an array of booleans
StringArray	std::vector<StringType>	strings([...]); reads as an array of strings
Array	RealtimeArray	Array
Map	RealtimeMap	A plain object for string keys, a Map for any other keys
Dictionary	RealtimeDictionary	dictionary(keyType, entries); reads as a Map
Custom	RealtimeCustom	custom(code, bytes); reads as a CustomValue

The C++ RealtimeValue has the following members:

C++ Member	Description
Type()	The ValueType currently held.
IsNull()	true for a Null value.
Is<T>()	Whether the value holds exactly T.
TryGet<T>()	A const T*, or nullptr when the value does not hold T.
Get<T>()	A const T&; asserts on a type mismatch and falls back to a default-constructed T when assertions are off.
TryGetNumber<T>()	A std::optional<T>, filled only when the stored number converts to T without loss.
TryGetCustom<T>()	A std::optional<T> decoded from a Custom value whose code equals T::TypeCode.
Visit(visitor)	Calls the visitor with the alternative currently held.
Raw()	The underlying std::variant.

In C++ equality compares type and value, so RealtimeValue(42) does not equal RealtimeValue(int64_t{42}).

A JavaScript value carries no wire type of its own: inspect a received value with typeof, Array.isArray() and instanceof. Integer width is not preserved on read, so a byte(5) that was sent reads back as 5.

RealtimeArray, RealtimeMap and RealtimeDictionary

RealtimeArray is std::vector<RealtimeValue>, a heterogeneous list.

RealtimeMap is an insertion-ordered key-value container, used both for nested map payloads and for room and player custom properties. Keys are a RealtimeKey, a std::variant over uint8_t, int16_t, int32_t, int64_t, float, double and StringType, and one map may mix key types. Custom properties are the exception: they are string-keyed on the wire, so the property setters reject a map holding any non-string key.

C++ Member	Description
Set(key, value)	Inserts the entry, or replaces the value of an existing key.
TryGet(key)	A const RealtimeValue*, or nullptr when the key is absent.
Remove(key)	Removes the entry and reports whether it existed.
Contains(key)	Whether the key is present.
Size() / IsEmpty()	The entry count.
KeyAt(index) / ValueAt(index)	Positional access in insertion order.

RealtimeDictionary is the same container with a single key type, fixed at construction by a RealtimeDictionary::Key (Byte, Int16, Int32, Int64, Float, Double, String). KeyType() reports it, and its Set() returns bool, false when the offered key is of another type. The authentication flow uses it with Key::String, for the AuthenticationValues::Data payload and the OnCustomAuthStep parameters, because both travel as string-keyed dictionaries.

RealtimeEntry is the {Key, Value} pair accepted by the initializer-list constructors of both containers.

JavaScript uses its own collections in place of these three containers. A RealtimeArray is an Array, and a RealtimeMap is a plain object when every key is a string and a Map otherwise. A RealtimeDictionary is written with dictionary(keyType, entries), where keyType is 'byte', 'int16', 'int32', 'int64', 'float', 'double' or 'string', and reads back as a Map. Custom properties are a plain object with string keys, and the customAuthStep event delivers its data as a plain object of strings.

RealtimeCustom

RealtimeCustom is the Custom alternative of RealtimeValue: a wire code plus the serialized bytes of an application type.

C++ Field	C++ Type	Description
Code	uint8_t	The custom type code. Valid codes are 1 through 254.
Data	std::vector<uint8_t>	The serialized value, at most 32767 bytes.

Application types are plugged in through the CustomValueType concept, which requires a static constexpr uint8_t TypeCode, a void SerializeValue(std::vector<uint8_t>& out) const and a static std::optional<T> DeserializeValue(std::span<const uint8_t> bytes). Any type satisfying it converts to a RealtimeValue implicitly and is read back with TryGetCustom<T>().

In JavaScript a custom value is a CustomValue with a code and its data as a Uint8Array; send one with custom(code, bytes). JavaScript has no counterpart of CustomValueType, so serialize the application type into the bytes yourself.

Player

Player is a read-only snapshot of one player in the room, obtained from the room's player list, the local player or the player-joined callback. In C++ these are GetPlayers(), GetLocalPlayer() and OnPlayerJoined. In JavaScript they are room.players, room.getPlayer(), client.localPlayer and the playerJoined event, and a player is { number, name, userId, customProperties, isInactive, isMasterClient } with customProperties as a plain object.

C++ Field	C++ Type	Description
Number	int	The player number, unique and positive within the room.
Name	StringType	The player's display name.
UserId	StringType	The player's user id; only populated when the room publishes user ids.
CustomProperties	RealtimeMap	The player's custom properties.
IsInactive	bool	true while the player has left but may still rejoin within the room's player TTL.
IsMasterClient	bool	true for the room's current master client.

RoomListing

RoomListing describes one lobby-visible room as delivered by an explicit room list request, the cached room list and the room-list callback. In C++ these are GetRoomList(), GetCachedRoomList() and OnRoomListUpdated. In JavaScript they are getRoomList(), client.cachedRoomList and the roomListUpdated event, and a listing is { name, playerCount, maxPlayers, isOpen, directMessaging, customProperties } with directMessaging as a DirectMode name.

C++ Field	C++ Type	Description
Name	StringType	The room name.
PlayerCount	int	The number of players currently in the room.
MaxPlayers	uint8_t	The room's player limit; 0 means unlimited.
IsOpen	bool	Whether the room currently accepts joins.
DirectMessaging	DirectMode	The room's direct messaging mode.
CustomProperties	RealtimeMap	The room's lobby-visible custom properties, limited to the keys listed in LobbyProperties.

RegionInfo

RegionInfo is one entry of the region list returned by AvailableRegions() in C++ and availableRegions() in JavaScript, where it is { code, server }.

C++ Field	C++ Type	Description
Code	StringType	The region code, for example eu or us.
Server	StringType	The address of the region's master server.

LobbyStats

LobbyStats is one entry of the statistics list returned by an explicit request and delivered by the lobby-statistics callback. In C++ these are GetLobbyStats() and OnLobbyStats. In JavaScript they are getLobbyStats() and the lobbyStats event, and an entry is { name, type, peerCount, roomCount } with type as a LobbyType name.

C++ Field	C++ Type	Description
Name	StringType	The lobby name; empty for the default lobby.
Type	LobbyType	The lobby type.
PeerCount	int	The number of players associated with this lobby and its rooms.
RoomCount	int	The number of rooms listed in this lobby.

FriendInfo

FriendInfo is one entry of the friend list returned by a friend lookup and cached on the client. In C++ these are FindFriends() and GetFriendList(). In JavaScript they are findFriends() and client.friendList, and an entry is { userId, isOnline, roomName, isInRoom }.

C++ Field	C++ Type	Description
UserId	StringType	The friend's user id, as passed to FindFriends().
IsOnline	bool	Whether the friend is currently connected.
RoomName	StringType	The name of the room the friend is in; empty when not in a room.
IsInRoom	bool	Whether the friend is currently in a room.

AuthenticationValues

AuthenticationValues is the credential bundle passed when connecting, as ConnectOptions.Auth in C++ and as the auth option of connect() in JavaScript; the provider flows are described on the Authentication page. In JavaScript it is { userId, type, parameters, data }: type is a CustomAuthenticationType name, 'none' by default, and data is a Uint8Array, a string or a plain object.

C++ Field	C++ Type	Description
UserId	StringType	The user id; the server assigns a random one when left empty.
Type	CustomAuthenticationType	The authentication provider; None by default.
Parameters	StringType	Query-string style parameters forwarded to the authentication provider.
Data	std::variant<std::monostate, std::vector<uint8_t>, StringType, RealtimeDictionary>	Optional payload posted to the authentication provider: empty, raw bytes, a string or a string-keyed dictionary. The wire format is a string-keyed dictionary, so a RealtimeDictionary whose key type is not Key::String sends no data.

NetworkStats

NetworkStats is the connection-quality snapshot returned by GetStats() in C++ and client.stats in JavaScript; the Statistics page explains how to interpret it. In JavaScript the fields have the same names in camelCase, such as roundTripTimeMs: masterServerAddress is a string, encryptionAvailable and payloadEncryptionAvailable are booleans and every other field is a number.

C++ Field	C++ Type	Description
RoundTripTimeMs	int	The current round-trip time in milliseconds.
RttVarianceMs	int	The variance of the round-trip time in milliseconds.
BytesIn	int	Total bytes received.
BytesOut	int	Total bytes sent.
BytesCurrentDispatch	int	Size in bytes of the command currently being dispatched.
BytesLastOperation	int	Size in bytes of the last operation sent.
QueuedIncomingCommands	int	Incoming commands waiting to be dispatched.
QueuedOutgoingCommands	int	Outgoing commands waiting to be sent.
IncomingReliableCommands	int	Reliable commands currently queued incoming.
ResentReliableCommands	int	Reliable commands that had to be resent.
PlayersInGame	int	Players currently in rooms of this application; updated with OnAppStatsUpdated.
GamesRunning	int	Rooms currently running in this application; updated with OnAppStatsUpdated.
PlayersOnline	int	Players currently connected to this application; updated with OnAppStatsUpdated.
ServerTimeOffsetMs	int	The offset between the local clock and the server time in milliseconds.
ServerTimeMs	int	The estimated current server time in milliseconds; the same value GetServerTime() returns.
TimestampLastReceive	int	Local timestamp of the most recently received data.
PacketLossByCrc	int	Packets discarded due to CRC checksum failures.
SentCountAllowance	int	The current resend allowance for reliable commands.
EncryptionAvailable	bool	Whether transport encryption is established.
PayloadEncryptionAvailable	bool	Whether payload encryption is available.
PeerId	short	The peer id the server assigned to this client.
DisconnectTimeoutMs	int	The current disconnect timeout setting in milliseconds.
PingIntervalMs	int	The current keep-alive ping interval in milliseconds.
TrafficStatsElapsedMs	int	Milliseconds since traffic statistics were enabled or reset.
MasterServerAddress	StringType	The address of the master server the client uses.
ChannelCountUserChannels	int	The number of user channels available for sequencing.
PeerCount	short	The number of client peer instances running in this process.

TrafficStats

TrafficStats breaks traffic down by command class, one instance per direction. It is returned by GetTrafficStatsIncoming() and GetTrafficStatsOutgoing() in C++, and by client.trafficStatsIncoming and client.trafficStatsOutgoing in JavaScript, with the same fields in camelCase, all numbers.

C++ Field	C++ Type	Description
PackageHeaderSize	int	Protocol header bytes counted per packet.
ReliableCommandCount	int	Number of reliable commands.
UnreliableCommandCount	int	Number of unreliable commands.
FragmentCommandCount	int	Number of fragment commands of large messages.
ControlCommandCount	int	Number of protocol control commands.
TotalPacketCount	int	Number of packets.
TotalCommandsInPackets	int	Number of commands across all packets.
ReliableCommandBytes	int	Bytes in reliable commands.
UnreliableCommandBytes	int	Bytes in unreliable commands.
FragmentCommandBytes	int	Bytes in fragment commands.
ControlCommandBytes	int	Bytes in protocol control commands.
TotalCommandCount	int	Number of commands of all classes.
TotalCommandBytes	int	Bytes in commands of all classes.
TotalPacketBytes	int	Bytes in packets, including protocol headers.
TimestampOfLastAck	int	Local timestamp of the most recent acknowledgement.
TimestampOfLastReliableCommand	int	Local timestamp of the most recent reliable command.

TrafficStatsGameLevel

TrafficStatsGameLevel counts traffic at the operation and event level and tracks the longest callback and pump-gap timings. It is returned by GetTrafficStatsGameLevel() in C++, and by client.trafficStatsGameLevel in JavaScript, with the same fields in camelCase, all numbers.

C++ Field	C++ Type	Description
OperationByteCount	int	Bytes in operations sent.
OperationCount	int	Number of operations sent.
ResultByteCount	int	Bytes in operation responses received.
ResultCount	int	Number of operation responses received.
EventByteCount	int	Bytes in events received.
EventCount	int	Number of events received.
LongestOpResponseCallbackMs	int	Longest time an operation-response callback took, in milliseconds.
LongestOpResponseCallbackOpCode	uint8_t	Operation code of that longest operation-response callback.
LongestEventCallbackMs	int	Longest time an event callback took, in milliseconds.
LongestEventCallbackCode	uint8_t	Event code of that longest event callback.
LongestDeltaBetweenDispatchingMs	int	Longest gap between two dispatch calls, in milliseconds.
LongestDeltaBetweenSendingMs	int	Longest gap between two send calls, in milliseconds.
DispatchIncomingCommandsCalls	int	Number of dispatch calls.
SendOutgoingCommandsCalls	int	Number of send calls.
TotalByteCount	int	Bytes in both directions combined.
TotalMessageCount	int	Messages in both directions combined.
TotalIncomingByteCount	int	Bytes received.
TotalIncomingMessageCount	int	Messages received.
TotalOutgoingByteCount	int	Bytes sent.
TotalOutgoingMessageCount	int	Messages sent.

Last updated on 27/10/2026

Back to top