wasm-nes

NES EMULATOR

wasm-nes

wasm-nes — a Rust-written NES (Nintendo Entertainment System / Famicom) emulator compiled to WebAssembly for use in web pages and JavaScript projects.

Jump to download ↓Jump to setup guide ↓

wasm-nes emulator screenshot.

nesPRIMARY SYSTEM

History documentedPROJECT BEGAN

Open sourcePROJECT MODEL

WHY IT MATTERS

Why try wasm-nes?

wasm-nes provides a compact, Rust-based NES implementation compiled to WebAssembly so it can be embedded in web pages or consumed as a JS/WASM package. It aims to cover the CPU, PPU and common mappers, expose an easy JS API, and include test-suite results so developers can evaluate accuracy and limitations quickly.

BEST FOR

Best for

Developers who want an embeddable WASM NES core for web demos, learning or integration into web frontends; projects where bundling a small Rust → WASM NES implementation as an ES module is useful.

Gameplay from The Legend of Zelda on NES.

The people behind wasm-nes

History & status

The project is hosted on GitHub (kabukki/wasm-nes). The README documents design goals and test results against common NES test ROMs. The codebase is written in Rust and compiled to WebAssembly using wasm-pack and wasm-bindgen. The repository shows ongoing development activity and a modest number of stars. The README lists implemented components (full CPU opcode set, PPU, input support), multiple supported mappers (NROM, MMC1, UxROM, CNROM, AxROM, GxROM and others), and known limitations — notably incomplete APU implementation and imperfect PPU timing and sprite handling. The repository provides test-suite results showing partial pass coverage against standard NES emulator tests, and describes a development toolchain requiring Rust and wasm-pack.

What wasm-nes supports

Web browsers (WebAssembly / ES module integration)
JavaScript/TypeScript projects that can import the emitted ES module
Can be built locally with Rust/wasm-pack for custom integrations
Examples in the repo demonstrate embedding in a web page; not a native desktop emulator distribution

Download and availability

OFFICIAL DOWNLOADS

Get wasm-nes

Official releases and source are available on the project's GitHub repository and Releases page. You can either clone the repository and build locally, or consume the packaged JS/WASM output as distributed by the project (ES module).

Get wasm-nes ↗

DOCUMENTATION

Official documentation

Read the official configuration, compatibility, and troubleshooting material before changing advanced options.

Read official documentation ↗

Broken or missing download? Emulator projects move and official links sometimes change. Please contact Retro Replay so the source can be verified and updated.

wasm-nes setup guide

Setup note: Practical setup notes — wasm-nes is primarily intended to run in browsers or JS environments that can load a WebAssembly ES module. Below are concrete setup paths: use the prebuilt release (if present), install and import the package in a web project, or build from source with the Rust toolchain and wasm-pack.

Option A — Use the published package / release: Check the project's Releases page and the repository for a prebuilt .wasm + JS wrapper. If a packaged ES module is published, download the release artifacts and place them in your web project. Serve the files from a web server (browsers generally block WASM when opened directly from file://). In your page or bundle import the emitted ES module, call init(), then construct Emulator and load a .nes ROM (Uint8Array). Example (from README): import init, { Emulator } from '@kabukki/wasm-nes'; init().then(() => { const emulator = new Emulator(); document.getElementById('input').addEventListener('change', async (e) => { const buffer = await e.target.files[0]?.arrayBuffer(); emulator.load(new Uint8Array(buffer)); emulator.start(); }); }).catch(console.error);
Option B — Install via npm (consume as module): If you prefer to consume the project as an npm/JS package, add it to your package.json or install with your package manager if published (the README demonstrates import from '@kabukki/wasm-nes'). After installation, import the module as an ES module in your app, call the init() entry function to instantiate the WebAssembly module, then create Emulator instances. Ensure your bundler is configured to correctly handle .wasm files or preserve the emitted JS wrapper as an ES module.
Option C — Build from source (recommended if you want the latest or to modify code): Prerequisites: Rust toolchain (rustup), wasm-pack, and Node.js for the frontend examples. From a shell: 1) git clone https://github.com/kabukki/wasm-nes.git 2) Change into the repository. 3) Follow the repo's Development instructions: use wasm-pack (which uses wasm-bindgen) to compile the Rust backend into a .wasm + JS wrapper (the README describes the toolchain). 4) Use the provided frontend/examples to run a local development server that serves the produced module. Note: building requires a working wasm-pack setup and an up-to-date Rust toolchain.
Loading ROMs and starting emulation: wasm-nes expects a standard .nes ROM image provided as an ArrayBuffer/Uint8Array. Use a file input or fetch the ROM from a server, then pass the Uint8Array to emulator.load(). Call emulator.start() to begin running frames. The README demonstrates a minimal flow using requestAnimationFrame-driven timing; the emulator synchronizes frames to the browser repaint.
Controller input, save states and debugging: The emulator exposes controller input support and save-state functionality where cartridge RAM is present. The project also provides debugging hooks (readme lists a useDebug hook that exposes logs and internal state) and test-suite logs (nestest-compliant logs are emitted). Consult the repo examples for wiring keyboard/gamepad input to the emulator API.
Accuracy, limitations and testing: wasm-nes documents its test coverage against public NES emulator test ROMs. The README shows detailed test results: CPU tests are partially passing, PPU and APU test coverage is incomplete, and some timing and sprite issues remain. Use the project's test summaries to judge whether it meets your compatibility needs before relying on it for specific commercial ROMs or accuracy-sensitive tasks.
Platform notes & deployment: wasm-nes is intended for the web (modern browsers) and JavaScript environments that can load WASM ES modules. Running it in Node.js may require bundler/runtime configuration to load WebAssembly and handle the ES module wrapper. Do not expect a native desktop binary — the repo focuses on WASM output and in-browser usage.

Software reminder: This project does not include NES game ROMs, BIOS files or other copyrighted firmware. You must supply your own legally obtained .nes files for use with the emulator.