Skip to content
Projects

hulkholden/n64js has 658 GitHub stars and 86 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 23:45 UTC. Last push 2026-11-14.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

An n64 emulator in JavaScript

Developer Tools

README.md

Original

n64js

n64js is a Nintendo 64 emulator written in modern JavaScript that runs directly in your browser. It runs many ROMs at full framerate.

Why?

Mostly for the challenge. I've spent ~25 years (on and off) working on N64 emulators and writing one in JavaScript gives me the opportunity to expand my comfort zone and learn something new. It's a good showcase for how powerful modern browsers have become.

How To Run

A hosted version is available on GitHub Pages at https://hulkholden.github.io/n64js/.

Click Load in the toolbar and choose a local N64 ROM file (.z64, .v64, or .n64). ROMs and save data stay locally in your browser.

Controls

n64js supports both the keyboard and standard gamepads (via the browser's Gamepad API).

N64 Input Keyboard Standard Gamepad
Analog Stick Arrow keys Left Stick
Start A Start
A S Bottom face button (A / Cross)
B X Right face button (B / Circle)
Z Z or Y Right Trigger (R2 / RT)
L / R C / V Left / Right Bumper (L1 / R1)
D-Pad T / F / G / H D-Pad
C-Buttons I / J / K / L Hold Left Trigger (L2 / LT) + face buttons

Graphics and Display Options

Display settings are available in the floating options panel under Graphics:

  • Internal Render Scale defaults to 1×, using the VI source resolution (often 320×240). Increase it (up to 4×) for higher-resolution 3D geometry.
  • Canvas Scale controls the output display resolution independently of internal rendering. The final presentation pass upscales the frame and applies CRT effects at the canvas resolution. Use 1× internal rendering for a native-pixel CRT look; 2× gives 640×480 rendering for a 320×240 game. Progressive CPU framebuffers also upload native pixels; interlaced CPU video retains field weaving.
  • CRT offers Off (default), Simple, or Mattias effects applied to the finished frame. Mattias adds colour separation, spatial ghosting, adjustable curvature, and animated scanlines that pause with emulation.

The Mattias style follows MattiasCRT by Mattias Gustavsson. Its implementation is adapted from his MIT-licensed crtemu_pc.h. The attribution and full MIT notice are retained in crt_mattias.glsl, including in the bundled shader source. This adaptation uses the current frame for ghosting and omits the original library's temporal blur buffers and frame overlay.

Audio

High-level audio emulation (HLE) is used by default for supported microcodes, derived from captured RSP disassembly and libultra headers:

  • ABI1 variants including Super Mario 64, Tetrisphere, GoldenEye 007, Diddy Kong Racing, and Blast Corps.
  • NAUDIO variants including Army Men: Air Combat, Banjo-Kazooie, and Donkey Kong 64.
  • NEAD variants including Mario Kart 64, Star Fox 64, Shindou editions of Super Mario 64 and Wave Race 64, Yoshi's Story, 1080° Snowboarding, Ocarina of Time, Majora's Mask, Pokémon Stadium 2, F-Zero X, and Animal Forest.

Unreviewed microcode identities and command shapes automatically fall back to low-level RSP emulation (LLE). Select Audio → Emulation Mode → LLE in the options panel to run all audio tasks on the RSP.

Compatibility

Compatibility has improved significantly across CPU, graphics, audio, and timing. Over 95% of n64-systemtest tests pass.

The main areas where system tests or games still run into limitations are:

  • Graphics: Graphics are primarily rendered using WebGL high-level emulation (with experimental LLE RDP support). Many games are playable, though some microcodes (such as Factor 5's custom microcodes) or hardware-specific framebuffer effects still have unimplemented features or visual glitches.
  • Cycle timing: Instruction timing is still an approximation rather than cycle-accurate, which can affect timing-sensitive games.
  • Edge-case CPU/FPU behaviour: Some 64-bit addressing edge cases and floating-point rounding near numerical limits are not fully emulated.

Indiana Jones and Battle for Naboo automatically use low-level RSP execution for their custom graphics microcodes, including when HLE graphics is selected. Their output uses the experimental RDP renderer and requires more CPU work than HLE graphics.

Performance

With dynamic CPU recompilation and HLE graphics/audio, most games run at full framerate on modern desktop hardware (tested primarily on Apple Silicon Macs). Games that fall back to LLE audio or experimental LLE graphics require significantly more CPU/GPU work.

Browser Compatibility

Saving and loading require native Uint8Array.prototype.toBase64() and Uint8Array.fromBase64() support: Chrome/Edge 140+, Firefox 133+, or Safari 18.2+ (including iOS). See browser compatibility. WebGL is also required.

Chrome is the preferred browser and typically offers the best performance.

Implementation Status

  • CPU
    • Interpreter & dynamic recompiler (JIT)
    • COP0 instructions
    • COP1 (FPU) instructions
    • TLB
    • Cycle accuracy
  • RSP
  • Controller
    • Static key bindings
    • Configurable bindings
    • Gamepad API
  • Graphics
    • HLE (GBI0, GBI1, GBI2, S2DEX, L3DEX, Turbo3D, T3DUX, ZSortp)
    • LLE (experimental RDP support)
  • Audio
    • HLE (supported ABI1, NAUDIO, and NEAD microcodes)
    • LLE
  • Save
    • Persistence (via localStorage)
    • Import/Export
    • MemPack (Controller Pak)
    • EEPROM 4K & 16K
    • SRAM
    • FlashRAM

TODOs

Here are some things I'd like to get around to:

  • Continue fixing graphics issues and expanding microcode coverage
  • Configurable controller bindings
  • Save game import/export
  • Savestates

Development

See DEVELOPMENT.md for instructions on building locally, running tests and headless scripts, querying ROM inventories, CI workflows, and publishing. See BENCHMARKS.md for benchmarking and profiling instructions.

History

n64js is derived from Daedalus, an emulator I started working on around 1999 and continued working on periodically for many years. Around 2012 I made a bet with @mmalex that I could write a port in JavaScript, and n64js was born!