About User Data

[Last update: 12/08/2022]

In Cubism 3.1 or later, a “user data” function is available to add string information to an ArtMesh.

The string data shown in the .userdata3.json file can be programmatically retrieved as information associated with the ArtMesh, and
it can be used as a discriminator for various treatments on the ArtMesh.


As an example, you can use it as follows.

  • The character can be customized by adding tags such as “Skin” and “Hair” and changing the color of the rendering depending on the tag.
  • Describe parameters such as manipulating transparency, and manipulate parameters by the distance from the average coordinates of the mesh to light sources, etc., to express illumination.
  • Put particles only on the tagged mesh.


Instance Creation

User data is described in the .userdata3.json file and handled by the CubismModelUserData class.
The following functions are used to read the data.

  • Native(C++) CubismModelUserData::Create function
  • CubismModelUserData.create function in Web (TypeScript)
  • CubismModelUserData.create function in Java




User data can be accessed using one of the following functions

  • Native(C++) CubismModelUserData::GetArtMeshUserDatas function
  • CubismModelUserData.getArtMeshUserDatas function in Web (TypeScript)
  • CubismModelUserData.getArtMeshUserData function in Java

A dynamic array containing the CubismModelUserDataNode structure is returned, which is accessed like a normal array.

Java a List containing the CubismModelUserDataNode class is returned, which is accessed like a normal List.




The CubismModelUserData class must also be destroyed when the model is released.

Java does not need to be destroyed because garbage collection is responsible for deallocation.



Displaying a range of Userdata

In the Live2D Cubism SDK for Native Cocos2d-x sample, by setting DebugDrawRectEnable in LAppDefine.cpp to true
the position where the ArtMesh is located in HitArea and Userdata will be displayed as a rectangle.

Red is the HitArea and the blue rectangle on the neck scarf is the area where the Userdata exists.

© 2010 - 2022 Live2D Inc.