Compatibility manifest

What runs in zxplay_go. This is a working document — every entry has a status, the model it was tested on, and (if "Issue") a brief note. The list isn't exhaustive; it's the titles a contributor has specifically loaded and run to a point of confident "works" or "broken here". To add an entry, follow the protocol at the bottom.

Status legend:

• Works — boots to title screen, accepts input, plays.
• Works (caveat) — playable but with a known emulator-side imperfection. Caveat documented in the Notes column.
• Parses cleanly — file-format parser accepts the image without error. No gameplay verification.
• Known issue — loads partway, crashes, or visibly wrong. Filed as a GitHub issue (linked).
• Untested — no contributor has run this through yet.

Confidence note: every title below sits on top of the same Z80 core that passes both Cringle exerciser suites (zexdoc and zexall). "Works" therefore means CPU correctness is not under suspicion when something does go wrong — it's almost always a peripheral or timing issue. See "Foundation tests" for what blanket-cover tests do and don't buy you.

Foundation tests

These integration tests under pkg/testharness (and one in pkg/plus3fdc) prove the foundation for each category works. They do not prove arbitrary programs in the category run correctly — they prove the boot path and primary API surface are sound, which narrows the debug area when a specific title misbehaves.

If a title in a covered category fails, the bug is almost certainly in a peripheral driver, timing, or untested undocumented behaviour — not the core CPU.

48K titles

Canonical 48K titles. None have been individually verified through zxplay_go yet; foundation tests confirm the 48K boot path works.

128K / +2 titles

Titles that use the AY-3-8912 sound chip and/or the extended 128K memory map. Foundation tests confirm 128K paging works.

+3 / +2A disk titles

Titles distributed on +3 floppy disk. Foundation: plus3fdc DSK / EDSK / UDI round-trip tests prove the disk container code is symmetric, but no individual +3 title has been loaded and run.

If you have a +3 DSK image that isn't listed and you want to add it, follow the protocol at the bottom of this document.

Demoscene

Demoscene productions exercise timing-sensitive features — mid-frame border palette switches, AY register tricks, contention patterns, multi-loader tape rituals — that the test harness doesn't cover. Visual + audio inspection is the only verification.

A general note rather than specific titles: zxplay_go's mid-frame border tracking (per-scanline, see pkg/ula) and AY-3-8912 register semantics should handle typical demo techniques, but no specific demo has been run through the full pipeline yet. Spectrum demos worth trying as stress tests are anything that uses a multicolour technique (8×1 attribute blocks via raster-synced palette writes), or anything labelled "intro" or "megademo" from a known group (Triebkraft, Raww Arse, Mayhem, Lyra) — these are the productions most likely to expose timing imperfections.

Spectrum Next titles

The Next cold-boots NextZXOS end-to-end — splash → firmware → welcome → menu/Browser/NextBASIC — see docs/spectrum-next.md. The individual hardware blocks (Layer 2 incl. hi-res, the sprite engine, tilemap, Copper, the NextReg file, the 8K MMU) are tested against the FPGA VHDL.

Running arbitrary .NEX games is the newest and least-finished part of zxplay_go, and the most likely place to hit a bug. .nex titles are launched through NextZXOS's own loader, so OS-dependent games run as on hardware — but per-title behaviour varies widely.

The table below is the July 2026 headless triage, re-baselined 2026-07-14 against the r47 core (post #163 RETI/RETN fix). Method: each title's WHOLE release folder (data subfolders included) is staged onto a copy of the shipped SD image with an auto-running .nexload autoexec (_tools/stage-oracle-sd, recursive staging), cold-booted headless 16000–40000 frames with screenshots, --press-key schedules where a menu blocks progress, and --dump-state signatures. "Works (title)" means the title screen/menu renders and the game was not driven further headless — not a full playability verdict.

Method lesson from the re-baseline: the original sweep launched each title through ZX_GO_RUN_NEX_FILE, which stages only the lone .nex. Titles that LOAD separate data files at runtime then failed for the wrong reason — two of the three previously recorded "game-era" failures (WOTEF's dead HALT, Aliens Neoplasma's sparse red lines) were exactly this staging artifact and cleared once their data folders were staged. Full-folder staging is now the sweep method.

Next failure classes and the ranked gap list (re-baselined 2026-07-14 against r47, work item #164)

The failures cluster into classes; ranked by how many titles each blocks (the conformance prioritizer — see work items #159/#164):

1. CLOSED (work item #171, 2026-07-15): Next wide-layer geometry — one 320×256 frame coordinate system. Found by a manual game-test pass: border-area corruption and a consistent vertical offset between sprites and background layers (Tyvarian's torn title + sprite/backdrop drift, Crowley World Tour's displaced text and falling shapes, and any title drawing tilemap or wide Layer 2 content). In the FPGA, sprites, the tilemap and Layer 2's 320×256/640×256 modes all consume the SAME whc/wvc wide counters (zxnext.vhd:4208/4337/4389) — one 320×256 frame, paper at (32,32). Our render used a 320×240 canvas with THREE vertical conventions: sprites correct, tilemap 32 px low in the paper area (frame offset applied horizontally but not vertically) and torn 24 px against itself at the paper/border seam, wide Layer 2 8 px low with its bottom 16 rows cropped, over-border sprites dropped in hi-res L2 mode, and L2 painted over sprites regardless of NR$15. Fixed by making the compositor-wired ULA render the full 320×256 frame (SetNextCompositor switches the geometry; image row = frame row) with every layer routed through frame coordinates, plus a sprite repaint above wide L2 in the S-above-L modes. 320×256 doubles to exactly the browser's 640×512 box. Pinned by TestNextWideFrameLayerAnchoring; NextZXOS Browser (full-frame tilemap) and Celeste (full-frame starfield) verified by headless screenshot. Tyvarian/Crowley gameplay alignment re-verified in the browser 2026-07-15 (r53 bundle) — both correct; see their rows.
2. CLOSED (work items #166/#169, 2026-07-16, r54): TX-1696's install — FOUR real gaps fixed across three sessions, the last one measured on real silicon. Final fix (r54): the hardware-IM2 vectored interrupt mode (NR$C0 bit 0) wired end-to-end — the game's install is caught by the CTC ch0 interrupt with a hardware-generated vector, not the frame INT the earlier geometry analysis chased (see the TX-1696 row for the full mechanism and the silicon measurements). The path there: the #166 story (r49): ULA.BeamPosition divided raw CPU T-states by 228, but the FPGA's cvc counter (NR$1E/$1F, copper WAITs, palette raster stamping) runs on the VIDEO clock (zxnext.vhd:5982-5986, zxula_timing.vhd) — fixed by deriving the beam from the 3.5 MHz-reference timeline against the CPU's own frame origin (z80.FrameOriginRefTstates); pinned by TestBeamPositionTurbo. #169 (r50) then pinned and fixed two more: (a) the 28 MHz wait state was charged on M1 fetches only — the FPGA waits EVERY memory READ cycle (opcode, prefix, operand, data; writes unwaited — zxnext.vhd:3168-3181; pkg/z80 readMem chokepoint); (b) the CTC was modelled (pkg/next/ctc, golden- tested) but never WIRED — channels 0-3 now sit behind ports $183B-$1F3B (decode a(15:11)="00011" + $3B, channel = a(10:8), zxnext.vhd:2690/4064-4093), NR$C5 int-enables write through to the channel control bits and read back live (vhd:4078/6242), and a ZC/TO on an int-enabled channel drives the legacy pulse-mode INT for 32 CPU cycles (im2_peripheral.vhd:186, zxnext.vhd: 2014-2043) via the new z80.ExtIntFunc hook (pkg/next/ ctcblock.go, TestWireCTCPulseInterrupt). SD block reads also gained a spec-faithful variable access time (Nac) before the data token. TX-1696 itself remains blocked on a measured ~1.3- line interrupt-vs-slide geometry shortfall — since hardware- probed (2026-07-15): the real Next matches our instruction timing and INT raster exactly, so timing is exonerated on both sides; see its row for the open launch-path hypothesis.
3. CLOSED (work item #165, 2026-07-14): runtime data-load failures — WOTEF, Aliens Neoplasma and Crowley's panel all unblocked by TWO stacked fixes. (a) fat32.go appendDirent extended a full directory without zeroing the freshly allocated cluster; on the shipped 24.11 image's dirty free space the free-slot scan then wove new entries around stale bytes, detaching VFAT LFN chains from their 8.3 entries — the guest's long-name F_OPENs failed for whichever files landed in an extension cluster. This is the shared machinery under stage-oracle-sd, zxPutFile (browser game-folder staging + project files) and .NEX import, so it was a REAL product bug, but a card-content bug, not core-emulation: any faithful emulator shows the same wreck on such a card. Which title failed which way was luck of directory layout — that's why Saboteur/Baggers sailed through and why the class resisted a single-emulator-cause story. (b) Under it, one real FPGA-conformance bug: the NR$44 palette half-pair latch must reset on NR$40/$41/$43 writes (zxnext.vhd:5376/5382/5395, Axis 9); WOTEF leaves a deliberate dangling half-pair, and without the reset every palette upload landed one byte out of phase (four shades of dark blue). The diagnosis account (SD-command ground truth → Layer 2 bank diff → NR write-stream phase analysis → game-code disassembly → F_OPEN carry) is in work item #165. TX-1696 did NOT move — see its row (its verdict is blocked on staging its 53 MB audio, not on this class).
4. CLOSED (work item #163, 2026-07-14): RETI mistreated as RETN unmapped the esxDOS overlay — 5 titles unblocked (Baggers in Space, Crowley World Tour, NextBASIC Invaders, Saboteur, Bomb Jack all load/render on the SHIPPED 24.11 distro now). Root cause: the Z80 core fired the RETN hook (divMMC automap unmap + Multiface unmap) for RETI and every RETN/RETI mirror, but zxnext.vhd's divmmc_retn_seen comes from the im2_control decoder which matches the EXACT pair ED 45 only (im2_control.vhd:236); RETI feeds the separate reti_seen (IM2 daisy chain). Failure mechanism: a game IM2 interrupt fires while an esxDOS RST $08 file call has the overlay paged in (interrupts are enabled during SD waits); the game ISR ends in EI / RETI ($74CF in Baggers), our RETI unmapped the overlay, and the ISR returned to a divMMC-ROM return address ($1F42) that now showed ROM 3 bytes — collapsing with SP still on the overlay's private $20xx stack. Every previously recorded "SP-in-ROM-window" signature was this wreckage. Pinned by TestRETNHookFiresForExactED45Only; VHDL_CONFORMANCE.md Axis 8. Two #159 readings corrected along the way: (a) the $3D96-$3D9E "DENY(3dxx)" events are FAITHFUL — 24.11's ROM0 has real code at $3D96 (HALT/LD A,$07/CALL $0D6B) that the rom3 gate correctly leaves untrapped when ROM0 is paged (the gate itself verified right, Axis 1); (b) the .nex entry PC IS reached on 24.11 — the wreck happened in-game during the first RST $08 data load, not "before the dot's first instruction". The #164 re-baseline retired the rest of the old class-2 list: WOTEF's dead-HALT and Aliens' sparse-red-lines verdicts were single-file-staging harness artifacts (their runtime data files were never on the card), and TX-1696's two distro-dependent signatures collapsed into the class-1 stall above once its folder was staged.
5. NR $B0/$B1/$B2 extended-keys / MD-pad registers — CLOSED (work item #160), and the original blame was wrong. The registers are now live-composed and VHDL-pinned (VHDL_CONFORMANCE.md Axis 3), but the A/B run showed Warhawk never needed them: its "unstartable" verdict was a triage harness artifact (the menu needs two fire edges, and --press-key couldn't press joystick buttons — it now accepts kfire/kup/kdown/kleft/kright). Warhawk is verified playing headless. Residual, tracked in known-gaps.md: the MD-only pad buttons (X Z Y MODE START A C) have no input source, so pad-default titles (Quantum Storm) still need their keyboard/Kempston control options.
6. RAMS input pump (work item #175) — 1 title, re-classed 2026-07-15. The old "architectural timing (Axis 10), do not chase" verdict is retired: post-r51 the browser plays RAMS Donkey Kong/Galaxian/Pacman, and Frogger's wedge traced to its per-frame input pump never running (static $E000-$E007 virtualized 8255 bytes), not cycle timing. See the RAMS row and

175 for the established state and next steps.

The loader-class A/B method (2026-07-14)

The class-1 finding came from a symmetric-launch harness that both zxplay_go and a reference emulator can boot: stage the game's files plus a fixed-name /zx.nex copy and an auto-running c:/nextzxos/autoexec.bas (10 .nexload /zx.nex, autostart 10) onto an SD image; every cold boot then launches the game with no typed input (autoexec.bas with an autostart line DOES run on headless boots). The 2020/NextZXOS 2.06 FAT16 image boots on both zxplay_go and ZEsarUX in seconds (ZEsarUX reached Baggers' .nex entry PC in 11.6 s from reset); the 24.11 distro image also boots in ZEsarUX but takes ~12 minutes through that loader build's RAM test. Local-only staging tools: _tools/stage-oracle-sd (FAT32 distro images; stages the game folder recursively since #164, so data subfolders land at their relative card paths), mtools mcopy for FAT16 ones, _tools/build-fat16-sd (rebuild a distro tree as FAT16). The card budget stopped being 64 MB at r55: the shipped browser image is now 512 MB / 4 KB clusters, mounted SPARSELY in the wasm (~5 MB resident for the distro; a staged game costs its real bytes), so 100 MB-class payloads (Atic Atac's 111 MB .nex) fit. The old 64 MB/512 B-cluster image remains as tbblue-64mb-backup.mmc and for the ZEsarUX oracle. For custom sizes, _tools/build-base-sd rebuilds the distro (extracted from the shipped image via mcopy -s) onto a BuildFAT32 card of any size (256 MB default; ZEsarUX only boots 64 MB-geometry images though — it sat in its RAM-test loop indefinitely on a 256 MB one). Useful probes: ZX_GO_DIVMMC_PAGE_TRACE=1 (automap grant/DENY events with PC + instruction number) and --trace pc --trace-pc-range $2000-$3FFF (dot-window PC streams for A/B diffing).

Class 2 is why the reference-emulator lockstep harness still matters: those dumps show where each game DIED, not where it DIVERGED. The --next-bisect / --next-lockstep / --next-nrdiff / --next-memdiff drivers exist for exactly this walk-back; they compile under the development-only oracle build tag with a local reference-emulator driver (ZEsarUX ZRCP since work item #162), and the sd-image spec accepts img.mmc!nexload=/zx.nex to have the local side type the launch when an autoexec can't be staged.

If a Next game fails for you, that is expected at this stage — please file it (with what you see vs. real hardware / a stable emulator) so it can be fixed. The Next title scene is small enough that any contributor running public .nex releases from specnext.com or itch.io should add their own rows above as they verify them. No fabrications — only list titles you've actually run, and mark anything unverified as Untested.

Tape format edge cases

The pkg/ula tape pipeline supports both TAP (load + save) and TZX (load + save, blocks 0x10 / 0x11 / 0x14). Edge cases worth verifying manually:

• Speedlock / Alkatraz loaders: turbo blocks with non-standard pilot lengths. Format support is present; correct decoding of every variant is not exhaustively tested.
• Multi-side tapes: side-A side-B "flip the tape" sequences in adventure games (Lords of Midnight Vol 1, etc.). Stop Tape from the menu and load the next side.
• Multi-load games (lots of action games): ensure the fast tape trap doesn't interfere with multi-block loaders; turn it off if so.

Joystick configurations

Verified by the keymap unit tests (pkg/keyboard/keyboard_test.go). Picking the right joystick for a given game is essential:

• Kempston (port 0x1F) — most arcade games of the late 80s
• Sinclair 1 (keys 1-5) — Sinclair Interface 2 left side; games with explicit "Sinclair joystick" support
• Sinclair 2 (keys 6-0) — right side
• Cursor / Protek (keys 5/6/7/8/0) — fewer games; check title documentation

How class evidence works

When a title isn't on the list, you can still predict whether it'll run by figuring out which class it belongs to:

1. Is it pure 48K BASIC? → TestNewBoots48K covers it.
2. Does it use the AY sound chip? → Multi-AY tests cover register semantics; if your title uses AY through standard ports, the sound will play.
3. Does it use IF1 / Microdrive? → TestIF1CATWorks covers the boot path.
4. Does it use DISCiPLE / +D? → TestDISCiPLEBootsIntoGDOS covers the boot path.
5. Does it use +3 disks? → TestPlus3FDCDiskRoundtrip covers disk I/O.
6. Does it depend on cycle-exact contention (e.g. multicolour scanline tricks)? → Open in a hex editor, check whether it does raster waiting via T-state loops; if yes, expect potential wobble.
7. Is it a Next .NEX file? → Banks 0-7 fully supported; 8-111 silently skipped today.

How to add a title

When you load a title and want to record the result:

1. Try the title on the appropriate model (most 48K games stay on 48K; +3 disk games need +3; etc.).
2. Note any peripheral state required (DISCiPLE on/off, joystick selection).
3. Run far enough to confirm the title is functional — not just "shows the loading screen" but "playable".
4. Add a row to the appropriate table:
   • Works for clean runs.
   • Works (caveat) for visible-but-cosmetic issues (audio pitch slightly off, etc.).
   • Known issue for crashes / corruption / freezes — file a GitHub issue first and link it.
5. Submit a PR.

This manifest is the cheapest credibility lever in the project: a title list with verified statuses is more useful than any number of internal benchmarks for telling a prospective user "yes, this works for what you want to do".

Automated compatibility corpus

TestCompatibilityCorpus (in cmd/zxplay_go) turns this manifest into an automated regression guard: it loads a real title headless, drives it to its title/menu screen, and asserts the rendered screen matches a recorded golden hash over a settle window. This catches "a real game silently stopped loading" — the class of bug a mechanism-level unit test passes straight through (e.g. the Renegade-128K tape failure).

Game files are copyrighted and not committed. Point the corpus at a folder holding them (titles whose files are absent skip, so CI stays green):

# Run the corpus against your own game folder
ZX_GO_CORPUS=/path/to/games go test ./cmd/zxplay_go/ -run TestCompatibilityCorpus -v

# Record/refresh a title's golden screen hash (new title, or intended
# rendering change)
ZX_GO_CORPUS_UPDATE=1 ZX_GO_CORPUS=/path/to/games \
  go test ./cmd/zxplay_go/ -run TestCompatibilityCorpus -v

To add a title, append a corpusTitle to the table in corpus_test.go (file, model, load type, key schedule, frame count) and record its golden.

Loader fuzzing

The file parsers are fuzzed (Go native fuzzing) so corrupt or hostile input is rejected, never crashes:

go test ./pkg/snapshot/ -run x -fuzz FuzzLoadBytes -fuzztime 60s   # .sna/.z80/.szx
go test ./pkg/betadisk/ -run x -fuzz FuzzLoadImage -fuzztime 60s   # .trd
go test ./pkg/ula/      -run x -fuzz FuzzLoadTAP  -fuzztime 60s    # .tap (+ FuzzLoadTZX)

The seed corpora run as part of the normal go test ./....