Class AnimatedModel

Performs an animation and renders a skinned model.

AnimatedModel
AnimatedModel
AnimatedModel
AnimatedModel
AnimatedModel
Assembly: FlaxEngine.dll
File: Engine/Level/Actors/AnimatedModel.h
Syntax
public class AnimatedModel : public ModelInstanceActor

Constructors

~AnimatedModel()

Declaration
public ~AnimatedModel()

DEPRECATED()

The shadows casting mode. [Deprecated on 26.10.2022, expires on 26.10.2024]

Declaration
public DEPRECATED() ShadowsCastingMode ShadowsMode

Fields

AnimationGraph

The animation graph asset used for the skinned mesh skeleton bones evaluation (controls the animation).

Declaration
public AssetReference<AnimationGraph> AnimationGraph
Field Value
AssetReference<AnimationGraph>

AnimationUpdated

Called after animation gets updated (new skeleton pose).

Declaration
public Action AnimationUpdated
Field Value
Action

BoundsScale

The master scale parameter for the actor bounding box. Helps reducing mesh flickering effect on screen edges.

Declaration
public float BoundsScale = 1.5f
Field Value
float

CustomBounds

The custom bounds(in actor local space). If set to empty bounds then source skinned model bind pose bounds will be used.

Declaration
public BoundingBox CustomBounds = BoundingBox::Zero
Field Value
BoundingBox

DrawModes

The draw passes to use for rendering this object.

Declaration
public DrawPass DrawModes = DrawPass::Default
Field Value
DrawPass

ForcedLOD

Gets the model forced Level Of Detail index. Allows to bind the given model LOD to show. Value -1 disables this feature.

Declaration
public int32 ForcedLOD = -1
Field Value
int32

GraphInstance

The graph instance data container. For dynamic usage only at runtime, not serialized.

Declaration
public AnimGraphInstanceData GraphInstance
Field Value
AnimGraphInstanceData

LODBias

The model Level Of Detail bias value. Allows to increase or decrease rendered model quality.

Declaration
public int32 LODBias = 0
Field Value
int32

PerBoneMotionBlur

If true, use per-bone motion blur on this skeletal model. It requires additional rendering, can be disabled to save performance.

Declaration
public bool PerBoneMotionBlur = true
Field Value
bool

RootMotionTarget

The animation root motion apply target. If not specified the animated model will apply it itself.

Declaration
public ScriptingObjectReference<Actor> RootMotionTarget
Field Value
ScriptingObjectReference<Actor>

ShowDebugDrawSkeleton

If checked, the skeleton pose will be shawn during debug shapes drawing.

Declaration
public bool ShowDebugDrawSkeleton = false
Field Value
bool

SkinnedModel

The skinned model asset used for rendering.

Declaration
public AssetReference<SkinnedModel> SkinnedModel
Field Value
AssetReference<SkinnedModel>

SortOrder

The object sort order key used when sorting drawable objects during rendering. Use lower values to draw object before others, higher values are rendered later (on top). Can be used to control transparency drawing.

Declaration
public int8 SortOrder = 0
Field Value
int8

UpdateMode

The animation update mode. Can be used to optimize the performance.

Declaration
public AnimationUpdateMode UpdateMode = AnimationUpdateMode::Auto
Field Value
AnimationUpdateMode

UpdateSpeed

The animation update delta time scale. Can be used to speed up animation playback or create slow motion effect.

Declaration
public float UpdateSpeed = 1.0f
Field Value
float

UpdateWhenOffscreen

If true, the animation will be updated even when an actor cannot be seen by any camera. Otherwise, the animations themselves will also stop running when the actor is off-screen.

Declaration
public bool UpdateWhenOffscreen = false
Field Value
bool

UseTimeScale

If true, animation speed will be affected by the global time scale parameter.

Declaration
public bool UseTimeScale = true
Field Value
bool

Methods

BeginPlay(SceneBeginData* data)

Called when adding object to the game.

Declaration
protected virtual void BeginPlay(SceneBeginData* data) override
Parameters
SceneBeginData data

The initialization data (e.g. used to collect joints to link after begin).
Overrides

ClearBlendShapeWeights()

Clears the weights of the blend shapes (disables any used blend shapes).

Declaration
public void ClearBlendShapeWeights()

Deserialize(DeserializeStream& stream, ISerializeModifier* modifier)

Deserializes object from the input stream.

Declaration
public virtual void Deserialize(DeserializeStream& stream, ISerializeModifier* modifier) override
Parameters
DeserializeStream stream

The input stream.
ISerializeModifier modifier

The deserialization modifier object. Always valid.
Overrides

Draw(RenderContext& renderContext)

Draws this actor. Called by Scene Rendering service. This call is more optimized than generic Draw (eg. geometry is rendered during all pass types but other actors are drawn only during GBufferFill pass).

Declaration
public virtual void Draw(RenderContext& renderContext) override
Parameters
RenderContext renderContext

The rendering context.
Overrides

Draw(RenderContextBatch& renderContextBatch)

Draws this actor. Called by Scene Rendering service. This call is more optimized than generic Draw (eg. geometry is rendered during all pass types but other actors are drawn only during GBufferFill pass).

Declaration
public virtual void Draw(RenderContextBatch& renderContextBatch) override
Parameters
RenderContextBatch renderContextBatch

The rendering context batch (eg, main view and shadow projections).
Overrides

EndPlay()

Called when removing object from the game.

Declaration
protected virtual void EndPlay() override
Overrides

FindClosestNode(const Vector3& location, bool worldSpace=false)

Finds the closest node to a given location.

Declaration
public int32 FindClosestNode(const Vector3& location, bool worldSpace=false) const
Parameters
Vector3 location

The text location (in local-space of the actor or world-space depending on worldSpace ).
bool worldSpace

True if convert input location is in world-space, otherwise it's in local-space of the actor.
Returns
int32

The zero-based index of the found node. Returns -1 if skeleton is missing.

GetBlendShapeWeight(const StringView& name)

Gets the weight of the blend shape.

Declaration
public float GetBlendShapeWeight(const StringView& name)
Parameters
StringView name

The blend shape name.
Returns
float

The normalized weight of the blend shape (in range -1:1).

GetCurrentPose(Array<Matrix>& nodesTransformation, bool worldSpace=false)

Gets the per-node final transformations (skeleton pose).

Declaration
public void GetCurrentPose(Array<Matrix>& nodesTransformation, bool worldSpace=false) const
Parameters
Array<Matrix> nodesTransformation

The output per-node final transformation matrices.
bool worldSpace

True if convert matrices into world-space, otherwise returned values will be in local-space of the actor.

GetEditorBox()

Gets actor bounding box (single actor, no children included) for editor tools.

Declaration
public virtual BoundingBox GetEditorBox() const override
Returns
BoundingBox

Overrides

GetEnableTracing()

Enables extracting animation playback insights for debugging or custom scripting.

Declaration
public bool GetEnableTracing() const
Returns
bool

GetMaterial(int32 entryIndex)

Gets the material used to draw the meshes which are assigned to that slot (set in Entries or model's default).

Declaration
public virtual MaterialBase* GetMaterial(int32 entryIndex) override
Parameters
int32 entryIndex

The material slot entry index.
Returns
MaterialBase

Overrides

GetMaterialSlots()

Gets the material slots array set on the asset (eg. model or skinned model asset).

Declaration
public virtual Span<MaterialSlot> GetMaterialSlots() const override
Returns
Span<MaterialSlot>

Overrides

GetMeshData(const MeshReference& ref, MeshBufferType type, BytesContainer& result, int32& count, GPUVertexLayout* *layout)

Extracts mesh buffer data from CPU. Might be cached internally (eg. by Model/SkinnedModel).

Declaration
public virtual bool GetMeshData(const MeshReference& ref, MeshBufferType type, BytesContainer& result, int32& count, GPUVertexLayout* *layout) const override
Parameters
MeshReference ref

Mesh reference.
MeshBufferType type

Buffer type
BytesContainer result

The result data
int32 count

The amount of items inside the result buffer.
GPUVertexLayout layout

The result layout of the result buffer (for vertex buffers). Optional, pass null to ignore it.
Returns
bool

True if failed, otherwise false.
Overrides

GetMeshDeformation()

Gets the mesh deformation utility for this model instance (optional).

Declaration
public virtual MeshDeformation* GetMeshDeformation() const override
Returns
MeshDeformation

Model deformation utility or null if not supported.
Overrides

GetNodeTransformation(const StringView& nodeName, Matrix& nodeTransformation, bool worldSpace=false)

Gets the node final transformation.

Declaration
public void GetNodeTransformation(const StringView& nodeName, Matrix& nodeTransformation, bool worldSpace=false) const
Parameters
StringView nodeName

The name of the skinned model skeleton node.
Matrix nodeTransformation

The output final node transformation matrix.
bool worldSpace

True if convert matrices into world-space, otherwise returned values will be in local-space of the actor.

GetNodeTransformation(int32 nodeIndex, Matrix& nodeTransformation, bool worldSpace=false)

Gets the node final transformation.

Declaration
public void GetNodeTransformation(int32 nodeIndex, Matrix& nodeTransformation, bool worldSpace=false) const
Parameters
int32 nodeIndex

The index of the skinned model skeleton node.
Matrix nodeTransformation

The output final node transformation matrix.
bool worldSpace

True if convert matrices into world-space, otherwise returned values will be in local-space of the actor.

GetParameter(const StringView& name)

Gets the anim graph instance parameter by name.

Declaration
public AnimGraphParameter* GetParameter(const StringView& name)
Parameters
StringView name

The parameter name.
Returns
AnimGraphParameter

The parameters.

GetParameters()

Gets the anim graph instance parameters collection.

Declaration
public Array<AnimGraphParameter> GetParameters() const
Returns
Array<AnimGraphParameter>

GetParameterValue(const Guid& id)

Gets the anim graph instance parameter value.

Declaration
public Variant GetParameterValue(const Guid& id) const
Parameters
Guid id

The parameter id.
Returns
Variant

The value.

GetParameterValue(const StringView& name)

Gets the anim graph instance parameter value.

Declaration
public Variant GetParameterValue(const StringView& name) const
Parameters
StringView name

The parameter name.
Returns
Variant

The value.

GetTraceEvents()

Gets the trace events from the last animation update. Valid only when EnableTracing is active.

Declaration
public Array<AnimGraphTraceEvent> GetTraceEvents() const
Returns
Array<AnimGraphTraceEvent>

HasContentLoaded()

Returns true if actor has loaded content.

Declaration
public virtual bool HasContentLoaded() const override
Returns
bool

Overrides

IntersectsEntry(const Ray& ray, Real& distance, Vector3& normal, int32& entryIndex)

Determines if there is an intersection between the model actor mesh entry and a ray. If mesh data is available on the CPU performs exact intersection check with the geometry. Otherwise performs simple BoundingBox vs Ray test. For more efficient collisions detection and ray casting use physics.

Declaration
public virtual bool IntersectsEntry(const Ray& ray, Real& distance, Vector3& normal, int32& entryIndex) override
Parameters
Ray ray

The ray to test.
Real distance

When the method completes and returns true, contains the distance of the intersection (if any valid).
Vector3 normal

When the method completes, contains the intersection surface normal vector (if any valid).
int32 entryIndex

When the method completes, contains the intersection entry index (if any valid).
Returns
bool

True if the actor is intersected by the ray, otherwise false.
Overrides

IntersectsEntry(int32 entryIndex, const Ray& ray, Real& distance, Vector3& normal)

Determines if there is an intersection between the model actor mesh entry and a ray. If mesh data is available on the CPU performs exact intersection check with the geometry. Otherwise performs simple BoundingBox vs Ray test. For more efficient collisions detection and ray casting use physics.

Declaration
public virtual bool IntersectsEntry(int32 entryIndex, const Ray& ray, Real& distance, Vector3& normal) override
Parameters
int32 entryIndex

The material slot entry index to test.
Ray ray

The ray to test.
Real distance

When the method completes and returns true, contains the distance of the intersection (if any valid).
Vector3 normal

When the method completes, contains the intersection surface normal vector (if any valid).
Returns
bool

True if the actor is intersected by the ray, otherwise false.
Overrides

IntersectsItself(const Ray& ray, Real& distance, Vector3& normal)

Determines if there is an intersection between the current object and a ray.

Declaration
public virtual bool IntersectsItself(const Ray& ray, Real& distance, Vector3& normal) override
Parameters
Ray ray

The ray to test.
Real distance

When the method completes, contains the distance of the intersection (if any valid).
Vector3 normal

When the method completes, contains the intersection surface normal vector (if any valid).
Returns
bool

True whether the two objects intersected, otherwise false.
Overrides

IsPlayingSlotAnimation()

Checks if the any animation playback is active on the any slot in Anim Graph (not paused).

Declaration
public bool IsPlayingSlotAnimation()
Returns
bool

IsPlayingSlotAnimation(const StringView& slotName, Animation* anim)

Checks if the animation playback is active on the slot in Anim Graph (not paused).

Declaration
public bool IsPlayingSlotAnimation(const StringView& slotName, Animation* anim)
Parameters
StringView slotName

The name of the slot.
Animation anim

The animation to check.
Returns
bool

OnActiveInTreeChanged()

Called when actor active in tree state gets changed.

Declaration
protected virtual void OnActiveInTreeChanged() override
Overrides

OnDebugDraw()

Draws debug shapes for the actor and all child scripts.

Declaration
public virtual void OnDebugDraw() override
Overrides

OnDebugDrawSelected()

Draws debug shapes for the selected actor and all child scripts.

Declaration
public virtual void OnDebugDrawSelected() override
Overrides

OnDeleteObject()

Deletes the object. Called by the ObjectsRemovalService. Can be overriden to provide custom logic per object (cleanup, etc.).

Declaration
public virtual void OnDeleteObject() override
Overrides

OnDisable()

Called when actor gets removed from game systems. Occurs on EndPlay event or when actor gets inactivated in hierarchy. Use this event to unregister object from other game system (eg. audio).

Declaration
protected virtual void OnDisable() override
Overrides

OnEnable()

Called when actor gets added to game systems. Occurs on BeginPlay event or when actor gets activated in hierarchy. Use this event to register object to other game system (eg. audio).

Declaration
protected virtual void OnEnable() override
Overrides

PauseSlotAnimation()

Pauses all the animations playback on the all slots in Anim Graph.

Declaration
public void PauseSlotAnimation()

PauseSlotAnimation(const StringView& slotName, Animation* anim)

Pauses the animation playback on the slot in Anim Graph.

Declaration
public void PauseSlotAnimation(const StringView& slotName, Animation* anim)
Parameters
StringView slotName

The name of the slot.
Animation anim

The animation to pause.

PlaySlotAnimation(const StringView& slotName, Animation* anim, float speed=1.0f, float blendInTime = 0.2f, float blendOutTime = 0.2f, int32 loopCount = 0)

Plays the animation on the slot in Anim Graph.

Declaration
public void PlaySlotAnimation(const StringView& slotName, Animation* anim, float speed=1.0f, float blendInTime = 0.2f, float blendOutTime = 0.2f, int32 loopCount = 0)
Parameters
StringView slotName

The name of the slot.
Animation anim

The animation to play.
float speed

The playback speed.
float blendInTime

The animation blending in time (in seconds). Cam be used to smooth the slot animation playback with the input pose when starting the animation.
float blendOutTime

The animation blending out time (in seconds). Cam be used to smooth the slot animation playback with the input pose when ending animation.
int32 loopCount

The amount of loops to play the animation: 0 to play once, -1 to play infinite, 1 or higher to loop once or more.

PreInitSkinningData()

Creates and setups the skinning data (writes the identity bones transformations).

Declaration
public void PreInitSkinningData()

ResetAnimation()

Resets the animation state (clears the instance state data but preserves the instance parameters values).

Declaration
public void ResetAnimation()

Serialize(SerializeStream& stream, const void* otherObj)

Serializes object to the output stream compared to the values of the other object instance (eg. default class object). If other object is null then serialize all properties.

Declaration
public virtual void Serialize(SerializeStream& stream, const void* otherObj) override
Parameters
SerializeStream stream

The output stream.
void otherObj

The instance of the object to compare with and serialize only the modified properties. If null, then serialize all properties.
Overrides

SetBlendShapeWeight(const StringView& name, float value)

Sets the weight of the blend shape.

Declaration
public void SetBlendShapeWeight(const StringView& name, float value)
Parameters
StringView name

The blend shape name.
float value

The normalized weight of the blend shape (in range -1:1).

SetCurrentPose(const Array<Matrix>& nodesTransformation, bool worldSpace=false)

Sets the per-node final transformations (skeleton pose).

Declaration
public void SetCurrentPose(const Array<Matrix>& nodesTransformation, bool worldSpace=false)
Parameters
Array<Matrix> nodesTransformation

The per-node final transformation matrices.
bool worldSpace

True if convert matrices from world-space, otherwise values are in local-space of the actor.

SetEnableTracing(bool value)

Enables extracting animation playback insights for debugging or custom scripting.

Declaration
public void SetEnableTracing(bool value)
Parameters
bool value

SetMasterPoseModel(AnimatedModel* masterPose)

Sets the master pose model that will be used to copy the skeleton nodes animation. Useful for modular characters.

Declaration
public void SetMasterPoseModel(AnimatedModel* masterPose)
Parameters
AnimatedModel masterPose

The master pose actor to use.

SetNodeTransformation(const StringView& nodeName, const Matrix& nodeTransformation, bool worldSpace=false)

Sets the node final transformation. If multiple nodes are to be set within a frame, do not use set worldSpace to true, and do the conversion yourself to avoid recalculation of inv matrices.

Declaration
public void SetNodeTransformation(const StringView& nodeName, const Matrix& nodeTransformation, bool worldSpace=false)
Parameters
StringView nodeName

The name of the skinned model skeleton node.
Matrix nodeTransformation

The final node transformation matrix.
bool worldSpace

True if convert matrices from world-space, otherwise values will be in local-space of the actor.

SetNodeTransformation(int32 nodeIndex, const Matrix& nodeTransformation, bool worldSpace=false)

Sets the node final transformation. If multiple nodes are to be set within a frame, do not use set worldSpace to true, and do the conversion yourself to avoid recalculation of inv matrices.

Declaration
public void SetNodeTransformation(int32 nodeIndex, const Matrix& nodeTransformation, bool worldSpace=false)
Parameters
int32 nodeIndex

The index of the skinned model skeleton node.
Matrix nodeTransformation

The final node transformation matrix.
bool worldSpace

True if convert matrices from world-space, otherwise values will be in local-space of the actor.

SetParameterValue(const Guid& id, const Variant& value)

Sets the anim graph instance parameter value.

Declaration
public void SetParameterValue(const Guid& id, const Variant& value)
Parameters
Guid id

The parameter id.
Variant value

The value to set.

SetParameterValue(const StringView& name, const Variant& value)

Sets the anim graph instance parameter value.

Declaration
public void SetParameterValue(const StringView& name, const Variant& value)
Parameters
StringView name

The parameter name.
Variant value

The value to set.

SetupSkinningData()

Validates and creates a proper skinning data.

Declaration
public void SetupSkinningData()

StopSlotAnimation()

Stops all the animations playback on the all slots in Anim Graph.

Declaration
public void StopSlotAnimation()

StopSlotAnimation(const StringView& slotName, Animation* anim)

Stops the animation playback on the slot in Anim Graph.

Declaration
public void StopSlotAnimation(const StringView& slotName, Animation* anim)
Parameters
StringView slotName

The name of the slot.
Animation anim

The animation to stop.

UpdateAnimation()

Performs the full animation update. The actual update will be performed during gameplay tick.

Declaration
public void UpdateAnimation()

UpdateBounds()

Updates the model bounds (eg. when mesh has applied significant deformation).

Declaration
public virtual void UpdateBounds() override
Overrides

WaitForModelLoad()

Declaration
protected virtual void WaitForModelLoad() override
Overrides