Skip to content

Live2D ZIP archives can fail to load when optional settings references are null #1933

@NashChennc

Description

@NashChennc

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

  • Follow our Code of Conduct
  • Read the Contributing Guide.
  • Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
  • Check that this is a concrete bug. For Q&A, please open a GitHub Discussion instead.

Contributions

  • I am willing to submit a PR to fix this issue
  • I am willing to submit a PR with failing tests (actually just go ahead and do it, thanks!)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No fields configured for Bug.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions