nesemu

NES/Famicom emulation workspace in Rust.

The workspace is built around a reusable core library. It also contains optional adapter crates and a GTK4 desktop frontend for manual testing.

What Is Here

• nesemu: core emulation library
• nesemu-adapter-api: backend-agnostic adapter traits
• nesemu-adapter-headless: null/headless adapter implementations
• nesemu-desktop: GTK4 desktop frontend

What The Core Library Provides

• CPU, PPU, APU, bus, and cartridge mapper emulation
• iNES ROM parsing
• Save/load state support
• Host-facing runtime wrappers for frame execution and pacing
• Public API and behavior tests

Quick Start

Add the main crate as a dependency:

[dependencies]
nesemu = { path = "../nesemu" }

Enable optional adapter support if needed:

[dependencies]
nesemu = { path = "../nesemu", features = ["adapter-api", "adapter-headless"] }

Recommended import style:

use nesemu::prelude::*;

Minimal setup:

use nesemu::{Cpu6502, NativeBus, create_mapper, parse_rom};

let rom_bytes = std::fs::read("game.nes")?;
let rom = parse_rom(&rom_bytes)?;
let mapper = create_mapper(rom)?;
let mut bus = NativeBus::new(mapper);
let mut cpu = Cpu6502::default();
cpu.reset(&mut bus);

Higher-level runtime setup:

use nesemu::{FRAME_RGBA_BYTES, NesRuntime};

let rom_bytes = std::fs::read("game.nes")?;
let mut runtime = NesRuntime::from_rom_bytes(&rom_bytes)?;
runtime.run_until_frame_complete()?;

let mut rgba = vec![0; FRAME_RGBA_BYTES];
runtime.render_frame_rgba(&mut rgba)?;

Desktop Frontend

Run the GTK4 desktop frontend:

cargo run -p nesemu-desktop -- path/to/game.nes

Linux build requirements: GTK4 development packages and pkg-config (for example on Debian/Ubuntu: libgtk-4-dev pkg-config).

Controls:

• Esc: quit
• P: pause/resume
• Open ROM: load .nes file
• Arrow keys: D-pad
• X: A
• Z: B
• Enter: Start
• Left Shift / Right Shift: Select

Development

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features

Documentation Map

• API Contract: supported external surface and stability expectations
• Integration Guide: how to embed the library into a host or frontend
• Architecture: internal module layout and layering