8269fc90a2
Works with TERM=linux, does not work with TERM=xterm-256color. Will need to update libtsm to handle mouse events as there is an escape sequence to turn tracking on/off. Probably something similar to tsm_vte_handle_keyboard(). |
||
---|---|---|
.github/workflows | ||
addons | ||
docs | ||
examples | ||
misc | ||
test | ||
themes | ||
.gitattributes | ||
.gitignore | ||
.gitmodules | ||
CHANGELOG.md | ||
default_env.tres | ||
export_presets.cfg | ||
icon.png | ||
icon.png.import | ||
LICENSE.md | ||
plug.gd | ||
project.godot | ||
README.md |
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.