Extend Dot Matrix Deck

.gitattributes

@@ -0,0 +1,14 @@
+# Keep Zig sources with LF line endings.
+*.zig text eol=lf
+build.zig text eol=lf
+build.zig.zon text eol=lf
+
+# Mark committed ROM images as binary.
+fixtures/roms/*.gb binary
+fixtures/blargg/*.gb binary
+
+# Documentation and text files.
+*.md text
+*.txt text
+*.yml text
+*.yaml text

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+      - name: Format check
+        run: zig fmt --check .
+      - name: Unit and integration tests
+        run: zig build test -Dsdl2=off --summary all
+      - name: Regenerate bundled ROMs
+        run: zig build fixtures -Dsdl2=off
+      - name: Build headless tools
+        run: zig build -Dsdl2=off
+
+  test-windows:
+    name: Test (windows)
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+      - name: Format check
+        shell: pwsh
+        run: zig fmt --check .
+      - name: Unit and integration tests
+        shell: pwsh
+        run: zig build test -Dsdl2=off --summary all
+      - name: Regenerate bundled ROMs
+        shell: pwsh
+        run: zig build fixtures -Dsdl2=off
+      - name: Build headless tools
+        shell: pwsh
+        run: zig build -Dsdl2=off
+
+  windowed:
+    name: Windowed frontend (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+      - name: Install SDL2
+        run: sudo apt-get update && sudo apt-get install -y libsdl2-dev
+      - name: Build windowed frontend
+        run: zig build

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Dot Matrix Deck is a work-in-progress emulator. Contributions are welcome.
+
+## Build
+
+Use Zig 0.16.0 or later.
+
+Build the headless tools:
+
+```text
+zig build -Dsdl2=off
+```
+
+Build the windowed frontend. SDL2 must be installed.
+
+On Linux, install the package `libsdl2-dev`.
+
+On Windows, install SDL2 in MSYS2 or set the prefix with `-Dsdl2=<prefix>`.
+
+```text
+zig build
+```
+
+## Test
+
+Run the unit, assembler, and integration tests:
+
+```text
+zig build test -Dsdl2=off
+```
+
+Run the blargg CPU instruction suite:
+
+```text
+zig build test-blargg
+```
+
+The blargg ROMs are public test files. Copy them into `fixtures/blargg` first.
+Without them, the suite prints a skip message and exits cleanly.
+
+## Format
+
+The CI workflow checks formatting. Format your changes before you open a
+pull request:
+
+```text
+zig fmt .
+```
+
+Verify the formatting with:
+
+```text
+zig fmt --check .
+```
+
+## Regenerate fixtures
+
+The bundled ROMs come from source. Regenerate them with:
+
+```text
+zig build fixtures
+```
+
+The output is deterministic. The integration tests read the generated ROMs.
+
+## Report a problem
+
+Open an issue that describes the expected behavior and the observed behavior.
+Include the ROM and the command you ran when you can.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dot Matrix Deck contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

NOTICE

@@ -0,0 +1,17 @@
+Dot Matrix Deck
+
+This product includes software developed for SDL2.
+
+The windowed frontend links against SDL2. SDL2 is available under the
+zlib license. See https://www.libsdl.org for details.
+
+The windowed frontend is optional. The headless runner, the assembler,
+and the tests do not require SDL2.
+
+Third-party test ROMs
+
+The blargg cpu_instrs suite is a set of public test ROMs for the Game Boy
+CPU. The ROMs are not committed to this repository. The suite was written
+by blargg and is distributed by the gb-test-roms project by retrio.
+
+Source: https://github.com/retrio/gb-test-roms

README.md

@@ -1,89 +1,163 @@
 # Dot Matrix Deck
 
-Dot Matrix Deck is a Game Boy emulator workbench written in Zig. It models the
-SM83 CPU, the memory bus, timers, serial output, and the pixel pipeline. A
-headless runner makes emulator behavior easy to inspect in scripts and CI.
+Dot Matrix Deck is a Game Boy emulator written in Zig.
+It emulates the SM83 CPU, the memory bus, the timers, and the pixel pipeline.
+A software renderer shows the screen in an SDL2 window.
+A headless mode runs public test ROMs in scripts and CI.
+
+## Why this project
+
+The emulator shows how a real console works.
+Every layer is small, readable Zig code.
+You can inspect the CPU, the bus, and the renderer separately.
+A bundled assembler builds test ROMs from source.
+Deterministic tests guard the core behavior.
 
 ## Current status
 
-This project is under active development. The headless core is the most useful
-entry point today. The SDL2 windowed frontend is available when SDL2 is
-installed, but it is still being built out.
+The emulator core is the most complete part.
+The CPU, timer, bus, and pixel pipeline are implemented.
+The windowed frontend works when SDL2 is installed.
+The headless runner drives automated checks.
 
 ## Features
 
-- SM83 CPU and instruction execution
-- Memory bus with timer, serial, and pixel-processing components
-- Headless ROM runner with cycle limits and serial verdicts
-- Optional instruction trace output
-- Small assembler tool for test ROM sources
-- Deterministic unit tests for the emulator core and assembler
+- SM83 CPU with all 256 opcodes
+- Memory bus with timer, serial, and pixel components
+- MBC1 cartridge mapper
+- SDL2 window with keyboard controls
+- Headless runner with pass or fail verdicts
+- Cartridge header display with `--info`
+- Instruction trace output
+- SM83 assembler with deterministic output
+- Bundled smoke ROM assembled from source
+- Deterministic unit and integration tests
+
+## Architecture
+
+The core does not depend on a window.
+It feeds the bus and the CPU for each step.
+The PPU fills a pixel frame.
+The headless runner and the SDL2 frontend both use the core.
+
+- `src/cpu.zig` - SM83 CPU
+- `src/bus.zig` - memory and device routing
+- `src/timer.zig` - DIV, TIMA, TMA, and TAC
+- `src/ppu.zig` - LCD, background, and sprites
+- `src/cartridge.zig` - ROM and MBC1 mapper
+- `src/serial.zig` - serial verdict helpers
+- `src/emulator.zig` - emulator composition
+- `src/headless.zig` - headless ROM runner
+- `src/main.zig` - SDL2 frontend
+- `src/integration.zig` - ROM-level tests
+- `tools/gbasm.zig` - SM83 assembler
 
 ## Requirements
 
-- Zig 0.16 or later
-- SDL2 for the optional windowed frontend
+- Zig 0.16.0 or later
+- SDL2 for the windowed frontend
 
-The headless build does not require SDL2. On Windows, the build searches common
-MSYS2 and vcpkg prefixes. You can also set `SDL2_DIR` or pass an SDL2 prefix.
+The headless build does not require SDL2.
+On Windows, the build searches common MSYS2 and vcpkg prefixes.
+You can also set `SDL2_DIR` or pass `-Dsdl2=<prefix>`.
 
 ## Build
 
-Build the headless runner and assembler:
+Build the headless tools:
 
 ```text
 zig build -Dsdl2=off
 ```
 
-Build with the windowed frontend when SDL2 is available:
+Build the windowed frontend:
 
 ```text
 zig build
 ```
 
-## Run a ROM
-
-Run a ROM without a window:
+## Run a ROM headlessly
 
 ```text
 zig build run-headless -- path/to/rom.gb
 ```
 
-Useful options are `--max-cycles N`, `--trace`, and `--expect pass|fail|any`.
-The runner prints serial output and returns a status from the detected verdict.
+Use `--expect pass` to require a passing verdict.
+Use `--expect any` to accept any outcome.
+Use `--trace` to print each instruction.
+Use `--info` to show the cartridge header without running.
+
+```text
+zig build run-headless -- path/to/rom.gb --expect pass
+```
+
+Sample output:
 
-Run a ROM in the SDL2 frontend:
+```text
+Serial output:
+Passed
+Verdict: pass
+```
+
+Run the bundled smoke ROM:
+
+```text
+zig build fixtures -Dsdl2=off
+zig build run-headless -- fixtures/roms/smoke.gb
+```
+
+## Run a ROM in a window
 
 ```text
 zig build run -- path/to/rom.gb
 ```
 
+| Key | Button |
+| --- | ------ |
+| X | A |
+| Z | B |
+| Enter | Start |
+| Backspace | Select |
+| Arrows | D-pad |
+| Esc | Quit |
+
 ## Test
 
-Run the core and assembler tests:
+Run all tests:
 
 ```text
 zig build test -Dsdl2=off
 ```
 
-The repository also contains build steps for generated fixtures and the Blargg
-CPU instruction suite. Add the required fixture files before using those steps.
+The test step assembles the smoke ROM first.
+It then runs the unit tests and the ROM-level tests.
+The suite is deterministic and reproducible.
 
-## Project layout
+Regenerate the bundled ROMs:
 
-- `src/cpu.zig` - SM83 CPU implementation
-- `src/emulator.zig` - emulator composition and core tests
-- `src/bus.zig` - memory and device routing
-- `src/headless.zig` - command-line ROM runner
-- `src/main.zig` - SDL2 frontend
-- `tools/gbasm.zig` - small assembler for fixture ROMs
+```text
+zig build fixtures
+```
+
+The blargg CPU instruction suite is optional.
+Copy its ROMs into `fixtures/blargg`, then run:
+
+```text
+zig build test-blargg
+```
+
+## Roadmap
+
+The roadmap lists complete and planned work.
+See `ROADMAP.md` for details.
 
 ## Limitations
 
-Hardware coverage is incomplete. Timing accuracy, cartridge support, audio,
-and frontend features will improve as the project grows.
+The emulator does not cover all hardware.
+Audio, OAM DMA, and battery saves are not implemented.
+The PPU timing is not cycle-accurate.
+The boot ROM is not emulated.
 
 ## License
 
-No license file is published yet. Treat this repository as an experimental
-project until a license is added.
+Dot Matrix Deck is available under the MIT license.
+See `LICENSE` for details.