amiga-re-kit (AREK)

Old Amiga games, rebuilt to run in your browser. AREK (Amiga Reverse Engineering Kit) is a free toolkit that lets an AI coding agent take a 1990s Amiga game apart, piece by piece, and build it again as a modern program: the game's own 68000 code from the disk is translated ahead of time to C and WebAssembly, the chipset is a model checked against the vAmiga emulator, and every step is measured against the original. The rebuilt game plays like the original, moves smoothly on today's screens and can show more of the level than the old window did.

Website: https://smikes75.github.io/amiga-re-kit/ (videos, the playable demo, About, FAQ; Czech mirror). Feedback: GitHub Discussions.

Status, October 2026

• Alien Breed II (Team17, 1993): intro, title and levels 1–2 playable at https://smikes75.github.io/arek-play/alienbreed2/ with your own disk images (A500 version, disks 1 and 2 as .adf; the preserved Fairlight dumps are verified, an original retail disk is not yet; AGA is not supported). Original and Enhanced modes, one or two players.
• Superfrog (Team17, 1993): in verification, not playable yet.
• The kit: version 0.9.1 on PyPI, 2477 tests. Extracted from five game rebuilds (S.W.I.V., Turrican II, Superfrog, Alien Breed, Alien Breed II) and made game-agnostic: one Python package (arek), one command line (arek), and an MCP server (arek-mcp) so an AI assistant can drive the same instruments you do.

The method is the point: first a complete, measured description of the original, only then anything else. Nothing here guesses. The decoder refuses instructions it does not model, the walker reports every indirect jump it cannot follow, the packers verify with the checksums the originals carry, and the emulator captures are compared byte for byte.

No game data is included or needed to run the kit. The tests use hand-assembled programs and random buffers. Your disk image and Kickstart ROM stay on your machine, referenced from a git-ignored local.conf.

Install

pip install "amiga-re-kit[mcp,web]"  # from PyPI; or from a checkout: pip install -e ".[mcp,dev]"
python -m pytest                    # 2477 tests: synthetic data + CPU timings measured on Moira
arek --help

Optional: a patched headless vAmiga for anything that runs the original (arek shot, arek bpstate) — see docs/HEADLESS.md. Optional: m68k-elf-objdump for arek xref.

The workflow in commands

arek init myproject && cd myproject    # skeleton + local.conf (edit the paths)

# 1. measure the disk
arek adf info  disk.adf                # size, sha256, boot block, checksum
arek adf map   disk.adf                # entropy picture, one char per sector
arek adf regions disk.adf              # where code / data / packed blocks sit
arek scan      disk.adf                # packer signatures, verified Bytekiller blocks

# 2. unpack what the loader unpacks
arek adf track  disk.adf -n 1 -o trk1.bin
arek adf ls     disk.adf                              # AmigaDOS files, if the disk has a filesystem
arek adf cat    disk.adf -p LEVELS/L1 -o l1.atn       # one file, data blocks verified
arek pp20       file.pp -o file.bin    # PowerPacker 2.0
arek bytekiller trk1.bin --offset 0x200 -o main.bin
arek t2         INTR -o intr.bin       # Turrican II three-stage
arek atn        BLOCK -o out.bin --offset 0x1234   # Atomik (ATN!), block inside an image
arek hunk info  prog && arek hunk load prog --base 0x20000 -o h   # AmigaDOS executables
arek hunk split prog --chip prog2 --base 0xc00000 0x20000 -o h    # records split over two files

# 3. read the code - flow graph, not linear
arek dis    main.bin --base 0x20700 --walk 0x20700     # only reachable code
arek walk   main.bin --base 0x20700 --start 0x20700    # call tree + frontiers
arek walk   main.bin --base 0x20700 --start 0x20700 --inline 21800:until=8000  # data stored after bsr
arek hwscan main.bin --base 0x20700 --roots 0x20700    # the hardware boundary
arek copper ram.bin --base 0x0 --limit 200             # a copper list from a RAM dump
arek bpstate --address 0x21234 --end 20 --out cap/f --screenshot   # RAM, chip registers and the picture
arek render  cap/f                                     # the frame RAM shows, compared with the picture
arek xref   prog.txt --syms syms.json                  # from an objdump listing
arek dis    main.bin --base 0x20700 --dcw              # linear, undecodable words as dc.w
arek dis    main.bin --base 0x20700 --walk 0x21234 --cycles   # 68000 clock count per instruction

# 4. translate and verify
arek recomp  main.bin --base 0x20700 --auto 0x21234 --main -o draw.c
arek recomp  main.bin --base 0x20700 --auto 0x20700 --refusals ref.json -o game.c   # every frontier as JSON
arek recomp  main.bin --base 0x20700 --auto 0x20700 --overlay 41d5c:b000 --dynamic 21350 -o game.c
arek recomp  intro.bin --base 0x41d5c --auto 0x41d5c --lib --prefix in_:41d5c:4cd5c --overlay-module 41d5c -o intro.c
arek recomp  main.bin --base 0x20700 --auto 0x20700 --timing --profile --main -o game.c   # then AREK_PROFILE=p.txt ./game ...
arek profile p.txt --by clocks                         # which routines to rewrite or replace (--extern) first
arek recomp  main.bin --base c00000 --auto c00000 --cover --oob zero --out game.c   # coverage bitmap; reads outside RAM give 0
arek cover   run1.cov run2.cov game.c.cover.json       # what the runs never executed (union of seeds; routines least covered first)
arek fuzz    --seed 3 --frames 30000 --start 320 --out build/in3.txt   # random input: the emulator (--inputs) and the rebuild alike
arek recomp  main.bin --base 0x20700 --auto 0x21234 --timing \
             --jtab 21300:21400:12:4:bra --indirect 21350=21500,21600 --extern 21700=load_file -o game.c
arek bpstate --address 0x21234 --end 20 --out cap/before
arek bpstate --address 0x21300 --end 20 --out cap/after
arek diff    cap/before cap/after --range 0x60000 0x70000
arek shot    build/shots/title 5 10 --at 3 "joystick2 press 1"
arek trace   run build/l1.vtr --arm 196 --end 199 --break 0xc01106 --range 0:80000 c00000:80000
arek trace   show build/l1.vtr --field px=0xc0599e:h  # one row per hit, emulation never stopped
arek trace   run build/l1.vtr --arm 3 --end 60 --break 0xc01106 --inputs l1.txt --reglog regs.bin  # input per frame
arek trace   compare build/orig.vtr build/native.vtr --best-shift 3   # long parity: where the rebuild leaves the original
arek trace   bus build/bus.bin --frame 8600            # who had the chip bus in every slot (buslog patch)
arek trace   run build/s.vtr --arm 3 --end 176 --shots build/f --shot-frames 8600:8619   # 20 frames, one run
arek trace   run build/w.vtr --arm 3 --end 200 --break 0xc01b06 --poke c01b06:c00faa=00000002  # write into the machine, go on
arek selftest inputs                                   # is this VAHeadless frame exact? (synthetic disk)

# 4b. many scenarios at once (arek.parity.suite): state (traces), picture (--shots), sound (--reglog)
# 5. the web page: display contract wb-shell obraz 1.4 (WB-OBRAZ-CRT.md)
arek web copy web/                                     # the reference wb-obraz.js into the game's page (1.5: WebGL2 or 2D presenter, one API)
arek web demo                                          # a page built on it (http://127.0.0.1:8920/demo.html)
arek web test http://localhost:8911/?test=1            # §5.1-5.4b in Chromium on both presenter paths (?gl=0 / ?gl=1) and §5.7 their equality (needs playwright)
arek web seal build/present/engine.wasm --set disk1.adf --label "disk 1, retail" --gzip --out build/present/sealed
arek web seal build/present/engine.wasm --payload build/payload.bin --payload-label "the game files" --out build/present/sealed  # any disk version with the same game data opens it
arek web check build/present                           # a bundle: no game data, derived files sealed, manifest right
arek parity  suite.json                                # scenarios against the original: state, picture, sound per tick
arek web copy web/                                     # also wb-nastaveni.js (the shared Display / Sound menu; never overwrites a file that is not from the kit), wb-zvuk.js (sound contract 1.1), wb-atn.js + wb-content.js (the game's files from the visitor's disks)
arek web payload --atn ADF1:0x57800 ADF2:0x64a00 --out build/payload.bin --content web/content.json   # the payload for --payload and the hashes the page matches
arek web serve build/present --port 8930               # the bundle with the disks of local.conf at /local-disks/diskN.adf (localhost)
arek web serve build/present --isolated                 # ... with the COOP / COEP headers (an engine with shared memory)
arek web strip web/page.js build/present/page.js --drop FULL   # the presentation's variant: lines //@FULL and blocks //@FULL{ ... //@}FULL cut out
arek web longrun http://127.0.0.1:8930/ --minutes 3     # smoothness over a longer play (playwright; the page's globalThis.WBLONGRUN hook)
arek web smooth http://127.0.0.1:8920/smooth-demo.html  # the canon's limits in Chromium and WebKit: dropped frames, camera and object steps, missing passes, key latency, sound under stalls (docs/WB-PLYNULOST.md; --no-interp for an original mode)
#    wb-scene.js (0.9.0): the wider, smoother view composed on the GPU from one record per game frame (clean window, map, objects, sprites, HUD),
#    with a CPU reference for a 0-mismatch check; scene-demo.html shows it (docs/WB-PLYNULOST.md G)
arek docs WB-PLYNULOST                                   # the kit's documents ship with it (arek docs: the list; --path: the file)
arek shots cap/shots/o build/shots/h --align 8          # the pictures of two runs paired by frame, each pair aligned for a screen shake
arek web test http://localhost:8911/?test=1            # ... and §6: the menu and the sound contract, when the page has the hooks

# 6. time inside the frame: the bus model per DMA slot (docs/BUS.md)
arek bus     copy lib/                                 # the model's C sources into a rebuild (arek_bus_glue.h behind the translation's hooks)
arek recomp  main.bin --base c00000 --auto c00000 --timing --bus-table --out game.c   # bus table: words, extra accesses, flags per instruction
arek roots   main.bin --base c00000 --lo c00fa0 --hi c58a8c --json roots.json        # static roots of a whole game (slot tables, pointer tables, stored handlers)
arek recomp  main.bin --base c00000 --auto-file roots.txt --auto-soft --out game.c    # a root into data is dropped, not refused
arek selftest bus                                      # the model against this VAHeadless's bus log (synthetic program, BLTPRI blits)
arek selftest audio                                    # the Paula model (audio DMA slots, output bytes) against this VAHeadless's logs
arek host copy lib && arek host state cap/s0 state0   # the host of a translation (docs/HOST.md) and the state a run starts from
arek host pack state0 state0.bin && arek host engine web/eng --game game.c --l3 f_c13e1c --entry f_c01c72 --run   # the web engine (ASYNCIFY)
arek host engine web/eng --game game.c --l3 f_c13e1c --entry f_c01c72 --thread --run   # ... in its own thread over shared memory (no ASYNCIFY; the page needs COOP/COEP)
arek --version                                         # version + decoder/recompiler hashes

Every command prints what it measured and nothing else. arek audit profile.json produces the JSON inventory + reachability record the method asks for (see examples/profile.example.json).

What is inside

Each module's docstring explains the format or the measurement it implements; docs/METHOD.md explains how they fit together.

MCP: let an assistant hold the instruments

pip install -e ".[mcp]"

Claude Code (.mcp.json in your project, or claude mcp add arek -- arek-mcp):

{"mcpServers": {"arek": {"command": "arek-mcp"}}}

The server exposes 26 tools (kit_info, adf_info, adf_map, adf_ls, adf_file, scan_packed, unpack, hunk_load, disassemble, walk, hwscan, recomp, xref, copper, headless_shot, headless_bpstate, trace_records, diff_captures, ram_at, …). kit_info returns the version and the SHA-256 of the decoder and recompiler; record it with every measurement. All of them take paths on the local machine; the server never fetches anything, never writes outside the paths it is given, and only returns measurements — the assistant sees entropy maps, listings and diffs, not your disk image.

A working session looks like: "map the disk" → "scan for packed blocks" → "unpack the block at 0x1f40 and walk it from its entry" → "which of these routines touch hardware?" → "recompile 0x21234 and compare its RAM writes with a capture of the original". Every answer is backed by a tool result.

Legal

The kit is MIT (see LICENSE). It ships no game data, no ROM, and no game-specific knowledge — the "engine without data" model: you supply the image you own. The vAmiga patches are modifications of MPL-2.0 sources and are published as required; see THIRD-PARTY.md.

Code comments inside the transplanted modules are partly in Czech (the projects' working language); public docstrings, the CLI and the docs are English.