Writing An NES Emulator with Rust and WebAssembly

bokuweb — Wed, 11 Apr 2018 14:30:56 +0000

I wrote the NES emulator with Rust and WebAssembly to learn Rust. It’s not perfect and have some audio bugs, but it’s good enough to play Super Mario bros.

TL;DR

Here is the source code. Also, you can play the game in the canvas below

rustynes

The Nintendo Entertainment System (NES)

The Nintendo Entertainment System (NES) was the world’s most widely used video games.

CPU 6502(RP2A03), 8bit 1.79MHz
PPU Picture Processing Unit RP2C02
ROM ProgramROM:32KiB + CharactorROM:8KiB
WRAM WorkingRAM 2KiB
VRAM VideoRAM 2KiB
Color 52color
Resolution 256x240pixles
Sound Square1/2, Triangle, Noise, DPCM
Controller Up, Down, Left, Right, A, B, Start, Select

I had to emulate the above specs with WebAssembly and browser features.

Emulator Structure

Building WebAssembly with Rust

I used wasm32-unknown-emscripten to convert Rust to WebAssembly. Because I did not have wasm32-unknown-unknown when I started this project, since there are now great libraries such as stdweb and wasm-bindgen with wasm32-unknown-unknown consider using them It might be good, too.

The most important of these are NO_EXIT_RUNTIME and EXPORTED_FUNCTIONS. NO_EXIT_RUNTIME is used to freeze the memory on the Rust side to use it from the JavaScript side. Without this setting, memory will be freed and unexpected behavior will occur.

EXPORTED_FUNCTIONS is used to specify the function to export to the Javascript side. Actually it is invoked from JavaScript side as follows.

bokuweb/rustynes

The Game loop

NES works at 60 FPS. It means that It is necessary to refresh the screen every 16 ms. So I used emscripten_set_main_loop for this. If 0 or negative value is used as the second argument, requestAnimationFrame will be used internally. (See. https://kripken.github.io/emscripten-site/docs/api_reference/emscripten.h.html#c.emscripten_set_main_loop)

I wanted to use closure so I struggled and finally wrote it as follows.

The CPU

The NES used the MOS6502 (at 1.79 MHz) as its CPU. The 6502 is an 8bit microprocessor.The 6502 had relatively few registers (A, X & Y) and they were special-purpose registers.

Registers

The stack pointer needs to point to a 16bit address space, but the upper 8 bits are fixed to 0x01. 256 bytes are available for the stack( 0x0100 to 0x01FF) in WRAM is allocated. That is, if the stack pointer register is 0xA0, the stack pointer is 0x01A0.

This is expressed as follows.

Memory map

The Program ROM is 0x8000~, The WRAM is mapped from 0x0000~0x07FF, and the PPU register is mapped to 0x2000~.

How to emulate CPU

The 6502 does not have a pipeline structure like a recent CPU, and can be emulated simply by repeating fetching, decoding, and execution from Program ROM.

In addition, the opcode dictionary is created using lazy_static. That is a very good library.

The PPU (Picture Processing Unit)

The PPU reads the sprite information from the cartridge and constructs the screen. So the data bus of the PPU is directly connected to the cartridge.

Sprites are 8 x 8 or 8 x16 pixels as follows, PPU places sprites based on data set in VRAM. (Below is the output of Super Mario Bros. sprite data).

Please refer to the following article for details about the NES graphic.

NES Graphics - Part 1

After generating data for one screen from VRAM data and sprite information, I emulated game screen by drawing on Canvas.

canvas_render is Javascript side code. If you are using emscriptenyou will be able to call on the Rust side via mergeInto.

The game Pad

The game pad emulated using keydownEvent. Specifically, the following handlers are registered at initialization, and specific bytes of ArrayBuffer are written at keyDown / keyUp. This is because, from the viewpoint of Browser, the memory on the Rust side can be handled as ArrayBuffer.

The Sound

Just like Canvas, we used mergeInto to invoke Javascript code using WebAudio API from Rust side.

As an example, the waveform is generated using the WebAudio API as follows

Although we omitted it considerably, we implemented NES Emulator with Rust and WebAssembly like this. The whole code please see the following repositry.