Types API

Overview

Core types, aliases, enums and utility functions shared across the Fusion SDK. All types live in the FusionCore namespace unless noted otherwise.

Headers: Aliases.h, Types.h, Misc.h, EMA.h, ForcedDisconnect.h, FusionRoomProperties.h

ObjectId

Unique identifier for a networked object, composed of a player origin, map index and sequential counter. sizeof(ObjectId) is 16 bytes, so an ObjectId does not fit into a single 64-bit value. Engine bindings that need a map key should key on the full struct (a std::hash specialization is provided).

C++

struct ObjectId {
    static constexpr size_t WORD_SIZE = 4;

    PlayerId Origin{0};
    Map Map{0};
    uint64_t Counter{0};

    ObjectId() = default;
    ObjectId(PlayerId origin, Map map, uint64_t counter);

    bool IsNone() const;
    bool IsSome() const;

    bool operator==(const ObjectId &other) const;
    bool operator!=(const ObjectId &other) const;

    explicit operator RealtimeCore::Common::StringType() const;
};

static_assert(sizeof(ObjectId) == 16);

RealtimeCore::Common::StringType ToStringType(ObjectId id);

Field	Type	Offset	Description
Origin	PlayerId	0	Player who created this object (16 bits).
Map	Map	2	Map index the object belongs to (16 bits, followed by 4 bytes of padding).
Counter	uint64_t	8	Sequential counter unique per (origin, map) pair.

Method	Description
IsNone()	Returns true if Origin, Map and Counter are all 0.
IsSome()	Returns true if any field is non-zero.
operator StringType()	Explicit conversion to a UTF-8 string representation.
ToStringType(id)	Free helper that performs the string conversion.

WORD_SIZE is the number of 32-bit words one ObjectId occupies inside an object's Words buffer (required-object slots) — kept in lockstep with sizeof(ObjectId) by a static_assert.

A std::hash<FusionCore::ObjectId> specialization is provided in Client.h for use in unordered containers.

Type Aliases

Alias	Underlying Type	Description
Tick	uint32_t	Frame/tick counter.
PlayerId	uint16_t	Player identifier. Narrowed from uint32_t in earlier SDKs — code that serialized PlayerId inline must update.
Map	uint16_t	Map index. Multi-map sessions use this to identify which map an object lives in.
Word	int32_t	Single replicated state word (4 bytes).

Special PlayerId Constants

Constant	Value	Description
MASTER_CLIENT_PLAYER_ID	0xFFFF	Targets the current master client.
PLUGIN_PLAYER_ID	0xFFFE	Server plugin actor.
OBJECT_OWNED_PLAYER_ID	0xFFFD	Targets the object's current owner.

TypeRef

Descriptor identifying a networked type by its hash and word count.

C++

struct TypeRef {
    uint64_t Hash;
    uint32_t WordCount;
};

Field	Type	Description
Hash	uint64_t	Crc64 hash of the type name or path.
WordCount	uint32_t	Number of replicated words (excluding tail).

SdkVersion

Version information returned by Client::GetSdkVersion(). Layout-compatible with the 20-byte Packed representation written into the fusion_sdk_version room property.

C++

struct SdkVersion {
    union {
        struct {
            int32_t Major;
            int32_t Minor;
            int32_t Patch;
            int32_t Build;
            int32_t Protocol;
        };
        unsigned char Packed[20];
    };
};

Field	Type	Description
Major	int32_t	Major version number.
Minor	int32_t	Minor version number.
Patch	int32_t	Patch version number.
Build	int32_t	Build number.
Protocol	int32_t	Wire protocol version.
Packed[20]	unsigned char[20]	Byte-level alias of the five 32-bit fields. Use FusionSdkVersionBuilder::ToBase64 to convert into a room property string. See Fusion Room Properties.

EMAReport

Exponential moving average statistics report. Returned by Client::GetSendReport(), Object::GetSendReport() and related methods.

C++

struct EMAReport {
    using TimePoint = std::chrono::steady_clock::time_point;

    double TotalAvg;
    double TotalAvgPerSecond;
    double CurrentAvgPerSecond;
    double Min;
    double Max;
    TimePoint LastUpdatedTime;
};

Field	Type	Description
TotalAvg	double	All-time weighted average of sample values.
TotalAvgPerSecond	double	All-time weighted average rate per second.
CurrentAvgPerSecond	double	Current instantaneous rate per second (decays toward 0 when idle).
Min	double	Minimum sample value observed. Before the first sample this reports std::numeric_limits<double>::max().
Max	double	Maximum sample value observed.
LastUpdatedTime	TimePoint	Steady-clock timestamp of the most recent sample.

Enums

ObjectOwnerModes

Ownership model for a networked object.

Value	Code	Description
Transaction	0	Ownership transferred via explicit request.
PlayerAttached	1	Transferable like Transaction, but the object is destroyed by the server when its owning player leaves the room.
Dynamic	2	Ownership can be claimed by any player.
MasterClient	3	Always owned by the master client.
GameGlobal	4	No owner; globally shared state.
PlayerPredicted	5	Owned authoritatively by the server, predicted client-side from queued inputs (used with SimulationMode::Authority).

ObjectOwnerIntent

Client-side ownership intent for dynamic objects.

Value	Code	Description
DontWantOwner	0	Not requesting ownership.
WantOwner	1	Requesting ownership.

SimulationMode

Top-level simulation model selected by the integration.

Value	Code	Description
Shared	0	Eventually-consistent shared simulation. Every client owns its own objects and writes their state.
Authority	1	Server-authoritative simulation. Predicted clients feed inputs and reconcile against authoritative state via OnPredictionReset.

ObjectType

Discriminator for object hierarchy position.

Value	Code	Description
Base	1	Abstract base (should not appear at runtime).
Child	2	Sub-object attached to a root.
Root	3	Top-level networked entity.

InterestKeyType

Classification of interest keys assigned to objects.

Value	Code	Description
Global	0	Visible to all players.
Area	1	Server-managed spatial interest.
User	2	User-defined interest group.

DestroyModes

Reason why a networked object was destroyed. Defined in Client.h.

Value	Code	Description
Local	0	Destroyed by the local client.
Remote	1	Destroyed by a remote client.
MapChange	2	Destroyed due to a map transition. Replaces the older SceneChange.
Shutdown	3	Destroyed during client shutdown.
RejectedNotOwner	4	Server rejected creation (not owner).
ForceDestroy	5	Force-destroyed by the server.

LogLevel

Bitmask for SDK log filtering. Compose flags with bitwise OR. Defined in Client.h.

Value	Bit	Description
Trace	1 << 0	Verbose trace messages.
Debug	1 << 1	Debug messages.
Info	1 << 2	Informational messages.
Warning	1 << 3	Warnings.
Error	1 << 4	Errors.

Forced Disconnect

Structured reason data delivered with Client::OnForcedDisconnect.

Header: ForcedDisconnect.h

ForcedDisconnectReason

Value	Code	Description
Generic	0	Unspecified server-initiated disconnect.
ProtocolIncompatible	1	Client wire protocol is incompatible with the server.
RoomVersionMismatch	2	Client SDK version does not match the version the room is locked to.

ParsedForcedDisconnect

C++

struct ParsedForcedDisconnect {
    RealtimeCore::Common::StringType Message;
    ForcedDisconnectReason Reason;
};

ParsedForcedDisconnect ParseForcedDisconnectPayload(const void *data, size_t length);

ParseForcedDisconnectPayload decodes a raw forced-disconnect payload into the message text and structured reason. The SDK calls it internally before firing OnForcedDisconnect; it is exposed for integrations that receive the raw payload through other paths.

Send Flag Constants

Per-packet flags for the next outgoing packet, read via Object::GetSendFlags() (the backing field is private).

Constant	Value	Description
OBJECT_SENDFLAG_CREATE	1	Object creation packet.
OBJECT_SENDFLAG_STRINGHEAP_ENTRIES_CHANGE	2	String heap entry metadata changed.
OBJECT_SENDFLAG_STRINGHEAP_DATA_CHANGE	4	String heap data changed.
OBJECT_SENDFLAG_IN_INTEREST_SET	8	Object is in the sender's interest set.
OBJECT_SENDFLAG_IS_SUBOBJECT	16	Packet is for a sub-object.
OBJECT_SENDFLAG_TIMEONLY	32	Time-only update (no state data).

RPC ID Constants

Reserved internal RPC identifier ranges and well-known IDs.

Constant	Value	Description
RPC_INTERNAL_MIN_ID	1	Start of internal RPC range.
RPC_INTERNAL_MAX_ID	1023	End of internal RPC range.
RPC_INTERNAL_MAP_CHANGE	1	Map change RPC. Replaces the older scene-change RPC.
RPC_INTERNAL_OBJECT_PRIORITY	2	Object priority update RPC.
RPC_INTERNAL_MAP_ADD	3	Map add RPC.
RPC_INTERNAL_MAP_REMOVE	4	Map remove RPC.
RPC_INTERNAL_OWNERSHIP_REQUEST	5	Ownership request issued by a non-owner; surfaces as OnOwnershipRequest.
RPC_INTERNAL_REJECT_SUB_OBJECT	6	Server rejected a sub-object creation.
RPC_INTERNAL_DESTROYED_MAP_ACTORS	7	Carries the list of map actors destroyed before the receiver joined.
RPC_INTERNAL_FORCE_DESTROY_OBJECT	8	Server-initiated forced destroy.
RPC_INTERNAL_FORCE_ALIVE_OBJECT	9	Server-initiated forced alive (recover slot).
RPC_INTERNAL_INPUT	10	Predicted-player input frame.
RPC_INTERNAL_PLAYER_INTEREST	11	Player interest-key delta.
RPC_INTERNAL_OWNERSHIP_RESPONSE	12	Reply to RPC_INTERNAL_OWNERSHIP_REQUEST; surfaces as OnOwnershipResponse.

Rpc Class

Represents a remote procedure call message.

C++

class Rpc {
public:
    uint64_t Id{};
    uint64_t Sequence{};
    RpcFlags Flags{RpcFlags::None};
    uint32_t DeliveryAttempts{0};
    PlayerId OriginPlayer{};
    PlayerId TargetPlayer{};
    ObjectId TargetObject{0, 0, 0};
    uint64_t EventHash{0};
    Data Bytes;

    bool IsInternal() const;

    static Rpc Read(ReadBuffer &reader);
    static void Write(WriteBuffer &writer, const Rpc &rpc);
};

Field	Type	Description
Id	uint64_t	RPC identifier (user IDs start at 1024).
Sequence	uint64_t	Per-RPC monotonic sequence assigned by Client::SendUserRpc.
Flags	RpcFlags	Delivery flags / error flags.
DeliveryAttempts	uint32_t	Count of delivery attempts so far. When this exceeds the SDK's threshold the RPC is given up and RpcFlags::MaxDeliveryAttemptsReached is set.
OriginPlayer	PlayerId	Sender player ID.
TargetPlayer	PlayerId	Target player ID (0 = broadcast).
TargetObject	ObjectId	Target object (optional).
EventHash	uint64_t	Crc64 of the event/method name. The older DescriptorTypeHash field has been removed; routing now uses EventHash alone (paired with Id).
Bytes	Data	Serialized payload.

Method	Description
IsInternal()	Returns true if Id is in the internal range [1, 1023].
Read(reader)	Deserialize an Rpc from a buffer.
Write(writer, rpc)	Serialize an Rpc to a buffer.

RpcFlags

Strong-typed enum of delivery and error flags. The older struct RpcFlags { uint32_t _value; } has been replaced by an enum class with bitwise operator overloads and the HasFlag / HasAnyFlag helpers.

C++

enum class RpcFlags : uint32_t {
    None                       = 0,
    ReturnResultOnFailure      = 1 << 0,
    IncorrectTargetForward     = 1 << 1,
    DontReplyWithResult        = 1 << 2,

    PlayerMissing              = 1 << 5,
    ObjectMissing              = 1 << 6,
    MapIncorrect               = 1 << 7,
    MaxDeliveryAttemptsReached = 1 << 8,
    ErrorFlags                 = PlayerMissing | ObjectMissing
                               | MapIncorrect | MaxDeliveryAttemptsReached,
};

RpcFlags operator|(RpcFlags a, RpcFlags b);
RpcFlags &operator|=(RpcFlags &a, RpcFlags b);
bool HasFlag(RpcFlags flags, RpcFlags flag);
bool HasAnyFlag(RpcFlags flags, RpcFlags mask);

HasFlag returns true only when ALL bits of flag are set. Use HasAnyFlag when testing against a multi-bit mask such as ErrorFlags — HasFlag(flags, RpcFlags::ErrorFlags) would require every error bit at once.

Flag	Bit	Description
None	0	No flags set.
ReturnResultOnFailure	1 << 0	Sender wants a failure-result delivered if the RPC cannot reach its target.
IncorrectTargetForward	1 << 1	RPC was forwarded by the server because the original target was wrong.
DontReplyWithResult	1 << 2	Suppress the auto-result reply for this RPC.
PlayerMissing	1 << 5	Error: target player was not in the room.
ObjectMissing	1 << 6	Error: target object was not present.
MapIncorrect	1 << 7	Error: target object's map differs from the sender's expected map.
MaxDeliveryAttemptsReached	1 << 8	Error: DeliveryAttempts exhausted the retry budget.
ErrorFlags	OR of bits 5–8	Mask for any error flag (used by OnRpcError).

Utility Functions

Float Quantization

C++

template<typename T>
int32_t FloatQuantize(T value, int decimals);

template<typename T>
T FloatDequantize(int32_t value, int decimals);

FloatQuantize converts a float or double to a fixed-point integer with decimals decimal places. FloatDequantize reverses the operation.

Useful for bandwidth-efficient position encoding when full float precision is not needed.

Quaternion Compression

C++

template<typename T>
uint32_t QuaternionCompress(T x, T y, T z, T w);

template<typename T>
void QuaternionDecompress(uint32_t buffer, T &outX, T &outY, T &outZ, T &outW);

Compresses a quaternion from 16 bytes (4 floats) to 4 bytes (1 uint32) using smallest-three encoding with 10 bits per component plus a 2-bit largest-axis index. Matches the server-side implementation exactly.

Crc64

C++

uint64_t Crc64(const void *data, size_t length);
uint64_t Crc64(uint64_t crc, const void *data, size_t length);

template<typename T> uint64_t Crc64(T data);               // non-pointer T
template<typename T> uint64_t Crc64(uint64_t crc, T data); // non-pointer T

Compute a CRC-64 hash. The seeded overloads continue hashing from a previous CRC value. Template overloads hash a value's bytes directly and are constrained to non-pointer types.

Used for type identification (TypeRef::Hash), RPC routing (Rpc::EventHash) and general-purpose hashing.

ZigZag Encoding

C++

int64_t ZigZagEncode(int64_t i);
int64_t ZigZagDecode(int64_t i);

Encode and decode signed integers using ZigZag encoding for efficient variable-length representation. Maps negative values to positive values. Used internally by WriteBuffer::LongVar() and ReadBuffer::LongVar().

Clock Quantization

C++

int64_t ClockQuantizeEncode(double clock);
double ClockQuantizeDecode(int64_t clock);

Encode and decode clock timestamps for compact wire representation.

Timer

Monotonic elapsed-time timer.

C++

class Timer {
public:
    void Start();
    bool Running() const;
    double ElapsedSeconds() const;
};

Method	Description
Start()	Start or restart the timer.
Running()	Returns true if the timer has been started.
ElapsedSeconds()	Returns seconds elapsed since Start().

TimerDelta

Monotonic timer that tracks consumable deltas.

C++

class TimerDelta {
public:
    void Start();
    bool Running() const;
    double Peek() const;
    double Consume();
    static TimerDelta StartNew();
};

Method	Description
Start()	Start or restart the timer.
Running()	Returns true if the timer has been started.
Peek()	Returns seconds since last Start/Consume without resetting.
Consume()	Returns seconds since last Start/Consume, then resets.
StartNew()	Create and start a new timer.

LinkList<T>

Intrusive doubly-linked list. Elements must have Prev and Next pointer fields.

C++

template<typename T>
struct LinkList {
    T *Head{nullptr};
    T *Tail{nullptr};
    int Count{0};
};

Method	Signature	Description
AddFirst	void AddFirst(T *item)	Insert at the head.
AddLast	void AddLast(T *item)	Insert at the tail.
AddBefore	void AddBefore(T *item, T *before)	Insert before an existing element.
AddAfter	void AddAfter(T *item, T *after)	Insert after an existing element.
Remove	bool Remove(T *item)	Remove an element. Returns true if found.
RemoveFirst	T *RemoveFirst()	Remove and return the head element.
RemoveLast	T *RemoveLast()	Remove and return the tail element.
TryRemoveFirst	bool TryRemoveFirst(T *&result)	Try to remove the head. Returns false if empty.
TryRemoveLast	bool TryRemoveLast(T *&result)	Try to remove the tail. Returns false if empty.
TryPeekFirst	bool TryPeekFirst(T *&result)	Peek at the head without removing. Returns false if empty.

WordData

Utility struct for sparse state updates.

C++

struct WordData {
    int32_t Offset;
    int32_t Value;
};

Field	Type	Description
Offset	int32_t	Word index in the buffer.
Value	int32_t	Word value.

Fusion Room Properties

Static helpers for building the room custom property values recognized by the Fusion server plugin. Seed these properties when creating a room; Client::Start() reads fusion_config and fusion_map_data off the joined room.

Header: FusionRoomProperties.h

Reserved Property Keys

The keys live in the FusionCore::FusionRoomProperties namespace as RealtimeCore::Common::StringViewType constants.

Constant	Key	Description
CONFIG	fusion_config	JSON string with overrides merged on top of FusionConfigDefaults::JSON when the plugin creates the room. Ignored when the server default AllowConfigOverride is false.
MAP_DATA	fusion_map_data	Base64-encoded byte payload in FusionMapStateBuilder format. Optional — defaults to empty.
SDK_VERSION	fusion_sdk_version	Base64-encoded 20-byte packed SdkVersion. Optional — if absent, the room locks to the first valid client's version via the version handshake.

FusionConfigDefaults

FusionConfigDefaults::JSON is the built-in default Fusion configuration as a StringViewType constant. The plugin uses it when no fusion_config override is supplied; integrations can deserialize, mutate and re-serialize a copy to override specific fields.

FusionMapStateBuilder

Builds the fusion_map_data payload. The wire format matches what the server plugin serializes and what Client::Start() expects.

Function	Signature	Description
Build	std::vector<uint8_t> Build(const std::map<Map, std::vector<uint8_t>> &maps, Map mapCounter = 0)	Serialize an arbitrary map state. Each (Map, bytes) entry becomes one map slot.
Empty	std::vector<uint8_t> Empty()	Bytes for an empty initial state — the global map 0 with no data and the map counter at zero.
BuildBase64	std::string BuildBase64(const std::map<Map, std::vector<uint8_t>> &maps, Map mapCounter = 0)	Build result Base64-encoded, ready for a room custom property.
EmptyBase64	std::string EmptyBase64()	Empty result Base64-encoded.

FusionSdkVersionBuilder

Builds the fusion_sdk_version payload.

Function	Signature	Description
ToBytes	std::vector<uint8_t> ToBytes(const SdkVersion &version)	20-byte packed representation of the supplied version.
ToBase64	std::string ToBase64(const SdkVersion &version)	Packed representation Base64-encoded, ready for a room custom property.

Base64

General Base64 utilities in the FusionCore::Base64 namespace. fusion_map_data and fusion_sdk_version are binary blobs carried as Base64 strings on the Photon wire.

Function	Signature	Description
Encode	std::string Encode(std::span<const uint8_t> bytes)	Encode bytes as a Base64 string (with padding).
Decode	std::vector<uint8_t> Decode(std::string_view input)	Decode a Base64 string. Non-alphabet characters are skipped; = terminates.

C++

using namespace FusionCore;

// Values to seed a new room's custom properties.
auto config = FusionConfigDefaults::JSON;                                  // or JSON with overrides
std::string mapData = FusionMapStateBuilder::EmptyBase64();                // empty initial map state
std::string sdkVersion = FusionSdkVersionBuilder::ToBase64(Client::GetSdkVersion());

String Conventions

The SDK uses char8_t (UTF-8) throughout:

C++

namespace RealtimeCore::Common {
    using CharType = char8_t;
    using StringType = std::u8string;
    using StringViewType = std::u8string_view;
}

#define PHOTON_STR(str) u8##str

All string parameters accept const CharType* or StringViewType. Engine integrations must convert their native string types to UTF-8 before calling SDK functions.

Related

• Architecture -- Fundamental types overview
• Object API -- Object, ObjectRoot, ObjectChild classes
• Buffers API -- ReadBuffer/WriteBuffer serialization
• Client API -- Client methods using these types

Back to top