rNES it's yet another NES emulator which has as it main goals:
- Accuracy to real hardware
- Low memory footprint
- High portability across platforms
Currently rNES implements mappers 0, 1, 2, 3, 4, 7 and 11, supporting thousands of NES games.
Currently only an interface using lib SDL is implemented. On a Debian family system, make sure to install the following packages:
- libsdl2-dev
- libsdl2-ttf-dev
rNES can be built by calling make from src directory:
cd src
makeTo run rNES just call:
./rNES <rom_file>The following options are supported:
Use: ./rNES [-s <scale_factor>] [-f] [-d] [-h] <rom_file>
-s, --scale Set screen scale factor (default: 2)
-f, --fullscreen Enable full screen mode
-d, --debug Show debug messages (it can be extremely slow!)
-i, --info Just show ROM information (don't play the game)
-v, --version Show version
-l, --license Show license
-h, --help Show this help
| Key | Action |
|---|---|
| Arrow keys | D-pad |
| Z | A |
| X | B |
| A | Start |
| S | Select |
| F12 | Toggle full screen mode |
| Q | Quit |
In full screen mode the picture keeps the NES aspect ratio and is letterboxed to fit the display.
A static version for Windows can be cross-compiled on Linux using the MinGW-w64 toolchain.
The script build-win32-cross.sh builds the cross-compiler environment with SDL2 and SDL2_ttf libraries.
First, ensure you have the MinGW-w64 toolchain installed (x86_64-w64-mingw32-gcc and x86_64-w64-mingw32-g++ must be available on the host system).
On Debian the following packages must be installed: gcc-mingw-w64 and g++-mingw-w64:
sudo apt install -y gcc-mingw-w64 g++-mingw-w64Run the build-win32-cross.sh script to create the build environment:
cd src
./scripts/build-win32-cross.shOnce the environment is ready, rNES.exe can be built using make:
make -f Makefile.mingwrNES provides an easy to use PalleteEditor that can be found in tools/PaletteEditor. The tool be built with cmake (Qt6 is required):
cd tools/PaletteEditor/
cmake .
make
./PaletteEditorThe tool is straightforward to use, you can create a new palette or load an existent one (.pal file, no headers, just a sequence of RGB color data for all 64 entries). Just click on the squares to change the color.
PaletteEditor interface.
rNES comes with a headless ROM test framework, located at test-framework, which runs a batch of NES ROMs without a display or a sound card and flags the obviously broken ones: crashes, hangs, blank or frozen screens and CPU jams.
First, build the headless harness (it links the emulator core against a null backend, so no SDL is needed):
make -C test-frameworkThen run it over a list of ROM paths (one per line, # comments allowed):
python3 test-framework/run_tests.py --rom-list ~/my-roms.txtEach ROM gets a PASS, FAIL or SKIP verdict (SKIP means the mapper isn't implemented yet). A single ROM can also be inspected directly with the harness, which prints a JSON report with per-frame metrics:
./test-framework/rnes_headless --frames 300 <rom_file> | python3 -m json.toolResults can be compared against a committed baseline, so that only regressions (PASS to FAIL) are reported. This is what CI runs on every pull request:
python3 test-framework/run_tests.py --rom-list test-framework/roms-ci.txt \
--baseline test-framework/baseline.jsonNote that no commercial ROM is (or should ever be) committed to the repository, so the list used by CI only contains license-clean ROMs. Point the framework at your own local collection when testing a change.
Alongside the game sweep, CI runs the NESdev test suites — blargg's CPU, PPU,
APU and MMC3 tests, Bisqwit's PPU read-buffer test and kevtris's nestest,
112 ROMs from nes-test-roms.
These do not need any heuristic: they exercise documented hardware behaviour
and report whether they passed, which the framework reads straight out of the
emulated machine (blargg's status byte at $6000, the result byte of his
2005-era runtime at $F8 or $F0, nestest's result bytes at $02/$03).
make -C test-framework testromsThat fetches the ROMs if they are not already there and runs them:
[PASS] m0 16-special.nes
[FAIL] m0 09-even_odd_frames.nes
-> blargg test failed (code 2): FD Pattern ----- should not skip
any clocks 09-even_odd_frames Failed #2
The test ROMs are not stored in this repository. None of them ships a licence, and rNES is BSD-3-Clause, so they are downloaded from a pinned commit on GitHub and verified against a recorded SHA-256 rather than redistributed here. See test-framework/roms/README.md.
Everything CI checks is available as a single target, so a change can be verified before it is pushed:
make -C test-framework check # strict build, unit tests, both ROM suites
make -C test-framework help # list every targetSee the test framework documentation for the complete list of options, the failure heuristics and the CI setup.
Developers are really encouraged to develop and contribute to rNES. For detailed information and porting guide, consult the Developer Documentation.
Source code documentation can be generated with Doxygen:
cd src
make docsThe generated documentation will be available in different formats at src/docs/dist.
Contributions of all kinds are welcome: bug reports, accuracy fixes, new mappers, ports to new platforms and documentation.
Please read CONTRIBUTING.md before opening an issue or a pull request. It covers:
- How to report a game-specific bug in a way that can be acted on.
- The coding style (enforced by clang-format:
cd src && make format-src) and the source file headers. - Commit conventions, including the mandatory
Signed-off-by:line (git commit -s) and how to disclose AI assisted code. - What CI checks on every pull request, and how to test your change.
- Step-by-step guides for adding a new mapper and for porting rNES to a new platform.
Everyone participating in this project is expected to follow the Code of Conduct. Security issues should not be reported in public issues, see SECURITY.md for the private reporting process.


