![]() |
ezEngine
Release 25.03
|
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 | UpdateBehaviorIfStatic { UpdateBehaviorIfStatic::None, UpdateBehaviorIfStatic::UpdateImmediately } |
Defines update behavior for global transforms when changing the local transform on a static game object. More... | |
Public Member Functions | |
ezGameObjectHandle | 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'. More... | |
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'. More... | |
bool | IsActive () const |
Checks whether this game object is in an active state. More... | |
void | SetCreatedByPrefab () |
Adds ezObjectFlags::CreatedByPrefab to the object. See the flag for details. | |
bool | WasCreatedByPrefab () const |
Checks whether the ezObjectFlags::CreatedByPrefab flag is set on this object. | |
void | SetName (ezStringView sName) |
Sets the name to identify this object. Does not have to be a unique name. | |
void | SetName (const ezHashedString &sName) |
ezStringView | GetName () const |
const ezHashedString & | GetNameHashed () const |
bool | HasName (const ezTempHashedString &sName) const |
void | SetGlobalKey (ezStringView sGlobalKey) |
Sets the global key to identify this object. Global keys must be unique within a world. | |
void | SetGlobalKey (const ezHashedString &sGlobalKey) |
ezStringView | GetGlobalKey () const |
void | EnableChildChangesNotifications () |
Enables or disabled notification message 'ezMsgChildrenChanged' 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 'ezMsgParentChanged' when the parent changes. The message is sent to this object only. | |
void | DisableParentChangesNotifications () |
void | SetParent (const ezGameObjectHandle &hParent, ezTransformPreservation::Enum preserve=ezTransformPreservation::PreserveGlobal) |
Sets the parent of this object to the given. | |
ezGameObject * | GetParent () |
Gets the parent of this object or nullptr if this is a top-level object. | |
const ezGameObject * | GetParent () const |
Gets the parent of this object or nullptr if this is a top-level object. | |
void | AddChild (const ezGameObjectHandle &hChild, ezTransformPreservation::Enum preserve=ezTransformPreservation::PreserveGlobal) |
Adds the given object as a child object. | |
void | AddChildren (const ezArrayPtr< const ezGameObjectHandle > &children, ezTransformPreservation::Enum preserve=ezTransformPreservation::PreserveGlobal) |
Adds the given objects as child objects. | |
void | DetachChild (const ezGameObjectHandle &hChild, ezTransformPreservation::Enum preserve=ezTransformPreservation::PreserveGlobal) |
Detaches the given child object from this object and makes it a top-level object. | |
void | DetachChildren (const ezArrayPtr< const ezGameObjectHandle > &children, ezTransformPreservation::Enum preserve=ezTransformPreservation::PreserveGlobal) |
Detaches the given child objects from this object and makes them top-level objects. | |
ezUInt32 | 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. | |
ezGameObject * | FindChildByName (const ezTempHashedString &sName, bool bRecursive=true) |
Searches for a child object with the given name. Optionally traverses the entire hierarchy. More... | |
ezGameObject * | FindChildByPath (ezStringView sPath) |
Searches for a child using a path. Every path segment represents a child with a given name. More... | |
ezGameObject * | SearchForChildByNameSequence (ezStringView sObjectSequence, const ezRTTI *pExpectedComponent=nullptr) |
Searches for a child similar to FindChildByName() but allows to search for multiple names in a sequence. More... | |
void | SearchForChildrenByNameSequence (ezStringView sObjectSequence, const ezRTTI *pExpectedComponent, ezHybridArray< ezGameObject *, 8 > &out_objects) |
Same as SearchForChildByNameSequence but returns ALL matches, in case the given path could mean multiple objects. More... | |
ezWorld * | GetWorld () |
const ezWorld * | GetWorld () const |
void | SetLocalPosition (ezVec3 vPosition) |
Changes the position of the object local to its parent. More... | |
ezVec3 | GetLocalPosition () const |
void | SetLocalRotation (ezQuat qRotation) |
ezQuat | GetLocalRotation () const |
void | SetLocalScaling (ezVec3 vScaling) |
ezVec3 | GetLocalScaling () const |
void | SetLocalUniformScaling (float fScaling) |
float | GetLocalUniformScaling () const |
ezTransform | GetLocalTransform () const |
void | SetGlobalPosition (const ezVec3 &vPosition) |
ezVec3 | GetGlobalPosition () const |
void | SetGlobalRotation (const ezQuat &qRotation) |
ezQuat | GetGlobalRotation () const |
void | SetGlobalScaling (const ezVec3 &vScaling) |
ezVec3 | GetGlobalScaling () const |
void | SetGlobalTransform (const ezTransform &transform) |
ezTransform | GetGlobalTransform () const |
ezTransform | GetLastGlobalTransform () const |
Last frame's global transform (only valid if EZ_GAMEOBJECT_VELOCITY is set, otherwise the same as GetGlobalTransform()) | |
void | SetLocalPosition (const ezSimdVec4f &vPosition, UpdateBehaviorIfStatic updateBehavior=UpdateBehaviorIfStatic::UpdateImmediately) |
const ezSimdVec4f & | GetLocalPositionSimd () const |
void | SetLocalRotation (const ezSimdQuat &qRotation, UpdateBehaviorIfStatic updateBehavior=UpdateBehaviorIfStatic::UpdateImmediately) |
const ezSimdQuat & | GetLocalRotationSimd () const |
void | SetLocalScaling (const ezSimdVec4f &vScaling, UpdateBehaviorIfStatic updateBehavior=UpdateBehaviorIfStatic::UpdateImmediately) |
const ezSimdVec4f & | GetLocalScalingSimd () const |
void | SetLocalUniformScaling (const ezSimdFloat &fScaling, UpdateBehaviorIfStatic updateBehavior=UpdateBehaviorIfStatic::UpdateImmediately) |
ezSimdFloat | GetLocalUniformScalingSimd () const |
ezSimdTransform | GetLocalTransformSimd () const |
void | SetGlobalPosition (const ezSimdVec4f &vPosition) |
const ezSimdVec4f & | GetGlobalPositionSimd () const |
void | SetGlobalRotation (const ezSimdQuat &qRotation) |
const ezSimdQuat & | GetGlobalRotationSimd () const |
void | SetGlobalScaling (const ezSimdVec4f &vScaling) |
const ezSimdVec4f & | GetGlobalScalingSimd () const |
void | SetGlobalTransform (const ezSimdTransform &transform) |
const ezSimdTransform & | GetGlobalTransformSimd () const |
const ezSimdTransform & | GetLastGlobalTransformSimd () const |
ezVec3 | GetGlobalDirForwards () const |
Returns the 'forwards' direction of the world's ezCoordinateSystem, rotated into the object's global space. | |
ezVec3 | GetGlobalDirRight () const |
Returns the 'right' direction of the world's ezCoordinateSystem, rotated into the object's global space. | |
ezVec3 | GetGlobalDirUp () const |
Returns the 'up' direction of the world's ezCoordinateSystem, 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 'ezMsgTransformChanged' 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 () |
ezBoundingBoxSphere | GetLocalBounds () const |
ezBoundingBoxSphere | GetGlobalBounds () const |
const ezSimdBBoxSphere & | GetLocalBoundsSimd () const |
const ezSimdBBoxSphere & | 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. | |
ezSpatialDataHandle | GetSpatialData () const |
Returns a handle to the internal spatial data. | |
void | EnableComponentChangesNotifications () |
Enables or disabled notification message 'ezMsgComponentsChanged' 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 ezRTTI *pType, ezComponent *&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 ezRTTI *pType, const ezComponent *&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 (ezDynamicArray< 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 (ezDynamicArray< 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 ezRTTI *pType, ezDynamicArray< ezComponent * > &out_components) |
Tries to find components of the given base type in the objects components list and returns all matches. | |
void | TryGetComponentsOfBaseType (const ezRTTI *pType, ezDynamicArray< const ezComponent * > &out_components) const |
Tries to find components of the given base type in the objects components list and returns all matches. | |
ezArrayPtr< ezComponent *const > | GetComponents () |
Returns a list of all components attached to this object. | |
ezArrayPtr< const ezComponent *const > | GetComponents () const |
Returns a list of all components attached to this object. | |
ezUInt16 | 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 (ezMessage &ref_msg) |
Sends a message to all components of this object. More... | |
bool | SendMessage (ezMessage &ref_msg) const |
Sends a message to all components of this object. More... | |
bool | SendMessageRecursive (ezMessage &ref_msg) |
Sends a message to all components of this object and then recursively to all children. More... | |
bool | SendMessageRecursive (ezMessage &ref_msg) const |
Sends a message to all components of this object and then recursively to all children. More... | |
void | PostMessage (const ezMessage &msg, ezTime delay, ezObjectMsgQueueType::Enum queueType=ezObjectMsgQueueType::NextFrame) const |
Queues the message for the given phase. The message is processed after the given delay in the corresponding phase. | |
void | PostMessageRecursive (const ezMessage &msg, ezTime delay, ezObjectMsgQueueType::Enum queueType=ezObjectMsgQueueType::NextFrame) const |
Queues the message for the given phase. The message is processed after the given delay in the corresponding phase. | |
bool | SendEventMessage (ezMessage &ref_msg, const ezComponent *pSenderComponent) |
Delivers an ezEventMessage to the closest (parent) object containing an ezEventMessageHandlerComponent. More... | |
bool | SendEventMessage (ezMessage &ref_msg, const ezComponent *pSenderComponent) const |
Delivers an ezEventMessage to the closest (parent) object containing an ezEventMessageHandlerComponent. More... | |
void | PostEventMessage (ezMessage &ref_msg, const ezComponent *pSenderComponent, ezTime delay, ezObjectMsgQueueType::Enum queueType=ezObjectMsgQueueType::NextFrame) const |
Delivers an ezEventMessage to the closest (parent) object containing an ezEventMessageHandlerComponent. More... | |
const ezTagSet & | GetTags () const |
Returns the tag set associated with this object. | |
void | SetTags (const ezTagSet &tags) |
Sets the tag set associated with this object. | |
void | SetTag (const ezTag &tag) |
Adds the given tag to the object's tags. | |
void | RemoveTag (const ezTag &tag) |
Removes the given tag from the object's tags. | |
bool | HasTag (const ezTempHashedString &sTagName) const |
Checks whether this object has the given tag. | |
const ezUInt16 & | GetTeamID () const |
Returns the 'team ID' that was given during creation (/see ezGameObjectDesc) More... | |
void | SetTeamID (ezUInt16 uiId) |
Changes the team ID for this object and all children recursively. | |
ezUInt32 | GetStableRandomSeed () const |
Returns a random value that is chosen once during object creation and remains stable even throughout serialization. More... | |
void | SetStableRandomSeed (ezUInt32 uiSeed) |
Overwrites the object's random seed value. More... | |
ezVisibilityState::Enum | GetVisibilityState (ezUInt32 uiNumFramesBeforeInvisible=5) const |
Retrieves a state describing how visible the object is. More... | |
template<typename T > | |
EZ_ALWAYS_INLINE bool | TryGetComponentOfBaseType (T *&out_pComponent) |
template<typename T > | |
EZ_ALWAYS_INLINE bool | TryGetComponentOfBaseType (const T *&out_pComponent) const |
Friends | |
class | ezWorld |
class | ezInternal::WorldData |
class | ezMemoryUtils |
class | ezComponentManagerBase |
class | ezGameObjectTest |
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 ezGameObjectHandle instead.
|
strong |
ezGameObject * ezGameObject::FindChildByName | ( | const ezTempHashedString & | sName, |
bool | bRecursive = true |
||
) |
Searches for a child object with the given name. Optionally traverses the entire hierarchy.
ezGameObject * ezGameObject::FindChildByPath | ( | ezStringView | 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.
EZ_ALWAYS_INLINE bool ezGameObject::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'.
EZ_ALWAYS_INLINE ezUInt32 ezGameObject::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.
|
inline |
Returns the 'team ID' that was given during creation (/see ezGameObjectDesc)
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.
ezVisibilityState::Enum ezGameObject::GetVisibilityState | ( | ezUInt32 | 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.
uiNumFramesBeforeInvisible | Used to treat an object that was visible and just became invisible as visible for a few more frames. |
EZ_ALWAYS_INLINE bool ezGameObject::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.
void ezGameObject::PostEventMessage | ( | ezMessage & | ref_msg, |
const ezComponent * | pSenderComponent, | ||
ezTime | delay, | ||
ezObjectMsgQueueType::Enum | queueType = ezObjectMsgQueueType::NextFrame |
||
) | const |
Delivers an ezEventMessage to the closest (parent) object containing an ezEventMessageHandlerComponent.
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 ezEventMessageHandlerComponent (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 ezEventMessageHandlerComponent 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.
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 ezEventMessage::m_hSenderObject and ezEventMessage::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 ezGameObject'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. |
ezGameObject * ezGameObject::SearchForChildByNameSequence | ( | ezStringView | sObjectSequence, |
const ezRTTI * | 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).
void ezGameObject::SearchForChildrenByNameSequence | ( | ezStringView | sObjectSequence, |
const ezRTTI * | pExpectedComponent, | ||
ezHybridArray< ezGameObject *, 8 > & | out_objects | ||
) |
Same as SearchForChildByNameSequence but returns ALL matches, in case the given path could mean multiple objects.
bool ezGameObject::SendEventMessage | ( | ezMessage & | ref_msg, |
const ezComponent * | pSenderComponent | ||
) |
Delivers an ezEventMessage to the closest (parent) object containing an ezEventMessageHandlerComponent.
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 ezEventMessageHandlerComponent (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 ezEventMessageHandlerComponent 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.
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 ezEventMessage::m_hSenderObject and ezEventMessage::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 ezGameObject's team-ID, it can detect which player fired the projectile). |
bool ezGameObject::SendEventMessage | ( | ezMessage & | ref_msg, |
const ezComponent * | pSenderComponent | ||
) | const |
Delivers an ezEventMessage to the closest (parent) object containing an ezEventMessageHandlerComponent.
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 ezEventMessageHandlerComponent (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 ezEventMessageHandlerComponent 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.
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 ezEventMessage::m_hSenderObject and ezEventMessage::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 ezGameObject's team-ID, it can detect which player fired the projectile). |
EZ_ALWAYS_INLINE bool ezGameObject::SendMessage | ( | ezMessage & | ref_msg | ) |
Sends a message to all components of this object.
Returns true, if there was any recipient for this type of message.
EZ_ALWAYS_INLINE bool ezGameObject::SendMessage | ( | ezMessage & | ref_msg | ) | const |
Sends a message to all components of this object.
Returns true, if there was any recipient for this type of message.
EZ_ALWAYS_INLINE bool ezGameObject::SendMessageRecursive | ( | ezMessage & | ref_msg | ) |
Sends a message to all components of this object and then recursively to all children.
Returns true, if there was any recipient for this type of message.
EZ_ALWAYS_INLINE bool ezGameObject::SendMessageRecursive | ( | ezMessage & | ref_msg | ) | const |
Sends a message to all components of this object and then recursively to all children.
Returns true, if there was any recipient for this type of message.
void ezGameObject::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.
EZ_ALWAYS_INLINE void ezGameObject::SetLocalPosition | ( | ezVec3 | vPosition | ) |
Changes the position of the object local to its parent.
EZ_ALWAYS_INLINE void ezGameObject::SetStableRandomSeed | ( | ezUInt32 | 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.