Getting started

Emu198x is 30 emulators, one binary per machine. The thing that catches people first: there is no emu198x command. You run the machine — emu198x-spectrum, emu198x-c64, emu198x-nes — and each one is its own download.

One binary is one machine

A binary carries the hardware and nothing else. The binary called emu198x-spectrum is a ZX Spectrum: its Z80, its ULA, its tape port, its timing. There is no Spectrum ROM inside it and no software, and it will not run a C64 disk. Point it at firmware and media you supply, and it boots.

Each binary starts in one of three modes.

• A window. The default, and what a bare start gives you on 20 of the 30 machines: run the binary and it boots into a native window. The other 10 want media first — the Atari, Sega and Nintendo consoles, the Dragon 32 and the BBC Micro — and starting one without it exits with an error naming what is missing.
• A headless run. Either --headless or --script. The machine runs with no window and follows a list of steps: run frames, load media, press keys, read or patch memory, save a screenshot or an audio capture.
• An MCP server. --mcp. The same controls over stdio, plus per-chip queries, for an agent or another tool to drive.

All 30 machines have all three modes. What they do not share is their flags. The Spectrum takes --rom and --tape, the Atari 2600 takes --cart, the MSX takes --bios, the C64 takes --rom-dir. Run any binary with --help and it prints that machine's own set, along with its keyboard controls.

Binary names are shortened, and they do not always match the name a machine goes by here: the NES ships from emu198x-nes, the MSX1 from emu198x-msx, the Oric from emu198x-oric-atmos. Every machine page in the system matrix names the binary that machine ships from.

What works today

Each release publishes an archive per machine per desktop platform — macOS on Apple Silicon and Intel, Linux x86_64, Windows x86_64. Start at the downloads page, which links the current release. Building from a source checkout gets you the same binaries and needs a current stable Rust toolchain.

What differs between machines is boot depth: how far real firmware and real software get. Some boot to a prompt and load from tape; some paint nothing until you give them media. The system matrix carries a boot capture for each machine that has one, and the accuracy progress page carries the evidence behind it.

Running a machine

Take the ZX Spectrum. From an unpacked release archive:

tar xf emu198x-spectrum-aarch64-apple-darwin.tar.gz
cd emu198x-spectrum-aarch64-apple-darwin
./emu198x-spectrum --rom /path/to/your/48.rom

The same run from a source checkout:

git clone https://github.com/emu198x/emu198x.git
cd emu198x
cargo run --release -p emu198x-spectrum -- --rom /path/to/your/48.rom

Both open a Spectrum window sitting on the copyright line, which is where a 48K machine starts with nothing loaded. To load something, hand it a tape and let the machine's own ROM loader run:

./emu198x-spectrum --tape /path/to/your/game.tap --autoload-tape

The --autoload-tape flag waits for the boot to finish, types LOAD "", and starts the tape motor. That is the real loading path rather than an instant-load trap, so the border stripes you get are the ones the hardware produced.

Where the firmware goes

Passing --rom on every run wears thin. Each binary also looks under ~/.emu198x/roms/ for the firmware its machine needs, in a directory named for that machine:

mkdir -p ~/.emu198x/roms/sinclair-zx-spectrum-48k
cp /path/to/your/48.rom ~/.emu198x/roms/sinclair-zx-spectrum-48k/48.rom
./emu198x-spectrum

Nothing here has to be guessed. Start a binary before its firmware is in place and the error names the exact file it went looking for:

error: ROM not found at /Users/you/.emu198x/roms/sinclair-zx-spectrum-48k/48.rom

What you need that we cannot give you

Firmware and software. Emu198x ships no ROMs, no BIOS images, and no disks, tapes or cartridges; the downloads page sets out the position on that. What you have to find depends on the machine: a Spectrum, an MSX or a PET needs its firmware before it will boot at all, while a NES or a Master System has no system ROM and starts from the cartridge image you supply.

What does not work yet

• No unified command. A wrapper that reads a file's type and starts the machine that matches is a design, not a release. You pick the binary yourself.
• No launcher screen. Starting a binary boots its machine immediately, and every option is a command-line flag. Per-machine launchers with model, memory and expansion pickers are planned and not built.
• No browser build. Releases target macOS, Linux and Windows. A WASM build is intended and does not exist.
• The windows are verifier shells. They exist to check the hardware against real firmware and real software, and they show it: file handling, input configuration and on-screen media controls are thin or absent.
• Boot depth is uneven. A machine having a binary is not a promise that it reaches a usable prompt with your firmware. The Sord M5, for one, paints a blank screen from its own monitor ROM and needs a cartridge before there is anything to see. Check the machine you care about on the system matrix before assuming.