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

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:

python scripts\build-raster-unit-sprites.py --preview-only

Rebuild all active unit sheets:

python scripts\build-raster-unit-sprites.py

Rebuild selected unit stems:

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