3ad0e105e7
Changes `write()` method of native pipe and terminal to accept a PoolByteArray rather than String. This means that `get_string_from_utf8()` is no longer called on data coming from PTY and being sent to Terminal. The terminal state machine already has a UTF8 parser which maintains its state across calls to `write()`. This means that we can write half the bytes of a single unicode character in one call and the remaining half in the next call and the state machine will parse it correctly. On the other hand, the `get_string_from_utf8()` method of Godot's PoolByteArray requires that the array contains completely valid UTF8, otherwise we get errors such as "Unicode error: invalid skip". The data coming from PTY can be arbitrarily split in the middle of a unicode character meaning that we will sometimes get errors when calling `get_string_from_utf8()` on it. This is more likely to occur when there is a large amount of output (i.e. it's more likely to be split). In other cases, the data might intentionally contain invalid unicode such as when printing binary files or random data (e.g. `cat /bin/sh`, `cat /dev/random`). We avoid these errors by passing the PoolByteArray data directly to the terminal state machine. In addition to fixing unicode errors, this commit: - Prevents repeated calls to pipes `_read_cb()` method that would block Godot and result in a crash with the message "ERROR: All memory pool allocations are in use" that resulted from writing data to an ever-increasing number of PoolByteArrays before any of them could be freed. This could be triggered by running the `cat /dev/urandom` command after making the change to `write()` mentioned above. - Prevents memory leaks by freeing libuv buffers after they have been copied to PoolByteArrays. Fixes #55. |
||
|---|---|---|
| .github | ||
| addons | ||
| docs | ||
| examples | ||
| misc | ||
| test | ||
| themes | ||
| .gitattributes | ||
| .gitignore | ||
| .gitmodules | ||
| default_env.tres | ||
| export_presets.cfg | ||
| LICENSE.md | ||
| project.godot | ||
| requirements.txt | ||
GodotXterm - Terminal Emulator
GDNative terminal for Godot. Built using libtsm, libuv, and node-pty. Primarily developed and tested on Linux, it also supports macOS with partial support for Windows and HTML5. See the Features section for more detail.
https://user-images.githubusercontent.com/3696783/126894061-a69eb6ad-9979-4723-ade7-829494a9fc87.mp4
Table of Contents
Features
-
Terminal
A Terminal emulator Control node.
Supports ANSI and (some) XTerm Control Sequences which can be used to do things such as clear the screen, move the cursor, change printed text color, ring a bell, and so on. For an exhaustive list of terminal control sequences (not all of which are supported by GodotXterm) see "XTerm Control Sequences".
-
PTY
Linux and macOS only.
Node for forking processes (e.g. bash, nodejs, python) with pseudoterminal file descriptors. Can be used with the Terminal node to get an actual shell.
Not currently supported on Windows, but it could be in the future using ConPTY or WinPTY. See issue #25.
-
Terminal Editor Plugin
Linux and macOS only.
Adds a panel to the Editor's bottom panel that can be used to spawn terminals in the editor. Similar to VSCode's integrated terminal and IntelliJ's embedded terminal.
-
Asciicast Import Plugin
Adds support for importing asciinema v2
.castfiles as animations that can be played by an AnimationPlayer that is a child of a Terminal node. Example.castfiles can be downloaded from the asciinema website. -
Xresources Import Plugin
Adds support for importing color schemes from
.xrdbor.Xresourcesfiles. Example xresources files can be exported from terminal.sexy. The iTerm2-Color-Schemes repo also has many example color scheme files in xrdb and Xresources format.
Screenshots
 |
 |
 |
 |
Demos and Examples
The GodotXterm repository contains several example scenes in the /examples directory.
After cloning this repo you will need to either build the GDNative binaries from source or copy pre-compiled binaries into your project.
See the Setup section for more details.
Other examples of GodotXterm usage are available online:
-
Live Demo: An HTML5 export of the GodotXterm repo's example scenes.
-
The Guest: A Linux only submission to the Linux Game Jam 2022. Uses GodotXterm in conjunction with the gdtemu addon and Linux's Kernel-based Virtual Machine, to provide the player with interactive VM that can be used in the game world.
-
Xterminate: A Linux, macOS, and Windows demo which uses an older version GodotXterm in conjunction with Godot Python.
Are you using GodotXterm in your project and want it listed here? Please open a pull request to have it added.
Installation
GodotXterm is available on the Godot Asset Library. For more ways to install see the Setup section.
Documentation
Documentation is available on GitHub Pages. If you have a question not answered by the docs, or would like more support, feel free to open a new discussion in the discussions section of this project.
License
Copyright (c) 2020-2022, Leroy Hopson and contributors (MIT License).
See the full license.
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.
Fonts
- The Hack regular font is bundled with GodotXterm as the default Terminal font. This is also the default monospace font of the Godot editor. See the full license.
Nonbundled Resources
The following resources are not bundled with GodotXterm (i.e. are not included in the addons/godot_xterm directory) but are included in this repository for demo and testing purposes. They are:
Sounds
- bell.wav by InspectorJ, downloaded from freesound.org, released under CC-BY-3.0.
Fonts
- The bold, italic, and bold italic styles of the Hack font which are covered by the same license as above.
- Nerd Fonts. Combines symbols from a multitude of other fonts. See license information.
- Noto Color Emoji. Released under the SIL Open Font License.
- Unifont. Dual-licensed (since version 13.0.04) under the GNU GPL 2+ with the GNU font embedding exception and the SIL Open Font License (OFL) version 1.1. This project uses it under the terms of the SIL Open Font License.