VIC-20 Emulator (mwenge)

Embedding

mwenge's VIC-20 is a set of plain-global JavaScript modules (no bundler). Vendor them and load them in dependency order, then drive the machine yourself instead of calling vic20.execute() - its internal setTimeout loop cannot be paused or stepped from outside, which the debugger needs.

Boot. Construct the machine (it installs the CHARGEN / BASIC / KERNAL ROMs into mem and points the VIC-6560 at the <canvas id="canvas">), then run your own loop built on vic20.cycle() (one machine clock: steps both VIAs, the CPU and the VIC):

window.vic20 = new Vic20();   // must be the global 'vic20' (chip callbacks read it)
vic20.isPal = false; kerneldata = kerneldataNtsc;
vic20.init();                    // builds CPU / VIAs / VIC, installs ROMs, resets
var CYCLES = 16965;             // ~1.02 MHz / 60 Hz
(function loop(){
  for (var i = 0; i < CYCLES; i++) vic20.cycle();
  requestAnimationFrame(loop);
})();

The machine is plain objects. Everything the debugger needs is a live global, with no wasm heap to reach into:

Because the CPU, bus and RAM are ordinary JavaScript, the debugger single-steps by running cycle() to the next instruction boundary, reads and writes registers straight through the CPU's get/set methods, and implements breakpoints and watchpoints as host-side checks around the loop. The only change to the core is a three-line numeric setPc/setSp/setP patch.

Debugger integration

The plug-in (mwenge-vic20-debug.js) hands the shared framework the machine surface and nothing else:

• Registers come from vic20.cpu.getRegisters() each refresh and are written back with setA/setX/setY (hex) and the added numeric setPc/setSp/setP; the status flags toggle bits of P.
• Memory is exposed as five chips: the side-effect-free CPU bus (invisibleRead/invisibleWrite), the raw 64 KB RAM, and the BASIC / KERNAL / Character ROM windows.
• Single step runs cycle() until cpu.isNextInst(), i.e. exactly one instruction.
• Breakpoints and watchpoints are host-side: the boot loop checks the PC against a set at each instruction boundary, and wraps vic20.write to catch a watched address.

Architecture

The VIC-20 (1981) was Commodore's first colour home computer: a 6502, the VIC-6560/6561 video-and-sound chip, two 6522 VIAs for I/O, and Commodore BASIC 2.0 in ROM. mwenge's emulation keeps each as its own object, clocked in lockstep one cycle at a time:

• Cpu6502 - the 6502 core, driven a sub-cycle at a time via a micro-op table; cycle() advances it.
• Vic6560 - the VIC video/sound chip, rastered into the canvas (text and the standard multicolour modes).
• Via6522 ×2, the timers, keyboard-matrix scan and joystick/tape lines.
• mem - the flat 64 KB array; vic20.read/write route reads and writes to RAM, ROM or the VIC/VIA registers.
• The CHARGEN, BASIC and KERNAL ROMs are embedded (packed) in carts.js and copied into mem on reset.

It boots straight to **** CBM BASIC V2 **** - a complete, inspectable machine with nothing to load.