gambaterm

A terminal frontend for gambatte game boy color emulator

These details have not been verified by PyPI

Project links

Homepage

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 ▄ █ ▀. 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	30 FPS	Buggy display
Cmder	Unplayable	24-bit colors	Good	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

Vincent Michel

Project details

These details have not been verified by PyPI

Project links

Homepage

Release history Release notifications | RSS feed

This version

0.12.7

Jul 2, 2024

0.12.4

Nov 14, 2023

0.12.3 yanked

Nov 14, 2023

0.12.2

Jul 17, 2023

0.12.1

Sep 25, 2022

0.12.0

Sep 25, 2022

0.11.0

Sep 20, 2022

0.10.0

Aug 22, 2022

0.9.9

Aug 21, 2022

0.9.8

Aug 21, 2022

0.9.7

Sep 30, 2021

0.9.6

Jun 27, 2021

0.9.5

Mar 17, 2021

0.9.4

Mar 16, 2021

0.9.3

Mar 13, 2021

0.9.2

Mar 12, 2021

0.9.1

Feb 25, 2021

0.9.0

Feb 11, 2021

0.8.1

Feb 10, 2021

0.8.0

Feb 8, 2021

0.7.0

Feb 3, 2021

0.6.2

Jan 28, 2021

0.6.1

Jan 27, 2021

0.5.0

Jan 25, 2021

0.4.1

Jan 21, 2021

0.4.0

Jan 21, 2021

0.3.0

Jan 20, 2021

0.2.0

Jan 19, 2021

0.1.2

Jan 19, 2021

0.1.0

Jan 19, 2021

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.12.7.tar.gz (144.6 kB view details)

Uploaded Jul 2, 2024 Source

Built Distributions

gambaterm-0.12.7-cp312-cp312-win_amd64.whl (194.0 kB view details)

Uploaded Jul 2, 2024 CPython 3.12 Windows x86-64

gambaterm-0.12.7-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.5 MB view details)

Uploaded Jul 2, 2024 CPython 3.12 manylinux: glibc 2.17+ x86-64

gambaterm-0.12.7-cp312-cp312-macosx_11_0_arm64.whl (221.8 kB view details)

Uploaded Jul 2, 2024 CPython 3.12 macOS 11.0+ ARM64

gambaterm-0.12.7-cp312-cp312-macosx_10_9_x86_64.whl (226.1 kB view details)

Uploaded Jul 2, 2024 CPython 3.12 macOS 10.9+ x86-64

gambaterm-0.12.7-cp311-cp311-win_amd64.whl (193.1 kB view details)

Uploaded Jul 2, 2024 CPython 3.11 Windows x86-64

gambaterm-0.12.7-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.5 MB view details)

Uploaded Jul 2, 2024 CPython 3.11 manylinux: glibc 2.17+ x86-64

gambaterm-0.12.7-cp311-cp311-macosx_11_0_arm64.whl (221.4 kB view details)

Uploaded Jul 2, 2024 CPython 3.11 macOS 11.0+ ARM64

gambaterm-0.12.7-cp311-cp311-macosx_10_9_x86_64.whl (225.7 kB view details)

Uploaded Jul 2, 2024 CPython 3.11 macOS 10.9+ x86-64

gambaterm-0.12.7-cp310-cp310-win_amd64.whl (193.0 kB view details)

Uploaded Jul 2, 2024 CPython 3.10 Windows x86-64

gambaterm-0.12.7-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.5 MB view details)

Uploaded Jul 2, 2024 CPython 3.10 manylinux: glibc 2.17+ x86-64

gambaterm-0.12.7-cp310-cp310-macosx_11_0_arm64.whl (221.4 kB view details)

Uploaded Jul 2, 2024 CPython 3.10 macOS 11.0+ ARM64

gambaterm-0.12.7-cp310-cp310-macosx_10_9_x86_64.whl (225.6 kB view details)

Uploaded Jul 2, 2024 CPython 3.10 macOS 10.9+ x86-64

gambaterm-0.12.7-cp39-cp39-win_amd64.whl (193.5 kB view details)

Uploaded Jul 2, 2024 CPython 3.9 Windows x86-64

gambaterm-0.12.7-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.5 MB view details)

Uploaded Jul 2, 2024 CPython 3.9 manylinux: glibc 2.17+ x86-64

gambaterm-0.12.7-cp39-cp39-macosx_11_0_arm64.whl (222.3 kB view details)

Uploaded Jul 2, 2024 CPython 3.9 macOS 11.0+ ARM64

gambaterm-0.12.7-cp39-cp39-macosx_10_9_x86_64.whl (226.8 kB view details)

Uploaded Jul 2, 2024 CPython 3.9 macOS 10.9+ x86-64

gambaterm-0.12.7-cp38-cp38-win_amd64.whl (194.2 kB view details)

Uploaded Jul 2, 2024 CPython 3.8 Windows x86-64

gambaterm-0.12.7-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.5 MB view details)

Uploaded Jul 2, 2024 CPython 3.8 manylinux: glibc 2.17+ x86-64

gambaterm-0.12.7-cp38-cp38-macosx_11_0_arm64.whl (222.5 kB view details)

Uploaded Jul 2, 2024 CPython 3.8 macOS 11.0+ ARM64

gambaterm-0.12.7-cp38-cp38-macosx_10_9_x86_64.whl (227.4 kB view details)

Uploaded Jul 2, 2024 CPython 3.8 macOS 10.9+ x86-64

gambaterm-0.12.7-cp37-cp37m-win_amd64.whl (193.8 kB view details)

Uploaded Jul 2, 2024 CPython 3.7m Windows x86-64

gambaterm-0.12.7-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.5 MB view details)

Uploaded Jul 2, 2024 CPython 3.7m manylinux: glibc 2.17+ x86-64

gambaterm-0.12.7-cp37-cp37m-macosx_10_9_x86_64.whl (227.0 kB view details)

Uploaded Jul 2, 2024 CPython 3.7m macOS 10.9+ x86-64

File details

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

File metadata

Download URL: gambaterm-0.12.7.tar.gz
Upload date: Jul 2, 2024
Size: 144.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/5.1.0 CPython/3.12.4

File hashes

Hashes for gambaterm-0.12.7.tar.gz
Algorithm	Hash digest
SHA256	`8ae9ad128942b4ec8bba06a2228137b579c1968b8b540f9afef1cd3779dd8e7c`
MD5	`884e6e4ae210057237d19e8cc862b733`
BLAKE2b-256	`9d42e000e3005568aa6ab3c4a462c7b23d2d60cc56d4c5429700283a35d400c8`

Algorithm	Hash digest
SHA256	`4d1fc7fd3ebc04dc58a9e0d9b85f6d570e418e43fc5c10342b214c722f849927`
MD5	`8a0ee577497671e6eb8a1bd372527512`
BLAKE2b-256	`e59d9a1e13717e9dc43d697ef26397222d3dede2aad2f97b50a2a73d88c24e02`

Algorithm	Hash digest
SHA256	`b46303d1a07a59416ef5ab0e53a4f7dd20b042bffd7092bb896065563b0ef5d2`
MD5	`9ab2c920cc4c85904a8946a124f1e603`
BLAKE2b-256	`f34eecfafc40a9eb55ca6490e3552aef8c71319b75f69fc03e81aaa13a06767e`

Algorithm	Hash digest
SHA256	`da0ff0c588f69c124b3ed975b24353ea1c8cd8f81888845bdcb10f1a882731b5`
MD5	`e1885aa4f1a557d52fe7129ee03eee36`
BLAKE2b-256	`9bc155075639c807dce1f99b70d7a193de4c0272a9fcebce6a98367eb2a2b797`

Algorithm	Hash digest
SHA256	`835107401d24610563d82b03a46e2b69449112cc120be8bc3f52e296dd22ea6d`
MD5	`bf0fc34985d04a0f01078c3a44a356d7`
BLAKE2b-256	`f2e1e9e718951236578208a3ceae976bdd73762a00dbe6eeb7cead3de7ab0c2a`

Algorithm	Hash digest
SHA256	`f1963178e5c791ef594253213663be5ef1a1cdc2ca30f504c402ea34390ce4f2`
MD5	`102765c5c8ecfe27f72c9ba15a418634`
BLAKE2b-256	`19e3df71b55eeaff99ecb139c1cd793a89f909c826794bfb2a93b99ddfd5c90c`

Algorithm	Hash digest
SHA256	`a9e9950f4313103f0889004c6903467d76f6a16408ef2c5f01ed8ccc92edc488`
MD5	`359c95abfae416827749ee35bd4f74a3`
BLAKE2b-256	`23889900883342e63a3c3dc08b835ed166c4771c2f6f556b1acdcdf89f388588`

Algorithm	Hash digest
SHA256	`0a4ace625c870e997a6e00ec86e50d65aeb977b11a321730455d7f57f8d5727a`
MD5	`730f76e7c7a2c7a034a6e5e79edd1b60`
BLAKE2b-256	`d8bda780e414f1fcb58cab983635500db7c969eee46082c4fdd4d387a90b0620`

Algorithm	Hash digest
SHA256	`9e3776fb081b8c106d816bb6aac04e1939f2c90afb191825a18853ee9bfe64b7`
MD5	`b4355b02c0bcb34bb5565ece2882494f`
BLAKE2b-256	`351cf4685e56fbaf5ef6ffad6e75596b3555e93dc2bff0202ace454b5ccf7946`

Algorithm	Hash digest
SHA256	`f3343416697ced3ad244913ec26b8a873e2381468c51ac1614bf5ce9aa8d01e8`
MD5	`6440529eb260b170f7a0e8a674fa58e6`
BLAKE2b-256	`fed7601f45eb8975ac32c3f67e471ad223dd6ea009c5f3a3f09beec22a79b422`

Algorithm	Hash digest
SHA256	`0a6fc6d9143ba4458423d66a0ba60142378962bfa99a31955a9ed14c6ee3b963`
MD5	`e0566c87914d8a9e509a4b17d8480a3a`
BLAKE2b-256	`2aedc94c11286925c4b0acfb11f51d221042497ea1066068f59c0516fb6223ed`

Algorithm	Hash digest
SHA256	`584e94f4a16b398547797221f87d1c141b5d6036d6aa7b46d8a674b1920666e8`
MD5	`ac051d58007569c81f8c2deb263dc4f3`
BLAKE2b-256	`02cbd97ebbc1ce921ecb23da288a4c108bd1c18adb150ebd1eee8bff000bb57c`

Algorithm	Hash digest
SHA256	`2f24f776791b4f6d6c8223ca0b160a2c678a4eaeb61e64e6c4aac3945de7fb38`
MD5	`91e6871e8d7b12e8bd10ca8d08995beb`
BLAKE2b-256	`b763306aed33559f398d1fa38beda6c73ab77870ac9ef3d4a3e3c9aa03b22e1f`

Algorithm	Hash digest
SHA256	`1a20f265f6d8741e47fb39be9133a33fc5d8046168629580cac180b1ce639d2f`
MD5	`a2ae6620e05d777664e1aabde788da3c`
BLAKE2b-256	`36165908b68c5abc340227b8c1344d20f13bff8cc73c54462527138515e87636`

Algorithm	Hash digest
SHA256	`cacf3f13a4f0318da94a5c9ff65f412a8a125e9db17553c2db4e5d333a88e53b`
MD5	`cac59631b9931393ed57a1a5651ee0ef`
BLAKE2b-256	`803444b2ca25bdb9c6dd92980ed6b562293858e9aca0079c2d609bff646336b7`

Algorithm	Hash digest
SHA256	`fe59dbbaa26d5d4462fa411bea414ad0ce68a93fdef90c3f4cd0609e0e4b53f5`
MD5	`89f84b94302067764466c4569c8fa9c7`
BLAKE2b-256	`47e29f13afa3fb96dcd27b467aa6a479c8d2439820650a722720e32fee78315a`

Algorithm	Hash digest
SHA256	`e2d1451c3056b37b1ffff533f18b2fc3eb7ede04823f626ff219e6a72579416f`
MD5	`ce592be487a20b1dbac6dc26040d1b2c`
BLAKE2b-256	`914be1882797a1e7e3ac88fa29f5fa955623ba32c877dd557daffc1bfba5d321`

Algorithm	Hash digest
SHA256	`727b3e4ea260e350505da60279d517346fcc2b58fded66a87bbd7590f0cd0b48`
MD5	`681a3b3c71f742f343b22a78c406390c`
BLAKE2b-256	`4c9e767f1c1f7da4a242fcf6bec85c8328dbd83d3e3da40aefee310cf0fc7df4`

Algorithm	Hash digest
SHA256	`ca93d872a2f2e457e7250f165493ae08ec6df402874050fb9388fbaeb10b69ee`
MD5	`66e36f199e6da4f659f31f28d5ce52ef`
BLAKE2b-256	`8badc078a334fbf2fbec06ed85ad421ca5ef9ab736da51dc0015af6b9938113f`

Algorithm	Hash digest
SHA256	`93dbba9cc7fc18538dc984cb81798bd024ed2bd3247d64a115992463cb37a389`
MD5	`4dae527da7f23bd004522b9c0b740454`
BLAKE2b-256	`957bc0ebaf38a89c4b8c3e9c73d429991a640312430654f6c59d328b74e53582`

Algorithm	Hash digest
SHA256	`bd885e36f75e9a9b54df8341a8cda027381fc74f432d0d504b8fc8372b99fb87`
MD5	`23def6a30dbf3bda9b74e81c1cdd6122`
BLAKE2b-256	`cf01f17be839fd19377abccbcd2c32dbbc239696bfd574a051684a705f26b775`

gambaterm 0.12.7

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

gambatte-terminal

Installation

Usage and arguments

SSH server

Terminal support

Terminal size

Keyboard, game controller and file inputs

Motivation

Dependencies

Contact

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

Algorithm	Hash digest
SHA256	`eab142aae391632b814ca9d096fda3f3df4d80c82235dcb76a842d5098caf2c6`
MD5	`08e9f83e4cc188a24e1a638a8e3e81b3`
BLAKE2b-256	`d8ed5c0367820dcbc10d0e7c7902d5ba134060b7139d83266af3abe1712203bf`

Algorithm	Hash digest
SHA256	`72f13ee1e58bdc47ed62547f9234483ebcb7a26aa106b95060cf45fbe46e4d24`
MD5	`c8792dbfc5857fe2c59a8ca520f9f0a7`
BLAKE2b-256	`31900527b004c33780efd2f10fab08daf363af9a96e3032070bebe6d9934b8b3`

Algorithm	Hash digest
SHA256	`70839cdbc939775493a4fd70a80bce05a0a2effe6c6c6f4b52c18fcbd89cb9c5`
MD5	`0b97f64d65782c442947f9a21c95eab0`
BLAKE2b-256	`b6fe612ce3b3df7915fc5cae756ba3f67c22aaddbd41e3bc4cbb315031518be7`