home / skills / project-n-e-k-o / n.e.k.o / live2d-expression-404-triage

live2d-expression-404-triage skill

safe

/.cursor/skills/live2d-expression-404-triage

This skill triages Live2D expression 404 errors by aligning EmotionMapping and FileReferences paths to ensure correct expression loading.

npx playbooks add skill project-n-e-k-o/n.e.k.o --skill live2d-expression-404-triage

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.8 KB

---
name: live2d-expression-404-triage
description: Diagnose and fix Live2D expression 404 errors caused by mismatch between EmotionMapping expression file paths and FileReferences.Expressions names. Use when logs show expressionXX.exp3.json 404, Failed to load expression, or temporary click effect expression playback failures.
---

# Live2D Expression 404 Triage

## Quick checks

1. Confirm error signature in console:
   - `Failed to load resource ... expressionXX.exp3.json 404`
   - `Failed to load expression: expressionXX.exp3.json`
2. Locate click/effect path:
   - `static/live2d-interaction.js` in `_playTemporaryClickEffect`
   - `static/live2d-emotion.js` in `playExpression`
3. Check whether code maps by strict equality only (`expr.File === choiceFile`).

## Root cause pattern

- `EmotionMapping.expressions` may contain basename only (for example `expression15.exp3.json`).
- `FileReferences.Expressions` often stores full relative path (for example `expressions/expression15.exp3.json`).
- Strict comparison fails, code falls back to inferred name, and runtime loads wrong path.

## Fix pattern

1. Add a shared resolver in `Live2DManager` (core file):
   - Normalize paths (slash style, leading `./` or `/`, case).
   - Match in two passes:
     - exact normalized file path
     - basename fallback
   - Return `expr.Name` from `FileReferences.Expressions`.
2. Replace duplicated file->name conversion logic with this shared resolver.
3. If resolver returns null:
   - avoid forcing native `currentModel.expression()` with guessed name;
   - fall back to file-based/manual expression path when available.

## Regression checks

- Clicking model no longer triggers repeated expression 404 logs.
- Temporary click effects still recover after timeout.
- Persistent expression re-apply flow still runs.
- Existing models with full path mapping still behave the same.

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

FAQ

What exact log lines confirm this issue?

Look for Failed to load resource ... expressionXX.exp3.json 404 and Failed to load expression: expressionXX.exp3.json in the console.

Why not just always use basename matching?

Basename-only matching hides real path issues and can cause incorrect fallback choices; the resolver first tries exact normalized path then falls back to basename to be both correct and tolerant.