The previous version of hud_demo passed `score & 0x0F` and tile
index `1` (= Heart) to nt_set / nt_fill_h, but the demo had no
Heart sprite declared and tile 1 in CHR was uninitialized garbage.
The result was a screen of blue smileys with a tiny red strip in
the corner — the buffer mechanism worked, but the visual gave no
sense that anything HUD-shaped was happening.
This commit makes the HUD actually look like a HUD:
- 12 sprite declarations (Bar, Heart, Digit0..9, Ball) that the
compiler lays into CHR at known tile indices in declaration
order. Tile-index constants (`BAR_TILE`, `HEART_TILE`,
`DIGIT_BASE`) match that order so the call sites can use names
instead of magic numbers.
- bg1 palette restructured to `[red, white, yellow]` so pixel-art
characters resolve to visible colours: `#` = red (background
fill), `%` = white (heart shape), `@` = yellow (digit strokes).
- Background pre-paints row 1 with the solid `Bar` (red) tile
via a `legend { "B": 1 }` entry, giving the HUD a uniform red
canvas for individual cell writes to land on.
- Eight `nt_attr` calls at startup paint the entire top metatile
row (4 rows × 32 cols) with sub-palette 1 so the HUD chrome
reads as visually distinct from the playfield.
The result at frame 180 is unmistakably HUD-shaped: a yellow-on-
red status bar at the top of the screen above blue playfield with
a yellow ball bouncing around. Per-frame cost still scales with
what changed — `last_score` / `last_lives` shadow-compares mean
the buffer stays empty on the ~58 of 60 frames where nothing
ticks.
Tests: 758 pass. Clippy clean. 48/48 emulator goldens match.
Follow-up to 807c9c7 (the VRAM update buffer core). Adds the
realistic-HUD example the core was missing, plus a language-guide
section that explains when and how to use the three buffer
intrinsics.
**examples/hud_demo.ne**
A bouncing-ball playfield with a classic status bar across the
top:
- 5-cell lives indicator that ticks down once per second and
resets at zero, drawn via `nt_fill_h` (plus a second
`nt_fill_h` to erase the stale tail).
- Score counter at the right edge that bumps on every wall
bounce, drawn via `nt_set`.
- One-shot `nt_attr` call on the first frame flipping the
top-left metatile group to sub-palette 1 (the red HUD
palette) so the UI chrome reads as distinct from the
playfield.
The demo's point is the `last_score != score` / `last_lives !=
lives` shadow-compare pattern: on the ~58-of-60 frames where
nothing changed, the buffer stays empty and drain work is zero.
That's the whole reason the VRAM buffer exists — per-frame cost
scales with what moved, not with HUD complexity. Committed
`.nes` + pixel/audio goldens.
**docs/language-guide.md**
New "VRAM Update Buffer" section between "Hardware Intrinsics"
and "Inline Assembly". Covers:
- Why user code can't just poke `$2006` / `$2007` directly.
- The three intrinsics + their coordinate systems (cell, not
pixel).
- The HUD pattern with a ready-to-paste code snippet and a
pointer at `examples/hud_demo.ne`.
- A per-entry budget table + worked 1000-cycle drain example
against the ~2273-cycle vblank budget.
- Known limits: horizontal-only, no overflow check,
no coalescing — all already tracked under `future-work.md` §G.
**examples/README.md**
`vram_buffer_demo.ne` reframed as the minimal test-case exercise
it actually is, with a pointer at `hud_demo.ne` for the realistic
pattern. New table row for `hud_demo.ne`.
All 758 tests pass. Clippy clean. 48/48 emulator goldens match.
