RustyNES

Precise. Pure. Powerful.

RustyNES is a cycle-accurate Nintendo Entertainment System emulator written in pure Rust. It aims at the Mesen2 / higan / ares accuracy bar: one master clock, every CPU cycle a real bus access, and the PPU caught up to each half of it, so a sprite-zero hit, a mid-scanline scroll write or an MMC3 IRQ lands on the exact dot without a per-game patch. It passes AccuracyCoin 146/146 and matches the Nintendulator nestest log with zero diff.

Around that core sits a complete, modern platform: 208 mapper families, the Famicom Disk System, Vs. System and PlayChoice-10 arcade boards, rollback netplay, RetroAchievements, a TAStudio piano-roll editor, a Mesen2-class debugger, HD packs, a shader stack, and native apps for desktop, the browser, Android, iOS and RetroArch, all on one bit-deterministic core.

Play it in your browser, no install required.

Upgrading from v2.x? v3.0.0 "Cornerstone" is a major release. Save states and movies made by earlier versions are refused, netplay needs both sides on the same emulation epoch, and saves are keyed to the ROM without its header. The v3.0.0 release notes list every change by audience: players, RetroArch, mobile and the Rust crates.

Development note: AI-assisted. RustyNES is built with LLM tooling under a human-directed, test-driven workflow, with public test ROMs as the oracle. See docs/originality-and-provenance.md for what that means for originality and licensing. The accuracy claims are meant to be checked by running the public suites, not taken on faith. A comparison to another emulator is a comparison, not a claim of being better.

---

Contents

• Highlights
• Quick start
• Features
• Controls
• Accuracy
• Platforms
• Architecture
• Documentation
• Current release
• Roadmap
• The MiSTer core
• Contributing
• License
• Acknowledgments

---

Highlights

Cycle-accurate	CPU, PPU and APU on one master clock: AccuracyCoin 146/146, nestest 0-diff, blargg's CPU, APU and PAL suites
208 mapper families	NROM through MMC5, the whole VRC line, Sunsoft FME-7, Namco 163, Taito, J.Y. Company, the MMC3 and MMC1 multicarts, Waixing and Nanjing boards, homebrew flash boards with working saves, and a UNIF (.unf) loader. Each is classified Core, Curated or BestEffort by the evidence behind it
Famicom Disk System	Real-BIOS boot, writable disks, side swapping, a timed disk-head model and 2C33 wavetable audio
Vs. / PlayChoice-10	Arcade boards in true 2C03 / 2C04 / 2C05 RGB, per-game DIP presets, and Vs. DualSystem two-screen cabinets
Rollback netplay	GGPO-style, up to four players over UDP or browser WebRTC, with room codes, TURN traversal and spectators; peers must match on ROM, emulation options and emulation epoch, so a session cannot silently diverge, and a mismatch is refused with its reason
RetroAchievements	Achievements, leaderboards, rich presence and hardcore mode through the rcheevos library
TAStudio	A piano-roll TAS editor with a greenzone, branches and markers, plus .fm2 / .bk2 / .fcm / .fmv / .vmv import
Debugger	Conditional breakpoints, watchpoints, a hex editor, RAM search, a callstack, .dbg source maps, and editable palette, nametable, CHR and OAM
Video and audio	NTSC composite filtering, a CRT shader stack, HD packs with OGG audio, .pal palettes, a generated NTSC palette, and an NSF / NSFe player
Save states, rewind, run-ahead	All on the deterministic snapshot path. A movie records the options it was made with (console model, chip revisions, power-on state and more) and the emulation epoch, so a replay is bit-identical whatever the player's settings, and a movie from a version that emulates differently is refused rather than replayed wrong
Lua scripting	A sandboxed Lua 5.4 engine with memory access, callbacks, an HUD and a TAStudio API

---

Quick start

Download

Pre-built binaries for every release are on the Releases page: Linux x86_64, macOS (Apple silicon) and Windows x86_64. From v2.9.7 they are the full native build: RetroAchievements, Lua scripting, HD packs, A/V recording (with ffmpeg on your PATH) and the debugger telemetry are all included.

# Linux / macOS
tar xf rustynes-<tag>-<target>.tar.gz && ./rustynes path/to/rom.nes
# Windows (PowerShell)
Expand-Archive rustynes-<tag>-x86_64-pc-windows-msvc.zip; .\rustynes.exe path\to\rom.nes

Launch it without a ROM and use F12, the File menu, or drag and drop a .nes / .fds onto the window.

Build from source

You need Rust 1.99 (pinned in rust-toolchain.toml; rustup installs it) and Git.

git clone https://github.com/doublegate/RustyNES.git
cd RustyNES
cargo run --release -p rustynes-frontend -- path/to/rom.nes

# Everything native at once: RetroAchievements, Lua, host IPC, HD packs,
# debugger telemetry and A/V recording.
cargo full-run path/to/rom.nes

On Linux, the window, GPU and audio stack need a few system libraries:

# Ubuntu / Debian
sudo apt-get install -y libxkbcommon-dev libwayland-dev libxkbcommon-x11-dev libasound2-dev libudev-dev
# Arch / CachyOS
sudo pacman -S --needed libxkbcommon wayland alsa-lib systemd-libs

macOS and Windows need nothing extra; the optional retroachievements feature needs a C compiler on every platform.

rustynes --help lists the command-line options, and rustynes help opens an interactive guide to the controls, hotkeys, mappers, configuration, scripting and netplay.

In the browser

The hosted build is at doublegate.github.io/RustyNES. To build it yourself, install trunk and run trunk serve in crates/rustynes-frontend/web.

---

Features

Emulation core

• One master clock. A single cycle counter drives the CPU, PPU and APU at the region-exact ratios (3:1 NTSC and Dendy, 3.2:1 PAL). Every CPU cycle is clocked in two halves with the PPU caught up to each, so events inside an instruction are visible to the next access.
• 6502. All 256 opcodes including the unstable ones, per-cycle bus access, exact interrupt polling, and OAM and DMC DMA through one unified model.
• 2C02. A per-dot pipeline, the cycle-resolution sprite-evaluation state machine with its hardware overflow bug, and the rendering-time $2007 behaviour.
• 2A03. The non-linear mixer, band-limited synthesis, the analog filter chain, and expansion audio for VRC6, VRC7, MMC5, Namco 163, Sunsoft 5B and the FDS.
• Determinism. The same seed, ROM and input give a bit-identical framebuffer and audio, which is what makes save states, replays, regression tests and rollback netplay correct by construction.

Cartridges

• 208 mapper families, written from the NESdev wiki and pinned by test ROMs, unit tests and a commercial-ROM oracle. docs/mappers.md lists every family, its tier and its evidence.
• Self-flashing homebrew boards (GTROM, UNROM 512) emulate their SST39SF040 flash chip, so games that save by rewriting their own ROM keep those saves.
• Battery saves persist on desktop, Android and iOS, and in the browser (IndexedDB, from v2.9.7).
• Famicom Disk System with a user-supplied disksys.rom, and UNIF boards mapped to their iNES numbers.
• Header corrections on every platform: a built-in game database fixes known bad mapper, mirroring and region headers on desktop, web, Android, iOS and the libretro core alike. A correct NES 2.0 header is never overridden. Saves are keyed by the ROM's contents, not its header, so a corrected header keeps them.
• An optional Famicom console model, whose PPU leaves reset before the CPU, for the few carts that depend on it.

Playing

• Netplay: GGPO-style rollback for two to four players over UDP or browser WebRTC, with a deployable signaling bundle in deploy/.
• RetroAchievements on desktop, Android, iOS and the libretro core.
• Speed and pacing: 25-300% speed, fast-forward, frame advance, rewind, run-ahead, and display-synced, VRR or wall-clock pacing.
• Input: USB gamepads with hot-plug and remapping, turbo, the Four Score, Zapper, Arkanoid paddle, Power Pad, keyboards and mouse.
• Cheats: a Game Genie encoder with a ~10,800-code database, and raw RAM cheats.

Creating and debugging (opt-in features)

• TAStudio: a piano-roll editor with a save-state greenzone, lag log, markers and branches, and movie import from FCEUX, BizHawk and others. Movies record every input the core takes, expansion devices, the microphone, Vs. coins, disk swaps and barcode scans included (.rnm format 7).
• Speedrun timing: splits from RAM conditions, timed in master-clock cycles, with a fixed-layout memory interface for splitters (docs/memory-export-interface.md), and rustynes dump-check to tell whether a ROM file is the dump it claims to be.
• An MCP server, rustynes-mcp, serving the headless core to a Model Context Protocol client, with reproducible fork-and-diff experiments (docs/mcp-server.md).
• Debugger: breakpoints on expressions and conditions, R/W/X watchpoints, a trace logger, an event viewer, a hex editor, RAM search, a callstack, and ca65 / cc65 source maps. The inspectors become editors on request.
• Lua 5.4 scripting: memory and state access, per-frame and per-access callbacks, an HUD, and host IPC for automation (HTTP, WebSockets and OS shared memory). See docs/scripting.md.
• HD packs: a Mesen-format loader with OGG audio, and a builder that authors packs from the running game.
• A/V recording to .mp4 / .mkv through ffmpeg.

Display and audio

• An NES-NTSC composite / S-video filter, a CRT and scanline shader stack, hqNx and xBRZ upscalers, and a constrained RetroArch .slangp importer.
• Custom .pal palettes, a generated NTSC palette, and a choice of analog filter models.
• An NSF / NSFe player through the real APU and expansion synths.
• Every display option is off the core's path, so the emulated framebuffer is unchanged by it.

Mobile

• Android: a Jetpack Compose app with touch and hardware controllers, the shared shader stack, save states, netplay, RetroAchievements and Lua. Distributed through GitHub Releases. See docs/android.md.
• iOS / iPadOS: a SwiftUI app on Metal with GameController support, iCloud save sync and ReplayKit. Distributed through TestFlight. See docs/ios.md.

Both apps run the same core as desktop, and both are free: RustyNES is permanently non-commercial (ADR 0035).

---

Controls

Every binding can be changed in Settings or in the TOML config; the controls guide has the full list. USB gamepads bind to player 1 automatically.

Action	Player 1	Player 2
D-pad	Arrow keys	W / A / S / D
A / B	Z / X	Q / E
Start / Select	Enter / Right Shift	P / R

Action	Key	Action	Key
Pause	Space	Save / load state	F1 / F4
Fast-forward (hold)	Tab	Rewind (hold)	F5
Frame advance	\	Reset / power cycle	F2 / F3
Speed up / down / reset	= / - / 0	Open ROM	F12
TAS record / play / branch	F6 / F7 / F8	FDS disk side	F9
Menu bar	M	Vs. coin	F10
Debugger	`	Fullscreen	F11
Quit	Esc	Famicom microphone	N (hold)

---

Accuracy

Suite	Result
AccuracyCoin	146/146 (100.00%) at upstream f5f41dc2, read from RAM rather than the screen. The 144/144 reported before v3.1.0 was overstated: the older ROM's Misaligned OAM behavior fail path fell through to a pass, hiding a real failure the re-sync found and fixed
nestest	0-diff against the Nintendulator log
blargg cpu_interrupts_v2	5/5, and the unstable-store tests 6/6
blargg APU (NTSC and PAL)	11/11 and 10/10
blargg apu_test frame-counter probes	10/10
blargg MMC3 (mmc3_test_2)	5/6 strict, including 4-scanline_timing (all 13 sub-tests) since v3.0.0; 6-MMC3_alt tests the NEC revision, which the Sharp default is not, by design
region_timing	4/4, including PAL's 3.2:1 ratio
Holy Mapperel	every committed variant reports detail code 0000
Commercial-ROM oracle	99 titles, SHA-256-pinned, byte-identical frames

The last MMC3 interrupt-timing residual, mmc3_test_2/4-scanline_timing, closed in v3.0.0 (T-MMC3-BG-A12): every sub-test of the battery's MMC3 suite now passes except the deliberate other-revision case. Every remaining known approximation is listed, with its evidence, in docs/accuracy-ledger.md, and the per-suite detail is in docs/STATUS.md.

When a document and a passing test ROM disagree, the ROM wins: that is this project's definition of cycle-accurate.

Mapper tiers. Of the 208 families, 181 are accuracy-gated: 51 Core and 130 Curated, each backed by a test ROM, a commercial dump, or a precise register description with a synthetic fixture. The other 27 are BestEffort: their documentation is thin, and a CI gate keeps them out of every accuracy claim.

---

Platforms

Platform	Status
Linux x86_64, Windows x86_64, macOS (Apple silicon)	Release binaries
macOS (Intel), Linux ARM64	Build from source
WebAssembly	Hosted and buildable
Android (arm64)	GitHub Releases (sideload)
iOS / iPadOS	TestFlight
RetroArch	rustynes_libretro core, published by the libretro buildbot

A GPU with a wgpu backend is required: Vulkan, Metal, DX12, or WebGPU / WebGL2 in the browser. The headless core runs a frame in about 4 ms on an Intel i9-10850K, about four times faster than real time; docs/performance.md has the measurements.

---

Architecture

RustyNES is a Cargo workspace of focused crates. Three decisions carry the design, detailed in docs/architecture.md and docs/scheduler.md:

1. One master clock. Each CPU cycle runs in two halves around its bus access, and the PPU, APU and DMA are caught up to each half.
2. The bus owns everything mutable. It holds the PPU, APU, cartridge, work RAM and controllers, and the CPU borrows it one instruction at a time. That single choice avoids the borrow-checker fight of the alternative.
3. A one-directional dependency graph. The chip crates are no_std and do not depend on each other, so each can be fuzzed and benchmarked alone.

Crate	Role
rustynes-cpu, rustynes-ppu, rustynes-apu	The 6502, 2C02 and 2A03
rustynes-mappers	208 mapper families, expansion audio, the UNIF loader
rustynes-core	The bus, scheduler, console and save states
rustynes-frontend	The winit + wgpu + cpal + egui application (rustynes)
rustynes-netplay	Rollback netcode over UDP and WebRTC
rustynes-script	Sandboxed Lua 5.4
rustynes-cheevos, rustynes-ra	RetroAchievements
rustynes-hdpack, rustynes-gfx-shaders	HD packs and the shared WGSL shaders
rustynes-mobile, rustynes-android, rustynes-ios	The mobile bridge and platform glue
rustynes-libretro	The RetroArch core
rustynes-mcp	A Model Context Protocol server over the headless core (rustynes-mcp)
rustynes-test-harness	Integration tests and the accuracy oracles

---

Documentation

User guide	Installing, controls, save states, the debugger, configuration, FAQ
Documentation handbook	The subsystem specs and user guide as a website
API documentation	Rustdoc for the whole workspace
Status	Current state: per-suite results, the mapper matrix, feature flags
Changelog	Every release, newest first
Hardware specs	CPU, PPU, APU, mappers, testing, netplay
Decisions	Architecture Decision Records
Libretro core

---

Current release

RustyNES's current release is v3.5.0 "Chorus" (2026-10-22) — creator tools: movies record every input the core takes (.rnm format 7), Lua gains WebSockets and real shared memory, an MCP server, speedrun auto-timing and dump checks arrive, the MMC5 scanline IRQ is fixed (epoch 6), and the MiSTer core adds the MMC5, VRC6, Namco 163, VRC7 (silent) and Bandai FCG boards, off the die only. Built on v3.4.2 "Countersign" (2026-10-20) — the RetroArch core loads on Apple Silicon Macs again. Built on v3.4.1 "Beacon" (2026-10-19) — the hosted netplay lobby live with the browser and mobile builds pointing at it (the TURN relay deployed but held off: Cloudflare kept honouring expired and revoked credentials), the browser RetroAchievements build fixed (web RA held until RetroAchievements answers the integration request), version-named MiSTer release assets, and the MiSTer save engine's cartridge-change defects and v3.4.0's two build findings fixed. Built on v3.4.0 "Waypoint" (2026-10-18) — netplay authenticated and three and four players on the desktop, RetroAchievements hardcore held to RA's full block list, the hosted services shipped as code (deployed in v3.4.1), the window thread's CPU halved, and the MiSTer core's headline build made the off-die one, with save states, rewind and Phase F3a's boards. Built on v3.3.0 "Plumbline" (2026-10-16) — v3.2.0's leftovers settled and its claims re-measured: CHR-RAM writes go through the bank registers on seven boards, mapper 71 decodes its bank select as documented, v3.1.x Bandai states load again, a v3.2.0 performance figure is withdrawn, the IRQ trace goldens became a test, and, in simulation, the MiSTer core's off-die build reads CHR-RAM back and loads CHR correctly. Built on v3.2.0 "Confluence" (2026-10-15) — every v3.2.0 branch in both repositories brought into one release: 17 mapper families (208 in all), the VRC4 IRQ fix, an AI remediation branch audited change by change, netplay protocol 8, slim libretro states, and sixteen more boards on the MiSTer core. Built on v3.1.0 "Bellwether" (2026-10-08) — the AccuracyCoin re-sync and an honest 146/146, the CPU overclock and the sprite-limit option in movies and netplay, PAL emphasis, the alternate MMC3, rewind and run-ahead on the Vs. cabinet, and the MiSTer core matched to all of it. Built on v3.0.1 "Mortar" (2026-10-07) — a maintenance release: one game's graphics fixed, the MiSTer core's last MMC3 rule exception tested, Rust 1.99 everywhere, every unanswered bot review answered, and the plan to v4.0.0. Built on v3.0.0 "Cornerstone" (2026-10-06) — the API major: every break since v2.x in one place, a core timing epoch for movies and netplay, the last MMC3 timing gap closed in both cores, and a release-candidate MiSTer core. Built on v2.9.9 "Ballast" (2026-10-04) — the release candidate for v3.0.0: the audits re-run, MMC3 and MMC5 by their documentation, audio exact across save states, and the MiSTer core moved onto it. Built on (2026-10-02) — the preparation release for v3.0.0: v3.0.0's breaking changes landed early (a save identity that ignores the header, old states and movies refused, movies and netplay that record the machine, the API removals), every staged game was booted and the defects found were fixed, and the game database's corrections reach every platform. Built on (2026-09-30) — the desktop's features on the web and on phones, the release binaries built with every native feature, and a PPU A12 fix found by real games: Acclaim's MC-ACC games, the J.Y. ASIC and mapper 91 now count at their documented rates. Built on (2026-09-30) — seventeen mapper families written from their NESdev pages (174 → 191), GTROM promoted to Curated with a modelled flash chip whose saves persist, mapper 4's NES 2.0 submappers corrected (MMC6, NEC, MC-ACC, T9552), and the local commercial suites re-baselined after drifting unread since about v2.0.0.

v3.0.0 is the API major (ADR 0043). It gathers every breaking change since v2.x, most of them made early in v2.9.8 and v2.9.9, and adds the last: movies and netplay carry an emulation epoch (ADR 0045), and four more public structs became #[non_exhaustive]. Its release notes restate every break by audience.

The per-release detail, back to v0.1.0, is in CHANGELOG.md and on the Releases page.

---

Roadmap

v3.0.0 has shipped: the API major with a release-candidate MiSTer core (ADR 0043). Next is v3.x, hardware verification: the MiSTer core on a SuperStation One, the mobile apps on real devices, and the fixes each produces (v3.x-hardware-verification-plan.md). A change that alters what the emulator produces raises the emulation epoch, so v3.x releases that emulate identically still share movies and netplay.

The full plan is to-dos/ROADMAP.md, with one plan per release in to-dos/plans/. A free mobile store listing may follow later, with no monetization of any kind.

---

The MiSTer core

A sibling project writes a new NES core in SystemVerilog for the MiSTer FPGA platform, from public hardware documentation, and uses this emulator as its verification oracle through crates/rustynes-cosim. RustyNES itself is not being ported to an FPGA: what can be built is a new implementation checked against this one, cycle by cycle.

Its co-simulation ladder covers the 6502, the bus and interrupts, the 2C02, the 2A03, AccuracyCoin parity and twenty-one iNES mappers. Each release attaches a timing-closed bitstream pair; v3.3.0's (on-die and off-die, both at fitter seed 7, each compiled twice to the same bytes) is a release candidate, not hardware-verified. Its co-simulation ladder reads 260 passed, 0 failed, 3 expected failures on-die and 263 / 0 / 3 off-die. No hardware has run any bitstream yet, so a booting core, a synced display, audible sound and a working pad are not claimed. The details, and what each rung can and cannot verify, are in docs/mister.md.

---

Contributing

Contributions of every kind are welcome. CONTRIBUTING.md explains the quality gates, the Conventional Commit format, and the rule that a change to chip behaviour updates its docs/<subsystem>.md in the same pull request.

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Questions are welcome in GitHub Discussions.

---

License

RustyNES is licensed GPL-3.0-or-later.

It is a derivative work of GPL-licensed NES emulators: it incorporates code derived from Mesen2 (GPL-3.0-or-later) and, for a few subsystems, from puNES, FCEUX and Nestopia UE (GPL-2.0-or-later). An earlier version described that code as "oracle cross-checks" and licensed it MIT/Apache-2.0, which was wrong; after a NESdev community review the project was relicensed and every derivation credited in docs/originality-and-provenance.md and NOTICE (ADR 0036).

How that happened, and the rules that keep it from recurring, are public: docs/provenance-failure-postmortem.md and docs/ai-emulator-provenance-guardrails.md. Reference emulators are black-box oracles: their output may be compared, and their source is never read.

Permissive components (emu2413, TriCNES, rcheevos, blip_buf and the bundled fonts) are credited in NOTICE. The test ROMs under tests/roms/ are CC0, MIT or zlib. No commercial ROMs are included: dumps for the commercial-ROM oracle must come from cartridges you own.

---

Acknowledgments

• The NESdev wiki community, for decades of hardware documentation and research.
• Mesen2, the primary derivation source, and higan and ares, which set the accuracy bar.
• puNES, FCEUX and Nestopia UE, for specific subsystems.
• TetaNES, for the bus-owns-everything lesson.
• blargg, kevtris' nestest, Tepples' Holy Mapperel and 100thCoin's AccuracyCoin, which define "cycle-accurate" here.
• RetroAchievements and rcheevos.
• emu2413 (VRC7 audio) and TriCNES (PPU and DMA models).
• The shader authors whose looks RustyNES reimplements: CRT-Royale, crt-guest-advanced, Sony Megatron, and Bisqwit's composite model.

Full attribution is in NOTICE.

Citation

@software{rustynes2026,
  author  = {RustyNES Contributors},
  title   = {RustyNES: A Cycle-Accurate NES Emulator in Rust},
  year    = {2026},
  url     = {https://github.com/doublegate/RustyNES},
  note    = {Cycle-accurate NES emulator; AccuracyCoin 146/146, nestest 0-diff}
}