Skip to main content

A terminal frontend for gambatte game boy color emulator

Project description

gambatte-terminal

A terminal front-end for gambatte, the gameboy color emulator.

It supports:

  • 16 colors, 256 colors and 24-bit colors terminal
  • Playing audio from the emulator
  • Using TAS input files as game input
  • Using keyboard presses as game input

Installation

Wheels are available on linux, windows and macos for python 3.6, 3.7, 3.8 and 3.9:

$ pip3 install gambaterm

Usage and arguments

Usage:

usage: gambaterm [-h] [--input-file INPUT_FILE] [--frame-advance FRAME_ADVANCE] [--break-after BREAK_AFTER] [--speed-factor SPEED_FACTOR] [--force-gameboy]
                 [--skip-inputs SKIP_INPUTS] [--cpr-sync] [--disable-audio] [--color-mode COLOR_MODE]
                 ROM

Positional arguments:

  • ROM

    Path to a GB or GBC rom file

Optional arguments:

  • --input-file INPUT_FILE, -i INPUT_FILE

    Path to a bizhawk BK2 input file

  • --frame-advance FRAME_ADVANCE, --fa FRAME_ADVANCE

    Number of frames to run before displaying the next one (default is 1)

  • --break-after BREAK_AFTER, --ba BREAK_AFTER

    Number of frames to run before forcing the emulator to stop (doesn't stop by default)

  • --speed-factor SPEED_FACTOR, --sf SPEED_FACTOR

    Speed factor to apply to the emulation (default is 1.0 corresponding to 60 FPS)

  • --force-gameboy, --fg

    Force the emulator to treat the rom as a GB file

  • --skip-inputs SKIP_INPUTS, --si SKIP_INPUTS

    Number of frame inputs to skip in order to compensate for the lack of BIOS (default is 188)

  • --cpr-sync, --cs

    Use CPR synchronization to prevent video buffering

  • --enable-controller, --ec

    Enable game controller support

  • --disable-audio, --da

    Disable audio entirely

  • --color-mode COLOR_MODE, -c COLOR_MODE

    Force a color mode (1: 4 greyscale colors, 2: 16 colors, 3: 256 colors, 4: 24-bit colors)

SSH server

It is possible to serve the emulation though SSH, although clients won't be able to send input to the emulator without an X server and the ssh -X option. Use gambaterm-ssh --help for more information.

Terminal support

Not all terminals will actually offer a pleasant experience. The main criteria are:

  • Support for basic ANSI codes (VT100) More specifically setting background/foreground colors and moving cursor (absolute and relative). Those are usually supported.

  • Support for at least 256 colors Those are usually supported. 16 colors also works but it doesn't look too good. In this case, it might be better to use greyscale colors using --force-gameboy or --color-mode=1.

  • Support for UTF-8 and good rendering of unicode block elements More specifically the following characters ▄ █ ▀. Changing the code page might be necessary on windows, using chcp 65001. Also, the alignement might be off (e.g small spaces between pixels) This is not always well supported.

  • Good rendering performance The terminal has to be able to process about 500KB of requests per seconds for a smooth rendering of "intense" frames. Typically, the most intense frames happen during screen transitions of two detailed scenes.

The table below sums up my findings when I tried a the most common terminal emulators. Here's about linux:

Linux Status Colors Unicode rendering Performance Comments
Gnome terminal Excellent 24-bit colors Good 60 FPS
Terminator Excellent 24-bit colors Good 60 FPS
Kitty Excellent 24-bit colors Good 60 FPS
XTerm Good 24-bit colors Good 60 FPS No resize shortcuts
Termit Ok 24-bit colors Good 60 FPS No window title
Rxvt Ok 256 colors Good 60 FPS No resize shortcuts
Mlterm Ok 24-bit colors Light misalignments 60 FPS No resize shortcuts
Terminology Ok 24-bit colors Possible misalignments 30 FPS Weird colors

About MacOS:

MacOS Status Colors Unicode rendering Performance Comments
iTerm2 Good 24-bit colors Good 30 FPS
Terminal Unplayable 256 colors Misalignments 20 FPS

About Windows:

Windows Status Colors Unicode rendering Performance Comments
Windows terminal Unpleasant 24-bit colors Good (chcp 65001) 30 FPS Buggy display
Cmder Unplayable 24-bit colors Good (chcp 65001) 2 FPS No window title
Terminus Unplayable 24-bit colors Misalignments 10 FPS
Command prompt Broken N/A N/A N/A No ANSI code support
Git bash Broken N/A N/A N/A Doesn't work with winpty

Terminal size

The emulator uses a single character on screen to display two vertically aligned pixels, like so ▄▀. The gameboy being 160 pixels wide over 144 pixels high, you'll need your terminal to be at least 160 characters wide over 72 characters high to display the entire screen. Setting the terminal to full screen is usually enough but you might want to tweak the character size, typically using the ctrl - / ctrl + or ctrl wheel shortcuts.

Keyboard, game controller and file inputs

Keyboard controls are enabled by default, while game controller controls have to be enabled using --enable-controller or --ec. The key bindings are not configurable at the moment:

Buttons Keyboard Controller
Directions Arrows Left hat / Left stick
A F / V / Space Button 0 / Button 3
B D / C / Alt Button 1 / Button 2
Start Right Ctrl / Enter Button 7
Select Right Shift / Delete Button 6

Key releases, which are usually mandatory to play games, cannot be detected through stdin. It is then required to access the window system to get access to the key presses. There are a couple of problems with that:

  • It can be hard to detect the window corresponding to the terminal. With X11, the best solution is to look for the current focused window. For other systems, the fallback solution is to use global hotkeys.

  • It only works through SSH for clients with X servers using ssh -X, meaning it requires Windows and MacOS users to run an X server. Moreover, it's a bad idea to connect with -X to an untrusted server.

  • Additional permissions might be required to access the window system, especially on MacOS (see this guide)

It is also possible to use a bizhawk BK2 input file to play tool-assisted speedruns using the --input-file (or -i) option.

Motivation

To be honest there is no actual reason to use this gameboy emulator, other than you might find it fun or interesting. The motivation behind this project is simply to push the idea of running a video game console emulator in a terminal as far as possible. It seems like there has been a similar attempt that used a different approach for displaying the video stream. In any case I'm quite satisfied with this project, and also a bit surprised that I could push it to the point where playing games is actually enjoyable. In particular, I've been able to complete The Bouncing Ball at 60 FPS in XTerm, and I'm now looking forward to playing more homebrew games :)

Dependencies

Here is the list of the dependencies used in this project, all great open source libraries:

Contact

Vincent Michel

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gambaterm-0.11.0.tar.gz (141.6 kB view details)

Uploaded Source

Built Distributions

gambaterm-0.11.0-cp311-cp311-win_amd64.whl (165.0 kB view details)

Uploaded CPython 3.11 Windows x86-64

gambaterm-0.11.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

gambaterm-0.11.0-cp311-cp311-macosx_10_9_x86_64.whl (214.9 kB view details)

Uploaded CPython 3.11 macOS 10.9+ x86-64

gambaterm-0.11.0-cp310-cp310-win_amd64.whl (165.9 kB view details)

Uploaded CPython 3.10 Windows x86-64

gambaterm-0.11.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.10 manylinux: glibc 2.17+ x86-64

gambaterm-0.11.0-cp310-cp310-macosx_10_9_x86_64.whl (215.2 kB view details)

Uploaded CPython 3.10 macOS 10.9+ x86-64

gambaterm-0.11.0-cp39-cp39-win_amd64.whl (165.9 kB view details)

Uploaded CPython 3.9 Windows x86-64

gambaterm-0.11.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.9 manylinux: glibc 2.17+ x86-64

gambaterm-0.11.0-cp39-cp39-macosx_10_9_x86_64.whl (215.2 kB view details)

Uploaded CPython 3.9 macOS 10.9+ x86-64

gambaterm-0.11.0-cp38-cp38-win_amd64.whl (165.5 kB view details)

Uploaded CPython 3.8 Windows x86-64

gambaterm-0.11.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.8 manylinux: glibc 2.17+ x86-64

gambaterm-0.11.0-cp38-cp38-macosx_10_9_x86_64.whl (215.2 kB view details)

Uploaded CPython 3.8 macOS 10.9+ x86-64

gambaterm-0.11.0-cp37-cp37m-win_amd64.whl (165.6 kB view details)

Uploaded CPython 3.7m Windows x86-64

gambaterm-0.11.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.7m manylinux: glibc 2.17+ x86-64

gambaterm-0.11.0-cp37-cp37m-macosx_10_9_x86_64.whl (214.9 kB view details)

Uploaded CPython 3.7m macOS 10.9+ x86-64

File details

Details for the file gambaterm-0.11.0.tar.gz.

File metadata

  • Download URL: gambaterm-0.11.0.tar.gz
  • Upload date:
  • Size: 141.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.9.14

File hashes

Hashes for gambaterm-0.11.0.tar.gz
Algorithm Hash digest
SHA256 a420d9b7e96096c8e4b8e06f03e05338fcb299fe39f80795836d301e4506efc0
MD5 e9774db5e6f9a2ae7574030a5e353b82
BLAKE2b-256 de87dc30c6bc52f04675a63d2037ee0a2e2be44210dd1c093e2c550541904412

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 2d8b58b0e3f8fb4ba29d988802fae43d7847279252050a1c4ae3c5be1e585bef
MD5 bd6a7754945e9291ed8a0ea8102cccf6
BLAKE2b-256 a4872675ec34626a63a61cbf35d9234396fad681fc270f01a3424ec553be3467

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 53e6a27106246f42d0f2526f6738a9a4ac47d4ab4ca8ad5924aaf7f429bdac74
MD5 85a56a2c74bf07c09543fa3960ec7ee9
BLAKE2b-256 a6609ed8e92a5da056aff470d44eebda3d0503f420601d7ca29bb020d3a8d380

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp311-cp311-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp311-cp311-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 3453c33cfa9a1d3276309e389cbfa201d9962488e9414a2e5787023b7ffe2746
MD5 c32d1b3501fe77d5da7e78300cc010c1
BLAKE2b-256 cde8a5e489fd3b6009d72b46ed54c892400d7cd1d4f50226f923eee74cb02ec8

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 79ad0d3ccd1391ece896efe00214d3d91cc97de0f9aa81b6f1c56ce6005ff9f7
MD5 b09f1b2e3c532e4819b58a00aae286e8
BLAKE2b-256 dbf0517afc489c96c4effe6cf21e4042795c448bf8e790b5a7693bf7b359eaa3

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 322d4eb0f92aef8d58ac8143369e8963e1603e436d2ddf30a0979d0eea291101
MD5 7cc803a741ffda9526082c84e27e7523
BLAKE2b-256 eeee709f2d556447af66b5b253ec328891192ef40a5b32cc3564c2ba234af47c

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp310-cp310-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp310-cp310-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 958394714d5377d86cdb95188fc8d6203841452cdbd43934537f3165b56462ea
MD5 89d4791df59450d53b7c2696b0b3fba9
BLAKE2b-256 cdf0cf8ae5859a7f2239236aa10e7643dc2a01878dac425be077f76b7c5753cd

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp39-cp39-win_amd64.whl.

File metadata

  • Download URL: gambaterm-0.11.0-cp39-cp39-win_amd64.whl
  • Upload date:
  • Size: 165.9 kB
  • Tags: CPython 3.9, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.9.14

File hashes

Hashes for gambaterm-0.11.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 1279c242b52c4b006e5dbe1fbda076107c7bcac724127930daa0e959eba43f68
MD5 308d8efab8e5648211ed93bba03e85d2
BLAKE2b-256 54ce696e29f969a5c1d9b49ec1680d055f84ea0e6fcc7fe35580c0c8cd21528c

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 71a0a56c216cc29d30fa1f786dd3909d9be101ed597da8196694726e37578af5
MD5 d0055dc534d123df3071cb1003045d66
BLAKE2b-256 859b1245e7f35edb70bde4f2ca2a5c6dbdd4b11f1e41cae2ef32afce61a9b475

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp39-cp39-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp39-cp39-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 73766340e29964f969aabc34d18259c702f5a9486d1f25c33871d21ae7e17167
MD5 e14a578d26c309e3595cdce6b70d879f
BLAKE2b-256 291051036ec9389051a9d323b63be8d895bd73272b33dbb5ee7b81dc52bfcdc5

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp38-cp38-win_amd64.whl.

File metadata

  • Download URL: gambaterm-0.11.0-cp38-cp38-win_amd64.whl
  • Upload date:
  • Size: 165.5 kB
  • Tags: CPython 3.8, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.9.14

File hashes

Hashes for gambaterm-0.11.0-cp38-cp38-win_amd64.whl
Algorithm Hash digest
SHA256 d756743cfd920684e473c440d64a8aec52a404d15eedd466bcb37cdde2a0259f
MD5 725c49cb966a4ca5310063b3d663c314
BLAKE2b-256 2eda8ccbef3f399f197fe347406dc9a4aabc70fae8bbb22025e572b9199c0cc2

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 4be0ad387326ce636c840b8bf26ddd75b2ab889fbdc4808cb8f86c8f56246900
MD5 c5b4875e383dabaca2073dfc427dd733
BLAKE2b-256 0f852da213ee2ed0c7f94194e2bf1702dc4fc1c8d7496348a7e97c695749e77f

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp38-cp38-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 515d2294833750a7b043bde03de9b863733b736e7862911b1128f73b9cac7aab
MD5 f9682d406bfc36fbaaaa58ba07288595
BLAKE2b-256 20dc9aa00364eab13175d73af8f3faf47e12ea32c3903a38abee57d4a7835a0f

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp37-cp37m-win_amd64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp37-cp37m-win_amd64.whl
Algorithm Hash digest
SHA256 fa8c83d3f090503e41428b6cc797d6df64a0be3c1f21b3c44176cbfccd92e7b3
MD5 92f78887b0e6c09a621eeb4eeed124ef
BLAKE2b-256 a4d75162a965dbfb08e13ddc61e8f98319139f647674d5a2ebb165d04a957261

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 36f1a4860fc3a6ebfdd2ea97050452bcddb22a2da39e4526a0a064d56bd0d5e9
MD5 c4df5562d5c48888909824c4cf42c176
BLAKE2b-256 8bdc53e9acdcf081e8abbce11e250bd9a21205011bda0cd9c2a511435b1a36ea

See more details on using hashes here.

File details

Details for the file gambaterm-0.11.0-cp37-cp37m-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for gambaterm-0.11.0-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 bfe619363e496f706fedd7aa552dae8f6c1352246007798313a7be39bfb3c0b6
MD5 7d5817f7f56fab73ee43a5f2e2ccb249
BLAKE2b-256 c13d2568db5ba80e57a3392027853e265fc2b4f9d43c8b29367f2450d21f3be7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page