Rebuild battle unit sprites as raster sheets

docs/unit-sprite-raster-pipeline-v1.md

@@ -0,0 +1,96 @@
+# Unit Sprite Raster Pipeline v1
+
+This pass replaces the active 91 battle unit sheets with raster source art derived from the approved v1 sprite art direction.
+
+## Inputs
+
+- `docs/unit-sprite-quality-contact-sheet-v1.png`
+- `docs/unit-sprite-quality-actual-size-v1.png`
+- `docs/unit-sprite-art-sources/infantry-spearman-master.png`
+- `docs/unit-sprite-art-sources/archer-strategist-master.png`
+- `docs/unit-sprite-art-sources/cavalry-master.png`
+- `docs/unit-sprite-art-sources/rebel-master.png`
+- `docs/unit-sprite-art-sources/nanman-master.png`
+- `docs/unit-sprite-art-sources/commander-master.png`
+
+The art source sheets are hand-painted-style raster generations created for this project. They are not traced from or copied out of existing copyrighted game assets.
+
+## Build Script
+
+`scripts/build-raster-unit-sprites.py` packs the generated raster sources into the runtime sprite sheet format.
+
+The script uses PIL for production processing only:
+
+- crop source cells from the raster source sheets
+- remove source-sheet backgrounds
+- place sprites on a fixed transparent 313x313 canvas
+- keep a shared bottom anchor
+- create faction and rank color variants
+- add small frame offsets for idle, move, attack, hurt, strategy, item, and celebrate timing
+- palette-optimize generated PNGs to 192 colors while preserving alpha
+- save sprite sheets and preview sheets
+
+It does not draw unit bodies from procedural shapes.
+
+## Runtime Format
+
+The generated files keep the existing Phaser mapping intact.
+
+- Frame size: `313x313`
+- Base sheet size: `5008x1252`
+- Base row order: `south`, `east`, `north`, `west`
+- Base columns per direction: 8 idle frames, then 8 move frames
+- Action sheet size: `11268x1252`
+- Action row order: `south`, `east`, `north`, `west`
+- Action columns per direction:
+  - attack: 10 frames
+  - strategy: 8 frames
+  - item: 8 frames
+  - hurt: 4 frames
+  - celebrate: 6 frames
+
+## Outputs
+
+- `src/assets/images/units/unit-*.png`
+- `src/assets/images/units/unit-*-actions.png`
+- `docs/unit-sprite-raster-contact-sheet-v1.png`
+- `docs/unit-sprite-raster-actual-size-v1.png`
+
+The representative contact sheet covers 12 units across commander, infantry, spearman, archer, strategist, cavalry, rebel, Wei, Wu, and Nanman styles.
+
+## Commands
+
+Preview only:
+
+```powershell
+python scripts\build-raster-unit-sprites.py --preview-only
+```
+
+Rebuild all active unit sheets:
+
+```powershell
+python scripts\build-raster-unit-sprites.py
+```
+
+Rebuild selected unit stems:
+
+```powershell
+python scripts\build-raster-unit-sprites.py --only unit-liu-bei,unit-zhao-yun
+```
+
+## Verification Performed
+
+- Rebuilt all 91 active unit definitions.
+- Verified every base sheet is `5008x1252`.
+- Verified every action sheet is `11268x1252`.
+- Reduced the generated runtime unit PNG set from roughly 452 MB to roughly 91 MB with palette PNG encoding.
+- Ran `pnpm build`.
+- Browser-verified the first battle and Red Cliffs vanguard battle at desktop canvas size.
+- Confirmed idle frame changes within the running battle scene.
+- Confirmed attack, hurt, and celebrate poses resolve to `-actions` sheets.
+- Confirmed no browser console errors during the verification run.
+
+Verification screenshots:
+
+- `docs/unit-sprite-battle-first-battle-v1.png`
+- `docs/unit-sprite-battle-redcliffs-v1.png`