eighty-three

A ZX81 emulator for macOS, Linux and Windows, with ZXpand+ support, a debugger and an MCP server.

The emulation core is based on EightyOne by Michael D Wynne, rebuilt around C++17 + SDL2 + CMake with a new front end.

What it does:

• Video is generated per CPU cycle, the way the ZX81 itself does it, so SLOW and FAST modes and WRX hi-res work.
• Sound: the beeper and the AY-3-8910 (ZonX / ZXpand+).
• Keys are mapped by physical position, so the OS keyboard layout does not matter. Any key can be rebound.
• ZXpand+: the SD card is a folder on your disk, and the ZXpand Commander shell boots from the menu.
• Loads .P, .P81, .Z81, .O, .80, .81 by drag-and-drop or from File > Open, and saves .P, .P81, .T81 or a .Z81 snapshot. .P files go through the ROM's own LOAD routine, so programs that auto-start do.
• Debugger: disassembly, registers, memory and stack editing, breakpoints (execution, conditional, and watchpoints on memory or ports), an inline assembler, a BASIC listing view.
• e83_mcp, a headless ZX81 with 66 tools over the Model Context Protocol, in every release package.

Install

Prebuilt packages are on the releases page.

macOS 11 and later on Apple Silicon, macOS 10.15 and later on Intel. One universal app covers both. Unpack and drag eighty-three.app into Applications; the bundle carries its own SDL2, the ROMs and the guide. It is signed ad-hoc and not notarised, so the first launch of a downloaded copy is refused. On macOS 15 and later: double-click it, dismiss the warning, then System Settings > Privacy & Security > Open Anyway. On macOS 14 and earlier: right-click the app > Open > Open.

Windows. Unpack the zip anywhere and run eighty-three.exe. SDL2 and the Microsoft C++ runtime are in the folder. The executable is unsigned, so SmartScreen shows "Windows protected your PC" the first time: More info > Run anyway. Keep the folder together, because the emulator reads ROMs\ and USER_GUIDE.md from next to the exe.

Linux. Unpack the tarball and run ./install.sh, which installs into ~/.local without root, or run ./eighty-three from the unpacked folder. The prebuilt binary links your system's SDL2 and its file name says which distribution it was built on. If it does not start on yours, build from source:

git clone https://github.com/alffcpu/eighty-three.git
cd eighty-three
./scripts/build.sh --deps    # installs what is missing, then builds
./build/eighty-three

build.sh recognises pacman, apt, dnf, zypper, apk, xbps, emerge and brew, and checks dependencies by capability rather than by package name, so a hand-built SDL2 counts. Without --deps it installs nothing: it prints the exact command for your system and stops.

First-launch details: USER_GUIDE.md, Getting Started > Installing.

Quick start

The emulator boots to the ZX81 BASIC prompt, a blinking K cursor.

• Load. Drag a .P file onto the window, or File > Open.
• Type. P types PRINT at the K cursor, as on a real ZX81. Symbols come from the ZX81 SHIFT layer. The on-screen keyboard, with legends read from the ROM, is under File > Settings > Input > Remap ZX81 keyboard.
• ZXpand+. Put .p files into Documents/eighty-three/ZXpand_SD_Card/ and browse them with Machine > ZXpand+ menu.
• Settings. File > Settings covers the ROM edition, RAM size, WRX hi-res, ZXpand+, sound, display scale and theme.
• Help. Info > Help opens the user guide inside the emulator.

USER_GUIDE.md covers the keyboard, file formats, settings, sound, the debugger and the MCP server.

Screenshots

MCP server

e83_mcp speaks the Model Context Protocol over stdio and exposes 66 tools: registers, memory, single-stepping, breakpoints, disassembly, an inline assembler, the BASIC listing, the keyboard, the ZXpand SD card, and the screen both as a PNG and as text. It also measures: coverage, an instruction trace, a T-state profiler that separates the program's own work from the time the CPU spends drawing the picture, sound capture, and recording the screen to a GIF. Load a symbol file and every address argument takes a label name.

It is its own headless ZX81, not a remote control for the emulator window. The agent gets a machine of its own to boot, load programs into and inspect. The GUI can run at the same time; the two are independent.

The server ships in every release package next to the emulator. Its single argument is the folder containing ROMs/: the unpacked package folder on Linux and Windows, and eighty-three.app/Contents/Resources/ on macOS, where the ROMs travel inside the bundle.

{
  "mcpServers": {
    "eighty-three-zx81": {
      "command": "/path/to/eighty-three-1.1-linux-x86_64/e83_mcp",
      "args": ["/path/to/eighty-three-1.1-linux-x86_64/"]
    }
  }
}

Clients with a command line can add it in one line, for example claude mcp add eighty-three-zx81 -- ./build/e83_mcp ./build/. The repository also carries a .mcp.json for clients that read that convention.

Protocol details, the full tool table and the argument formats: USER_GUIDE.md, MCP Server for AI Agents.

How it is built and tested

EightyOne's emulation core is ported almost verbatim and lives under core/; everything around it - the SDL2 window, the menus, the debugger, the settings, the MCP server - is this project's own and lives under src/ and tools/. docs/ARCHITECTURE.md has the map, what the Borland Windows application did that had to be rebuilt, and the traps in the core that cost a day each.

tests/ is a headless regression suite that ctest runs: the debug core, the assembler and disassembler, the save formats, the BASIC editor, sound, the ZXpand SD card, the keyboard map, the character set, the menu model, and the MCP server driven over JSON-RPC as a client would. ./scripts/build.sh --test runs all of it.

python3 scripts/coverage.py reports how much of the project's own code that suite executes, per file, weakest first, and fails below a floor:

file                              lines   branch   region    funcs
tools/e83dbg.cpp                   0.0%     0.0%     0.0%     0.0%
...
e83_zx81_charset.cpp             100.0%    96.1%   100.0%   100.0%
TOTAL                             81.8%    57.4%    68.1%    72.9%   (4723/5773 lines)

That is one run on one commit; the command is the claim rather than the number.

The user interface is not in it: testing an ImGui window means building a frame, driving a renderer and comparing pixels, and there is no harness for that here. The files left out on that ground are listed at the top of the script, beside the number, rather than left for a reader to find. core/ is out too - it is EightyOne's emulator, ported almost verbatim, and the suite drives it through the machine rather than by calling into it.

Everything else is in, including the four programs nothing runs, at zero. A weakest-first table whose weakest entries are hidden is not worth printing.

Build from source

./scripts/build.sh --deps --test   # macOS/Linux: install what is missing,
                                   # build, run the test suite

scripts\build.cmd --test   :: Windows: Visual Studio 2022 + vcpkg

Details, CMake options and how releases are packaged: BUILDING.md.

ROMs

The ZX81 ROM images and the ZXpand+ overlay are included, so the emulator runs out of the box. They are third-party firmware, not covered by this project's licence, and each keeps its own copyright. The conditions they are distributed under are in roms/NOTICE.txt.

Licence

GPL-2.0-or-later, inherited from EightyOne (© Michael D Wynne). Full text: COPYING.

Bundled third-party components keep their own licences, listed in THIRD_PARTY_LICENSES.md: the Fuse Z80 core, Pasmo, Dear ImGui, nlohmann/json, JetBrains Mono, the ROM images and the ZXpand Commander menu program.

Credits

• Michael D Wynne, EightyOne, whose emulation core this is built on.
• Philip Kendall and the Fuse team, the Z80 core.
• Charlie Robson, ZXpand+ and the ZXpand Commander shell.
• Julián Albo, Pasmo, the Z80 assembler used by the inline assembler.
• Omar Cornut, Dear ImGui.