live2d-expression-404-triage_skill

Overview

This skill diagnoses and fixes Live2D expression 404 errors caused by mismatches between EmotionMapping expression entries and FileReferences.Expressions names. It provides a focused triage checklist, a resilient path resolver to unify basename and full-path mappings, and regression checks to confirm the fix. Use it to stop repeated expression 404s and restore reliable temporary click/effect playback.

How this skill works

The skill inspects console logs for 404 signatures and locates the playback sites in static/live2d-interaction.js and static/live2d-emotion.js. It detects strict-equality mapping failures where EmotionMapping contains basenames and FileReferences stores full relative paths. The remediation is a shared resolver in Live2DManager that normalizes paths and matches in two passes (exact normalized path, then basename fallback), returning the correct expression Name to avoid guessing and 404s.

When to use it

• When console shows Failed to load resource ... expressionXX.exp3.json 404 or Failed to load expression: expressionXX.exp3.json
• When temporary click/effect expression playback fails or recovers inconsistently
• When code compares expr.File === choiceFile with strict equality
• When EmotionMapping.expressions and FileReferences.Expressions disagree in path style or casing
• When repeated expression 404 logs occur after model clicks

Best practices

• Add a single shared resolver in Live2DManager and remove duplicated file->name conversion logic across modules
• Normalize path separators, leading ./ or /, and casing before any comparison
• Match in two passes: exact normalized path first, then basename fallback
• Avoid forcing native currentModel.expression() with guessed names; fall back to file-based/manual playback when resolver returns null
• Add unit/regression checks to verify click effects, timeouts, and persistent re-apply flows

Example use cases

• Triage an app where logs show expression15.exp3.json 404 when clicking the avatar
• Implement a Live2DManager resolver to bridge EmotionMapping basenames and FileReferences full paths
• Patch static/live2d-interaction.js and static/live2d-emotion.js to call the shared resolver instead of local equality checks
• Run regression checks to confirm temporary click effects recover without 404 spam
• Ensure backwards compatibility for models already using full-path mappings