How to use CubismJavaFramework directly

[Last update: 10/06/2022]

Cubism SDK for Java is currently in alpha version, and the specifications may change in the beta or official version.

The sample project included with the Cubism SDK for Java uses the CubismJavaFramework (under /Framework/ in the SDK package) to handle Cubism models.
When creating a project that handles Cubism models, it is best to use the sample project as a basis, but there may be times when you want to handle the Cubism JavaFramework API directly when implementing it in an existing application or in your own engine. However, there are cases where you may want to use the CubismJavaFramework API directly.
However, the included sample project is highly functional, so it is not easy 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 used to take an allocator (ICubismAllocator) as the first argument, but Cubism SDK for Java (alpha version) Cubism SDK for Java does not use it.


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


Get the path to the model file

The set of data for Cubism embedding is described by their relative paths in .model3.json.
You can directly specify MOC3 files, textures, etc. to be loaded, but basically we recommend that you obtain the path from .model3.json and load them.

The CubismModelSettingJson class of CubismFramework is used to parse .model3.json.



Loading the model

The model is loaded through the CubismModel interface.

Instances of CubismModel are held by CubismUserModel._model in the CubismJavaFramework.
When using this, it is recommended to handle it from a class inheriting from CubismUserModel.
Resource management for textures, motion, facial expression motion, etc. can also be done externally.

As an example, we will use CubismUserModelExtend, which extends CubismUserModel.


The path to the MOC3 file to be loaded can be obtained in .model3.json as described above, and similarly the path to facial expressions, physics, poses, blinking, 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 instances of the same number of CubismUserModel derived classes as the models to be displayed.


Update process

The Cubism model update process is performed by calling CubismModel.update(), which is the interface to CubismModel, as well as model initialization.
Calling CubismModel.update() updates the Cubism Core and updates vertex information from the values of parameters and parts that have been set so far.

The update process always performs eye tracking, physics, motion playback, etc. before 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.


CubismMotionManager.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 CubismMotionManager.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.saveParameters() before and after the process of applying the motion to 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 physics operations and vertex information updated by the _model.update function to the renderer, the Cubism model can be drawn on the screen.


Model Destruction

Cubism SDK for Java (alpha version) Cubism SDK for Java basically leaves resource release to garbage collection, but model generation is achieved by using the Java Native Interface (JNI) to access Native functions.
Therefore, a delete operation must be performed for this location.



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 not dependent on model data and can be used across multiple models.
Therefore, there is no need to call CubismFramework.dispose() if you just want to switch models.

© 2010 - 2022 Live2D Inc.