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, usingchcp 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:
- gambatte - Gameboy emulation
- Cython - Binding to gambatte C++ API, and fast video frame conversion
- prompt-toolkit - Cross-platform terminal handling
- samplerate - Resampling the audio stream
- sounddevice - Playing the audio stream
- xlib/pynput - Getting keyboard inputs
- pygame - Getting game controller inputs
- asyncssh - Running the SSH server
Contact
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | a420d9b7e96096c8e4b8e06f03e05338fcb299fe39f80795836d301e4506efc0 |
|
MD5 | e9774db5e6f9a2ae7574030a5e353b82 |
|
BLAKE2b-256 | de87dc30c6bc52f04675a63d2037ee0a2e2be44210dd1c093e2c550541904412 |
File details
Details for the file gambaterm-0.11.0-cp311-cp311-win_amd64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp311-cp311-win_amd64.whl
- Upload date:
- Size: 165.0 kB
- Tags: CPython 3.11, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2d8b58b0e3f8fb4ba29d988802fae43d7847279252050a1c4ae3c5be1e585bef |
|
MD5 | bd6a7754945e9291ed8a0ea8102cccf6 |
|
BLAKE2b-256 | a4872675ec34626a63a61cbf35d9234396fad681fc270f01a3424ec553be3467 |
File details
Details for the file gambaterm-0.11.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 1.3 MB
- Tags: CPython 3.11, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 53e6a27106246f42d0f2526f6738a9a4ac47d4ab4ca8ad5924aaf7f429bdac74 |
|
MD5 | 85a56a2c74bf07c09543fa3960ec7ee9 |
|
BLAKE2b-256 | a6609ed8e92a5da056aff470d44eebda3d0503f420601d7ca29bb020d3a8d380 |
File details
Details for the file gambaterm-0.11.0-cp311-cp311-macosx_10_9_x86_64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp311-cp311-macosx_10_9_x86_64.whl
- Upload date:
- Size: 214.9 kB
- Tags: CPython 3.11, macOS 10.9+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3453c33cfa9a1d3276309e389cbfa201d9962488e9414a2e5787023b7ffe2746 |
|
MD5 | c32d1b3501fe77d5da7e78300cc010c1 |
|
BLAKE2b-256 | cde8a5e489fd3b6009d72b46ed54c892400d7cd1d4f50226f923eee74cb02ec8 |
File details
Details for the file gambaterm-0.11.0-cp310-cp310-win_amd64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp310-cp310-win_amd64.whl
- Upload date:
- Size: 165.9 kB
- Tags: CPython 3.10, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 79ad0d3ccd1391ece896efe00214d3d91cc97de0f9aa81b6f1c56ce6005ff9f7 |
|
MD5 | b09f1b2e3c532e4819b58a00aae286e8 |
|
BLAKE2b-256 | dbf0517afc489c96c4effe6cf21e4042795c448bf8e790b5a7693bf7b359eaa3 |
File details
Details for the file gambaterm-0.11.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 1.3 MB
- Tags: CPython 3.10, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 322d4eb0f92aef8d58ac8143369e8963e1603e436d2ddf30a0979d0eea291101 |
|
MD5 | 7cc803a741ffda9526082c84e27e7523 |
|
BLAKE2b-256 | eeee709f2d556447af66b5b253ec328891192ef40a5b32cc3564c2ba234af47c |
File details
Details for the file gambaterm-0.11.0-cp310-cp310-macosx_10_9_x86_64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp310-cp310-macosx_10_9_x86_64.whl
- Upload date:
- Size: 215.2 kB
- Tags: CPython 3.10, macOS 10.9+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 958394714d5377d86cdb95188fc8d6203841452cdbd43934537f3165b56462ea |
|
MD5 | 89d4791df59450d53b7c2696b0b3fba9 |
|
BLAKE2b-256 | cdf0cf8ae5859a7f2239236aa10e7643dc2a01878dac425be077f76b7c5753cd |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1279c242b52c4b006e5dbe1fbda076107c7bcac724127930daa0e959eba43f68 |
|
MD5 | 308d8efab8e5648211ed93bba03e85d2 |
|
BLAKE2b-256 | 54ce696e29f969a5c1d9b49ec1680d055f84ea0e6fcc7fe35580c0c8cd21528c |
File details
Details for the file gambaterm-0.11.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 1.3 MB
- Tags: CPython 3.9, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 71a0a56c216cc29d30fa1f786dd3909d9be101ed597da8196694726e37578af5 |
|
MD5 | d0055dc534d123df3071cb1003045d66 |
|
BLAKE2b-256 | 859b1245e7f35edb70bde4f2ca2a5c6dbdd4b11f1e41cae2ef32afce61a9b475 |
File details
Details for the file gambaterm-0.11.0-cp39-cp39-macosx_10_9_x86_64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp39-cp39-macosx_10_9_x86_64.whl
- Upload date:
- Size: 215.2 kB
- Tags: CPython 3.9, macOS 10.9+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 73766340e29964f969aabc34d18259c702f5a9486d1f25c33871d21ae7e17167 |
|
MD5 | e14a578d26c309e3595cdce6b70d879f |
|
BLAKE2b-256 | 291051036ec9389051a9d323b63be8d895bd73272b33dbb5ee7b81dc52bfcdc5 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | d756743cfd920684e473c440d64a8aec52a404d15eedd466bcb37cdde2a0259f |
|
MD5 | 725c49cb966a4ca5310063b3d663c314 |
|
BLAKE2b-256 | 2eda8ccbef3f399f197fe347406dc9a4aabc70fae8bbb22025e572b9199c0cc2 |
File details
Details for the file gambaterm-0.11.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 1.3 MB
- Tags: CPython 3.8, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4be0ad387326ce636c840b8bf26ddd75b2ab889fbdc4808cb8f86c8f56246900 |
|
MD5 | c5b4875e383dabaca2073dfc427dd733 |
|
BLAKE2b-256 | 0f852da213ee2ed0c7f94194e2bf1702dc4fc1c8d7496348a7e97c695749e77f |
File details
Details for the file gambaterm-0.11.0-cp38-cp38-macosx_10_9_x86_64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp38-cp38-macosx_10_9_x86_64.whl
- Upload date:
- Size: 215.2 kB
- Tags: CPython 3.8, macOS 10.9+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 515d2294833750a7b043bde03de9b863733b736e7862911b1128f73b9cac7aab |
|
MD5 | f9682d406bfc36fbaaaa58ba07288595 |
|
BLAKE2b-256 | 20dc9aa00364eab13175d73af8f3faf47e12ea32c3903a38abee57d4a7835a0f |
File details
Details for the file gambaterm-0.11.0-cp37-cp37m-win_amd64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp37-cp37m-win_amd64.whl
- Upload date:
- Size: 165.6 kB
- Tags: CPython 3.7m, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | fa8c83d3f090503e41428b6cc797d6df64a0be3c1f21b3c44176cbfccd92e7b3 |
|
MD5 | 92f78887b0e6c09a621eeb4eeed124ef |
|
BLAKE2b-256 | a4d75162a965dbfb08e13ddc61e8f98319139f647674d5a2ebb165d04a957261 |
File details
Details for the file gambaterm-0.11.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 1.3 MB
- Tags: CPython 3.7m, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 36f1a4860fc3a6ebfdd2ea97050452bcddb22a2da39e4526a0a064d56bd0d5e9 |
|
MD5 | c4df5562d5c48888909824c4cf42c176 |
|
BLAKE2b-256 | 8bdc53e9acdcf081e8abbce11e250bd9a21205011bda0cd9c2a511435b1a36ea |
File details
Details for the file gambaterm-0.11.0-cp37-cp37m-macosx_10_9_x86_64.whl
.
File metadata
- Download URL: gambaterm-0.11.0-cp37-cp37m-macosx_10_9_x86_64.whl
- Upload date:
- Size: 214.9 kB
- Tags: CPython 3.7m, macOS 10.9+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | bfe619363e496f706fedd7aa552dae8f6c1352246007798313a7be39bfb3c0b6 |
|
MD5 | 7d5817f7f56fab73ee43a5f2e2ccb249 |
|
BLAKE2b-256 | c13d2568db5ba80e57a3392027853e265fc2b4f9d43c8b29367f2450d21f3be7 |