ZX Play documentation

ZX Play is three things built on one emulation core:

All three come out of one repository, stever/zxcode.

Which part do you want?

I want to write a Spectrum or Next program without installing anything. Start with Using the IDE, then pick a toolchain from Languages and toolchains.

I am developing a game locally and want the emulator in my build loop. Automating the emulator is the page to read: headless runs, scripted breakpoints, screenshots, and regression tests that fail your build when the game breaks.

I use DeZog / ZEsarUX / CSpect and want to know how zxplay_go fits. Read DeZog, ZEsarUX and CSpect first. The short version: zxplay_go speaks its own line-oriented protocol, DeZog cannot attach to it, and the page explains what to use instead and where each tool wins.

I want to know whether my game will run correctly. Game compatibility lists tested titles and their status; the conformance dashboard shows the emulator's live standing against its oracles and the external Next test suites; and known gaps records the deliberate differences from real hardware.

I want to change the emulator. Read the architecture docs before anything else, then Contributing.

Honest status

The classic line — ZX80, ZX81, Spectrum 48K/128K/+2/+2A/+3, Pentagon, SAM Coupé — is mature: cycle-accurate, contended, and stable enough for day-to-day work.

The Spectrum Next boots real NextZXOS through the authentic FPGA chain and its individual hardware blocks are extensively tested against the FPGA VHDL, but running arbitrary .nex games is the newest and least-finished area. Some titles are playable, several render with bugs, and many are unverified. If a Next game misbehaves, that is expected at this stage — open an issue, because a comparison against real hardware is exactly what moves it forward.

Start here

What this project publishes, and which part you want.

OverviewThe player, the IDE and the emulator — and which one to reach for.

Writing code — code.zxplay.org

The browser IDE: projects, eleven toolchains, and a source-line debugger that runs against the real emulator.

Using the IDEProjects, files, compiling, running, sharing, and the asset editors.Languages and toolchainsAll eleven languages, what each targets, and what each supports in the debugger.Debugging in the browserSource-line breakpoints, the console command language, and how each language maps lines to the machine.

Playing — zxplay.org

The player site, and the URL options that let you link straight to a program.

The playerLoading programs, the URL parameters, and how Next games are distributed.

Game development with the emulator

zxplay_go on your own machine: run it, script it, and use it as a test harness for the game you are building.

zxplay_goWhat the emulator is, what it supports, and how to install or build it.Automating the emulatorHeadless runs, scripted debugging, screenshots and regression tests for your game.DeZog, ZEsarUX and CSpectWhat zxplay_go's debug protocol is and is not — and how to work with the tools you already use.User manualDay-to-day use: machines, loading, saving, peripherals, sound, shortcuts.Debugger referenceThe complete visual, telnet and headless debugger reference.The Spectrum NextROM install, SD-card setup, boot modes, .nex loading, licensing.Debugging real hardwareDriving a real Spectrum Next over serial with DZRP — the silicon ground truth.Game compatibilityThe tested-title manifest, per-title status and known issues.Compared to other emulatorszxplay_go against CSpect, ZEsarUX and MAME, criterion by criterion.ZX80 and ZX81The CPU-generated-display machines in detail.SAM CoupéMGT's 1989 Z80B machine: modes, sound, disk, status.

Emulator internals

Developer documentation for the emulation core itself — read this before changing it.

Architecture docsThe index of the architecture set, and the rule for keeping it current.System overviewHow the machine is assembled and how a frame is executed.Code organisationWhere each subsystem lives and what depends on what.Emulation patternsThe recurring implementation idioms: timing, hooks, event scheduling.Chip emulationPer-chip notes: Z80, ULA, AY, FDC, WD179x and the rest.Next FPGA internalsThe Next's custom hardware as emulated, cited against the core's VHDL.FrontendsThe GUI, headless harness and wasm builds over one core.Known gapsThe register of deliberate differences from real hardware.ContributingHow to work on the emulator, and what a change is expected to carry.

Conformance

Generated on every publish from the manifest and the actual test run.

Conformance dashboardLive status of every conformance check against its oracle.VHDL conformance matrixOur emulation against the Next's FPGA source, axis by axis.z80test inventoryraxoft/z80test — per-test status.ZXSpectrumNextTests (MrKWatkins)External Next test suite — per-test status.ZXSpectrumNextTests (327)External Next test suite — per-test status.