Class IRealtimeEngine

• Defined in File IRealtimeEngine.h

Inheritance Relationships

Derived Types

• public csp::multiplayer::OfflineRealtimeEngine (Class OfflineRealtimeEngine)

• public csp::multiplayer::OnlineRealtimeEngine (Class OnlineRealtimeEngine)

Class Documentation

class IRealtimeEngine

Interface abstraction of a CSP Realtime Engine.

A Realtime engine is the CSP component responsible for driving the realtime behaviour of a connected space, primarily by responding to user input and managing updates to entities within the space.

Most users will use the OnlineMultiUserRealtimeEngine implementation to support online experiences. However, other implementations exist for alternate use cases, such as OnlineSingleUserRealtimeEngine for single-user flows inside an online space.

A RealtimeEngine should be created before entering a space, and provided to the EnterSpace call. Users are responsible for deleting RealtimeEngines, CSP does not claim ownership. RealtimeEngines must not be deleted whilst users are in space, wait until the user has exited a space before performing cleanup.

Important

This type is not a true interface, instead throwing default implementations. This is due to wrapper generator constraints, hopefully temporary ones.

Note

Terminology:

• Entity: All items in a space are entities.

• Avatar: A specialization of Entity representing an avatar. Defined by whether the entity contains an AvatarSpaceComponent.

• Object: An entity that is not an avatar. Defined by that entity not containing an AvatarSpaceComponent.

Subclassed by csp::multiplayer::OfflineRealtimeEngine, csp::multiplayer::OnlineRealtimeEngine

Public Functions

virtual ~IRealtimeEngine() = default

Virtual destructor.

inline virtual RealtimeEngineType GetRealtimeEngineType() const

Returns the concrete type of the instantiation of the abstract IRealtimeEngine.

inline virtual void CreateAvatar(const csp::common::String &Name, const csp::common::String &UserId, const csp::multiplayer::SpaceTransform &SpaceTransform, bool IsVisible, csp::multiplayer::AvatarState AvatarState, const csp::common::String &AvatarId, csp::multiplayer::AvatarPlayMode AvatarPlayMode, csp::multiplayer::EntityCreatedCallback Callback)

Create and add a SpaceEntity with type Avatar, and relevant components and default states as specified.

Parameters

• Name – csp::common::String : The entity name of the newly created avatar entity.

• UserId – csp::common::String : Id of the user creating this avatar. If your backend data store requires authentication, this will probably be your username or some similar unique identifier.

• SpaceTransform – csp::multiplayer::SpaceTransform : The initial transform to set the SpaceEntity to.

• IsVisible – bool : Whether the avatar defaults to being visible.

• AvatarState – csp::multiplayer::AvatarState : The initial Avatar State to set.

• AvatarId – csp::common::String : The ID to be set on the AvatarSpaceComponent

• AvatarPlayMode – csp::multiplayer::AvatarPlayMode : The Initial AvatarPlayMode to set.

• Callback – csp::multiplayer::EntityCreatedCallback A callback that executes when the creation is complete, which will provide a non-owning pointer to the new SpaceEntity so that it can be used on the local client.

inline virtual void CreateEntity(const csp::common::String &Name, const csp::multiplayer::SpaceTransform &SpaceTransform, const csp::common::Optional<uint64_t> &ParentID, csp::multiplayer::EntityCreatedCallback Callback)

Create and add a SpaceEntity, with relevant default values.

Parameters

• Name – csp::common::String : The name of the newly created SpaceEntity.

• SpaceTransform – csp::multiplayer::SpaceTransform : The initial transform to set the SpaceEntity to.

• ParentID – csp::common::Optional<uint64_t> : ID of another entity in the space that this entity should be created as a child to. If empty, entity is created as a root entity.

• Callback – csp::multiplayer::EntityCreatedCallback : A callback that executes when the creation is complete, which will provide a non-owning pointer to the new SpaceEntity so that it can be used on the local client.

inline virtual void DestroyEntity(csp::multiplayer::SpaceEntity *Entity, csp::multiplayer::CallbackHandler Callback)

Destroy the specified entity.

Parameters

• Entity – csp::multiplayer::SpaceEntity : A non-owning pointer to the entity to be destroyed.

• Callback – csp::multiplayer::CallbackHandler : A callback that executes when the entity destruction is complete.

inline virtual bool AddEntityToSelectedEntities(csp::multiplayer::SpaceEntity *Entity)

Adds an entity to the set of selected entities.

Parameters

Entity – csp::multiplayer::SpaceEntity* Entity to set as selected

Returns

True if the entity was succesfully added, false otherwise. Refer to your specific IRealtimeEngine instantiation for specific failure cases.

inline virtual bool RemoveEntityFromSelectedEntities(csp::multiplayer::SpaceEntity *Entity)

Removes an entity to the set of selected entities.

Parameters

Entity – csp::multiplayer::SpaceEntity* Entity to set as selected

Returns

True if the entity was succesfully removed, false otherwise. Refer to your specific IRealtimeEngine instantiation for specific failure cases.

inline virtual void FetchAllEntitiesAndPopulateBuffers(const csp::common::String &SpaceId, EntityFetchStartedCallback FetchStartedCallback)

Fetch space entities from the RealtimeEngine data source and perform initial setup to populate internal buffers.

This method is called during csp::systems::SpaceSystem::Enterspace.

Parameters

• SpaceId – const csp::common::String& : The identifier of the space to fetch entities from. Format depends on how your specific backend store indexes spaces.

• FetchStartedCallback – EntityFetchStartedCallback : Callback notifying for when csp::systems::SpaceSystem::EnterSpace can yield control back to clients

Post

FetchStartedCallback will have been called, and the EntityFetchCompleteCallback the engine was constructed with will either have been called, or an async job started with an intent to call it once fetch is complete.

inline virtual csp::multiplayer::SpaceEntity *FindSpaceEntity(const csp::common::String &Name)

Finds the first found SpaceEntity of a matching Name.

Parameters

Name – csp::common::String : The name to search.

Returns

A non-owning pointer to the first found matching SpaceEntity.

inline virtual csp::multiplayer::SpaceEntity *FindSpaceEntityById(uint64_t EntityId)

Finds the first found SpaceEntity that has the ID EntityId.

Parameters

EntityId – uint64_t : The Id to look for.

Returns

A non-owning pointer to the first found matching SpaceEntity.

inline virtual csp::multiplayer::SpaceEntity *FindSpaceAvatar(const csp::common::String &Name)

Finds the first found SpaceEntity of a matching Name.

The found SpaceEntity will contain an AvatarSpaceComponent.

Parameters

Name – The name to search for.

Returns

A pointer to the first found matching SpaceEntity.

inline virtual csp::multiplayer::SpaceEntity *FindSpaceObject(const csp::common::String &Name)

Finds the first found SpaceEntity of a matching Name.

The found SpaceEntity will not contain an AvatarSpaceComponent.

Parameters

Name – The name to search for.

Returns

A pointer to the first found matching SpaceEntity.

inline virtual csp::multiplayer::SpaceEntity *GetEntityByIndex(size_t EntityIndex)

Get an Entity by its index.

Parameters

EntityIndex – size_t : The index of the entity to get.

Returns

A non-owning pointer to the entity at the given index.

inline virtual csp::multiplayer::SpaceEntity *GetAvatarByIndex(size_t AvatarIndex)

Get an Avatar by its index.

The returned pointer will be an entity that contains an AvatarSpaceComponent.

Parameters

AvatarIndex – size_t : The index of the avatar entity to get.

Returns

A non-owning pointer to the avatar entity with the given index.

inline virtual csp::multiplayer::SpaceEntity *GetObjectByIndex(size_t ObjectIndex)

Get an Object by its index.

The returned pointer will be an entity that does not contain an AvatarSpaceComponent.

Parameters

ObjectIndex – size_t : The index of the object entity to get.

Returns

A non-owning pointer to the object entity with the given index.

inline virtual const csp::common::List<csp::multiplayer::SpaceEntity*> *GetAllEntities() const

Return all the entities currently known to the realtime engine.

Warning

This list may be extremely large.

Returns

A non-owning pointer to a List of non-owning pointers to all entities.

inline virtual size_t GetNumEntities() const

Get the number of total entities in the system.

Returns

The total number of entities.

inline virtual size_t GetNumAvatars() const

Get the number of total Avatars in the system.

Avatars are entities that contain AvatarSpaceComponents.

Returns

The total number of Avatar entities.

inline virtual size_t GetNumObjects() const

Get the number of total Objects in the system.

Objects are entities that do not contain AvatarSpaceComponents.

Returns

The total number of object entities.

inline virtual const csp::common::List<csp::multiplayer::SpaceEntity*> *GetRootHierarchyEntities() const

Retrieves all entities that exist at the root level (do not have a parent entity).

Returns

A list of root entities containing non-owning pointers to entities.

inline virtual void ResolveEntityHierarchy(csp::multiplayer::SpaceEntity *Entity)

“Resolves” the entity heirarchy for the given entity, setting all internal parent/child buffers correctly.

This method is called whenever parent/child relationships are changed for a given entity, including when one is first created.

Parameters

Entity – csp::multiplayer::SpaceEntity* : The Entity to resolve

inline void SetEntityFetchCompleteCallback(EntityFetchCompleteCallback Callback)

Set Callback that notifies when the OnlineRealtimeEngine is in a valid state after entering a space, and entity mutation can begin.

Users should not mutate entities before receiving this callback. This callback should be emitted in response to FetchAllEntitiesAndPopulateBuffers completing, either syncronously or asyncronously. This callback must be set prior to entering a space.

Parameters

FetchCompleteCallback – csp::common::EntityFetchCompleteCallback : Callback that notifies when the RealtimeEngine has completed initial entity fetch

inline EntityFetchCompleteCallback GetEntityFetchCompleteCallback() const

inline virtual void LockEntityUpdate()

Lock a mutex that guards against any changes to the entity list.

If the mutex is already locked, will wait until it is able to acquire the lock. May cause deadlocks.

inline virtual bool TryLockEntityUpdate()

Attempt to lock a mutex that guards against any changes to the entity list.

Returns

Whether the mutex successfully locked. The mutex should fail to lock if already locked in order to avoid deadlocks.

inline virtual void UnlockEntityUpdate()

Unlock a mutex that guards against any changes to the entity list.

inline virtual csp::multiplayer::SpaceEntityStatePatcher *MakeStatePatcher(csp::multiplayer::SpaceEntity &SpaceEntity) const

Create the state patcher to use for space entities created with this engine If your engine does not require a patch workflow, return null.

Parameters

SpaceEntity – cs::multiplayer::SpaceEntity The SpaceEntity to create the patcher for.

Returns

A pointer to a statepatcher, or null. Pointer ownership is transferred to the caller.

Protected Functions

IRealtimeEngine() = default

IRealtimeEngine(const IRealtimeEngine&) = delete

IRealtimeEngine &operator=(const IRealtimeEngine&) = delete

IRealtimeEngine(IRealtimeEngine&&) = delete

IRealtimeEngine &operator=(IRealtimeEngine&&) = delete

Protected Attributes

EntityFetchCompleteCallback EntityFetchCompleteCallback = nullptr