NES Emulator

Nintendo Entertainment System (NES) Emulator writen in Rust

This project is under development and it's still far to be a full emulator. However, some games are already playable (without music).

Any contribution is more than welcome! Feel free to open an issue or a PR :)

Features

Done

• CPU (MOS6502) emulated
• Memories (RAM, ROM and mirrored RAMs)
• Buses
• GTK4 GUI capable to render frames
• Maper-0 support
• PPU (Picture Processing Unit) background and sprite rendering

Work in progress

• Support more mappers
• Known PPU bugs and todos

TODOs and ideas

• APU (Audio Processing Unit)
• Web interface (compiling to web assembly)

Run nes-emulator

Dependencies

GTK-4 Graphical interface

When using GTK-4 desktop application to render NES screen, GTK-4 library is needed. To install the necessary dependencies, refer to GTK-4 Rust bindings documentation. For Linux users based on Debian and derivates, install the following libraries:

• libgtk-4-dev
• build-essential

Run nes-emulator binary

nes-emulator can be run with:

cargo run --release

For the moment, it'll run a binary with a hardcoded path to a cartridge. Open src/main.rs and change the path to load you NES game.

NES games must be in iNES file format.

Run examples

There's some useful examples to look at in the examples/ folder. They can be run with:

cargo run --example <EXAMPLE>

Some of the examples point to a ROM which is not part of the repository. If that's the case, download a ROM and change the cartridge path in the example.

Test nes-emulator

To run nes-emulator tests, execute:

cargo test

Some integration tests require you to download some external ROMs in a specific path. This will probably change in the future but it is convinient for development.

Debugging

nes-emulator library uses logging as observability/debugging tool. Some modules can export verbose logs, so it's recommended to customize RUST_LOG to print only the logs needed.

For example, to log CPU instructions being executed, run with RUST_LOG="nes_emulator::processor::cpu=DEBUG"

Screenshots

Let's see some nice screenshots of things working right now :)

Super Mario Bros

Donkey Kong:

Contributing

Contributions are more than welcome. However, to make code more standard, pre-commit is used. Please, install it and run it before submitting any code to this repo. Thanks!

To install the pre-commit hooks, execute:

pre-commit install

Thanks

This project wouldn't exist if I hadn't found the NES Emulator series from javidx9. Big thanks to him and his content, with great explanations and diagrams on how the NES works. You've been incredibly helpful!

Also, thanks to all the nesdev wiki contributors and maintainers to gather all this amazing information about the NES system. I can't stop being fascinated with the reverse engineering work done to this machine.

Thanks again, without those, this project wouldn't be here today.