https://github.com/tmustier/pi-nes
https://github.com/tmustier/pi-nes
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/tmustier/pi-nes
- Owner: tmustier
- License: mit
- Created: 2026-01-27T00:42:19.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-01-27T02:44:30.000Z (4 months ago)
- Last Synced: 2026-01-27T12:15:26.476Z (4 months ago)
- Language: TypeScript
- Size: 40 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# pi-nes
Play NES games in your terminal. A [pi](https://github.com/mariozechner/pi) extension that runs a full NES emulator with Kitty graphics support.
## Installation
```bash
pi install npm:@tmustier/pi-nes
```
Or from git:
```bash
pi install git:github.com/tmustier/pi-nes
```
## Quick Start
```bash
/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 ` | 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.
```json
{
"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 `/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) |
## Saves
Battery-backed SRAM is saved to `/-.sav` where the hash is derived from the full ROM path to avoid collisions. Old `.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
- **No audio** — Sound is not currently supported
- **No save states** — Only battery-backed SRAM saves work
---
## Building from Source
Requires Rust toolchain (cargo + rustc).
```bash
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:
```bash
pi --extension /path/to/pi-nes
```