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

Update documentation and LICENSE

Browse source
This commit is contained in:
Leroy Hopson 2020-10-05 16:25:48 +07:00
parent 293d35f5c5
commit c66e478484
7 changed files with 186 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
LICENSE
View file

@ -1,6 +1,6 @@
MIT License
Copyright (c) 2020 Leroy Hopson
Copyright (c) 2020 Leroy Hopson and [contributors](https://github.com/lihop/godot-xterm/contributors)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal

86
README.md
View file

@ -1,36 +1,100 @@
<img align="left" width="64" height="64" src="icon.png">
# Godot Xterm Native
# GodotXterm
![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)
![Godot Version](https://img.shields.io/badge/godot-3.2+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
Native implementation of Godot Xterm using GDNative with [libtsm](https://github.com/Aetf/libtsm).
[![Build Status](https://travis-ci.org/lihop/godot-xterm.svg?branch=master)](https://travis-ci.org/lihop/godot-xterm)
Terminal emulator for Godot using GDNative and [libtsm](https://github.com/Aetf/libtsm).
**Note**: If you are looking for the purely gdscript version of this plugin it was too buggy and slow so is no longer being developed or maintained but can found [here](https://github.com/lihop/godot-xterm/tree/gdscript-unmaintained).
**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.
## Demo
![Screenshot of Main Menu Scene](./docs/screenshot.png)
Click the thumbnail to watch a demo video on youtube:
## Building
[![Demo video thumbnail](https://img.youtube.com/vi/_Tt4eQEBybo/0.jpg)](https://www.youtube.com/watch?v=_Tt4eQEBybo)
### All Operating Systems
**Important**: The main dependencies of this project are included as git submodules.
You can install them in this repo after cloning with:
```
git submodule update --init --recursive
```
In addition to these, you will need some other dependencies including:
- a C++ compiler (e.g. gcc)
- ar (part of GNU Binutils)
- CMake
- Python
- SCons
### Operating System Specific
#### NixOS
On NixOS you can simply run the [build.sh] script in the `addons/godot_xterm/native` directory:
```
cd addons/godot_xterm/native
./build.sh
```
All dependencies will be pulled in by nix-shell and the build steps will run.
#### Arch Linux and Ubuntu
See the [Arch Linux Dockerfile](dockerfiles/archlinux) and [Ubuntu Dockerfile](dockerfiles/ubuntu) for a list of packages that need to be installed. Once installed, run the [build.sh] script from the `addons/godot_xterm/native` directory:
```
cd addons/godot_xterm/native
bash ./build.sh
```
Make sure you use `bash` to run the script as the default interpreter is set to nix-shell.
#### Other
Other operating systems will probably be similar to the above. When in doubt check the documentation in the submodule repos, the [build.sh] script, and the [SConstruct] file.
## Usage
### Asciicast (.cast) file importer
[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 the Terminal node. Playing the animation will play the terminal session recording in the parent Terminal.
- ### [Terminal](addons/godot_xterm/nodes/terminal/README.md)
The main node provided by this plugin.
For an example, see the scene in [/examples/asciicast](/examples/asciicast).
- ### [Pseudoterminal](addons/godot_xterm/nodes/pseudoterminal/README.md)
A node that can be used to connect the Terminal to a shell. Currently Linux 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
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.
Copyright (c) 2020 Leroy Hopson (MIT License)
Copyright (c) 2020 [The GodotXterm authors](https://github.com/lihop/godot-xterm/graphs/contributors) (MIT License)<br>
The fonts used in this project are published under a seperate license.
See the various license files in the [subdirectories](addons/godot_xterm/themes/fonts/) for each font.
[build.sh]: /addons/godot_xterm/native/build.sh
[SConstruct]: /addons/godot_xterm/native/SConstruct

2
addons/godot_xterm/LICENSE
View file

@ -1,6 +1,6 @@
MIT License
Copyright (c) 2020 The GodotXterm authors (https://github.com/lihop/godot-xterm/contributors)
Copyright (c) 2020 Leroy Hopson and [contributors](https://github.com/lihop/godot-xterm/contributors)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal

51
addons/godot_xterm/nodes/pseudoterminal/README.md Normal file
View file

@ -0,0 +1,51 @@
# Pseudoterminal
**Inherits:** [Node] < [Object]
Can be used with the [Terminal] node to get an actual shell. Currently only tested/working on Linux.
## Methods
| Returns | Signature |
|---------|----------------------------------------|
| void | write **(** [PoolByteArray] data **)** |
| void | resize **(** [Vector2] size **)** |
## Signals
- **data_sent** **(** [PoolByteArray] data **)**
Emitted when some data comes out of the pseudoterminal.
In a typical setup this signal would be connected to the [Terminal]'s `write()` method.
---
- **exited** **(** [int] status **)**
Emitted when the pseudoterminal's process (typically a shell like `bash` or `sh`) has exited. `status` is the exit code.
For example, if you are using the terminal with a `bash` shell, then issuing the `exit` command would cause this signal to be emitted.
```bash
> exit
exit
```
## Method Descriptions
- void **write** **(** [PoolByteArray] data **)**
Writes data to the pseudoterminal. In a typical setup this would be connected to the [Terminal]'s `data_sent()` signal.
- void **resize** **(** [Vector2] size **)**
Used to notify the pseudoterminal about window size changes. In a typical setup it would be connected to the [Terminal]'s `size_changed()` signal.
[Node]: https://docs.godotengine.org/en/stable/classes/class_node.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
[Terminal]: ../terminal/README.md
[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html

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

@ -9,7 +9,7 @@ Terminal emulator.
<img align="right" src="./docs/important_properties.png"/>
- If you are not seeing anything in the terminal check that a theme has been set. If there is no theme, everything will be drawn in black by default.
- If you are not seeing anything in the terminal check that a theme has been set. If there is no theme, everything will be drawn in black by default. A default theme can be found in the [themes directory](../../themes).
- 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.
@ -19,15 +19,15 @@ Terminal emulator.
### (1) User Input
The users 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](../native/src/terminal.cpp).
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 down key, the terminal would
and the `data_sent` signal would be emitted with the value `"\u001b[A"`.
For a full list of escape sequences ["XTerm Control Sequences"](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html).
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
@ -36,7 +36,7 @@ In the other direction, characters can be sent to the terminal. This corresponds
### (4) Draw
The input from (3) is then intepreted by the terminal and drawn to the screen.
For example if the string "\u001b[39;m" was written to the terminal, then it would draw some colorful output 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
@ -47,6 +47,11 @@ For example if the string "\u001b[39;m" was written to the terminal, then it wou
## Methods
| Returns | Signature |
|---------|-------------------------------------------------|
| void | write **(** [String]\|[PoolByteArray] data **)** |
## Theme Properties
| Type | Name | Default |
@ -76,44 +81,63 @@ For example if the string "\u001b[39;m" was written to the terminal, then it wou
## Signals
- **data_sent** **(** PoolByteArray data **)**
- **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.
It might also occur.
Depending on several terminal settings can be interpreted differently, depending on modifier keys and the terminals settings/state.
In a typical setup, this data would be forwarded to the linux operating system.
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** **(** int row **)**
- **key_pressed** **(** [String] data, [InputEventKey] event **)**
Emitted when a key is pressed.
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* | set_rows(value) |
| *Getter* | get_rows(value) |
| *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 one side to another.
Therefore it is affected by the things thing.
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**
The number of columns in the terminal's rect.
| | |
|-----------|------|
| *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 **)**
- void **write** **(** [String]|[PoolByteArray] data **)**
Writes data to the terminal emulator. Accepts either a String or PoolByteArray.
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
@ -122,10 +146,14 @@ The number of columns in the terminal's rect.
$Terminal.write(PoolByteArray([0x1b, 0x9e])
```
[Control]: https://docs.godotengine.org/en/stable/classes/class_control.html#class-control
[CanvasItem]: https://docs.godotengine.org/en/stable/classes/class_canvasitem.html#class-canvasitem
[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html#class-node
[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html#class-object
[Color]: https://docs.godotengine.org/en/stable/classes/class_color.html#class-color
[Font]: https://docs.godotengine.org/en/stable/classes/class_font.html#class-font
[int]: https://docs.godotengine.org/en/stable/classes/class_int.html#class-int
[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

0
docs/.gdignore Normal file
View file

BIN
docs/screenshot.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 14 KiB