Troubleshooting

Fully restart the game first, then search the log for [Live2D].

The Mod does not load

1. Confirm the game version satisfies min_game_version in Live2D.json.
2. Install the required RitsuLib version.
3. Check that mods/Live2D contains Live2D.json, Live2D.dll, Live2D.pck, and the gd_cubism native files.
4. Fully restart after replacing the DLL.

The model is white or invisible

• Startup logs should report Cubism shaders 10/10.
• Check .moc3, textures, relative paths, and path casing in .model3.json.
• Reset filters, use Normal blending, and temporarily disable canvas clipping.
• Check the target scene, opacity, scale, and master visibility state.

A large model freezes or crashes while loading

• Before entering native Cubism loading, the Mod logs texture count, maximum dimensions, and estimated RGBA8 memory. Search for Beginning native Cubism load.
• The importer adaptively scales the managed copy from the maximum texture dimension and total estimated mipmapped RGBA8 budget: each texture is capped at 2048 pixels and the total at 128 MiB. The source model is untouched, and every optimized PNG is decoded again before the staged import is committed.
• Non-ASCII VTube Studio motion and expression paths are written as native UTF-8. Older managed manifests containing \uXXXX paths are migrated before loading to avoid a native Cubism parser access violation.
• Auto mask resolution is bounded to 1024 and manual values to 2048, preventing multiple Cubism clipping render targets from exhausting GPU memory.
• Native/GPU OOM or device loss can terminate the process without a managed exception. If the log ends at Beginning native Cubism load, include that resource-profile line in the report.

The model or mask looks blurred

• Restore Normal blending, neutral filters, and no canvas mask first. This state renders the model directly without a composite target.
• Canvas masks and MaskViewportSize are separate. Raise the latter only when Cubism drawable-mask edges are blurred.
• Prefer Auto for MaskViewportSize (bounded to 1024); manual values are capped at 2048.
• In Preview and edit, choose a reference resolution close to the actual window and verify model scale before judging clarity.

Mask controls appear to do nothing

• Enable the model mask override or press Enable mask and fit model bounds.
• Make sure the type is not None. Corner radius applies only to Rounded Rectangle; changing the radius switches the type automatically.
• Enable Edit mask directly on canvas, drag to move the mask, use the wheel to resize it, and confirm the sliders and numbers move together.

The model appears in only one scene

Main Menu and In Game use separate settings; Map and Combat share In Game. A Main Menu model is temporarily hidden while another menu page or modal is open.

Motions or expressions are missing

• Cubism models: confirm model3 declares the action.
• VTube Studio models: confirm .vtube.json points to the selected model3 and assets are under expressions or animations.
• Re-import the model to refresh the managed action list.
• Check that its hotkey is enabled in the current scene.
• Check for duplicate hotkeys or conflicting looping motions.

The model shows “Model missing”

Restore managed files for a local model, or enable the provider Mod for a provider model. Live2D preserves the configuration and reactivates the instance and hotkeys when assets become available.

Pack import fails

• The root must contain manifest.json and settings/models.json.
• Format values are FormatVersion = 1 and SettingsSchemaVersion = 6.
• Every model resource must stay under models/<OriginalId>/.
• Absolute paths, .., symlinks, duplicate paths, and suspicious compression are rejected.

If the log says JSON value could not be converted to List<Live2DModelConfig>, change the Pack's settings/models.json root to an array. Check the actual load path in the startup log, compare SHA-256 hashes between the publish directory and mods/<ModId>, and deploy one complete publish set.

See the Pack format for the complete rules.

Reporting an issue

Include the game, RitsuLib, and Live2D versions; relevant [Live2D] log lines; the affected scene; and whether the model or Pack can be shared. Remove personal paths and other sensitive data before posting logs.