Package: gambaterm
gambatte-terminalA terminal front-end for gambatte, the gameboy color emulator.It supports:16 colors, 256 colors and 24-bit colors terminalPlaying audio from the emulatorUsing TAS input files as game inputUsing keyboard presses as game inputInstallationWheels are available on linux, windows and macos for python 3.6, 3.7, 3.8 and 3.9:$pip3installgambatermUsage and argumentsUsage: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]
                 ROMPositional arguments:ROMPath to a GB or GBC rom fileOptional arguments:--input-file INPUT_FILE, -i INPUT_FILEPath to a bizhawk BK2 input file--frame-advance FRAME_ADVANCE, --fa FRAME_ADVANCENumber of frames to run before displaying the next one (default is 1)--break-after BREAK_AFTER, --ba BREAK_AFTERNumber of frames to run before forcing the emulator to stop (doesn't stop by default)--speed-factor SPEED_FACTOR, --sf SPEED_FACTORSpeed factor to apply to the emulation (default is 1.0 corresponding to 60 FPS)--force-gameboy, --fgForce the emulator to treat the rom as a GB file--skip-inputs SKIP_INPUTS, --si SKIP_INPUTSNumber of frame inputs to skip in order to compensate for the lack of BIOS (default is 188)--cpr-sync, --csUse CPR synchronization to prevent video buffering--enable-controller, --ecEnable game controller support--disable-audio, --daDisable audio entirely--color-mode COLOR_MODE, -c COLOR_MODEForce a color mode (1: 4 greyscale colors, 2: 16 colors, 3: 256 colors, 4: 24-bit colors)SSH serverIt 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 thessh -Xoption. Usegambaterm-ssh --helpfor more information.Terminal supportNot 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 colorsThose 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-gameboyor--color-mode=1.Support for UTF-8 and good rendering of unicode block elementsMore specifically the following characters▄ █ ▀.
Also, the alignement might be off (e.g small spaces between pixels)
This is not always well supported.Good rendering performanceThe 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:LinuxStatusColorsUnicode renderingPerformanceCommentsGnome terminalExcellent24-bit colorsGood60 FPSTerminatorExcellent24-bit colorsGood60 FPSKittyExcellent24-bit colorsGood60 FPSXTermGood24-bit colorsGood60 FPSNo resize shortcutsTermitOk24-bit colorsGood60 FPSNo window titleRxvtOk256 colorsGood60 FPSNo resize shortcutsMltermOk24-bit colorsLight misalignments60 FPSNo resize shortcutsTerminologyOk24-bit colorsPossible misalignments30 FPSWeird colorsAbout MacOS:MacOSStatusColorsUnicode renderingPerformanceCommentsiTerm2Good24-bit colorsGood30 FPSTerminalUnplayable256 colorsMisalignments20 FPSAbout Windows:WindowsStatusColorsUnicode renderingPerformanceCommentsWindows terminalUnpleasant24-bit colorsGood30 FPSBuggy displayCmderUnplayable24-bit colorsGood2 FPSNo window titleTerminusUnplayable24-bit colorsMisalignments10 FPSCommand promptBrokenN/AN/AN/ANo ANSI code supportGit bashBrokenN/AN/AN/ADoesn't work with winptyTerminal sizeThe 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 thectrl - / ctrl +orctrl wheelshortcuts.Keyboard, game controller and file inputsKeyboard controls are enabled by default, while game controller controls have to be enabled using--enable-controlleror--ec. The key bindings are not configurable at the moment:ButtonsKeyboardControllerDirectionsArrowsLeft hat / Left stickAF / V / SpaceButton 0 / Button 3BD / C / AltButton 1 / Button 2StartRight Ctrl / EnterButton 7SelectRight Shift / DeleteButton 6Key releases, which are usually mandatory to play games, cannot be detected throughstdin. 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 usingssh -X, meaning it requires Windows and MacOS users to run an X server. Moreover, it's a bad idea to connect with-Xto an untrusted server.Additional permissions might be required to access the window system, especially on MacOS (seethis guide)It is also possible to use a bizhawk BK2 input file to play tool-assisted speedruns using the--input-file(or-i) option.MotivationTo 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 asimilar attemptthat 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 completeThe Bouncing Ballat 60 FPS in XTerm, and I'm now looking forward to playing more homebrew games :)DependenciesHere is the list of the dependencies used in this project, all great open source libraries:gambatte- Gameboy emulationCython- Binding to gambatte C++ API, and fast video frame conversionprompt-toolkit- Cross-platform terminal handlingsamplerate- Resampling the audio streamsounddevice- Playing the audio streamxlib/pynput- Getting keyboard inputspygame- Getting game controller inputsasyncssh- Running the SSH serverContactVincent Michel