RustyNES

RustyNES is a Nintendo Entertainment System (NES) emulator written in Rust.

Written from scratch in Rust without using any external libraries.

Cross-platform and can run on Linux, Windows, and in a web browser (using WebAssembly).

Runs using very low cpu and memory resources at stable 60fps.

Supports all 5 channels of NES audio.

Supports save state and load state, so that we can resume the game from where we left.

Can run classic NES games like Super Mario Bros, Super Mario Bros 2, Super Mario Bros 3, Contra and many more.

---

Try on your local machine by downloading the executable from the releases

Try online in your browser: RustyNES (Under development).

Screenshots

Super Mario Bros

Project Statistics

Language	Files	Lines	Code	Comments	Blanks
Rust	36	4403	3505	329	569
TypeScript	2	436	351	25	60
CSS	1	351	289	11	51
HTML	1	149	137	0	12
Total	40	5339	4282	365	692

---

Generated using the tokei CLI tool.

Command used to generate the statistics:

tokei -C -t=Rust,TYPESCRIPT,HTML,CSS -s=lines

Project Structure

• RustyNES_core: This is the heart of the emulator, containing the core emulation logic.

• RustyNES_cli: This is a command-line interface that uses RustyNES_core and SDL2 for rendering output, outputting audio, and handling input.

• RustyNES_wasm: This crate compiles RustyNES_core to WebAssembly which is used by the RustyNES_web_ui.

• RustyNES_web_ui: This is a web interface that uses RustyNES_wasm to run the emulator in a web browser.

Keyboard controls

NES Controller keybindings

Emulator Button	Keyboard Key
Up	W
Left	A
Down	S
Right	D
A	L
B	K
Start	Enter
Select	Right Shift

---

In most games, the following keybindings are used:

• A: Used for jumping.

• B: Used for shooting.

• Start: Starts the game or pauses it when running.

• Select: Selects the next option in the menu.

---

Extra Features keybindings (Not in the original NES)

Action	Key
Save emulator state	N
Load emulator state	M

Emulator state is saved in a .rustynes_sav file.

.rustynes_sav file can be loaded by passing the path to the file as an argument to the emulator.

./rusty_nes_cli <path_to_save_file>

Building and Usage

The RustyNES_core library crate has zero dependencies, but RustyNES_cli uses SDL2 for rendering and input handling. Ensure that SDL2 is installed on your system for building RustyNES_cli.

Building for Linux

1. Build the project in release mode:

   cargo build --release

   The rusty_nes_cli executable will be in the target/release directory.

2. Run the executable with the path to the ROM file as an argument:

   ./rusty_nes_cli <path_to_rom_file>

3. To load a save file (.rustynes_sav), pass the path to the save file as an argument:

   ./rusty_nes_cli <path_to_save_file>

Cross-compiling to Windows

1. Add the Rust target for Windows:

   rustup target add x86_64-pc-windows-gnu

2. Install mingw-w64:

   sudo apt install mingw-w64

3. Build the project for Windows:

   cargo build --release --target=x86_64-pc-windows-gnu

   The rusty_nes_cli.exe executable will be in the target/x86_64-pc-windows-gnu/release directory, and the SDL2.dll file will be in the project root directory.

   For running the emulator on Windows, ensure the SDL2.dll file is in the same directory as the executable.

4. Run the executable with the path to the ROM file as an argument:

   rusty_nes_cli.exe <path_to_rom_file>

5. To load a save file (.rustynes_sav), pass the path to the save file as an argument:

   ./rusty_nes_cli <path_to_save_file>

Building for Web

1. Install wasm-pack:

   cargo install wasm-pack

2. In the RustyNES_web_ui directory, run:

   npm install
   npm run dev

   This command will build the RustyNES_wasm library and output the WebAssembly file and JavaScript bindings to the RustyNES_web_ui/public/pkg directory.

Mappers Implemented

• Mapper 0 (NROM)
• Mapper 2 (UNROM)
• Mapper 4 (MMC3)

Resources

Documentation

• NES Documentation (PDF)
• Nesdev Wiki
• 6502 CPU Reference 1
• 6502 CPU Reference 2
• NES Rendering Overview

Videos

• The NES Explained YouTube playlist by NesHacker
• NES Emulator from Scratch YouTube playlist by OneLoneCoder

Code

• zeta0134/rusticnes-sdl
• OneLoneCoder/olcNES
• marethyu/nesty
• takahirox/nes-rust
• nathsou/nessy
• fogleman/nes
• maxpoletaev/dendy
• scottferg/Fergulator
• ltriant/nes
• spieglt/nestur