nescript/examples/war/PLAN.md

War — Implementation Plan

A production-quality card game example for NEScript. This document is the living plan: each step is checked off as it's completed, and any mid-flight design changes are recorded in the "Design revisions" section at the bottom.

---

1. Scope & quality bar

A production-grade NES version of War:

• Title screen with a big logo, a 3-option menu (0 PLAYERS / 1 PLAYER / 2 PLAYERS), blinking "PRESS START", and music.
• Gameplay with an animated deal, two live decks with running card counts, cards that slide between the decks and the center, a readable face-up card on each side.
• War / tie-breaker flow with a distinct "WAR!" banner, an exciting SFX, and buried cards that actually come out of each player's deck.
• Victory screen with the winning player highlighted and a fanfare.
• Sound: title music, card-flip click, distinct round-win cues for A vs B, exciting WAR tie-break sfx, victory fanfare.

---

2. File layout

examples/war.ne                  # top-level: game decl, palette, background, sprite sheet, includes, start
examples/war/PLAN.md             # this file
examples/war/constants.ne        # gameplay + layout constants
examples/war/audio.ne            # sfx + music declarations
examples/war/state.ne            # global variables (decks, phase, rng, anim timers, ...)
examples/war/rng.ne              # 8-bit LFSR PRNG helpers
examples/war/deck.ne             # queue ops on decks + pot
examples/war/compare.ne          # card rank/suit extraction, round resolver
examples/war/render.ne           # draw_card_front / draw_card_back helpers
examples/war/title_state.ne      # state Title
examples/war/deal_state.ne       # state Deal
examples/war/play_state.ne       # state Playing (phase machine)
examples/war/victory_state.ne    # state Victory

The top-level examples/war.ne is the file the pre-commit hook and emulator harness see. It compiles to examples/war.nes without any tooling changes. The split source files all live under examples/war/ and are pulled in via include "war/<name>.ne" directives.

---

3. Hardware budget

Sprite budget per frame

All sprites use sprite sub-palette 0 (the NEScript codegen hard-wires the OAM attribute byte to 0). That gives 4 shared colours: transparent, red, white, black — enough for both red and black suits on a white card face with a black outline.

Cards are 16×24 px (2 cols × 3 rows = 6 sprites). Max on-screen simultaneously in the steady state:

Entity	Qty	Sprites	Notes
Deck A top	1	6	card back
Deck B top	1	6	card back
Face-up A	1	6	varies by round
Face-up B	1	6	varies by round
Flying card	1	6	only during anim
Cursor / UI	≤2	≤2	title selector + misc
		32	≤ 64 OAM slots ✓

8-per-scanline check. Decks are at y = 80, face-up cards at y = 128. Those two bands never overlap vertically, so the worst case is 2 cards side by side within the same band = 4 sprites per scanline.

Tile budget (max 256)

Group	Tiles	Purpose
Card frame	6	outline corners + top/bottom blank cells
Card back	4	diamond-lattice pattern, symmetric
Rank glyphs	13	A, 2-9, 10, J, Q, K (8×8 each)
Small suit (corner)	4	♠ ♥ ♦ ♣
Big suit left half	4	left half of large centre pip
Big suit right half	4	right half
Font A-Z	26	title/menu/HUD
Font 0-9	10	deck counts + HUD
Punctuation + space	~4	:, !, space, ?
Big "WAR" banner	12	2×2 block per letter
Felt-table tile	2	background fill + subtle pattern
Border / divider	4	thin framing
Cursor / arrow	2	menu selection
Total	~95	leaves ~150 tiles free

RAM budget

Structure	Bytes	Notes
deck_a: u8[52]	52	circular buffer, packed rank<<4 | suit
deck_b: u8[52]	52
pot: u8[52]	52	cards currently in play
queue cursors, counts, phase, anim timers	~20
RNG state	1
Total	~180	well under the ~1700 bytes of general RAM

---

4. Card representation & RNG

Card encoding

One byte per card, packed as (rank << 4) | suit:

• rank = 1..13 (A=1, 2=2, …, 10=10, J=11, Q=12, K=13)
• suit = 0..3 (♠=0, ♥=1, ♦=2, ♣=3)

PRNG

8-bit Galois LFSR seeded from the frame counter on title-screen exit.

Shuffle

Bounded random-swap shuffle: 200 swaps between two 6-bit random indices, retrying when either index ≥ 52. Uses only & and compare, no multiply or divide.

Deck as a queue

Each deck is a circular buffer with front / count cursors. draw bumps front, push_back writes at (front + count) % 52. Modulo is implemented with if x >= 52 { x -= 52 } to avoid the expensive % software routine.

---

5. State machine

Title → Deal → Playing → Victory → Title

Playing contains an inner phase machine driven by a u8 phase var:

Phase	Notes
P_WaitA	Human: wait for input; CPU: wait for think timer
P_FlyA	16-frame lerp of A's card from deck to play position
P_WaitB	symmetric
P_FlyB	symmetric
P_Reveal	Both cards visible; brief beat
P_Resolve	Compare, branch to P_WinA / P_WinB / P_WarBanner
P_WinA / P_WinB	Cards slide to winner deck
P_WarBanner	Flash "WAR!" banner, play WarFlash
P_WarBury	Bury 3 face-down cards from each deck
P_Check	Win-condition check, possibly transition Victory

Game modes (0/1/2 players) are captured by two bool flags a_is_cpu / b_is_cpu chosen on title exit.

---

6. Audio

Name	Channel	Shape
FlipCard	pulse 1	short descending click
CheerA	pulse 1	8-frame rising arpeggio, pitch envelope
CheerB	pulse 1	8-frame descending arpeggio, pitch envelope
WarFlash	pulse 1	16-frame pitch sweep, loud → soft → loud
ThudDown	noise	4-frame noise burst (bury animation)
TitleTheme	pulse 2	brisk 4/4 march, looping
Victory	builtin fanfare	one-shot on win

---

7. Implementation steps

The checkboxes below are updated as each step lands. A step is only marked complete after the compiler still produces a working ROM and the change visibly does what it's supposed to.

• Step 1: Skeleton — top-level file, empty included files, compiles.
• Step 2: Palette, felt background, card-back tiles, static card rendered on the table.
• Step 3: Card-face tiles (ranks, suits, big pips) + draw_card_face helper showing all 13 ranks × 4 suits.
• Step 4: Deck data structures, RNG, shuffle, init + HUD digit rendering.
• Step 5: Title state (WAR banner, 3-option menu, cursor, music, autopilot).
• Step 6: Deal state (animated deal + flip sfx).
• Step 7: Play state phase machine with card animations and sfx.
• Step 8: War tie-break (banner + bury animation + WarFlash).
• Step 9: Victory state (winner banner + fanfare + auto-return).
• Step 10: Polish pass (timing, readability, sfx/music tuning).
• Step 11: Rebuild war.nes, capture goldens, verify diff.
• Step 12: Update README.md and examples/README.md.
• Code review pass: read every file end-to-end, fix mistakes.

---

8. Design revisions

(Empty — will be updated in-flight if anything changes from the approved design.)