build-vesperfall-review-assets

Build Vesperfall Review Assets

Create one reviewable asset pair without confusing catalog media, imported files, procedural factories, and future contracts.

Workflow

1. Inspect repository truth before choosing a model path.
   • Locate shipped PNG, FBX, GLB, textures, runtime factories, and declared-but-missing paths.
   • Prefer a shipped FBX/GLB when it is the actual runtime source.
   • Use $img2threejs only when reconstructing from an image in code. Never relabel imported geometry as img2threejs.
   • Do not claim a GLB or texture exists because code declares a future URL.
2. Produce the transparent catalog reference.
   • Reuse or derive from the production portrait when it already matches the asset identity.
   • Normalize catalog copies to 512×512 RGBA unless the project contract says otherwise.
   • Keep transparent corners and avoid baked floor, halo, or shadow.
   • Store project-bound output under public/asset-catalog/<category>/.
3. Build the live model preview.
   • Put loading/model construction in a small asset-specific module.
   • Preserve runtime provenance in userData: source paths or factory, action count, sockets, and review-only status.
   • Attach equipment to named sockets. Keep materials, renderer, mixers, events, and animation frames disposable.
   • Frame from measured bounds. Ground from foot/contact geometry, not the lowest weapon tip.
4. Pair the catalog surfaces.
   • Card/grid: transparent PNG only, with no canvas.
   • Selected inspector: one live model canvas plus truthful format label.
   • Add a button to an isolated preview or moveset route.
   • Keep fallback media visible until WebGL/model loading is ready.
5. Build the isolated review route.
   • Expose the real action library when clips exist.
   • Provide restart, pause/play, action selection, drag rotation, source paths, and provenance.
   • For procedural motions, mark runtime, contract, and candidate actions separately.
6. Validate before committing.
   • Run scripts/validate_pair.py <png> <model-source>.
   • Add inventory tests for exact paths, RGBA dimensions, preview kind, and route.
   • Test every motion/contact point deterministically when grounding changes with animation.
   • Run build, lint, full tests, and git diff --check.
   • Use the Codex in-app browser only. Verify desktop and mobile, card PNG/no canvas, inspector model/one canvas, preview navigation, grounding, scroll, overflow, broken media, and console warnings/errors.
7. Commit the narrow task and hand off its exact SHA before deployment reconciliation.

Read references/catalog-contract.md when changing catalog types, provenance language, or review-route behavior.

Required reporting

Report:

• PNG path, dimensions, and alpha status
• model source or procedural factory
• whether the model is imported, runtime procedural, or review-only reconstruction
• preview route and available actions
• test/build/browser proof
• exact commit SHA