From f7c29429e3ef601766b59eee4b1378a479662aa2 Mon Sep 17 00:00:00 2001 From: 0xrsydn Date: Tue, 6 Oct 2026 22:23:28 +0700 Subject: [PATCH] docs: define general GBA usability milestones --- README.md | 1 + docs/status.md | 8 ++++++- docs/usability-roadmap.md | 46 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 docs/usability-roadmap.md diff --git a/README.md b/README.md index 60a8bad..89560f0 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ Use `--test-suite suite.json` for [repeatable headless ROM assertions](docs/rom- | Document | Contents | | --- | --- | | [docs/status.md](docs/status.md) | What works today, deliberate limits, and next steps | +| [docs/usability-roadmap.md](docs/usability-roadmap.md) | General GBA usability criteria and feature priorities | | [docs/demos.md](docs/demos.md) | Every demo, its command, and its controls | | [docs/development.md](docs/development.md) | Nix, direnv, and macOS build notes | | [docs/testing.md](docs/testing.md) | Validation commands and what the test suites cover | diff --git a/docs/status.md b/docs/status.md index ecc54ea..2d13394 100644 --- a/docs/status.md +++ b/docs/status.md @@ -169,6 +169,12 @@ Writes to cartridge addresses return errors instead of modeling cartridge hardwa ## Next steps +Follow the [general GBA usability roadmap](usability-roadmap.md). +Prioritize repeatable homebrew gameplay, demonstrated compatibility failures, cartridge saves, and audio. +The goal is usable emulation across games, not an Emerald-specific implementation. + +The remaining hardware-validation backlog includes: + 1. Extend shared fetch samples to verified general-bus data-access history and unsupported fetch regions. General DMA open-bus reads and sub-instruction arbitration remain separate from retained channel data and local IWRAM lanes. Keep unknown history diagnostic until fetch ordering and latch ownership have independent coverage. @@ -183,7 +189,7 @@ Writes to cartridge addresses return errors instead of modeling cartridge hardwa 3. Validate keypad retrigger behavior with hardware tests and add remaining device registers; extend BIOS reset coverage as sound/serial support becomes available. Validate STOP entry/wake edges and add external wake sources and remaining DMA device modes. 4. Replace nominal sprite work limits with verified individual fetch timing; add background fetch timing and per-pixel composition. -5. Validate more original/public test ROMs through the window; add audio, cartridge hardware, and saves before testing Emerald compatibility. +5. Validate more original/public test ROMs through the window. Expand compatibility evidence across independent programs. Keep the emulator core independent of window and audio libraries. Treat Nintendo DS support as a separate project phase. diff --git a/docs/usability-roadmap.md b/docs/usability-roadmap.md new file mode 100644 index 0000000..744670c --- /dev/null +++ b/docs/usability-roadmap.md @@ -0,0 +1,46 @@ +# General GBA usability roadmap + +The goal is a general-purpose GBA emulator, not a port of one game. +Pokémon Emerald is one possible future compatibility target. It does not define hardware behavior. +Nintendo DS support remains a separate phase. + +## Usability criteria + +A usable release must demonstrate these results with several lawfully obtained games: + +- Boot into a menu and enter gameplay without an unsupported-hardware diagnostic. +- Present stable graphics in the native Darwin window. +- Respond to button presses, held buttons, and releases. +- Preserve supported cartridge saves across process restarts without damaging existing files. +- Produce audio through an isolated host output layer. +- Exit cleanly and report unsupported behavior clearly. + +A bounded run without a diagnostic is not proof of playability. +A test pass establishes only the configured assertions, not complete game compatibility. + +## Work order + +1. Establish repeatable gameplay checks using licensed public homebrew. + Add VBlank completion, button schedules, and captured-pixel assertions to the ROM suite runner. +2. Exercise menus and gameplay in the native window. Record the exact ROM revision and checksums. +3. Select another independent program. Fix demonstrated boot, graphics, or input failures with original regressions. +4. Implement cartridge save devices and safe host persistence. Verify saving and reloading across processes. +5. Implement audio devices and host output. Keep host dependencies outside `gba-core`. +6. Expand the compatibility matrix across games and hardware features. + Refine timing when independent tests or gameplay failures show a requirement. + +SRAM, Flash, and EEPROM require different protocols. Supporting one does not establish support for the others. +Audio needs device clocks, mixing, and buffering; accepting sound-register writes alone is not audio support. +The detailed hardware limits remain in [status.md](status.md). + +## Development loop + +For each feature, inspect the source and hardware evidence, then write original regression tests. +Implement the smallest general behavior that satisfies the requirement. +Run focused tests, workspace validation, and relevant native-window checks through `direnv exec .`. +Update behavior notes and compatibility evidence. Save a semantic jj change with its own bookmark. +Then select the next demonstrated requirement without waiting for another confirmation. + +Stop for missing access, a necessary product decision, or a destructive operation that needs approval. +Do not replace unsupported hardware with game-specific patches or silent register stubs. +Keep external ROMs, firmware, implementation source, and assets outside version control.