completed game

README.md

@@ -1,15 +1,74 @@
-# A mos-6502 emulator in c
-[Design Doc ](./docs/design.md)
-
-The source code in this repository has been developed exploratively, in order to validate and refine the ideas laid out in above document. As such, it is incomplete, may occasionally malfunction, and does not yet provide the fine bone porcelain rendering it usable in anger. It's a prototype, if you wish.
-
-## Links
-
-http://en.wikipedia.org/wiki/MOS_Technology_6502
-
-http://www.6502.org/documents/datasheets/mos/
-
-http://www.mdawson.net/vic20chrome/cpu/mos_6500_mpu_preliminary_may_1976.pdf
-
-http://rubbermallet.org/fake6502.c
-
+# MOS 6502 emulator
+
+A portable NMOS MOS 6502 emulator in C with an Easy6502-compatible virtual
+machine and an original Snake game.
+
+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
+
+```sh
+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.
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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](docs/design.md) and [project status](docs/plan.md).
+
+## 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.