Class SpaceEntity

Defined in File SpaceEntity.h

Class Documentation

class SpaceEntity

Primary multiplayer object that can have associated scripts and many multiplayer components created within it.

Public Types

typedef std::function<void(SpaceEntity*, SpaceEntityUpdateFlags, csp::common::Array<ComponentUpdateInfo>&)> UpdateCallback

typedef std::function<void(bool)> DestroyCallback

typedef std::function<void(bool)> CallbackHandler

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

Public Functions

SpaceEntity(): Creates a default instance of a SpaceEntity.

SpaceEntity(csp::common::IRealtimeEngine *InEntitySystem, csp::common::IJSScriptRunner &ScriptRunner, csp::common::LogSystem *LogSystem): Creates a SpaceEntity instance using the space entity system provided.

SpaceEntity(csp::common::IRealtimeEngine *EntitySystem, csp::common::IJSScriptRunner &ScriptRunner, csp::common::LogSystem *LogSystem, SpaceEntityType Type, uint64_t Id, const csp::common::String &Name, const SpaceTransform &Transform, uint64_t OwnerId, csp::common::Optional<uint64_t> ParentId, bool IsTransferable, bool IsPersistent)

Internal constructor to explicitly create a SpaceEntity in a specified state.

Initially implemented for use in OnlineRealtimeEngine::CreateAvatar

~SpaceEntity(): Destroys the SpaceEntity instance.

uint64_t GetId() const

Get the ID of this SpaceEntity, this should be unique to each Entity.

Returns: The uint64_t ID of the SpaceEntity.

uint64_t GetOwnerId() const

Get the ClientID of the owner of the SpaceEntity.

This starts as the user that creates the Entity but can change if another user patches the Entity.

Returns: the uint64_t ClientID of the owner of the SpaceEntity.

const csp::common::String &GetName() const

Get the name set for this SpaceEntity.

Returns: Name.

bool SetName(const csp::common::String &Value)

Set the name of the SpaceEntity.

Parameters: Value – csp::common::String : The name to set.
Returns: Whether a new value was set, may fail if not modifiable, or if a dirty property is already set to this value.

const SpaceTransform &GetTransform() const

Get the SpaceTransform of the SpaceEntity.

Returns: SpaceTransform.

SpaceTransform GetGlobalTransform() const

Get the Global SpaceTransform of the SpaceEntity, derived from it’s parent.

Returns: SpaceTransform.

const csp::common::Vector3 &GetPosition() const

Get the position of the SpaceEntity, in world space.

Returns: Position.

csp::common::Vector3 GetGlobalPosition() const

Get the Global position of the SpaceEntity, in world space, derived from it’s parent.

Returns: Position.

bool SetPosition(const csp::common::Vector3 &Value)

Set the position of the SpaceEntity, in world space.

Parameters: Value – csp::common::Vector3 : The position to set.
Returns: Whether a new value was set, may fail if not modifiable, or if a dirty property is already set to this value.

const csp::common::Vector4 &GetRotation() const

Get the rotation of the SpaceEntity.

Returns: Rotation.

csp::common::Vector4 GetGlobalRotation() const

Get the Global rotation of the SpaceEntity, derived from it’s parent.

Returns: Rotation.

bool SetRotation(const csp::common::Vector4 &Value)

Set the rotation of the SpaceEntity.

Parameters: Value – csp::common::Vector4 : The rotation to set.
Returns: Whether a new value was set, may fail if not modifiable, or if a dirty property is already set to this value.

const csp::common::Vector3 &GetScale() const

Get the scale of the SpaceEntity.

Returns: Scale.

csp::common::Vector3 GetGlobalScale() const

Get the Global scale of the SpaceEntity, derived from it’s parent.

Returns: Scale.

bool SetScale(const csp::common::Vector3 &Value)

Set the scale of the SpaceEntity.

Parameters: Value – csp::common::Vector3 : The scale to set.
Returns: Whether a new value was set, may fail if not modifiable, or if a dirty property is already set to this value.

bool GetIsTransient() const

Get whether the space is transient or persistent.

Returns: returns True if the space is transient and false if it is marked as persistent.

const csp::common::String &GetThirdPartyRef() const

Get the third party reference of this entity.

Returns: A string representing the third party reference set for this entity.

bool SetThirdPartyRef(const csp::common::String &InThirdPartyRef)

Set the third party reference for this entity.

Parameters: InThirdPartyRef – csp::common::String : The third party reference to set.
Returns: Whether a new value was set, may fail if not modifiable, or if a dirty property is already set to this value.

csp::systems::EThirdPartyPlatform GetThirdPartyPlatformType() const

Get the third party platform type of this entity.

Returns: A string representing third party platform type set for this entity.

bool SetThirdPartyPlatformType(const csp::systems::EThirdPartyPlatform InThirdPartyPlatformType)

Set third party platform type for this entity.

Parameters: InThirdPartyPlatformType – csp::systems::EThirdPartyPlatform : The third party platform type to set.
Returns: Whether a new value was set, may fail if not modifiable, or if a dirty property is already set to this value.

SpaceEntityType GetEntityType() const

Get the type of the Entity.

Returns: The SpaceEntityType enum value.

void SetParentId(uint64_t ParentId)

Sets the parent for this entity QueueUpdate() should be called afterwards to enable changes to the parent.

Parameters: ParentId – uint64_t The new parent id of this entity.

void RemoveParentEntity(): Removes the parent entity QueueUpdate() should be called afterwards to enable changes to the parent.

SpaceEntity *GetParentEntity() const

Gets the parent of this entity.

Returns: Non-owning pointer to the parent of this entity. May be null.

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

Create a new entity with this entity as it’s parent.

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.

const csp::common::List<SpaceEntity*> *GetChildEntities() const

Gets the children of this entity.

Returns: csp::common::List<SpaceEntity>

void Destroy(CallbackHandler Callback)

Sends a patch message with a flag to destroy the entity.

Will remove the entity from endpoints and signal remote clients to delete the entity. Note this will trigger local deletion of the SpaceEntity immediately, without considering if remotes were able to also delete. If the endpoint fails to process this message, the client that called this function will be out of sync. It is advised to handle this situation by dropping the client out of a space if the callback comes back as failed.

Parameters: Callback – CallbackHandler : The callback triggers when the patch message completes, either successfully or unsuccessfully.

void SetUpdateCallback(UpdateCallback Callback)

Set a callback to be executed when a patch message is received for this Entity.

Only one callback can be set.

Parameters: Callback – UpdateCallback : Contains the SpaceEntity that updated, a set of flags to tell which parts updated and an array of information to tell which components updated. When this callback is received, the flags and arrays should be used to determine which properties have updated data.

void SetDestroyCallback(DestroyCallback Callback)

Set a callback to be executed when a patch message with a destroy flag is received for this Entity.

Only one callback can be set.

Parameters: Callback – DestroyCallback : Contains a bool that is true if the Entity is being deleted.

void SetPatchSentCallback(CallbackHandler Callback)

Set a callback to be executed when a patch message queued for the entity is sent.

Only one callback can be set.

Parameters: Callback – CallbackHandler : Contains a bool that is true when the patch message is sent.

ComponentBase *FindFirstComponentOfType(ComponentType Type) const

Get a pointer to the first component on the entity of specified type.

Returns: Non-owning pointer to component, nullptr if component of type cannot be found

const csp::common::Map<uint16_t, ComponentBase*> *GetComponents() const

Get the map of components on this SpaceEntity.

Returns: A map of components indexed with the component ID.

ComponentBase *GetComponent(uint16_t Key)

Get a component on this SpaceEntity by the specified key.

Parameters: Key – uint16_t : The component ID for the desired component.
Returns: The component if found or nullptr if not found.

ComponentBase *AddComponent(ComponentType Type)

Add a component of the given type.

Parameters: Type – ComponentType : The type of component to add.
Returns: The newly created component.

bool UpdateComponent(ComponentBase *Component)

Mark that a component has just been updated, ie, that a property on it has been modified.

Warning

This is a pattern divergence, as updates to component data happen immediately, rather than being deferred via the regular patch flow. This method could also be spelled “MarkComponentHasUpdated”, … however, this will change, so the naming sticks to the pattern. This is why this is CSP_NO_EXPORT, we’d like external users to be able to call this directly, but they probably shouldn’t right now.

Parameters: Component – ComponentBase : The component that has just updated
Returns: Always returns true

bool RemoveComponent(uint16_t Key)

Remove a component of the given key.

Note that the component cannot currently truly be removed from the server data, the best we can do is add a blank component in its place, which clients decide to ignore when retrieving data.

Parameters: Key – uint16_t : The component ID of the component to remove.
Returns: Whether a component was removed, may fail if not modifiable, there is no component of provided key, or if a dirty component is already set to this deletion.

EntityScript &GetScript()

Gets the script associated with the space entity.

Returns: The EntityScript instance set on the entity.

bool IsSelected() const

Returns the selection state of the entity.

Returns: Selection state of the entity, Selected = True, Deselected = False.

uint64_t GetSelectingClientID() const

Retrieve the ClientID for the Selecting Client.

Returns: The client ID of the selecting client. Deselected Entity = 0.

bool Select()

Select the Entity.

Only works if the Entity is currently deselected.

Returns: True if selection occurred. False if not.

bool Deselect()

Deselect the Entity.

Only works if:

The Entity is currently selected
The Client attempting to deselect has the same ClientID as the one who selected it

Returns: True if deselection occurred. False if not.

bool IsModifiable() const

Checks if the entity can be modified.

Specifically whether the local client already owns the entity or can take ownership of the entity.

Returns: True if the entity can be modified, False if not.

bool Lock()

Locks the entity if it hasn’t been locked already.

Pre: The entity must not already be locked. A CSP error will be sent to the LogSystem if this condition is not met.
Post: This internally sets the lock type as a dirty property. This entity should now be replicated, to process the change.
Returns: Whether setting the lock was successful.

bool Unlock()

Unlocks the entity if the entity is locked.

Pre: The entity must be locked. A CSP error will be sent to the LogSystem if this condition is not met.
Post: This internally sets the lock type as a dirty property. This entity should now be replicated, to process the change.
Returns: Whether removing the lock was successful.

csp::multiplayer::LockType GetLockType() const

Gets the type of lock currently applied to this entity.

Returns: The Locktype, will be LockType::None if the entity is currently unlocked.

bool IsLocked() const

Checks if the entity has a lock type other than LockType::None, set by calling SpaceEntity::Lock.

Returns: bool

void QueueUpdate(): Queues an update which will be executed on next Tick() or ProcessPendingEntityOperations(). Not a blocking or async function.

UpdateCallback GetEntityUpdateCallback()

Getter for the EntityUpdateCallback.

Returns: : UpdateCallback

DestroyCallback GetEntityDestroyCallback()

Getter for the EntityDestroyCallback.

Returns: : DestroyCallback

SpaceEntity *GetParent()

Getter for the parent entity.

Returns: SpaceEntity*

csp::common::Optional<uint64_t> GetParentId() const

Getter for the parent id.

Returns: csp::common::Optional<uint64_t>

bool GetIsTransferable() const

Whether the entity’s ownership may be transferred from one user to another.

Generally true of all entities except entities representing a user within a space

bool GetIsPersistent() const

Whether the entity should persist even after the user who created the entity disconnects.

Generally true of all entities except entities representing a user within a space

std::chrono::milliseconds GetTimeOfLastPatch()

Getter for the time of the last patch.

Returns: std::chrono::milliseconds

void RemoveParentFromChildEntity(size_t Index)

Remove the parent from the specified child entity.

Parameters: Index – size_t : the index of the child entity

EntityScriptInterface *GetScriptInterface()

Getter for the script interface.

Returns: EntityScriptInterface*

void ClaimScriptOwnership(): Claim script ownership.

void ApplyLocalPatch(bool InvokeUpdateCallback = true, bool AllowSelfMessaging = false)

Apply a local patch.

Parameters

InvokeUpdateCallback – bool : whether to invoke the update callback (default: true)
AllowSelfMessaging – bool : Whether or not to apply local patches. Normally sources from the RealtimeEngine state. Don’t set this unless you know what you are doing. (default: false)

void ResolveParentChildRelationship(): Resolve the relationship between the parent and the child.

const std::unique_ptr<SpaceEntityStatePatcher> &GetStatePatcher()

void OnPropertyChanged(ComponentBase *DirtyComponent, int32_t PropertyKey)

Update after the property of a component was changed.

Parameters

DirtyComponent – ComponentBase* : the dirty component to update
PropertyKey – int32_t : the key of the property to update

void RemoveAsChildFromParent(): Remove child entities from parent.

void RemoveParentId(): Sets the internal ParentId to nullptr.

void SetNameDirect(const csp::common::String &Value, bool CallNotifyingCallback = false)

void SetPositionDirect(const csp::common::Vector3 &Value, bool CallNotifyingCallback = false)

void SetRotationDirect(const csp::common::Vector4 &Value, bool CallNotifyingCallback = false)

void SetScaleDirect(const csp::common::Vector3 &Value, bool CallNotifyingCallback = false)

void SetThirdPartyRefDirect(const csp::common::String &Value, bool CallNotifyingCallback = false)

void SetThirdPartyPlatformDirect(const csp::systems::EThirdPartyPlatform Value, bool CallNotifyingCallback = false)

void SetEntityLockDirect(LockType Value, bool CallNotifyingCallback = false)

void SetSelectedIdDirect(uint64_t Value, bool CallNotifyingCallback = false)

void SetParentIdDirect(csp::common::Optional<uint64_t> Value, bool CallNotifyingCallback)

bool AddComponentDirect(uint16_t ComponentKey, ComponentBase *Component, bool CallNotifyingCallback = false)

bool UpdateComponentDirect(uint16_t ComponentKey, ComponentBase *Component, bool CallNotifyingCallback = false)

bool RemoveComponentDirect(uint16_t ComponentKey, bool CallNotifyingCallback = false)

void SetOwnerId(const uint64_t InOwnerId)

Setter for the owner ID.

Parameters: InOwnerId – uint64_t : the owner ID to set

void AddComponentFromItemComponentData(uint16_t ComponentId, const csp::multiplayer::mcs::ItemComponentData &ComponentData)

ComponentUpdateInfo AddComponentFromItemComponentDataPatch(uint16_t ComponentId, const csp::multiplayer::mcs::ItemComponentData &ComponentData)