se.cherkasov
bdf23de8db
Some checks failed
CI / rust (push) Has been cancelled
Full NES emulation: CPU, PPU, APU, 47 mappers, iNES/NES 2.0 parsing. GTK4 desktop client with HeaderBar, pixel-perfect Cairo rendering, drag-and-drop ROM loading, and keyboard shortcuts. 187 tests covering core emulation, mappers, and runtime.
103 lines
2.3 KiB
Markdown
103 lines
2.3 KiB
Markdown
# 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
|