class
Component
Components represent primary logic elements in the scene.
They are attached to scene objects.
You should implement some or all of Update/FixedUpdate/OnCreated/OnBeginPlay/OnEnabled/OnDisabled/ OnTransformChanged/OnDestroyed methods to implement the relevant component logic. Avoid putting logic in constructors or destructors.
Components can be in different states. These states control which of the events listed above trigger:
- Running - Scene manager is sending out events.
- Paused - Scene manager is sending out all events except per-frame update().
- Stopped - Scene manager is not sending out events except for OnCreated/OnDestroyed.
These states can be changed globally though SceneManager and affect all components. Individual components can override these states in two ways:
- Set the ComponentFlag::AlwaysRun to true and the component will always stay in Running state, regardless of state set in SceneManager. This flag should be set in constructor and not change during component lifetime.
- If the component's parent SceneObject is inactive (SceneObject::setActive(false)), or any of his parents are inactive, then the component is considered to be in Stopped state, regardless whether the ComponentFlag::AlwaysRun flag is set or not.
Public
Methods
~Component
GetHandle
Returns a handle to this object.
SceneObject
Returns the SceneObject this Component is assigned to.
SO
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.
Update
Called once per frame.
Only called if the component is in Running state.
FixedUpdate
Called at fixed time intervals (e.g. 60 times per frame).
Generally any physics-related functionality should go in this method in order to ensure stability of calculations. Only called if the component is in Running state.
CalculateBounds
Calculates bounds of the visible contents represented by this component (for example a mesh for Renderable).
- bounds
- Bounds of the contents in world space coordinates.
Returns: True if the component has bounds with non-zero volume, otherwise false.
TypeEquals
Checks if this and the provided component represent the same type.
Destroy
Removes the component from parent SceneObject and deletes it.
All the references to this component will be marked as destroyed and you will get an exception if you try to use them.
- immediate
- If true the destruction will be performed immediately, otherwise it will be delayed until the end of the current frame (preferred option).
SetEnabled
Enables or disables this object.
Disabled component is not updated.
GetEnabled
Returns whether or not an object is enabled.
- self
- If true, the method will only check if this particular object was enabled or disabled directly via SetEnabled. If false we also check if any of the objects parents are disabled.
CreateECSEntity
Creates an ECS entity in the provided registry and adds default fragments.
Asserts if entity already exists.
staticGetRttiStatic
Internal
Methods
Initialize
Construct any resources the component needs before use.
Called when the parent scene object is initialized. A non-initialized component shouldn't be used in a live scene (i.e. it should not receive any of the component logic updates or events).
SetNotifyFlags
Sets new flags that determine when is onTransformChanged called.
RefreshEnabledState
Sets or unsets the disable state flag depending on the enabled state of the parent and the component itself.
GetNotifyFlags
Gets the currently assigned notify flags.
See SetNotifyFlagsInternal().
Protected
Constructors
Component
Component
Methods
OnCreated
Called once when the component has been created.
Called regardless of the state the component is in.
OnBeginPlay
Called once when the component first leaves the Stopped state.
This includes component creation if requirements for leaving Stopped state are met, in which case it is called after OnCreated. Note this is called even if the component is in disabled state.
OnDestroyed
Called once just before the component is destroyed.
Called regardless of the state the component is in.
OnDisabled
Called every time a component is placed into the Stopped state.
This includes component destruction if component wasn't already in Stopped state during destruction. When called during destruction it is called before OnDestroyed.
OnEnabled
Called every time a component leaves the Stopped state, if the component is enabled.
This includes component creation if requirements for leaving the Stopped state are met. When called during creation it is called after OnBeginPlay.
OnTransformChanged
Called when the component's parent scene object has changed.
Not called if the component is in Stopped state. Also only called if necessary notify flags are set via SetNotifyFlagsInternal().
OnSceneChanged
Called when the parent SceneObject's ECS entity is migrated to a new registry (e.g. when moving between scenes).
The old scene and entity are provided so that components can access sub-systems (renderer, physics, etc.) and read any data stored only in ECS fragments.
DestroyImmediate
Destroys the component without delay.
Object will be removed from its game object collection, and reference to the object in all active handles will become null. If is specified, the component will be removed from the parent's child list, otherwise it's expected the caller to perform the removal.
QueueForDestroy
Queues the component to be destroyed at the end of the frame.
If is specified, the component will be removed from the parent's child list, otherwise it's expected the caller to perform the removal.
SupportsNotify
Checks whether the component wants to received the specified transform changed message.
SetFlag
Enables or disabled a flag controlling component's behaviour.
SetSceneManagerId
Sets an index that uniquely identifies a component with the SceneManager.
GetSceneManagerId
Returns an index that unique identifies a component with the SceneManager.