V2 model touch zones (HitArea)

This page is V2 only (Cubism 4+ / 5) — i.e. *.model3.json models. V1 (journey-ad / Cubism 2~3) models use a separate touch system based on hit_areas_custom, which is not covered here.

1. Where are touch zones declared?

V2 touch zones are defined in the top-level HitAreas field of *.model3.json. Each entry is a name + an ArtMesh ID. The browser uses Cubism Core to compute the ArtMesh's bounding box, and a click that hits the box counts as a click on that HitArea.

{
  "Version": 3,
  "FileReferences": { "...": "..." },
  "HitAreas": [
    { "Name": "Head", "Id": "HitAreaHead" },
    { "Name": "Body", "Id": "HitAreaBody" }
  ]
}

• Name: a logical name. The plugin dispatches actions based on this name. The conventional names are Head and Body, corresponding to the model's "head" and "body".
• Id: the ID assigned to the ArtMesh in Cubism Editor. In the Editor, select the mesh → the right-hand inspector shows / lets you edit this ID.

2. Mapping between HitAreas and motion groups

The dispatch rules match those of the official Live2D CubismWebSamples:

HitArea clicked	Triggered motion group	Group required in model3.json
Head	Random expression switch	Expressions field (not Motions)
Body	Body touch motion	Motions.TapBody

If your model3.json has no Expressions / TapBody, clicking the corresponding area does nothing — but no error is raised.

3. How to mark an ArtMesh as a HitArea in Cubism Editor

1. Open the .cmo3 project, switch to the Modeling view.
2. Select the ArtMesh you want as the hit zone (typically the mesh that covers the head / body).
3. Right-hand inspector → ID, note or set a recognizable ID (e.g. HitAreaHead).
4. When exporting .moc3, tick Embed texture atlas and generate .model3.json.
5. Open .model3.json in a text editor and add an entry to HitAreas: { "Name": "Head", "Id": "HitAreaHead" } (if you ticked "Include HitArea" during export, the Editor writes this automatically).

4. Debugging tips

• If clicking does nothing, check the browser console for motion / expression load errors.
• HitArea hit detection is based on the ArtMesh's actual visible mesh: if the mesh is fully transparent (because you hid it), it still occupies the click box — that's usually why "I can't see anything yet it still responds to clicks" happens.
• Different model authors name things differently: some use HitAreaHead, some head, some name every HitArea HitArea. The plugin dispatches by Name, so make sure Name is Head or Body.

5. Further reading

• Live2D official docs: Hit area setup (Cubism Editor)
• Live2D official docs: model3.json file specification
• This plugin's V2 loader source: live2d_sdk/src/v2/lapplive2dmanager.ts and lappmodel.ts