imjasonh/nescript
1
0
Fork 0
mirror of https://github.com/imjasonh/nescript synced 2026-07-10 01:37:45 +00:00
Code Activity
nescript/examples/platformer.ne

942 lines
34 KiB
Text
Raw Normal View History

platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// Platformer — an end-to-end side-scrolling demo game that
// exercises nearly every subsystem of the NEScript compiler in
// one program: custom CHR tiles, a full 32×30 background nametable
// with per-region attribute palettes, a multi-tile metasprite
// player with gravity/jump physics, wrap-around horizontal
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// scrolling, moving enemies with stomp-or-die contact logic, a
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
// sprite-based status bar at the top of the viewport (coin icon +
// two-digit score on the left, heart icon + lives counter on the
// right) that rides along through the death screen, cross-state
// life tracking that cycles GameOver → Playing while hearts last
// and bounces back to Title when the last heart is spent,
// collectible coins, user-declared SFX envelopes, a user-declared
// music track, and a title → playing → game-over state machine
// driven by both controller input and an autopilot so the jsnes
// golden harness (which runs headless with no simulated buttons)
// still captures the full gameplay loop inside the first ~6
// seconds of demo.
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
//
// Controls (when played by a human):
// D-pad left/right — walk
// A — jump
// Start — on title screen: begin; after game over: retry
//
// Build: cargo run --release -- build examples/platformer.ne
// Output: examples/platformer.nes
//
// All CHR tile art, nametable bytes, and attribute bytes in this
// file are generated by `cargo run --bin gen_platformer_tiles`.
// Regenerate them from `scripts/gen_platformer_tiles.rs` if you
// want to tweak the level.
game "Platformer" {
mapper: NROM
// Horizontal arrangement means nametable 1 mirrors nametable 0
// horizontally, so our single loaded nametable tiles endlessly
// as the camera scrolls right.
mirroring: horizontal
}
// ── Palette ──────────────────────────────────────────────────
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
// Authored in grouped form: one shared `universal:` colour fills
// every sub-palette's index-0 slot automatically. That single
// declaration is enough to dodge the notorious `$3F10/$3F14/$3F18/
// $3F1C` PPU mirror trap — when a program writes 8 distinct
// "index 0" bytes sequentially, the last write clobbers the
// shared background colour and the screen turns the wrong colour
// (or all-black). Using one shared universal everywhere is what
// every shipped NES game does; the parser handles it for us.
//
// `0x22` is the lavender-blue NES master palette slot Super Mario
// Bros uses for its iconic sky. The colour names map to the
// curated set documented in `docs/language-guide.md`.
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
palette Main {
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
universal: 0x22 // sky blue (NES $22)
// Background sub-palettes
bg0: [white, gray, black] // sky / clouds
bg1: [red, orange, dk_red] // bricks, Q-blocks
bg2: [bright_green, dk_orange, brown] // grass, hills, bushes, dirt
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
bg3: [red, orange, white] // HUD chrome (matches sp0)
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
// Sprite sub-palette 0 — every `draw` uses this one slot
// because the OAM attribute byte is always 0 in v0.1.
// 1 = red cap, 2 = orange skin, 3 = white highlight.
sp0: [red, orange, white]
sp1: [brown, dk_orange, orange] // reserved
sp2: [neon_green, bright_green, white] // reserved
sp3: [yellow, olive, cream] // reserved
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
}
// ── Tileset ──────────────────────────────────────────────────
// One big sprite declaration holds every custom CHR tile used by
// both sprites and the background nametable. `draw Tileset ...
// frame: N` overrides the OAM tile-index byte with `N`, so the
// same declaration drives the player, enemies, coins, and every
// background tile after tile 0. Tile 0 is reserved by the linker
// for the built-in smiley — the background leaves it unreferenced.
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
//
// All 15 tiles are authored as 8×8 ASCII pixel art and stacked
// vertically (1 tile wide × 15 tiles tall) so the parser splits
// them into consecutive CHR tile indices in reading order. The
// art uses the `.abc` vocabulary (`. = 0`, `a = 1`, `b = 2`,
// `c = 3`); regenerate with `cargo run --bin gen_platformer_tiles`.
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
sprite Tileset {
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
pixels: [
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 1: Player head L
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"..aaaaaa",
".aaaaaaa",
".aaabbbb",
".aabbbbc",
"aabbcccc",
"aabbccbc",
"aabbbbbb",
"aabbbbbb",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 2: Player head R
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"aaaaaa..",
"aaaaaaa.",
"bbbbaaa.",
"cbbbbbaa",
"cccccbbb",
"bcbbccbb",
"bbbbbbbb",
"bbbbbbbb",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 3: Player body L
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
".aaaaaaa",
"aaacaaaa",
"aaaccaaa",
"aaaaaaaa",
".bbbbbbb",
".bbbbbbb",
".bb..bbb",
"aaa..bbb",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 4: Player body R
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"aaaaaaa.",
"aaaacaaa",
"aaaccaaa",
"aaaaaaaa",
"bbbbbbb.",
"bbbbbbb.",
"bbb..bb.",
"bbb..aaa",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 5: Enemy
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"..aaaa..",
".aaaaaa.",
".aacbaa.",
"aacccaaa",
"abbccbba",
".aaaaaa.",
"a.aaaa.a",
"a..aa..a",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 6: Coin
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"...bb...",
"..bbbb..",
".bbccbb.",
".bcbbcb.",
".bcbbcb.",
".bbccbb.",
"..bbbb..",
"...bb...",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 7: Grass top
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"aaaaaaaa",
"a.aaa.aa",
"aaaaaaaa",
"accacaca",
"ccccaccc",
"cccccccc",
"cbccccbc",
"cccccccc",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 8: Dirt
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"cccccccc",
"cbccccbc",
"cccccccc",
"ccccbccc",
"cccccccc",
"cbccccbc",
"ccccbccc",
"cccccccc",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 9: Brick
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"cccccccc",
"caaaaaca",
"caaaaaca",
"caaaaaca",
"cccccccc",
"aaacaaaa",
"aaacaaaa",
"aaacaaaa",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 10: Cloud L
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"........",
"...aaa..",
"..aaaaa.",
".aaaaaaa",
".aaaaaaa",
".bbaaaaa",
"..bbbbba",
".....bbb",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 11: Cloud R
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"........",
".aaa....",
"aaaaa...",
"aaaaaaa.",
"aaaaaaa.",
"aaaaabb.",
"abbbbb..",
"bbb.....",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 12: Hill
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"........",
"....aa..",
"...aaaa.",
"..aaaaaa",
"..abaaaa",
".abbabaa",
".aaababa",
"aabbabba",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 13: Bush
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"........",
"...aa...",
"..aaaa..",
".aaaaac.",
"aaaaaaca",
"aaaaacca",
"aaaaacca",
"acacacac",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 14: Q Block
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"cccccccc",
"caaaaaac",
"cabbbbac",
"cabccbac",
"cabcbbac",
"cabbbbac",
"caaaaaac",
"cccccccc",
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// tile 15: Sky (blank)
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"........",
"........",
"........",
"........",
"........",
"........",
"........",
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
"........",
// tile 16: Digit 0
"........",
"..cccc..",
"..c..c..",
"..c..c..",
"..c..c..",
"..c..c..",
"..cccc..",
"........",
// tile 17: Digit 1
"........",
"...cc...",
"..ccc...",
"...cc...",
"...cc...",
"...cc...",
"..cccc..",
"........",
// tile 18: Digit 2
"........",
"..cccc..",
".....c..",
"....cc..",
"...cc...",
"..cc....",
"..cccc..",
"........",
// tile 19: Digit 3
"........",
"..cccc..",
".....c..",
"...ccc..",
".....c..",
".....c..",
"..cccc..",
"........",
// tile 20: Digit 4
"........",
"..c..c..",
"..c..c..",
"..cccc..",
".....c..",
".....c..",
".....c..",
"........",
// tile 21: Digit 5
"........",
"..cccc..",
"..c.....",
"..cccc..",
".....c..",
"..c..c..",
"..cccc..",
"........",
// tile 22: Digit 6
"........",
"..cccc..",
"..c.....",
"..cccc..",
"..c..c..",
"..c..c..",
"..cccc..",
"........",
// tile 23: Digit 7
"........",
"..cccc..",
".....c..",
"....c...",
"...c....",
"..c.....",
"..c.....",
"........",
// tile 24: Digit 8
"........",
"..cccc..",
"..c..c..",
"..cccc..",
"..c..c..",
"..c..c..",
"..cccc..",
"........",
// tile 25: Digit 9
"........",
"..cccc..",
"..c..c..",
"..cccc..",
".....c..",
".....c..",
"..cccc..",
"........",
// tile 26: Heart
"........",
".aa..aa.",
"aaaaaaaa",
"aaaaaaaa",
".aaaaaa.",
"..aaaa..",
"...aa...",
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
"........",
// tile 27: Sprite 0 anchor (single opaque pixel at row 7,
// col 3 — the sprite-0 hit fires on the last
// HUD scanline so the scroll split lands
// cleanly on the playfield below)
"........",
"........",
"........",
"........",
"........",
"........",
"........",
"...c...."
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
]
}
// Tile index constants — must match `scripts/gen_platformer_tiles.rs`.
const TILE_PLAYER_HL: u8 = 1
const TILE_PLAYER_HR: u8 = 2
const TILE_PLAYER_BL: u8 = 3
const TILE_PLAYER_BR: u8 = 4
const TILE_ENEMY: u8 = 5
const TILE_COIN: u8 = 6
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// HUD glyphs. The digit tiles are contiguous so
// `TILE_DIGIT_0 + n` picks digit `n`. Digit + heart tiles are
// shared between sprite rendering (v0.1 sprites) and background
// rendering (the HUD row's `nt_set`s) via the matching `bg3`
// sub-palette.
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
const TILE_DIGIT_0: u8 = 16
const TILE_HEART: u8 = 26
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// OAM slot-0 anchor — a 7-scanline-tall transparent sprite with
// one opaque pixel at row 7. Aligns with the coin tile's bottom
// row so sprite-0 hit fires at scanline 15, keeping the scroll
// split exactly at the HUD-row boundary.
const TILE_SPRITE0_ANCHOR: u8 = 27
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// ── Background ──────────────────────────────────────────────
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
// The 32×30 nametable is authored as ASCII art with a `legend`
// block naming each tile by a single character. Horizontal
// scrolling pans this single nametable via `scroll()` so it only
// needs to look interesting at any X offset.
//
// `palette_map:` is the friendlier alternative to a 64-byte
// hand-packed attribute table: 16×15 metatile entries, one
// digit per 16×16 metatile, and the parser packs the 2-bit
// `(br<<6)|(bl<<4)|(tr<<2)|tl` quadrants automatically. The
// three palette regions are sky (`0`), brick row (`1`), and
// ground (`2`).
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
background Level {
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
legend {
".": 15 // sky (blank)
"<": 10 // cloud left half
">": 11 // cloud right half
"#": 9 // brick
"Q": 14 // question block
"^": 12 // hill silhouette
"*": 13 // bush
"=": 7 // grass top
"%": 8 // dirt
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// HUD chrome glyphs — row 0 only. Mapped to the sprite
// CHR tiles we already declared so sprites and background
// render identical glyphs under the matching bg3 palette.
"o": 6 // coin icon (HUD score marker)
"h": 26 // heart icon (HUD lives marker)
"0": 16 // digit 0 (initial score tens/ones + fallback)
"3": 19 // digit 3 (initial lives)
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
}
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// Row 1 carries the status bar: coin + two score digits on the
// left, heart + single lives digit on the right. Row 0 stays
// sky because the jsnes golden harness (and many emulators)
// mask out the top 8 scanlines as overscan — anything painted
// there would never show in the committed PNG. Sprite 0
// (painted over column 2's coin tile every frame) overlaps the
// `o` glyph's opaque pixels so the sprite-0 hit flag fires on
// a scanline inside the HUD row; `sprite_0_split(camera_x, 0)`
// in `on frame` picks up that hit and swaps the horizontal
// scroll from 0 to `camera_x` for the rest of the frame,
// pinning the HUD while the playfield scrolls underneath. The
// digits and heart glyph sit at fixed columns so shadow-compare
// `nt_set` writes can tick the score / lives readouts without
// repainting the whole row.
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
map: [
"................................",
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
"..o.00..................h.3.....",
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"................................",
"................................",
"................................",
"....<>..............<>..........",
"............<>..................",
"................................",
"................................",
"................................",
"................................",
"................................",
"................................",
"................................",
"................................",
"......##Q#........###...........",
"................................",
"................................",
"................................",
"................................",
"..^^^.................^^^^......",
"..........***..............**...",
"================================",
"%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%#%",
"%%%%%#%%%%%%%%%%%%#%%%%%%%%%%%%%",
"%%%%%%%%%%%#%%%%%%%%%%%%#%%%%%%%",
"%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%",
"%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%",
"%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%",
"%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%"
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
]
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
palette_map: [
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
"3333333333333333", // metatile row 0 (NT rows 0-1)
// → bg3 (HUD chrome: red / orange / white)
"0000000000000000", // metatile rows 1-5 → sky sub-palette
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
"0000000000000000",
"0000000000000000",
"0000000000000000",
"0000000000000000",
"1111111111111111", // metatile rows 6-7 → brick sub-palette
"1111111111111111",
"0000000000000000", // metatile rows 8-9 → sky again
"0000000000000000",
"2222222222222222", // metatile rows 10-15 → ground sub-palette
"2222222222222222", // (rows 15 sits off-screen but the PPU
"2222222222222222", // still reads its attribute byte, so
"2222222222222222", // we emit it explicitly to match the
"2222222222222222", // hand-packed attribute table the
"2222222222222222" // old form was using.)
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
]
}
// ── Audio ────────────────────────────────────────────────────
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
//
// SFX: scalar `pitch:` matches the v1 driver's latch-once
// behaviour — pulse 1's period is sampled exactly once when the
// effect triggers and never updated, so a single byte is the
// natural form for the current pipeline. `envelope:` is the
// friendlier alias for `volume:`.
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
// Custom boingy jump sound — fixed-pitch arc on pulse 1.
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
sfx Boing {
duty: 2
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
pitch: 0x30
envelope: [12, 11, 10, 9, 7, 5, 2]
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
}
// Custom coin ding — short rising blip.
sfx Ding {
duty: 2
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
pitch: 0x20
envelope: [14, 12, 8, 3]
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
}
// Custom looping underworld theme — playful four-bar loop on
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
// pulse 2 that plays while the player is alive. Note names
// (C4 / E4 / etc.) plus a default `tempo:` so each note only
// has to spell its frame count when it deviates from the beat.
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
music Theme {
duty: 2
volume: 9
repeat: true
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
tempo: 10
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
notes: [
examples: adopt the friendly asset syntax Rewrites every example with non-trivial asset declarations to use the pleasant QoL syntax introduced in the previous commit. Every example still compiles to a byte-identical ROM (verified by a temp-path diff before committing), so the committed `.nes` files and the 23 emulator goldens are unchanged. * platformer.ne — the centerpiece end-to-end demo: - `palette Main` goes to grouped form with a shared `universal: 0x22` (sky blue), one shared colour per sub-palette, and named NES colours throughout; the long-standing `$3F10` mirror-trap warning is now handled by the parser and the manual pitfall comment is gone. - `sprite Tileset` is 15 tiles of ASCII pixel art instead of 240 bytes of inline hex. - `background Level` uses a `legend { '.': 15, '#': 9, ... }` block plus `map:` strings for the 32×30 nametable, and `palette_map:` rows for the attribute table. The map reads top-down like the rendered screen. - SFX latch-once `pitch: 0x30` scalars + `envelope:` alias. - `music Theme` uses note names + `tempo: 10` default. * audio_demo.ne — scalar sfx pitches, `envelope:` alias, and a note-name `C4, E4, G4, ...` music track. * palette_and_background.ne — grouped CoolBlues / WarmReds palettes with `universal: black` + named colours, plus `legend` + `map:` tilemaps for the two backgrounds. * sprites_and_palettes.ne — Arrow and Heart sprites rewritten as `pixels:` ASCII art. Along the way, two small parser extensions support the rewrites: - `parse_pixel_art` now accepts `a/b/c` as aliases for `#/%/@`, matching the vocabulary every NES editor (and our own gen_platformer_tiles.rs generator) uses. - `palette_map_to_attrs` allows up to 16 metatile rows (the full attribute-table coverage, including the off-screen bottom half) and auto-replicates row 14 → row 15 when only 15 rows are supplied so the visible bottom of the screen gets consistent sub-palette assignments by default. The old 15-row cap couldn't match a hand-packed `0xAA` attribute table for the last row; the platformer required this to stay byte-identical. `scripts/gen_platformer_tiles.rs` is updated to emit the new syntax directly (pixel-art `pixels:` block + `legend`/`map:`/ `palette_map:` for the background), so regenerating the platformer tiles stays a one-liner. 474 lib tests + 64 integration tests pass (3 new parser tests for `palette_map:` 15/16/17 rows and the `abc` alias). All 23 emulator goldens still match pixel- and sample-for-sample. https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
2026-04-13 18:04:21 +00:00
C4, E4, G4, C5, G4, E4,
D4 15,
rest 5,
B3, E4, G4,
C5 20,
rest 10
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
]
}
// ── Gameplay constants ──────────────────────────────────────
const PLAYER_SCREEN_X: u8 = 80 // fixed camera-relative X
const GROUND_Y: u8 = 160 // feet land here (y of head)
const JUMP_RISE: u8 = 12 // upward frames after take-off
const JUMP_PX: u8 = 3 // px moved each rise frame
const GRAVITY_CAP: u8 = 4 // terminal fall speed
const ENEMY_Y: u8 = 168 // enemies walk on the grass
const COIN_Y: u8 = 144 // coins float a bit above
// World-space X positions of the moving entities. Wrap-around
// arithmetic (u8) makes the level feel like an endless loop.
const ENEMY1_WORLD_X: u8 = 100
const ENEMY2_WORLD_X: u8 = 200
const COIN1_WORLD_X: u8 = 50
const COIN2_WORLD_X: u8 = 150
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// How many auto-jumps the autopilot will pre-queue per life. Two
// is exactly enough to stomp enemy 1 and enemy 2 once each; after
// that the autopilot stops assisting so the headless harness gets
// to see the player walk into the next enemy, die, and retry.
const AUTOPILOT_JUMPS: u8 = 2
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// ── Game state ──────────────────────────────────────────────
examples: move state-scoped globals to state-local in coin_cavern + platformer Both examples declared their gameplay variables at the top level even though every read and write happened inside one specific state. That pattern hid the overlay feature from new users and kept the state-local code path from being exercised outside the dedicated `state_machine.ne` demo (which is how the "state-locals silently drop their writes" bug survived so long). `coin_cavern.ne`: the five Playing-only physics/position/inventory vars (`player_x`, `player_y`, `player_vy`, `on_ground`, `coins_left`) move onto Playing's state block. `score` stays global because GameOver-era code could reasonably grow to read it. The `on_enter` body loses its redundant resets — the declared initializers on the state-locals re-run on every entry, so retrying after `transition Title` comes back to a fresh state. `platformer.ne`: player physics, camera, liveness, animation phase, and the autopilot budget (`player_y`, `on_ground`, `rise_count`, `fall_vy`, `camera_x`, `anim_tick`, `alive`, `auto_jumps`) all move onto Playing. `frame_tick` and `stomp_count` stay global — Title reads the former to auto-advance, GameOver reads the latter to tally coins on the death screen. The analyzer now overlays Title's `blink`, Playing's eight physics vars, and GameOver's `linger` starting at the same ZP byte (`$1A`), so the three scenes share a 9-byte window instead of each claiming their own slots. Byte-level ROM bytes for both examples shift because variable addresses moved. Video goldens stay pixel-identical (the harness doesn't see Playing in coin_cavern, and the pre-transition Title→Playing timing in platformer is preserved); the platformer audio hash needed one more refresh because the now-slightly-shorter reset prologue shifts APU writes within each frame. https://claude.ai/code/session_015kvJu3iEFLSRJoShPBfm3X
2026-04-17 11:58:02 +00:00
// `frame_tick` is shared: Title reads it to auto-advance, Playing
// reads it for animation phasing. `stomp_count` bridges
// Playing → GameOver so the death screen can tally coins. The
// rest — player physics, camera, liveness, autopilot budget —
// are only meaningful while Playing is running, so they live on
// Playing's state block and overlay with the Title / GameOver
// locals (`blink`, `linger`) at the same bytes.
// Cross-state scratch
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
var frame_tick: u8 = 0 // free-running frame counter
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
var stomp_count: u8 = 0 // successful enemy stomps this life
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
var lives: u8 = 3 // lives remaining; HUD heart readout
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// HUD shadow-compare cache. The initial nametable already paints
// "coin 00" / "heart 3" into row 0 with the bg3 palette, so the
// shadow values here start matching the on-screen glyphs — every
// frame where `stomp_count == last_score` skips the score repaint
// entirely, and likewise for lives. 255 would also force a
// guaranteed-initial-paint fallback on the first frame if the map
// ever drifts from these defaults; we use the real starting values
// so the harness's frame-180 golden doesn't capture a transient
// paint flicker.
var last_score: u8 = 0
var last_lives: u8 = 3
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
// ── HUD helpers ─────────────────────────────────────────────
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// Background-row HUD, pinned to the top of the viewport with a
// sprite-0 hit split instead of burning five OAM slots every
// frame. Two moving pieces:
//
// 1. The status glyphs — coin, two score digits, heart, lives
// digit — live in NT row 0 and are repainted via `nt_set`
// only when the backing state changes (`stomp_count`,
// `lives`). The initial map already contains the starting
// values so the first frame is already correct.
//
// 2. A single OAM sprite (slot 0) is drawn over the coin tile
// every frame. The PPU sets the sprite-0 hit flag when the
// sprite's opaque pixels overlap the coin tile's opaque
// pixels — guaranteed to fire on some scanline inside the
// HUD row — and a `sprite_0_split(camera_x, 0)` call picks
// up that hit to switch the horizontal scroll from 0 to
// `camera_x` for the rest of the frame. Row 0 stays pinned,
// everything below it scrolls with the camera.
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
fun draw_hud() {
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// Sprite 0 — must be the FIRST draw of the frame so it lands
// in OAM slot 0. The anchor tile has one opaque pixel at row
// 7, col 3 (a single dot), which when positioned at (16, 7)
// in OAM renders at screen (19, 15) and overlaps column 3 of
// the coin tile's bottom row in NT row 1. That last-scanline
// overlap makes the sprite-0 hit flag set at scanline 15, so
// the `sprite_0_split(camera_x, 0)` call below can write
// `$2005` before the next HBLANK and the PPU latches the new
// horizontal scroll starting at scanline 16 — exactly the
// boundary between the HUD row and the playfield. The rest
// of the anchor tile is fully transparent, so the sprite is
// functionally invisible on top of the coin.
draw Tileset at: (16, 7) frame: TILE_SPRITE0_ANCHOR
// Score tens / ones — shadow-compare so the VRAM ring only
// gets an entry when `stomp_count` actually moved. The
// comparison runs once per frame and most frames take the
// no-op path (score only ticks on a stomp).
if stomp_count != last_score {
last_score = stomp_count
nt_set(4, 1, TILE_DIGIT_0 + (stomp_count / 10))
nt_set(5, 1, TILE_DIGIT_0 + (stomp_count % 10))
}
// Lives digit — same shadow-compare. Only fires on a life
// transition (death in `GameOver.on_enter`, refill in
// `Title.on_enter`).
if lives != last_lives {
last_lives = lives
nt_set(26, 1, TILE_DIGIT_0 + lives)
}
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
}
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// ── Helper functions ────────────────────────────────────────
// Try to start a jump. Only valid when the player is on the
// ground (on_ground == 1); otherwise this is a no-op.
fun try_jump() {
if on_ground == 1 {
rise_count = JUMP_RISE
on_ground = 0
fall_vy = 0
play Boing
}
}
// Advance player physics one frame. Handles the jump-rise phase
// (upward movement while rise_count > 0) and the gravity fall
// phase (increment fall_vy each frame up to GRAVITY_CAP, clamp to
// GROUND_Y on landing).
fun step_physics() {
if rise_count > 0 {
// Clamp underflow so a too-high jump doesn't wrap into the
// bottom of the screen on an 8-bit subtraction.
if player_y >= JUMP_PX {
player_y -= JUMP_PX
} else {
player_y = 0
}
rise_count -= 1
} else {
player_y += fall_vy
if fall_vy < GRAVITY_CAP {
fall_vy += 1
}
if player_y >= GROUND_Y {
player_y = GROUND_Y
on_ground = 1
fall_vy = 0
}
}
}
// Draw the 2×2 hero metasprite at (PLAYER_SCREEN_X, player_y).
// Each `draw` statement writes a fresh OAM slot via the runtime
// cursor, so four calls produce four sprites occupying a 16×16
// block.
fun draw_player() {
draw Tileset at: (PLAYER_SCREEN_X, player_y ) frame: TILE_PLAYER_HL
draw Tileset at: (PLAYER_SCREEN_X + 8, player_y ) frame: TILE_PLAYER_HR
draw Tileset at: (PLAYER_SCREEN_X, player_y + 8) frame: TILE_PLAYER_BL
draw Tileset at: (PLAYER_SCREEN_X + 8, player_y + 8) frame: TILE_PLAYER_BR
}
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// Resolve contact with an enemy whose screen X is `e_sx`. Mutates
// the player's physics / alive flag directly and returns 1 on a
// successful stomp, 0 on no contact or a fatal hit. The caller
// checks `alive` after invocation to decide whether to keep
// running the frame.
//
// The player's 16×16 hitbox is at ([80, 96), [player_y, player_y+16)).
// Each enemy's 8×8 hitbox is at ([e_sx, e_sx+8), [168, 176)). Those
// overlap horizontally when e_sx ∈ (72, 96) and overlap vertically
// when player_y ∈ (152, 176).
//
// Outcomes:
// - No overlap → no-op
// - Overlap while rising (rise_count > 0) → graceful
// pass-through. rise_count > 0 only happens right after a
// successful stomp bounce (try_jump() clears rise_count by
// the end of the same frame) or on the stomp's own upward
// leg, which we don't want to retrigger.
// - Overlap while falling, feet near enemy head → STOMP: bounce
// up, increment `stomp_count`, play Boing
// - Any other overlap (walking, on ground) → DEATH: set
// `alive = 0` and play the builtin `hit` sfx
fun resolve_enemy_hit(e_sx: u8) -> u8 {
if e_sx > 72 {
if e_sx < 96 {
if player_y > 152 {
if player_y < 176 {
// Real contact. Stomp if falling; otherwise, if
// we're not in the post-bounce grace window,
// die.
if fall_vy > 0 {
rise_count = 6
fall_vy = 0
stomp_count += 1
play Boing
return 1
}
if rise_count == 0 {
alive = 0
play hit
}
}
}
}
}
return 0
}
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// ── States ──────────────────────────────────────────────────
state Title {
var blink: u8 = 0
on enter {
blink = 0
frame_tick = 0
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
// Fresh run — restore the full life bar so the HUD reads 3
// when Playing kicks in and the GameOver loop doesn't trap
// the game in a zero-lives state forever.
lives = 3
stomp_count = 0
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
start_music Theme
}
on frame {
frame_tick += 1
blink += 1
if blink >= 60 {
blink = 0
}
// Blink a "press start" marker at roughly 0.5 Hz. We use
// the coin tile for visual continuity with the game world.
if blink < 30 {
draw Tileset at: (120, 120) frame: TILE_COIN
}
// Auto-advance so the jsnes golden harness (which never
// presses start) still reaches Playing and captures gameplay
// at frame 180. A human player can also press Start to skip
// the wait early.
if frame_tick >= 20 {
transition Playing
}
if button.start {
transition Playing
}
}
}
state Playing {
examples: move state-scoped globals to state-local in coin_cavern + platformer Both examples declared their gameplay variables at the top level even though every read and write happened inside one specific state. That pattern hid the overlay feature from new users and kept the state-local code path from being exercised outside the dedicated `state_machine.ne` demo (which is how the "state-locals silently drop their writes" bug survived so long). `coin_cavern.ne`: the five Playing-only physics/position/inventory vars (`player_x`, `player_y`, `player_vy`, `on_ground`, `coins_left`) move onto Playing's state block. `score` stays global because GameOver-era code could reasonably grow to read it. The `on_enter` body loses its redundant resets — the declared initializers on the state-locals re-run on every entry, so retrying after `transition Title` comes back to a fresh state. `platformer.ne`: player physics, camera, liveness, animation phase, and the autopilot budget (`player_y`, `on_ground`, `rise_count`, `fall_vy`, `camera_x`, `anim_tick`, `alive`, `auto_jumps`) all move onto Playing. `frame_tick` and `stomp_count` stay global — Title reads the former to auto-advance, GameOver reads the latter to tally coins on the death screen. The analyzer now overlays Title's `blink`, Playing's eight physics vars, and GameOver's `linger` starting at the same ZP byte (`$1A`), so the three scenes share a 9-byte window instead of each claiming their own slots. Byte-level ROM bytes for both examples shift because variable addresses moved. Video goldens stay pixel-identical (the harness doesn't see Playing in coin_cavern, and the pre-transition Title→Playing timing in platformer is preserved); the platformer audio hash needed one more refresh because the now-slightly-shorter reset prologue shifts APU writes within each frame. https://claude.ai/code/session_015kvJu3iEFLSRJoShPBfm3X
2026-04-17 11:58:02 +00:00
// Physics, camera, liveness, and autopilot budget — all of
// this is Playing-only. Declaring them inside the state block
// lets the analyzer overlay them with Title.blink and
// GameOver.linger; each variable's initializer re-runs on
// entry, so the retry loop starts each life on the ground
// with a fresh autopilot budget without any manual reset.
var player_y: u8 = GROUND_Y
var on_ground: u8 = 1
var rise_count: u8 = 0
var fall_vy: u8 = 0
var camera_x: u8 = 0
var anim_tick: u8 = 0
var alive: u8 = 1
var auto_jumps: u8 = 0
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
on enter {
frame_tick = 0
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
stomp_count = 0
start_music Theme
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
}
on frame {
frame_tick += 1
anim_tick += 1
// ── Input ─────────────────────────────────────────────
// Human controls — these work even while the autopilot
// is running so you can stomp the demo at any time.
if button.a {
try_jump()
}
if button.right {
camera_x += 1 // walk forward by scrolling right
}
if button.left {
// Walk back (wraps the camera — the level is cyclic).
camera_x -= 1
}
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// Always advance camera one px per frame (baseline scroll).
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
camera_x += 1
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// ── Compute screen positions of world entities ──────
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
var e1_sx: u8 = ENEMY1_WORLD_X - camera_x
var e2_sx: u8 = ENEMY2_WORLD_X - camera_x
var c1_sx: u8 = COIN1_WORLD_X - camera_x
var c2_sx: u8 = COIN2_WORLD_X - camera_x
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// ── Proximity autopilot ─────────────────────────────
// Pre-jump when an enemy is 19 px ahead. The fall phase of
// a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's
// feet at enemy head height ~20 frames later, by which
// point the autopilot camera has scrolled the enemy under
// the player. Limited to AUTOPILOT_JUMPS hops per life so
// the third enemy encounter becomes a scripted death,
// giving the golden harness a visible game-over sequence.
if auto_jumps < AUTOPILOT_JUMPS {
if on_ground == 1 {
if e1_sx == 99 {
try_jump()
auto_jumps += 1
}
if e2_sx == 99 {
try_jump()
auto_jumps += 1
}
}
}
// ── Physics ──────────────────────────────────────────
step_physics()
// ── Coin pickups ─────────────────────────────────────
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// Coin collect: player occupies [80..96). A coin is "hit"
// when its screen X is in [72..96) (8-px tolerance on each
// side of the player's left edge).
if c1_sx >= 72 and c1_sx < 96 {
if player_y <= COIN_Y + 16 {
play Ding
}
}
if c2_sx >= 72 and c2_sx < 96 {
if player_y <= COIN_Y + 16 {
play Ding
}
}
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// ── Enemy collisions ────────────────────────────────
// Both enemies get the full stomp-or-die check; the helper
// mutates player state directly. If `alive` flips to 0
// we fall through the rest of the frame (drawing is
// guarded below) and transition to GameOver at the end.
resolve_enemy_hit(e1_sx)
resolve_enemy_hit(e2_sx)
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
// ── Drawing ──────────────────────────────────────────
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// `draw_hud()` runs FIRST so its coin sprite lands in OAM
// slot 0 — that's what makes the PPU's sprite-0 hit flag
// fire on the coin-tile overlap inside the HUD row, which
// we pick up with `sprite_0_split` at the end of the
// frame. Every other `draw` has to come after.
draw_hud()
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// Enemies and coins are always drawn so the scene stays
// coherent even on the fatal-contact frame.
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
var ey: u8 = ENEMY_Y
if (anim_tick & 16) != 0 {
ey = ENEMY_Y - 2
}
draw Tileset at: (e1_sx, ey) frame: TILE_ENEMY
draw Tileset at: (e2_sx, ENEMY_Y) frame: TILE_ENEMY
var cy: u8 = COIN_Y
if (anim_tick & 8) != 0 {
cy = COIN_Y - 1
}
draw Tileset at: (c1_sx, cy) frame: TILE_COIN
draw Tileset at: (c2_sx, COIN_Y) frame: TILE_COIN
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// Player is only drawn while alive — on the dying frame
// we show the scene without the hero on top of the enemy
// that killed them, which reads as "player got got".
if alive == 1 {
draw_player()
}
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// ── Sprite-0 scroll split ────────────────────────────
// The VRAM-drain in NMI resets `$2005` to `(0, 0)` for
// the top of each frame; `sprite_0_split` busy-waits for
// the sprite-0 hit flag (fired mid-HUD-row where OAM
// slot 0's coin sprite overlaps the NT-row-1 coin tile)
// and then latches `(camera_x, 0)` for the remainder of
// the frame. Scanlines above the hit render the HUD
// pinned; scanlines below render the playfield scrolled.
sprite_0_split(camera_x, 0)
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// Fatal contact this frame → kick the state machine over
// to GameOver on the next frame.
if alive == 0 {
transition GameOver
}
}
}
state GameOver {
var linger: u8 = 0
on enter {
linger = 0
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
// Burn a life on entry so the HUD's heart counter ticks
// down visibly each death. Guard against underflow in case
// something transitions here with lives already at zero.
if lives > 0 {
lives -= 1
}
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
stop_music
}
on frame {
linger += 1
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// Sync the HUD row first (sprite 0 + shadow-compare
// `nt_set` for the digits) so the tens/ones glyphs tick
// down when `lives` decrements in `on_enter`. No
// `sprite_0_split` call here — GameOver doesn't scroll,
// so NMI's scroll-reset keeps the whole frame at
// `(0, 0)` and the HUD row renders normally. The sprite-
// 0 hit flag fires harmlessly and stays latched until the
// next Playing frame clears it.
draw_hud()
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// "GAME OVER" marker: a row of enemy tiles across the
platformer: move HUD from sprite OAM slots to background + sprite-0 split The status bar now paints into NT row 1 (coin + score digits on the left, heart + lives digit on the right) using the `bg3` sub-palette that matches `sp0` pixel-for-pixel. A single OAM slot-0 anchor sprite sits over the coin tile; its one opaque pixel lines up with the coin's bottom row so sprite-0 hit fires at scanline 15, and a trailing `sprite_0_split(camera_x, 0)` latches the playfield scroll starting at scanline 16. NT rows 0-1 stay pinned while scanlines 16+ scroll with the camera. Score / lives updates are shadow-compared (`last_score`, `last_lives`) so the VRAM ring sees an entry only when the backing state actually changes — most frames append zero bytes. OAM footprint drops from 5 sprites per frame down to 1. Tile pipeline gains a 27th entry — a 7-transparent-row + 1-pixel anchor — so the sprite-0 hit lands on scanline 15 instead of scanline 8 (the latter would smear the HUD glyphs across the split). `gen_platformer_tiles.rs` is updated in lockstep. Ancillary changes: `bg3` retuned from `[yellow, orange, dk_orange]` to `[red, orange, white]` (matching `sp0`); `palette_map` row 0 flips from bg0 to bg3; legend gains `o`, `h`, `0`, `3` so the initial map can preload the static HUD tiles and the committed nametable already reads "coin 00 ... heart 3" on frame 0. `docs/future-work.md` loses the sprite-0 HUD follow-up section (this commit lands it). Goldens + gif refreshed.
2026-04-20 17:21:20 +00:00
// middle of the screen. The death-screen backdrop is
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
// whatever Playing last scrolled to — we don't clear it.
draw Tileset at: (96, 112) frame: TILE_ENEMY
draw Tileset at: (112, 112) frame: TILE_ENEMY
draw Tileset at: (128, 112) frame: TILE_ENEMY
draw Tileset at: (144, 112) frame: TILE_ENEMY
// Auto-retry after ~1 s so the headless harness sees the
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
// full loop. When the last life is spent, bounce back to
// the Title screen instead (Title's `on enter` refills the
// heart bar for the next run). A human can hit Start to
// skip the wait.
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
if linger >= 60 {
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
if lives == 0 {
transition Title
} else {
transition Playing
}
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
}
if button.start {
platformer: sprite-based status bar with score + lives Upgrades the platformer's "live coin count" into a proper heads-up display that stays pinned to the top of the viewport while the nametable scrolls. Left side: coin icon + two-digit stomp tally. Right side: red heart icon + single-digit lives counter. Both ride through the GameOver screen without jumping position, so the death banner reads as a continuation of the same run. Wire-up: three new cross-state bits — score now accumulates across lives, `lives` starts at 3 and decrements in `GameOver.on_enter`, and the GameOver → Playing retry bounces to Title instead when the last heart is spent (Title's `on_enter` refills both). Tile pipeline: ten decimal digits + a heart glyph added to the committed Tileset (generator source in `scripts/gen_platformer_tiles.rs` kept in sync). Digits use `c` (white) so they read against the sky; the heart uses `a` (red) to match the cap/brick palette. Division workaround: the obvious `stomp_count / 10` / `% 10` pair miscompiles near state transitions — the built ROM cycles Title → Playing → Title once per blink period with Playing surviving exactly one frame. Swapping both calls for repeated `while r >= 10 { r -= 10 }` helpers fixes it. Documented as a new entry in `docs/future-work.md` so the next person reaching for `/` or `%` knows to check there first. Goldens, docs/platformer.gif, and the top-level + examples README entries all refreshed in the same commit.
2026-04-20 13:59:14 +00:00
if lives == 0 {
transition Title
} else {
transition Playing
}
feat(platformer): add stomp-or-die enemy collisions, live HUD, GameOver state The previous platformer example drew enemies but had almost no interaction with them: only enemy 1 had a stomp check, the stomp window was unreachable under the default +1-px-per-frame-plus-a- jump-every-40-frames autopilot, contact from any other angle was a silent no-op, and the header comment promised a "title → playing → game-over state machine" that didn't actually exist. The README demo gif and the committed golden both froze that state — a level the player could walk through indefinitely with no consequence. Flesh the enemy interaction model out into something real: - `resolve_enemy_hit(e_sx)`: one helper, called symmetrically for both enemies. Computes the player/enemy hitbox overlap (horizontal in `e_sx ∈ (72, 96)`, vertical in `player_y ∈ (152, 176)`) and branches three ways — falling onto the head is a stomp bounce (`rise_count = 6`, `fall_vy = 0`, `stomp_count += 1`, `play Boing`); overlap while `rise_count > 0` is a grace pass-through so the stomp bounce itself can't retrigger contact on the same enemy; anything else (walking into the side, standing on the ground against the enemy) is fatal — `alive = 0` and `play hit`. - New `GameOver` state: draws four enemy tiles across the middle of the screen plus a coin row sized to `stomp_count`, stops the music, lingers 60 frames then auto-retries, and also honours Start for an instant retry. - Proximity-based autopilot: pre-jump when an enemy is exactly 19 px ahead (`e1_sx == 99` or `e2_sx == 99`), capped at two jumps per life by `auto_jumps < AUTOPILOT_JUMPS`. Tuning: a JUMP_RISE=12, GRAVITY_CAP=4 jump lands the player's feet at enemy-head height exactly 21 frames after lift-off, by which point the autopilot camera has scrolled the enemy under the player. The first jump fires on Playing frame 1 and stomps enemy 1 on frame 22; the second fires on Playing frame 101 and stomps enemy 2 on frame 122. After that the autopilot is exhausted and the third enemy encounter (camera wraps back past enemy 1) is fatal — the golden harness now sees the full stomp, stomp, die, retry, stomp loop instead of a frozen walk. - Live HUD: up to four coin sprites in the top-left, one per stomp, rendered both during `Playing` and on the `GameOver` screen so the score is visible in the death frame. `Playing`'s player draw is now guarded by `if alive == 1` so the hero disappears on the fatal-contact frame and the enemy that killed them is visible underneath. Verified with a per-frame ZP trace through the patched puppeteer + jsnes harness: first stomp at emu frame 44 (camera_x=22), second at emu frame 144 (camera_x=122), death at emu frame 283 (camera_x=5 after a 256-px wrap), `Playing` restart at emu frame 343, third stomp at emu frame 365. All 22 emulator goldens still match after the update, and `docs/platformer.gif` regenerated from the new ROM now shows two clean stomps, a clean side-collision death, the GameOver screen, and the retry cycle all inside the 6-second demo window. Golden updates: - `tests/emulator/goldens/platformer.png` — the frame-180 capture now shows the hero walking forward with a two-coin HUD after both autopilot stomps (previously: a frozen bouncing hero). - `tests/emulator/goldens/platformer.audio.hash` — the track now includes two `Boing` stomp bounces, which shifts the hash. - `examples/platformer.nes` — rebuilt from the rewritten source. Also updates the platformer rows in `README.md` and `examples/README.md` to match the new gameplay. https://claude.ai/code/session_013Bi4H4YQ5or5HtMB4doUFi
2026-04-13 20:19:28 +00:00
}
platformer: end-to-end side-scroller demo + three runtime bug fixes Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A
2026-04-13 13:04:26 +00:00
}
}
start Title
Copy permalink