132 lines
4.8 KiB
Markdown
132 lines
4.8 KiB
Markdown
## Title
|
|
|
|
Packaged `sprimo-tauri` sprite rendering breaks after pack switch; default switch errors and
|
|
scaling stops applying.
|
|
|
|
## Severity
|
|
|
|
P1
|
|
|
|
## Environment
|
|
|
|
- OS: Windows
|
|
- App version/build: packaged release (`sprimo-tauri.exe`)
|
|
- Renderer/backend details: Tauri main overlay + settings pop-out
|
|
- Evidence screenshots:
|
|
- `issues/screenshots/issue4.png`
|
|
- `issues/screenshots/issue4-b.png`
|
|
- `issues/screenshots/issue4-c.png`
|
|
|
|
## Summary
|
|
|
|
In packaged runtime, sprite display is incorrectly split/tiled, switching to `default` can fail,
|
|
and scaling becomes ineffective after the error.
|
|
|
|
## Reproduction Steps
|
|
|
|
1. Run packaged `sprimo-tauri.exe` from ZIP extract.
|
|
2. Open settings window.
|
|
3. Switch character between `ferris` and `default`.
|
|
4. Observe main overlay rendering and debug output.
|
|
5. Change scale slider.
|
|
|
|
## Expected Result
|
|
|
|
- Sprite sheet is split into the correct frame grid regardless of image resolution.
|
|
- Pack switching works for both `ferris` and `default`.
|
|
- Scale changes continue to apply after pack changes.
|
|
|
|
## Actual Result
|
|
|
|
- Main overlay shows incorrectly split/tiled sprite sheet.
|
|
- Pack switch can produce runtime error and break subsequent behavior.
|
|
- Scale update stops working reliably after the error.
|
|
|
|
## Root Cause Analysis
|
|
|
|
1. Existing splitting logic relied on fixed pixel frame metadata that did not generalize to
|
|
packaged `sprite.png` dimension variants.
|
|
2. Pack metadata inconsistency:
|
|
- `assets/sprite-packs/ferris/manifest.json` used duplicated `id` (`default`), causing pack
|
|
identity ambiguity.
|
|
3. Settings/runtime flow then entered an unstable state after pack switch failures.
|
|
4. Renderer reload lifecycle in tauri UI was unsafe:
|
|
- `PixiPetRenderer::dispose` performed duplicate teardown (`ticker.destroy` + `app.destroy`),
|
|
which could trigger runtime `TypeError` during pack reload.
|
|
- Renderer replacement disposed previous renderer before new renderer creation succeeded, leaving
|
|
the view in a broken/cropped state on creation failures.
|
|
5. Chroma-key conversion tolerance removed most `#FF00FF` background but still left magenta fringe
|
|
on anti-aliased edges.
|
|
|
|
## Fix Plan
|
|
|
|
1. Introduce generic splitter policy for `sprite.png`:
|
|
- fixed topology: `8` columns x `7` rows
|
|
- derive frame size from actual image dimensions
|
|
- keep chroma-key background handling (`#FF00FF`) in renderer
|
|
2. Validate animation frame indices against fixed frame count (`56`) for `sprite.png`.
|
|
3. Ensure pack apply path validates atlas geometry before committing `SetSpritePack`.
|
|
4. Fix ferris manifest ID uniqueness.
|
|
|
|
## Implementation Notes
|
|
|
|
Implemented:
|
|
|
|
1. `crates/sprimo-tauri/src/main.rs`
|
|
- Added `sprite.png`-specific frame derivation (`8x7`) from PNG dimensions.
|
|
- Added PNG header dimension decoding utility.
|
|
- Added animation frame index validation against fixed `56` frames for `sprite.png`.
|
|
- Applied validation in both `load_active_sprite_pack` and `set_sprite_pack`.
|
|
|
|
2. `assets/sprite-packs/ferris/manifest.json`
|
|
- Changed manifest `id` from `default` to `ferris`.
|
|
|
|
3. `docs/SPRITE_PACK_SCHEMA.md`
|
|
- Documented Tauri `sprite.png` override behavior and 8x7 derived frame policy.
|
|
|
|
4. `frontend/tauri-ui/src/renderer/pixi_pet.ts`
|
|
- Made renderer disposal idempotent and removed duplicate ticker destruction.
|
|
- Delayed DOM canvas replacement until atlas load succeeds.
|
|
- Improved chroma-key edge handling with soft alpha + magenta spill suppression.
|
|
|
|
5. `frontend/tauri-ui/src/main.tsx`
|
|
- Made pack reload transactional (keep old renderer until new renderer creation succeeds).
|
|
- Improved fit-window flow so scale apply continues after reload retries.
|
|
- Added targeted diagnostics for reload failures.
|
|
|
|
## Verification
|
|
|
|
### Commands Run
|
|
|
|
- [ ] `just build-release-tauri`
|
|
- [ ] `just package-win-tauri`
|
|
- [ ] `just smoke-win-tauri`
|
|
- [x] `cargo check -p sprimo-tauri`
|
|
|
|
### Visual Checklist
|
|
|
|
- [x] Before screenshot(s): `issues/screenshots/issue4.png`
|
|
- [x] Before screenshot(s): `issues/screenshots/issue4-b.png`
|
|
- [x] Before screenshot(s): `issues/screenshots/issue4-c.png`
|
|
- [ ] After screenshot(s): `issues/screenshots/issue4-after-YYYYMMDD-HHMMSS.png`
|
|
|
|
### Result
|
|
|
|
- Status: `Fix Implemented`
|
|
- Notes: packaged runtime validation and after screenshots for this round are pending.
|
|
|
|
## Status History
|
|
|
|
- `2026-02-14 00:00` - reporter - `Reported` - packaged runtime failure screenshots attached.
|
|
- `2026-02-14 00:00` - codex - `Triaged` - localized to sprite splitting/pack identity behavior.
|
|
- `2026-02-14 00:00` - codex - `Fix Implemented` - applied 8x7 generic splitter policy and pack-ID correction.
|
|
- `2026-02-14 00:00` - reporter - `In Progress` - reported `issue4-after-fix1` still failing in packaged runtime.
|
|
- `2026-02-14 00:00` - codex - `Fix Implemented` - hardened renderer reload/dispose and chroma-key edge cleanup.
|
|
|
|
## Closure
|
|
|
|
- Current Status: `Fix Implemented`
|
|
- Close Date:
|
|
- Owner:
|
|
- Linked PR/commit:
|