Describe the bug
Bug Report
Some Live2D ZIP archives cannot be loaded even though their file structure is valid.
model/
model.model3.json
model.moc3
textures/model_00.png
motions/idle.motion3.json
With settings shaped like:
{
"Version": 3,
"FileReferences": {
"Moc": "model.moc3",
"Textures": ["textures/model_00.png"],
"Physics": null,
"Motions": {
"": [{ "File": "motions/idle.motion3.json" }]
}
}
}
Actual Behavior
The loader treats nullable optional settings references as real file references. During ZIP loading or OPFS cache replay, validation attempts to resolve null as a path and fails before the model can render.
The OPFS cache path can also behave differently from the first ZIP load because the previous cache implementation stores a reconstructed resource list and rewritten .model3.json instead of the original ZIP directory contents.
Expected Behavior
Valid Live2D archives should load consistently from the original ZIP and from OPFS cache.
Optional FileReferences entries that are explicitly null should behave like missing optional references.
Impact
Affected Live2D models cannot be imported or rendered through the model selector, even when all required model, texture, and motion files are present.
System Info
System:
OS: macOS 26.4.1
CPU: (10) arm64 Apple M4
Memory: 205.75 MB / 16.00 GB
Shell: 5.9 - /bin/zsh
Binaries:
Node: 24.16.0 - ~/.local/state/fnm_multishells/44256_1780397299721/bin/node
npm: 11.13.0 - ~/.local/state/fnm_multishells/44256_1780397299721/bin/npm
pnpm: 10.33.0 - ~/.local/state/fnm_multishells/44256_1780397299721/bin/pnpm
Browsers:
Safari: 26.4
Validations
Contributions
Describe the bug
Bug Report
Some Live2D ZIP archives cannot be loaded even though their file structure is valid.
With settings shaped like:
{ "Version": 3, "FileReferences": { "Moc": "model.moc3", "Textures": ["textures/model_00.png"], "Physics": null, "Motions": { "": [{ "File": "motions/idle.motion3.json" }] } } }Actual Behavior
The loader treats nullable optional settings references as real file references. During ZIP loading or OPFS cache replay, validation attempts to resolve
nullas a path and fails before the model can render.The OPFS cache path can also behave differently from the first ZIP load because the previous cache implementation stores a reconstructed resource list and rewritten
.model3.jsoninstead of the original ZIP directory contents.Expected Behavior
Valid Live2D archives should load consistently from the original ZIP and from OPFS cache.
Optional
FileReferencesentries that are explicitlynullshould behave like missing optional references.Impact
Affected Live2D models cannot be imported or rendered through the model selector, even when all required model, texture, and motion files are present.
System Info
System: OS: macOS 26.4.1 CPU: (10) arm64 Apple M4 Memory: 205.75 MB / 16.00 GB Shell: 5.9 - /bin/zsh Binaries: Node: 24.16.0 - ~/.local/state/fnm_multishells/44256_1780397299721/bin/node npm: 11.13.0 - ~/.local/state/fnm_multishells/44256_1780397299721/bin/npm pnpm: 10.33.0 - ~/.local/state/fnm_multishells/44256_1780397299721/bin/pnpm Browsers: Safari: 26.4Validations
Contributions