NESER

NESER is a Nintendo emulation systems engine written in Rust. It provides native desktop and browser frontends for multiple emulated systems, with shared platform code for audio, video, input, save states, configuration, ROM browsing, and debugging.

Supported emulation targets:

• Nintendo Entertainment System / Famicom / related variants
• Game Boy and Game Boy Color
• Game Boy Advance

For emulator-specific options and notes, see:

• NES-specific documentation
• Game Boy-specific documentation
• Game Boy Advance-specific documentation

Installation

Pre-built releases

Download the latest archive for your platform from GitHub Releases.

Release archives contain a top-level neser/ directory. Extract the archive, enter that directory, and run the included binary:

cd neser
./neser --version
./neser

On Windows, run neser.exe --version and neser.exe from the extracted neser\ directory.

Release packages include the native emulator binary, runtime assets, shader presets required by configured presets, neser.conf.example, README.md, the system-specific README files, and LICENSE.

Install from crates.io

cargo install neser

No SDL2 setup is required. The native frontend uses Rust crates for windowing, audio, and gamepad input. Linux source builds may still require system development packages for backend libraries used by those crates, such as ALSA and Wayland/X11.

Building from source

Prerequisites:

• Rust toolchain
• Platform build tools needed by Rust native dependencies
• Node.js 20+ and npm for the web frontend

Native desktop build:

cargo build --release --bin neser

Native desktop run from source:

cargo run --release --bin neser -- [OPTIONS] [ROM]

Examples:

cargo run --release --bin neser --
cargo run --release --bin neser -- path/to/game.nes
cargo run --release --bin neser -- path/to/game.gb
cargo run --release --bin neser -- path/to/game.gba

The repository contains multiple binaries, so include --bin neser when using cargo run.

Running NESER

NESER can be launched with or without a ROM path:

neser
neser path/to/rom

When launched without a ROM path, NESER opens the ROM browser. When launched with a ROM path, it loads that ROM directly.

Use the built-in help for the complete current CLI reference:

neser --help

Common examples:

neser --fullscreen path/to/rom
neser --no-audio path/to/rom
neser --config path/to/neser.conf path/to/rom

Web frontend

The browser frontend is built from the Rust WASM target and the JavaScript frontend under web/.

See web/README.md for detailed prerequisites, build, run, and test commands.

Convenience commands:

bash scripts/build_web.sh
bash scripts/run_web.sh

scripts/run_web.sh serves the built dist/ directory at http://localhost:8000.

Configuration

NESER can be configured with config files and command-line arguments.

Configuration priority is:

1. Built-in defaults
2. ~/.neser/neser.conf
3. ./neser.conf
4. --config <file> if specified
5. Command-line arguments

Copy the example config to get started:

mkdir -p ~/.neser
cp neser.conf.example ~/.neser/neser.conf

See neser.conf.example for all documented configuration keys and valid values.

Controls

The native frontend supports keyboard and gamepad input.

Common hotkeys:

System-specific controls and controller options are documented in:

• README-NES.md
• README-GB.md
• README-GBA.md

Development

Recommended setup after cloning:

git config core.hooksPath .githooks

Useful checks:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --no-default-features --lib
npm test

Run tests for a specific Rust source area:

./scripts/test-dir.sh src/gb --skip-integration
./scripts/test-dir.sh src/nes/cartridge

Python tooling tests:

source .venv/bin/activate
python -m unittest discover -s scripts -t scripts -p "test_*.py"
python -m unittest discover -s scripts/metadata-scraper -t scripts/metadata-scraper -p "test_*.py"
python -m unittest discover -s scripts/nes-rom-db-scraper -t scripts/nes-rom-db-scraper -p "test_*.py"

Repository guide

• src/ contains Rust emulator, frontend, and shared platform code.
• web/ contains the browser frontend.
• roms/ contains automated test ROMs and test assets.
• scripts/ contains build, packaging, test, ROM management, and metadata tools.
• shaders/ and vendor/slang-shaders/ contain shader presets used by the native frontend.
• architecture.md describes the codebase structure in more detail.

License

NESER is licensed under the MIT License. See LICENSE.