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.

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 | Configure ROM directory and quality | | /nes debug | Show FPS and memory stats |

Configuration

Config is stored at ~/.pi/nes/config.json. Use /nes config for quick setup.

{
  "romDir": "/roms/nes",
  "saveDir": "/roms/nes/saves",
  "renderer": "image",
  "imageQuality": "balanced",
  "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) | | pixelScale | 1.0 | Display scale (0.5–4.0) |

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

• No audio — Sound is not currently supported
• No save states — Only battery-backed SRAM saves work

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 shared memory renderer (optional, faster on Kitty)
cd ../kitty-shm
npm install && npm run build

Run locally:

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