A cycle-accurate NES emulator written in Rust, designed to faithfully replicate the behavior of the Nintendo Entertainment System hardware. This project strives to provide precise emulation of the CPU, PPU, APU, and other critical components, ensuring that every game runs as it would on the original hardware.

This emulator’s design and implementation draw heavily from the excellent Mesen2 project. Mesen2’s documentation, code structure, and many of its implementation ideas (especially around timing, open-bus behaviour, and audio mixing) have been an invaluable reference. Huge thanks to the Mesen2 authors and contributors for making such a high‑quality emulator available.

• Cycle-accurate emulation: Every clock cycle is emulated precisely to ensure accurate game behavior.
• CPU (6502) Emulation: Full emulation of the 6502 processor with support for all instructions.
• PPU Emulation: Accurate rendering of graphics, including support for palettes, sprites, and background layers.
• APU Emulation: Recreates sound processing with support for the NES sound channels.
• Compatibility: Supports a variety of NES games, with ongoing improvements to compatibility and performance.

This repository currently ships two UI frontends:

• nesium-egui (apps/nesium-egui) — A lightweight desktop frontend built with egui. It has a small footprint and provides the essentials for quick debugging and development.
  • 
• nesium-flutter (apps/nesium_flutter) — A modern frontend built with Flutter. It aims for a more polished UI and broader cross‑platform reach than the egui app.
  • 
• Web build (play online) — https://mikai233.github.io/nesium/ (Runs in the browser via high-performance Flutter WASM (dart2wasm) + Web Worker + Rust WASM).
  • (Chrome/Edge 119+, Firefox 120+)

• Active development with ongoing improvements to accuracy, performance, and compatibility.
• Still in the early stages, but several key components are already functional.

The long-term vision for Nesium focuses on precision, tooling, and extensibility:

• Accurate NES Emulation:
  Achieve cycle-perfect accuracy across CPU, PPU, and APU components. The goal is to pass all standard compliance suites (including tricky edge cases in blargg's tests and nes-test-roms) and support "unlicensed" or hardware-quirk-dependent titles correctly.

• Advanced Debugging Suite:
  Implement a comprehensive debugger within the frontend. Planned features include:

  • Real-time disassembly and stepping.
  • Memory inspection/editing (RAM, VRAM, OAM).
  • Nametable, Pattern Table, and Palette viewers.
  • Breakpoint management (execution, read/write, IRQ).

• Lua Scripting Integration:
  Embed a Lua runtime to enable powerful automation and analysis. This will support:

  • Tool-Assisted Speedrun (TAS) workflows.
  • Custom HUDs and overlays for training or streaming.
  • Automated regression testing scripts.

• Netplay: Implement networked multiplayer support for two-player games over the internet.

• MMC5 (mapper 5): ExRAM-as-nametable modes and extended attribute/fill features are still TODO; expansion audio unimplemented.
• J.Y. Company 90: Commercial multicart audio/video parity is now verified on sampled mapper 90 ROMs; dedicated coverage for rarer advanced nametable edge cases is still needed.
• TQROM (mapper 119): Edge cases around CHR ROM/RAM bit toggling still need verification.
• Action 52 / Cheetahmen II (mapper 228): Mapper RAM window behaviour is minimal; verify against all carts.
• Generic: Bus conflict handling for certain discrete boards (e.g., some UNROM/CNROM variants) is not fully modelled yet.

Nesium integrates a large number of NES test ROM suites (via rom_suites.rs) to validate CPU, PPU, APU, and mapper behaviour. The tables below summarize which suites currently pass automatically, which are interactive/manual, and which are still marked as failing/ignored and need more work.

Legend:

• ✅: Enabled automated tests (no #[ignore]) that currently pass
• ❌: Tests marked with #[ignore = "this test fails and needs investigation"]
• 🔶: Interactive/manual ROMs (e.g., controller/visual tests)
• ℹ️: Tracking/diagnostic ROMs kept under #[ignore] by design

These ROMs are designed for interactive/manual verification and do not expose a simple $6000 state byte or TV hash protocol. They are wired into the test harness but kept under #[ignore] and should be checked by hand.

The following suites are currently marked with #[ignore = "this test fails and needs investigation"]. They highlight areas where Nesium’s behaviour still diverges from reference emulators and hardware.

These suites are baseline-tracking diagnostics against reference output and do not indicate a known failing area by themselves.

This project is a fan-made, non-commercial emulator intended for educational and preservation purposes. It is not affiliated with, endorsed, or sponsored by Nintendo or any other rights holder. You are solely responsible for complying with local laws and for ensuring that any ROMs or other copyrighted content you use with this emulator are obtained and used legally (for example, from cartridges you personally own).

Feel free to fork the project, open issues, and submit pull requests. Contributions are welcome as we work to improve accuracy and expand the feature set.

Nesium is distributed under the terms of the GNU General Public License, version 3 or (at your option) any later version (GPL‑3.0‑or‑later). See LICENSE.md for the full text.

This project also includes Shay Green’s blip_buf library (used via the nesium-blip crate), which is licensed under the GNU Lesser General Public License v2.1. The relevant license text is included alongside the imported sources in crates/nesium-blip/csrc/license.md.

The workspace includes the libretro-bridge crate, which automatically generates Rust bindings for the upstream libretro.h header via bindgen. The build script fetches the most recent header at compile time (with a vendored fallback for offline builds) so Nesium—and any other Rust project—can integrate with the libretro ecosystem as soon as API changes land upstream.