pi-boy

A Game Boy / Game Boy Color emulator stuffed directly into the pi terminal UI.

This is a goofy side project. It is not serious. It is not trying to become the One True Emulator Experience. It exists because putting a Game Boy inside pi sounded funny, and then it worked.

Under the hood, pi-boy uses mGBA plus a tiny native bridge for video and audio. On the surface, it lets you launch a ROM in your terminal and feel mildly delighted that this is a thing you can do.

Why pi-boy?

Because why not?

More specifically:

• because playing Game Boy in a terminal is inherently funny
• because pi can render it inline, which makes the whole thing even sillier
• because side projects are allowed to be a little unhinged
• because opening a normal emulator window would have been far less entertaining

What it does

• plays .gb and .gbc ROMs inside pi
• uses mGBA through a bundled native bridge in mgba-bridge/
• renders with Kitty images when available
• falls back to ANSI rendering when Kitty is not available
• supports inline and overlay display modes
• lets you set a ROM directory and selected ROM from settings
• includes a built-in self-test
• lets you toggle audio on and off with M
• tries to recover automatically if the bridge dies in a recoverable way

What you need

• Node.js + npm
• a pi environment that loads this repo as an extension
• your own legally owned .gb or .gbc ROMs
• native build tools for the bundled mGBA bridge:
  • cc
  • make
  • rsync

Nice to have:

• a Kitty-compatible terminal for prettier rendering
• ffplay for the most reliable audio on macOS

The bundled bridge currently builds around the macOS-style mgba_libretro.dylib, so the default path is most at home on macOS right now.

Install

From npm with pi

pi install npm:@patleeman/pi-boy

Then reload or restart pi. The extension will expose the /pi-boy:* commands.

From source

1. Install dependencies:

   npm install

2. Optional: build the native bridge now instead of waiting for first launch:

   npm run build:mgba

3. Launch pi from this repo so it discovers the extension via package.json.

Get it running

1. In pi, open the setup menu:

   /pi-boy:settings

2. Set a ROM directory and choose a ROM.

3. Start the tiny terminal handheld dream:

   /pi-boy:start

Audio starts muted by default. Press M while playing if you want the full chaos.

Commands

| Command | Description | | --- | --- | | /pi-boy:settings | Open the interactive settings menu for ROM directory, selected ROM, audio backend, render mode, ANSI block mode, overlay mode, and self-test. | | /pi-boy:start | Start pi-boy with the current ROM selection (and auto-resume if a suspend state exists). | | /pi-boy:clear_suspend [path] | Delete a ROM's suspend state. Without an argument, it opens a picker listing all suspend states. |

Controls

| Input | Action | | --- | --- | | Arrow keys or W A S D | D-pad | | Z or J | B | | X or K | A | | Enter or P | Start | | Tab or Backspace | Select | | M | Toggle audio | | Q or Esc | Quit and suspend progress |

Settings and config

pi-boy stores persistent data at:

• ~/.config/pi-boy/config.json (settings)
• ~/.config/pi-boy/states/*.state (auto suspend/resume states)

Most people should just use /pi-boy:settings. It can manage:

• ROM directory
• selected ROM
• audio backend (auto, speaker, ffplay)
• render mode (auto, ansi)
• ANSI block mode (half, quarter)
• overlay mode (inline, overlay)
• self-test
• clearing the saved ROM
• resetting all saved settings

Environment overrides

Environment variables are optional. If you like configuring things the hard way, these override saved settings where applicable.

| Variable | Effect | | --- | --- | | PI_BOY_ROM_PATH | Default ROM path when no command argument is provided. | | PI_BOY_FORCE_ANSI=1 | Force ANSI rendering. | | PI_BOY_ANSI_BLOCK_MODE | Set ANSI block mode to half or quarter. | | PI_BOY_AUDIO_BACKEND | Set audio backend preference to auto, speaker, or ffplay. | | PI_BOY_FORCE_OVERLAY=1 | Force overlay mode instead of inline rendering. | | PI_BOY_MGBA_BRIDGE_BIN=/absolute/path/to/pi-boy-mgba-bridge | Use a custom mGBA bridge binary. | | PI_BOY_MGBA_BRIDGE_REBUILD=1 | Rebuild the bundled bridge on the next start. |

Rendering and audio weirdness

• auto render mode prefers Kitty image rendering when available.
• iTerm defaults to ANSI mode because image rendering is unstable there.
• quarter ANSI mode gives more detail, but is usually slower than half mode.
• Inline mode is the default; overlay mode is available from settings or via PI_BOY_FORCE_OVERLAY=1.
• Audio is opt-in and starts muted.
• Audio backend order:
  • macOS auto: ffplay → speaker
  • other platforms auto: speaker → ffplay

How this nonsense works

pi-boy uses mGBA as its only emulator core.

The repo includes a native sidecar in mgba-bridge/ that:

• builds the bundled libretro mGBA core
• exposes a local pi-boy-mgba-bridge executable
• streams video and audio back to the TypeScript extension

If the bridge exits in a recoverable way, pi-boy tries to restart it and reload the current ROM automatically.

If you want to tinker with it

| Command | Purpose | | --- | --- | | npm run typecheck | Run TypeScript type checking. | | npm test | Run tests. | | npm run build:mgba | Build the bundled mGBA bridge manually. | | PI_BOY_TEST_ROM=/absolute/path/to/game.gb npm run test:smoke | Run the real-ROM smoke test. |

Notes

• pi-boy does not bundle ROMs.
• Only compatible .gb and .gbc ROMs are supported.
• The self-test lives inside /pi-boy:settings.
• Exiting with Q/Esc auto-suspends. Resume with /pi-boy:start.
• Use /pi-boy:clear_suspend to delete suspend state when you want a clean start.
• This project is for fun, which is honestly the main feature.

License

MIT