terminal_gameboy
| Crates.io | terminal_gameboy |
| lib.rs | terminal_gameboy |
| version | 0.1.0 |
| created_at | 2026-01-04 22:59:20.108521+00 |
| updated_at | 2026-01-04 22:59:20.108521+00 |
| description | A terminal-based Game Boy emulator with ASCII and block rendering modes |
| homepage | |
| repository | https://github.com/dquigles/terminal_gameboy |
| max_upload_size | |
| id | 2022713 |
| size | 517,947 |
Dillon Quigley (dquigles)
documentation
README
Terminal GameBoy
A rust, terminal-based Game Boy and Game Boy Color emulator with ASCII art and block rendering modes. Play your favorite retro games right in your terminal!
Utilizes gameboy_core for the emulator, providing input & output directly to the emulator.
Features
- Two rendering modes:
- ASCII mode — Classic ASCII art using brightness characters
- Block mode — Unicode half-block characters for higher fidelity
- Audio support — Full sound emulation via rodio
- Save states — Automatic save/load for games with battery backup
- Interactive menu — ROM browser when launched without arguments
- Cross-platform — Works on macOS, Linux, and Windows
Installation
From crates.io
cargo install terminal_gameboy
From source
git clone https://github.com/dquigles/terminal_gameboy.git
cd terminal_gameboy
cargo build --release
The binary will be at target/release/terminal_gameboy.
Usage
Interactive Mode
Simply run without arguments to get an interactive ROM browser:
terminal_gameboy
Command Line
terminal_gameboy <rom_file.gb> [OPTIONS]
Options
| Flag | Description |
|---|---|
--ascii |
ASCII art mode with brightness characters (default) |
--block |
Unicode block mode with solid half-blocks |
--mute |
Disable audio output |
--help |
Show help message |
Examples
# Run with ASCII rendering (default)
terminal_gameboy pokemon.gb
# Run with block rendering
terminal_gameboy pokemon.gb --block
# Run without sound
terminal_gameboy pokemon.gb --mute
Rendering Modes
ASCII Mode — uses brightness characters for a classic terminal look:
Block Mode — uses Unicode half-blocks for higher fidelity:
Controls
| Key | Action |
|---|---|
| Arrow keys | D-Pad |
| Z | A button |
| X | B button |
| Enter | Start |
| Space | Select |
| Q / Esc | Quit |
Terminal Requirements
For the best experience:
- Use a terminal with true color support (24-bit color)
- A monospace font is required
- Recommended terminal size: 162×74 or larger
- Terminals with keyboard release event support (Ghostty, Kitty, WezTerm) provide better input handling
Tested Terminals
| Terminal | Status |
|---|---|
| Ghostty | ✅ Excellent |
| Kitty | ✅ Excellent |
| WezTerm | ✅ Excellent |
| iTerm2 | ✅ Good |
| Terminal.app | ⚠️ Unplayable, block mode has weird tearing |
| Windows Terminal | ✅ Good |
ROM Files
This emulator requires Game Boy (.gb) or Game Boy Color (.gbc) ROM files. You must provide your own legally obtained ROM files.
Save Files
Save files are automatically stored in a .saves/ directory next to the ROM file. The emulator automatically loads saves on startup and saves on exit.
License
MIT License — see LICENSE for details.
Acknowledgments
Built with:
- gameboy_core — Game Boy emulation
- crossterm — Terminal handling
- rodio — Audio playback