SceneObject Class Reference

Description

An object in the scene graph.

It has a world position, place in the hierarchy and optionally a number of attached components.

Inherits GameObject.

Methods

void destroy (bool immediate=false)
 Destroys this object and any of its held components. More...
 
HSceneObject getHandle () const
 Returns a handle to this object. More...
 
String getPrefabLink (bool onlyDirect=false) const
 Returns the UUID of the prefab this object is linked to, if any. More...
 
HSceneObject getPrefabParent () const
 Returns the root object of the prefab instance that this object belongs to, if any. More...
 
void breakPrefabLink ()
 Breaks the link between this prefab instance and its prefab. More...
 
bool hasFlag (UINT32 flag) const
 Checks if the scene object has a specific bit flag set. More...
 
void setPosition (const Vector3 &position)
 Sets the local position of the object. More...
 
const Vector3getPosition () const
 Gets the local position of the object. More...
 
void setWorldPosition (const Vector3 &position)
 Sets the world position of the object. More...
 
const Vector3getWorldPosition () const
 Gets the world position of the object. More...
 
void setRotation (const Quaternion &rotation)
 Sets the local rotation of the object. More...
 
const QuaterniongetRotation () const
 Gets the local rotation of the object. More...
 
void setWorldRotation (const Quaternion &rotation)
 Sets the world rotation of the object. More...
 
const QuaterniongetWorldRotation () const
 Gets world rotation of the object. More...
 
void setScale (const Vector3 &scale)
 Sets the local scale of the object. More...
 
const Vector3getScale () const
 Gets the local scale of the object. More...
 
void setWorldScale (const Vector3 &scale)
 Sets the world scale of the object. More...
 
const Vector3getWorldScale () const
 Gets world scale of the object. More...
 
void lookAt (const Vector3 &location, const Vector3 &up=Vector3::UNIT_Y)
 Orients the object so it is looking at the provided location (world space) where up is used for determining the location of the object's Y axis.
 
const Matrix4getWorldTfrm () const
 Gets the objects world transform matrix. More...
 
Matrix4 getInvWorldTfrm () const
 Gets the objects inverse world transform matrix. More...
 
const Matrix4getLocalTfrm () const
 Gets the objects local transform matrix. More...
 
void move (const Vector3 &vec)
 Moves the object's position by the vector offset provided along world axes. More...
 
void moveRelative (const Vector3 &vec)
 Moves the object's position by the vector offset provided along it's own axes (relative to orientation). More...
 
Vector3 getForward () const
 Gets the Z (forward) axis of the object, in world space. More...
 
Vector3 getUp () const
 Gets the Y (up) axis of the object, in world space. More...
 
Vector3 getRight () const
 Gets the X (right) axis of the object, in world space. More...
 
void setForward (const Vector3 &forwardDir)
 Rotates the game object so it's forward axis faces the provided direction. More...
 
void rotate (const Vector3 &axis, const Radian &angle)
 Rotate the object around an arbitrary axis. More...
 
void rotate (const Quaternion &q)
 Rotate the object around an arbitrary axis using a Quaternion. More...
 
void roll (const Radian &angle)
 Rotates around local Z axis. More...
 
void yaw (const Radian &angle)
 Rotates around Y axis. More...
 
void pitch (const Radian &angle)
 Rotates around X axis. More...
 
void updateTransformsIfDirty ()
 Forces any dirty transform matrices on this object to be updated. More...
 
UINT32 getTransformHash () const
 Returns a hash value that changes whenever a scene objects transform gets updated. More...
 
void setParent (const HSceneObject &parent, bool keepWorldTransform=true)
 Changes the parent of this object. More...
 
HSceneObject getParent () const
 Gets the parent of this object. More...
 
HSceneObject getChild (UINT32 idx) const
 Gets a child of this item. More...
 
int indexOfChild (const HSceneObject &child) const
 Find the index of the specified child. More...
 
UINT32 getNumChildren () const
 Gets the number of all child GameObjects. More...
 
HSceneObject findChild (const String &name, bool recursive=true)
 Searches the child objects for an object matching the specified name. More...
 
Vector< HSceneObjectfindChildren (const String &name, bool recursive=true)
 Searches the child objects for objects matching the specified name. More...
 
void setActive (bool active)
 Enables or disables this object. More...
 
bool getActive (bool self=false)
 Returns whether or not an object is active. More...
 
void setMobility (ObjectMobility mobility)
 Sets the mobility of a scene object. More...
 
ObjectMobility getMobility () const
 Gets the mobility setting for this scene object. More...
 
HSceneObject clone (bool instantiate=true)
 Makes a deep copy of this object. More...
 
template<class T , class... Args>
GameObjectHandle< T > addComponent (Args &&...args)
 Constructs a new component of the specified type and adds it to the internal component list. More...
 
HComponent addComponent (UINT32 typeId)
 Constructs a new component of the specified type id and adds it to the internal component list. More...
 
template<typename T >
GameObjectHandle< T > getComponent ()
 Searches for a component with the specific type and returns the first one it finds. More...
 
template<typename T >
Vector< GameObjectHandle< T > > getComponents ()
 Returns all components with the specific type. More...
 
template<typename T >
bool hasComponent ()
 Checks if the current object contains the specified component or components derived from the provided type. More...
 
HComponent getComponent (RTTITypeBase *type) const
 Searches for a component with the specified type and returns the first one it finds. More...
 
void destroyComponent (const HComponent component, bool immediate=false)
 Removes the component from this object, and deallocates it. More...
 
void destroyComponent (Component *component, bool immediate=false)
 Removes the component from this object, and deallocates it. More...
 
const Vector< HComponent > & getComponents () const
 Returns all components on this object. More...
 
RTTITypeBasegetRTTI () const override
 Returns an interface you can use to access class' Run Time Type Information. More...
 
Internal
void _setInstanceData (GameObjectInstanceDataPtr &other) override
 Replaces the instance data with another objects instance data. More...
 
void _instantiate (bool prefabOnly=false)
 Register the scene object with the scene and activate all of its components. More...
 
void _clearPrefabDiff ()
 Clears the internally stored prefab diff. More...
 
const String_getPrefabLinkUUID () const
 Returns the UUID of the prefab this object is linked to, if any. More...
 
void _setPrefabLinkUUID (const String &UUID)
 Allows you to change the prefab link UUID of this object. More...
 
const SPtr< PrefabDiff > & _getPrefabDiff () const
 Returns a prefab diff object containing instance specific modifications of this object compared to its prefab reference, if any.
 
void _setPrefabDiff (const SPtr< PrefabDiff > &diff)
 Assigns a new prefab diff object. More...
 
void _setFlags (UINT32 flags)
 Recursively enables the provided set of flags on this object and all children. More...
 
void _unsetFlags (UINT32 flags)
 Recursively disables the provided set of flags on this object and all children. More...
 
- Methods inherited from GameObject
UINT64 getInstanceId () const
 Returns the unique instance ID of the GameObject. More...
 
UINT32 getLinkId () const
 Returns an ID that identifies a link between this object and its equivalent in the linked prefab. More...
 
const StringgetName () const
 Gets the name of the object. More...
 
void setName (const String &name)
 Sets the name of the object. More...
 
void _setIsDestroyed ()
 Marks the object as destroyed. More...
 
bool _getIsDestroyed () const
 Checks if the object has been destroyed. More...
 
void _setLinkId (UINT32 id)
 Changes the prefab link ID for this object. More...
 
virtual GameObjectInstanceDataPtr _getInstanceData () const
 Returns instance data that identifies this GameObject and is used for referencing by game object handles. More...
 
- Methods inherited from IReflectable
bool isDerivedFrom (RTTITypeBase *base)
 Returns true if current RTTI class is derived from base (Or if it is the same type as base). More...
 
UINT32 getTypeId () const
 Returns an unique type identifier of the class. More...
 
const StringgetTypeName () const
 Returns the type name of the class. More...
 

Static methods

static HSceneObject create (const String &name, UINT32 flags=0)
 Creates a new SceneObject with the specified name. More...
 
static RTTITypeBasegetRTTIStatic ()
 
- Static methods inherited from GameObject
static RTTITypeBasegetRTTIStatic ()
 
- Static methods inherited from IReflectable
static Vector< RTTITypeBase * > & getDerivedClasses ()
 Returns all classes deriving directly from IReflectable. More...
 
static SPtr< IReflectablecreateInstanceFromTypeId (UINT32 rttiTypeId)
 Creates an empty instance of a class from a type identifier. More...
 
static void _registerDerivedClass (RTTITypeBase *derivedClass)
 Called by each type deriving from IReflectable, on program load. More...
 
static RTTITypeBase_getRTTIfromTypeId (UINT32 rttiTypeId)
 Returns class' RTTI type from type id. More...
 
static bool _isTypeIdDuplicate (UINT32 typeId)
 Checks if the provided type id is unique. More...
 
static void _checkForCircularReferences ()
 Iterates over all RTTI types and reports any circular references (for example one type having a field referencing another type, and that type having a field referencing the first type). More...
 
static RTTITypeBasegetRTTIStatic ()
 Returns an interface you can use to access class' Run Time Type Information. More...
 

Method documentation

void _clearPrefabDiff ( )

Clears the internally stored prefab diff.

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

const String& _getPrefabLinkUUID ( ) const

Returns the UUID of the prefab this object is linked to, if any.

Unlike getPrefabLink() method this will not search parents, but instead return only the value assigned to this object.

void _instantiate ( bool  prefabOnly = false)

Register the scene object with the scene and activate all of its components.

Parameters
[in]prefabOnlyIf true, only objects within the current prefab will be instantiated. If false all child objects and components will.
void _setFlags ( UINT32  flags)

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

void _setInstanceData ( GameObjectInstanceDataPtr &  other)
overridevirtual

Replaces the instance data with another objects instance data.

This object will basically become the original owner of the provided instance data as far as all game object handles referencing it are concerned.

Note
No alive objects should ever be sharing the same instance data. This can be used for restoring dead handles.

Reimplemented from GameObject.

void _setPrefabDiff ( const SPtr< PrefabDiff > &  diff)

Assigns a new prefab diff object.

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

void _setPrefabLinkUUID ( const String UUID)

Allows you to change the prefab link UUID of this object.

Normally this should be accompanied by reassigning the link IDs.

void _unsetFlags ( UINT32  flags)

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

GameObjectHandle<T> addComponent ( Args &&...  args)

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

HComponent addComponent ( UINT32  typeId)

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

Component must have a parameterless constructor.

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.

HSceneObject clone ( bool  instantiate = true)

Makes a deep copy of this object.

Parameters
[in]instantiateIf false, the cloned hierarchy will just be a memory copy, but will not be present in the scene or otherwise active until instantiate() is called.
static HSceneObject create ( const String name,
UINT32  flags = 0 
)
static

Creates a new SceneObject with the specified name.

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

Parameters
[in]nameName of the scene object.
[in]flagsOptional flags that control object behavior. See SceneObjectFlags.
void destroy ( bool  immediate = false)

Destroys this object and any of its held components.

Parameters
[in]immediateIf true, the object will be deallocated and become unusable right away. Otherwise the deallocation will be delayed to the end of frame (preferred method).
void destroyComponent ( const HComponent  component,
bool  immediate = false 
)

Removes the component from this object, and deallocates it.

Parameters
[in]componentThe component to destroy.
[in]immediateIf true, the component will be deallocated and become unusable right away. Otherwise the deallocation will be delayed to the end of frame (preferred method).
void destroyComponent ( Component component,
bool  immediate = false 
)

Removes the component from this object, and deallocates it.

Parameters
[in]componentThe component to destroy.
[in]immediateIf true, the component will be deallocated and become unusable right away. Otherwise the deallocation will be delayed to the end of frame (preferred method).
HSceneObject findChild ( const String name,
bool  recursive = true 
)

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

Parameters
[in]nameName of the object to locate.
[in]recursiveIf 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.
Vector<HSceneObject> findChildren ( const String name,
bool  recursive = true 
)

Searches the child objects for objects matching the specified name.

Parameters
[in]nameName of the objects to locate.
[in]recursiveIf true all descendants of the scene object will be searched, otherwise only immediate children.
Returns
All scene objects matching the specified name.
bool getActive ( bool  self = false)

Returns whether or not an object is active.

Parameters
[in]selfIf 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.
HSceneObject getChild ( UINT32  idx) const

Gets a child of this item.

Parameters
[in]idxThe zero based index of the child.
Returns
SceneObject of the child.
GameObjectHandle<T> getComponent ( )

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

Will also return components derived from the type.

Template Parameters
TType of the component.
Returns
Component if found, nullptr otherwise.
Note
Don't call this too often as it is relatively slow. It is more efficient to call it once and store the result for further use.
HComponent getComponent ( RTTITypeBase 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.

Parameters
[in]typeRTTI information for the type.
Returns
Component if found, nullptr otherwise.
Note
Don't call this too often as it is relatively slow. It is more efficient to call it once and store the result for further use.
Vector<GameObjectHandle<T> > getComponents ( )

Returns all components with the specific type.

Will also return components derived from the type.

Template Parameters
typenameT Type of the component.
Returns
Array of found components.
Note
Don't call this too often as it is relatively slow. It is more efficient to call it once and store the result for further use.
const Vector<HComponent>& getComponents ( ) const

Returns all components on this object.

Vector3 getForward ( ) const

Gets the Z (forward) axis of the object, in world space.

Returns
Forward axis of the object.
HSceneObject getHandle ( ) const

Returns a handle to this object.

Matrix4 getInvWorldTfrm ( ) const

Gets the objects inverse world transform matrix.

Note
Performance warning: This might involve updating the transforms if the transform is dirty.
const Matrix4& getLocalTfrm ( ) const

Gets the objects local transform matrix.

ObjectMobility getMobility ( ) const

Gets the mobility setting for this scene object.

See setMobility();

UINT32 getNumChildren ( ) const

Gets the number of all child GameObjects.

HSceneObject getParent ( ) const

Gets the parent of this object.

Returns
Parent object, or nullptr if this SceneObject is at root level.
const Vector3& getPosition ( ) const

Gets the local position of the object.

String getPrefabLink ( bool  onlyDirect = false) const

Returns the UUID of the prefab this object is linked to, if any.

Parameters
[in]onlyDirectIf true, this method will return prefab link only for the root object of the prefab instance. If false the parent objects will be searched for the prefab ID.
HSceneObject getPrefabParent ( ) const

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

Returns null if the object is not part of a prefab instance.

Vector3 getRight ( ) const

Gets the X (right) axis of the object, in world space.

Returns
Right axis of the object.
const Quaternion& getRotation ( ) const

Gets the local rotation of the object.

RTTITypeBase* getRTTI ( ) const
overridevirtual

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

Note
You must derive your own version of RTTITypeBase, in which you may encapsulate all reflection specific operations.

Reimplemented from GameObject.

const Vector3& getScale ( ) const

Gets the local scale of the object.

UINT32 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.

Vector3 getUp ( ) const

Gets the Y (up) axis of the object, in world space.

Returns
Up axis of the object.
const Vector3& getWorldPosition ( ) const

Gets the world position of the object.

Note
Performance warning: This might involve updating the transforms if the transform is dirty.
const Quaternion& getWorldRotation ( ) const

Gets world rotation of the object.

Note
Performance warning: This might involve updating the transforms if the transform is dirty.
const Vector3& getWorldScale ( ) const

Gets world scale of the object.

Note
Performance warning: This might involve updating the transforms if the transform is dirty.
const Matrix4& getWorldTfrm ( ) const

Gets the objects world transform matrix.

Note
Performance warning: This might involve updating the transforms if the transform is dirty.
bool hasComponent ( )

Checks if the current object contains the specified component or components derived from the provided type.

Template Parameters
typenameT Type of the component.
Returns
True if component exists on the object.
Note
Don't call this too often as it is relatively slow.
bool hasFlag ( UINT32  flag) const

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

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.

Parameters
[in]childThe child to look for.
Returns
The zero-based index of the found child, or -1 if no match was found.
void move ( const Vector3 vec)

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

void moveRelative ( const Vector3 vec)

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

void pitch ( const Radian angle)

Rotates around X axis.

Parameters
[in]angleAngle to rotate by.
void roll ( const Radian angle)

Rotates around local Z axis.

Parameters
[in]angleAngle to rotate by.
void rotate ( const Vector3 axis,
const Radian angle 
)

Rotate the object around an arbitrary axis.

void rotate ( const Quaternion q)

Rotate the object around an arbitrary axis using a Quaternion.

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.

void setForward ( const Vector3 forwardDir)

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

Parameters
[in]forwardDirThe forward direction to face, in world space.
Note
Local forward axis is considered to be negative Z.
void setMobility ( ObjectMobility  mobility)

Sets 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.

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.

Parameters
[in]parentNew parent.
[in]keepWorldTransformDetermines should the current transform be maintained even after the parent is changed (this means the local transform will be modified accordingly).
void setPosition ( const Vector3 position)

Sets the local position of the object.

void setRotation ( const Quaternion rotation)

Sets the local rotation of the object.

void setScale ( const Vector3 scale)

Sets the local scale of the object.

void setWorldPosition ( const Vector3 position)

Sets the world position of the object.

void setWorldRotation ( const Quaternion rotation)

Sets the world rotation of the object.

void setWorldScale ( const Vector3 scale)

Sets the world scale of the object.

Note
This will not work properly if this object or any of its parents have non-affine transform matrices.
void updateTransformsIfDirty ( )

Forces any dirty transform matrices on this object to be updated.

Note
Normally this is done internally when retrieving a transform, but sometimes it is useful to update transforms manually.
void yaw ( const Radian angle)

Rotates around Y axis.

Parameters
[in]angleAngle to rotate by.