The reusable core implements all 56 documented instructions (151 official opcode encodings), NMOS decimal arithmetic, IRQ/NMI/BRK, stack behavior, addressing quirks, and instruction cycle counts. Unsupported opcodes stop with an explicit error.

Build and test

make                 # core and command-line emulator
make test            # unit/integration checks
make test-functional # official Klaus Dormann functional suite
make debug            # strict -Werror debug build and tests
make sanitize         # AddressSanitizer/UBSan build and tests

The core has no external dependencies. The graphical frontend uses SDL2 and SDL2_ttf. Building the included game also needs ca65 and ld65 from cc65. On Debian/Ubuntu install libsdl2-dev, libsdl2-ttf-dev, fonts-dejavu-core, and cc65. Set MOS6502_FONT to another TrueType font path if desired.

make snake

The startup menu offers Start/Resume, New Game, Reset High Score, and Quit. Use Up/Down or W/S to select and Enter or Space to activate. During play, WASD or the arrow keys steer, Space or P pauses, R restarts after game over, and Escape returns to the menu. D-pad and Start controls are supported on SDL game controllers. The window title shows the current score and persistent high score. The high score is stored in snake.highscore in the working directory.

F5 saves the current game and F9 restores it. Food and game-over events have lightweight synthesized sound effects. Save states are stored in snake.state.

The in-game arcade layout includes a framed pixel display, live score and high score, control legend, responsive resizing, and a full playfield pause overlay.

Run another flat binary with:

bin/mos6502 program.bin --load 0x0600 --start 0x0600

Useful options are --hz, --scale, --seed, --headless, and --trace.

External functional ROMs can be run without modifying the application:

make test-rom ROM=6502_functional_test.bin LOAD=0 START=0x400 SUCCESS=0x3469

Virtual machine

The machine provides 64 KiB RAM, a game-state byte at $00FB, a high-score byte at $00FC, a game-score byte at $00FD, a random byte at $00FE, the latest keyboard character at $00FF, and a 32x32 16-color framebuffer at $0200-$05FF. This is deliberately a small game-oriented computer, not an NES emulator. Original arcade Pac-Man used a Z80; running that ROM would require a different CPU and hardware platform.

See the design and project status.

Validation status

The in-tree tests exercise the CPU's major correctness boundaries. External Klaus Dormann functional and decimal ROM validation is the next hardening gate; the binaries are not vendored because their redistribution terms must be respected.