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::MotionSystem Class Referenceabstract

#include <MotionSystem.h>

Inherits EMotionFX::BaseObject.

Inherited by EMotionFX::MotionLayerSystem.

Public Member Functions

virtual MotionInstancePlayMotion (Motion *motion, class PlayBackInfo *info=nullptr)
 
virtual uint32 GetType () const =0
 
virtual const char * GetTypeString () const =0
 
virtual void Update (float timePassed, bool updateNodes)=0
 
void RemoveMotion (size_t nr, bool deleteMem=true)
 
void RemoveMotion (MotionInstance *motion, bool delMem=true)
 
virtual bool RemoveMotionInstance (MotionInstance *instance)
 
MotionInstanceGetMotionInstance (size_t nr) const
 
virtual MotionInstanceFindFirstNonMixingMotionInstance () const =0
 
size_t GetNumMotionInstances () const
 
bool CheckIfIsValidMotionInstance (MotionInstance *instance) const
 
bool GetIsPlaying () const
 
bool CheckIfIsPlayingMotion (Motion *motion, bool ignorePausedMotions=false) const
 
void SetMotionQueue (MotionQueue *motionQueue)
 
void AddMotionQueue (MotionQueue *motionQueue)
 
MotionQueueGetMotionQueue () const
 
ActorInstanceGetActorInstance () const
 
void StopAllMotions ()
 
void StopAllMotions (Motion *motion)
 
void AddMotionInstance (MotionInstance *instance)
 
- 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
 

Protected Member Functions

 MotionSystem (ActorInstance *actorInstance)
 
virtual ~MotionSystem ()
 
virtual void StartMotion (MotionInstance *motion, PlayBackInfo *info)=0
 
void UpdateMotionInstances (float timePassed)
 
MotionInstanceCreateMotionInstance (Motion *motion, PlayBackInfo *info)
 
- Protected Member Functions inherited from EMotionFX::BaseObject
void Delete () override
 
virtual void Delete ()
 

Protected Attributes

AZStd::vector< MotionInstance * > m_motionInstances
 
ActorInstancem_actorInstance
 
MotionQueuem_motionQueue
 

Friends

class MotionQueue
 

Detailed Description

The motion system base class. A motion system has to manage how motions are being mixed and blended together. When we make a call to Actor::PlayMotion(...) this system will have to handle the things which need to happen in order to play this motion. Also when motions are stopped it has to handle this. Smooth transitions between motions also have to be handled by this class, as well as the mixing of motions, where specific parts of the body are overwritten by a given motion. The motion system also contains a motion queue, which is responsible for some very basic scheduling of motions.

Constructor & Destructor Documentation

◆ MotionSystem()

EMotionFX::MotionSystem::MotionSystem ( ActorInstance actorInstance)
protected

Constructor.

Parameters
actorInstanceThe actor to which this layer belongs to.

◆ ~MotionSystem()

virtual EMotionFX::MotionSystem::~MotionSystem ( )
protectedvirtual

Destructor.

Member Function Documentation

◆ AddMotionInstance()

void EMotionFX::MotionSystem::AddMotionInstance ( MotionInstance instance)

Add a given motion instance to this motion system.

Parameters
instanceThe motion instance to add.

◆ AddMotionQueue()

void EMotionFX::MotionSystem::AddMotionQueue ( MotionQueue motionQueue)

Add a motion queue to the motion system. All motions in the given motion queue will be put after the existing ones.

Parameters
motionQueueThe motion queue to add.

◆ CheckIfIsPlayingMotion()

bool EMotionFX::MotionSystem::CheckIfIsPlayingMotion ( Motion motion,
bool  ignorePausedMotions = false 
) const

Check if there is a motion instance playing which is an instance of a specified motion. This can be used to check if for example there currently is playing a 'walk' motion on a given actor.

Parameters
motionA pointer to the motion we want to check. So this method will answer the question "Is there still an Actor::PlayMotion( motion ) active?"
ignorePausedMotionsIgnore paused motions and make sure to only return true in case there is an actually playing motion.
Returns
Returns true when there still is a motion instance active, which uses the specified motion, otherwise false is returned.

◆ CheckIfIsValidMotionInstance()

bool EMotionFX::MotionSystem::CheckIfIsValidMotionInstance ( MotionInstance instance) const

Checks if a given motion instance is still valid. With valid we mean if it has not been deleted from memory yet. Because when a motion is stopped the motion instance will automatically be deleted from the Actor as well as from memory. You can validate if a given motion instance is still valid by passing it to this method. NOTE: Be sure to pass only motion instances which are returned by the PlayMotion method of this actor! Here follows some example code:

ActorInstance* human = .....;     // assuming that human now contains a valid Actor.
ActorInstance* orc = ....;        // assuming that orc now contains a valid Actor.
Motion*        walkMotion = ....; // assuming that walkMotion now contains a valid Motion.

// start playing the walk motion on the human
MotionInstance* humanWalk = human->GetMotionSystem()->PlayMotion( walkMotion );

// this is valid to execute, so no problems with this
// isValid will be 'true' at this moment
bool isValid  = human->GetMotionSystem()->IsValidMotionInfo( humanWalk );

// this is VERY WRONG! :)
// you cannot validate a motion instance returned by the human on the orc
// isValid2 will now contain 'false', while the motion is really still valid!
// but it's simply not valid inside the orc...
bool isValid2 = orc->GetMotionSystem()->IsValidMotionInfo( humanWalk );

◆ CreateMotionInstance()

MotionInstance * EMotionFX::MotionSystem::CreateMotionInstance ( Motion motion,
PlayBackInfo info 
)
protected

Create the motion instance and add the motion info the parent actor. It also creates the motion links.

Parameters
motionThe motion from which the system creates the instance from.
infoA pointer to the playback information.
Returns
A pointer to the created motion instance.

◆ FindFirstNonMixingMotionInstance()

virtual MotionInstance * EMotionFX::MotionSystem::FindFirstNonMixingMotionInstance ( ) const
pure virtual

Recursively search for the first non mixing motion and return the motion instance.

Returns
A pointer to the motion instance.

Implemented in EMotionFX::MotionLayerSystem.

◆ GetActorInstance()

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

Return the actor instance to which this motion system belongs to.

Returns
The actor instance to which this motion system belongs to.

◆ GetIsPlaying()

bool EMotionFX::MotionSystem::GetIsPlaying ( ) const

Test if there is currently a motion playing or active. Motions which are in pause mode will also count as playing. So in case of motions being paused a value of "true" will be returned as well.

Returns
True if there is a motion playing, false if not.

◆ GetMotionInstance()

MotionInstance * EMotionFX::MotionSystem::GetMotionInstance ( size_t  nr) const

Get a given motion instance. Every motion instance inside an actor represents a motion which is currently playing or active inside the actor. Motion instances are automatically removed from the actor once they are not used anymore. This for example happens when a motion instance has finished playing. Before you do any calls to methods of a given motion instance, always first use the IsValidMotionInstance() method to check if the motion instance has not yet been removed from the actor (and from memory).

Parameters
nrThe motion instance number to get.
Returns
A pointer to the motion instance.
See also
IsValidMotionInstance

◆ GetMotionQueue()

MotionQueue * EMotionFX::MotionSystem::GetMotionQueue ( ) const

Return motion queue pointer.

Returns
A pointer to the motion queue.

◆ GetNumMotionInstances()

size_t EMotionFX::MotionSystem::GetNumMotionInstances ( ) const

Get the number of active motion instances inside this actor. Every motion instance inside an actor represents a motion which is currently playing or active inside the actor. Motion instances are automatically removed from the actor once they are not used anymore. This for example happens when a motion instance has finished playing. Before you do any calls to methods of a given motion instance, always first use the IsValidMotionInstance() method to check if the motion instance has not yet been removed from the actor (and from memory).

Returns
The number of active motion instances inside this actor.
See also
IsValidMotionInstance

◆ GetType()

virtual uint32 EMotionFX::MotionSystem::GetType ( ) const
pure virtual

Get the unique motion system type ID.

Returns
The motion system type identification number.

Implemented in EMotionFX::MotionLayerSystem.

◆ GetTypeString()

virtual const char * EMotionFX::MotionSystem::GetTypeString ( ) const
pure virtual

Get the type identification string. This can be a description or the class name of the motion system.

Returns
A pointer to the string containing the name.

Implemented in EMotionFX::MotionLayerSystem.

◆ PlayMotion()

virtual MotionInstance * EMotionFX::MotionSystem::PlayMotion ( Motion motion,
class PlayBackInfo info = nullptr 
)
virtual

Start playing the specified motion on this actor.

Parameters
motionThe motion to play.
infoA pointer to an object containing playback information. This pointer is NOT allowed to be nullptr here.
Returns
A pointer to a created motion instance object. You can use this motion instance object to adjust and retrieve playback information at any time.
See also
PlayBackInfo

◆ RemoveMotion() [1/2]

void EMotionFX::MotionSystem::RemoveMotion ( MotionInstance motion,
bool  delMem = true 
)

Remove a given motion.

Parameters
motionThe motion to remove.
delMemIf true the allocated memory of the motion will be deleted.

◆ RemoveMotion() [2/2]

void EMotionFX::MotionSystem::RemoveMotion ( size_t  nr,
bool  deleteMem = true 
)

Remove a given motion.

Parameters
nrThe motion to remove.
deleteMemIf true the allocated memory of the motion will be deleted.

◆ RemoveMotionInstance()

virtual bool EMotionFX::MotionSystem::RemoveMotionInstance ( MotionInstance instance)
virtual

Removes a given motion instance from the actor, including all motion links in the nodes inside this Actor.

Parameters
instanceThe motion instance to remove.
Returns
Returns true when everything went fine and will return false when the instance could not be removed from any of these nodes or from this actor itself.

◆ SetMotionQueue()

void EMotionFX::MotionSystem::SetMotionQueue ( MotionQueue motionQueue)

Set a new motion queue. Old one will be deleted.

Parameters
motionQueueThe motion queue to set.

◆ StartMotion()

virtual void EMotionFX::MotionSystem::StartMotion ( MotionInstance motion,
PlayBackInfo info 
)
protectedpure virtual

Start playing the specified motion on this actor. The difference with PlayMotion is that PlayMotion takes care of the calls to CreateMotionInstance, and handles the insertion into the motion queue, etc. This method should purely start the motion.

Parameters
motionThe motion to play.
infoA pointer to an object containing playback information. This pointer is NOT allowed to be nullptr here.
Returns
A pointer to a created motion instance object. You can use this motion instance object to adjust and retrieve playback information at any time.
See also
PlayBackInfo

◆ StopAllMotions() [1/2]

void EMotionFX::MotionSystem::StopAllMotions ( )

Stop playing all motion instances. The fade-out times used are the ones setup in the motion instances.

◆ StopAllMotions() [2/2]

void EMotionFX::MotionSystem::StopAllMotions ( Motion motion)

Stop playing all motion instances using a given motion object. The fade-out times used are the ones setup in the motion instances.

Parameters
motionAll motion instances that use this given motion will be stopped.

◆ Update()

virtual void EMotionFX::MotionSystem::Update ( float  timePassed,
bool  updateNodes 
)
pure virtual

Update this character motions, if updateNodes is false only time values are updated. If it's true, the heavy calcs (forward kinematics and other transformations) are performed.

Parameters
timePassedThe time passed since the last call.
updateNodesIf true the nodes will be updated.

Implemented in EMotionFX::MotionLayerSystem.

◆ UpdateMotionInstances()

void EMotionFX::MotionSystem::UpdateMotionInstances ( float  timePassed)
protected

Update the motion instances.

Parameters
timePassedThe time passed since the last call.

Member Data Documentation

◆ m_actorInstance

ActorInstance* EMotionFX::MotionSystem::m_actorInstance
protected

The actor instance where this motion system belongs to.

◆ m_motionInstances

AZStd::vector<MotionInstance*> EMotionFX::MotionSystem::m_motionInstances
protected

The collection of motion instances.

◆ m_motionQueue

MotionQueue* EMotionFX::MotionSystem::m_motionQueue
protected

The motion queue.


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