#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

Motion *	GetMotion () 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

ActorInstance *	GetActorInstance () 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 ()

MotionInstanceEventHandler *	GetEventHandler (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 MotionLinkData *	FindMotionLinkData (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 MotionInstance *	Create (Motion motion, ActorInstance actorInstance)

static MotionInstance *	Create (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

eventHandler The 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

info	The playback info settings to initialize from.
resetCurrentPlaytime	Set 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

eventInfo The 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

info	The 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

info	The 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

eventHandler A 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

mode	The 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

enabled Set 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

canOverwrite Set 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

time	The current time in the animation, in seconds.
resetLastTime	When 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

normalizedTimeValue The 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

customDataPointer The 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

deleteOnZeroWeight Set 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

weightThreshold The 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

fadeTime The 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

enabled Set 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

enabled Set 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

numLoops The 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

playTime The 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

enabled Set 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

mixModeEnabled Set 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

enabled Set 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

enable Set 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

numCurrentLoops The number of times the motion has been played.

◆ SetPause()

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

Set the pause mode.

Parameters

pauseEnabled When 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

mode	The 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

speed The 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

enabled Set 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

playTime The 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

targetWeight	The weight value we want to blend towards.
blendTimeInSeconds	The 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

fadeOutTime The 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

timePassed The 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

oldTime	The previous time value of the current motion time.
newTime	The new current motion time.
outEventBuffer	The 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:

Gems/EMotionFX/Code/EMotionFX/Source/MotionInstance.h

Classes

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ AddEventHandler()

◆ AZ_DEPRECATED()

◆ GetActorInstance()

◆ GetBlendInTime()

◆ GetBlendMode()

◆ GetBlendOutBeforeEnded()

◆ GetCanOverwrite()

◆ GetCurrentTime()

◆ GetCurrentTimeNormalized()

◆ GetCustomData()

◆ GetDeleteOnZeroWeight()

◆ GetDuration()

◆ GetEventHandler()

◆ GetEventWeightThreshold()

◆ GetFadeTime()

◆ GetFreezeAtLastFrame()

◆ GetHasEnded()

◆ GetHasLooped()

◆ GetID()

◆ GetIsActive()

◆ GetIsBlending()

◆ GetIsFrozen()

◆ GetIsMixing()

◆ GetIsPaused()

◆ GetIsPlaying()

◆ GetIsPlayingForever()

◆ GetIsStopping()

◆ GetLastCurrentTime()

◆ GetMaxLoops()

◆ GetMaxPlayTime()

◆ GetMirrorMotion()

◆ GetMotion()

◆ GetMotionEventsEnabled()

◆ GetMotionExtractionEnabled()

◆ GetNumCurrentLoops()

◆ GetNumEventHandlers()

◆ GetPlayMode()

◆ GetPlaySpeed()

◆ GetPriorityLevel()

◆ GetRetargetingEnabled()

◆ GetTargetWeight()

◆ GetTimeDifToLoopPoint()

◆ GetTotalPlayTime()

◆ GetWeight()

◆ InitFromPlayBackInfo()

◆ OnChangedActiveState()

◆ OnChangedPauseState()

◆ OnDeleteMotionInstance()

◆ OnEvent()

◆ OnHasLooped()

◆ OnHasReachedMaxNumLoops()

◆ OnHasReachedMaxPlayTime()

◆ OnIsFrozenAtLastFrame()

◆ OnQueueMotionInstance()

◆ OnStartBlending()

◆ OnStartMotionInstance()

◆ OnStop()

◆ OnStopBlending()

◆ Pause()

◆ RemoveAllEventHandlers()

◆ RemoveEventHandler()

◆ Rewind()

◆ SetBlendMode()

◆ SetBlendOutBeforeEnded()

◆ SetCanOverwrite()

◆ SetCurrentTime()

◆ SetCurrentTimeNormalized()

◆ SetCustomData()

◆ SetDeleteOnZeroWeight()

◆ SetEventWeightThreshold()

◆ SetFadeTime()

◆ SetFreezeAtLastFrame()

◆ SetIsActive()