romdev-mcp 0.1.1

package/src/platforms/atari7800/TROUBLESHOOTING.md

@@ -0,0 +1,195 @@
+# Atari 7800 — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first
+(via `getPlatformDoc({platform:"atari7800", name:"mental_model"})`)
+for the "what's going on" version — the 7800 is the architectural outlier
+of the bundled platforms and most "wait, why?" moments come from
+expecting it to behave like a NES.
+
+## "Screen is black / wrong border colour"
+
+Two common modes:
+
+1. **`CTRL` doesn't have DMA enabled.** Write `CTRL = 0x40` AFTER
+   you've set up DPPH/DPPL. The high bit (`0x80`) is "color burst
+   off" (monochrome) — leave it off. Bit 6 (`0x40`) is "DMA enable
+   AND no border" — that's what you want for a normal display.
+2. **DPPL/DPPH point at a stale DLL.** If you set them before
+   you've filled in DLL bytes 1+2 with the actual DL pointer, MARIA
+   walks garbage and draws nothing. Order:
+   ```c
+   dll[1] = high_byte_of_dl;
+   dll[2] = low_byte_of_dl;
+   DPPL = low_byte_of_dll;
+   DPPH = high_byte_of_dll;
+   CTRL = 0x40;
+   ```
+
+## "Sprite is invisible"
+
+The most common cause is the DL header's "write width" byte being
+wrong. The format is:
+
+```
+header[1] = 0x80 | ((-width_bytes) & 0x1F)
+```
+
+For a 16-pixel-wide sprite at 160B mode (4 px per byte → 4 bytes
+wide), `width_bytes = 4`, so `header[1] = 0x80 | ((-4) & 0x1F) =
+0x9C`. If you instead wrote `header[1] = width_bytes`, the bit-7
+"write form" flag isn't set and MARIA interprets the header as a
+4-byte form pointing at garbage.
+
+## "Sprite is in the wrong vertical position"
+
+Y position is encoded by **which DLL zone** the DL entry is in,
+NOT by a per-object Y. To move a sprite vertically across zones,
+you have to:
+
+1. Build a multi-zone DLL (each zone N scanlines tall).
+2. Place the sprite's DL entry into the zone covering its Y range.
+3. Per-frame, move the entry's bytes from old-zone DL → new-zone DL.
+
+Our scaffolds use a single-zone DLL for simplicity. Vertical
+movement is faked by stamping the sprite at different row offsets
+within the canvas data — only works if the canvas is tall enough.
+
+## "Memory overflow during link (RAM1 by N bytes)"
+
+The 7800 has **4 KB of RAM**. The `default.c` and `hello_sprite.c`
+scaffolds use very little; the `shmup.c` puzzle (and the older
+canvas-buffer approach) easily blow past it.
+
+Symptoms:
+```
+/share/cc65/cfg/atari7800.cfg:22: Warning: Segment 'BSS' overflows
+memory area 'RAM1' by N bytes
+```
+
+Fixes:
+- Drop large static arrays. Anything > ~1 KB is suspect.
+- Use ROM constants (`const uint8_t` at file scope) instead of
+  RAM globals.
+- Replace canvas-buffer rendering with per-object DLs (see
+  `shmup.c` scaffold for the canonical pattern).
+- Avoid per-frame `memset(canvas, 0, ...)` — instead, only stamp
+  changed cells.
+
+## "Colours look wrong / washed out"
+
+The 7800 uses the **Atari NTSC palette**, not RGB. Colour bytes are
+`HHHL` (hue + luminance). If you pass an SMS-style 2-2-2 BGR byte
+you'll get nonsense colours.
+
+Common values:
+```
+0x00  black
+0x0E  white
+0x46  orange
+0x88  blue mid
+0xC4  green dim
+0x1A  yellow-orange
+```
+
+Use Stella's palette reference (or any 2600/7800 palette diagram)
+to look up the byte for your intended colour.
+
+## "Game runs but plays sounds from the wrong channel"
+
+The 7800's TIA audio uses identical registers to the 2600:
+`AUDC0/AUDC1`, `AUDF0/AUDF1`, `AUDV0/AUDV1` at `$15-$1A`. Channel
+ordering is consistent across systems.
+
+If audio is silent: check that **VOLUME** (`AUDV0/1`) is non-zero
+— it defaults to 0 on reset. Many sample drivers forget the
+volume write.
+
+## "cc65 compile warning: 'Integer constant implies signed long'"
+
+This is harmless for 7800 code. cc65 warns when a literal exceeds
+int16 range. Cast to unsigned or use `UL` suffix to silence.
+
+## "DL works the first frame, then renders garbage"
+
+You're modifying the DL while MARIA is reading it. MARIA scans the
+DL during active rendering; safe modification windows:
+
+- Before `CTRL = 0x40` first runs (boot)
+- During vblank (`MSTAT & 0x80` true)
+
+Build a "next-frame" DL during the game-state update phase and
+swap pointers (DPPL/DPPH) at vblank — double-buffered.
+
+Our scaffolds rebuild the DL during vblank, which works for small
+DLs (< ~100 bytes). Large DLs that take ~1 ms to rebuild may
+exceed vblank time and start corrupting the active frame.
+
+**For a real moving game, prefer PATCHING IN PLACE over rebuilding.**
+Build the DLL + DL structure ONCE at init, then each frame overwrite
+only the bytes that changed (an object's X / graphics-pointer / palette,
+or set width=0 / a blank tile to hide it). A full per-frame DLL+DL
+rebuild is the most common cause of "stable for one frame, then tears /
+hangs once motion starts." See MENTAL_MODEL.md § "Dynamic display lists —
+what to rebuild per frame" for the per-field rebuild-cadence table.
+
+## "ROM > 32 KB doesn't run"
+
+The default linker config is single-bank 32 KB. The 7800 supports
+bank-switching via the SuperGame mapper for ROMs up to 512 KB. To
+use it, edit the linker config to declare additional banks and
+the bank-switch entry-point at `$8000`. For most agent-driven
+games, stay in 32 KB.
+
+## "First build is slow but later ones are fast"
+
+Expected. cc65 + ca65 + ld65 cold-load + cfg-parse takes ~1-2s.
+Steady-state builds are sub-second thanks to the worker pool (R12).
+
+## "Screen has garbage strips / random pixel patterns / pink+black bands"
+
+Almost always one of THREE bugs in your DL/DLL setup:
+
+1. **DLL too short.** MARIA has NO DLL terminator — it walks one
+   entry per scanline for ALL 243 display lines (NTSC). If your DLL
+   only covers a few zones, MARIA reads past the end into random
+   RAM and renders garbage zones.
+   Fix: allocate `dll[243*3]` and explicitly point every entry
+   (use `dl_empty` for zones with no objects). See `default.c`.
+
+2. **DL header in too-small array.** A 5-byte extended DL entry
+   takes 5 bytes, but MARIA reads the NEXT entry's mode byte at
+   `dp + 6` after advancing. If your DL is `uint8_t dl[6]`, MARIA
+   reads `dl[6]` — out of bounds, almost guaranteed non-zero, loop
+   keeps going into garbage.
+   Fix: allocate `uint8_t dl[7]` with byte 5 unused + byte 6 = 0
+   (the terminator). See the `MK_DL` macro in `default.c`.
+
+3. **DLL zone with `offset > 15`.** The DLL byte-0 `offset` field
+   is only 4 bits (bits 0-3), so max value 15 → zone height max
+   16 scanlines. Writing `0x80 | 183` (intending "183 scanlines
+   in this zone") sets DLI (bit 7) and offset to `183 & 15 = 7`
+   — you get an 8-scanline zone AND fire NMIs you don't have a
+   handler for.
+   Fix: use multiple smaller zones, or the 1-scanline-per-zone
+   pattern in `default.c` (offset = 0 everywhere).
+
+## "BSS overflow / 'Segment BSS overflows memory area RAM1'"
+
+The 7800's RAM1 is 2112 bytes ($1800-$203F). The default DLL
+(243*3 = 729 B) plus a per-scanline DL pool plus game state can
+exceed this fast.
+
+Diagnostic:
+```
+build log shows: 'Segment BSS overflows memory area RAM1 by N bytes'
+```
+
+Fix options (in order of how much they shrink BSS):
+- Reduce `PLAY_LINES` (per-scanline DL pool size scales linearly).
+- Reduce `MAX_OBJS_PER_LINE` (each removes 5 bytes per scanline).
+- Use the simpler per-row-DL pattern (`MK_DL(dl_row0)..dl_row7`)
+  if you only need one sprite at a time — see `default.c` and
+  `hello_sprite.c`. No per-scanline pool needed.
+
+The bundled scaffolds size their pools to fit; if you scale up
+(more objects, taller play area), watch the build log.

package/src/platforms/atari7800/UPSTREAM_SOURCES.md

@@ -0,0 +1,43 @@
+# Atari 7800 — source you can read
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/atari7800/templates/*.c`).
+2. **Bundled runtime** — `src/platforms/atari7800/lib/c/
+   atari7800_sfx.c`, `atari7800_music.c`, asm helpers in `lib/*.asm`,
+   `maria_registers.h`.
+3. **Bundled cc65 atari7800 libsrc** (R58) at `src/platforms/
+   atari7800/lib/cc65-src/`. cc65's 7800 target — joystick, conio,
+   MARIA helpers.
+4. **Upstream**:
+
+   | What | Upstream |
+   |---|---|
+   | cc65 | https://github.com/cc65/cc65 |
+   | prosystem libretro core | https://github.com/libretro/prosystem-libretro |
+
+## 7800 hardware docs
+
+- **7800 Software Guide** (Atari official, scanned): https://atariage.com/2600/archives/index.html#7800
+- **MARIA programming**: https://atariage.com/forums/forum/51-atari-7800-programming/
+- **TIA audio** (same chip as 2600): see `../atari2600/UPSTREAM_SOURCES.md`
+
+## MARIA is unusual
+
+The 7800's video chip (MARIA) doesn't use a fixed framebuffer or
+tile grid — every scanline is composed from **Display List Objects**
+that point at sprite-like graphics buffers. The programmer assembles
+each frame's display list in RAM and writes a pointer to it via
+`DLL` ($FC). MARIA walks the list each frame.
+
+Bundled `display_list.asm` + `maria_init.asm` show the canonical
+single-zone DL pattern. Read the 7800 Software Guide § DMA + DL
+sections before doing anything custom.
+
+## When to use what
+
+- "How do I render N sprites?" → MARIA DL — 7800 SW Guide
+- "TIA audio (POKEY's not on most 7800 carts)" → atari7800_sfx.c +
+  TIA docs (same chip as 2600)
+- "prosystem doesn't expose register X" → libretro prosystem GitHub
+- "cc65's 7800 conio implementation" → `lib/cc65-src/`

package/src/platforms/atari7800/lib/README.md

@@ -0,0 +1,45 @@
+Atari 7800 starter snippets
+===========================
+
+Hand-vetted boilerplate for the 7800. The default toolchain is **7800basic**
+or **cc65** with the `atari7800` target — the snippets here are written in
+ca65-style asm for use with cc65/ca65 or as inline asm in C via `__asm__()`.
+
+Files
+-----
+
+- **maria_registers.h** — symbolic names + bit masks for MARIA + TIA-audio
+  registers ($20-$3F and $15-$1A).
+- **maria_init.asm** — boot-time setup: enable DMA, install minimal
+  display-list-list (DLL), point CTRL at the display list.
+- **display_list.asm** — example single-zone display list rendering a
+  single sprite from RAM.
+- **palette_load.asm** — write 8 palettes × 3 colors + the background
+  color into the MARIA palette registers.
+- **vblank_wait.asm** — busy-wait on MARIA STATUS bit 7 (vblank).
+- **read_pad.asm** — read joystick 0 + 1 from INPT0-3 (analog) + INPT4-5
+  (digital fire).
+
+Toolchain
+---------
+
+Build via `buildSource({ platform: "atari7800", source: "..." })`. Server
+spawns cc65 with the bundled `atari7800.cfg`. The MCP server invokes
+the prosystem libretro core to run the result.
+
+Foot-guns
+---------
+
+1. **No automatic init.** Unlike NES/SNES the 7800 has no power-on screen
+   blank — if you don't enable DMA + load a display list, MARIA renders
+   uninitialised memory. Always run `maria_init.asm` first.
+2. **DLL ≠ DL.** The display-list-LIST (DLL) is a list of pointers to
+   display-LISTs (DL). A DLL entry says "draw this DL for N scanlines."
+   Each DL is one or more drawable entries (sprite/character mode).
+3. **Palette bytes share format with the 2600.** Each color is one byte
+   from the 256-color master palette ((hue<<4) | luma).
+4. **CHARBASE matters in character mode** ($87). Sets the high byte of
+   character pixel data — make sure your font data is page-aligned.
+5. **No NES-style mappers.** 7800 carts are either 16 KB, 32 KB, or 48 KB
+   linear-mapped to the top of address space; banked carts (>48 KB) use
+   game-specific schemes (POKEY/SuperGame).

package/src/platforms/atari7800/lib/c/atari7800_music.c

@@ -0,0 +1,215 @@
+/* atari7800_music.c — 2-voice TIA music driver for Atari 7800.
+ *
+ * TIA audio register layout (same as atari7800_sfx.c):
+ *   $15 AUDC0 / $16 AUDC1 — waveform/distortion (0..15)
+ *   $17 AUDF0 / $18 AUDF1 — frequency divider (0..31, lower = higher pitch)
+ *   $19 AUDV0 / $1A AUDV1 — volume (0..15)
+ *
+ * Distortion modes used here:
+ *   4  = pure tone via 5-bit polynomial — used for both melody and bass
+ *   6  = pure tone (div-by-31), lower-pitched character — used for bass
+ *        so the two voices have distinct timbres even when their AUDF
+ *        values overlap (TIA's 5-bit divider gives only 32 pitches).
+ *
+ * Pitch picks: AUDF=4..30. Lower = higher pitch. The "tonic" of the
+ * melody hook sits around AUDF=12, the octave-up around AUDF=6.
+ * Bass walks an octave below the melody (AUDF=24/18 range).
+ *
+ * Each table entry is 3 bytes: { distortion, freq, frames }. The trailing
+ * sentinel is { 0, 0, 0 } — the player wraps to index 0 when it sees
+ * frames==0 OR when it runs past the table end (frames==0 doubles as
+ * "end of song"). Each voice loops independently.
+ *
+ * @60Hz, 30 frames = 0.5s = one quarter note at 120 BPM. The melody uses
+ * 15-frame eighths and 30-frame quarters; the bass uses 60-frame halves
+ * for a walking quarter-note feel (60-frame note at 120BPM = a half).
+ */
+
+#include "atari7800_music.h"
+
+#define AUDC0  (*(volatile uint8_t*)0x15)
+#define AUDC1  (*(volatile uint8_t*)0x16)
+#define AUDF0  (*(volatile uint8_t*)0x17)
+#define AUDF1  (*(volatile uint8_t*)0x18)
+#define AUDV0  (*(volatile uint8_t*)0x19)
+#define AUDV1  (*(volatile uint8_t*)0x1A)
+
+/* Pitch shorthand (AUDF values, picked by ear on TIA distortion 4).
+ * These aren't equal-tempered — TIA can't be — but they're audibly
+ * distinct and form a usable "scale". */
+#define M_DO_HI  6
+#define M_TI     7
+#define M_LA     8
+#define M_SOL    9
+#define M_FA     10
+#define M_MI     12
+#define M_RE     14
+#define M_DO     15
+
+/* Bass an octave down (distortion mode 6 for timbre contrast). */
+#define B_DO     30
+#define B_SOL    20
+#define B_FA     25
+#define B_LA     18
+
+/* Note tables. Format: distortion, freq, frames. The note tables ARE
+ * the song; edit them to re-compose. */
+
+/* Melody: 4-bar arpeggio hook (do-mi-sol-do-mi-do-sol-mi) twice, then
+ * a descending walk (do-ti-la-sol-fa-mi-re-do), then repeat with the
+ * arpeggio shifted up an octave. ~48 notes. */
+static const uint8_t melody_notes[] = {
+  /* bar 1: do mi sol do (octave up) */
+  4, M_DO,    15,
+  4, M_MI,    15,
+  4, M_SOL,   15,
+  4, M_DO_HI, 15,
+  /* bar 2: mi sol mi do */
+  4, M_MI,    15,
+  4, M_SOL,   15,
+  4, M_MI,    15,
+  4, M_DO,    15,
+  /* bar 3: sol mi do mi */
+  4, M_SOL,   15,
+  4, M_MI,    15,
+  4, M_DO,    15,
+  4, M_MI,    15,
+  /* bar 4: sol do (octave-up) sol mi */
+  4, M_SOL,   15,
+  4, M_DO_HI, 15,
+  4, M_SOL,   15,
+  4, M_MI,    15,
+  /* bar 5: descending walk */
+  4, M_DO_HI, 15,
+  4, M_TI,    15,
+  4, M_LA,    15,
+  4, M_SOL,   15,
+  /* bar 6: continue walk */
+  4, M_FA,    15,
+  4, M_MI,    15,
+  4, M_RE,    15,
+  4, M_DO,    30,
+  /* bar 7: octave-up arpeggio */
+  4, M_DO_HI, 15,
+  4, M_SOL,   15,
+  4, M_MI,    15,
+  4, M_SOL,   15,
+  /* bar 8: cadence */
+  4, M_DO_HI, 15,
+  4, M_SOL,   15,
+  4, M_MI,    15,
+  4, M_DO,    30,
+  /* bar 9-12: repeat arpeggio + variation */
+  4, M_DO,    15,
+  4, M_MI,    15,
+  4, M_SOL,   15,
+  4, M_DO_HI, 15,
+  4, M_SOL,   15,
+  4, M_MI,    15,
+  4, M_DO,    15,
+  4, M_MI,    15,
+  4, M_FA,    15,
+  4, M_LA,    15,
+  4, M_FA,    15,
+  4, M_MI,    15,
+  4, M_RE,    15,
+  4, M_MI,    15,
+  4, M_DO,    15,
+  4, M_DO,    30,
+  0, 0,        0    /* sentinel — loop */
+};
+
+/* Bass: walking quarter-notes following a do-do-sol-sol / do-do-fa-sol
+ * I-V-IV-V style pattern. Each entry is a half-note @ 60 frames so the
+ * melody plays ~4 eighths per bass note. ~16 notes. */
+static const uint8_t bass_notes[] = {
+  6, B_DO,  60,
+  6, B_DO,  60,
+  6, B_SOL, 60,
+  6, B_SOL, 60,
+  6, B_FA,  60,
+  6, B_FA,  60,
+  6, B_SOL, 60,
+  6, B_DO,  60,
+  6, B_DO,  60,
+  6, B_LA,  60,
+  6, B_FA,  60,
+  6, B_FA,  60,
+  6, B_SOL, 60,
+  6, B_SOL, 60,
+  6, B_DO,  60,
+  6, B_DO,  60,
+  0, 0,      0    /* sentinel — loop */
+};
+
+/* Per-voice playback state. */
+static uint16_t mel_idx;
+static uint16_t bass_idx;
+static uint8_t  mel_frames_left;
+static uint8_t  bass_frames_left;
+
+static void start_melody_note(void) {
+  uint8_t c = melody_notes[mel_idx];
+  uint8_t f = melody_notes[mel_idx + 1];
+  uint8_t l = melody_notes[mel_idx + 2];
+  if (l == 0) {           /* sentinel — loop back to start */
+    mel_idx = 0;
+    c = melody_notes[0];
+    f = melody_notes[1];
+    l = melody_notes[2];
+  }
+  AUDC0 = c;
+  AUDF0 = f & 0x1F;
+  AUDV0 = 12;             /* slightly less than max so 2 voices don't clip */
+  mel_frames_left = l;
+}
+
+static void start_bass_note(void) {
+  uint8_t c = bass_notes[bass_idx];
+  uint8_t f = bass_notes[bass_idx + 1];
+  uint8_t l = bass_notes[bass_idx + 2];
+  if (l == 0) {
+    bass_idx = 0;
+    c = bass_notes[0];
+    f = bass_notes[1];
+    l = bass_notes[2];
+  }
+  AUDC1 = c;
+  AUDF1 = f & 0x1F;
+  AUDV1 = 10;             /* bass a touch quieter than melody */
+  bass_frames_left = l;
+}
+
+void music_init(void) {
+  AUDC0 = 0; AUDC1 = 0;
+  AUDF0 = 0; AUDF1 = 0;
+  AUDV0 = 0; AUDV1 = 0;
+  mel_idx = 0;
+  bass_idx = 0;
+  mel_frames_left = 0;
+  bass_frames_left = 0;
+}
+
+void music_play(void) {
+  mel_idx = 0;
+  bass_idx = 0;
+  start_melody_note();
+  start_bass_note();
+}
+
+void music_update(void) {
+  if (mel_frames_left > 0) {
+    mel_frames_left--;
+    if (mel_frames_left == 0) {
+      mel_idx += 3;
+      start_melody_note();
+    }
+  }
+  if (bass_frames_left > 0) {
+    bass_frames_left--;
+    if (bass_frames_left == 0) {
+      bass_idx += 3;
+      start_bass_note();
+    }
+  }
+}

package/src/platforms/atari7800/lib/c/atari7800_music.h

@@ -0,0 +1,33 @@
+/* atari7800_music.h — 2-voice TIA music engine for Atari 7800.
+ *
+ * Pairs with atari7800_sfx (same TIA registers) but is a *song player*,
+ * not a one-shot fx wrapper. Two parallel note tables (melody on voice 0,
+ * bass on voice 1) drive the chip per-frame. The note tables ARE the song;
+ * editing them re-composes the tune.
+ *
+ *   music_init()    — silences both TIA voices, resets cursors
+ *   music_play()    — restart playback from index 0 on both voices
+ *   music_update()  — call once per frame (after vblank_wait). Each voice
+ *                     independently counts down its current note's
+ *                     frames-left; when it hits 0, advance to the next
+ *                     note in that voice's table (wrapping at the end so
+ *                     the song loops forever).
+ *
+ * TIA's frequency divider is only 5 bits (0..31), so the available pitch
+ * set is small and the song sounds primitive. Goal here is "music plays
+ * + you can hear melody-vs-bass" not "good music".
+ *
+ * Each note is a triple { AUDC distortion, AUDF frequency, length_frames }.
+ * The note tables live in the .c file so the source IS the song.
+ */
+
+#ifndef ATARI7800_MUSIC_H
+#define ATARI7800_MUSIC_H
+
+#include <stdint.h>
+
+void music_init(void);
+void music_play(void);
+void music_update(void);
+
+#endif

package/src/platforms/atari7800/lib/c/atari7800_sfx.c

@@ -0,0 +1,74 @@
+/* atari7800_sfx.c — TIA audio driver for Atari 7800 scaffolds.
+ *
+ * TIA audio register layout:
+ *   $15 AUDC0   channel 0 waveform/distortion (0..15)
+ *   $16 AUDC1   channel 1 waveform/distortion
+ *   $17 AUDF0   channel 0 frequency divider (0..31, lower = higher pitch)
+ *   $18 AUDF1   channel 1 frequency divider
+ *   $19 AUDV0   channel 0 volume (0..15)
+ *   $1A AUDV1   channel 1 volume
+ *
+ * Per-channel "frames-left" counter drives auto-silence in sfx_update.
+ * Without sfx_update() the volume stays set and notes ring forever.
+ */
+
+#include "atari7800_sfx.h"
+
+#define AUDC0  (*(volatile uint8_t*)0x15)
+#define AUDC1  (*(volatile uint8_t*)0x16)
+#define AUDF0  (*(volatile uint8_t*)0x17)
+#define AUDF1  (*(volatile uint8_t*)0x18)
+#define AUDV0  (*(volatile uint8_t*)0x19)
+#define AUDV1  (*(volatile uint8_t*)0x1A)
+
+static uint8_t sfx_remaining[2];
+
+void sfx_init(void) {
+  AUDC0 = 0; AUDC1 = 0;
+  AUDF0 = 0; AUDF1 = 0;
+  AUDV0 = 0; AUDV1 = 0;
+  sfx_remaining[0] = 0;
+  sfx_remaining[1] = 0;
+}
+
+void sfx_tone(uint8_t channel, uint8_t freq, uint8_t length_frames) {
+  if (channel == 0) {
+    AUDC0 = 4;             /* pure tone */
+    AUDF0 = freq & 0x1F;   /* 5-bit divider */
+    AUDV0 = 15;            /* max vol */
+    sfx_remaining[0] = length_frames;
+  } else if (channel == 1) {
+    AUDC1 = 4;
+    AUDF1 = freq & 0x1F;
+    AUDV1 = 15;
+    sfx_remaining[1] = length_frames;
+  }
+}
+
+void sfx_noise(uint8_t length_frames) {
+  /* White noise on channel 1 so an in-flight tone on ch 0 isn't
+   * interrupted. Distortion mode 8 = white-noise-ish. */
+  AUDC1 = 8;
+  AUDF1 = 8;
+  AUDV1 = 15;
+  sfx_remaining[1] = length_frames;
+}
+
+void sfx_update(void) {
+  uint8_t i;
+  for (i = 0; i < 2; i++) {
+    if (sfx_remaining[i] > 0) {
+      sfx_remaining[i]--;
+      if (sfx_remaining[i] == 0) {
+        if (i == 0) AUDV0 = 0;
+        else        AUDV1 = 0;
+      }
+    }
+  }
+}
+
+void sfx_off(void) {
+  AUDV0 = 0; AUDV1 = 0;
+  sfx_remaining[0] = 0;
+  sfx_remaining[1] = 0;
+}

package/src/platforms/atari7800/lib/c/atari7800_sfx.h

@@ -0,0 +1,45 @@
+/* atari7800_sfx.h — minimal Atari 7800 TIA sound-effects wrapper.
+ *
+ * The 7800 inherits the 2600's TIA audio chip (the MARIA video chip
+ * is the 7800-specific upgrade). TIA audio = 2 independent voices:
+ *
+ *   AUDC0/1  ($15/$16) — waveform/distortion (0..15)
+ *     Useful values:
+ *       1  = pure  (4-bit poly, sounds buzzy)
+ *       4  = pure tone (5-bit poly)
+ *       6  = pure tone (div-by-31)
+ *       8  = white noise
+ *      12  = pure tone (LFSR)
+ *      15  = noise (lowest pitch)
+ *   AUDF0/1  ($17/$18) — frequency divider (0..31). Lower = higher pitch.
+ *   AUDV0/1  ($19/$1A) — volume (0..15). 0 = silent.
+ *
+ * Same 5-function shape as nes_runtime / gb_runtime / gba_sfx /
+ * genesis_sfx / sms_sfx / gg_sfx:
+ *
+ *   sfx_init()
+ *   sfx_tone(channel, freq, length_frames)
+ *   sfx_noise(length_frames)
+ *   sfx_update()       — call once per frame
+ *   sfx_off()
+ *
+ * channel = 0 or 1 for sfx_tone (only 2 voices). sfx_noise always
+ * uses channel 1 so channel 0 can keep playing a tone underneath.
+ *
+ * Notes: 7800 has an optional cartridge-side POKEY chip with 4 more
+ * voices, but most carts didn't ship with POKEY. This wrapper uses
+ * TIA-only so it works on every 7800.
+ */
+
+#ifndef ATARI7800_SFX_H
+#define ATARI7800_SFX_H
+
+#include <stdint.h>
+
+void sfx_init(void);
+void sfx_tone(uint8_t channel, uint8_t freq, uint8_t length_frames);
+void sfx_noise(uint8_t length_frames);
+void sfx_update(void);
+void sfx_off(void);
+
+#endif