pi-extension-gba

Play Game Boy Advance games inside pi — right in your terminal, while the agent works.

When the agent is busy thinking, the game takes over your screen. The moment it turns the conversation back to you, the chat reappears and your keystrokes go back to the prompt. No window switching, no context loss — just Pokémon in the gaps.

---

Why

Agents spend real seconds working. This extension fills that dead time with a full GBA emulator (a WebAssembly build of mGBA) rendered directly in your terminal via the Kitty graphics protocol. It auto-pauses, auto-saves, and auto-resumes around the agent's turns, so playing never interferes with the work.

Features

• Full GBA emulation — real mGBA core, save files (.sav) and save states (.state).
• Seamless hand-off — game shows on agent_start, chat returns on agent_end.
• Plays in your terminal — no separate window; rendered inline with Kitty graphics.
• Optional audio — opt-in, uses whatever audio tool you already have.
• Pick up where you left off — last ROM and state auto-resume on /gba.

Requirements

• pi installed and working.
• A Kitty-graphics terminal — Ghostty, Kitty, or WezTerm. Terminals without Kitty graphics (and bare tmux) are detected and the extension self-disables with a warning instead of printing garbage.
• Your own .gba ROM files — none are bundled. Use ROMs you legally own.
• (Optional) an audio tool — pw-cat, pacat, ffplay, or aplay on your $PATH, only if you want sound.

Install

From GitHub:

pi install git:github.com/WSeubring/pi-extension-gba

From a local checkout:

npm install && npm run build && pi install .

Add a ROM

1. Drop your .gba files into:

   ~/.config/pi/roms/gba/
   

2. In pi, type /gba to open the game picker (or resume your last game).

That's it — pick a ROM and play.

Playing

Type /gba to start. Inside the game, keys route to the emulator:

Key	Button
Arrow keys	D-pad
z	A
x	B
a	L
s	R
Enter	Start
Backspace	Select
alt+g / ctrl+c	Exit game mode

Commands

Command	Effect
/gba	Resume last-played ROM; otherwise open picker (or warn if empty).
/gba list	Always open the ROM picker.
/gba <basename>	Load a ROM directly by filename (.gba suffix auto-appended).
/gba reset	Soft reset current ROM (keeps .sav, discards .state).
/gba mute	Mute audio (when audio is enabled).
/gba unmute	Unmute audio (when audio is enabled).
/gba config	Interactive options menu (scale, frame rate, auto-focus, audio...).
/gba config reset	Wipe ~/.config/pi/gba.json; defaults restored on next activation.

Shortcuts

Shortcut	Effect
alt+g	Toggle full-screen game mode (also exits with ctrl+c).
alt+shift+g	Manual pause/resume — overrides the auto-transitions until the next ROM load.
alt+m	Toggle audio mute (no-op when audio is disabled).

Screenshots

Inline widget rendering while you chat:

The /gba config options menu:

---

Advanced

How the hand-off works

By default the extension auto-enters full-screen game mode on agent_start (with a short debounce so quick replies don't flash the screen) and returns to the chat editor on agent_end.

.state snapshots are written on every pause; .sav SRAM is flushed on every in-game save. Both auto-resume on the next /gba. alt+g remains a manual override — enter game mode during agent_end, or exit mid-agent_start if you need to type context.

Configuration

Persistent settings live in ~/.config/pi/gba.json; tune them via /gba config. Precedence is env var > config file > built-in default.

Environment variables

Scale, frame rate, audio, and the auto-focus/auto-hide behaviour are set in /gba config. The variables below cover modes and diagnostics not exposed there.

Var	Default	Effect
PI_GBA_MINIMAL	unset	1 = minimal mode: widget-only render + invisible input overlay, no lifecycle coupling.
PI_GBA_DEBUG_CORE	unset	1 restores mGBA core stdout traces (diagnostics only).
PI_GBA_RENDER_TRACE	unset	1 logs placement pins + every handleInput byte string to stderr.
PI_GBA_AUDIO_TRACE	unset	1 logs per-tick audio drain stats (samples, stdin backlog).
PI_GBA_FRAME_DUMP	unset	Directory path — dumps a PNG every PI_GBA_FRAME_DUMP_EVERY frames (default 30).

Audio

Audio is opt-in (default false). Toggle it in /gba config. The extension auto-detects an audio tool on your $PATH, first found wins:

Tool	Package (common distros)
pw-cat	pipewire / pipewire-pulse
pacat	pulseaudio-utils
ffplay	ffmpeg
aplay	alsa-utils

If none is found, the extension activates with a one-time warning and falls back to silent mode. No native npm addon is required.

Development

npm run typecheck  # TypeScript type check (no emit)
npm test           # run all unit tests

experiments/ contains the standalone smoke scripts used to de-risk and verify the emulator, render, and audio paths.

License

MIT for this extension (see LICENSE).

The bundled emulator core (vendor/mgba-wasm/dist/) is a custom WebAssembly build of mGBA, licensed under the Mozilla Public License 2.0. The exact source revision, patch set, and a reproducible Docker build are documented in vendor/mgba-wasm/ (README.md + BUILD.md).

ROMs are not included. Use ROMs you legally own.