Skip to content
renePublic

About

Yet another Nintendo Entertainment System emulator

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

rNES logo

rNES - Yet another Nintendo Entertainment System emulator

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.

rNES

How to build

POSIX systems

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
make

To 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

Keyboard controls

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.

Windows (cross-compile)

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-w64

Run the build-win32-cross.sh script to create the build environment:

cd src
./scripts/build-win32-cross.sh

Once the environment is ready, rNES.exe can be built using make:

make -f Makefile.mingw

Tools

Palette Editor

rNES 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
./PaletteEditor

The 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

PaletteEditor interface.

Testing

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-framework

Then run it over a list of ROM paths (one per line, # comments allowed):

python3 test-framework/run_tests.py --rom-list ~/my-roms.txt

Each 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.tool

Results 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.json

Note 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.

Test ROMs

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 testroms

That 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 target

See the test framework documentation for the complete list of options, the failure heuristics and the CI setup.

Developing rNES

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 docs

The generated documentation will be available in different formats at src/docs/dist.

Contributing

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.

About

Yet another Nintendo Entertainment System emulator

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages