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

ObjectId

Unique identifier for a networked object, composed of a player origin, map index and sequential counter.

C++

struct ObjectId {
    static constexpr size_t WordSize = 2;

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

    ObjectId() = default;
    ObjectId(PlayerId origin, Map map, uint32_t counter);
    explicit ObjectId(const uint64_t &packed);

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

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

    operator PhotonCommon::StringType() const;
    operator uint64_t() const;
};

static_assert(sizeof(ObjectId) == 8);

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).
Counter	uint32_t	4	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()	Convert to UTF-8 string representation.
operator uint64_t()	Pack into a 64-bit value (Origin in low 16, Map in next 16, Counter in high 32).

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
MasterClientPlayerId	0xFFFF	Targets the current master client.
PluginPlayerId	0xFFFE	Server plugin actor.
ObjectOwnerPlayerId	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.

EMAReport

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

C++

struct EMAReport {
    double TotalAvg;
    double TotalAvgPerSecond;
    double CurrentAvgPerSecond;
    double Min;
    double Max;
};

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.
Max	double	Maximum sample value observed.

Enums

ObjectOwnerModes

Ownership model for a networked object.

Value	Code	Description
Transaction	0	Ownership transferred via explicit request.
PlayerAttached	1	Owned by a specific player for its lifetime.
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 OnPredictionOverride.

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.

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.

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.

Send Flag Constants

Per-packet flags written into Object::SendFlags.

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_InternalMinId	1	Start of internal RPC range.
RPC_InternalMaxId	1023	End of internal RPC range.
RPC_InternalMapChange	1	Map change RPC. Replaces the older RPC_InternalSceneChange.
RPC_InternalObjectPriority	2	Object priority update RPC.
RPC_InternalMapAdd	3	Map add RPC.
RPC_InternalMapRemove	4	Map remove RPC.
RPC_InternalOwnershipRequest	5	Ownership request issued by a non-owner; surfaces as OnOwnershipRequest.
RPC_InternalRejectSubObject	6	Server rejected a sub-object creation.
RPC_InternalDestroyedMapActors	7	Carries the list of map actors destroyed before the receiver joined.
RPC_InternalForceDestroyObject	8	Server-initiated forced destroy.
RPC_InternalForceAliveObject	9	Server-initiated forced alive (recover slot).
RPC_InternalInput	10	Predicted-player input frame.
RPC_InternalPlayerInterest	11	Player interest-key delta.
RPC_InternalOwnershipResponse	12	Reply to RPC_InternalOwnershipRequest; 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 a HasFlag helper.

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);

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);
template<typename T> uint64_t CRC64(uint64_t crc, T data);

Compute a CRC-64 hash.
The seeded overloads continue hashing from a previous CRC value.
Template overloads hash any trivially-copyable value directly.

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.

String Formatting

C++

std::string stringf(const char *format, ...);

Printf-style string formatting returning a std::string.

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.

String Conventions

The SDK uses char8_t (UTF-8) throughout:

C++

namespace PhotonCommon {
    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