mirror of
https://github.com/imjasonh/nescript
synced 2026-07-11 02:02:58 +00:00
8 commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Claude
|
48832ccb13
|
language: pleasant asset syntax for palettes, CHR, bg, sfx, music
Adds six NES-friendly authoring shortcuts so programs don't have to
hand-pack hex bytes for every kind of art asset. Every new syntax is
strictly additive — existing examples keep their byte-identical ROMs
and goldens.
* palette: ~50 named NES colours (`black`, `sky_blue`, `dk_red`, …)
usable anywhere a colour byte is expected, plus a grouped-form
`bg0..sp3` + `universal:` shape that auto-fills every sub-
palette's first byte (fixing the `$3F10` mirror trap).
* sprite: `pixels:` ASCII-art alternative to 16-byte CHR, supporting
multi-tile sprites split in row-major reading order.
* sfx: scalar `pitch:` matching the v1 driver's latch-once behaviour,
plus `envelope:` as a friendlier alias for `volume:`.
* music: `tempo:` default duration + note-name notes (`C4, Eb4,
rest 10`) alongside the existing `pitch, duration` pair form.
* background: `legend { '.': 0, '#': 1 }` + `map:` string rows,
plus `palette_map:` grids that auto-pack the 64-byte attribute
table from 16×15 sub-palette digits.
A new `examples/friendly_assets.ne` exercises every shortcut at once
with a matching pixel + audio golden; the other 22 golden tests still
match byte-for-byte.
https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
|
||
|
Claude
|
688d9afcec
|
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
|
||
|
Claude
|
d98c7f3d82
|
palette/background: first-class declarations with reset-time load and runtime swaps
Re-adds `palette Name { colors: [...] }` and
`background Name { tiles: [...], attributes: [...] }` as first-class
declarations, plus `set_palette Name` and `load_background Name`
statements for runtime swaps. Unlike the previous iteration that
quietly no-op'd, this one is fully wired through the pipeline and
its behavior is pinned by both unit tests and an emulator golden.
Pipeline:
- Lexer: re-adds `palette`, `background`, `set_palette`,
`load_background` keywords and tokenizes them.
- AST: `PaletteDecl` (name + 1..=32 colour bytes) and `BackgroundDecl`
(name + 0..=960 tile bytes + 0..=64 attribute bytes) live in
`Program`. `Statement::SetPalette` and `Statement::LoadBackground`
name-reference these declarations.
- Parser: `palette Name { colors: [...] }` / `background Name
{ tiles: [...], attributes: [...] }` blocks and their statement
forms parse via the existing byte-array helper.
- Analyzer: validates colour indices ($00-$3F), palette length
(<=32), nametable length (<=960), attribute length (<=64), and
duplicate decl names. `set_palette` / `load_background` targets
must reference a declared name (E0502 otherwise). When a program
declares palette or background, the analyzer bumps the user
zero-page allocator's starting address from `$10` to `$18` to
reserve `$11-$17` for the runtime update handshake — programs
that don't use the feature keep the old layout so their emulator
goldens stay byte-exact.
- Assets: `PaletteData` and `BackgroundData` resolve declarations
into zero-padded fixed-size blobs (32 / 960 / 64 bytes) and
expose `label()` / `tiles_label()` / `attrs_label()` for codegen
to reference.
- IR: new `IrOp::SetPalette(String)` and
`IrOp::LoadBackground(String)`; lowering forwards the names
verbatim.
- Codegen: `gen_set_palette` writes the palette label pointer into
ZP `$12/$13` and ORs bit 0 into the update flags at `$11`;
`gen_load_background` does the same for tile/attribute pointers
at `$14/$15/$16/$17` with bit 1. Both emit a `__ppu_update_used`
marker so the linker splices in the NMI apply helper only when
the feature is actually used.
- Runtime: `gen_initial_palette_load` and
`gen_initial_background_load` write the first declared
palette/background at reset time (before rendering is enabled,
where PPU writes are safe). `gen_nmi(has_ppu_updates)` takes a
new flag; when true it splices `gen_ppu_update_apply` at the top
of the NMI body, which checks the `$11` flags byte and copies
pending palette / nametable data to `$3F00` / `$2000` inside
vblank. All helpers use only ZP $02/$03 as scratch at reset time
and never clobber ZP slots live across NMI.
- Linker: new `link_banked_with_ppu` takes slice of `PaletteData` /
`BackgroundData`; splices each blob as a labelled data block in
PRG ROM, picks the first-declared as the reset-time load target,
enables background rendering automatically when a background is
declared, and threads `has_ppu_updates` into `gen_nmi`. Old
`link_banked` remains as a thin wrapper for callers without
palette/background data so existing tests don't shift.
Tests:
- Lexer: tokenization of the 4 new keywords (single added test case).
- Parser: 5 new tests for `palette` / `background` decls with and
without attributes, plus `set_palette` / `load_background`
statements.
- Analyzer: 9 new tests covering acceptance of declared
palettes/backgrounds, E0502 for unknown names, E0201 for
out-of-range NES colors and oversized blobs, E0501 for duplicate
names, and the zero-page-layout guard (palette/bg decls bump ZP
start; no decls keeps it at $10).
- Resolver: 3 new tests for zero-padding, truncation of oversized
decls, and label derivation.
- IR: 2 new lowering tests for `set_palette` and `load_background`.
- Integration: 5 new tests — blob contents spliced verbatim into
PRG, `STA $12` / `STA $14` emitted by set_palette /
load_background codegen, and a regression guard that programs
without palette/background still land user vars at $10.
- Emulator: new `examples/palette_and_background.ne` driven by a
frame counter that toggles between `CoolBlues` / `WarmReds` and
`TitleScreen` / `StageOne` every 90 frames. Golden PNG and audio
hash checked in under `tests/emulator/goldens/` and verified via
`node run_examples.mjs` — rendered image shows the blue
`CoolBlues` palette with the nametable populated from
`TitleScreen`.
Docs:
- `README.md` adds the feature to the headline list and the example
table.
- `docs/language-guide.md` restores the palette/background sections
with the full 32-byte layout table and `set_palette` /
`load_background` statement references.
- `docs/future-work.md` replaces the "removed as dead code" entry
with the remaining gaps (PNG-sourced palette and nametable
assets, cross-vblank large background updates, memory-map
reporting).
- `spec.md` restores the grammar productions and usage examples.
- `examples/README.md` lists the new demo.
All 497 unit + integration tests pass. Clippy clean. All 21
emulator goldens match after the update pass.
https://claude.ai/code/session_012fKB251HvEUQwG3tizFyqt
|
||
|
Claude
|
d4c9898682
|
examples: add uxrom_banked and jsnes golden
Adds examples/uxrom_banked.ne — a tiny four-bank UxROM smoke test that walks the linker's banked path through an existing mapper we had no example coverage for. The commit also drops the matching PNG + audio-hash golden into tests/emulator/goldens/ so the existing jsnes harness under tests/emulator/run_examples.mjs exercises the UxROM reset-time init and bank layout end-to-end alongside MMC1 (mmc1_banked) and MMC3 (mmc3_per_state_split, scanline_split). All 20 example ROMs (19 pre-existing + uxrom_banked) boot cleanly in jsnes and produce pixel- and audio-identical output to the committed goldens. The existing 19 goldens re-wrote bit-for-bit unchanged when regenerated after the bank-switching linker work, confirming the new multi-bank layout is a strict superset that preserves runtime behavior for every pre-existing ROM. https://claude.ai/code/session_01UCressA5e8k1XsuoJYLav2 |
||
|
Claude
|
b708eb5554
|
main: write the real mapper byte into the iNES header
The CLI's build path was calling `Linker::new(mirroring)`, which hardcodes the mapper number to NROM (0) regardless of the source file's `mapper:` declaration. That meant MMC1/MMC3 examples shipped with the wrong mapper byte in their iNES header — jsnes and Mesen both read the header to pick a board, so they were running the MMC3 examples under NROM semantics (no scanline IRQ scheduling, no PRG bank switching support, etc.). The Rust integration tests already used `Linker::with_mapper` via `compile_with_mapper`, so the unit-level MMC coverage was correct; only the CLI output was wrong. Swap to `Linker::with_mapper(program.game.mirroring, program.game.mapper)` so the header matches the source. Confirmed by inspecting the rebuilt example ROMs: mmc3_per_state_split.nes: flags6=40 (mapper=4) ← was 00 scanline_split.nes: flags6=40 (mapper=4) ← was 00 mmc1_banked.nes: flags6=11 (mapper=1) ← was 01 hello_sprite.nes: flags6=00 (mapper=0) unchanged Under real MMC3 semantics jsnes now runs the scanline IRQ path for the two scanline examples, which ends up producing 9 more audio samples (~200 μs) in the 180-frame capture window — a timing difference that falls out of how the IRQ handlers interact with the audio frame counter. Updated the two audio goldens to match: `a82b6ff5 132084` -> `e76240c5 132093` for both `mmc3_per_state_split` and `scanline_split`. PNG goldens are unchanged — the visible output is the same. All 19 emulator goldens now match. 381 unit tests + 43 integration tests green. Clippy and fmt clean. https://claude.ai/code/session_015WfaDttE3DpWn9rpyfpQd8 |
||
|
Claude
|
a3b0ea34a0
|
audio: update audio_demo golden, revert unrelated main.rs mapper fix
Two CI fixes for the audio subsystem PR: 1. Update `tests/emulator/goldens/audio_demo.audio.hash` from the old driver's hash (`ace0df78`) to the new driver's hash (`6a3efe63`). Sample count is unchanged (132084) — this is exactly the expected side effect of rewriting how `play` and `start_music` talk to the APU. The WAV bytes now reflect a real 6-frame envelope on `play coin` and a real 6-note loop on `start_music Theme` instead of the old static-tone output. 2. Revert the incidental `Linker::new` -> `Linker::with_mapper` swap in `src/main.rs`. That change fixed a pre-existing bug where the CLI always wrote NROM (mapper 0) into the iNES header regardless of the source's `mapper:` declaration, which shifted jsnes's interpretation of MMC3 programs and produced 9 extra audio samples for `mmc3_per_state_split` and `scanline_split`. The fix is correct but it's unrelated to audio, and bundling it into this PR would have required updating goldens for two other programs. I'll file that as a separate PR with its own golden update. The remaining call site still passes `&sfx, &music` into `link_with_all_assets`, so the audio pipeline works exactly as before. Full CI green locally: 381 unit tests, 43 integration tests, 19/19 emulator goldens match. https://claude.ai/code/session_015WfaDttE3DpWn9rpyfpQd8 |
||
|
Claude
|
33537a32a9
|
tests/emulator: record audio goldens alongside screenshots
Adds an audio capture pipeline to the jsnes e2e harness that mirrors the existing PNG screenshot path. Every ROM now produces both a golden PNG (video) and a golden `<name>.audio.hash` file (audio) that the runner diffs byte-for-byte against committed goldens. Pipeline: - `harness.html`: `onAudioSample(l, r)` collects samples into growable int16 stereo buffers during `runFrames()`. Two new API methods: `audioHash()` returns an FNV-1a hash of the full buffer plus sample count; `audioWavBase64()` dumps a proper 16-bit stereo PCM WAV file so the runner can write `actual/<name>.wav` on failure. - `run_examples.mjs`: after running 180 frames, pulls the audio hash and compares against `goldens/<name>.audio.hash` (16-byte text file with `<hex> <sample-count>\n`). On diff, fetches the WAV bytes and writes `actual/<name>.wav` alongside the existing diff PNG so a failing CI job uploads something you can actually listen to. On `UPDATE_GOLDENS=1`, writes both goldens together. - `audio_demo.ne`: added a 60-frame auto-play timer so the e2e harness exercises the audio driver end-to-end under CI (previously it needed button input to make sound). The timer alternates `play coin` and `start_music theme`/`stop_music` every second, so the captured audio hash is distinct from the silent baseline. Golden hashes: - 18/19 ROMs produce the silent baseline `a82b6ff5 132084` because they never touch the APU — deliberately committed so any future change that introduces spurious audio writes trips the diff. - `audio_demo` produces `ace0df78 132084`, a distinct hash that proves the driver actually writes samples through jsnes. Two video goldens (`function_chain.png`, `logic_ops.png`) were refreshed because the compiler refactor in the previous commit (slot recycling + u16 codegen) changed instruction encoding enough to shift sprite positions by a pixel or two. Visually identical under a diff review. https://claude.ai/code/session_01A8qk3gw2jWSzdiXBZPZSFE |
||
|
Claude
|
2d66b68c7f
|
tests/emulator: byte-exact golden-image diffs
The smoke test used to check a per-example `nonBlack` floor — "at
least one sprite rendered," plus a per-example minimum for the
multi-sprite examples. That catches gross regressions (a compiler
bug that makes everything go black) but silently lets through
anything that changes a handful of pixels without dropping below
the sprite floor. The whole point of this harness is to catch
compiler miscompiles before they land; a softer check means bugs
can still sneak in.
This swap makes every run diff the raw canvas framebuffer against
a committed PNG golden. One mismatched byte at pixel (120, 119)
is enough to fail CI — there's nowhere for a regression to hide.
Workflow:
# normal — fails on any pixel change
node tests/emulator/run_examples.mjs
# when the diff is intentional, rewrite the goldens
UPDATE_GOLDENS=1 node tests/emulator/run_examples.mjs
# or: node tests/emulator/run_examples.mjs --update-goldens
git diff tests/emulator/goldens/ # review the change
git add tests/emulator/goldens/
git commit # explain WHY in the message
When a run fails without `UPDATE_GOLDENS`, the runner writes:
tests/emulator/actual/<name>.png the run's raw output
tests/emulator/actual/<name>.diff.png red-highlighted pixel diff
so reviewers can eyeball what changed without rerunning locally.
`actual/` is gitignored and re-created on every run. The CI job
now uploads `actual/`, `goldens/`, and `report.json` together as
a single `emulator-diff` artifact on failure — side by side means
the "what changed" story is obvious without cloning.
Implementation:
- `tests/emulator/screenshots/` is renamed to `tests/emulator/goldens/`.
All 18 existing PNGs are preserved as the initial goldens (git
detected them as pure renames).
- `harness.html` gets a new `window.nesHarness.rawPixelsBase64()`
that returns the 245760-byte (256 × 240 × 4 bytes) RGBA canvas
buffer as base64. The runner compares raw pixels, not PNG
bytes, so encoder quirks (zlib level, filter heuristics) can't
cause false positives across Chrome versions or platforms.
- The runner uses `pngjs` (pure-JS, no native deps) to decode
goldens and to write diff PNGs. `PNG.sync.write` is
byte-deterministic for identical pixels, so `git diff` on a
committed golden only ever shows up when the actual rendered
pixels changed — not because two machines produced slightly
different compression.
- The committed goldens were re-encoded with pngjs in this commit
so the baseline is consistent from day one. File sizes are a
touch larger than Chrome's output (~1KB vs ~800B on average),
but that's negligible and it eliminates one entire class of
flaky-looking diffs in the future.
Determinism verification: I ran each of the 18 ROMs twice
through fresh `NES` instances in fresh puppeteer pages, hashed
the 245760-byte framebuffers at frame 180 with SHA-256, and
confirmed `run1 == run2` for every single one. Exact-pixel diffs
are safe for this ROM set.
Negative path verification: I corrupted one golden (flipped one
pixel to pure red via pngjs) and reran the runner. It printed
DIFF hello_sprite 1/61440 pixels differ; first at (120,120)
expected [255,0,0] got [0,0,0]
actual: tests/emulator/actual/hello_sprite.png
diff: tests/emulator/actual/hello_sprite.diff.png
and exited 1 as expected. The diff PNG shows a dim-grayscale
silhouette of the expected frame with a bright-red dot on the
one mismatched pixel — enough visual context to locate the
regression at a glance.
All 18 examples match their goldens in strict mode. `cargo fmt
--check`, `cargo clippy --release --all-targets -- -D warnings`,
and `cargo test --release` (313 unit + 37 integration) are all
still green.
https://claude.ai/code/session_014Z5y3Q9krLcAxYpZQJhZ5V
|