Rusty2600

Build Status License: MIT OR Apache-2.0 Version Rust: 1.96
Accuracy battery SingleStepTests Try in browser
Platform

Rusty2600 is a cycle-accurate Atari 2600 (VCS) emulator written in pure Rust. It targets the Mesen2 / ares / higan accuracy bar: a master-clock lockstep scheduler running at TIA-color-clock resolution (3.579545 MHz NTSC), with the 6507 CPU advancing on every third clock and WSYNC/RDY beam-stalls freezing the CPU mid-cycle while the rest of the machine keeps running. It clears its bundled Klaus2m5 functional and decimal-mode oracles bit-exact and passes the trimmed SingleStepTests 6502 corpus 4,660/4,660 cases across all 233 opcodes, with the full ~10K-case-per-opcode corpus verified weekly in CI.

Beyond reference accuracy, Rusty2600 is a real emulation platform, not just a timing-accurate core: all 26 of the console's catalogued bankswitch schemes (all 8 Curated-tier schemes plus all 16 BestEffort schemes) wired into automatic detection, a real debugger (live 6507/TIA/RIOT/memory panels, breakpoints, a standalone disassembler), a real RetroAchievements backend (rcheevos-vendored, per-frame achievement tracking and hardcore mode), save-states and rewind, and a growing accuracy battery (rusty2600-test-harness) gated in CI so a regression can never silently ship. The frontend is pure Rust (winit + wgpu + cpal + egui) with native binaries for Linux, macOS, and Windows, plus a WebAssembly build that runs in the browser.

Try it in your browser — no install required.

Rusty2600 combines accuracy-first emulation of one of the industry's oldest and most idiosyncratic consoles with modern tooling and the safety guarantees of Rust. The 2600 has no framebuffer of its own — the TIA races the electron beam and the program itself is responsible for timing every visible pixel — which makes cycle-exactness a correctness requirement, not a nice-to-have: get the timing wrong and games don't just look different, they visibly break.

Key differentiators:

• Reference-grade timing — an integer TIA-color-clock lockstep scheduler (not catch-up), the 6507 on every third clock, WSYNC/RDY beam-stalls modeled as a genuine sub-instruction freeze — see docs/scheduler.md and ADR 0001.
• Determinism as a hard contract — same seed, ROM, and input sequence yield a bit-identical framebuffer and audio (ADR 0004). This is what makes save-state round-trips and regression testing correct by construction, and what save-states, rewind, run-ahead, and the planned rollback-netplay work all build on.
• An honesty gate, not a marketing number — every bankswitch scheme is classified Core / Curated / BestEffort (ADR 0003); a BestEffort scheme can never silently back the accuracy oracle, enforced structurally by CI, not just documented.
• Safe, modular Rust — the chip stack (rusty2600-cpu, -tia, -riot, -cart, -core) is no_std + alloc, one-directional, and independently testable; the only unsafe lives behind the frontend/FFI boundary.

The v1.1.0 -> v2.0.0 RustyNES-parity line is complete; v2.1.0 through v2.3.0 closed every follow-up gap that release's own reconciliation carried forward except mobile-store submission and a real Xcode-verified iOS build (both explicitly deferred, not gaps). v2.4.0 "Save Point" opened a new gap-closure arc against RustyNES itself (v2.4.0 -> v3.0.0, see to-dos/ROADMAP.md), landing manual save-state slots (the headline item — Rusty2600 previously had no player-facing "save my game" feature at all despite the underlying format being real since v1.10.0), a CI-gated performance- regression bench, a Stella-oracle differential test strengthening the real paddle-timing simulation, .zip ROM-archive loading, and a GitHub repo hygiene pass. v2.5.0 "Web Awakens" followed with a real winit+wgpu+egui wasm build (compiles and builds cleanly; rendering unconfirmed in a real browser — see the WebAssembly row above), a debugger Lua console panel, and a Keyboard Controller/Trak-Ball research decision. v2.6.0 "Rollback Bridge" added browser WebRTC netplay (see the Rollback Netplay row above) and a master dependency-upgrade sweep consolidating 12 Dependabot PRs. v2.7.0 "True Colors" built the TIA object-ID mask and wired the HD-pack live rendering splice (see the HD-Pack Live Rendering row above). v2.8.0 "Touchpoint" built the first wave of wasm-winit web parity — an on-screen touch overlay, a wasm32-safety review of the Settings panel, and real localStorage config persistence (see the WebAssembly row above). v2.9.0 "Full Circle" built the second wave — a ?settings= share-link, a wasm32-safe debug-hooks debugger overlay, and PWA install/offline support (see the WebAssembly row above). In-browser Lua scripting was investigated for real this release (not just re-deferred on old reasoning) and stays deliberately unsupported on wasm32: mlua's vendored C build is confirmed to be a hard wall on wasm32-unknown-unknown, and the one realistic pure-Rust fallback, piccolo, isn't yet a workable substrate either — its only published release implements almost none of Lua's string/table stdlib, and its more-complete unpublished branch is explicitly pre-1.0-unstable by its own maintainer's admission (see docs/scripting.md's v2.9.0 status section) — see CHANGELOG.md for exactly what shipped in each release. Open follow-up work (each its own well-scoped future release): real Xcode-verified iOS build/run (this sandbox has no Xcode toolchain), netplay's WebRTC transport and real cross-NAT verification, DPC+/CDF per-player console-switch/paddle modeling, in-browser Lua scripting (blocked on piccolo publishing a crates.io release with real string/table coverage — an upstream milestone, not one this project controls), and a real HD-pack replacement-art library (only a proof-of-mechanism placeholder exists today). The .r26m movie format and TAStudio-lite panel shipped in v1.7.0; live per-frame auto-recording into the emu-thread's hot path is honestly deferred (docs/movie.md).

• 6507 CPU — documented and undocumented opcodes, cycle-exact against the full SingleStepTests corpus (weekly CI) and Bruce Clark's exhaustive ADC/SBC decimal-mode sweep (ERROR=0, bit-exact).
• TIA — beam-raced video (RESPx/HMOVE comb, playfield, players/missiles/ ball, all 15 pairwise collision latches) and two-channel poly-counter audio synthesis, unit-tested against Stella/Gopher2600 as differential oracles.
• RIOT — the console's only 128 B of RAM, the DDR/I/O ports, and the interval timer (prescale, underflow/INSTAT, read-after-write, and the post-underflow decrement-rate reversion — see docs/riot.md).
• Master-clock lockstep scheduler — the Bus owns every chip; the 2600 has no separate work RAM, so save-states/rewind only ever need to capture the CPU + Bus (TIA + RIOT + cart) state.

All 26 catalogued schemes are implemented and wired into automatic detect() — all 8 Curated-tier schemes (2K, 4K, F8, F6, F4, CV, FA/CBS-RAM, Superchip, DPC, E7) plus all 16 BestEffort schemes (F0, E0, 3F, 3E, EF/EFSC, DF/DFSC, BF/BFSC, UA, 0840, FE, SB, X07, 4A50, AR/Supercharger, DPC+, CDF/CDFJ/CDFJ+). Two Board hooks (snoop_write/snoop_read) let a scheme react to accesses the console routes to TIA/RIOT space, not just the 1000ドル+ cart window — needed for the 3F/3E/UA/0840/FE/X07/SB/4A50/AR families (4A50 also uses a smaller in-window instance of its hotspot state machine at 1ドルF00-1ドルFFF; AR's BIOS handoff additionally uses a Board::take_oob_pokes() hook to stage direct RIOT-RAM writes, mirroring Stella's System::pokeOob). Both Harmony/Melody ARM-coprocessor families consume the rusty2600-thumb ARM7TDMI Thumb-1 interpreter (v1.6.0): DPC+ (v2.2.0) and CDF/CDFJ/CDFJ+ (v2.3.0), the latter also exercising a real ARMinterrupt fault- servicing dispatch DPC+ never needed — both verified running real hand-assembled Thumb-1 programs. See docs/cart.md and docs/thumb.md for the full catalogue, tiering, and interpreter architecture.

• Debugger (debug-hooks, default-on) — live 6507/TIA/RIOT/memory panels, breakpoints/step/continue, a side-effect-free Bus::peek/ peek_range, a standalone disassembler, a watch/conditional-breakpoint expression engine, a JSR/RTS call stack, a TIA write-scatter viewer, and a player/missile/ball position panel.
• RetroAchievements (retroachievements, off by default) — rusty2600-cheevos vendors the rcheevos C library; login, a live achievement list, leaderboards, rich presence, per-frame achievement tracking, hardcore mode, and a recent-unlocks toast list all work.
• Save-states + rewind — a versioned binary snapshot format (rusty2600-core::save_state, ADR 0007) built on the chip stack's existing serde derives; the rewind ring reuses the same encoding rather than paying a raw-clone's worst-case cost.
• Run-ahead — speculatively simulates a few frames ahead to hide a game's internal input lag, built on the save-state snapshot primitives.
• WebAssembly — a canvas-2D bootstrap with real keyboard input and Web Audio API output; native-only features compile out automatically. A full winit+wgpu+egui browser build (wasm-winit, matching the native binary) compiles cleanly and, as of v2.9.0, has a wasm32-safe debugger overlay and a ?settings= share-link; live-browser rendering confirmation and a deployed switch-over remain open (see the WebAssembly feature-matrix row above and docs/frontend.md).
• PWA install (v2.9.0) — a web-app manifest + service worker (crates/rusty2600-frontend/web/manifest.json/sw.js) make the deployed wasm demo installable and offline-capable after a first visit.
• A/V recording (av-record, off by default, native-only, v2.13.0) — Tools -> Start/Stop Recording mux an .mp4/.mkv via an external ffmpeg process; a read-only tap that never touches emulator state.

Grab the latest release for your platform from the Releases page.

# Linux / macOS
tar xzf rusty2600-<version>-<target>.tar.gz
./rusty2600
# Windows (PowerShell)
Expand-Archive rusty2600-<version>-x86_64-pc-windows-msvc.zip
.\rusty2600.exe

# Clone the repository
git clone https://github.com/doublegate/Rusty2600.git
cd Rusty2600
# Build the workspace (release)
cargo build --release --workspace
# Run a ROM you legally own (or launch bare and use File -> Open ROM).
# .a26/.bin/.rom, or a .zip containing one, both work.
cargo run --release -p rusty2600-frontend -- path/to/rom.a26
# Optional: build with RetroAchievements (needs a C compiler for vendored rcheevos)
cargo build --release -p rusty2600-frontend --features retroachievements
# Optional: the "cargo --full equivalent" -- one command for the most
# fully-featured native binary (retroachievements + scripting + hd-pack +
# netplay, on top of the always-on default set). Needs a C compiler.
cargo full-build
cargo full-run path/to/rom.a26
# The no_std embedded-target gate (confirms the core stays no_std + alloc)
cargo build -p rusty2600-core --target thumbv7em-none-eabihf --no-default-features

On Linux the frontend needs the wgpu/winit/cpal system dependencies (CachyOS / Arch shown; substitute your distro's equivalents):

sudo pacman -S --needed libxkbcommon wayland alsa-lib systemd-libs

Paddles (INPT0–3, analog) bind to the mouse / gamepad axes. USB gamepads auto-bind to P0. All bindings live in config.toml (see docs/frontend.md); a key-rebind UI is planned.

Rusty2600 is a Cargo workspace with a strictly one-directional chip-crate graph — no chip crate depends on another except rusty2600-tia, which reads cart-mediated bus state via rusty2600-cart:

The Bus owns everything mutable; the CPU borrows &mut Bus for the duration of a step. The 2600 has no separate work RAM, so there's no WRAM field on the Bus — the only RAM in the whole console lives in the RIOT's 128 bytes. See docs/architecture.md for the full picture and docs/adr/ for the numbered architectural decisions (the master-clock scheduler, the fractional-timebase question, the accuracy honesty gate, the determinism contract, TIA revision modeling, power-on RAM seeding, and save-state versioning).

Every bankswitch scheme is classified Core (register-decode trivial, always oracle-gated), Curated (a redistributable fixture + full test coverage, oracle-gated), or BestEffort (reference-ported, register-decode

• boot-smoke tested only — never allowed to back the accuracy oracle). This isn't a documentation promise: mapper_tier_honesty.rs asserts the invariant in CI on every push. See docs/STATUS.md for the authoritative, currently-accurate per-suite numbers and board matrix, and docs/testing-strategy.md for the full layered methodology (unit tests → CPU golden-log → the accuracy battery → tolerance-aware snapshot comparison → a commercial-ROM regression oracle gated behind locally-supplied, never-committed ROM dumps).

Known accuracy work fixed along the way: a RIOT interval-timer bug that permanently stalled Pitfall II's boot-time wait loop (found via a rebuilt Gopher2600/Stella differential probe, confirmed against Stella's own M6532::peek/updateEmulation) — see docs/riot.md.

Rusty2600's per-frame workload is a fraction of a modern console's — a 2600 frame is ~262 scanlines ×ばつ 228 color clocks with a handful of chips, not a PPU/APU pipeline juggling thousands of tiles. Real Criterion baselines for the CPU/TIA/RIOT/cart crates live in docs/performance.md, measured with cargo bench on a pinned dev host — treat the documented numbers as deltas across changes, not absolute cross-machine guarantees.

Contributions are welcome — see CONTRIBUTING.md for the workflow, commit-message conventions, and the pre-tag quality gate (cargo fmt, cargo test --workspace, cargo clippy -- -D warnings, the no_std build). Never commit commercial ROMs; the commercial-roms feature and tests/roms/external/ exist precisely so local dumps stay local.

Rusty2600 is dual-licensed under MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.

Rusty2600's differential-oracle workflow leans on two open-source references studied (never vendored — both are GPL-licensed, incompatible with this project's MIT/Apache-2.0 dual license) for behavioral cross-checking: Stella (the canonical C++ Atari 2600 emulator) and Gopher2600 (a Go implementation used as a headless differential-testing harness). Test ROMs are drawn from Klaus Dormann's public-domain 6502 functional/decimal test suites and the trimmed SingleStepTests 65x02 corpus.