nes-sim 0.1.2

A NES (Famicom) emulator core library written in pure Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# nes-sim

A NES (Famicom) emulator core library written in Rust. Headless design decouples the emulation engine from the frontend, making it easy to integrate into different UI frameworks or testing environments.

## Features

- **Complete CPU emulation** — 6502 processor with full addressing mode support and undocumented instructions
- **PPU rendering** — 256x240 resolution with sprite and background rendering
- **APU audio** — 5 standard channels (Pulse x2, Triangle, Noise, DMC)
- **Expansion audio** — VRC6, Namco 163, Sunsoft 5B, MMC5
- **Mappers** — Coverage of MMC1/MMC3/VRC series/Namco/Taito/Sunsoft and other common mappers
- **Multi-system support** — NTSC, PAL, DENDY
- **Save states** — Custom binary format with mapper validation
- **Debug support** — CPU/PPU state snapshots, per-channel mute
- **Zero-dependency core** — Core library has no external crate dependencies

## Quick Start

### Use as a library

```toml
[dependencies]
nes-sim = "0.1"
```

```rust
use nes_sim::NES;

let mut nes = NES::new("game.nes")?;
nes.reset();

// Run one frame (returns indexed color pixel data)
let frame = nes.clock();

// Output 44100Hz mono audio samples
let audio = nes.audio_samples();
```

## Project Structure

```
nes-sim/            Core library (zero dependencies)
nes-desktop/        Desktop frontend (minifb + cpal)
```

## Building

```bash
# Build core library
cargo build -p nes-sim

# Build desktop frontend
cargo build -p nes-desktop

# Run tests
cargo test -p nes-sim
```

## Examples

| Example | Description |
|---|---|
| `export_frame` | Export a single frame as PPM image |
| `analyze_audio` | Export audio as WAV |
| `analyze_state` | Analyze emulator state at a specific frame |
| `hash_frame` | Hash frame pixels for regression testing |

```bash
cargo run -p nes-sim --example export_frame -- "game.nes" "output.ppm" 180
```

## Desktop Frontend

```bash
cargo run --release -p nes-desktop -- "game.nes"
```

## Supported Mappers

- 0 (NROM)
- 1 (MMC1)
- 2 (UxROM)
- 3 (CNROM)
- 4 (MMC3)
- 5 (MMC5)
- 7 (AxROM)
- 11 (Color Dreams)
- 13 (CpROM)
- 19 (Namco 163)
- 21/23/25 (VRC4)
- 22 (VRC2)
- 24/26 (VRC6)
- 32 (Irem G-101)
- 33/48 (Taito TC0190)
- 34 (BNROM)
- 36
- 46
- 62
- 65 (Irem H-3001)
- 66 (GxROM)
- 67 (Sunsoft 3)
- 69 (FME-7)
- 70
- 71 (Camerica)
- 72
- 76
- 78
- 79/113 (NINA-003)
- 80 (Taito X1-005)
- 82 (Taito X1-017)
- 86 (JF-13)
- 87
- 88/154 (Namco 3433)
- 92 (JF-19)
- 94
- 97 (Irem Tam S1)
- 115
- 118 (TxSROM)
- 119 (TQROM)
- 152
- 162