Class SpaceEntitySystem

Class Documentation

class SpaceEntitySystem

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(bool)> CallbackHandler
typedef std::function<void(SpaceEntity*)> EntityCreatedCallback

Public Functions

void CreateAvatar(const csp::common::String &InName, const SpaceTransform &InSpaceTransform, AvatarState InState, const csp::common::String &InAvatarId, AvatarPlayMode InAvatarPlayMode, EntityCreatedCallback Callback)

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

Parameters

  • InName – csp::common::String : The name to give the new SpaceEntity.

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

  • InState – AvatarState : The initial Avatar State to set.

  • InAvatarId – csp::common::String : The Initial AvatarID to set.

  • InAvatarPlayMode – AvatarPlayMode : The Initial AvatarPlayMode to set.

  • Callback – EntityCreatedCallback A callback that executes when the creation is complete, which contains a pointer to the new SpaceEntity so that it can be used on the local client.

void CreateObject(const csp::common::String &InName, const SpaceTransform &InSpaceTransform, EntityCreatedCallback Callback)

Creates a SpaceEntity of type Object, and relevant default values.

Parameters

  • InName – csp::common::String : The name to give the new SpaceEntity.

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

  • Callback – EntityCreatedCallback : A callback that executes when the creation is complete, which contains a pointer to the new SpaceEntity so that it can be used on the local client.

void DestroyEntity(SpaceEntity *Entity, CallbackHandler Callback)

Destroys both the remote view and the local view of the specified entity.

Parameters

  • Entity – SpaceEntity : The entity to be destroyed.

  • Callback – CallbackHandler : the callback to execute.

void LocalDestroyEntity(SpaceEntity *Entity)

Destroys the local client’s view of the specified entity.

Parameters

Entity – SpaceEntity : The entity to be destroyed locally.

SpaceEntity *FindSpaceEntity(const csp::common::String &InName)

Finds the first SpaceEntity that matches InName.

Parameters

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

Returns

A pointer to the first found match SpaceEntity.

SpaceEntity *FindSpaceEntityById(uint64_t EntityId)

Finds the first SpaceEntity that has the ID EntityId.

Parameters

EntityId – uint64_t : The Id to look for.

Returns

A pointer to the first found match SpaceEntity.

SpaceEntity *FindSpaceAvatar(const csp::common::String &InName)

Finds the first SpaceEntity of type Avatar that matches InName.

Parameters

InName – The name to search.

Returns

A pointer to the first found match SpaceEntity.

SpaceEntity *FindSpaceObject(const csp::common::String &InName)

Finds the first SpaceEntity of type Object that matches InName.

Parameters

InName – The name to search.

Returns

A pointer to the first found match SpaceEntity.

void LockEntityUpdate() const

Locks the entity mutex.

void UnlockEntityUpdate() const

Unlocks the entity mutex.

size_t GetNumEntities() const

Get the number of total entities in the system (both Avatars and Objects).

Returns

The total number of entities.

size_t GetNumAvatars() const

Get the number of total Avatars in the system.

Returns

The total number of Avatar entities.

size_t GetNumObjects() const

Get the number of total Objects in the system.

Returns

The total number of object entities.

SpaceEntity *GetEntityByIndex(const size_t EntityIndex)

Get an Entity (Avatar or Object) by its index.

Note this is not currently thread safe and should only be called from the main thread.

Parameters

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

Returns

A pointer to the entity with the given index.

SpaceEntity *GetAvatarByIndex(const size_t AvatarIndex)

Get an Avatar by its index.

Note this is not currently thread safe and should only be called from the main thread.

Parameters

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

Returns

A pointer to the avatar entity with the given index.

SpaceEntity *GetObjectByIndex(const size_t ObjectIndex)

Get an Object by its index.

Note this is not currently thread safe and should only be called from the main thread.

Parameters

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

Returns

A pointer to the object entity with the given index.

void AddEntity(SpaceEntity *EntityToAdd)

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.

void SetEntityCreatedCallback(EntityCreatedCallback Callback)

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

Only one callback may be registered, calling this function again will override whatever was previously set. If this is not set, some patch functions may fail.

Parameters

Callback – EntityCreatedCallback : the callback to execute.

void SetConnection(csp::multiplayer::SignalRConnection *InConnection)

Sets a local pointer to the connection for communication with the endpoints, this should be called as early as possible.

Note that this is already called in MultiplayerConnection::Connect, so this shouldn’t need to be called anywhere else. This should not be called by client code directly, marked as No Export.

Parameters

InConnection – csp::multiplayer::SignalRConnection : A pointer to the connection object to be used by the system.

void SetInitialEntitiesRetrievedCallback(CallbackHandler Callback)

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

Parameters

Callback – CallbackHandler : the callback to execute.

void SetScriptSystemReadyCallback(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 QueueEntityUpdate(SpaceEntity *EntityToUpdate)

Triggers queuing of the SpaceEntities updated components and replicated data.

Causes the replication of a SpaceEntities data on next Tick() or ProcessPendingEntityOperations(). However, this is bound by an entities rate limit and will only be replicated if there has been sufficient time since the last time the entity sent a message.

Parameters

EntityToUpdate – SpaceEntity : A pointer to the SpaceEntity to update.

void TickEntities()

Processes pending entity operations and then calls tick on scripts if necessary.

void RegisterEntityScriptAsModule(SpaceEntity *NewEntity)
void BindNewEntityToScript(SpaceEntity *NewEntity)
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 MarkEntityForUpdate(SpaceEntity *Entity)

Adds the entity to a list of entities to be updated on tick.

Parameters

Entity – SpaceEntity : A pointer to the entity to be added

void ProcessPendingEntityOperations()

Process pending entity adds/removes and Patch message send and receives.

Note this should only be called from main thread

void RetrieveAllEntities()

Retrieves all entities from the endpoint, calls “GetAllScopedObjects” currently.

Note this will generate new entity objects for every entity in the current scopes. If this is called by a client manually without first deleting all existing tracked entities, it is possible there will be duplicates. It is highly advised not to call this function unless you know what you are doing.

void LocalDestroyAllEntities()

Destroys the client’s local view of all currently known entities.

They still reside on the server, however they will not be accessible in the client application.

bool SetSelectionStateOfEntity(const bool SelectedState, SpaceEntity *Entity)

Sets the selected state of an entity, if the operation is acceptable.

Criteria: For Selection:

  • Entity must be deselected currently For Deselection:

  • Entity must be selected currently

  • Entity must be selected by the client attempting the deselection (SpaceEntity::GetSelectingClientID will return this information)

Parameters

  • SelectedState – bool : The state to set the entity to, Selected = True, Deselected = false.

  • Entity – SpaceEntity : A pointer to the entity to modify selection state on.

Returns

True if a selection state change has occurred, false if no change was made (due to one of the above criteria not being met).

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.

ComponentBase *FindComponentById(uint16_t Id)

Finds a component by the given id.

Searchs through all components of all entites so should be used sparingly.

Parameters

Id – The id of the component to find.

Returns

A pointer to the found component which can be nullptr if the component is not found.

const 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 consequntly more patch merges may occur on the server as a result. ///

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

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

Returns

A list of root entities.

Protected Types

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

Protected Attributes

SpaceEntityList Entities
SpaceEntityList Avatars
SpaceEntityList Objects
SpaceEntityList SelectedEntities
SpaceEntityList RootHierarchyEntities
std::recursive_mutex *EntitiesLock