atari-dl-analyzer

name

atari-dl-analyzer

description

Analyze an Atari 8-bit ANTIC display list (and its DLIs) for the Rescue on Fractalus port. Given a savestate (and optionally a DL address), produces a clear region-by-region description of what the display list does — the scanline ranges, the screen mode + screen RAM (LMS) of each region, the live GTIA colour / player / missile / priority state at those scanlines, and what each DLI handler writes (and from which mem[] source). Use this whenever you need to understand how a scene composes its screen before generating the matching Amiga CopperList / poke code, instead of re-deriving it by hand from disasm + dumps.

Atari display-list analyzer

Reusable replacement for the ad-hoc "drive atari800, DLIST, BLINE/GTIA, disassemble the DLI" investigation we keep repeating. The output is a behavioural spec of a display list (not a copper list) that you then translate into the appropriate Amiga CopperList / update*Copper poke code.

It answers, per scene:

• which scanlines are waited / where each region starts and ends;
• which ANTIC screen mode applies in each region (and the LMS screen-RAM address);
• which DLIs fire on which rows and what colours/positions they modify;
• the live GTIA state (COLBK, COLPF0-3, COLPM0-3, GRAFM, PRIOR, HPOSM/P) at each scanline — i.e. the actual on-screen result, including mid-frame DLI changes that static analysis of the shadows ($02C0-$02C8) cannot see.

Prerequisites

• atari800 (v5.x) and gstdbuf (brew install coreutils) on PATH.
• A savestate of the scene of interest in a800dumps/ (e.g. launch_1_title.a8s = Standby, launch_5_planet.a8s, flight1.a8s). Capture new ones from the FIFO monitor with SAVESTATE <name>.a8s if needed.
• kill -9 any stray atari800 first (pkill -9 atari800).

How to run

The skill scripts live in this directory (.claude/skills/atari-dl-analyzer/).

1. Capture (headless; drives the emulator's monitor — no display interaction):

.claude/skills/atari-dl-analyzer/dl_capture.sh a800dumps/launch_1_title.a8s [ymin ymax step]

• Defaults sweep scanlines 8..240 (~90 s). Narrow the range once you know roughly where the region is (e.g. 120 150 1 for a cockpit-top band) — ~0.4 s per scanline.
• Writes the raw log to /tmp/dl_capture.log (override with DL_OUT=).
• It runs DLIST once, then BLINE y; CONT; GTIA for each scanline, tagging each GTIA dump with ==L<y>==.

2. Report — turn the capture into the region-by-region spec:

python3 .claude/skills/atari-dl-analyzer/dl_report.py /tmp/dl_capture.log [--ram a800dumps/<scene>.bin]

Prints two sections: the DL structure (modes/LMS/DLI flags, relative scanlines) and the live GTIA state by scanline collapsed into constant-state runs (absolute scanlines). The DL MODE D / distinctive regions let you align the two.

3. DLI sources — to learn which mem[] feeds a colour (decides baked-constant vs per-frame poke on the Amiga), disassemble the DLI handler. Find its address from the live VDSLST vector ($0200/$0201) or the dispatcher slot table, then:

python3 .claude/skills/atari-dl-analyzer/dl_report.py --ram a800dumps/<scene>.bin --dli 0x6D7C

Lists the handler's STA $D0xx writes with their source (#$imm vs from reg/mem). A write sourced from a zero-page address that ramps (e.g. a fade) → make it a per-frame copper poke; a hard immediate → bake it constant.

Static-only DL walk (no emulator, fast structural map from a RAM dump):

python3 .claude/skills/atari-dl-analyzer/dl_report.py --ram a800dumps/<scene>.bin --dl 0x3000

Reading the result → Amiga copper

• A region's value-0 pixels show COLBK; value-1/2/3 show COLPF0/1/2 (map modes) or per the GTIA-10/text mapping. Match the Amiga color00..03 for that scanline band to the GTIA values shown.
• MODE D rows are line-doubled on the Amiga (2 scanlines each); account for that when converting relative DL scanlines to the Amiga band height.
• A colour that differs across the sweep within one DL region means a DLI changed it mid-region → the Amiga copper needs a WAIT + MOVE at that scanline (a palette split), not a single baked value. (This is exactly the Standby windscreen-band COLBK green→black split.)
• GRAFM/HPOSM nonzero in a band = missiles are part of the composition (port as Amiga sprites behind the bitplanes); PRIOR & $10 = 5th-player (missiles take COLPF3).

Notes / gotchas (kept so they are not rediscovered)

• atari800 stdout is block-buffered to a pipe — dl_capture.sh uses gstdbuf -o0 so dumps flush. If a run shows no output, that is the cause.
• BLINE ypos is the absolute frame scanline; the visible display starts ~line 8. The DL walk gives scanlines relative to DL start, so align the two reports by the distinctive region (e.g. the mode-D band), not by assuming a fixed offset.
• The Amiga display maps hardware scanline = Amiga-display-y + kDisplayTop (0x2c/44): e.g. hardware scanline 172 = display y128.
• RAM base in .a8s is anchored at $7148 (see tools/extract_a8s_ram.py); --ram accepts either a .bin (flat 64K) or a .a8s (auto-extracted).