class `SceneObject`

Inherits: GameObject

An object in the scene graph.

It has a transform object that allows it to be positioned, scaled and rotated. It can have other scene objects as children, and will have a scene object as a parent, in which case transform changes to the parent are reflected to the child scene objects (children are relative to the parent).

Each scene object can have one or multiple Components attached to it, where the components inherit the scene object's transform, and receive updates about transform and hierarchy changes.

Public

Methods

~SceneObject

~SceneObject() noexcept

staticCreate

static HSceneObject Create(const String &name, u32 flags = 0)

Creates a new SceneObject with the specified name.

Object will be placed in the top of the scene hierarchy.

name: Name of the scene object.
flags: Optional flags that control object behavior. See SceneObjectFlags.

Destroy

void Destroy(bool immediate = false)

Destroys this object and any of its held components.

immediate: If true, the object will be deallocated and become unusable right away. Otherwise the deallocation will be delayed to the end of frame (preferred method).

GetHandle

HSceneObject GetHandle() const

Returns a handle to this object.

GetPrefabResourceId

const UUID &GetPrefabResourceId() const

Identifies the prefab resource this object is linked to.

Will return an empty ID if the object is not linked to a prefab.

GetPrefabVersion

const UUID &GetPrefabVersion() const

Returns the version of the prefab the prefab instance was created from.

Not relevant if the object is not a prefab instance.

IsPrefabInstanceRoot

bool IsPrefabInstanceRoot() const

Returns true if this object is linked to a prefab (See IsPrefabInstance()), and is the root of the prefab instance hierarchy (i.e. its parent is either not linked to a prefab, or linked to a different prefab).

GetPrefabInstanceRoot

HSceneObject GetPrefabInstanceRoot() const

Returns the root object of the prefab instance that this object belongs to, if any.

Returns null if the object is not a prefab instance.

BreakPrefabLink

void BreakPrefabLink()

Breaks the link between this prefab instance and its prefab.

Object will retain all current values but will no longer be influenced by modifications to its parent prefab, nor will you be able to apply changes from this object to the prefab resource.

HasFlag

bool HasFlag(SceneObjectFlag flag) const

Checks if the scene object has a specific bit flag set.

GetTransform

const Transform &GetTransform() const

Gets the transform object representing object's position/rotation/scale in world space.

UpdateWorldTransformIfDirty

void UpdateWorldTransformIfDirty() const

Updates the world transform if it is dirty.

GetLocalTransform

const Transform &GetLocalTransform() const

Gets the transform object representing object's position/rotation/scale relative to its parent.

SetLocalTransform

void SetLocalTransform(const Transform &transform)

Sets a new transform for the object, relative to the parent.

SetPosition

void SetPosition(const Vector3 &position)

Sets the local position of the object.

SetWorldPosition

void SetWorldPosition(const Vector3 &position)

Sets the world position of the object.

SetRotation

void SetRotation(const Quaternion &rotation)

Sets the local rotation of the object.

SetWorldRotation

void SetWorldRotation(const Quaternion &rotation)

Sets the world rotation of the object.

SetScale

void SetScale(const Vector3 &scale)

Sets the local scale of the object.

SetWorldScale

void SetWorldScale(const Vector3 &scale)

Sets the world scale of the object.

LookAt

void LookAt(const Vector3 &location, const Vector3 &up = Vector3::kUnitY)

Orients the object so it is looking at the provided (world space) where is used for determining the location of the object's Y axis.

GetWorldMatrix

Matrix4 GetWorldMatrix() const

Gets the objects world transform matrix.

GetInvWorldMatrix

Matrix4 GetInvWorldMatrix() const

Gets the objects inverse world transform matrix.

GetLocalMatrix

Matrix4 GetLocalMatrix() const

Gets the objects local transform matrix.

Move

void Move(const Vector3 &vec)

Moves the object's position by the vector offset provided along world axes.

MoveRelative

void MoveRelative(const Vector3 &vec)

Moves the object's position by the vector offset provided along it's own axes (relative to orientation).

SetForward

void SetForward(const Vector3 &forwardDir)

Rotates the game object so it's forward axis faces the provided direction.

forwardDir: The forward direction to face, in world space.

Rotate

void Rotate(const Vector3 &axis, const Radian &angle)

Rotate the object around an arbitrary axis.

Rotate

void Rotate(const Quaternion &q)

Rotate the object around an arbitrary axis using a Quaternion.

Roll

void Roll(const Radian &angle)

Rotates around local Z axis.

angle: Angle to rotate by.

Yaw

void Yaw(const Radian &angle)

Rotates around Y axis.

angle: Angle to rotate by.

Pitch

void Pitch(const Radian &angle)

Rotates around X axis

angle: Angle to rotate by.

GetTransformHash

u32 GetTransformHash() const

Returns a hash value that changes whenever a scene objects transform gets updated.

It allows you to detect changes with the local or world transforms without directly comparing their values with some older state.

CreateECSEntity

void CreateECSEntity(ecs::Registry *registry) override

Creates an ECS entity in the provided registry and adds default fragments.

Asserts if entity already exists.

SetParent

void SetParent(const HSceneObject &parent, bool keepWorldTransform = true)

Changes the parent of this object.

Also removes the object from the current parent, and assigns it to the new parent.

parent: New parent.
keepWorldTransform: Determines should the current transform be maintained even after the parent is changed (this means the local transform will be modified accordingly).

GetParent

HSceneObject GetParent() const

Gets the parent of this object.

Returns: Parent object, or nullptr if this SceneObject is at root level.

GetChild

HSceneObject GetChild(u32 idx) const

Gets a child of this item.

idx: The zero based index of the child.

Returns: SceneObject of the child.

IndexOfChild

int IndexOfChild(const HSceneObject &child) const

Find the index of the specified child.

Don't persist this value as it may change whenever you add/remove children.

child: The child to look for.

Returns: The zero-based index of the found child, or -1 if no match was found.

GetChildCount

u32 GetChildCount() const

Gets the number of all child scene objects.

IterateHierarchy

void IterateHierarchy(const Function<bool (const HSceneObject &)> &onSceneObjectFound, const Function<void (const HComponent &)> &onComponentFound, bool visitSelf = true) const

Iterates over all the components on this object, and then does the same on all child scene objects recursively.

Calls a callback for each component and scene object.

onSceneObjectFound: Called for every child object. If the callback returns false, iteration will stop. If is true, it's also called on the root object itself. May be null.
onComponentFound: Called for every component. May be null.
visitSelf: If true, will be called for the root object.

GetScene

SPtr<SceneInstance> GetScene() const

Returns the scene this object is part of.

Can be null if scene object hasn't been instantiated.

FindPath

HSceneObject FindPath(const String &path) const

Searches the scene object hierarchy to find a child scene object using the provided path.

path: Path to the property, where each element of the path is separated with "/" Path elements signify names of child scene objects (first one relative to this object).

FindChild

HSceneObject FindChild(const String &name, bool recursive = true)

Searches the child objects for an object matching the specified name.

name: Name of the object to locate.
recursive: If true all descendants of the scene object will be searched, otherwise only immediate children.

Returns: First found scene object, or empty handle if none found.

FindChildren

Vector<HSceneObject> FindChildren(const String &name, bool recursive = true)

Searches the child objects for objects matching the specified name.

name: Name of the objects to locate.
recursive: If true all descendants of the scene object will be searched, otherwise only immediate children.

Returns: All scene objects matching the specified name.

SetActive

void SetActive(bool active)

Enables or disables this object.

Disabled objects also implicitly disable all their child objects. No components on the disabled object are updated.

GetActive

bool GetActive(bool self = false) const

Returns whether or not an object is active.

self: If true, the method will only check if this particular object was activated or deactivated directly via SetActive. If false we we also check if any of the objects parents are inactive.

SetMobility

void SetMobility(ObjectMobility mobility)

Determines the mobility of a scene object.

This is used primarily as a performance hint to engine systems. Objects with more restricted mobility will result in higher performance. Some mobility constraints will be enforced by the engine itself, while for others the caller must be sure not to break the promise he made when mobility was set. By default scene object's mobility is unrestricted.

GetMobility

ObjectMobility GetMobility() const

Clone

HSceneObject Clone()

Makes a deep copy of this object (including all its children).

Cloned object will be parented to the same parent as this object.

AddComponent

HComponent AddComponent(u32 typeId)

Constructs a new component of the specified type id and adds it to the internal component list.

Component must have a parameterless constructor.

GetComponent

HComponent GetComponent(RTTIType *type) const

Searches for a component with the specified type and returns the first one it finds.

Will also return components derived from the type.

type: RTTI information for the type.

Returns: Component if found, nullptr otherwise.

GetComponents

const Vector<HComponent> &GetComponents() const

Returns all components on this object.

staticGetRttiStatic

static RTTIType *GetRttiStatic()

GetRtti

RTTIType *GetRtti() const override

Returns an interface you can use to access class' Run Time Type Information.

Internal

Methods

SetOwnerCollection

void SetOwnerCollection(const SPtr<GameObjectCollection> &collection) override

Changes the collection the game object is part of.

Game object will be unregistered with the old collection (if any) and registered with the new collection.

Initialize

void Initialize()

SetPrefabResourceId

void SetPrefabResourceId(const UUID &id)

ClearPrefabDelta

void ClearPrefabDelta()

Clears the internally stored prefab delta.

If this object is updated from prefab its instance specific changes will be lost.

GetPrefabDelta

const SPtr<SceneObjectHierarchyDelta> &GetPrefabDelta() const

Returns a prefab delta object containing instance specific modifications of this object compared to its prefab reference, if any.

SetPrefabDelta

void SetPrefabDelta(const SPtr<SceneObjectHierarchyDelta> &delta)

Assigns a new prefab delta.

Caller must ensure the prefab delta was generated for this object.

SetPrefabVersion

void SetPrefabVersion(const UUID &version)

SetFlags

void SetFlags(SceneObjectFlags flags)

Recursively enables the provided set of flags on this object and all children.

UnsetFlags

void UnsetFlags(SceneObjectFlags flags)

Recursively disables the provided set of flags on this object and all children.

ClearParent

void ClearParent()

Sets the current scene parent to null.

Only useful if an object is replacing an existing scene instance root.

Clone

HSceneObject Clone(const SPtr<GameObjectCollection> &cloneOwnerCollection, bool preserveIds = false)

Makes a deep copy of this object (including all its children).

The cloned objects will not be parented to any scene object, not be associated with any scene instance and not initialized.

cloneOwnerCollection: Collection into which to place the cloned scene objects. If is true this must be a different collection that the current scene object, otherwise IDs would conflict. The collection's ECS registry will be used for the cloned hierarchy's entities and components.
preserveIds: If false, each cloned game object will be assigned a brand new ID. Otherwise the ID of the original game objects will be preserved.

Returns: Cloned scene object hierarchy.

Clone

HSceneObject Clone(const SPtr<SceneInstance> &cloneSceneInstance, bool initialize = true, bool preserveIds = false)

Makes a deep copy of this object (including all its children).

Cloned object will be parented to the root of the provided scene instance.

cloneSceneInstance: Scene instance into which to place the cloned scene objects. If is true this must be a different scene instance that the current scene object, otherwise IDs would conflict.
initialize: If false, the cloned hierarchy will just be a memory copy, but will not be present in the scene or otherwise active until Initialize() is called.
preserveIds: If false, each cloned game object will be assigned a brand new ID. Otherwise the ID of the original game objects will be preserved.

Returns: Cloned scene object hierarchy.

GetMutableComponents

Vector<HComponent> &GetMutableComponents()

Returns a modifyable list of all components on this object.

RemoveComponent

void RemoveComponent(const HComponent &component)

Removes the component from the internal component list.

This shouldn't be called externally, use Component::Destroy() instead.

Private

Constructors

SceneObject

SceneObject(const String &name, u32 flags)

Methods

staticCreateInternal

static HSceneObject CreateInternal(const SPtr<GameObjectCollection> &ownerCollection, const String &name, u32 flags = 0)

Creates a new SceneObject instance and registers it with the game object collection, and returns a handle to the new object.

ownerCollection: Collection to register the scene object with.
name: Name of the scene object.
flags: Optional flags that control scene object behaviour.

staticCreateInternal

static HSceneObject CreateInternal(const SPtr<GameObjectCollection> &ownerCollection, const SPtr<SceneObject> &sceneObject)

Registers an existing SceneObject instance with the game object collection, and returns a handle to the object.

ownerCollection: Collection to register the scene object with.
sceneObject: Scene object to register.

DestroyImmediate

void DestroyImmediate() override

Destroys the game object without delay.

Object will be removed from its game object collection, and reference to the object in all active handles will become null. If the object contains any child objects or components, those will be destroyed as well.

QueueForDestroy

void QueueForDestroy() override

Queues the provided game object to be destroyed at the end of the frame.

If the object contains any child objects or components, those will be queued for destroy as well. Object will not be removed from any parent's child or component list.

AddMobilityTag

void AddMobilityTag(ObjectMobility mobility)

Adds the ECS mobility tag for the given mobility.

For fresh entities with no existing tags.

IsMovable

bool IsMovable() const

Returns true if the scene object can be moved.

This is true if the object has ObjectMobility::Movable mobility.

GetMutableLocalTransform

Transform &GetMutableLocalTransform()

Returns a mutable reference to the local transform stored in the ECS registry.

GetMutableWorldTransform

Transform &GetMutableWorldTransform()

Returns a mutable reference to the world transform stored in the ECS registry.

UpdateHierarchyDepthFromParent

void UpdateHierarchyDepthFromParent()

Recomputes hierarchy depth based on current parent and propagates to all descendants.

UpdateHierarchyDepthRecursive

void UpdateHierarchyDepthRecursive(u16 hierarchyDepth)

Assigns hierarchy depth to this object and descendants, increasing by one per hierarchy level.

NotifyTransformChanged

void NotifyTransformChanged(TransformChangedFlags flags) const

Notifies components and child scene object that a transform has been changed.

flags: Specifies in what way was the transform changed.

UpdateWorldTransform

void UpdateWorldTransform() const

Updates the world transform.

Reconstructs the local transform matrix and multiplies it with any parent transforms.

SetParentInternal

void SetParentInternal(const HSceneObject &parent, bool keepWorldTransform = true)

Internal version of setParent() that allows you to set a null parent.

parent: New parent.
keepWorldTransform: Determines should the current transform be maintained even after the parent is changed (this means the local transform will be modified accordingly).

SetScene

void SetScene(const SPtr<SceneInstance> &scene)

Changes the owning scene of the scene object and all children.

AddChild

void AddChild(const HSceneObject &object)

Adds a child to the child array.

This method doesn't check for null or duplicate values.

object: New child.

RemoveChild

void RemoveChild(const HSceneObject &object)

Removes the child from the object.

object: Child to remove.

SetActiveHierarchy

void SetActiveHierarchy(bool active, bool triggerEvents = true)

Changes the object active in hierarchy state, and triggers necessary events.

RegisterComponentWithOwnerCollection

HComponent RegisterComponentWithOwnerCollection(const SPtr<Component> &component)

Registers the provided component with the owner game object collection and returns the component handle.

InternalAddComponent

void InternalAddComponent(const HComponent &component, bool initialize)

Adds the component to the internal component array, and optionally initialized it.

Note the component will only be initialized if this scene object is initialized and

flag is true.

InternalAddComponent

void InternalAddComponent(const SPtr<Component> &component, bool initialize)

Equivalent to AddComponent(const HComponent & , bool), but internally looks up the component handle from the game object collection.

Fields

mPrefabResourceId

UUID mPrefabResourceId

Identifier of the prefab resource that this object is linked to, if any.

mPrefabVersion

UUID mPrefabVersion

mPrefabDelta

SPtr<SceneObjectHierarchyDelta> mPrefabDelta

mFlags

SceneObjectFlags mFlags

mDirtyHash

u32 mDirtyHash

mParentScene

WeakSPtr<SceneInstance> mParentScene

mParent

HSceneObject mParent

mChildren

Vector<HSceneObject> mChildren

mComponents

Vector<HComponent> mComponents