Static ZX Spectrum → .NET recompiler. Feed it a .z80 snapshot, get a runnable .NET game and readable C#.
ZX2ILRecomp reads a ZX Spectrum snapshot, disassembles the Z80 program, and
translates every reachable instruction into equivalent C#. That C# is compiled
by the .NET SDK into a normal Windows game that renders through WinForms and
plays through winmm.
There is no Z80 interpreter in the hot path. Control flow becomes real C#
methods — one per basic block of original code — and a three-level dispatch
table (pc >> 8 → page → address) walks them. An interpreter fallback still
exists, but only for addresses the static analysis could not prove reachable —
and it writes them to dynamic_targets.log so the next lift can inline them.
A 48K game lifts, compiles and links in about ten seconds.
game.z80
│
├─► .z80 / .sna / .szx / .tap / .tzx loader ─► registers, banks, ROM
│
├─► recursive descent + linear sweep ────────► instructions, labels, edges
│ (decoded through real paging)
│
├─► LifterZ80 ───────────────────────────────► C#: CPU, ULA, AY, keyboard
│
└─► dotnet publish ──────────────────────────► game.exe + game.dll (+ icon)
git clone https://github.com/dpteam/ZX2ILRecomp.git
cd ZX2ILRecomp
dotnet build
# Just run it: the window opens.
dotnet run
# Prove the whole toolchain works. No game files needed.
dotnet run -- --selftest
# Or stay on the command line.
dotnet run -- "Manic Miner.z80" --full-exeOne pipeline, three front ends. Pick whichever fits the job.
| Interface | Launch | Best for |
|---|---|---|
| GUI | ZX2ILRecomp (or --gui) |
picking a folder, watching a batch, reading the log |
| TUI | ZX2ILRecomp on a console without a desktop |
servers, SSH, remote sessions |
| CLI | ZX2ILRecomp <snapshot> [options] |
scripts, CI, one-off lifts |
With no arguments the tool opens the window. Explicit arguments always skip the UI and behave exactly like the CLI, so scripts and CI never block on a prompt.
| Format | What is recovered |
|---|---|
.z80 |
full register file, 48K and 128K (v1, v2, v3), compressed and raw blocks |
.sna |
full register file, 48K, plus the 128K extension when present |
.szx |
registers, RAM pages, ROM pages, paging latches |
.tap |
memory blocks and load address (a tape carries no registers) |
.tzx |
memory blocks and load address, all standard/turbo data blocks |
Models: 48K and 128K (including +2 paging through port 0x7FFD).
The model is auto-detected from the container and can be forced with
--model 48 or --model 128.
- CPU — full Z80 including
IX/IY,CB/ED/DD/FDpages, block moves,DAA,NEG,RRD/RLD, interrupt modes 0/1/2. - ULA — 256×192 picture inside a border, correct bitmap interleaving, bright and flash attributes, both screens on 128K.
- AY-3-8912 — three tone channels mixed into the beeper stream.
- Keyboard — the real 8×5 matrix, so
IN/OUTpolls work as written. - Window — 2× nearest-neighbour blit,
F1diagnostics overlay,F2sound,Escto quit. - Headless mode —
Game.exe --headless 600runs 600 frames with no window and prints a summary. This is what CI uses. - Icon self-capture —
Game.exe --capture-icon 5screenshots itself into<name>.icon.ico, which the next lift picks up automatically.
<out>/<Name>/
<Name>.exe double-click to play (default packaging)
<Name>.dll lifted game assembly
<Name>.icon.ico icon captured from the running game
src/Game.generated.cs generated C#, readable and annotated
analysis.txt model, entry point, coverage, full disassembly
dynamic_targets.txt addresses to force into the next lift
| Flag | Result | Needs .NET installed |
|---|---|---|
--exe (default) |
Game.exe + Game.dll + deps |
yes |
--dll |
Game.dll only, run with dotnet Game.dll |
yes |
--full-exe |
single self-contained .exe (~70 MB) |
no |
Aliases for --full-exe: --self-contained, --standalone.
- Load. The container is parsed into registers, ROM images and eight 16K RAM banks — a bank-oriented model, because that is the only representation that survives 128K paging.
- Fix up. The model is applied first, then the ROM is located on disk,
then the entry-point heuristics run. Order matters: a real snapshot may be
paused inside a ROM call, and forcing
0x8000there would break it. For a tape, the entry point comes fromRANDOMIZE USR nin its BASIC loader. - Analyse. Recursive descent from the entry point, the RST vectors and the IM 1 handler, followed by a linear sweep over the rest of RAM. The sweep is what turns jump-table-driven games from "half interpreted" into fully static.
- Prune. Only code that is actually reachable earns a method; swept data tables stay with the interpreter.
- Emit. One method per basic block, plus a runtime carrying CPU helpers, the memory decoder, the ULA, the AY and the window.
- Package.
dotnet publishproduces the apphost and embeds the icon.
Full detail: docs/ARCHITECTURE.md.
Not a slogan — the whole point. The project references zero NuGet packages:
- no Roslyn → the .NET SDK's own
dotnet publishcompiles the generated C# - no test framework → a 120-line assertion harness in
tests/ - no audio library →
winmmwaveOutP/Invoke - no imaging library → GDI+ and a hand-written ICO writer
- no UI framework → stock WinForms controls
That keeps the build reproducible, the download small, and the supply chain empty.
dotnet run --project tests/ZX2ILRecomp.Tests # unit tests
dotnet run -- --selftest --frames 60 --keep # lift + package + run--selftest builds a synthetic snapshot for every supported container, lifts
it, packages it, and executes the result headlessly, checking that it
reaches the frame budget without trapping and that the rendered frame has a
border, paper and ink. A loader regression, a broken opcode table or a runtime
that deadlocks on HALT all fail there.
To see what the tool does with real games:
# put your snapshots in testdata/, then:
powershell -File tools/demo.ps1Every snapshot is lifted into bin/recompiled/<name>/, run headlessly and
screenshotted. The output is git-ignored: these are builds of copyrighted games,
and only the script is committed.
bin/recompiled/Manic Miner/
Manic Miner.exe
src/Game.generated.cs
analysis.txt
frame.png <- the screenshot the headless run took
demo.txt <- what that run reported
lift.log <- the lifter's own output
A game counts as playable only when its rendered frame contains more than two colours. That is deliberate: a lift can run for hundreds of frames without trapping and still draw nothing, and a loader heuristic can be wrong in both directions. The picture cannot.
- Windows 10 or later
- .NET 10 SDK (to lift) and the .NET 10 desktop runtime (to play
--exebuilds)
| Document | Contents |
|---|---|
| docs/ARCHITECTURE.md | every stage of a lift, in order |
| docs/SNAPSHOTS.md | container formats, bank mapping, ROM handling |
| docs/RUNTIME.md | what the generated game actually contains |
| docs/TROUBLESHOOTING.md | games that hang, render wrong, or trap |
| ROADMAP.md | what is next: disk images, audio-in, ZX80/ZX81 |
See CONTRIBUTING.md. In short: dotnet build -warnaserror
must be clean, the tests and the self-test must pass, and no package references
may be added.
GPL-3.0. See LICENSE.
