@tmustier/pi-nes

pi-nes

Play NES games in your terminal. A pi extension that runs a full NES emulator with Kitty graphics support.

Installation

pi install npm:@tmustier/pi-nes

Or from git:

pi install git:github.com/tmustier/pi-nes

Quick Start

/nes              # Pick a ROM from your library
/nes ~/roms/smb.nes   # Load a specific ROM

On first run, you'll be prompted to set your ROM directory and display quality. When launching /nes without a path, type to filter the ROM list while you navigate.

Controls

Game Controls

Action	Keys
D-pad	Arrow keys or WASD
A button	Z
B button	X
Start	Enter or Space
Select	Tab

Emulator Controls

Action	Key
Detach (keep running)	Ctrl+Q
Quit	Q

Tip: Detach with Ctrl+Q to return to pi, then run /nes to reattach to your game.

Commands

Command	Description
/nes	Pick a ROM or reattach to running session
/nes <path>	Load a specific ROM file
/nes config	Quick setup (ROM directory + audio)
/nes-config	Toggle audio, quality, and display style + advanced options
/nes debug	Show FPS and memory stats

Configuration

Config is stored at ~/.pi/nes/config.json. Use /nes config for quick setup (ROM dir + audio), or /nes-config to toggle audio/quality/style inline and access advanced options.

{
  "romDir": "/roms/nes",
  "saveDir": "/roms/nes/saves",
  "renderer": "image",
  "imageQuality": "balanced",
  "videoFilter": "ntsc-composite",
  "enableAudio": false,
  "pixelScale": 1.0,
  "keybindings": {
    "up": ["up", "w"],
    "down": ["down", "s"],
    "left": ["left", "a"],
    "right": ["right", "d"],
    "a": ["z"],
    "b": ["x"],
    "start": ["enter", "space"],
    "select": ["tab"]
  }
}

Options

Option	Default	Description
romDir	/roms/nes	Where to look for ROM files
saveDir	/roms/nes/saves	Where to store battery saves (defaults to <romDir>/saves)
renderer	"image"	"image" (Kitty graphics) or "text" (ANSI)
imageQuality	"balanced"	"balanced" (30 fps) or "high" (60 fps)
videoFilter	"ntsc-composite"	"off", "ntsc-composite", "ntsc-svideo", "ntsc-rgb"
enableAudio	false	Enable audio output (requires native core built with audio-cpal)
pixelScale	1.0	Display scale (0.5–4.0)

videoFilter applies a lightweight CRT/NTSC-inspired pass (horizontal bleed + scanlines). It runs in the native core and is optional.

Saves

Battery-backed SRAM is saved to <saveDir>/<rom-name>-<hash>.sav where the hash is derived from the full ROM path to avoid collisions. Old <rom-name>.sav files are ignored.

Saves are flushed on quit and periodically during play.

Terminal Support

Best experience: a Kitty-protocol terminal like Ghostty, Kitty, or WezTerm (image protocol + key-up events).

• Kitty-protocol terminals — Full graphics via image protocol (shared memory or file transport)
• Other terminals — Falls back to ANSI half-block characters (▀▄)

Set "renderer": "text" if you prefer the ANSI renderer or have display issues.

Limitations

• Audio is opt-in — Requires building the native core with audio-cpal and setting enableAudio: true
• No auto-save — Save manually just like you would with the original NES (battery-backed SRAM)

Vendored Dependencies

• nes_rust is vendored under extensions/nes/native/nes-core/vendor/nes_rust.
• Fork: https://github.com/tmustier/nes-rust (upstream: https://github.com/takahirox/nes-rust)
• Update helper: scripts/update-vendor-nes-rust.sh

Building from Source

Requires Rust toolchain (cargo + rustc).

git clone https://github.com/tmustier/pi-nes
cd pi-nes
npm install

# Build the NES core (required)
cd extensions/nes/native/nes-core
npm install && npm run build

# Build the NES core with audio (optional)
npm run build:audio

# Build shared memory renderer (optional, faster on Kitty)
cd ../kitty-shm
npm install && npm run build

Run locally:

pi --extension /path/to/pi-nes