Donkey Kong

Embedding

Donkey Kong is Nintendo's 1981 arcade machine: a Zilog Z80 at 3.072 MHz driving a 256×224 raster, rotated 90° in the upright cabinet. This build runs the original program ROMs on DrGoldfire/Z80.js (MIT), an instruction-at-a-time Z80 interpreter, wrapped in a hand-written model of the Donkey Kong board (memory map, tile/sprite video and input latches). The graphics-ROM decode, colour-PROM palette and renderer are ported from the galagino project.

Boot. The four 4 KB program ROMs are loaded into 0x0000–0x3FFF and the Z80 starts at 0x0000, dropping straight into the attract-mode demo:

var dk = new DKong();      // decodes gfx ROMs + PROMs, wires the Z80
dk.reset();                  // PC = 0x0000 -> attract mode

The machine object. DKong exposes the whole cabinet as ordinary methods, so the host page can render, step and inject input:

Video. Each animation frame the loop runs one field's worth of Z80 cycles, pulses the NMI, then re-renders: the background is a 32×32 tilemap of 8×8 characters (video RAM at 0x7400), and the sprites are 16×16, four bytes each, taken from the block the game DMA-copies to 0x7000. Colours come from the two palette PROMs and the character/sprite colour-map PROM, banked by the 0x7D86/0x7D87 latches.

Debugger integration

The debugger drives a host-owned run loop: because the Z80 interpreter runs one instruction at a time in JavaScript, the loop can pause, single-step and check breakpoints between any two instructions, with no changes to the CPU core needed.

window.EMU_BOOT.transport exposes the controls the shared debugger calls:

• pause / resume / isPaused - stop or restart the requestAnimationFrame loop.
• stepInsn(n) - call the core's stepInsn() exactly n times and redraw, so a single step advances the PC by one Z80 instruction.
• step(n) - advance n whole 60 Hz fields (each with its NMI).
• breakpoints - a Set of PC values. When it is non-empty the loop reads the Z80's PC (via getState()) before each instruction and pauses before executing an address in the set; when empty it runs a full field at speed, so an idle debugger costs nothing.
• watchpoints - the Z80 core's memory-write callback is wrapped, so a write to a watched RAM address sets a flag that pauses the loop after that instruction.

The plug-in (donkeykong-debug.js) reads these hooks and calls EmuKit.defineMachine with the full Z80 register file (AF/BC/DE/HL and their bytes, the alternate set via IX/IY, SP, PC, I, R and the S Z H P/V N C flags), each read live from getState() and written back through setState(). It reuses the shared z80 disassembler (/debugger/src/cpus/z80.js) for the hex/disasm views over the 64 KB bus, the 16 KB program ROM, the tile RAM (rendered as tiles) and the sprite RAM.

Architecture

The Donkey Kong board is a single Zilog Z80 at 3.072 MHz with 16 KB of program ROM, 4 KB of work/video RAM and Nintendo's tile-and-sprite video, all modelled here as plain JavaScript hanging off DKong:

• CPU - a Z80 interpreter. 0x0000–0x3FFF is program ROM; 0x6000–0x6FFF and 0x7000–0x77FF are RAM (work RAM, sprite RAM at 0x6900, tile RAM at 0x7400).
• Video - a 32×32 background tilemap of 8×8 2bpp characters, plus 16×16 sprites with per-object X/Y flip. Two 256-byte palette PROMs give the 8-bit-per-channel colours and a third PROM maps tile/sprite pixels to palette groups; a two-bit bank (0x7D86/0x7D87) selects one of four colour tables.
• DMA - writing 0x7D85 copies 384 bytes of sprite attributes from 0x6900 to 0x7000, exactly as the board's DMA does each field.
• Input - the player-one joystick and jump button are read on 0x7C00; coin and start on 0x7D00; the DIP switches on 0x7D80.
• Interrupt - a single NMI per field at vertical blank, gated by the 0x7D84 mask latch, is the only timing the game depends on.
• Sound - the real cabinet uses an i8035 with sample ROMs; this build has no audio, so the sound-trigger writes are ignored.