mod_live2d_base/docs/en.md

Live2D Cubism — animated 2D characters

Live2D Cubism brings Live2D models into the game: drawn characters that breathe, blink, follow a point, move with physics (hair, clothes) and play the motions and expressions their artist made. It contains the Cubism runtime for C# and its native core libraries; other mods use it to show a model in a scene.

It is an optional block of the Cthangover game. The current story content still uses still portraits, and no built-in game ships a Live2D model yet; the mod's own demo shows a working model.

What a model can do

• Idle life — automatic blinking (on by default) and breathing (off by default).
• Physics — hair and clothes swing according to the model's physics3.json.
• Looking — the head and eyes turn toward a target point; the demo lets you drag the mouse over the character to steer them.
• Motions and expressions — play a motion from a group (mtn_01…) or set an expression (exp_01…) defined in the model.
• Parameters — set any of the model's parameters directly, as in the picture above, where the right arm is raised by one parameter.
• Placement — the model is fitted to its area automatically, or placed at a given position and scale.

Model requirements

A model is the standard Cubism export folder, kept inside a mod:

my_mod/
└── models/
    └── runtime/
        ├── ren.model3.json       the entry file you point to
        ├── ren.moc3
        ├── ren.physics3.json
        ├── ren.cdi3.json
        ├── ren.4096/texture_00.png
        ├── expressions/exp_01.exp3.json …
        └── motions/mtn_01.motion3.json …

• The model is a Cubism model (.moc3 with a model3.json). The demo model is made with Cubism 5.3 and uses its masks and offscreen drawing.
• The native Cubism core is included for Windows (.dll) and Linux (.so).
• Sample models come with Live2D's own licence; read the model's ReadMe.txt before publishing it.

Show a model from a scenario

The add_live2d_model action puts a model into the scene's view:

action add_live2d_model model_path=models/runtime/ren.model3.json mod_id=my_mod node_name=Ren x=960 y=540 scale=0.5

• model_path — the model3.json, relative to the mod's folder;
• mod_id — the mod that contains it;
• node_name — a name for this model in the scene (a second action with the same name is ignored);
• x, y, scale — optional position and size; without them the model is fitted automatically.

A mod with code can create a model with Live2DService.CreateModel(...) and then call StartMotion(group, number), StartExpression(id), SetLiveParameter(id, value) or SetTargetPoint(x, y) on it.

The demo

The mod's avatar test suite contains the sample model Ren. When it is turned on, Ren appears outside the villa in Cthangover and follows mouse drags; its automatic check raises the right arm and compares the frames. It is a developer demo and is off in normal play.

If something goes wrong

1. No model and a log message about model_path or the mod. The path is relative to the mod's folder and must point to the model3.json; mod_id must be the id of the mod that has it.
2. The model appears in the wrong place or size. Give x, y and scale, or leave all three out for automatic fitting.
3. The model does not load on a platform. The Cubism core library is provided for Windows and Linux only.