Adding Custom Live2D Avatars

Yumi is designed to support custom Live2D avatars. You are not locked into the default visual look! You can download any Cubism 4 compatible model (from creators on platforms like Booth.pm or Nizima) and load it directly.

Follow this guide to swap Yumi's visual appearance.

1. Structure Your Model Folder

Live2D Cubism models are exported as a bundle of assets. Yumi requires the model to follow the standard Cubism 4 layout.

Ensure your downloaded model folder contains:

An authoritative .model3.json file (this coordinates all other assets).
A .moc3 binary model file.
One or more .png texture atlases.
A motions/ and expressions/ subfolder (containing .motion3.json and .exp3.json files).

2. Place in Yumi's Avatar Directory

For security and modularity, Yumi loads custom avatars from a specific system-level directory:

Windows: C:\Users\YourName\.yumi\avatar\
macOS / Linux: ~/.yumi/avatar/

Create a subdirectory matching your character's name and paste all files inside it:

~/.yumi/avatar/my_custom_waifu/
   ├── my_custom_waifu.model3.json
   ├── my_custom_waifu.moc3
   ├── my_custom_waifu.physics3.json
   └── textures/

3. Update the WebUI Loader

Once your custom model is placed in the folder, you must instruct the HTML5 frontend to compile and load it.

Open the web UI index file: src/yumi/assets/webui/index.html

Locate the line defining modelUrl (around line 111):

const modelUrl = "/Yumi_Avatar/huohuo.model3.json";

Replace huohuo.model3.json with the exact filename of your new custom model's .model3.json file:
```
const modelUrl = "/Yumi_Avatar/my_custom_waifu.model3.json";
```
Save the file and refresh your browser! Yumi's backend automatically mounts ~/.yumi/avatar/ to the web server under /Yumi_Avatar, so your new model will compile and load instantly!

Proceed to the Parameter Mapping page to customize how she emotes!