This class represents an object inside the world. More...

#include <GameObject.h>

Classes
class	ChildIterator

class	ConstChildIterator
	Iterates over all children of one object. More...

Public Types
enum class	TransformPreservation { PreserveLocal , PreserveGlobal }
	Defines during re-parenting what transform is going to be preserved.

enum class	UpdateBehaviorIfStatic { None , UpdateImmediately }
	Defines update behavior for global transforms when changing the local transform on a static game object. More...

Public Member Functions
plGameObjectHandle	GetHandle () const
	Returns a handle to this object.

void	MakeDynamic ()
	Makes this object and all its children dynamic. Dynamic objects might move during runtime.

void	MakeStatic ()
	Makes this object static. Static objects don't move during runtime.

bool	IsDynamic () const
	Returns whether this object is dynamic.

bool	IsStatic () const
	Returns whether this object is static.

void	SetActiveFlag (bool bEnabled)
	Sets the 'active flag' of the game object, which affects its final 'active state'.

bool	GetActiveFlag () const
	Checks whether the 'active flag' is set on this game object. Note that this does not mean that the game object is also in an 'active state'.

bool	IsActive () const
	Checks whether this game object is in an active state.

void	SetCreatedByPrefab ()
	Adds plObjectFlags::CreatedByPrefab to the object. See the flag for details.

bool	WasCreatedByPrefab () const
	Checks whether the plObjectFlags::CreatedByPrefab flag is set on this object.

void	SetName (plStringView sName)
	Sets the name to identify this object. Does not have to be a unique name.

void	SetName (const plHashedString &sName)

plStringView	GetName () const

bool	HasName (const plTempHashedString &sName) const

void	SetGlobalKey (plStringView sGlobalKey)
	Sets the global key to identify this object. Global keys must be unique within a world.

void	SetGlobalKey (const plHashedString &sGlobalKey)

plStringView	GetGlobalKey () const

void	EnableChildChangesNotifications ()
	Enables or disabled notification message 'plMsgChildrenChanged' when children are added or removed. The message is sent to this object and all its parent objects.

void	DisableChildChangesNotifications ()

void	EnableParentChangesNotifications ()
	Enables or disabled notification message 'plMsgParentChanged' when the parent changes. The message is sent to this object only.

void	DisableParentChangesNotifications ()

void	SetParent (const plGameObjectHandle &hParent, plGameObject::TransformPreservation preserve=TransformPreservation::PreserveGlobal)
	Sets the parent of this object to the given.

plGameObject *	GetParent ()
	Gets the parent of this object or nullptr if this is a top-level object.

const plGameObject *	GetParent () const
	Gets the parent of this object or nullptr if this is a top-level object.

void	AddChild (const plGameObjectHandle &hChild, plGameObject::TransformPreservation preserve=TransformPreservation::PreserveGlobal)
	Adds the given object as a child object.

void	AddChildren (const plArrayPtr< const plGameObjectHandle > &children, plGameObject::TransformPreservation preserve=TransformPreservation::PreserveGlobal)
	Adds the given objects as child objects.

void	DetachChild (const plGameObjectHandle &hChild, plGameObject::TransformPreservation preserve=TransformPreservation::PreserveGlobal)
	Detaches the given child object from this object and makes it a top-level object.

void	DetachChildren (const plArrayPtr< const plGameObjectHandle > &children, plGameObject::TransformPreservation preserve=TransformPreservation::PreserveGlobal)
	Detaches the given child objects from this object and makes them top-level objects.

plUInt32	GetChildCount () const
	Returns the number of children.

ChildIterator	GetChildren ()
	Returns an iterator over all children of this object.

ConstChildIterator	GetChildren () const
	Returns an iterator over all children of this object.

plGameObject *	FindChildByName (const plTempHashedString &sName, bool bRecursive=true)
	Searches for a child object with the given name. Optionally traverses the entire hierarchy.

plGameObject *	FindChildByPath (plStringView sPath)
	Searches for a child using a path. Every path segment represents a child with a given name.

plGameObject *	SearchForChildByNameSequence (plStringView sObjectSequence, const plRTTI *pExpectedComponent=nullptr)
	Searches for a child similar to FindChildByName() but allows to search for multiple names in a sequence.

void	SearchForChildrenByNameSequence (plStringView sObjectSequence, const plRTTI pExpectedComponent, plHybridArray< plGameObject , 8 > &out_objects)
	Same as SearchForChildByNameSequence but returns ALL matches, in case the given path could mean multiple objects.

plWorld *	GetWorld ()

const plWorld *	GetWorld () const

void	SetLocalPosition (plVec3 vPosition)
	Changes the position of the object local to its parent.

plVec3	GetLocalPosition () const

void	SetLocalRotation (plQuat qRotation)

plQuat	GetLocalRotation () const

void	SetLocalScaling (plVec3 vScaling)

plVec3	GetLocalScaling () const

void	SetLocalUniformScaling (float fScaling)

float	GetLocalUniformScaling () const

plTransform	GetLocalTransform () const

void	SetGlobalPosition (const plVec3 &vPosition)

plVec3	GetGlobalPosition () const

void	SetGlobalRotation (const plQuat &qRotation)

plQuat	GetGlobalRotation () const

void	SetGlobalScaling (const plVec3 &vScaling)

plVec3	GetGlobalScaling () const

void	SetGlobalTransform (const plTransform &transform)

plTransform	GetGlobalTransform () const

plTransform	GetLastGlobalTransform () const
	Last frame's global transform (only valid if PL_GAMEOBJECT_VELOCITY is set, otherwise the same as GetGlobalTransform())

void	SetLocalPosition (const plSimdVec4f &vPosition, UpdateBehaviorIfStatic updateBehavior=UpdateBehaviorIfStatic::UpdateImmediately)

const plSimdVec4f &	GetLocalPositionSimd () const

void	SetLocalRotation (const plSimdQuat &qRotation, UpdateBehaviorIfStatic updateBehavior=UpdateBehaviorIfStatic::UpdateImmediately)

const plSimdQuat &	GetLocalRotationSimd () const

void	SetLocalScaling (const plSimdVec4f &vScaling, UpdateBehaviorIfStatic updateBehavior=UpdateBehaviorIfStatic::UpdateImmediately)

const plSimdVec4f &	GetLocalScalingSimd () const

void	SetLocalUniformScaling (const plSimdFloat &fScaling, UpdateBehaviorIfStatic updateBehavior=UpdateBehaviorIfStatic::UpdateImmediately)

plSimdFloat	GetLocalUniformScalingSimd () const

plSimdTransform	GetLocalTransformSimd () const

void	SetGlobalPosition (const plSimdVec4f &vPosition)

const plSimdVec4f &	GetGlobalPositionSimd () const

void	SetGlobalRotation (const plSimdQuat &qRotation)

const plSimdQuat &	GetGlobalRotationSimd () const

void	SetGlobalScaling (const plSimdVec4f &vScaling)

const plSimdVec4f &	GetGlobalScalingSimd () const

void	SetGlobalTransform (const plSimdTransform &transform)

const plSimdTransform &	GetGlobalTransformSimd () const

const plSimdTransform &	GetLastGlobalTransformSimd () const

plVec3	GetGlobalDirForwards () const
	Returns the 'forwards' direction of the world's plCoordinateSystem, rotated into the object's global space.

plVec3	GetGlobalDirRight () const
	Returns the 'right' direction of the world's plCoordinateSystem, rotated into the object's global space.

plVec3	GetGlobalDirUp () const
	Returns the 'up' direction of the world's plCoordinateSystem, rotated into the object's global space.

void	UpdateGlobalTransform ()
	Updates the global transform immediately. Usually this done during the world update after the "Post-async" phase.

void	EnableStaticTransformChangesNotifications ()
	Enables or disabled notification message 'plMsgTransformChanged' when this object is static and its transform changes. The notification message is sent to this object and thus also to all its components.

void	DisableStaticTransformChangesNotifications ()

plBoundingBoxSphere	GetLocalBounds () const

plBoundingBoxSphere	GetGlobalBounds () const

const plSimdBBoxSphere &	GetLocalBoundsSimd () const

const plSimdBBoxSphere &	GetGlobalBoundsSimd () const

void	UpdateLocalBounds ()
	Invalidates the local bounds and sends a message to all components so they can add their bounds.

void	UpdateGlobalBounds ()
	Updates the global bounds immediately. Usually this done during the world update after the "Post-async" phase. Note that this function does not ensure that the global transform is up-to-date. Use UpdateGlobalTransformAndBounds if you want to update both.

void	UpdateGlobalTransformAndBounds ()
	Updates the global transform and bounds immediately. Usually this done during the world update after the "Post-async" phase.

plSpatialDataHandle	GetSpatialData () const
	Returns a handle to the internal spatial data.

void	EnableComponentChangesNotifications ()
	Enables or disabled notification message 'plMsgComponentsChanged' when components are added or removed. The message is sent to this object and all its parent objects.

void	DisableComponentChangesNotifications ()

template<typename T >
bool	TryGetComponentOfBaseType (T *&out_pComponent)
	Tries to find a component of the given base type in the objects components list and returns the first match.

template<typename T >
bool	TryGetComponentOfBaseType (const T *&out_pComponent) const
	Tries to find a component of the given base type in the objects components list and returns the first match.

bool	TryGetComponentOfBaseType (const plRTTI pType, plComponent &out_pComponent)
	Tries to find a component of the given base type in the objects components list and returns the first match.

bool	TryGetComponentOfBaseType (const plRTTI pType, const plComponent &out_pComponent) const
	Tries to find a component of the given base type in the objects components list and returns the first match.

template<typename T >
void	TryGetComponentsOfBaseType (plDynamicArray< T * > &out_components)
	Tries to find components of the given base type in the objects components list and returns all matches.

template<typename T >
void	TryGetComponentsOfBaseType (plDynamicArray< const T * > &out_components) const
	Tries to find components of the given base type in the objects components list and returns all matches.

void	TryGetComponentsOfBaseType (const plRTTI pType, plDynamicArray< plComponent > &out_components)
	Tries to find components of the given base type in the objects components list and returns all matches.

void	TryGetComponentsOfBaseType (const plRTTI pType, plDynamicArray< const plComponent > &out_components) const
	Tries to find components of the given base type in the objects components list and returns all matches.

plArrayPtr< plComponent *const >	GetComponents ()
	Returns a list of all components attached to this object.

plArrayPtr< const plComponent *const >	GetComponents () const
	Returns a list of all components attached to this object.

plUInt16	GetComponentVersion () const
	Returns the current version of components attached to this object. This version is increased whenever components are added or removed and can be used for cache validation.

bool	SendMessage (plMessage &ref_msg)
	Sends a message to all components of this object.

bool	SendMessage (plMessage &ref_msg) const
	Sends a message to all components of this object.

bool	SendMessageRecursive (plMessage &ref_msg)
	Sends a message to all components of this object and then recursively to all children.

bool	SendMessageRecursive (plMessage &ref_msg) const
	Sends a message to all components of this object and then recursively to all children.

void	PostMessage (const plMessage &msg, plTime delay, plObjectMsgQueueType::Enum queueType=plObjectMsgQueueType::NextFrame) const
	Queues the message for the given phase. The message is processed after the given delay in the corresponding phase.

void	PostMessageRecursive (const plMessage &msg, plTime delay, plObjectMsgQueueType::Enum queueType=plObjectMsgQueueType::NextFrame) const
	Queues the message for the given phase. The message is processed after the given delay in the corresponding phase.

bool	SendEventMessage (plMessage &ref_msg, const plComponent *pSenderComponent)
	Delivers an plEventMessage to the closest (parent) object containing an plEventMessageHandlerComponent.

bool	SendEventMessage (plMessage &ref_msg, const plComponent *pSenderComponent) const
	Delivers an plEventMessage to the closest (parent) object containing an plEventMessageHandlerComponent.

void	PostEventMessage (plMessage &ref_msg, const plComponent *pSenderComponent, plTime delay, plObjectMsgQueueType::Enum queueType=plObjectMsgQueueType::NextFrame) const
	Delivers an plEventMessage to the closest (parent) object containing an plEventMessageHandlerComponent.

const plTagSet &	GetTags () const
	Returns the tag set associated with this object.

void	SetTags (const plTagSet &tags)
	Sets the tag set associated with this object.

void	SetTag (const plTag &tag)
	Adds the given tag to the object's tags.

void	RemoveTag (const plTag &tag)
	Removes the given tag from the object's tags.

const plUInt16 &	GetTeamID () const
	Returns the 'team ID' that was given during creation (/see plGameObjectDesc)

void	SetTeamID (plUInt16 uiId)
	Changes the team ID for this object and all children recursively.

plUInt32	GetStableRandomSeed () const
	Returns a random value that is chosen once during object creation and remains stable even throughout serialization.

void	SetStableRandomSeed (plUInt32 uiSeed)
	Overwrites the object's random seed value.

plVisibilityState	GetVisibilityState (plUInt32 uiNumFramesBeforeInvisible=5) const
	Retrieves a state describing how visible the object is.

template<typename T >
PL_ALWAYS_INLINE bool	TryGetComponentOfBaseType (T *&out_pComponent)

template<typename T >
PL_ALWAYS_INLINE bool	TryGetComponentOfBaseType (const T *&out_pComponent) const

Friends
class	plWorld

class	plInternal::WorldData

class	plMemoryUtils

class	plComponentManagerBase

class	plGameObjectTest

Detailed Description

This class represents an object inside the world.

Game objects only consists of hierarchical data like transformation and a list of components. You cannot derive from the game object class. To add functionality to an object you have to attach components to it. To create an object instance call CreateObject on the world. Never store a direct pointer to an object but store an plGameObjectHandle instead.

See also: plWorld; plComponent; plGameObjectHandle

Member Enumeration Documentation

◆ UpdateBehaviorIfStatic

enum class plGameObject::UpdateBehaviorIfStatic

strong

Defines update behavior for global transforms when changing the local transform on a static game object.

Enumerator
None	Only sets the local transform, does not update.
UpdateImmediately	Updates the hierarchy underneath the object immediately.

Member Function Documentation

◆ FindChildByName()

plGameObject * plGameObject::FindChildByName	(	const plTempHashedString &	sName,
		bool	bRecursive = true )

Searches for a child object with the given name. Optionally traverses the entire hierarchy.

Test: Needs a unit test

◆ FindChildByPath()

plGameObject * plGameObject::FindChildByPath ( plStringView sPath )

Searches for a child using a path. Every path segment represents a child with a given name.

Paths are separated with single slashes: / When an empty path is given, 'this' is returned. When on any part of the path the next child cannot be found, nullptr is returned. This function expects an exact path to the destination. It does not search the full hierarchy for the next child, as SearchChildByNameSequence() does.

Test: Needs a unit test

◆ GetActiveFlag()

PL_ALWAYS_INLINE bool plGameObject::GetActiveFlag ( ) const

Checks whether the 'active flag' is set on this game object. Note that this does not mean that the game object is also in an 'active state'.

See also: IsActive(), SetActiveFlag()

◆ GetStableRandomSeed()

PL_ALWAYS_INLINE plUInt32 plGameObject::GetStableRandomSeed ( ) const

Returns a random value that is chosen once during object creation and remains stable even throughout serialization.

This value is intended to be used for choosing random variations of components. For instance, if a component has two different meshes it can use for variation, this seed should be used to decide which one to use.

The stable random seed can also be set from the outside, which is what the editor does, to assign a truly stable seed value. Therefore, each object placed in the editor will always have the same seed value, and objects won't change their appearance on every run of the game.

The stable seed is also propagated through prefab instances, such that every prefab instance gets a different value, but in a deterministic fashion.

◆ GetTeamID()

const plUInt16 & plGameObject::GetTeamID ( ) const

inline

Returns the 'team ID' that was given during creation (/see plGameObjectDesc)

It is automatically passed on to objects created by this object. This makes it possible to identify which player or team an object belongs to.

◆ GetVisibilityState()

plVisibilityState plGameObject::GetVisibilityState ( plUInt32 uiNumFramesBeforeInvisible = 5 ) const

Retrieves a state describing how visible the object is.

An object may be invisible, fully visible, or indirectly visible (through shadows or reflections). This can be used to adjust the update logic of objects. An invisible object may stop updating entirely. An indirectly visible object may reduce its update rate.

Parameters

uiNumFramesBeforeInvisible Used to treat an object that was visible and just became invisible as visible for a few more frames.

◆ IsActive()

PL_ALWAYS_INLINE bool plGameObject::IsActive ( ) const

Checks whether this game object is in an active state.

The active state is determined by the active state of the parent game object and the 'active flag' of this game object. Only if the parent game object is active (and thus all of its parent objects as well) and this game object has the active flag set, will this game object be active.

See also: plGameObject::SetActiveFlag(), plComponent::IsActive()

◆ PostEventMessage()

void plGameObject::PostEventMessage	(	plMessage &	ref_msg,
		const plComponent *	pSenderComponent,
		plTime	delay,
		plObjectMsgQueueType::Enum	queueType = plObjectMsgQueueType::NextFrame ) const

Delivers an plEventMessage to the closest (parent) object containing an plEventMessageHandlerComponent.

Regular SendMessage() and PostMessage() send a message directly to the target object (and all attached components). SendMessageRecursive() and PostMessageRecursive() send a message 'down' the graph to the target object and all children.

In contrast, SendEventMessage() / PostEventMessage() bubble the message 'up' the graph. They do so by inspecting the chain of parent objects for the existence of an plEventMessageHandlerComponent (typically a script component). If such a component is found, the message is delivered to it directly, and no other component. If it is found, but does not handle this type of message, the message is discarded and NOT tried to be delivered to anyone else.

If no such component is found in all parent objects, the message is delivered to one plEventMessageHandlerComponent instances that is set to 'handle global events' (typically used for level-logic scripts), no matter where in the graph it resides. If multiple global event handler component exist that handle the same message type, the result is non-deterministic.

Parameters

msg	The message to deliver.
senderComponent	The component that triggered the event in the first place. May be nullptr. If not null, this information is stored in msg as plEventMessage::m_hSenderObject and plEventMessage::m_hSenderComponent. This information is used to pass through more contextual information for the event handler. For instance, a trigger component would pass through itself. A projectile component sending a 'take damage event' to the hit object, would also pass through itself (the projectile) such that the handling code can detect which object was responsible for the damage (and using the plGameObject's team-ID, it can detect which player fired the projectile).
queueType	In which update phase to deliver the message.
delay	An optional delay before delivering the message.

◆ SearchForChildByNameSequence()

plGameObject * plGameObject::SearchForChildByNameSequence	(	plStringView	sObjectSequence,
		const plRTTI *	pExpectedComponent = nullptr )

Searches for a child similar to FindChildByName() but allows to search for multiple names in a sequence.

The names in the sequence are separated with slashes. For example, calling this with "a/b" will first search the entire hierarchy below this object for a child named "a". If that is found, the search continues from there for a child called "b". If such a child is found and pExpectedComponent != nullptr, it is verified that the object contains a component of that type. If it doesn't the search continues (including back-tracking).

Test: Needs a unit test

◆ SearchForChildrenByNameSequence()

void plGameObject::SearchForChildrenByNameSequence	(	plStringView	sObjectSequence,
		const plRTTI *	pExpectedComponent,
		plHybridArray< plGameObject *, 8 > &	out_objects )

Same as SearchForChildByNameSequence but returns ALL matches, in case the given path could mean multiple objects.

Test: Needs a unit test

◆ SendEventMessage() [1/2]

bool plGameObject::SendEventMessage	(	plMessage &	ref_msg,
		const plComponent *	pSenderComponent )

Delivers an plEventMessage to the closest (parent) object containing an plEventMessageHandlerComponent.

Regular SendMessage() and PostMessage() send a message directly to the target object (and all attached components). SendMessageRecursive() and PostMessageRecursive() send a message 'down' the graph to the target object and all children.

In contrast, SendEventMessage() / PostEventMessage() bubble the message 'up' the graph. They do so by inspecting the chain of parent objects for the existence of an plEventMessageHandlerComponent (typically a script component). If such a component is found, the message is delivered to it directly, and no other component. If it is found, but does not handle this type of message, the message is discarded and NOT tried to be delivered to anyone else.

If no such component is found in all parent objects, the message is delivered to one plEventMessageHandlerComponent instances that is set to 'handle global events' (typically used for level-logic scripts), no matter where in the graph it resides. If multiple global event handler component exist that handle the same message type, the result is non-deterministic.

Parameters

msg The message to deliver.

senderComponent The component that triggered the event in the first place. May be nullptr. If not null, this information is stored in msg as plEventMessage::m_hSenderObject and plEventMessage::m_hSenderComponent. This information is used to pass through more contextual information for the event handler. For instance, a trigger component would pass through itself. A projectile component sending a 'take damage event' to the hit object, would also pass through itself (the projectile) such that the handling code can detect which object was responsible for the damage (and using the plGameObject's team-ID, it can detect which player fired the projectile).

◆ SendEventMessage() [2/2]

bool plGameObject::SendEventMessage	(	plMessage &	ref_msg,
		const plComponent *	pSenderComponent ) const

Delivers an plEventMessage to the closest (parent) object containing an plEventMessageHandlerComponent.

Regular SendMessage() and PostMessage() send a message directly to the target object (and all attached components). SendMessageRecursive() and PostMessageRecursive() send a message 'down' the graph to the target object and all children.

In contrast, SendEventMessage() / PostEventMessage() bubble the message 'up' the graph. They do so by inspecting the chain of parent objects for the existence of an plEventMessageHandlerComponent (typically a script component). If such a component is found, the message is delivered to it directly, and no other component. If it is found, but does not handle this type of message, the message is discarded and NOT tried to be delivered to anyone else.

If no such component is found in all parent objects, the message is delivered to one plEventMessageHandlerComponent instances that is set to 'handle global events' (typically used for level-logic scripts), no matter where in the graph it resides. If multiple global event handler component exist that handle the same message type, the result is non-deterministic.

Parameters

msg The message to deliver.

senderComponent The component that triggered the event in the first place. May be nullptr. If not null, this information is stored in msg as plEventMessage::m_hSenderObject and plEventMessage::m_hSenderComponent. This information is used to pass through more contextual information for the event handler. For instance, a trigger component would pass through itself. A projectile component sending a 'take damage event' to the hit object, would also pass through itself (the projectile) such that the handling code can detect which object was responsible for the damage (and using the plGameObject's team-ID, it can detect which player fired the projectile).

◆ SetActiveFlag()

void plGameObject::SetActiveFlag ( bool bEnabled )

Sets the 'active flag' of the game object, which affects its final 'active state'.

The active flag affects the 'active state' of the game object and all its children and attached components. When a game object does not have the active flag, it is switched to 'inactive'. The same happens for all its children and all components attached to those game objects. Thus removing the active flag from a game object recursively deactivates the entire sub-tree of objects and components.

When the active flag is set on a game object, and all of its parent nodes have the flag set as well, then the active state will be set to true on it and all its children and attached components.

See also: IsActive(), plComponent::SetActiveFlag()

◆ SetLocalPosition()

PL_ALWAYS_INLINE void plGameObject::SetLocalPosition ( plVec3 vPosition )

Changes the position of the object local to its parent.

Note: The rotation of the object itself does not affect the final global position! The local position is always in the space of the parent object. If there is no parent, local position and global position are identical.

◆ SetStableRandomSeed()

PL_ALWAYS_INLINE void plGameObject::SetStableRandomSeed ( plUInt32 uiSeed )

Overwrites the object's random seed value.

See GetStableRandomSeed() for details.

It should not be necessary to manually change this value, unless you want to make the seed deterministic according to a custom rule.

The documentation for this class was generated from the following files:

Code/Engine/Core/World/GameObject.h
Code/Engine/Core/World/Implementation/GameObject.cpp
Code/Engine/Core/World/Implementation/GameObject_inl.h

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ UpdateBehaviorIfStatic

Member Function Documentation

◆ FindChildByName()

◆ FindChildByPath()

◆ GetActiveFlag()

◆ GetStableRandomSeed()

◆ GetTeamID()

◆ GetVisibilityState()

◆ IsActive()

◆ PostEventMessage()

◆ SearchForChildByNameSequence()

◆ SearchForChildrenByNameSequence()

◆ SendEventMessage() [1/2]

◆ SendEventMessage() [2/2]

◆ SetActiveFlag()

◆ SetLocalPosition()

◆ SetStableRandomSeed()