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

audio: complete the subsystem — asset pipeline, user decls, tracker-style driver

Browse source 
The audio subsystem was a sketch: `play name` / `start_music name` /
`stop_music` parsed, lowered, and emitted a few hardcoded register
writes from a builtin name table. No user-declared effects, no
per-frame envelope, no note streams, no real engine.

This flesh-out brings audio up to the quality bar of the rest of
the compiler (sprites, palettes, bank switching, scanline IRQ,
etc.) with a full data-driven pipeline:

## Asset pipeline (new `src/assets/audio.rs`)

- `sfx Name { duty, pitch, volume }` blocks compile into per-frame
  pulse-1 envelopes. Pitch/volume arrays must match in length; each
  entry is one NMI's worth of `$4000` data.
- `music Name { duty, volume, repeat, notes }` blocks compile into
  flat `(pitch, duration)` streams for pulse 2. Pitch 0 is a rest,
  1-60 indexes a builtin period table covering C1-B5.
- `resolve_sfx` / `resolve_music` walk the program for `play` /
  `start_music` references and append builtin fallbacks for any
  name that isn't user-declared — so `play coin` still works
  without a `sfx Coin { ... }` block.
- Builtin effects (coin, jump, hit, click, cancel, shoot, step)
  and tracks (theme, battle, victory, gameover) synthesize through
  the same compile path as user decls — one data model, one driver.

## Runtime engine (`src/runtime/mod.rs`)

- `gen_audio_tick()` walks both channels every NMI: reads one
  envelope byte through `(ZP_SFX_PTR),Y` -> writes `$4000`,
  advances ptr, mutes on zero sentinel. Music decrements the note
  counter, advances to the next `(pitch, dur)` pair on zero, looks
  up the period through `(__period_table),Y`, loops on `0xFF 0xFF`.
- `gen_period_table()` emits a 60-entry equal-tempered table
  (A4 = 440 Hz, NTSC 1.789773 MHz CPU clock) with length-counter
  load bits pre-baked into each high byte.
- `gen_data_block()` emits a label + raw-bytes pseudo pair so
  user sfx/music data can be spliced into PRG with regular labels
  that the two-pass assembler resolves.
- New ZP layout: `$05/$06` music loop base, `$07` music state
  (duty/volume/loop/active), `$0C-$0F` sfx and music pointers.

## IR codegen (`src/codegen/ir_codegen.rs`)

- `with_audio(sfx, music)` registers compile-time trigger constants
  per blob name.
- `gen_play_sfx` emits: write period to `$4002`/`$4003`, load
  envelope pointer into `ZP_SFX_PTR` via SymbolLo/SymbolHi of
  `__sfx_<name>`, mark the sfx counter active.
- `gen_start_music` stamps the header byte into `ZP_MUSIC_STATE`
  with the active bit OR'd in, seeds both ptr and loop base from
  `__music_<name>`, primes the duration counter.
- `gen_stop_music` mutes pulse 2 and clears state.

## Linker (`src/linker/mod.rs`)

- New `link_with_all_assets(user_code, sprites, sfx, music)` path
  that splices driver body, period table, and each sfx/music data
  blob into PRG — all guarded on the `__audio_used` marker so
  silent programs pay zero ROM cost.

## Assembler (`src/asm/opcodes.rs`, `src/asm/mod.rs`)

- New `AddressingMode::Bytes(Vec<u8>)` variant for raw-data
  pseudo-instructions. `NOP+Bytes(v)` emits the payload verbatim,
  letting the linker splice ROM data tables into a code section
  and still have `Label` / `SymbolLo` / `SymbolHi` fixups resolve
  correctly in the same assembly pass.

## Analyzer

- `play` / `start_music` now validate the name against user decls
  and builtin tables. Unknown names emit E0505 with a helpful list
  of builtins — previously a typo would silently compile to no-op.

## Parser

- New `sfx_decl` / `music_decl` grammar with property-style
  configuration. Strict validation: duty 0-3, volume 0-15, pitch
  arrays must match volume length, music notes must come in pairs,
  pitch 0-60, duration ≥ 1.

## Tests

+170 new tests across every layer:
- `src/assets/audio.rs`: 17 tests (compile, resolve, builtins,
  shadowing, label sanitation, nested reference walks)
- `src/parser/tests.rs`: 13 tests (valid/invalid sfx + music
  declarations, property validation, play/start_music/stop_music)
- `src/analyzer/tests.rs`: 7 tests (builtin acceptance, user decl
  acceptance, unknown-name rejection)
- `src/runtime/tests.rs`: 10 tests (audio tick labels, RTS end,
  $4000 write, $4004 mute, period table assembly, A4 = 440 Hz,
  length counter bits, data block verbatim emit)
- `src/linker/tests.rs`: 4 tests (sfx/music blob placement,
  pointer resolution, elision when unused)
- `src/codegen/ir_codegen.rs`: rewrote the 4 existing audio tests
  to match the new data-driven contract
- `tests/integration_test.rs`: 4 end-to-end tests including a
  user-declared `sfx` + `music` program that verifies bytes land
  in PRG ROM at the right addresses

## Docs

- New Audio section in `docs/language-guide.md` with syntax
  reference, builtin tables, and an explanation of how the
  driver works at compile and run time.
- `docs/architecture.md` updated to reflect the real audio
  pipeline instead of the old "audio import stubs" stub.
- `docs/future-work.md` moves audio from "status: minimal" to
  "status: full subsystem" with a narrower list of follow-up work
  (triangle/noise/DMC channels, NSF/FTM imports, richer envelopes).
- `examples/audio_demo.ne` rewritten to showcase user-declared
  `sfx LongCoin`, `sfx Zap`, `music Theme`, still demonstrating
  builtin fallback via `play coin`.

Total: 424 tests passing (381 unit + 43 integration), clippy clean,
fmt clean, all 19 examples compile.

https://claude.ai/code/session_015WfaDttE3DpWn9rpyfpQd8
This commit is contained in:
Claude 2026-04-13 01:10:21 +00:00
parent c5c8c38a54
commit d42540f45e
No known key found for this signature in database
22 changed files with 2865 additions and 243 deletions
Download patch file Download diff file Expand all files Collapse all files

70
src/linker/mod.rs
View file

@ -3,6 +3,7 @@ mod tests;
use crate::asm;
use crate::asm::{AddressingMode as AM, Instruction, Opcode::*};
use crate::assets::{MusicData, SfxData};
use crate::parser::ast::{Mapper, Mirroring};
use crate::rom::RomBuilder;
use crate::runtime;
@ -89,8 +90,28 @@ impl Linker {
}
/// Link all code sections into a .nes ROM, placing sprite CHR data at
/// specific tile indices.
/// specific tile indices. No audio data is linked — use
/// [`Linker::link_with_all_assets`] for audio.
pub fn link_with_assets(&self, user_code: &[Instruction], sprites: &[SpriteData]) -> Vec<u8> {
self.link_with_all_assets(user_code, sprites, &[], &[])
}
/// Link all code sections into a .nes ROM, placing both graphic
/// assets (sprite CHR) and audio assets (sfx envelopes, music
/// note streams) into the appropriate ROM regions.
///
/// Audio data is spliced into PRG ROM under labels derived from
/// each blob's name (see `SfxData::label` / `MusicData::label`).
/// The linker only emits these blobs and the audio-driver body
/// when user code contains the `__audio_used` marker label, so
/// programs that never touch audio pay zero ROM cost.
pub fn link_with_all_assets(
&self,
user_code: &[Instruction],
sprites: &[SpriteData],
sfx: &[SfxData],
music: &[MusicData],
) -> Vec<u8> {
// For NROM: everything fits in one 16 KB PRG bank ($C000-$FFFF)
// Layout:
// $C000: RESET handler (init + palette load + user code)
@ -116,13 +137,35 @@ impl Linker {
all_instructions.extend(runtime::gen_multiply());
all_instructions.extend(runtime::gen_divide());
// Audio driver body — linked in whenever user code touched
// audio. The driver needs to exist before `__nmi` (the NMI
// JSR target must be defined before the caller), so emit it
// alongside the math routines. No-cost elision when unused:
// the `has_label` check below skips the whole block.
if has_label(user_code, "__audio_used") {
// Audio subsystem — linked in whenever user code touched
// audio (detected via the `__audio_used` marker emitted by
// the IR codegen). The driver body, period table, and
// user/builtin data blobs are all spliced into PRG here.
//
// Order is important: the audio tick references both the
// period table and the data blobs by label, so those labels
// must be defined in the same assembly pass. The tick body
// also has to exist before `__nmi` because NMI JSRs into
// `__audio_tick` — so we emit it alongside the math
// routines, well before the NMI handler below.
let has_audio = has_label(user_code, "__audio_used");
if has_audio {
all_instructions.extend(runtime::gen_audio_tick());
all_instructions.extend(runtime::gen_period_table());
// Emit one data block per sfx blob: a label followed by
// the envelope bytes. `play Name` codegen emits a
// SymbolLo/SymbolHi pair that resolves to this label.
for blob in sfx {
all_instructions.extend(runtime::gen_data_block(
&blob.label(),
blob.envelope.clone(),
));
}
// Same for music: label + note stream.
for blob in music {
all_instructions
.extend(runtime::gen_data_block(&blob.label(), blob.stream.clone()));
}
}
// NMI handler
@ -138,14 +181,11 @@ impl Linker {
if has_label(user_code, "__ir_mmc3_reload") {
all_instructions.push(Instruction::new(JSR, AM::Label("__ir_mmc3_reload".into())));
}
// Audio tick: if the user program ever triggered an SFX or
// music (detected by the marker label `__audio_used` emitted
// by `IrCodeGen` when it sees any audio op), JSR into the
// driver's per-frame tick before the normal NMI body. The
// tick decrements the SFX counter and silences pulse 1 when
// it reaches zero. Programs that never play audio skip both
// the splice and the driver body entirely — no ROM cost.
let has_audio = has_label(user_code, "__audio_used");
// Audio tick: if audio is in use, JSR into the per-frame
// driver tick before the normal NMI body. The tick walks
// both the sfx envelope and the music note stream, writing
// APU registers as needed. Programs that never use audio
// skip this splice entirely — no ROM cost.
if has_audio {
all_instructions.push(Instruction::new(JSR, AM::Label("__audio_tick".into())));
}

132
src/linker/tests.rs
View file

@ -163,6 +163,138 @@ fn link_omits_audio_tick_when_no_marker() {
assert_eq!(info.prg_banks, 1);
}
#[test]
fn link_with_audio_data_places_sfx_blobs_in_prg() {
// When user code has the `__audio_used` marker AND we pass in
// sfx data, the linker must:
// 1. Splice in the audio tick (driver body)
// 2. Splice in the period table
// 3. Splice in the envelope blob under its label
// 4. Resolve SymbolLo/SymbolHi references from user code to
// the blob's address (second pass of the assembler)
let linker = Linker::new(Mirroring::Horizontal);
// User code: `LDA #<__sfx_test`, `STA $0C`, `LDA #>__sfx_test`,
// `STA $0D` — simulates what IR codegen's gen_play_sfx emits.
let user_code = vec![
Instruction::new(NOP, AM::Label("__audio_used".into())),
Instruction::new(LDA, AM::SymbolLo("__sfx_test".into())),
Instruction::new(STA, AM::ZeroPage(0x0C)),
Instruction::new(LDA, AM::SymbolHi("__sfx_test".into())),
Instruction::new(STA, AM::ZeroPage(0x0D)),
];
let sfx = vec![SfxData {
name: "test".into(),
period_lo: 0x50,
period_hi: 0x08,
envelope: vec![0xBF, 0xB8, 0xB4, 0xB0, 0x00],
}];
let rom = linker.link_with_all_assets(&user_code, &[], &sfx, &[]);
let info = rom::validate_ines(&rom).unwrap();
assert_eq!(info.prg_banks, 1);
// The envelope bytes must appear somewhere in PRG. Find them.
let prg = &rom[16..16 + 16384];
let needle = [0xBF, 0xB8, 0xB4, 0xB0, 0x00];
let found = prg.windows(needle.len()).any(|w| w == needle);
assert!(found, "sfx envelope bytes should be spliced into PRG ROM");
}
#[test]
fn link_with_audio_data_places_music_stream_in_prg() {
let linker = Linker::new(Mirroring::Horizontal);
let user_code = vec![
Instruction::new(NOP, AM::Label("__audio_used".into())),
Instruction::new(LDA, AM::SymbolLo("__music_test".into())),
Instruction::new(STA, AM::ZeroPage(0x0E)),
Instruction::new(LDA, AM::SymbolHi("__music_test".into())),
Instruction::new(STA, AM::ZeroPage(0x0F)),
];
let music = vec![MusicData {
name: "test".into(),
header: 0xA9,
stream: vec![37, 8, 41, 8, 44, 8, 0xFF, 0xFF],
}];
let rom = linker.link_with_all_assets(&user_code, &[], &[], &music);
let prg = &rom[16..16 + 16384];
let needle = [37, 8, 41, 8, 44, 8, 0xFF, 0xFF];
let found = prg.windows(needle.len()).any(|w| w == needle);
assert!(found, "music note stream should be spliced into PRG ROM");
}
#[test]
fn link_with_audio_resolves_sfx_pointer_references() {
// The SymbolLo/SymbolHi references in user code must get
// fixed up to the *actual* PRG address of the envelope blob.
// We can verify this by reading back the user code bytes and
// checking that the LDA immediates point somewhere in the
// valid PRG range ($C000-$FFFF).
let linker = Linker::new(Mirroring::Horizontal);
let user_code = vec![
Instruction::new(NOP, AM::Label("__audio_used".into())),
Instruction::new(LDA, AM::SymbolLo("__sfx_test".into())),
Instruction::new(LDA, AM::SymbolHi("__sfx_test".into())),
];
let sfx = vec![SfxData {
name: "test".into(),
period_lo: 0x50,
period_hi: 0x08,
envelope: vec![0xDE, 0xAD, 0xBE, 0xEF, 0x00],
}];
let rom = linker.link_with_all_assets(&user_code, &[], &sfx, &[]);
// The user code starts at RESET ($C000) after init+palette_load.
// Rather than compute the exact offset, verify the envelope
// bytes appear at a byte that matches what the LDA immediate
// pair would produce. We find the immediate pair by searching
// for `A9 xx A9 yy` and checking `$xxyy` points at the needle.
let prg = &rom[16..16 + 16384];
let needle = [0xDE, 0xAD, 0xBE, 0xEF, 0x00];
// Find where the envelope lives in ROM.
let env_offset = prg
.windows(needle.len())
.position(|w| w == needle)
.expect("envelope should be in PRG");
let env_addr = 0xC000u16 + env_offset as u16;
// Find any LDA-immediate pair that matches the envelope address.
let lo = (env_addr & 0xFF) as u8;
let hi = (env_addr >> 8) as u8;
let pattern = [0xA9u8, lo, 0xA9, hi];
let matched = prg.windows(pattern.len()).any(|w| w == pattern);
assert!(
matched,
"should find `LDA #<env_addr; LDA #>env_addr` in PRG ($A9 ${lo:02X} $A9 ${hi:02X})"
);
}
#[test]
fn link_without_audio_marker_does_not_emit_period_table() {
// Programs that never use audio must not pay the cost of the
// period table, driver body, or any blobs. We verify this
// indirectly: the `__period_table` label should NOT appear at
// a distinct ROM address from the main body.
let linker = Linker::new(Mirroring::Horizontal);
let user_code = vec![Instruction::implied(NOP)];
let rom = linker.link_with_all_assets(
&user_code,
&[],
&[SfxData {
name: "unused".into(),
period_lo: 0,
period_hi: 0,
envelope: vec![0xAA, 0xBB, 0x00],
}],
&[],
);
// The envelope bytes `AA BB 00` must NOT appear in PRG — the
// linker should have elided the whole audio section because
// the marker is absent.
let prg = &rom[16..16 + 16384];
let needle = [0xAAu8, 0xBB, 0x00];
let found = prg.windows(needle.len()).any(|w| w == needle);
assert!(
!found,
"unused sfx data should not be spliced when __audio_used is absent"
);
}
#[test]
fn palette_load_writes_to_ppu() {
let linker = Linker::new(Mirroring::Horizontal);