Realtime API

Overview

RealtimeCore::Matchmaking::RealtimeClient (header RealtimeCore/Matchmaking/RealtimeClient.h) manages the Photon connection, rooms and matchmaking underneath FusionCore::Client. This page is a slim reference for the surface a Fusion Core integration uses. The complete Realtime API — lobbies, random matchmaking, player properties, friends, statistics, transport tuning — is documented in the Realtime Core documentation. For the narrative connection guide and examples, see Connection and Matchmaking.

RealtimeClient is non-copyable and non-movable.

Construction

C++

RealtimeCore::Matchmaking::ClientConstructOptions options;
options.AppId      = PHOTON_STR("your-app-id");
options.AppVersion = PHOTON_STR("1.0");

RealtimeCore::Matchmaking::RealtimeClient client{options};

ClientConstructOptions fields:

Field	Type	Default	Purpose
`AppId`	`StringType`	--	Photon application ID from the Dashboard
`AppVersion`	`StringType`	--	Client version for room isolation
`Protocol`	`ConnectionProtocol`	`Default`	UDP or TCP
`UseAlternativePorts`	`bool`	`false`	Use alternative port range
`RegionSelection`	`RegionSelectionMode`	`Default`	How the region is chosen
`AutoLobbyStats`	`bool`	`false`	Auto-request lobby statistics
`DisconnectTimeoutMs`	`optional<int>`	--	Override disconnect timeout
`PingIntervalMs`	`optional<int>`	--	Override ping interval
`EnableCrc`	`optional<bool>`	--	CRC checking
`SentCountAllowance`	`optional<int>`	--	Outgoing command buffer
`QuickResendAttempts`	`optional<uint8_t>`	--	Fast retransmit count
`LimitOfUnreliableCommands`	`optional<int>`	--	Unreliable queue cap

Runtime setters exist for the transport tunables (SetDisconnectTimeout, SetPingInterval, SetSentCountAllowance, SetQuickResendAttempts) — see Configuration.

Service Loop

The client processes network I/O only when serviced:

Method	Behavior
`void Service(bool dispatchIncomingCommands = true)`	Full pump: receive, dispatch, send. Call once per frame while not running Fusion.
`void ServiceBasic()`	Minimal keep-alive pump.
`bool SendOutgoingCommands()`	Flush the outgoing queue only.
`bool SendAcksOnly()`	Send pending acks only.
`bool DispatchIncomingCommands()`	Dispatch received commands only.

While Fusion is running, Client::UpdateFrameBegin() services the realtime client internally — see Frame Loop.

Connection

Method	Returns
`Connect()` / `Connect(ConnectOptions options)`	`Task<Result<void>>`
`Disconnect()`	`Task<Result<void>>`
`Reconnect()`	`Task<Result<void>>`
`AvailableRegions()`	`Task<Result<std::vector<RegionInfo>>>`
`SelectRegion(StringViewType region)`	`Task<Result<void>>`
`GetBestRegion()`	`StringType`

ConnectOptions fields are documented in Connection and Matchmaking; regions in Connection and Regions.

Connection State

C++

enum class ConnectionState : uint8_t {
    Disconnected, Connecting, Connected,
    JoiningRoom, InRoom, LeavingRoom, Disconnecting
};

Query	Returns
`GetState()`	`ConnectionState`
`IsConnected()`	`bool`
`IsInRoom()`	`bool`
`IsInLobby()`	`bool`
`GetDisconnectCause()`	`DisconnectCause` — values in Errors and Disconnects

Rooms

Room operations take their options by value and return Task<Result<MutableRoomView>> unless noted:

Method	Behavior
`CreateRoom(name = {}, CreateRoomOptions = {})`	Create a new room. Fails if the name exists.
`JoinRoom(name, JoinRoomOptions = {})`	Join an existing room by name.
`JoinOrCreateRoom(name, CreateRoomOptions = {}, JoinRoomOptions = {})`	Join if it exists, otherwise create.
`JoinRandomRoom(MatchmakingOptions = {})`	Random matchmaking — see Lobbies and Matchmaking.
`JoinRandomOrCreateRoom(CreateRoomOptions = {}, MatchmakingOptions = {})`	Random join with create fallback.
`LeaveRoom(bool willComeBack = false)`	Leave the current room. Returns `Task<Result<void>>`.
`GetCurrentRoom()`	`std::optional<MutableRoomView>`.

CreateRoomOptions essentials for Fusion:

Field	Type	Default
`MaxPlayers`	`uint8_t`	`0` (unlimited)
`IsVisible`	`bool`	`true`
`IsOpen`	`bool`	`true`
`CustomProperties`	`RealtimeMap`	`{}`
`Plugins`	`vector<StringType>`	`{}` — leave empty; see the plugin note

The remaining fields (LobbyProperties, LobbyName, Lobby, PlayerTtlMs, EmptyRoomTtlMs, SuppressRoomEvents, PublishUserId, DirectMessaging, ExpectedUsers) and the JoinRoomOptions / MatchmakingOptions structs are documented in Rooms and Players and Lobbies and Matchmaking.

MutableRoomView

The essentials:

Member	Behavior
`GetName()`	Room name.
`GetPlayerCount()` / `GetMaxPlayers()`	Occupancy.
`GetCustomProperties()`	`const RealtimeMap&` — includes the reserved `fusion_*` properties.
`GetPlayers()`	`const std::vector<PlayerView>&`.
`GetMasterClientId()` / `IsMasterClient()`	Master client info.
`GetPlugins()`	Plugins bound to the room.
`SetOpen(bool)` / `SetVisible(bool)` / `SetMaxPlayers(uint8_t)`	Mutations; return `bool`.
`SetProperties(const RealtimeMap&)` / `SetProperty<T>(key, value)`	Write custom properties; return `bool`.

Full surface (TTLs, expected users, lobby properties, master-client transfer, CAS writes): Rooms and Players.

RealtimeValue and RealtimeMap

RealtimeValue is a variant over every type the Photon wire protocol carries, and the value type of room and player custom properties (header RealtimeCore/Matchmaking/RealtimeValue.h). Type() returns the ValueType currently held; Is<T>(), TryGet<T>() and Get<T>() read the alternative, and TryGetNumber<T>() yields a std::optional<T> filled only when the stored number converts without loss.

RealtimeMap is the insertion-ordered key-value container that holds custom properties. Keys are a RealtimeKey — a variant over uint8_t, int16_t, int32_t, int64_t, float, double and StringType — but custom properties are string-keyed on the wire, so the property setters reject a map holding any non-string key.

Member	Behavior
`Set(key, value)`	Insert the entry, or replace the value of an existing key.
`TryGet(key)`	A `const RealtimeValue*`, or `nullptr` when the key is absent.
`Remove(key)` / `Contains(key)`	Remove an entry, or test for one.
`Size()` / `IsEmpty()`	The entry count.
`KeyAt(index)` / `ValueAt(index)`	Positional access in insertion order.

The full alternative list, the RealtimeArray / RealtimeDictionary / RealtimeCustom containers and the conversion rules are documented in Data Types.

Result and Task

All async operations return Task<Result<T>> (headers RealtimeCore/Common/Result.h, RealtimeCore/Common/Task.h, aliased into RealtimeCore::Matchmaking).

Result<T> essentials:

Member	Behavior
`IsOk()` / `IsErr()` / `explicit operator bool()`	Status.
`GetValue()`	The value; asserts when called on an error. Ref-qualified (`&`, `const&`, `&&`).
`GetError()`	`const Error<CodeT>&` with `Code` and `Message` fields; asserts on ok.
`GetErrorCode()`	The code, or `Ok` when the result holds a value.
`operator->()`	Access members of the value directly.
`Transform(f)` / `AndThen(f)` / `OrElse(f)` / `TransformError(f)`	Monadic composition.

Task<T> essentials:

Member	Behavior
`co_await task`	Suspends until completion; the normal consumption path.
`IsReady()`	`true` once the operation has finished.
`Get()`	Moves the result out. Does not block — calling it before `IsReady()` is undefined behavior.
`Transform` / `AndThen` / `OrElse` / `TransformError`	Monadic composition (`&&`-qualified).

Task<T> has no default constructor and is move-only; create it where the operation starts (e.g. hold a std::optional<Task<T>> for polling patterns). Task<void> has no Get() — check IsReady(). Full guide: Asynchronous Operations.

Broadcasters

Broadcaster<Sig>::Subscribe(callback) returns a Subscription token. Subscription is not RAII — store it in a ScopedSubscription or SubscriptionBag to unsubscribe automatically.

The broadcasters most Fusion integrations use:

Broadcaster	Signature
`OnDisconnected`	`void(DisconnectCause)`
`OnError`	`void(ErrorCode, StringViewType)`
`OnRoomJoined`	`void()`
`OnRoomLeft`	`void()`
`OnPlayerJoined`	`void(const PlayerView&)`
`OnPlayerLeft`	`void(int playerNumber, bool isInactive)`
`OnMasterClientChanged`	`void(int newId, int oldId)`

Also available: OnRoomPropertiesChanged, OnPlayerPropertiesChanged, OnRoomListUpdated, OnLobbyStats, OnCustomAuthStep, OnAppStatsUpdated, OnWarning, OnPropertiesChangeFailed, OnCacheSliceChanged, OnDirectConnectionEstablished, OnDirectConnectionFailed, OnCustomOperationResponse, OnDirectMessage — see Client Callbacks.

Connection and Matchmaking -- Narrative guide and examples
Frame Loop -- Service integration with the Fusion frame sequence
Client API -- FusionCore::Client reference
Realtime Core documentation -- Complete Realtime API

Overview
Construction
Service Loop
Connection

Connection State

Rooms

MutableRoomView

RealtimeValue and RealtimeMap
Result and Task
Broadcasters
Related