How to use CubismWebFramework directly

[Last updated : 01/30/2020]

The sample project included in the Cubism SDK for Web handles Cubism models using the processes under the “/Framework” directory of the SDK package.
However, there are cases where you may want to use the CubismWebFramework API directly when implementing Cubism models in existing applications or your own engine.
However, the included sample project is so sophisticated that it is difficult to understand and isolate the structure just by referring to it.

The following is a minimal snippet that directly calls CubismFramework to handle models for users like those listed above.


CubismFramework Cycle

The procedure for working with CubismFramework is as follows:

  1. Initialization of CubismFramework
  2. Get the path to the model file
  3. Loading the model
  4. Update process
  5. Model Destruction
  6. Exit process of CubismFramework


Initialization of CubismFramework

The initialization process of CubismFramework is as follows:

CubismFramework is initialized using CubismFramework.startUp().
Cubism SDK for Native takes an allocator (ICubismAllocator) as its first argument, but Cubism SDK for Web does not use it.

The contents of printMessage() should be implemented by referring to the function of the same name in the sample.



CubismFramework.initialize() is called only once at initialization, after which successive calls will be skipped unless the CubismFramework instance is destroyed by CubismFramework.dispose().
However, once the CubismFramework instance has been destroyed, CubismFramework.initialize() is called to initialize it again.



Obtaining model files

The set of data for Cubism's built-in data is described in model3.json with their relative paths, and byte data is loaded by referring to this file.
It is recommended to parse model3.json to obtain the path to model files, etc. and load them.

Parsing of model3.json uses CubismFramework's CubismModelSettingJson class.

.moc3 files and textures can also be directly specified and loaded.
If you want to specify directly and have it read, code modification is required.

In the sample, fetch() is used in LAppModel.loadAssets() to retrieve a file from the resource path and read the byte data to get the Json content.



Loading the model

The model is loaded through the CubismModel interface.

The CubismModel instance is held by CubismUserModel._model in CubismNativeFramework, and model data is retrieved and stored using CubismUserModel.loadModel().

When using CubismModel, it is recommended to handle it from a class that extends CubismUserModel.
In the sample, the LAppModel class inherits from and handles CubismUserModel.

Resource management for textures, motion, facial expression motion, etc. can also be done externally.

In the sample, fetch() is used in LAppModel.setupModel() to load model data from a file path stored in ICubismModelSetting.

The path to the moc3 file to be loaded can be obtained in model3.json as described above. Similarly, the path to facial expressions, physics, poses, blinks, lip-sync, user data, and motion can be obtained from model3.json.
The SDK sample loads these at the same time as the model is loaded.
Please refer to the following for each loading method.


The snippet above is based on the assumption that a single model will be displayed on the screen.
To display multiple models on the screen at the same time, create the same number of instances of CubismUserModel derived classes as the number of models to be displayed.



Update process

The update process for a Cubism model is accomplished by setting the target model by passing the parameters and values to be updated through the CubismModel interface, such as CubismModel.setParameterValueById(), and
call CubismModel.update() to update.
Calling CubismModel.update() causes Cubism Core to perform an update process, updating vertex information and other information based on the values of parameters and parts that have been set up to that point.

By passing this updated vertex information, etc. to the renderer, the Cubism model can be drawn on the screen.

The following code directly manipulates model parameters in a class with _model(CubismModel) and calls Cubism Core's update process to apply the operation.


The update process always performs eye tracking, physics, motion playback, etc. before CubismModel.update().

Manipulating parameter values after CubismModel.update() will not take effect.
After that, call CubismModel.update() again to reflect the changes. However, this process is very burdensome, so it is recommended to combine them into a single call.


Cubism MotionManager.updateMotion(), which plays the motion, overwrites any ID parameter values used in the motion to be played.
Therefore, any manipulation of parameter values prior to this process will be overwritten by Cubism MotionManager.updateMotion().
It is recommended that value operations such as line-of-sight tracking and physics operations be performed first, followed by motion playback processing.


Also, if not all parameters are used in the motion to be played back, or if the parameter values are not manipulated because playback of the motion is stopped, the result of the value manipulation done in the previous frame will remain.
Therefore, the results of subsequent relative parameter value manipulations may be unintended.
This can be done by calling CubismModel.loadParameter() and CubismModel.saveParameter() before and after the process of reflecting the motion in the model to reset any subsequent relative value operations.


Please refer to the respective documents for information on eye tracking, physics operations, motion playback, and other processes themselves.

By passing this updated vertex information, etc. to the renderer, the Cubism model can be drawn on the screen.


Model Destruction

To destroy the model, destroy the instance of the generated CubismUserModel derived class.
This destroys the motion, facial expressions, physics, and other information held by this model from the destructor of the CubismUserModel.



Termination process of Cubism Framework

To release common part resources allocated by CubismFramework, call CubismFramework.dispose().
Do not call CubismFramework.dispose() before calling CubismFramework.initialize().


Data initialized in CubismFramework is placed in a static area and does not depend on model data.
Therefore, it can be used across multiple models, and there is no need to call CubismFramework.dispose() if you just want to switch models.

© 2010 - 2022 Live2D Inc.