Extend Dot Matrix Deck

.gitattributes

@@ -0,0 +1,8 @@
+# Normalise line endings so that regenerated fixtures diff cleanly on
+# every platform. Binary images must never be touched by line-ending rules.
+* text=auto eol=lf
+
+*.gb binary
+*.ppm binary
+*.png binary
+*.sav binary

.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+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 --summary all
+      - name: Regenerate bundled ROMs
+        run: zig build fixtures
+      - name: Bundled ROMs match their sources
+        run: git diff --exit-code -- fixtures
+      - name: CPU instruction suite (blargg)
+        run: zig build test-blargg
+      - 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 --summary all
+      - name: Regenerate bundled ROMs
+        shell: pwsh
+        run: zig build fixtures
+      - name: Bundled ROMs match their sources
+        shell: pwsh
+        run: git diff --exit-code -- fixtures
+      - name: CPU instruction suite (blargg)
+        shell: pwsh
+        run: zig build test-blargg
+      - 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

.gitignore

@@ -7,6 +7,12 @@ zig-out/
 *.dylib
 *.exe
 .DS_Store
-*.gb
 *.sav
 *.swp
+*.ppm
+
+# Generated ROM images are ignored by default, but the bundled test
+# fixtures are committed so that CI can run the ROM suites.
+*.gb
+!fixtures/roms/*.gb
+!fixtures/blargg/*.gb

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thank you for your interest in Dot Matrix Deck.
+
+## Setup
+
+Install Zig 0.16.0 or newer.
+Install SDL2 for the windowed frontend.
+
+## Build and test
+
+Run the test suite.
+
+```
+zig build test
+```
+
+Run the blargg CPU instruction suite.
+
+```
+zig build test-blargg
+```
+
+Build the headless tools.
+
+```
+zig build -Dsdl2=off
+```
+
+Format the code.
+
+```
+zig fmt .
+```
+
+## Code style
+
+Follow the existing style in the repository.
+Run `zig fmt --check .` before you finish.
+Keep each module small and single-purpose.
+Add a test for every new behaviour.
+
+## Adding tests
+
+Use the bundled smoke ROM for end-to-end checks.
+Regenerate its binary after you change its assembly source.
+
+```
+zig build fixtures
+```
+
+Verify the committed ROM still matches its source.
+
+```
+git diff --exit-code -- fixtures
+```
+
+Update the golden frame checksum when rendering changes.
+Run the headless runner to read the new value.
+
+```
+zig build run-headless -- fixtures/roms/smoke.gb --dump-frame out.ppm
+```
+
+## Submitting changes
+
+Create a pull request against the main branch.
+Make the change small and focused.
+Add a clear description of what changed.
+Confirm all CI checks pass before you request a review.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Cuevas
+
+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,15 @@
+# Notice
+
+This file lists third-party content distributed with Dot Matrix Deck.
+
+## blargg CPU instruction tests
+
+The directory `fixtures/blargg` contains the `cpu_instrs` test ROMs.
+Shay Green wrote these ROMs.
+The ROMs verify the instruction set of the CPU.
+They are used as read-only test fixtures.
+See the blargg test collection at:
+https://github.com/retrio/gb-test-roms
+
+The ROMs are included for test purposes only.
+Dot Matrix Deck does not claim ownership of these files.