Writing An NES Emulator with Rust and WebAssembly
Tags: webassembly, rust, javascript, emulator
Published: 2018-04-11 22:27:49

---
title: Writing An NES Emulator with Rust and WebAssembly
published: true
tags: webassembly,rust,javascript,emulator
canonical_url: 
---

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.

![](https://cdn-images-1.medium.com/max/759/1*FeNjHAjDRrgLw9w5PJ0GgQ.gif)

### **TL;DR**

[Here](https://github.com/bokuweb/rustynes) is the source code. Also, you can play the game in the canvas below

[rustynes](https://bokuweb.github.io/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

![](https://cdn-images-1.medium.com/max/1024/1*NudS1Jxt1STmldYF9n88sg.png)

### 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](https://github.com/koute/stdweb) and [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen) with wasm32-unknown-unknown consider using them It might be good, too.

{% gist https://gist.github.com/bokuweb/583180a945f35091fd4d7bdf2a71f973 %}

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](https://github.com/bokuweb/rustynes/blob/master/main.js#L63)

### 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](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.

{% gist https://gist.github.com/bokuweb/95a955a10871174520c3004cc08dd315 %}

{% gist https://gist.github.com/bokuweb/011a0e8473e237bfe419269c4b19cde0 %}

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

{% gist https://gist.github.com/bokuweb/bffc910f40e273d7a23d1c53ef7446de %}

This is expressed as follows.

{% gist https://gist.github.com/bokuweb/4ceb1b31f05d7452b0e4aa848e89a5a5 %}

#### Memory map

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

{% gist https://gist.github.com/bokuweb/d5759203352b8babc775f4384aa6c14b %}

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

{% gist https://gist.github.com/bokuweb/9fec9d2fcb01cbe557e857a699cd0b40 %}

In addition, the opcode dictionary is created using lazy\_static. That is a very good library.

{% gist https://gist.github.com/bokuweb/02a79abd939c5038351769e2062fc018 %}

### 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).

![](https://cdn-images-1.medium.com/max/800/1*P5Dg-Vr49SgwL31xxI62gg.png)

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

[NES Graphics - Part 1](http://www.dustmop.io/blog/2015/04/28/nes-graphics-part-1/)

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

{% gist https://gist.github.com/bokuweb/31930ab3b86e4aa27146b04f944c9e2b %}

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

{% gist https://gist.github.com/bokuweb/86c512978e915c72dbbac55889d3d1e0 %}

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

{% gist https://gist.github.com/bokuweb/dd21f70b9a1a492365355578abcc3b55 %}

### The Sound

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

{% gist https://gist.github.com/bokuweb/0fc5f72bcf63258c0cf2d64f45ce6cc3 %}

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

{% gist https://gist.github.com/bokuweb/669b0c8daf31500e1556266011d1d69b %}

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

[bokuweb/rustynes](https://github.com/bokuweb/rustynes)

If you want to know deeply, you may want to look at the following.

- [NES Documentation (PDF)](http://nesdev.com/NESDoc.pdf)
- [NES Reference Guide (Wiki)](http://wiki.nesdev.com/w/index.php/NES_reference_guide)
- [6502 CPU Reference](http://www.obelisk.demon.co.uk/6502/)

### Conclusions

I’ve been really impressed with Rust, and I think that it is one very good choice for building on the WebAssembly. A framework for an advanced browser front end like [yew](https://github.com/DenisKolodin/yew) has also been developed and I think that it is also a remarkable language for developers who usually write Javascript.