Adding a model to the sample project

Last update [09/04/2019]


This page describes the steps to add a Live2D Cubism model to the Live2D Cubism SDK for Native sample.
Samples should be built in advance with reference to “Building Samples”.


Prepare Editor and Cubism Viewer (for OW)

When adding a model to a project, various data processing is required.
Prepare the Editor. When installed, “Cubism Viewer (for OW)” will also be installed.

“Cubism Editor”


Model Preparation

First, prepare the model to be added.
In this tutorial, we will add the sample model “Miara” to the sample project.

When adding the model, we also process the model to match the sample program at the same time.


Addition of a hit detection

The sample program has the following elements.
• Clicking on the area set as “Head” in the model changes the facial expression.
• Clicking on the area set as “Body” in the model will play a random motion.
Since these are not present in the sample miara, we will add hit detection for the head and torso.
For operations on the Editor side, please refer to “Preparing for the Hit Decision”.

Add two ArtMeshes for the percussion as follows.

1. Hit judgment

2. Percussion 2


Adding User Data

The sample program using Cocos2d-x has the ability to display the user data area as well as the hit detection.
This time, we will use this feature with additional user data.
Create an ArtMesh to which user data will be set and configure it as follows.
See “UserData” for information on adding user data.

I added the user data 'Wisp' to the fairy light effect part.


Add parameter settings

No parameters for blinking or lip-sync are also specified in the model data for Miara. These settings are also added in the Editor.
Please refer to “Eye Blinking Settings” for the setting method.

In this case, the following settings were made.




Additional motion for facial expressions

Miara has motion for walking and actions, but no motion for facial expressions, which we will add.
To create motions for facial expressions, please refer to the following. The work is almost the same for 3.1.

“Creating facial expressions in Animator”

This time we have added the following three such expressions.

happy normal sad


Working with Cubism Viewer (for OW)

Some of the model data available in the Framework is created in Cubism Viewer (for OW) as well as in the Editor.


HitArea Settings

Simply defining a HitArea on an ArtMesh in the Editor is not enough for the application to recognize it.
Add information to the .model3.json file for the application to recognize it.
Using the Cubism Viewer (for OW) feature, this information can be automatically populated.



Adding Pose Files

The Pose function is configured in Cubism Viewer (for OW).
For more information on the pose function, see “About Pose” and “Pose Settings”.
In this model, there are no parts to be switched, so no settings are made.


Conversion and registration of facial expressions

The motion for facial expressions created in Animator earlier cannot be used as is as a facial expression file.
It must be converted to an .exp3.json file in Cubism Viewer (for OW).
To create a file for expression, please refer to the following. The process is almost the same for versions 3.1 and later.

“Setup and Export of Facial Expressions”

This time, both eyes are opened and closed to multiply mode.


Motion Registration

The motion file registers how the model is used in the program.
For details on how to register motions in Cubism Viewer (for OW), please refer to “Motion Settings”.

In this registration, the group settings are set to Scene1.motion3.json as Idle and
Scene2.motion3.json and Scene3.motion3.json as TapBody.
Other settings are left at default.


Output final model file

After each setting is completed, write out the model settings (.model3.json file).
At this time, unsaved .exp3.json and .pose3.json files are written out at the same time.
See “Exporting Model Configuration Files” for detailed export instructions.

According to the specifications of the sample program, the file name should be the same as the name of the folder to be written.
This is specified by the folder name string and set to the specification that reads the folder name.model3.json file.


Exporting results in a file similar to the one shown above.


Viewing JSON Contents

Before we move on to the program, let's take a peek at the model3.json file.
Open miara.model3.json with a text editor to see the following code.

All settings are output in Json format and can be created and edited in a text editor as long as the formatting of each setting is followed.
The specifications of each Json can be checked at “CubismSpecs” on Github.



Program-side changes

First, add the folder of the finished model to the resources folder.

To add to the Cocos2d-x sample,
add to [root]SamplesCocos2d-xDemoResources folder

To add to the OpenGL sample,
add to [root]SamplesOpenGLDemoResources folder

Then add the string 'miara' to ModelDir in LAppDefine.cpp.

This completes the process of adding a model.
Let's build and run it. Press the gear icon in the upper right corner of the screen for the number of times it is matched to ModelDir[], and Meara will appear in the center of the screen.



Data Verification

If it is a Cocos2d-x project, you can visualize the range of the hit and Userdata.

Check to see if the various data are really loaded.

First, change DebugDrawRectEnable in LAppDefine.cpp to true.

This code will display the range of the ArtMesh where the hit decision and user data are located.

Red is the HitArea and blue is the range where user data is located.


Is the actual information you are getting correct?
Let's add debug output and check it out.
Add the following to the LAppModel::GetUserDataAreas function in LAppModel.cpp.

When executed with range display enabled, the contents of the user data will be output to the VisualStudio output window.



CubismLogInfo is a macro for debugging output to extract and examine internal movements.

© 2010 - 2022 Live2D Inc.