nes-emu

NesCore

A NES Emulator made in JavaScript for educational purposes. Try it!

Its main objective is to reflect the NES internals as simply as possible by using clean, object-oriented code. It doesn't have any complex bitwise operations, huge switch-case statements or files with lots of magic numbers.

Created by [r]labs.

⚠️ This is not a cycle-accurate emulator and performance is not the main concern.

Features

• 👾 It emulates the NES
• 👨‍🔧 It plays Super Mario Bros. 3!
• 💻 CPU
  • All official instructions are implemented
  • nestest passes ✔️
• Fully functional 🖥️ PPU and 🔊 APU
• 🔌 Supported mappers
  • Mapper 0: NROM
  • Mapper 1: MMC1
  • Mapper 2: UxROM
  • Mapper 3: CNROM
  • Mapper 4: MMC3
• 🐏 SRAM support
• 💾 Save states support
• 🌎 Web frontend with Gamepad support

Usage

npm install --save nes-emu

// configure video and audio:
const onFrame = (frameBuffer) => {
  // write `frameBuffer` (a Uint32Array) to screen...
};
const onSample = (sample) => {
  // write `sample` (a number) to audio buffer...
};

// create an instance:
const nes = new NES(onFrame, onSample);

// load a game:
nes.load(rom); // rom = Uint8Array

// run at 60 fps, or as fast as you can:
{
  nes.setButton(1, "BUTTON_A", true); // player = 1, button = A, pressed = true
  nes.setButton(2, "BUTTON_DOWN", false); // player = 2, button = DOWN, pressed = false
  // ...set the rest of the buttons
  nes.frame();
}

// save / restore states:
const saveState = nes.getSaveState();
nes.setSaveState(saveState);

👀 Have a look at the demo implementation for more details.

Full API

Method	Parameters	Description
constructor	onFrame, onSample, logger	Creates an emulator's instance. All properties can be set at any time.
load	rom, saveFileBytes	Loads a ROM. If a saveFileBytes array is provided, it sets the SRAM content.
frame		Runs the emulation for a whole video frame.
samples	requestedSamples	Runs the emulation until the audio system generates requestedSamples.
scanline		Runs the emulation until the next scanline.
setButton	player, button, isPressed	Sets the button state of player to isPressed. The button can be one of: ["BUTTON_A", "BUTTON_B", "BUTTON_SELECT", "BUTTON_START", "BUTTON_UP", "BUTTON_DOWN", "BUTTON_LEFT", "BUTTON_RIGHT"]
clearButtons	player	Sets all buttons of player to a non-pressed state.
getSaveFile		Returns an array with the SRAM bytes, or null.
getSaveState		Returns an object with a snapshot of the current state.
setSaveState	saveState	Restores a saveState.

Screenshots

Debugging

You can inspect the emulator state by using the global window.debug object.

Also, if you add ?debug to the URL and use a gamepad, shoulder buttons will behave as follows:

2--4
1--3

1: Enter debug mode
2: Exit debug mode
3: Hold to run frame
4: Hold to run scanline

Useful links

• NesDev | Mirror
• NES Emulation Overview | Mirror
• NES Ebook | Mirror
• Easy 6502 | Mirror
• 6502 Reference | Mirror
• NES Rendering | Mirror
• NES Graphics Part 1 | Mirror
• NES Graphics Part 2 | Mirror
• NES Graphics Part 3 | Mirror