Callbacks for start and end of motion playback (Web)

Updated: 12/19/2024

Summary

Cubism SDK for Web allows callbacks to retrieve events at the start and end of motion playback.

In the sample, the callback function outputs log text notifying the user of the start and end of playback.

Callback Implementation

In order to use callbacks when motion playback starts and ends, callbacks have been implemented in Framework/src/motion/acubismmotion, an abstract class that manages motion.

export namespace Live2DCubismFramework
{
    // Definition of the motion playback start callback function
    export type BeganMotionCallback = (self: ACubismMotion) => void;

    // Definition of the motion playback end callback function
    export type FinishedMotionCallback = (self: ACubismMotion) => void
  
    export abstract class ACubismMotion
    {
        ・
        ・
        ・
        // Register motion playback start callback
        public setBeganMotionHandler =
            (onBeganMotionHandler: BeganMotionCallback) =>
                (this._onBeganMotion = onBeganMotionHandler);

        // Register motion playback end callback
        public setFinishedMotionHandler =
            (onFinishedMotionHandler: FinishedMotionCallback) =>
                this._onFinishedMotion = onFinishedMotionHandler;

        // Obtain motion playback start callback
        public getBeganMotionHandler = () => this._onBeganMotion;

        // Obtain motion playback end callback
        public getFinishedMotionHandler = () => this._onFinishedMotion;
        ・
        ・
        ・
        // Variable that contains the callback function to be called when motion playback ends
        public _onBeganMotion?: BeganMotionCallback;

        // Variable that contains the callback function to be called when motion playback ends
        public _onFinishedMotion?: FinishedMotionCallback;
    }
}

Use Callback Functions

Implement what you actually want to be processed in the callback function.

The sample uses LAppPal.printMessage() to output log text notifying the user of the start and end of motion playback.
To change the processing at the start and end of motion playback, change the implementation of the following functions.

_beganMotion = (self: ACubismMotion) => {
    LAppPal.printMessage("Motion Began:");
    console.log(self);
}

_finishedMotion = (self: ACubismMotion) => {
    LAppPal.printMessage("Motion Finished:");
    console.log(self);
}

The callback function is registered when CubismUserModel.loadMotion() is used in the Framework layer to load motion data, and the callback function is passed at the same time the motion is generated.
When motion is already present, setBeganMotionHandler() and setFinishedMotionHandler(), introduced in “Callback Implementation,” are used.

public startMotion(
    group: string,
    no: number,
    priority: number,
    onFinishedMotionHandler?: FinishedMotionCallback,
    onBeganMotionHandler?: BeganMotionCallback
): CubismMotionQueueEntryHandle {
    ・
    ・
    ・
    if(motion == null)
    {
        let path: string = fileName;
        path = this._modelHomeDir + path;

        fetch(path).then(
            (response) =>
            {
                return response.arrayBuffer();
            }
        ).then(
            (arrayBuffer) =>
            {
                let buffer: ArrayBuffer = arrayBuffer;
                let size = buffer.byteLength;

                // Register motion data by passing a callback function at the same time it is loaded.
                motion = <CubismMotion>this.loadMotion(
                    arrayBuffer,
                    arrayBuffer.byteLength,
                    null,
                    onFinishedMotionHandler,
                    onBeganMotionHandler);
                ・
                ・
                ・
            }
        );
    } else {
        motion.setBeganMotionHandler(onBeganMotionHandler);
        motion.setFinishedMotionHandler(onFinishedMotionHandler);
    }
}

In the sample, the callback function is passed from startRandomMotion(), which is called when OnTap() is executed to obtain the tap event.

In addition, since CubismMotion.doUpdateParameters() is actually playing back the motion, the implementation allows the callback function to be passed to CubismMotion.

public static create(
    buffer: ArrayBuffer,
    size: number,
    onFinishedMotionHandler?: FinishedMotionCallback,
    onBeganMotionHandler?: BeganMotionCallback
): CubismMotion {
    const ret = new CubismMotion();

    ret.parse(buffer, size);
    ret._sourceFrameRate = ret._motionData.fps;
    ret._loopDurationSeconds = ret._motionData.duration;
    // Register callback functions
    ret._onFinishedMotion = onFinishedMotionHandler;
    ret._onBeganMotion = onBeganMotionHandler;

    return ret;
}

On the Development of Implementation

In the sample, only the end of motion playback is implemented, but the implementation can be developed to allow asynchronous processing to be used in callback functions at the start and end of motion playback.
Alternately, reversing the function from the actual process to which the callback is to be applied allows callbacks to be implemented at points other than the start and end of motion playback.