neskimo

A bare-bones NES emulator written in Rust.

Notes

Notes on general NES system architecture can be found at NES_NOTES.md.

Notes on implementation options and Rust in general can be found at IMPLEMENTATION_NOTES.md.

Running

Currently the only way to run neskimo is to build it from source. Once the project is further along, I hope to provide pre-built binaries or installers.

Clone the GitHub repo

First, ensure that you have Git installed.

Next, run the following command to pull the source code from GitHub onto your local machine:

git clone https://github.com/patlillis/neskimo
cd neskimo

Install SDL

The windowing part of neskimo relies on the SDL framework, which must be installed separately.

MacOS

If building on a Mac, SDL can be installed easily through homebrew using the following command:

brew install sdl2

Windows & Linux

Follow the installation instructions on the rust-sdl2 GitHub page.

Install Cargo

Since neskimo is written using Rust, the easiest way to build it is using Cargo.

Build

You should now be ready to build the project. Run one of the following commands from the neskimo directory:

cargo build  #Build with the "dev" profile, best suited for development or debugging.
cargo build --release  #Build with the "release" profile, optimized for release builds.

Run!

Binaries from cargo build and cargo build --release are built to target/debug/neskimo and target/release/neskimo, respectively.

Note that you need to pass a .nes ROM file for neskimo to run. A few test ROMs are provided in the GitHub repo, in the test_roms directory.

Run neskimo --help to see full usage instructions:

neskimo (version)
Pat Lillis <[email protected]>
A bare-bones NES emulator written in Rust.

USAGE:
    neskimo [FLAGS] [OPTIONS] <ROM>

FLAGS:
    -f, --fps        Print frames-per-second during emulator run
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -l, --logfile <LOGFILE>                    Writes the CPU log to a file
    -d, --mem-dump <PROGRAM COUNTER>           When executaion reaches this point, contents of memory will be written to mem_dump.bin
    -p, --program-counter <PROGRAM COUNTER>    Sets the initial program counter to the provided hex value

ARGS:
    <ROM>    The .nes ROM file to run

EXAMPLES:
    neskimo mario.nes
    neskimo -l=testing.log donkey_kong.nes
    neskimo -p=C000 castlevania.nes
    neskimo --logfile=testing.log --program-counter=0F00 my-cool-game.nes

Inspiration

Inspiration drawn from these fantastic projects:

• Nintengo by Niels Widger (written in Go)
• nes-rs by Walter Kuppens (written in Rust)
• sprocketnes by Patrick Walton (written in Rust)
• pinky by Koute (written in Rust)
• oxidenes by iamsix (written in Rust)

License

Code licensed MIT. © 2019 Pat Lillis.