ユーザデータについて

最終更新: 2023年1月26日

Cubism3.1以降では、アートメッシュに文字列情報を付加する「ユーザデータ」機能を利用できます。

.userdata3.jsonファイルに示される文字列データはプログラム上でアートメッシュに紐づいた情報として取得でき、
アートメッシュに対して様々な処理をする際の判別材料として使用することができます。

例として、以下のような使い方ができます。

  • ”Skin”や”Hair”などのタグを付け、タグによってレンダリング時の色合いを変化させることでキャラクターのカスタマイズを可能にする。
  • 透明度を操作するなどのパラメータを記述し、光源などへのメッシュの平均座標からの距離でパラメータを操作し、照り返しを表現する。
  • タグのあるメッシュだけにパーティクルをつける。

インスタンスの作成

ユーザデータは.userdata3.jsonファイルに記述され、取り扱いはCubismModelUserDataクラスで行われます。
読み込みは以下の関数で行います。

  • Native(C++)のCubismModelUserData::Create関数
  • Web(TypeScript)のCubismModelUserData.create関数
  • JavaのCubismModelUserData.create関数
// C++
csmString path = _modelSetting->GetUserDataFile();
path = _modelHomeDir + path;

buffer = CreateBuffer(path.GetRawString(), &size);

CubismModelUserData* _modelUserData = CubismModelUserData::Create(buffer, size);

DeleteBuffer(buffer, path.GetRawString());
// TypeScript
let path: string = _modelSetting.getUserDataFile();
path = _modelHomeDir + path;

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

        let _modelUserData: CubismModelUserData = CubismModelUserData.create(buffer, size);
        deleteBuffer(buffer, path);
    }
);
// Java
String path = modelSetting.getUserDataFile();
path = modelHomeDir + path;

buffer = createBuffer(path);

CubismModelUserData modelUserData = CubismModelUserData.create(buffer);

アクセス

ユーザデータへのアクセスは以下のいずれかの関数を使用します。

  • Native(C++)のCubismModelUserData::GetArtMeshUserDatas関数
  • Web(TypeScript)のCubismModelUserData.getArtMeshUserDatas関数
  • JavaのCubismModelUserData.getArtMeshUserData関数

CubismModelUserDataNode構造体が入った動的配列が返されるので、通常の配列のようにアクセスします。

Javaの場合は、CubismModelUserDataNodeクラスが入ったListが返されるので、通常のListのようにアクセスします。

// C++
const csmVector<const CubismModelUserData::CubismModelUserDataNode*>& ans =
    _modelUserData->GetArtMeshUserDatas();

for ( csmUint32 i = 0; i < ans.GetSize(); ++i)
{
    CubismIdHandle handle = ans[i]->TargetId;
}
// TypeScript
const ans: csmVector<CubismModelUserData.CubismModelUserDataNode> = _modelUserData.getArtMeshUserDatas();

for(let i: number = 0; i < ans.getSize(); ++i)
{
    let handle: CubismIdHandle = ans[i].targetId;
}
// Java
final List<CubismModelUserDataNode> ans = modelUserData.getArtMeshUserData();

for(int i = 0; i < ans.size(); i++){
  CubismId handle = ans.get(i).targetId;
}

破棄

モデルが解放されるタイミングでCubismModelUserDataクラスも破棄する必要があります。

// C++
CubismModelUserData::Delete(_modelUserData);
// TypeScript
CubismModelUserData.delete(_modelUserData);

Javaの場合はガベージコレクションに解放を任せているので破棄する必要はありません。

Userdataの範囲の表示

Live2D Cubism SDK for NativeのCocos2d-xサンプルではLAppDefine.cppにあるDebugDrawRectEnableをtrueにすることで、
HitAreaとUserdataのアートメッシュがある位置を矩形で表示するようになります。

赤がHitArea、首のスカーフについている青い矩形がUserdataの存在する範囲になります。

この記事に関するご意見・
ご要望をお聞かせください。