Open 3D Engine EMotionFX Gem API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
EMotionFX::MotionInstance Class Reference

#include <MotionInstance.h>

Inherits EMotionFX::BaseObject.

Classes

struct  PlayStateIn
 
struct  PlayStateOut
 

Public Member Functions

void Update (float timePassed)
 
void UpdateByTimeValues (float oldTime, float newTime, AnimGraphEventBuffer *outEventBuffer)
 
void ProcessEvents (float oldTime, float newTime)
 
void ExtractEvents (float oldTime, float newTime, AnimGraphEventBuffer *outBuffer)
 
void ExtractEventsNonLoop (float oldTime, float newTime, AnimGraphEventBuffer *outBuffer)
 
void SetCustomData (void *customDataPointer)
 
void * GetCustomData () const
 
AZ::u32 GetID () const
 
float GetBlendInTime () const
 
float GetCurrentTime () const
 
 AZ_DEPRECATED (float GetMaxTime() const, "This method has been deprecated. Please use MotionInstance::GetDuration() instead.")
 
float GetDuration () const
 
float GetPlaySpeed () const
 
MotionGetMotion () const
 
void SetMotion (Motion *motion)
 
void SetCurrentTimeNormalized (float normalizedTimeValue)
 
float GetCurrentTimeNormalized () const
 
void SetCurrentTime (float time, bool resetLastTime=true)
 
void SetLastCurrentTime (float timeInSeconds)
 
float GetLastCurrentTime () const
 
void SetPlaySpeed (float speed)
 
void SetPlayMode (EPlayMode mode)
 
EPlayMode GetPlayMode () const
 
void UpdateTime (float timePassed)
 
void SetFadeTime (float fadeTime)
 
float GetFadeTime () const
 
EMotionBlendMode GetBlendMode () const
 
bool GetIsInPlace () const
 
void SetIsInPlace (bool inPlace)
 
float GetWeight () const
 
float GetTargetWeight () const
 
void SetWeight (float targetWeight, float blendTimeInSeconds=0)
 
void SetBlendMode (EMotionBlendMode mode)
 
void SetMirrorMotion (bool enabled)
 
bool GetMirrorMotion () const
 
void Rewind ()
 
bool GetHasEnded () const
 
void SetMixMode (bool mixModeEnabled)
 
bool GetIsStopping () const
 
bool GetIsPlaying () const
 
bool GetIsMixing () const
 
bool GetIsBlending () const
 
void Pause ()
 
void UnPause ()
 
void SetPause (bool pauseEnabled)
 
bool GetIsPaused () const
 
void SetMaxLoops (AZ::u32 numLoops)
 
AZ::u32 GetMaxLoops () const
 
bool GetHasLooped () const
 
void SetNumCurrentLoops (AZ::u32 numCurrentLoops)
 
void SetNumLastLoops (AZ::u32 numCurrentLoops)
 
AZ::u32 GetNumLastLoops () const
 
AZ::u32 GetNumCurrentLoops () const
 
bool GetIsPlayingForever () const
 
ActorInstanceGetActorInstance () const
 
AZ::u32 GetPriorityLevel () const
 
void SetPriorityLevel (AZ::u32 priorityLevel)
 
bool GetMotionExtractionEnabled () const
 
void SetMotionExtractionEnabled (bool enable)
 
bool GetCanOverwrite () const
 
void SetCanOverwrite (bool canOverwrite)
 
bool GetDeleteOnZeroWeight () const
 
void SetDeleteOnZeroWeight (bool deleteOnZeroWeight)
 
void Stop (float fadeOutTime)
 
void Stop ()
 
bool GetRetargetingEnabled () const
 
void SetRetargetingEnabled (bool enabled)
 
bool GetIsActive () const
 
void SetIsActive (bool enabled)
 
bool GetIsFrozen () const
 
void SetIsFrozen (bool isFrozen)
 
bool GetMotionEventsEnabled () const
 
void SetMotionEventsEnabled (bool enabled)
 
void SetEventWeightThreshold (float weightThreshold)
 
float GetEventWeightThreshold () const
 
bool GetFreezeAtLastFrame () const
 
void SetBlendOutBeforeEnded (bool enabled)
 
bool GetBlendOutBeforeEnded () const
 
void SetFreezeAtLastFrame (bool enabled)
 
float GetTotalPlayTime () const
 
void SetTotalPlayTime (float playTime)
 
float GetMaxPlayTime () const
 
void SetMaxPlayTime (float playTime)
 
void InitFromPlayBackInfo (const PlayBackInfo &info, bool resetCurrentPlaytime=true)
 
float GetTimeDifToLoopPoint () const
 
void AddEventHandler (MotionInstanceEventHandler *eventHandler)
 
void RemoveEventHandler (MotionInstanceEventHandler *eventHandler)
 
void RemoveAllEventHandlers ()
 
MotionInstanceEventHandlerGetEventHandler (size_t index) const
 
size_t GetNumEventHandlers () const
 
void OnEvent (const EventInfo &eventInfo) const
 
void OnStartMotionInstance (PlayBackInfo *info)
 
void OnDeleteMotionInstance ()
 
void OnStop ()
 
void OnHasLooped ()
 
void OnHasReachedMaxNumLoops ()
 
void OnHasReachedMaxPlayTime ()
 
void OnIsFrozenAtLastFrame ()
 
void OnChangedPauseState ()
 
void OnChangedActiveState ()
 
void OnStartBlending ()
 
void OnStopBlending ()
 
void OnQueueMotionInstance (PlayBackInfo *info)
 
void SetIsOwnedByRuntime (bool isOwnedByRuntime)
 
bool GetIsOwnedByRuntime () const
 
float GetFreezeAtTime () const
 
void SetFreezeAtTime (float timeInSeconds)
 
void CalcRelativeTransform (Node *rootNode, float curTime, float oldTime, Transform *outTransform) const
 
bool ExtractMotion (Transform &outTrajectoryDelta)
 
void CalcGlobalTransform (const AZStd::vector< size_t > &hierarchyPath, float timeValue, Transform *outTransform) const
 
void ResetTimes ()
 
 AZ_DEPRECATED (void CalcNewTimeAfterUpdate(float timePassed, float *outNewTime) const, "MotionInstance::CalcNewTimeAfterUpdate has been deprecated, please use MotionInstance::CalcPlayStateAfterUpdate(timeDelta).m_currentTime instead.")
 
PlayStateOut CalcPlayStateAfterUpdate (float timePassed) const
 
PlayStateIn ConstructInputPlayState () const
 
void SetPlayState (const PlayStateIn &inState, const PlayStateOut &outState, bool triggerEvents)
 
void ExtractMotionEvents (const PlayStateIn &inState, PlayStateOut &outState, AnimGraphEventBuffer &eventBuffer) const
 
void ProcessMotionEvents (const PlayStateIn &inState, PlayStateOut &outState) const
 
MotionInstancePool::SubPool * GetSubPool () const
 
const MotionLinkDataFindMotionLinkData (const Actor *actor) const
 
- Public Member Functions inherited from EMotionFX::BaseObject
 BaseObject ()
 
virtual ~BaseObject ()
 
- Public Member Functions inherited from MCore::MemoryObject
 MemoryObject ()
 
virtual ~MemoryObject ()
 
void IncreaseReferenceCount ()
 
void DecreaseReferenceCount ()
 
void Destroy ()
 
uint32 GetReferenceCount () const
 

Static Public Member Functions

static MotionInstanceCreate (Motion *motion, ActorInstance *actorInstance)
 
static MotionInstanceCreate (void *memLocation, Motion *motion, ActorInstance *actorInstance)
 
static PlayStateOut CalcPlayState (const PlayStateIn &inState, float timePassed)
 

Friends

class RepositioningLayerPass
 
class AnimGraphMotionNode
 
class MotionInstancePool
 

Additional Inherited Members

- Protected Member Functions inherited from EMotionFX::BaseObject
void Delete () override
 
virtual void Delete ()
 

Detailed Description

The MotionInstance class. Since Motion objects can be shared between different Actors, there needs to be a mechanism which allows this. By introducing this MotionInstance class, we can create instances from Motions, where the instance also contains playback information. This playback information allows us to play the same animation data at different actors all with unique play positions and speeds, etc.

Member Function Documentation

◆ AddEventHandler()

void EMotionFX::MotionInstance::AddEventHandler ( MotionInstanceEventHandler eventHandler)

Add an event handler to this motion instance. After adding, the event handler will receive events.

Parameters
eventHandlerThe new event handler to register.

◆ AZ_DEPRECATED()

EMotionFX::MotionInstance::AZ_DEPRECATED ( float GetMaxTime() const  ,
"This method has been deprecated. Please use MotionInstance::GetDuration() instead."   
)

Get the maximum time of this motion.

Returns
The maximum time of this motion, in seconds.

◆ GetActorInstance()

ActorInstance * EMotionFX::MotionInstance::GetActorInstance ( ) const

Get the actor instance we are playing this motion instance on.

Returns
A pointer to the actor where this motion instance is playing on.

◆ GetBlendInTime()

float EMotionFX::MotionInstance::GetBlendInTime ( ) const

Get the blend in time. This is the time passed to the SetWeight(...) method where when the target weight is bigger than the current. So only blend ins are counted and not blending out towards for example a weight of 0. When you never call SetWeight(...) yourself, this means that this will contain the value specificied to PlayBackInfo::m_blendInTime at the time of MotionSystem::PlayMotion(...).

Returns
The blend-in time, in seconds.

◆ GetBlendMode()

EMotionBlendMode EMotionFX::MotionInstance::GetBlendMode ( ) const

Get the motion blending mode of this motion instance. This describes how the motion gets blend with the other motions being played. For more information about what the blendmodes exactly do, read the documentation of the SetBlendMode method.

Returns
The motion blend mode for this motion instance.
See also
SetBlendMode

◆ GetBlendOutBeforeEnded()

bool EMotionFX::MotionInstance::GetBlendOutBeforeEnded ( ) const

The "blend out before end"-option allows you to specify whether a motion should start fading out before the motion has ended (before it reached its maximum number of loops) or if it should fade out after the maximum number of loops have been reached. In the latter case it would mean that the motion will start another loop while it starts fading out. On default this option is enabled, which means the motion will be faded out exactly when it reaches the last frame it should play.

Returns
Returns true when this option is enabled, otherwise false is returned.

◆ GetCanOverwrite()

bool EMotionFX::MotionInstance::GetCanOverwrite ( ) const

Check if this motion instance is allowed to overwrite (and thus delete) other motion instances/layers. This happens in the motion layer system when the weight of this motion instance becomes 1, which means it would completely overwrite other motions because the other motions will not have any influence anymore. On default this value is set to true.

Returns
Returns true when the motion instance will automatically delete other motion instances when its weight reaches a value of 1. If the motion instance will not delete/overwrite any other motion instances, false is returned.

◆ GetCurrentTime()

float EMotionFX::MotionInstance::GetCurrentTime ( ) const

Returns the current time in the playback of the motion.

Returns
The current time, in seconds.

◆ GetCurrentTimeNormalized()

float EMotionFX::MotionInstance::GetCurrentTimeNormalized ( ) const

Returns the current time in the playback of the motion. Normalized in this case means from 0.0 to 1.0. The maximum time of this animation is then 1.0.

Returns
The normalized current time, in seconds.

◆ GetCustomData()

void * EMotionFX::MotionInstance::GetCustomData ( ) const

Get the custom data pointer value. This can be used to link your own custom data to this MotionInstance object. You are responsible later on for deleting any allocated data by this custom data. You can use the MotionEventHandler::OnDeleteMotionInstance() callback to detect when a motion instance is being deleted. On default the custom data value will return nullptr, unless you have used SetCustomData() to adjust the value.

Returns
The pointer to your custom data that is linked to this MotionInstance object.

◆ GetDeleteOnZeroWeight()

bool EMotionFX::MotionInstance::GetDeleteOnZeroWeight ( ) const

Check if this motion instance can delete itself when its weight equals zero, which means the motion would have no visual influence. On default this value is set to true.

Returns
Returns true when the motion instance will delete itself when its weight equals a value of zero. Otherwise false is returned.

◆ GetDuration()

float EMotionFX::MotionInstance::GetDuration ( ) const

Get the duration of the motion, which is the difference between the clip start and end time.

Returns
The playback duration of this motion instance, in seconds.

◆ GetEventHandler()

MotionInstanceEventHandler * EMotionFX::MotionInstance::GetEventHandler ( size_t  index) const

Get the event handler at the given index.

Returns
A pointer to the event handler at the given index.

◆ GetEventWeightThreshold()

float EMotionFX::MotionInstance::GetEventWeightThreshold ( ) const

Get the motion event weight threshold for this motion instance. The threshold value represents the minimum weight value the motion instance should have in order for it to have its motion events executed. For example if the motion event threshold is set to 0.3, and the motion instance weight value is 0.1, then no motion events will be processed. If however the weight value of the motion instance is above or equal to this 0.3 value then all events will be processed. On default the value is 0.0, which means that all events will be processed.

Returns
The motion event threshold value.

◆ GetFadeTime()

float EMotionFX::MotionInstance::GetFadeTime ( ) const

Return the time spend to fade out the motion when it is being stopped automatically when the motion has reached its end. This will only happen when the play mode is PLAYMODE_ONCE.

Returns
The fade time, in seconds.

◆ GetFreezeAtLastFrame()

bool EMotionFX::MotionInstance::GetFreezeAtLastFrame ( ) const

Check if this motion instance will freeze at its last frame (when not using looping). This only happens when using a maximum play time, or a given number of loops that is not infinite.

Returns
Returns true when the motion instance will freeze at the last frame. Otherwise false is returned.

◆ GetHasEnded()

bool EMotionFX::MotionInstance::GetHasEnded ( ) const

Check if this motion instance has ended or not. This will only happen when the play mode is PLAYMODE_ONCE, because a looping motion will of course never end.

Returns
Returns true when the motion has reached the end of the animation, otherwise false is returned.

◆ GetHasLooped()

bool EMotionFX::MotionInstance::GetHasLooped ( ) const

Check if the motion has looped since the last update. This is the case when the number of loops returned by GetNumCurrentLoops is not equal to the number of loops before the playback mode object has been updated.

Returns
Returns true when the motion has looped, otherwise false is returned.

◆ GetID()

AZ::u32 EMotionFX::MotionInstance::GetID ( ) const

Get the unique identification number for the motion instance.

Returns
The unique identification number.

◆ GetIsActive()

bool EMotionFX::MotionInstance::GetIsActive ( ) const

Check if the motion instance is active or not. On default the motion instance will be active. Inactive motion instances do not get processed at all. They will not update their weight blending or time values. The difference with paused motion instances is that paused instances do process their weight blending, while inactive motion instances do not.

Returns
Returns true when the motion instance is active, otherwise false is returned.

◆ GetIsBlending()

bool EMotionFX::MotionInstance::GetIsBlending ( ) const

Checks if the motion is being blended or not. A blend could be the smooth fade in after starting the motion, or a smooth fade out when stopping the animation.

Returns
Returns true when the motion is currently in a blend process, otherwise false is returned.

◆ GetIsFrozen()

bool EMotionFX::MotionInstance::GetIsFrozen ( ) const

Check if we are frozen in the last frame or not. This would only happen when the SetFreezeAtLastFrame(...) was set to true and when the maximum number of loops has been reached. Instead of fading out the motion, it will remain in its last frame.

Returns
Returns true when the motion is frozen in its last frame.

◆ GetIsMixing()

bool EMotionFX::MotionInstance::GetIsMixing ( ) const

Checks if the motion is in mix mode or not.

Returns
Returns true when the motion is being mixed, otherwise false.

◆ GetIsPaused()

bool EMotionFX::MotionInstance::GetIsPaused ( ) const

Check if the motion currently is paused or not.

Returns
Returns true when the motion is in pause mode.

◆ GetIsPlaying()

bool EMotionFX::MotionInstance::GetIsPlaying ( ) const

Checks if the motion is currently playing or not.

Returns
Returns true when the motion is playing, otherwise false.

◆ GetIsPlayingForever()

bool EMotionFX::MotionInstance::GetIsPlayingForever ( ) const

Check if the motion will play forever or not.

Returns
Returns true when the motion is looping forever, or false when there will be a moment where it will be stopped.

◆ GetIsStopping()

bool EMotionFX::MotionInstance::GetIsStopping ( ) const

Checks if the motion is currently stopping or not, so if it is fading out.

Returns
Returns true when the motion is currently stopping, so is fading out.

◆ GetLastCurrentTime()

float EMotionFX::MotionInstance::GetLastCurrentTime ( ) const

Get the current time of the previous update.

Returns
The time value, in seconds, of the current playback time, in the previous update.

◆ GetMaxLoops()

AZ::u32 EMotionFX::MotionInstance::GetMaxLoops ( ) const

Get the number of loops the motion will play.

Returns
The number of times the motion will be played. This value will be EMFX_LOOPFOREVER (see Actor.h for the define) in case the motion will play forever.
See also
IsPlayingForever

◆ GetMaxPlayTime()

float EMotionFX::MotionInstance::GetMaxPlayTime ( ) const

Get the maximum play time of this motion instance (well actually of the motion where this is an instance from). So this returns the duration of the motion, in seconds. When this value is zero or a negative value, then the maximum play time option has been disabled for this motion instance.

Returns
The duration of the motion, in seconds.

◆ GetMirrorMotion()

bool EMotionFX::MotionInstance::GetMirrorMotion ( ) const

On default motion mirroring is disabled, so set to false. Motion mirroring is often very useful in sport games, where you can choose whether your character is left or right-handed. The motion mirroring feature allows you to create just one set of motions, for example right handed. By enabling mirroring of EMotion FX we can turn the right handed motions into left handed motions on the fly, by using the right handed motion source data and modifying it into a left handed motion. This does not really take more memory. Of course there is a little performance impact, but it is definitely worth the memory savings and art time savings.

Returns
Returns true when motion mirroring is enabled, or false when it is disabled. On default it is disabled.

◆ GetMotion()

Motion * EMotionFX::MotionInstance::GetMotion ( ) const

Returns motion it is using.

Returns
The original motion it's using.

◆ GetMotionEventsEnabled()

bool EMotionFX::MotionInstance::GetMotionEventsEnabled ( ) const

Check if motion event processing is enabled for this motion instance.

Returns
Returns true when processing of motion events for this motion event is enabled. Otherwise false is returned.

◆ GetMotionExtractionEnabled()

bool EMotionFX::MotionInstance::GetMotionExtractionEnabled ( ) const

Check if this motion has motion extraction enabled or not.

Returns
Returns true if motion extraction is enabled, false if not.
See also
Actor::SetMotionExtractionNode

◆ GetNumCurrentLoops()

AZ::u32 EMotionFX::MotionInstance::GetNumCurrentLoops ( ) const

Get the number of times the motion currently has been played.

Returns
The number of times the motion has been completely played.

◆ GetNumEventHandlers()

size_t EMotionFX::MotionInstance::GetNumEventHandlers ( ) const

Get the number of event handlers.

Returns
The number of event handlers assigned to the motion instance.

◆ GetPlayMode()

EPlayMode EMotionFX::MotionInstance::GetPlayMode ( ) const

Get the play mode, which defines the deireciton the motion is playing (foward or backward).

Returns
The playback mode.

◆ GetPlaySpeed()

float EMotionFX::MotionInstance::GetPlaySpeed ( ) const

Return the play speed factor (1.0 is normal, 0.5 is half speed, etc.).

Returns
The play speed factor.

◆ GetPriorityLevel()

AZ::u32 EMotionFX::MotionInstance::GetPriorityLevel ( ) const

Get the priority level of the motion instance. Higher values mean less change on getting overwritten by another motion. A good example are facial motions being played on a walking character. You would first play the walk motion, with priority of say 0. After that you will play a facial motion, with mix mode, and priority level 5 for example. Now you want to change the walk motion into a run motion. If we did not set the priority level for the facial motion above 0, the run motion would overwrite the facial motion. But since the facial motion has got a higher priority, it will not be overwritten by the run motion. If we now want to change the facial motion with another one, we simply play the facial motion with the same or a higher priority level as the previous facial motion. So a priority level of 5 or higher would work in the example case.

Returns
The priority level of the motion instance.

◆ GetRetargetingEnabled()

bool EMotionFX::MotionInstance::GetRetargetingEnabled ( ) const

Check if motion retargeting on this motion instance is enabled or not.

Returns
Returns true when motion retargeting is enabled on this motion instance. Otherwise false is returned.

◆ GetTargetWeight()

float EMotionFX::MotionInstance::GetTargetWeight ( ) const

Returns the target weight. This is the weight we are blending towards. If you specified a blendTimeInSeconds of zero in the SetWeight method, the target weight will return the same as the value returned by GetWeight(). The value returned is in range of [0..1].

Returns
The target weight value, where we are blending towards.

◆ GetTimeDifToLoopPoint()

float EMotionFX::MotionInstance::GetTimeDifToLoopPoint ( ) const

Get the time difference between the current play time and the end of the motion. With end of motion we mean the point where there is no more motion data, so where it would need to loop to continue to play.

Returns
The time remaining until the loop point of the motion would be reached.

◆ GetTotalPlayTime()

float EMotionFX::MotionInstance::GetTotalPlayTime ( ) const

Get the total time this motion has been playing already.

Returns
The total time, in seconds, that this motion is already playing.

◆ GetWeight()

float EMotionFX::MotionInstance::GetWeight ( ) const

Returns the current weight of the layer. This weight is in range of [0..1], where 0 means no influence and 1 means full influence.

Returns
The current weight value.

◆ InitFromPlayBackInfo()

void EMotionFX::MotionInstance::InitFromPlayBackInfo ( const PlayBackInfo info,
bool  resetCurrentPlaytime = true 
)

Initialize the motion instance from PlayBackInfo settings.

Parameters
infoThe playback info settings to initialize from.
resetCurrentPlaytimeSet back the current playtime, even though this is not an attribute of the playback info in case of true. In case of false the current time won't be modified.

◆ OnChangedActiveState()

void EMotionFX::MotionInstance::OnChangedActiveState ( )

This event gets triggered once the motion active state changes. For example when the motion is active but gets set to inactive using the MotionInstance::SetActive(...) method, then this even twill be triggered. Inactive motions don't get processed at all. They will not update their playback times, blending, nor will they take part in any blending calculations of the final node transforms. In other words, it will just be like the motion instance does not exist at all.

◆ OnChangedPauseState()

void EMotionFX::MotionInstance::OnChangedPauseState ( )

This event gets triggered once the motion pause state changes. For example when the motion is unpaused but gets paused, then this even twill be triggered. Paused motions don't get their playback times updated. They do however still perform blending, so it is still possible to fade them in or out.

◆ OnDeleteMotionInstance()

void EMotionFX::MotionInstance::OnDeleteMotionInstance ( )

The event that gets triggered once a MotionInstance object is being deleted. This can happen when calling the MotionSystem::RemoveMotionInstance() method manually, or when EMotion FX internally removes the motion instance because it has no visual influence anymore. The destructor of the MotionInstance class automatically triggers this event.

◆ OnEvent()

void EMotionFX::MotionInstance::OnEvent ( const EventInfo eventInfo) const

The method that processes an event.

Parameters
eventInfoThe struct holding the information about the triggered event.

◆ OnHasLooped()

void EMotionFX::MotionInstance::OnHasLooped ( )

This event gets triggered once a given motion instance has looped.

◆ OnHasReachedMaxNumLoops()

void EMotionFX::MotionInstance::OnHasReachedMaxNumLoops ( )

This event gets triggered once a given motion instance has reached its maximum number of allowed loops. In this case the motion instance will also be stopped automatically afterwards.

◆ OnHasReachedMaxPlayTime()

void EMotionFX::MotionInstance::OnHasReachedMaxPlayTime ( )

This event gets triggered once a given motion instance has reached its maximum playback time. For example if this motion instance is only allowed to play for 2 seconds, and the total playback time reaches two seconds, then this event will be triggered.

◆ OnIsFrozenAtLastFrame()

void EMotionFX::MotionInstance::OnIsFrozenAtLastFrame ( )

This event gets triggered once the motion instance is set to freeze at the last frame once the motion reached its end (when it reached its maximum number of loops or playtime). In this case this event will be triggered once.

◆ OnQueueMotionInstance()

void EMotionFX::MotionInstance::OnQueueMotionInstance ( PlayBackInfo info)

This event gets triggered once the given motion instance gets added to the motion queue. This happens when you set the PlayBackInfo::m_playNow member to false. In that case the MotionSystem::PlayMotion() method (OnPlayMotion) will not directly start playing the motion (OnStartMotionInstance), but will add it to the motion queue instead. The motion queue will then start playing the motion instance once it should.

Parameters
infoThe playback information used to play this motion instance.

◆ OnStartBlending()

void EMotionFX::MotionInstance::OnStartBlending ( )

This event gets triggered once a motion instance is automatically changing its weight value over time. For example when a motion is automatically being faded in from weight 0 to a given target weight in half a second, then once this blending starts, this event is being triggered. Once the the MotionInstance::SetWeight(...) method is being called with a blend time bigger than zero, and if the motion instance isn't currently already blending, then this event will be triggered. This event most likely will get triggered when using the MotionSystem::PlayMotion() and MotionInstance::Stop() methods.

◆ OnStartMotionInstance()

void EMotionFX::MotionInstance::OnStartMotionInstance ( PlayBackInfo info)

The event that gets triggered when a motion instance is really being played. This can be a manual call through MotionInstance::PlayMotion or when the MotionQueue class will start playing a motion that was on the queue. The difference between OnStartMotionInstance() and this OnPlayMotion() is that the OnPlayMotion doesn't guarantee that the motion is being played yet, as it can also be added to the motion queue. The OnStartMotionInstance() method will be called once the motion is really being played.

Parameters
infoThe playback info used to play the motion.

◆ OnStop()

void EMotionFX::MotionInstance::OnStop ( )

The event that gets triggered when a motion instance is being stopped using one of the MotionInstance::Stop() methods. EMotion FX will internally stop the motion automatically when the motion instance reached its maximum playback time or its maximum number of loops.

◆ OnStopBlending()

void EMotionFX::MotionInstance::OnStopBlending ( )

This event gets triggered once a motion instance stops it automatic changing of its weight value over time. For example when a motion is automatically being faded in from weight 0 to a given target weight in half a second, and once the target weight is reached after half a second, will cause this event to be triggered. Once the the MotionInstance::SetWeight(...) method is being called with a blend time equal to zero and the motion instance is currently blending its weight value, then this event will be triggered. This event most likely will get triggered when using the MotionSystem::PlayMotion() and MotionInstance::Stop() methods.

◆ Pause()

void EMotionFX::MotionInstance::Pause ( )

Pause the motion instance.

◆ RemoveAllEventHandlers()

void EMotionFX::MotionInstance::RemoveAllEventHandlers ( )

Remove all motion event handlers from this motion instance.

◆ RemoveEventHandler()

void EMotionFX::MotionInstance::RemoveEventHandler ( MotionInstanceEventHandler eventHandler)

Remove the given event handler. Even if the function returns false, if delFromMem is set to true it will delete the handler from memory.

Parameters
eventHandlerA pointer to the event handler to remove.

◆ Rewind()

void EMotionFX::MotionInstance::Rewind ( )

Rewinds the motion instance. It sets the current time to 0 seconds.

◆ SetBlendMode()

void EMotionFX::MotionInstance::SetBlendMode ( EMotionBlendMode  mode)

Set the motion blend mode of this motion instance. If you want to switch between two different motions, for example going from walk into run, you most likely want to use the BLENDMODE_OVERWRITE mode. However, there are some cases where overwriting doesn't work well. Think of a skateboard game, where you play a looping base animation, which is played while moving forwards. Now on top of this you want to bend the character's upper body to the right. So you play a mixing motion of the upper body. You now have a character, which is skate boarding, while bending his upper body to the right. Now imagine you want to have some motion which shoots. You want the character to shoot, while it is skating and while it is has bend his upper body to the right. If you would use overwrite mode, and the shoot animation adjusts the bones in the upper body, the motion of the bend will be overwritten. This means you will only see a shoot animation while skating, and not the desired, shoot, while bending right, while skating. In order to solve this, you can play the shoot motion additive, on top of the bend and skate motions. EMotion FX will then add all relative changes (compared to the original pose of the actor) to the current result, which in our case is the skating, while bending right. Playing an additive motion in mix-mode, will act the same as playing one in non-mixing mode.

Parameters
modeThe blendmode to use. The default blendmode of motion instances are set to BLEND_OVERWRITE.
See also
EMotionBlendMode

◆ SetBlendOutBeforeEnded()

void EMotionFX::MotionInstance::SetBlendOutBeforeEnded ( bool  enabled)

This option allows you to specify whether a motion should start fading out before the motion has ended (before it reached its maximum number of loops) or if it should fade out after the maximum number of loops have been reached. In the latter case it would mean that the motion will start another loop while it starts fading out. On default this option is enabled, which means the motion will be faded out exactly when it reaches the last frame it should play.

Parameters
enabledSet to true to to enable this option, or false to disable it. On default it is set to true.

◆ SetCanOverwrite()

void EMotionFX::MotionInstance::SetCanOverwrite ( bool  canOverwrite)

Enable or disable this motion instance to overwrite and so delete other motion instances. This happens in the motion layer system when the weight of this motion instance becomes 1, which means it would completely overwrite other motions because the other motions will not have any influence anymore. On default overwriting is enabled, so the value would be true.

Parameters
canOverwriteSet to true to allow this motion instance to overwrite/delete other motion instances/layers. Otherwise set to false.

◆ SetCurrentTime()

void EMotionFX::MotionInstance::SetCurrentTime ( float  time,
bool  resetLastTime = true 
)

Set the current time in the animation (automatic wrapping/looping performed when out of range).

Parameters
timeThe current time in the animation, in seconds.
resetLastTimeWhen set to true, the last frame time will be set equal to the new current time as well.

◆ SetCurrentTimeNormalized()

void EMotionFX::MotionInstance::SetCurrentTimeNormalized ( float  normalizedTimeValue)

Set the current time in the animation (automatic wrapping/looping performed when out of range). Normalized in this case means from 0.0 to 1.0. The maximum time of this animation is then 1.0.

Parameters
normalizedTimeValueThe new normalized time value, in seconds.

◆ SetCustomData()

void EMotionFX::MotionInstance::SetCustomData ( void *  customDataPointer)

Set the custom data pointer. This can be used to link your own custom data to this MotionInstance object. You are responsible later on for deleting any allocated data by this custom data. You can use the MotionEventHandler::OnDeleteMotionInstance() callback to detect when a motion instance is being deleted.

Parameters
customDataPointerThe pointer to your custom data.

◆ SetDeleteOnZeroWeight()

void EMotionFX::MotionInstance::SetDeleteOnZeroWeight ( bool  deleteOnZeroWeight)

Allow or disallow the motion instance to delete itself when its weight equals zero. When a motion instance has a weight of zero it means it would have no visual influence in the final result. On default deletion on zero weights is enabled, so the value would be true.

Parameters
deleteOnZeroWeightSet to true when you wish to allow the motion instance to delete itself when it has a weight of zero. Otherwise set it to false.

◆ SetEventWeightThreshold()

void EMotionFX::MotionInstance::SetEventWeightThreshold ( float  weightThreshold)

Set the motion event weight threshold for this motion instance. The threshold value represents the minimum weight value the motion instance should have in order for it to have its motion events executed. For example if the motion event threshold is set to 0.3, and the motion instance weight value is 0.1, then no motion events will be processed. If however the weight value of the motion instance is above or equal to this 0.3 value then all events will be processed. On default the value is 0.0, which means that all events will be processed.

Parameters
weightThresholdThe motion event weight threshold. If the motion instance weight is below this value, no motion events will be processed for this motion instance. Basically this value should be in range of [0..1].

◆ SetFadeTime()

void EMotionFX::MotionInstance::SetFadeTime ( float  fadeTime)

Set the fade-out time.

Parameters
fadeTimeThe fade time, in seconds.

◆ SetFreezeAtLastFrame()

void EMotionFX::MotionInstance::SetFreezeAtLastFrame ( bool  enabled)

Enable or disable freezing at the last frame. This only happens when using a maximum play time, or a given number of loops that is not infinite. When you play a full body death motion, you probably want to enable this. If in that case this option would be disabled (default) it will blend back into its base/bind pose instead of freezing at the last frame, keeping the character dead on the ground.

Parameters
enabledSet to true when you want to enable the freeze at last frame option, otherwise set to false.

◆ SetIsActive()

void EMotionFX::MotionInstance::SetIsActive ( bool  enabled)

Activate or deactivate this motion instance. On default the motion instance will be active. Inactive motion instances do not get processed at all. They will not update their weight blending or time values. The difference with paused motion instances is that paused instances do process their weight blending, while inactive motion instances do not.

Parameters
enabledSet to true when you want to activate the motion instance, or false when you wish to deactivate it.

◆ SetIsFrozen()

void EMotionFX::MotionInstance::SetIsFrozen ( bool  isFrozen)

Set if we are frozen in the last frame or not. Instead of fading out the motion, it will remain in its last frame.

◆ SetIsOwnedByRuntime()

void EMotionFX::MotionInstance::SetIsOwnedByRuntime ( bool  isOwnedByRuntime)

Marks the object as used by the engine runtime, as opposed to the tool suite.

◆ SetMaxLoops()

void EMotionFX::MotionInstance::SetMaxLoops ( AZ::u32  numLoops)

Set the number of loops the motion should play. If you want to loop it forever, set the value to EMFX_LOOPFOREVER (which is defined in Actor.h).

Parameters
numLoopsThe number of loops the motion should play, or EMFX_LOOPFOREVER in case it should play forever.

◆ SetMaxPlayTime()

void EMotionFX::MotionInstance::SetMaxPlayTime ( float  playTime)

Set the maximum play time, in seconds, that this motion instance is allowed to play. When you set this to zero (default), or a negative value, then this option is disabled.

Parameters
playTimeThe maximum play time, in seconds, or zero or a negative value to disable the maximum play time.

◆ SetMirrorMotion()

void EMotionFX::MotionInstance::SetMirrorMotion ( bool  enabled)

Enable or disable motion mirroring. On default motion mirroring is disabled. Motion mirroring is often very useful in sport games, where you can choose whether your character is left or right-handed. The motion mirroring feature allows you to create just one set of motions, for example right handed. By enabling mirroring of EMotion FX we can turn the right handed motions into left handed motions on the fly, by using the right handed motion source data and modifying it into a left handed motion. This does not really take more memory. Of course there is a little performance impact, but it is definitely worth the memory savings and art time savings. When mirroring is enabled the motion mirror plane normal is used to determine how to mirror the motion. This can be set with SetMirrorPlaneNormal().

Parameters
enabledSet to true if you want to enable motion mirroring, or false when you want to disable it.

◆ SetMixMode()

void EMotionFX::MotionInstance::SetMixMode ( bool  mixModeEnabled)

Set the motion to mix mode or not.

Parameters
mixModeEnabledSet to true when the motion has to mix, otherwise set to false.

◆ SetMotionEventsEnabled()

void EMotionFX::MotionInstance::SetMotionEventsEnabled ( bool  enabled)

Enable or disable processing of motion events for this motion instance.

Parameters
enabledSet to true when you wish to enable processing of motion events. Otherwise set it to false.

◆ SetMotionExtractionEnabled()

void EMotionFX::MotionInstance::SetMotionExtractionEnabled ( bool  enable)

Enable or disable motion extraction.

Parameters
enableSet to true when you want to enable motion extraction.
See also
GetMotionExtractionEnabled

◆ SetNumCurrentLoops()

void EMotionFX::MotionInstance::SetNumCurrentLoops ( AZ::u32  numCurrentLoops)

Set the new number of times the motion has been played. Changing this value will misrepresent the exact number.

Parameters
numCurrentLoopsThe number of times the motion has been played.

◆ SetPause()

void EMotionFX::MotionInstance::SetPause ( bool  pauseEnabled)

Set the pause mode.

Parameters
pauseEnabledWhen true, the motion will be set to pause, else it will be unpaused.

◆ SetPlayMode()

void EMotionFX::MotionInstance::SetPlayMode ( EPlayMode  mode)

Set the play mode, which defines the direction the motion is playing (forward or backward).

Parameters
modeThe playback mode to use.

◆ SetPlaySpeed()

void EMotionFX::MotionInstance::SetPlaySpeed ( float  speed)

Set the current play speed (1.0 is normal, 0.5 is half speed, etc.). The speed has to be bigger or equal to 0. You should not use negative playback speeds. If you want to play backward, use the SetPlayMode( PLAYMODE_BACKWARD ), or use the PlayBackInfo::m_playMode value.

Parameters
speedThe current play speed (1.0 is normal, 0.5 is half speed, etc.).

◆ SetPriorityLevel()

void EMotionFX::MotionInstance::SetPriorityLevel ( AZ::u32  priorityLevel)

Set the priority level of the motion instance. Higher values mean less change on getting overwritten by another motion. A good example are facial motions being played on a walking character. You would first play the walk motion, with priority of say 0. After that you will play a facial motion, with mix mode, and priority level 5 for example. Now you want to change the walk motion into a run motion. If we did not set the priority level for the facial motion above 0, the run motion would overwrite the facial motion. But since the facial motion has got a higher priority, it will not be overwritten by the run motion. If we now want to change the facial motion with another one, we simply play the facial motion with the same or a higher priority level as the previous facial motion. So a priority level of 5 or higher would work in the example case.

Returns
The priority level of the motion instance.

◆ SetRetargetingEnabled()

void EMotionFX::MotionInstance::SetRetargetingEnabled ( bool  enabled)

Enable or disable motion retargeting on this motion instance. Retargeting takes a bit more speed, but it is a very small performance difference.

Parameters
enabledSet to true when you wish to enable motion retargeting, otherwise set to false (false is the default).

◆ SetTotalPlayTime()

void EMotionFX::MotionInstance::SetTotalPlayTime ( float  playTime)

Adjust the total play time that this motion is already playing.

Parameters
playTimeThe total play time, in seconds.

◆ SetWeight()

void EMotionFX::MotionInstance::SetWeight ( float  targetWeight,
float  blendTimeInSeconds = 0 
)

Set the target weight value. This can be used to smoothly blend towards another weight value. You specify the new (target) weight value, and the time in seconds in which we should blend into that weight. A weight value of 0 means no influence, and a weight value of 1 means full influence. Please keep in mind that motion layers inside the motion layer system will automatically be removed when we are in overwrite motion blend mode and this motion reaches full influence. In order to prevent this from happening, you can blend towards a weight of for example 0.999. This will not have any visual difference compared to a weight of 1, but will prevent motion instances and layers from being removed. The same goes for motion weights of 0. Instead of motion weights of 0, you can use values like 0.001 in these cases.

Parameters
targetWeightThe weight value we want to blend towards.
blendTimeInSecondsThe time, in seconds, in which we should blend from the current weight value into the specified target weight value.

◆ Stop() [1/2]

void EMotionFX::MotionInstance::Stop ( )

Stop the motion, using the currently set fade-out time. This will blend the weight into zero.

◆ Stop() [2/2]

void EMotionFX::MotionInstance::Stop ( float  fadeOutTime)

Stop the motion, using a given fade-out time. This will first modify the fade-out time and then fade to a zero weight.

Parameters
fadeOutTimeThe time it takes, in seconds, to fade out the motion.

◆ UnPause()

void EMotionFX::MotionInstance::UnPause ( )

Unpause the motion instance.

◆ Update()

void EMotionFX::MotionInstance::Update ( float  timePassed)

Update the motion info.

Parameters
timePassedThe time passed, in seconds.

◆ UpdateByTimeValues()

void EMotionFX::MotionInstance::UpdateByTimeValues ( float  oldTime,
float  newTime,
AnimGraphEventBuffer outEventBuffer 
)

Update based on an old and new time value. This will update the motion instance internally as it was previously at oldTime and now has progressed towards newTime. This does not simply change the current time value, but really detects loops, increasing loop counts, triggering events, etc.

Parameters
oldTimeThe previous time value of the current motion time.
newTimeThe new current motion time.
outEventBufferThe output event buffer. This can be nullptr if you want to skip triggering events.

◆ UpdateTime()

void EMotionFX::MotionInstance::UpdateTime ( float  timePassed)

Updates the current play time value. This is automatically called.


The documentation for this class was generated from the following file: