Donkey Kong (Atari 2600) — ROM port

Coleco's Donkey Kong for the Atari 2600 (1982, programmed by Garry Kitchen), translated into JavaScript instruction for instruction from the original cartridge and checked against the real ROM frame by frame. Play it at https://plicerin.github.io/donkeykong-rom-port/.

How it works

The translated program runs on a model of the 2600's TIA (picture, collisions, sound registers) and RIOT (RAM, timer, joystick and console switches):

• src/dkRecomp.mjs: the cartridge's code, one case per instruction at its ROM address, with the disassembly's labels and comments and each instruction's cycle count. Generated by tools/recompile.mjs.
• src/dkRomData.mjs: the cartridge's tables and graphics, i.e. the bytes no instruction occupies plus the few code bytes the game also reads as data. The cartridge image itself is not included.
• src/vcsBus.mjs, src/tia.mjs, src/cpu6502.mjs: RAM, RIOT timer and switches, the TIA, and the 6502 registers and arithmetic. The game and the dev oracle share them.
• src/dkMachine.mjs: the translated code on the bus, one frame per runFrame().
• src/dkPlayer.mjs: canvas, keyboard, gamepad, touch buttons and the TIA sound worklet (src/tiaSound.worklet.js).
• index.html: the site, with the game embedded. game.html: the game on its own.
• img/: the poster, sprite plates and icons, rendered from the game by tools/gen-images.mjs.

Run locally

python -m http.server 5500 --bind 127.0.0.1

Then open http://127.0.0.1:5500/. ES modules need a server; opening the file directly will not work.

Controls: arrows or WASD walk and climb, Space or Z jumps, Enter is Game Reset (then wait for the tune and press jump), P pauses, M mutes. Gamepads work too (Start = Game Reset, Back = pause), and phones get touch buttons.

Verify against the ROM

Needs the cartridge at rom/donkey_kong.a26 (MD5 36b20c427975760cb9cf4a47e41369e4, git-ignored, never committed) and, for rebuilding, DASM 2.20.17 with its vcs.h in tools/dasm/.

powershell -File tools/build-rom.ps1          # reassemble the disassembly; must match the cartridge's MD5
node tools/recompile.mjs                      # regenerate src/dkRecomp.mjs and src/dkRomData.mjs
node tools/verify-recomp.mjs 20000 1 cover    # translation vs the real ROM, frame by frame
node tools/verify-tia.mjs 3000 1              # fast TIA model vs the per-pixel reference

verify-recomp runs the real cartridge on a 6502 interpreter (tools/atari/) next to the translation with identical inputs, and requires identical CPU registers, cycle counts, RAM, TIA write logs and pictures after every frame. With cover, identical RAM pokes in both machines force level clears, hand Mario the hammer and leave long idle spells, so both screens and attract mode get played. 100,000 frames over five seeds show no differences.

tools/build-rom.ps1 assembles Dennis Debro's disassembly with two adjustments for current DASM, neither of which changes a byte: the two ldy #<A-B+C lines take the low byte explicitly, and the TIA read registers sit at $30 as in the vcs.h the disassembly was written against. DASM is run in %TEMP% because Windows' Controlled Folder Access can stop it writing under Documents.

The TIA model matches reference screenshots of both screens pixel for pixel in everything that does not depend on the moment of play (girders, ladders, Donkey Kong, Pauline, Mario's start). Getting there took three corrections, all as Stella models the hardware: frames are counted from the start of the VSYNC line, the playfield takes its bit at the start of each 4-pixel block with PF writes landing 2 color clocks late, and the RIOT timer decrements on the cycle after it is written.

The earlier port

archive_old_port/ holds the previous hand-written port (game.html with geometry measured from screenshots, its bot and its analysis scripts) for reference.

Credits

Donkey Kong is © Nintendo; the Atari 2600 version is © 1982 Coleco, programmed by Garry Kitchen. This is an unofficial preservation project, not affiliated with Nintendo or Coleco. donkey_kong_2600.asm is Dennis Debro's disassembly. Colors are from Stella's NTSC palette; the sound worklet follows Ron Fries' TIASound.