About Motion

[Last updated: 01/06/2022]


Classes required before motion can be played

1. Class that holds motion data and operates on the model

a. Create an instance (read motion3.json file)

b. Settings for how motion is played back

c. Destroying instances

2. Motion management class

a. Instance creation

b. Motion playback

c. Update model parameters

d. Termination of motion

e. Receipt of user triggers


1-a. Creating an instance of motion (.motion3.json file is read)

The CubismMotion class, derived from the ACubsimMotion class, is used for motion playback.
The data used for motion is a motion file with the extension “.motion3.json”.
You cannot use “.mtn” in Cubism 2.1.
To load this .motion3.json file, use the Native (C++) CubismMotion::Create function or the Web (TypeScript) CubismMotion.create function.
Load the json file once and then load it passing the buffer and size.



1-b. Playback method setting for each motion file

The main items to be set for motion are as follows.
Playback is possible without these settings.

* Fade-in time at start of motion

It can be set by ACubismMotion::SetFadeInTime function in Native (C++) or ACubismMotion.setFadeInTime function in Web (TypeScript), and
obtained with the ACubismMotion::GetFadeInTime function in Native (C++) or the ACubismMotion.getFadeInTime function in Web (TypeScript).
Specify the fade-in time in seconds.

* Fade-out time at end of motion

It can be set by ACubismMotion::SetFadeOutTime function in Native (C++) or ACubismMotion.setFadeOutTime function in Web (TypeScript), and
obtained with the Native (C++) ACubismMotion::GetFadeOutTime function or the Web (TypeScript) ACubismMoiton.getFadeOutTime function.
Specify the fade-out time in seconds.

* Loop playback ON/OFF

It can be set by void CubismMotion::IsLoop(csmBool loop) function in Native(C++) or CubismMotion.setIsLoop function in Web(TypeScript), and
obtained with the Native(C++) csmBool CubismMotion::IsLoop() function or the Web(TypeScript) CubismMotion.isLoop function.
If set to true, playback starts from the beginning at the end.
It continues to loop indefinitely until another motion interrupts or the end instruction is called.
If not set, the default value is false (no loop).

* ramework's looping behavior is not guaranteed to be exactly the same as the editor's looping behavior.
* Currently, Animator is unable to reflect loop settings in the motion3.json file, so
the Framework ignores the loop setting in the motion3.json file and sets it to false.

Setting example (* These settings should be made before the motion is played back.)

1-c. Destruction of instances

Cubism SDK for Web does not require explicit destruction.


For information on how to set motion fade values from a file:

A. How to set as an overall value in the .motion3.json file (overall fade)

B. How to set as individual parameter values in the .motion3.json file (parameter fade)

C. How to set as an overall value in the .model3.json file

There are three above, with priority applied in the order of B, C, and A.
If none is specified, the default value of 1 second is set.




2-a. Creating an instance of motion management class

To apply (animate) an instance of the CubismMotion class created in the previous section to a model, use the CubismMotionManager class.



2-b. Motion playback

Use the Native(C++) CubismMotionManager::StartMotionPriority function or the Web(TypeScript) CubismMotionManager.startMotionPriority function for motion playback.

First argument: ACubismMotion instance, motion data

Pass an instance of motion data.
This argument can be instances of CubismMotion and CubismExpressionMotion, which are derived instances of ACubismMotion.
Generally, only one instance type should be handled by a single motion manager.

Second argument: Boolen, flag for automatic deletion

This is a flag indicating whether or not motion data is automatically deleted when playback is finished.
Used for motions that are played back only once.

Third argument: Int, Priority

Specifies the priority setting for playback managed by CubismMotionManager.
Denial of playback by priority must be done outside of CubismMotionManager.
Please see the CubismMotionManager section at the bottom of the page regarding priority.

If you want to play multiple motions simultaneously, increase the number of CubismMotionManager instances.
This can be used for things such as controlling the motion of the right and left hands separately.
When playing back motions simultaneously, avoid making settings for the same parameter as much as possible.
In this case, the parameters of the last updated motion will take effect.
Also, the fade may not be applied cleanly.


2-c. Update model parameters

With Native (C++) CubismMotionManager::StartMotionPriority function or Web (TypeScript) CubismMotionManager.startMotionPriority function,
simply playing back motion does not animate the model.
To set the parameters of the currently playing motion to the model,
call the Native(C++) CubismMotionManager::UpdateMotion function or the Web(TypeScript) CubismMotionmanager.updateMotion function at each drawing.

First argument: CubismModel instance, model to which motion is applied

Used only to obtain and manipulate parameter information.

Second argument: Float, difference time since last run

Enter the difference time calculated by Update, etc.
Float Enter a real number in seconds. Enter 0.016 in 1/60 seconds for execution at 60FPS and 0.03 in 1/30 seconds for 30FPS.


You can slow, stop, or fast-forward by adjusting the deltaTimeSeconds input.
However, reverse playback using negative values is designed out of consideration.



2-d. Termination of motion

Motion will automatically end when the playback time has expired, but
if you want to terminate at an arbitrary time, you can use the Native(C++) CubismMotionQueueManager::StopAllMotions function
or Web(TypeScript) CubismMotionQueueManager.stopAllMotions function.
If two or more motions are playing at the same time, such as in the middle of a fade, all of them are terminated.



2-e. Event Receipt

When an “event” set in motion is played back,
it can be called by a callback registered with Native (C++) SetUserTriggerCallback function in CubismMotionQueueManager
or the setUserTriggerCallback function of Web(TypeScript).
Only one callback can be registered.
When you want to call a function of an instance, register a static function with a pointer to the instance, and
use a pointer to the registered instance from a static function to call the desired function.
If you want to perform multiple actions, call them one after the other, starting with one callback.

The CubismUserModel class has this mechanism built in by default.
Native (C++) (CubismUserModel::UserTriggerEventFired function, CubismUserModel::CustomDefaultUserTriggerCallback function)
or Web (TypeScript) (CubismUserModel.customerDefaultUserTriggerCallback function)


Automatic deletion of motion

If you put true in the second argument autoDelete when calling the Native (C++) CubismMotionQueueManager::StartMotion function or the Web (TypeScript) CubismMotionQueueManager.startMotion function,
when the motion finishes playing, the motion is deleted along with the deletion of the CubismMotionQueueEntry.
It is intended to be used for files that are played only once.



CubismMotionQueueManager and CubismMotionManager classes

The motion management classes include the CubismMotionQueueManager class and
a CubismMotionManager class that extends the CubismMotionQueueManager class.



The CubismMotionQueueManager is responsible for switching the degree to which motion values are applied with a fade.

LAppModel::StartMotion function in Native (C++) or LAppModel.startMotion function in Web (TypeScript) for motions that are already playing when adding motion playback,
StartFadeout brings forward the end time.

This operation causes the motion currently playing to switch to a new motion with a fade.




The CubismMotionManager class has the ability to save the priority of a motion to be played and to register the priority of the upcoming playback as an integer.
It is envisioned to create a function that regulates motion playback with lower priority by comparing it to this recorded priority.
The part that regulates playback must be prepared outside of CubismMotionManager.

The Native (C++) LAppModel::StartMotion function or the Web (TypeScript) LAppModel.startMotion function supports playback from an asynchronous thread.
At the beginning of the function, the priority of the playback is registered by SetReservePriority and ReserveMotion.
Next, reading is performed, but if this function is called asynchronously, the priority is registered at the beginning, so the
system regulates other low-priority playback on other threads during loading.

At the end of playback, the priority is set to 0, which is fixed, and other controls are left to external parties.

© 2010 - 2022 Live2D Inc.