Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

x-nes

A cycle-accurate NES emulator written in Rust, targeting everything from microcontrollers to modern desktops.

What is an Emulator?

An emulator is a program that mimics the behavior of a hardware system. For the NES, this means simulating:

  • The CPU (6502) — executes game code, handles interrupts
  • The PPU — generates the video signal, scanlines, sprites, and scrolling
  • The APU — generates the audio signal (5 channels: 2 pulse, triangle, noise, DMC)
  • The Memory Bus — routes data between components and the cartridge mapper
  • The Mapper — cartridge chip that provides bank switching, IRQs, extra RAM, and custom features

All running in lockstep, synchronized to the NES’s master clock.

What is x-nes?

x-nes is a from-scratch implementation of the NES hardware in Rust. It is:

  • Cycle-accurate — the CPU follows the expected cycle timing for each instruction, including page-cross penalties
  • no_std — no operating system dependencies, so it can run on bare metal
  • Portable — the same core code is shared across desktop and embedded targets
  • Practical — 8 mappers implemented (NROM, MMC1, UxROM, CNROM, MMC3, MMC5, AxROM, GxROM), covering ~90% of the NES library
  • Full-featured APU — all 5 audio channels with frame sequencer, sweep units, envelope generators, and DMC DMA

The current implementation passes 86% of the AccuracyCoin test suite (86/141 tests), with all Blargg CPU tests passing cleanly.

Current Status

ComponentStatus
CPU (all 151 opcodes)✅ Cycle-accurate, all unofficial opcodes
PPU rendering✅ On-the-fly renderer with NMI edge detection
PPU scrolling✅ $2005/$2006 with loopy-V register, fine X/Y
APU (5 channels)⚠️ Functional, timing needs refinement
Mapper 0 (NROM)✅ Complete
Mapper 1 (MMC1)✅ Complete
Mapper 2 (UxROM)✅ Complete
Mapper 3 (CNROM)✅ Complete
Mapper 4 (MMC3)✅ Complete — SMB3, Mega Man 3, Kirby support
Mapper 5 (MMC5)✅ Complete — Castlevania III support
Mapper 7 (AxROM)✅ Complete
Mapper 66 (GxROM)✅ Complete
Open bus emulation✅ With capacitive decay
NMI penultimate cycle✅ Deferred NMI from $2000 writes
iNES 2.0 headers✅ Correct detection
AccuracyCoin⚠️ 86/141 (61%)
Expansion audio (MMC5)❌ Not yet implemented

Highlights

MMC5 Support

x-nes is one of the few emulators with working MMC5 support, enabling Castlevania III and other rare MMC5 games:

  • 4 PRG modes (32KB, 2×16KB, 16KB+8KB+8KB, 4×8KB) with up to 1MB PRG ROM
  • 4 CHR modes (8KB, 4KB, 2KB, 1KB) with separate BG/sprite banking and up to 1MB CHR ROM
  • ExRAM with 4 operating modes (extra nametable, extended attributes, CPU RAM, read-only)
  • Scanline IRQ for split-screen effects
  • Hardware 8×8→16 multiplier at $5205/$5206
  • Fill mode and per-nametable source mapping via $5105

On-the-Fly Rendering

Instead of emulating the PPU’s internal shift registers (which would require complex tile caching), x-nes computes each pixel directly from scroll state snapshots. This approach:

  • Simplifies the renderer significantly
  • Naturally supports MMC5 extended attributes (per-tile CHR bank + palette)
  • Uses render_v snapshots at prerender cycle 0 and cycle 257

Want to Contribute?

x-nes is an open-source project aiming to be the most accurate NES emulator library in Rust. We’re actively looking for help with:

  • Audio accuracy — APU timing and tone refinement
  • PPU edge cases — sprite evaluation corner cases, OAM corruption
  • DMA timing — DMC DMA + OAM DMA interaction
  • Expansion audio — MMC5 extra pulse channels, VRC6, etc.
  • New mappers — VRC series, FME-7, Namco 163, etc.
  • RetroArch integration — libretro core support

Contributing guide | Issue tracker

How This Book is Organized

ChapterWhat You’ll Learn
1. ArchitectureSystem design, tick function, PPU sync, open bus
2. The 6502 CPUCPU registers, flags, stack, memory model
3. Instruction SetAll 56 official + unofficial opcodes, 13 addressing modes
4. Memory & I/ONES memory map, PPU/APU registers, OAM DMA
5. PPUVideo generation, scanlines, scrolling, NMI, on-the-fly rendering
6. Audio & ROMAPU channels, frame sequencer, iNES format
7. MappersAll 8 mappers, bank switching, IRQs, CHR banking
8. MMC5 Deep DiveComplete register map, ExRAM modes, extended attributes
9. DebuggingCPU/PPU/mapper debugging, crash triage, diagnostic tools
10. Graphics DebuggingVisual symptom diagnosis, pixel inspection, frame comparison
11. PerformanceCross-platform design, optimization techniques
12. Building & TestingBuild targets, test suite, profiling, CI

Each chapter explains the hardware first, then shows the Rust implementation. The code is designed to match the hardware behavior as closely as possible.