GodotXterm

Terminal emulator for Godot using GDNative and libtsm.

Note: If you are looking for the purely gdscript version of this plugin which was based on Xterm.js, it turned out to be too buggy and slow so is no longer being developed or maintained but can still be found in the gdscript-unmaintaned branch.

Supported Platforms

Confirmed:

• Linux 64-bit (primarily developed/tested on this platform)
• HTML5 (also tested on this platform)
• Linux 32-bit
• MacOS 64-bit
• Windows 64-bit
• Windows 32-bit

Demo

• An online demo of an HTML5 export of this repo (using the GDNative export type, available since Godot 3.3) can be found here. Make sure you click the screen at least once after loading.

• A Linux, MacOS, and Windows demo, which uses GodotXterm in conjunction with Godot Python can be downloaded here.

Setup

To install, copy (or symlink) the addons/godot_xterm directory in this repo to the addons directory of your Godot project. You will then need to setup the gdnative components, by either downloading the precompiled binaries or building from source.

Note: If you are running the demo project, it is recommended that you build or install the gdnative binaries before opening it, otherwise the Godot editor will disconnect some signals when it fails to find the gdnative nodes meaning that the project won't run correctly when they are installed. If in doubt, use git status to see if any of the .tscn files have been changed automatically by the editor.

Precompiled Binaries

Precompiled binaries can be downloaded from the GitHub releases page. Download the libgodot-xterm-release.zip (or libgodot-xterm-debug.zip) file and extract it to the addons/godot_xterm/native/bin directory. This will install the gdnative libraries for all supported platforms. After extracting the zip file, the directory should contain the following:

• libgodot-xterm.linux.64.so
• libgodot-xterm.linux.32.so
• libgodot-xterm.javascript.32.wasm
• libgodot-xterm.osx.64.dylib
• libgodot-xterm.windows.64.dll

Building From Source

This plugin follows the standard format of a GDNative plugin as shown in GDNative C++ Example, including the use of the SCons build tool. Therefore, referring to the following documentation on compiling a GDNative plugin and compiling the Godot engine itself may be useful:

• GDNative C++ Example: Compiling the plugin.
• Compiling for X11 (Linux, *BSD)
• Compiling for the Web
• Compiling for macOS
• Compiling for Windows

Dependencies

This plugin does not have any special dependencies beyond those used to compile Godot or the GDNative C++ example. If you can compile those then you should be able to compile this plugin. When in doubt, see the documentation above. The main dependencies are:

• Git (to clone git submodules)
• SCons (a software construction tool)
• A C/C++ compiler (i.e. gcc, llvm, MSVC)
• Emscripten version 2.0.10 (for HTML5 build)

Note: If you are cross-compiling, then you will likely need other dependencies than those listed below.

Linux

Distribution	Command
NixOS	nix-env -iA nixpkgs.git nixpkgs.scons
Arch Linux	pacman -S --needed git scons base-devel
Ubuntu	sudo apt-get install git scons build-essential

MacOS

If Homebrew is installed then you should already have llvm and git. In this case you simply need to install scons with:

brew install scons

Windows

You will need to have Git and Microsoft Visual Studio installed with C++ tools (compiling using mingw is not yet supported). If you have the chocolatey package manager, you can install scons with:

choco install python3 && python -m pip install scons

Steps

The build.sh script in addons/godot_xterm/native is provided for convenience and can be used on Linux to perform the steps below using the default scons options. On NixOS it will use the shell.nix file in the same directory to bring in all dependencies to the build environment. A Dockerfile is also provided to build for the javascript platform. It can be run (after cloning Git submodules) with:

UID_GID="$(id -u):$(id -g)" docker-compose run javascript-build

The 'wasm' binary will be placed in the bin directory alongside others.

1. Clone Git Submodules

This step only needs to be performed once and will clone the git repos this plugin depends on to addons/godot_xterm/native/external.

# In the top-level directory of this git repo...
git submodule update --init --recursive

2. Build C++ Bindings

This step only needs to be performed once per platform/target/bits combination your are targeting, and possibly more if you are targeting different versions of Godot. See GDNative C++ Example: Building the C++ bindings for more info.

# From the top-level directory of this git repo...
cd addons/godot_xterm/native/external/godot-cpp
scons platform=<platform> target=<target> bits=<bits> generate_bindings=yes

Where <platform> is one of linux, javascript, osx or windows, <target> is one of release or debug and <bits> is one of 32 or 64. The generate_bindings=yes option is essential.

3. Build GodotXterm

This step needs to be performed every time the code of this plugin in src/ or external/libtsm is modified.

cd ../../ # If following from the directory of the previous step.
# In addons/godot_xterm/native.
scons platform=<platform> target=<target> bits=<bits>

The same options should be used as in the previous step. If the options are omitted, scons will auto-detect the platform and architecture of the current machine and target will default to debug.

Usage

• Terminal

  The main node provided by this plugin.

• Pseudoterminal

  A node that can be used to connect the Terminal to a shell. Currently Linux and MacOS only.

  An example of how to use this node with a Terminal can be found in the terminal scene.

• TPut

  An incomplete helper class based on the tput utility.

  Example: On the command line you can use tput cup 5 5 to position the cursor at row 5 col 5. In GDScript this utility can be used to similar effect by doing:

  tput.cup(5, 5)
  

  Other commands include tput setaf to set a foreground color, tput setab to set a background color, and many more. But only a few of these have been implemented.

  Its usage is demonstrated in the script for the menu scene.

• Asciicast (.cast) file importer plugin

  Asciinema recordings saved with the .cast extension will be automatically imported as animations. They can then be added to AnimationPlayer which is a child of a Terminal node. Playing the animation will play the terminal session recording in the parent Terminal.

  See the asciicast scene for an example.

Examples

There are three example scenes included in this project which you can study to learn more.

• menu.tscn
• terminal.tscn
• asciicast.tscn

License

Copyright (c) 2020-2021, Leroy Hopson and contributors (MIT License).

Contributor License Agreement

If you contribute code to this project, you are implicitly allowing your code to be distributed under the MIT license. You are also implicitly verifying that all code is your original work, or unoriginal work which is published under a compatible license or waiver.

Sounds

• bell.wav by InspectorJ (https://www.jshaw.co.uk), downloaded from freesound.org, released under CC-BY-3.0.

Fonts

• Hack (see LICENSE.md).

Third-party components

The GDNative source code incorporates code snippets and source code from many third-party libraries. The licenses of these components can be found in the various sub-directories of this project (provided git submodules have been cloned). Many of these licenses must be distributed with source and binary distributions of this software. For convenience, the texts of these licenses have been bundled together (but clearly demarcated) in the THIRDPARTY_NOTICES.txt file.

Note: On platforms where the PTY node is not supported or if the library has been compiled with the option disable_pty=yes then only the licenses bundled in THIRDPARTY_NOTICES_nopty.txt are applicable.