heros_web/docs/unit-sprite-rework-plan.md

Hand-Painted Unit Sprite Rework Plan

Current Baseline

• Approved baseline commit: 3092b295 Improve handpainted battle unit readability
• Approved batch 1 style references:
  • unit-liu-bei
  • unit-guan-yu
  • unit-zhang-fei
  • unit-rebel
  • unit-rebel-archer
  • unit-rebel-cavalry
• Pending quality restart sample:
  • unit-shu-infantry
  • Source: handpaint-batch2-shu-infantry-quality-restart-source-v3.png
  • Contact sheet: handpaint-batch2-shu-infantry-quality-restart-v3-contact.png
  • Battle-scale composite: handpaint-batch2-shu-infantry-quality-restart-v3-battle-composite.png
  • Approval packet: unit-sprite-shu-infantry-v3-approval-packet.md

Batch Inventory

Generated by scripts/audit-unit-sprite-sheets.py.

Visual review boards are generated by scripts/render-unit-sprite-review-boards.py.

• Review index: unit-sprite-review-index.png

• Approved/pending deliverables only: unit-sprite-review-approved-and-pending.png

• Current Shu batch board: unit-sprite-review-batch2-shu.png

• Review manifest: unit-sprite-rework-manifest.json

• Output checklist: unit-sprite-batch-output-checklist.md

• Pipeline guide: unit-sprite-handpaint-pipeline-guide.md

• Progress log: unit-sprite-rework-progress-log.md

• Next-step report: unit-sprite-next-steps.md

• Batch 1 approved core: 3 sheets

• Batch 1 approved rebel: 3 sheets

• Batch 2 Shu generic: 18 sheets

• Batch 3 Wei generic: 16 sheets

• Batch 4 Wu generic: 16 sheets

• Batch 5 remaining rebel/bandit: 6 sheets

• Batch 6 Nanman/special: 10 sheets

• Batch 7 unique officers: 19 sheets

Batch 2 Shu Order

The Shu infantry v3 sample is the quality gate before expanding the rest of batch 2.

1. unit-shu-infantry - pending approval as the v3 restart sample.
2. unit-shu-spearman - long spear silhouette, green/bronze Shu armor. Spec: unit-sprite-batch2-shu-spearman-spec.md
3. unit-shu-archer - bow silhouette readable at 50px. Spec: unit-sprite-batch2-shu-archer-spec.md
4. unit-shu-cavalry - horse and rider must fit inside tile without lateral drift. Spec: unit-sprite-batch2-shu-cavalry-spec.md
5. unit-shu-strategist - fan/scroll/robe silhouette. Spec: unit-sprite-batch2-shu-strategist-spec.md
6. unit-shu-officer - command/officer silhouette. Spec: unit-sprite-batch2-shu-officer-spec.md
7. Variants after primary classes are approved:
   • unit-shu-infantry-banner
   • unit-shu-infantry-guard
   • unit-shu-spearman-guard
   • unit-shu-spearman-veteran
   • unit-shu-archer-longbow
   • unit-shu-archer-veteran
   • unit-shu-cavalry-scout
   • unit-shu-cavalry-white
   • unit-shu-strategist-field
   • unit-shu-strategist-white
   • unit-shu-officer-council
   • unit-shu-officer-vanguard

Quality Gate

Each unit must pass these checks before batch commit/deploy:

• New hand-painted raster source, not a filter-only or simple shape pass.
• Existing 313x313 frame layout preserved.
• Base sheet size: 5008x1252.
• Action sheet size: 11268x1252.
• Partial alpha: 0.
• Frame border hits: 0 unless a reviewed attack effect intentionally reaches near the border without gameplay clipping.
• Idle/walk body scale and bottom position stable.
• No detached sprite fragments in idle/walk frames.
• 50px battle-scale view reads before the background.
• Contact sheet, GIF, before/after, and battle-scale verification image generated.
• pnpm build passes.
• Local PC browser preview has no console errors.

Approval Gate

• Do not expand to the next unit until the current sample direction is approved.
• Do not commit, push, or deploy an unapproved sample batch.
• Use unit-sprite-review-approved-and-pending.png for quality review of actual deliverables; batch boards still include old queued assets for inventory only.
• Review stages are controlled by unit-sprite-rework-manifest.json, not by whether a sheet is merely technically ok.
• When the user approves a unit or batch, move it from pendingApproval to approvedBaseline in the manifest before regenerating audit/review boards.
• scripts/check-unit-sprite-approval-gate.py --mode sample must pass while a sample is pending.
• scripts/check-unit-sprite-art-quality.py must pass for the current pending sample before asking for approval.
• scripts/check-unit-sprite-workflow-consistency.py must pass so manifest, docs, and gate command lists stay aligned.
• scripts/check-unit-sprite-approval-gate.py --mode release must pass before commit/push/deploy; it blocks pending samples by design.
• scripts/write-unit-sprite-next-steps.py records the current blocker and the first queued unit after approval.
• After a batch is approved, run build/browser verification, then commit, push, and deploy.