Jasima/godot-xterm
1
0
Fork 0
mirror of https://github.com/lihop/godot-xterm.git synced 2024-11-22 09:40:25 +01:00
Code Issues Projects Releases Packages Wiki Activity

Update documentation

Browse source 
- Remove contributor license agreement:

  The terms are same as the standard "inbound=outbound" norm for open
  source projects which is covered by GitHub's terms of service
  which every GitHub user has already agreed to:
  https://docs.github.com/en/github/site-policy/github-terms-of-service#6-contributions-under-repository-license

- Add wiki as submodule and move documentation to it.

- Update README and replace screenshot with video
This commit is contained in:
Leroy Hopson 2021-07-25 08:07:05 +07:00
parent 72fcc0e451
commit d75c26cec6
No known key found for this signature in database
GPG key ID: D2747312A6DB51AA
6 changed files with 67 additions and 4092 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
.gitmodules vendored
View file

@ -16,3 +16,9 @@
url = https://github.com/libuv/libuv
[submodule "godot-cpp/"]
url = https://github.com/godotengine/godot-cpp
[submodule "docs/godot-xterm.wiki"]
path = docs/godot-xterm.wiki
url = https://github.com/lihop/godot-xterm.wiki
[submodule "docs/wiki"]
path = docs/wiki
url = https://github.com/lihop/godot-xterm.wiki

216
README.md
View file

@ -6,181 +6,85 @@
![License](https://img.shields.io/badge/license-MIT-green.svg)
[![Build Status](https://github.com/lihop/godot-xterm/workflows/build/badge.svg?branch=master)](https://github.com/lihop/godot-xterm/actions?query=branch%3Amaster)
Terminal emulator for Godot using GDNative and [libtsm](https://github.com/Aetf/libtsm).
GDNative terminal for Godot.
Built using [libtsm](https://www.freedesktop.org/wiki/Software/libtsm/), [libuv](https://github.com/libuv/libuv), and [node-pty](https://github.com/microsoft/node-pty).
Primarily developed and tested on Linux, it also supports macOS with partial support for Windows and HTML5. See the [Features](#features) section for more detail.
**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](https://github.com/lihop/godot-xterm/tree/gdscript-unmaintained) branch.
https://user-images.githubusercontent.com/3696783/126894061-a69eb6ad-9979-4723-ade7-829494a9fc87.mp4
![Screenshot of Main Menu Scene](./docs/screenshot.png)
## [Documentation](https://github.com/lihop/godot-xterm/wiki)
## Supported Platforms
Documentation is available in [the wiki](https://github.com/lihop/godot-xterm/wiki).
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](https://github.com/lihop/godot-xterm/discussions) section of this project.
### 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
## Features
- ### [Terminal](https://github.com/lihop/godot-xterm/wiki/Terminal)
A Terminal emulator Control node.
## Demo
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 <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>.
- An online demo of an HTML5 export of this repo (using the GDNative export type, available since Godot 3.3) can be found [here](https://demo.godot-xterm.nix.nz).
- ### [PTY](https://github.com/lihop/godot-xterm/wiki/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](https://docs.microsoft.com/en-us/windows/console) or [WinPTY](https://github.com/rprichard/winpty).
See issue [\#25](https://github.com/lihop/godot-xterm/issues/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 `.cast` files as animations that can be played by an AnimationPlayer that is a child of a Terminal node.
Example `.cast` files can be downloaded from the [asciinema website](https://asciinema.org).
- ### Xresources Import Plugin
Adds support for importing color schemes from `.xrdb` or `.Xresources` files.
Example xresources files can be exported from [terminal.sexy](https://terminal.sexy).
The [iTerm2-Color-Schemes repo](https://github.com/mbadolato/iTerm2-Color-Schemes) also has many example color scheme files in [xrdb](https://github.com/mbadolato/iTerm2-Color-Schemes/tree/master/xrdb) and [Xresources](https://github.com/mbadolato/iTerm2-Color-Schemes) format.
## Demos
- [Online demo](https://demo.godot-xterm.nix.nz) of an HTML5 export of this repo (using the GDNative export type, available since Godot 3.3).
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](https://github.com/touilleMan/godot-python) can be downloaded [here](https://lihop.itch.io/xterminate).
- [Xterminate](https://lihop.itch.io/xterminate). A Linux, macOS, and Windows demo, which uses an older version GodotXterm in conjunction with [Godot Python](https://github.com/touilleMan/godot-python).
## Setup
- This repository also contains a number of demo scenes in the [`examples`](/examples) directory. The easiest way to run these scenes is to clone this repo and then download the `libgodot-xterm-release.zip` archive from the [Releases](https://github.com/lihop/godot-xterm/releases) section and extract its contents (`.so`, `.wasm`, `.dll`, and `.dylib` files) into the `addons/godot_xterm/native/bin` directory.
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](https://docs.godotengine.org/en/stable/tutorials/plugins/gdnative/gdnative-cpp-example.html), 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](https://docs.godotengine.org/en/stable/tutorials/plugins/gdnative/gdnative-cpp-example.html#compiling-the-plugin).
- [Compiling for X11 (Linux, \*BSD)](https://docs.godotengine.org/en/stable/development/compiling/compiling_for_x11.html)
- [Compiling for the Web](https://docs.godotengine.org/en/3.3/development/compiling/compiling_for_web.html)
- [Compiling for macOS](https://docs.godotengine.org/en/stable/development/compiling/compiling_for_osx.html)
- [Compiling for Windows](https://docs.godotengine.org/en/stable/development/compiling/compiling_for_windows.html)
#### 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](https://git-scm.com/) (to clone git submodules)
- [SCons](https://scons.org/) (a software construction tool)
- A C/C++ compiler (i.e. [gcc](https://gcc.gnu.org/), [llvm](https://llvm.org/), [MSVC](https://visualstudio.microsoft.com/vs/features/cplusplus/))
- [Emscripten](https://emscripten.org/) 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](https://brew.sh/) 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](https://chocolatey.org/) 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](https://docs.godotengine.org/en/stable/tutorials/plugins/gdnative/gdnative-cpp-example.html#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](addons/godot_xterm/nodes/terminal/README.md)
The main node provided by this plugin.
- ### [Pseudoterminal](addons/godot_xterm/nodes/pseudoterminal/README.md)
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](examples/terminal).
- ### TPut
An incomplete helper class based on the [tput](https://invisible-island.net/ncurses/man/tput.1.html) 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:
```gdscript
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](examples/menu).
- ### Asciicast (.cast) file importer plugin
[Asciinema](https://asciinema.org) 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](examples/asciicast) 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](/LICENSE.md)
Copyright (c) 2020-2021, Leroy Hopson and [contributors](https://github.com/lihop/godot-xterm/graphs/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](/addons/godot_xterm/themes/audio/bell.wav) by InspectorJ (<https://www.jshaw.co.uk>), downloaded from [freesound.org](https://freesound.org/people/InspectorJ/sounds/484344/), released under [CC-BY-3.0](https://creativecommons.org/licenses/by/3.0/).
### Fonts
- [Hack](https://sourcefoundry.org/hack/) (see [LICENSE.md](/addons/godot_xterm/themes/fonts/hack_v3.003/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](/addons/godot_xterm/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](/addons/godot_xterm/THIRDPARTY_NOTICES_nopty.txt) are applicable.
[build.sh]: /addons/godot_xterm/native/build.sh
[dist]: /addons/godot_xterm/native/dist
[SConstruct]: /addons/godot_xterm/native/SConstruct
### 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](/addons/godot_xterm/themes/fonts/hack/LICENSE.md).
### 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](/themes/audio/bell.wav) by InspectorJ (<https://www.jshaw.co.uk>), downloaded from [freesound.org](https://freesound.org/people/InspectorJ/sounds/484344/), released under [CC-BY-3.0](https://creativecommons.org/licenses/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](/themes/fonts/nerd_fonts/README.md).
- Noto Color Emoji. Released under the [SIL Open Font License](/themes/fonts/noto_color_emoji/LICENSE_OFL.txt).
- 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](/themes/fonts/unifont/LICENSE_OFL-1.1.txt).

159
addons/godot_xterm/nodes/terminal/README.md
View file

@ -1,159 +0,0 @@
# Terminal
**Inherits:** [Control] < [CanvasItem] < [Node] < [Object]
Terminal emulator.
**IMPORTANT:**
<img align="right" src="./docs/important_properties.png"/>
- If the terminal isn't responding to keyboard or mouse input check that `focus_mode` is set to `All`, otherwise `_gui_input()` won't be called so no input will be processed.
- If you want to customize the colors and font of the terminal, be sure to set the theme property. A default theme that can be found in the [themes directory](../../themes) and can be used as a template for creating a custom theme.
## Description
![Flow Diagram](./docs/flow_diagram.svg)
### (1) User Input
The user enters some data into the terminal, typically by typing something on the keyboard or clicking (and possibly dragging) somewhere on the screen.
This corresponds to the `_gui_input()` method which is implemented in [terminal.cpp](./terminal.cpp).
### (2) Terminal Output
The user input from (1) is processed by the terminal and converted.
For example, if the user were to press the downwards arrow key (↓), the terminal would interpret this
and the `data_sent()` signal would be emitted with the value `"\u001b[A"`.
For a full list of escape sequences see ["XTerm Control Sequences"](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html).
### (3) Terminal Input
In the other direction, characters can be sent to the terminal. This corresponds to the `write()` method.
### (4) Draw
The input from (3) is then intepreted by the terminal and drawn to the screen.
For example if the string "\u001b[38;2;0;255;0;mA" was written to the terminal, then it would draw a green colored capital letter 'A' on the screen.
## Properties
| Type | Name | Default |
|-------|------|---------|
| [int] | rows | 24 |
| [int] | cols | 80 |
## Methods
| Returns | Signature |
|---------|-------------------------------------------------|
| void | write **(** [String]\|[PoolByteArray] data **)** |
## Theme Properties
| Type | Name | Default |
|---------|-------------------------------|------------------------------|
| [Color] | Terminal/colors/Background | Color(0.0, 0.0, 0.0, 1.0) |
| [Color] | Terminal/colors/Black | Color(0.0, 0.0, 0.0, 1.0) |
| [Color] | Terminal/colors/Blue | Color(0.0, 0.0, 0.5, 1.0) |
| [Color] | Terminal/colors/Cyan | Color(0.0, 0.5, 0.5, 1.0) |
| [Color] | Terminal/colors/Dark Grey | Color(0.5, 0.5, 0.5, 1.0) |
| [Color] | Terminal/colors/Foreground | Color(1.0, 1.0, 1.0, 1.0) |
| [Color] | Terminal/colors/Green | Color(0.0, 0.5, 0.0, 1.0) |
| [Color] | Terminal/colors/Light Blue | Color(0.0, 0.0, 1.0, 1.0) |
| [Color] | Terminal/colors/Light Cyan | Color(0.0, 1.0, 1.0, 1.0) |
| [Color] | Terminal/colors/Light Green | Color(0.0, 1.0, 0.0, 1.0) |
| [Color] | Terminal/colors/Light Grey | Color(0.75, 0.75, 0.75, 1.0) |
| [Color] | Terminal/colors/Light Magenta | Color(1.0, 0.0, 1.0, 1.0) |
| [Color] | Terminal/colors/Light Red | Color(1.0, 0.0, 0.0, 1.0) |
| [Color] | Terminal/colors/Light Yellow | Color(1.0, 1.0, 0.0, 1.0) |
| [Color] | Terminal/colors/Magenta | Color(0.5, 0.0, 0.5, 1.0) |
| [Color] | Terminal/colors/Red | Color(0.5, 0.0, 0.0, 1.0) |
| [Color] | Terminal/colors/White | Color(1.0, 1.0, 1.0, 1.0) |
| [Color] | Terminal/colors/Yellow | Color(0.5, 0.5, 0.0, 1.0) |
| [Font] | Terminal/fonts/Bold | |
| [Font] | Terminal/fonts/Bold Italic | |
| [Font] | Terminal/fonts/Italic | |
| [Font] | Terminal/fonts/Regular | |
## Signals
- **data_sent** **(** [PoolByteArray] data **)**
Emitted when some data comes out of the terminal.
This typically occurs when the user interacts with the terminal by typing on the keyboard or clicking somewhere.
Input can be interpreted differently depending on modifier keys and the terminal's settings/state.
In a typical setup, this data would be forwarded to the pseudoterminal.
---
- **key_pressed** **(** [String] data, [InputEventKey] event **)**
Emitted when a key is pressed. `data` is the data that would be emitted by the terminal via the `data_sent()` signal and may vary based on the terminal's state. `event` is the event captured by Godot in the `_gui_input(event)` method.
---
- **size_changed** **(** [Vector2] new_size **)**
Emitted when the terminal's size changes, typically in response to its `rect_size` changing.
`new_size.x` will be the number of columns and `new_size.y` will be the number of rows.
This information should be forwarded to a pseudoterminal if it is connected so that it can update its size accordingly.
## Property Descriptions
- [int] **rows**
| | |
|-----------|------|
| *Default* | 24 |
| *Setter* | None |
| *Getter* | None |
The number of rows in the terminal's rect.
When using a monospace font, this is typically the number of characters that can fit from the top to the bottom.
It will automatically update as the Control's rect_size changes, and therefore shouldn't be used to set the size of the terminal directly.
---
- [int] **cols**
| | |
|-----------|------|
| *Default* | 80 |
| *Setter* | None |
| *Getter* | None |
The number of columns in the terminal's rect.
When using a monospace font, this is typically the number of characters that can fit from one side to another.
It will automatically update as the Control's rect_size changes, and therefore shouldn't be used to set the size of the terminal directly.
## Method Descriptions
- void **write** **(** [String]|[PoolByteArray] data **)**
Writes data to the terminal emulator. Accepts either a [String] or [PoolByteArray].
Typically it would be connected to the output of a pseudoterminal.
Example:
```gdscript
$Terminal.write("Hello World")
$Terminal.write("Hello World".to_utf8())
$Terminal.write(PoolByteArray([0x1b, 0x9e])
```
[CanvasItem]: https://docs.godotengine.org/en/stable/classes/class_canvasitem.html
[Color]: https://docs.godotengine.org/en/stable/classes/class_color.html
[Control]: https://docs.godotengine.org/en/stable/classes/class_control.html
[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html
[Font]: https://docs.godotengine.org/en/stable/classes/class_font.html
[InputEventKey]: https://docs.godotengine.org/en/stable/classes/class_inputeventkey.html
[int]: https://docs.godotengine.org/en/stable/classes/class_int.html
[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html
[PoolByteArray]: https://docs.godotengine.org/en/stable/classes/class_poolbytearray.html
[String]: https://docs.godotengine.org/en/stable/classes/class_string.html
[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html

3777
addons/godot_xterm/nodes/terminal/docs/flow_diagram.svg
View file

File diff suppressed because one or more lines are too long
Side by side

Before

Width:  |  Height:  |  Size: 360 KiB

BIN
addons/godot_xterm/nodes/terminal/docs/important_properties.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 11 KiB

1
docs/wiki Submodule

@ -0,0 +1 @@
Subproject commit 367cc1bdf4882b037677453d97583fbfbfc47544