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 147/147 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
| |
|---|
| Cycle-accurate | CPU, PPU and APU on one master clock: AccuracyCoin 147/147, 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, spectators who can join mid-match through the hosted relay, and an opt-in report of where a desync began; 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, editable palette, nametable, CHR and OAM, and live PRG/CHR-ROM edits recorded as a BPS patch |
| 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 |
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
This is the beginning of the README. Read the rest at the original. Read the full README ↗
