A ZX Spectrum emulator & programming environment for the browser.
The published documentation site is at https://stever.dev/zxcode/ — how to use code.zxplay.org and its eleven toolchains, how to use zxplay.org, how to automate the zxplay_go emulator when developing a game locally, the emulator's own manuals and architecture docs, and the live conformance dashboard.
It is generated from markdown in this repository; the site map and the conventions for adding to it are in docs/README.md.
Minimum pre-requisites:
- Docker with Docker Compose (https://docs.docker.com/get-docker/)
- Caddy web server (https://caddyserver.com/) caddy command installed and in PATH
# Create .env files from example .env-dist files
cp .env-dist .env
cp apps/proxy/.env-dist apps/proxy/.env
# Start up containers
docker compose up --build -d
# Wait for the GraphQL api to start
bash -c 'while [[ "$(curl -s -o /dev/null -w ''%{http_code}'' localhost:4000/healthz)" != "200" ]]; do sleep 5; done'npm install
npm run devLaunch the URL for the proxied web server on port 8080 (http://localhost:8080).
Remove docker compose deployment to start over:
docker compose stop && docker compose rm -f
docker volume rm zxcoder_pg_dataRefresh and restart docker-compose deployment:
docker compose pull
docker compose up --build -d| Port | Purpose | Protocol |
|---|---|---|
| 4000 | GraphQL api | HTTP |
| 5000 | Auth | HTTP |
| 8000 | React | HTTP |
| 8080 | Proxy | HTTP |
The emulator core is zxplay_go — this repository's fork of zx_go by Conor Armstrong — a ZX Spectrum emulator written in Go — compiled to WebAssembly. It is vendored (with the wasm-port changes applied in-tree) at packages/emulator-core, and consumed through the JSSpeccy(container, opts) handle in packages/emulator, whose UI chrome and keyboard handling descend from JSSpeccy3 (GPLv3) — the engine this project used before the zxplay_go migration.
Engine highlights:
- The websites run the 48K and 128K, booting from ROMs embedded in zx.wasm.
They do not support the ZX Spectrum Next and serve or proxy no NextZXOS
content. The engine's Next support (NextZXOS boot, .nex loading, the
IDE's TAP-to-Next translation in packages/emulator/src/zxgo/tapToNext.js)
stays in the code behind
opts.nextEnabled, which neither app sets: Next programs are refused with "ZX Spectrum Next programs are not supported." Local staging tooling and policy: packages/emulator-core/LICENSES.md. - Audio streams from the core into an AudioWorklet (served as /dist/zx-feeder.worklet.js: CSP script-src 'self' compatible); the machine is paced off the audio clock, so producer and consumer cannot drift.
- Every machine and video mode composites into a fixed 640x512 canvas.
This software uses code from, or is based on the work of, the following open source projects:
- zxplay_go, the emulator core — this repository's fork of zxplay_go by Conor Armstrong. Upstream is licensed under terms of the MIT License; the fork's modifications are licensed under terms of the GPL version 3.
- JSSpeccy3 & JSSpeccy3-mobile. These are licensed under terms of the GPL version 3.
- Pasmo by Julián Albo García, alias "NotFound". Licensed under terms of the GPL version 3.
- Boriel ZX BASIC by Jose Rodriguez. Licensed under terms of the GPL version 3.
- zmakebas by Russell Marks. This tool is public domain.
- txt2bas by Remy Sharp, the in-browser Sinclair BASIC tokeniser. Licensed under terms of the MIT License.
- zx-tools by Remy Sharp. The IDE's sprite, palette and tile map editors are original code modelled on his zx-tools suite: the .spr/.pal/.map file handling, drawing tools and key bindings follow it. zx-tools is licensed under terms of the MIT License.
- 8bitworkshop by Steven Hugg. Licensed under terms of the GPL version 3.