# 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:

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

Enable optional adapter support if needed:

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

Recommended import style:

```rust
use nesemu::prelude::*;
```

Minimal setup:

```rust
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:

```rust
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:

```bash
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

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

## Documentation Map

- [API Contract](docs/api_contract.md): supported external surface and stability expectations
- [Integration Guide](docs/integration.md): how to embed the library into a host or frontend
- [Architecture](docs/architecture.md): internal module layout and layering