# 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`