Class IRealtimeEngine

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 CSP initialization using one of the provided factory functions, and then passed to CSPFoundation::Initialize.

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.

Public Functions

virtual ~IRealtimeEngine() = default

Virtual destructor.

virtual RealtimeEngineType GetRealtimeEngineType() const = 0

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

virtual void CreateAvatar(const csp::common::String &Name, const csp::multiplayer::SpaceTransform &SpaceTransform, const csp::multiplayer::AvatarState &State, const csp::common::String &AvatarId, const csp::multiplayer::AvatarPlayMode &AvatarPlayMode, csp::multiplayer::EntityCreatedCallback Callback) = 0

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

Parameters
virtual void CreateEntity(const csp::common::String &Name, const csp::multiplayer::SpaceTransform &SpaceTransform, csp::multiplayer::EntityCreatedCallback Callback) = 0

Create and add a SpaceEntity, with relevant default values.

Parameters
virtual void DestroyEntity(csp::multiplayer::SpaceEntity *Entity, csp::multiplayer::CallbackHandler Callback) = 0

Destroy the specified entity.

Parameters
virtual void SetEntityCreatedCallback(csp::multiplayer::EntityCreatedCallback Callback) = 0

Sets a callback to be executed when an entity is fully created.

Only one EntityCreatedCallback may be registered, calling this function again will override whatever was previously set.

Parameters

Callback – csp::multiplayer::EntityCreatedCallback : the callback to execute.

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

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.

virtual csp::multiplayer::SpaceEntity *FindSpaceEntityById(uint64_t EntityId) = 0

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.

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

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.

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

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.

virtual csp::multiplayer::SpaceEntity *GetEntityByIndex(size_t EntityIndex) = 0

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.

virtual csp::multiplayer::SpaceEntity *GetAvatarByIndex(size_t AvatarIndex) = 0

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.

virtual csp::multiplayer::SpaceEntity *GetObjectByIndex(size_t ObjectIndex) = 0

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.

virtual size_t GetNumEntities() const = 0

Get the number of total entities in the system.

Returns

The total number of entities.

virtual size_t GetNumAvatars() const = 0

Get the number of total Avatars in the system.

Avatars are entities that contain AvatarSpaceComponents.

Returns

The total number of Avatar entities.

virtual size_t GetNumObjects() const = 0

Get the number of total Objects in the system.

Objects are entities that do not contain AvatarSpaceComponents.

Returns

The total number of object entities.

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

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.

virtual void SetInitialEntitiesRetrievedCallback(csp::multiplayer::CallbackHandler Callback) = 0

Sets a callback to be executed when all existing entities have been retrieved after entering a space.

Parameters

Callback – CallbackHandler : A callback that executes when all existing entities have been retrieved.

virtual void MarkEntityForUpdate(csp::multiplayer::SpaceEntity *Entity) = 0

Adds an entity to a list of entities to be updated when ProcessPendingEntityOperations is called.

From a client perspective, ProcessPendingEntityOperations is normally called via the CSPFoundation::Tick method.

Parameters

Entity – SpaceEntity : A non-owning pointer to the entity to be marked.

virtual void ProcessPendingEntityOperations() = 0

Applies any pending changes to entities that have been marked for update.