Class OnlineRealtimeEngine

Defined in File OnlineRealtimeEngine.h

Inheritance Relationships

Base Type

public csp::common::IRealtimeEngine (Class IRealtimeEngine)

Class Documentation

class OnlineRealtimeEngine : public csp::common::IRealtimeEngine 

Class for creating and managing multiplayer objects known as space entities.

This provides functions to create and manage multiple player avatars and other objects. It manages things like queueing updated entities and triggering tick events. Callbacks can be registered for certain events that occur within the entity system so clients can react appropriately.

Public Types

typedef std::function<void(SpaceEntity*)> EntityCreatedCallback

using SpaceEntityList = csp::common::List<SpaceEntity*>

using SpaceEntityQueue = std::deque<SpaceEntity*>

Public Functions

OnlineRealtimeEngine(MultiplayerConnection &InMultiplayerConnection, csp::common::LogSystem &LogSystem, csp::multiplayer::NetworkEventBus &NetworkEventBus, csp::common::IJSScriptRunner &RemoteScriptRunner)

OnlineRealtimeEngine constructor.

Parameters

InMultiplayerConnection – MultiplayerConnection* : the multiplayer connection to construct the OnlineRealtimeEngine with
LogSystem – csp::common::LogSystem : Logger such that this system can print status and debug output
NetworkEventBus – csp::multiplayer::NetworkEventBus& : Reference the the network event bus, used for leadership election messaging.
RemoteScriptRunner – csp::common::IJSScriptRunner& : Object capable of running a script. Called to execute scripts when the leader election system

~OnlineRealtimeEngine(): OnlineRealtimeEngine destructor.

virtual csp::common::RealtimeEngineType GetRealtimeEngineType() const override: Returns the concrete type of the instantiation of the abstract IRealtimeEngine.

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

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 : The Id of the user creating the avatar. This can be fetched from csp::systems::UserSystem::GetLoginState
SpaceTransform – csp::multiplayer::SpaceTransform : The initial transform to set the SpaceEntity to.
State – 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.

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

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<int64_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.

virtual void AddEntity(SpaceEntity *EntityToAdd) override

Add a new entity to the system.

This can be called at any time from any thread and internally add the entity to a pending list which is then updated in a thread safe manner when ProcessPendingEntityOperations is called from the main thread.

Parameters: EntityToAdd – SpaceEntity : Pointer to the entity to be added.

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

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.

virtual void SetEntityCreatedCallback(csp::multiplayer::EntityCreatedCallback Callback) override

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 bool AddEntityToSelectedEntities(csp::multiplayer::SpaceEntity *Entity) override

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 if the entity already existed in the selection and thus could not be added.

virtual bool RemoveEntityFromSelectedEntities(csp::multiplayer::SpaceEntity *Entity) override

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 if the entity did not exist in the selection and thus could not be removed.

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

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) override

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) override

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) override

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) override

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) override

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) override

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 override

Get the number of total entities in the system.

Returns: The total number of entities.

virtual size_t GetNumAvatars() const override

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 override

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 override

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 MarkEntityForUpdate(csp::multiplayer::SpaceEntity *Entity) override

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() override: Applies any pending changes to entities that have been marked for update.

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

Fetch all entities in the space from MCS.

Uses SignalR to fetch all the entities from MCS and populate the entities buffer. Also refreshes the scopes in the space, (a potentially redundant action that we are trying to remove), this coincidentally restarts the multiplayer connection, although this should be a purely internal implementation detail.

Parameters

SpaceId – const csp::common::String& : MCS formatted SpaceId
FetchStartedCallback – EntityFetchStartedCallback Callback called once scopes are reset and entity fetch has begun.

Pre

Space represented by SpaceId must exist on the configured server endpoint. See csp::systems::SpaceSystem::CreateSpace

Post

FetchStartedCallback will be called. The csp::common::EntityFetchCompleteCallback passed in the constructor will be called async once all the entities are fetched.

void SetScriptLeaderReadyCallback(CallbackHandler Callback)

Sets a callback to be executed when the script system is ready to run scripts.

Parameters: Callback – CallbackHandler : the callback to execute.

void ClaimScriptOwnership(SpaceEntity *Entity) const

Sets the script owner for the given entity to the current client.

Parameters: Entity – SpaceEntity : A pointer to the entity

void EnableLeaderElection(): Enable Leader Election feature.

void DisableLeaderElection(): Disable Leader Election feature.

bool IsLeaderElectionEnabled() const

Check if the Leader Election feature is enabled.

Returns: true if enabled, false otherwise.

uint64_t GetLeaderId() const

Debug helper to get the id of the currently elected script leader.

Returns: The id of the leader.

bool GetEntityPatchRateLimitEnabled() const

Retrieve the state of the patch rate limiter.

If true, patches are limited for each individual entity to a fixed rate.

Returns: True if enabled, false otherwise.

void SetEntityPatchRateLimitEnabled(bool Enabled)

Set the state of the patch rate limiter.

If true, patches are limited for each individual entity to a fixed rate.

This feature is enabled by default and should only be disabled if you are encountering issues.

Parameters

Enabled – : sets if the feature should be enabled or not.

///.. note:: /// If disabling this feature, more requests will be made to Magnopus Connected Services, /// and consequently more patch merges may occur on the server as a result. ///

void RefreshMultiplayerConnectionToEnactScopeChange(csp::common::String SpaceId, std::shared_ptr<async::event_task<std::optional<csp::multiplayer::ErrorCode>>> RefreshMultiplayerContinuationEvent)

“Refreshes” (ie, turns on an off again), the multiplayer connection, in order to refresh scopes.

This shouldn’t be neccesary, we should devote some effort to checking if it still is at some point

Parameters

SpaceId – csp::Common:String& : The Id of the space to refresh
RefreshMultiplayerContinuationEvent – : std::shared_ptr<async::event_task<std::optional<csp::multiplayer::ErrorCode>>> Continuation event that populates an optional error code on failure. Error is empty on success.

bool CheckIfWeShouldRunScriptsLocally() const

Checks whether we should run scripts locally.

Returns: bool

void RunScriptRemotely(int64_t ContextId, const csp::common::String &ScriptText)

Runs the provided script remotely.

Parameters

ContextId – int64_t : the ID of the context on which to run the script
ScriptText – csp::common::String& : the text of the script to run

SpaceEntityQueue *GetPendingAdds()

Getter for the pending adds.

Returns: : SpaceEntityQueue*

MultiplayerConnection *GetMultiplayerConnectionInstance()

Getter for the multiplayer connection instance.

Returns: : MultiplayerConnection*

void TickEntities()

void LockEntityUpdate() const: Locks the entity mutex.

void UnlockEntityUpdate() const: Unlocks the entity mutex.

void QueueEntityUpdate(SpaceEntity *EntityToUpdate): Queues a specific entity to update. Used in SpaceEntity to queue updates via passing the this pointer.

void ResolveEntityHierarchy(SpaceEntity *Entity)

“Resolves” the entity heirarchy, such that the entity is parented appropriately, and internal buffers are populated appropriately.

(Vague, need more understanding about what this does)

void OnObjectMessage(const signalr::value &Params)

void OnObjectPatch(const signalr::value &Params)

void OnRequestToSendObject(const signalr::value &Params)

Protected Attributes

SpaceEntityList Entities

SpaceEntityList Avatars

SpaceEntityList Objects

SpaceEntityList SelectedEntities

SpaceEntityList RootHierarchyEntities

std::recursive_mutex *EntitiesLock