joey-wong / nescore

A NES Emulator made in JavaScript for educational purposes.

NesCore

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

It's 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.

⚠️ 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 using Web Workers and Gamepad API

Usage

npm install --save nes-emu

// configure video and audio:
const onFrame = (frameBuffer) => {
  // write `frameBuffer` (an Uint32Array) to screen...
};
const onSample = (sample) => {
  // write `sample` (a number) to audio buffer...
};
const sampleRate = 48000; // set this to system's sample rate

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

// 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. When running the demo (npm start) you can add ?debug to the URL to enable a global window.debug object.

Full API

Method	Parameters	Description
constructor	onFrame, onSample, sampleRate, logger	Creates an emulator's instance. All properties can be set at any time (e.g. nes.sampleRate = newSampleRate).
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

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