Reference Materials

Reference Materials

Behavioral oracles (studied, never vendored)

Rusty2600's accuracy work leans on two open-source references for cross-checking real hardware behavior. Both are GPL-licensed, incompatible with this project's MIT/Apache-2.0 dual license, so they are read and run for comparison, never copied into this codebase:

• Stella — the canonical, long-maintained C++ Atari 2600 emulator. Treated as the behavioral oracle whenever prose documentation and observed hardware behavior disagree.
• Gopher2600 — a Go implementation used as a headless differential-testing harness: built and run directly against the same ROM as Rusty2600, then compared instruction-by-instruction. This technique found the project's hardest real bugs, including a Frogger WSYNC line-boundary jitter bug (see Lockstep-Scheduler) and a Pitfall II RIOT-timer boot-loop divergence (see RIOT).

Test-ROM oracles

• Klaus Dormann's 6502_functional_test and 6502_decimal_test — public-domain 6502 functional and BCD-decimal-mode conformance suites.
• SingleStepTests / ProcessorTests 6502 corpus — per-opcode, per-cycle bus-activity vectors, including undocumented NMOS opcode behavior. Rusty2600 passes all 233 opcodes on the trimmed corpus and re-verifies the full ~10,000-case-per-opcode corpus weekly in CI.

See Testing-Strategy for how these fit into the full accuracy battery.

Hardware documentation

• The Stella Programmer's Guide — the primary hardware reference for TIA register semantics, cited throughout the codebase's own documentation (with corrections noted where measured behavior differs from its stated values, e.g. the TIA audio clock).
• Real Atari 2600 hardware behavior, cross-checked against Stella/Gopher2600 wherever the written documentation is ambiguous or silent.

In this repository

• docs/ — the authoritative per-subsystem spec documents (architecture.md, cpu.md, tia.md, riot.md, cart.md, scheduler.md, netplay.md, scripting.md, mobile.md, frontend.md, testing-strategy.md, performance.md, compatibility.md) — this wiki summarizes them; the repository docs are the primary source when the two ever diverge.
• docs/adr/ — the numbered Architecture Decision Records; see Architecture-Decision-Records.
• docs/STATUS.md — the single source of truth for current pass counts, the board matrix, and version policy.
• to-dos/ROADMAP.md — the planning entry point; see Roadmap.

See also

Testing-Strategy · Architecture-Decision-Records · Roadmap