+
+# GodotXterm - Terminal Emulator
+
+
-
-# GodotXterm - Terminal Emulator
-
-- Emitted when data is read from the pseudoterminal master device. +**data_received** **(** {{PoolByteArray}} data **)** ---- +Emitted when data is read from the pseudoterminal master device. -- **exited** **(** [int] exit_code, [int] signum **)** +
- Emitted when the child program exits. `exit_code` is the exit status of the child program and `signum` is the number of the signal that terminated the child program. +**exited** **(** {{int}} exit_code, {{int}} signum **)** + +Emitted when the child program exits. `exit_code` is the exit status of the child program and `signum` is the number of the signal that terminated the child program. + +
## Enumerations -### enum **Signal**: +
+ +enum **Signal**: - **SIGHUP** = 1 --- Hangup. - **SIGINT** = 2 --- Terminal interrupt signal. @@ -73,121 +73,119 @@ See issue [\#25](https://github.com/lihop/godot-xterm/issues/25). - **SIGALRM** = 14 --- Alarm clock. - **SIGTERM** = 15 --- Termination signal. + + ## Property Descriptions -### [NodePath] **terminal_path** +
-| | | -| --------- | ------------------------ | -| _Default_ | None | -| _Setter_ | set_terminal_path(value) | -| _Getter_ | None | +{{NodePath}} **terminal_path** -[NodePath] to a [Terminal]. Setting this path will automatically connect the appropriate signals of both nodes for standard operation. It will also disconnected the signals of the previously set terminal, if any. +| | | +| --------- | --------------------------------------------- | +| _Default_ | None | +| _Setter_ | void set_terminal_path ( {{NodePath}} value ) | +| _Getter_ | None | ---- +{{NodePath}} to a {{Terminal}}. Setting this path will automatically connect the appropriate signals of both nodes for standard operation. It will also disconnected the signals of the previously set terminal, if any. -- [int] **cols** +
- | | | - | --------- | --------------- | - | _Default_ | `80` | - | _Setter_ | set_cols(value) | - | _Getter_ | None | +{{int}} **cols** - The column size in characters. +| | | +| --------- | ------------------------------- | +| _Default_ | 80 | +| _Setter_ | void set_cols ( {{int}} value ) | +| _Getter_ | None | ---- +The column size in characters. -- [int] **rows** +
- | | | - | --------- | --------------- | - | _Default_ | `24` | - | _Setter_ | set_rows(value) | - | _Getter_ | None | +{{int}} **rows** - The row size in characters. +| | | +| --------- | ------------------------------- | +| _Default_ | 24 | +| _Setter_ | void set_rows ( {{int}} value ) | +| _Getter_ | None | ---- +The row size in characters. -- [Dictionary] **env** +
- | | | - | --------- | ------------------------------------------------------ | - | _Default_ | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` | - | _Setter_ | None | - | _Getter_ | None | +{{Dictionary}} **env** - Environment variables to be set for the child program. +| | | +| --------- | ------------------------------------------------------ | +| _Default_ | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` | +| _Setter_ | None | +| _Getter_ | None | ---- +Environment variables to be set for the child program. -- [bool] **use_os_env** +
- | | | - | --------- | ------ | - | _Default_ | `true` | - | _Setter_ | None | - | _Getter_ | None | +{{bool}} **use_os_env** - If `true` the environment variables from `env` will be merged with the environment variables of the current program (i.e. Godot), with the variables from `env` taking precedence over the environment variables of the current program. +| | | +| --------- | ---- | +| _Default_ | true | +| _Setter_ | None | +| _Getter_ | None | + +If `true` the environment variables from `env` will be merged with the environment variables of the current program (i.e. Godot), with the variables from `env` taking precedence over the environment variables of the current program. + + ## Method Descriptions -- [Error] **fork** **(** [String] file=`$SHELL`, [PoolStringArray] args=[], [String] cwd=`$PWD`, [int] cols=80, [int] rows=24 **)** +
- Opens a pseudoterminal and starts a new process using the program specified by `file`. - `file` defaults to the value of the `SHELL` environment variable, falling back to `sh`. - The arguments specified in `args` are passed to the program. - `cwd` is the directory in which the program will be executed. Defaults to the working directory of the current program (typically the project directory, when running from editor). - `cols` is the initial number of columns and `rows` is the initial number of rows. - Returns [OK] if successful. +{{Error}} **fork** **(** {{String}} file=$SHELL, {{PoolStringArray}} args=[ ], {{String}} cwd=$PWD, {{int}} cols=80, {{int}} rows=24 **)** - See also Godot's [OS.execute()](https://docs.godotengine.org/en/stable/classes/class_os.html#class-os-method-execute) method. +Opens a pseudoterminal and starts a new process using the program specified by `file`. +`file` defaults to the value of the `SHELL` environment variable, falling back to `sh`. +The arguments specified in `args` are passed to the program. +`cwd` is the directory in which the program will be executed. Defaults to the working directory of the current program (typically the project directory, when running from editor). +`cols` is the initial number of columns and `rows` is the initial number of rows. +Returns {{OK}} if successful. ---- +:::{seealso} +Godot's {{ '[OS.execute()]({}/classes/class_os.html#class-os-method-execute)'.format(godot_docs) }} method. +::: -- void **kill** **(** [int] signum=1 **)** +
- Sends the specified signal (`signum`) to the PTY's child process, if any. Defaults to 1 (SIGHUP). +void **kill** **(** {{int}} signum=1 **)** - See also Godot's [OS.kill()](https://docs.godotengine.org/en/stable/classes/class_os.html#class-os-method-kill) method. +Sends the specified signal (`signum`) to the PTY's child process, if any. Defaults to `1` (`SIGHUP`). ---- +:::{seealso} +Godot's {{ '[OS.kill()]({}/classes/class_os.html#class-os-method-kill)'.format(godot_docs) }} method. +::: -- [Error] **open** **(** [int] cols=80, [int] rows=24 **)** +
- Opens a pseudoterminal but does not start any process. Returns [OK] if successful. +{{Error}} **open** **(** {{int}} cols=80, {{int}} rows=24 **)** ---- +Opens a pseudoterminal but does not start any process. Returns {{OK}} if successful. -- void **resize** **(** [int] cols, [int] rows **)** +
- Resizes the dimensions of the pseudoterminal. +void **resize** **(** {{int}} cols, {{int}} rows **)** ---- +Resizes the dimensions of the pseudoterminal. -- void **resizev** **(** [Vector2] size **)** +
- Same as resize, but accepts a [Vector2] where `x` is cols and `y` is rows. +void **resizev** **(** {{Vector2}} size **)** ---- +Same as resize, but accepts a {{Vector2}} where `x` is cols and `y` is rows. -- void **write** **(** [String] \| [PoolByteArray] data **)** +
- Writes data to the pseudoterminal master device. +void **write** **(** {{String}}\|{{PoolByteArray}} data **)** -[Dictionary]: https://docs.godotengine.org/en/stable/classes/class_dictionary.html -[Error]: https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#enum-globalscope-error -[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html -[NodePath]: https://docs.godotengine.org/en/stable/classes/class_nodepath.html -[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html -[OK]: https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#class-globalscope-constant-ok -[PoolByteArray]: https://docs.godotengine.org/en/stable/classes/class_poolbytearray.html -[PoolStringArray]: https://docs.godotengine.org/en/stable/classes/class_poolstringarray.html -[String]: https://docs.godotengine.org/en/stable/classes/class_string.html -[Terminal]: /api/terminal -[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html -[bool]: https://docs.godotengine.org/en/stable/classes/class_bool.html -[int]: https://docs.godotengine.org/en/stable/classes/class_int.html +Writes data to the pseudoterminal master device. diff --git a/docs/api/terminal.md b/docs/api/terminal.md index 1a5ae2e..6015a66 100644 --- a/docs/api/terminal.md +++ b/docs/api/terminal.md @@ -1,14 +1,6 @@ ---- -layout: default -title: Terminal -parent: API -nav_order: 2 -permalink: /api/terminal ---- - # Terminal -**Inherits:** [Control] < [CanvasItem] < [Node] < [Object] +**Inherits:** {{Control}} < {{CanvasItem}} < {{Node}} < {{Object}} A Terminal emulator Control node. @@ -17,7 +9,7 @@ For an exhaustive list of terminal control sequences (not all of which are suppo ## Overview - + "Terminal Flow Diagram" is a derivative of ["computer keyboard 2"](https://openclipart.org/detail/2396/computer-keyboard-2) and ["monitor"](https://openclipart.org/detail/1637/monitor), from U.S. patent drawings, uploaded by [johnny_automatic](https://openclipart.org/artist/johnny_automatic), used under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/). ### (1) User Input @@ -44,165 +36,172 @@ For example if the string `"\u001b[38;2;0;255;0;mA"` was written to the terminal | Type | Name | Default | | ------------ | ------------------------------------ | ------- | -| [bool] | [bell_muted](#prop-bell_muted) | `false` | -| [float] | [bell_cooldown](#prop-bell_cooldown) | `0.1` | -| [UpdateMode] | [update_mode](#prop-update_mode) | `AUTO` | +| {{bool}} | [bell_muted](#prop-bell_muted) | false | +| {{float}} | [bell_cooldown](#prop-bell_cooldown) | 0.1 | +| [UpdateMode] | [update_mode](#prop-update_mode) | AUTO | ## Methods -| Returns | Signature | -| -------- | ----------------------------------------------------------------- | -| void | [clear](#mthd-clear) **()** | -| [String] | [copy_all](#mthd-copy_all) **()** | -| [String] | [copy_selection](#mthd-copy_selection) **()** | -| [int] | [get_cols](#mthd-get_cols) **()** | -| [int] | [get_rows](#mthd-get_rows) **()** | -| void | [write](#mthd-write) **(** [String] \| [PoolByteArray] data **)** | +| Returns | Signature | +| ---------- | ------------------------------------------------------------------- | +| void | [clear](#mthd-clear) **( )** | +| {{String}} | [copy_all](#mthd-copy_all) **( )** | +| {{String}} | [copy_selection](#mthd-copy_selection) **( )** | +| {{int}} | [get_cols](#mthd-get_cols) **( )** | +| {{int}} | [get_rows](#mthd-get_rows) **( )** | +| void | [write](#mthd-write) **(** {{String}}\|{{PoolByteArray}} data **)** | ## Signals -- **bell** **()** +
- Emitted when the [bell character](https://en.wikipedia.org/wiki/Bell_character) (`"\u0007"`) is written to the terminal. +**bell** **(** **)** ---- +Emitted when the [bell character](https://en.wikipedia.org/wiki/Bell_character) (`"\u0007"`) is written to the terminal. -- **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. - Input can be interpreted differently depending on modifier keys and the terminal's settings/state. +**data_sent** **(** {{PoolByteArray}} data **)** - When connected to a [PTY], this data will be forwarded to it. +Emitted when some data comes out of the terminal. +This typically occurs when the user interacts with the terminal by typing on the keyboard. +Input can be interpreted differently depending on modifier keys and the terminal's settings and state. ---- +:::{note} +When connected to a {{PTY}}, this data will be forwarded to it. +::: -- **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()`](#sgnl-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. +**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()`](#sgnl-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. +**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. + +
## Enumerations - enum **UpdateMode**: +
-- **DISABLED** = **0** --- The terminal's `update()` method will never be called. No new cells will be drawn. -- **AUTO** = **1** --- Only changed cells will be drawn after `update()` is called, but will switch to **ALL_NEXT_FRAME** when mass redraws are required. -- **ALL** = **2** --- Every cell will be drawn on every `update()` call. -- **ALL_NEXT_FRAME** = **3** --- Draws every cell afetr the next `update()` call, then returns to **AUTO**. +enum **UpdateMode**: + +- **DISABLED** = 0 --- The terminal's `update()` method will never be called. No new cells will be drawn. +- **AUTO** = 1 --- Only changed cells will be drawn after `update()` is called, but will switch to `ALL_NEXT_FRAME` when mass redraws are required. +- **ALL** = 2 --- Every cell will be drawn on every `update()` call. +- **ALL_NEXT_FRAME** = 3 --- Draws every cell after the next `update()` call, then returns to `AUTO`. + +
## Property Descriptions -- [bool] **bell_muted** +
- | | | - | --------- | ------- | - | _Default_ | `false` | - | _Setter_ | None | - | _Getter_ | None | +{{bool}} **bell_muted** - If muted, no [`bell`](#sgnl-bell) signal will be emitted when the bell character (`"\u0007"`) is written to the terminal. +| | | +| --------- | ----- | +| _Default_ | false | +| _Setter_ | None | +| _Getter_ | None | ---- +If muted, no [`bell`](#sgnl-bell) signal will be emitted when the bell character (`"\u0007"`) is written to the terminal. -- [float] **bell_cooldown** +
- | | | - | --------- | ----- | - | _Default_ | `0.1` | - | _Setter_ | None | - | _Getter_ | None | +{{float}} **bell_cooldown** - The minimum amount of time to wait before emitting another [`bell`](#sgnl-bell) signal on subsequent writes of the bell character. - Writing the bell character too frequently, for example by running the command `while true; do echo -e "\a"; done`, - can have a negative impact on performance depending on how the signal is connected. - This property allows throttling of that signal. +| | | +| --------- | ---- | +| _Default_ | 0.1 | +| _Setter_ | None | +| _Getter_ | None | ---- +The minimum amount of time to wait before emitting another [`bell`](#sgnl-bell) signal on subsequent writes of the bell character. -- [UpdateMode] **update_mode** +:::{caution} +Writing the bell character too frequently, for example by running the command `while true; do echo -e "\a"; done`, +can have a negative impact on performance depending on how the signal is connected. +This property allows throttling of that signal's emission. +::: - | | | - | --------- | ---------------------- | - | _Default_ | `AUTO` | - | _Setter_ | set_update_mode(value) | - | _Getter_ | None | +
- Determines which cells of the terminal will be updated when its state changes. - By default `AUTO` will only update cells that changed, but will update all cells (i.e. the entire screen) on major changes, - such as terminal resize. - If you are having trouble with the terminal not updating correctly or exhibiting artifacts, you can try remedying this by setting `update_mode` to `ALL`, however, this will have a negative impact on performance. +[UpdateMode] **update_mode** + +| | | +| --------- | ------------------------------------------- | +| _Default_ | AUTO | +| _Setter_ | void set_update_mode ( [UpdateMode] value ) | +| _Getter_ | None | + +Determines which cells of the terminal will be updated when its state changes. +By default `AUTO` will only update cells that changed, but will update all cells (i.e. the entire screen) on major changes, +such as terminal resize. + +:::{hint} +If the screen is not updating properly, then setting the `update_mode` to `ALL` can be a workaround for this. However, this will have a negative impact on performance. Update issues should be reported to [the issue tracker](https://github.com/lihop/godot-xterm/issues). +::: + +
## Method Descriptions -- void **clear** **()** +
- Removes all but the bottommost row of the terminal including scrollback buffer. +void **clear** **( )** ---- +Removes all but the bottommost row of the terminal including scrollback buffer. -- [String] **copy_all** **()** +
- Copies all of the text in the terminal including scrollback buffer. +{{String}} **copy_all** **( )** ---- +Copies all of the text in the terminal including scrollback buffer. -- [String] **copy_selection** **()** +
- Copies only selected (i.e. highlighted) text in the terminal. - Will return an empty string if nothing is highligted. +{{String}} **copy_selection** **( )** ---- +Copies only selected (i.e. highlighted) text in the terminal. +Will return an empty string if nothing is highlighted. -- [int] **get_cols** **()** +
- Returns the width of the terminal in characters. - When using a monospace font, this is the number of visible characters that can fit from one side of the terminal to the other in a single row. - It will automatically update according to the terminal's rect_size and theme's font size. +{{int}} **get_cols** **( )** ---- +Returns the width of the terminal in characters. +When using a monospace font, this is the number of visible characters that can fit from one side of the terminal to the other in a single row. +It will automatically update according to the terminal's rect_size and theme's font size. -- [int] **get_rows** **()** +
- Returns the height of the terminal in characters. - When using a monospace font, this is the number of visible characters that can fit from the top of the terminal to the bottom in a single column. - It will automatically update according to the terminal's rect_size and theme's font size. +{{int}} **get_rows** **( )** ---- +Returns the height of the terminal in characters. +When using a monospace font, this is the number of visible characters that can fit from the top of the terminal to the bottom in a single column. +It will automatically update according to the terminal's rect_size and theme's font size. -- 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 [PTY]'s [`data_received()`](/api/pty#sgnl-data_received) signal. +void **write** **(** {{String}}\|{{PoolByteArray}} data **)** - Example: +Writes data to the terminal emulator. Accepts either a {{String}} or {{PoolByteArray}}. +Typically it would be connected to the output of a {{PTY}}'s [`data_received()`](pty.md#sgnl-data_received) signal. - ```gdscript - $Terminal.write("Hello World") - $Terminal.write("Hello World".to_utf8()) - $Terminal.write(PoolByteArray([0x1b, 0x9e]) - ``` +Example: + +```gdscript +$Terminal.write("Hello World") +$Terminal.write("Hello World".to_utf8()) +$Terminal.write(PoolByteArray([0x1b, 0x9e]) +``` -[AudioStream]: https://docs.godotengine.org/en/stable/classes/class_audiostream.html -[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 -[Font]: https://docs.godotengine.org/en/stable/classes/class_font.html -[InputEventKey]: https://docs.godotengine.org/en/stable/classes/class_inputeventkey.html -[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html -[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html -[PoolByteArray]: https://docs.godotengine.org/en/stable/classes/class_poolbytearray.html -[PTY]: /api/pty -[String]: https://docs.godotengine.org/en/stable/classes/class_string.html [UpdateMode]: #enum-update_mode -[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html -[bool]: https://docs.godotengine.org/en/stable/classes/class_bool.html -[float]: https://docs.godotengine.org/en/stable/classes/class_float.html -[int]: https://docs.godotengine.org/en/stable/classes/class_int.html diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..0c43690 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,65 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'GodotXterm' +copyright = '2024, Leroy Hopson' +author = 'Leroy Hopson' +godot_version = '3.5' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['myst_parser', 'sphinx_rtd_theme'] +myst_enable_extensions = ['colon_fence', 'substitution'] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +current_branch = os.getenv('CURRENT_BRANCH', 'main') +godot_class = 'https://docs.godotengine.org/en/' + godot_version + '/classes/class_{}' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_static_path = ['_static'] +html_theme = 'sphinx_rtd_theme' +html_theme_options = { + 'logo_only': True +} +html_logo = '_static/images/logo.png' + +myst_substitutions = { + 'repo': 'https://github.com/lihop/godot-xterm/blob/{}'.format(current_branch), + 'godot_docs': 'https://docs.godotengine.org/en/' + godot_version, + + 'PTY': '[PTY](/api/pty.md)', + 'Terminal': '[Terminal](/api/terminal.md)', + + # Godot classes. + 'AudioStream': '[AudioStream](' + godot_class.format('audiostream.html') + ')', + 'CanvasItem': '[CanvasItem](' + godot_class.format('canvasitem.html') + ')', + 'Color': '[Color](' + godot_class.format('color.html') + ')', + 'Control': '[Control](' + godot_class.format('control.html') + ')', + 'Error': '[Error](' + godot_class.format('%40globalscope.html#enum-globalscope-error') + ')', + 'Font': '[Font](' + godot_class.format('font.html') + ')', + 'InputEventKey': '[InputEventKey](' + godot_class.format('inputeventkey.html') + ')', + 'Node': '[Node](' + godot_class.format('node.html') + ')', + 'NodePath': '[NodePath](' + godot_class.format('nodepath.html') + ')', + 'Object': '[Object](' + godot_class.format('object.html') + ')', + 'OK': '[OK](' + godot_class.format('%40globalscope.html#class-globalscope-constant-ok') + ')', + 'PoolByteArray': '[PoolByteArray](' + godot_class.format('poolbytearray.html') + ')', + 'PoolStringArray': '[PoolStringArray](' + godot_class.format('poolstringarray.html') + ')', + 'String': '[String](' + godot_class.format('string.html') + ')', + 'Vector2': '[Vector2](' + godot_class.format('vector2.html') + ')', + 'bool': '[bool](' + godot_class.format('bool.html') + ')', + 'float': '[float](' + godot_class.format('float.html') + ')', + 'int': '[int](' + godot_class.format('int.html') + ')', +} + diff --git a/docs/favicon.ico b/docs/favicon.ico deleted file mode 100644 index eea3b14..0000000 Binary files a/docs/favicon.ico and /dev/null differ diff --git a/docs/index.md b/docs/index.md index cc1884c..30d301d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,30 @@ ---- -layout: default -title: Introduction -nav_order: 1 -permalink: / ---- +
-{% include_relative README.md %}
+# GodotXterm - Terminal Emulator
+
++ +[](#supported-godot-versions) +[](https://github.com/lihop/godot-xterm/blob/stable/LICENSE.md) +[](https://github.com/lihop/godot-xterm/actions/workflows/main.yml) + +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 section](introduction.md#features) for more detail. + + + +[](https://lihop.github.io/godot-xterm-dist/demo) +[](https://github.com/lihop/godot-xterm) + +```{toctree} +:maxdepth: 2 +:caption: Table of Contents + +introduction +setup/index +api/index +CHANGELOG +``` diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000..53318dd --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,112 @@ +# Introduction + +## 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"](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html). + +- ### {{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/tree/master/Xresources) format. + +## Screenshots + +| | | +| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +|  |  | +|  |  | + +## Demos and Examples + +The GodotXterm repository contains several example scenes in the {{ '[`/examples`]({}/examples)'.format(repo) }} directory. +If cloning the repo, you will need to either build the GDNative binaries from source or copy pre-compiled binaries into your project. +See the [Setup section](/setup/index.md) for more details. + +Other examples of GodotXterm usage are available online: + +- [**Live Demo**](https://lihop.github.io/godot-xterm-dist/demo): An HTML5 export of the GodotXterm repo's example scenes. + +- [**The Guest**](https://lihop.itch.io/the-guest): A Linux only submission to the [Linux Game Jam 2022](https://itch.io/jam/linux-game-jam-2022). Uses GodotXterm in conjunction with the [gdtemu addon](https://github.com/lihop/gdtemu) and Linux's Kernel-based Virtual Machine, to provide the player with an interactive VM that can be used in the game world. + +- [**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). + +Are you using GodotXterm in your project and want it listed here? Please [open a pull request](https://github.com/lihop/godot-xterm/pulls) to have it added. + +## Supported Godot Versions + +GodotXterm aims to support the current stable release of Godot, but may lag slightly. +Currently, Godot 3.x versions are supported with support for Godot 4 coming soon. + +:::{tip} +Godot 3.3.x versions are no longer officially supported but _may_ work if the GDNative libraries are compiled using an older version of godot-cpp. +::: + +## Installation + +GodotXterm is available on the [Godot Asset Library](https://godotengine.org/asset-library/asset/1007). +For more ways to install see the [Setup section](/setup/index.md). + +## Help + +Documentation is available here on [Read the Docs](https://docs.godot-xterm.nix.nz). +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 the project repo. + +## License + +Copyright (c) 2020-2024, Leroy Hopson and [contributors](https://github.com/lihop/godot-xterm/graphs/contributors) (MIT License). + +See the {{ '[full license]({}/LICENSE.md)'.format(repo) }}. + +### 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)'.format(repo) }} 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)'.format(repo) }} 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]({}/addons/godot_xterm/themes/fonts/hack/LICENSE.md)'.format(repo) }}. + +### 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 the project repository for demo and testing purposes. They are: + +#### Fonts + +- The **bold**, _italic_, and **_bold italic_** styles of the Hack font, covered by the same Hack font license as above. +- Nerd Fonts. Combines symbols from a multitude of other fonts. See {{ '[license information]({}/themes/fonts/nerd_fonts/README.md)'.format(repo) }}. +- Noto Color Emoji. Released under the {{ '[SIL Open Font License]({}/themes/fonts/noto_color_emoji/LICENSE_OFL.txt)'.format(repo) }}. +- 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)' }}. + +#### Sounds + +- {{ '[bell.wav]({}/themes/audio/bell.wav)'.format(repo) }} 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/). diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..954237b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/media/live_demo_button.png b/docs/media/live_demo_button.png deleted file mode 100644 index a4a96cc..0000000 Binary files a/docs/media/live_demo_button.png and /dev/null differ diff --git a/docs/media/pty_diagram.png b/docs/media/pty_diagram.png deleted file mode 100644 index b780094..0000000 Binary files a/docs/media/pty_diagram.png and /dev/null differ diff --git a/docs/media/view_it_on_github_button.png b/docs/media/view_it_on_github_button.png deleted file mode 100644 index e991290..0000000 Binary files a/docs/media/view_it_on_github_button.png and /dev/null differ diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..531581e --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +myst-parser==2.0.0 +sphinx-rtd-theme==2.0.0 diff --git a/docs/setup/building_from_source.md b/docs/setup/building_from_source.md index abecc22..695bb9e 100644 --- a/docs/setup/building_from_source.md +++ b/docs/setup/building_from_source.md @@ -1,11 +1,3 @@ ---- -layout: default -title: Building From Source -parent: Setup -nav_order: 2 -permalink: /setup/building-from-source ---- - # Building From Source Building GodotXterm from source consists of four steps: @@ -15,7 +7,9 @@ Building GodotXterm from source consists of four steps: 3. Compile godot-cpp using scons. 4. Compile libtsm and libgodotxterm using scons. -This plugin follows the same format as the [GDNative C++ Example](https://docs.godotengine.org/en/stable/tutorials/plugins/gdnative/gdnative-cpp-example.html). So if you can compile that example then you are 90% of the way there. The main difference is using CMake to compile libuv. +:::{hint} +This plugin follows the same format as the {{ '[GDNative C++ Example]({}/tutorials/plugins/gdnative/gdnative-cpp-example.html)'.format(godot_docs) }}. So if you can compile that example then you are 90% of the way there. The main difference is using CMake to compile libuv. +::: ## Dependencies @@ -28,31 +22,28 @@ This plugin follows the same format as the [GDNative C++ Example](https://docs.g Run the build script in `addons/godot-xterm/native`: -``` +```sh cd addons/godot_xterm/native ./build.sh ``` -On Windows you can use `git-bash` to run this script. +:::{tip} +On Windows, you can use `git-bash` to run this script. Provided the dependencies above are installed then it should "just workâ˘". +::: Binaries for your platform will be installed in `addons/godot_xterm/native/bin`. -The [build.sh] script accepts args `--target` which can be set to `debug` (default) or `release` and `--disable-pty` to compile only the dependencies of [Terminal] node and not [PTY] node (even on platforms that support it). +The {{ '[build.sh]({}/addons/godot_xterm/native/build.sh)'.format(repo) }} script accepts args `--target` which can be set to `debug` (default) or `release` and `--disable-pty` to compile only the dependencies of {{Terminal}} node and not {{PTY}} node (even on platforms that support it). -### The Hard Way +## The Hard Way -If you are having trouble compiling, study the [build.sh] script and the GitHub actions workflow in [main.yml] to see what commands are being run and how dependencies are installed. You can also dig into the [SConstruct](https://github.com/lihop/godot-xterm/blob/stable/addons/godot_xterm/native/SConstruct) file, and don't forget to refer back to the [GDNative C++ Example](https://docs.godotengine.org/en/stable/tutorials/plugins/gdnative/gdnative-cpp-example.html). +If you are having trouble compiling, study the {{ '[build.sh]({}/addons/godot_xterm/native/build.sh)'.format(repo) }} script and the GitHub actions workflow in {{ [main.yml]({}/.github/workflows/main.yml)'.format(repo) }} to see what commands are being run and how dependencies are installed. You can also dig into the {{ '[SConstruct]({}/addons/godot_xterm/native/SConstruct)'.format(repo) }} file, and don't forget to refer back to the {{ '[GDNative C++ Example]({}/tutorials/plugins/gdnative/gdnative-cpp-example.html)'.format(godot_docs) }}. -Also feel free to open a new discussion in the [discussions](https://github.com/lihop/godot-xterm/discussions) section of this project. +Also feel free to open a new discussion in the [discussions](https://github.com/lihop/godot-xterm/discussions) section of the project repo. ## Cross Compiling -Although the SConstruct file contains some logic for cross-compiling, it has never been tested. If you want compile for other platforms consider forking this repo and then pushing your changes to GitHub. The workflow defined in [main.yml] will run and build the library for all supported platforms (Linux, macOS, Windows, and HTML5). +Although the SConstruct file contains some logic for cross-compiling, it has never been tested. If you want compile for other platforms consider forking this repo and then pushing your changes to GitHub. The workflow defined in {{ '[main.yml]({}/.github/workflows/main.yml)'.format(repo) }} will run and build the library for all supported platforms (Linux, macOS, Windows, and HTML5). -Additionally, If you have `docker` and `docker-compose` installed, the [build.sh] script will also try to build the HTML5 binary inside a docker container and copy them to `addons/godot_xterm/native/bin`. - -[PTY]: /api/pty -[Terminal]: /api/terminal -[build.sh]: https://github.com/lihop/godot-xterm/blob/stable/addons/godot_xterm/native/build.sh -[main.yml]: https://github.com/lihop/godot-xterm/blob/stable/.github/workflows/main.yml +Additionally, If you have `docker` and `docker-compose` installed, the {{ '[build.sh]({}/addons/godot_xterm/native/build.sh)'.format(repo) }} script will also try to build the HTML5 binary inside a docker container and copy them to `addons/godot_xterm/native/bin`. diff --git a/docs/setup/index.md b/docs/setup/index.md new file mode 100644 index 0000000..d0b7496 --- /dev/null +++ b/docs/setup/index.md @@ -0,0 +1,7 @@ +# Setup + +```{toctree} +:maxdepth: 1 +precompiled_binaries +building_from_source +``` diff --git a/docs/setup/precompiled_binaries.md b/docs/setup/precompiled_binaries.md index 064af8d..b008459 100644 --- a/docs/setup/precompiled_binaries.md +++ b/docs/setup/precompiled_binaries.md @@ -1,50 +1,38 @@ ---- -layout: default -title: Precompiled Binaries -parent: Setup -nav_order: 1 -permalink: /setup/precompiled-binaries ---- - # Precompiled Binaries -{: .no_toc } - -Installing GodotXterm using precompiled binaries means that you wont be required +Installing GodotXterm using precompiled binaries means that you won't be required to use a C/C++ compiler to build the project from source. It is simply a matter of copying files to the correct location in your project. These files can be -installed from several sources: +installed from several sources. -1. TOC - {:toc} - -**Note:** precompiled binaries will only work with certain versions of Godot +:::{warning} +Precompiled binaries will only work with certain versions of Godot (usually the current stable release). If you need binaries for a different or custom Godot version, or want to make modifications to the C/C++ code, please refer to the section on [Building From Source](/setup/building-from-source). +::: ## Godot Asset Library GodotXterm can be installed from the [Godot Asset Library](https://godotengine.org/asset-library/asset/1007). -See the [Godot Asset Library documentation](https://docs.godotengine.org/en/stable/community/asset_library/using_assetlib.html) for more info on how to use it. +See the {{ '[Godot Asset Library documentation]({}/community/asset_library/using_assetlib.html)'.format(godot_docs) }} for more info on how to use it. ## Gd-plug Plugin Manager If you are using the gd-plug plugin manager you can add the following line to your `plug.gd` file: ``` -plug("lihop/godot-xterm-dist", {commit = "a1131a562e8e8f0c57b0ddf61de7fa015d463ba0", include = ["addons/godot_xterm"]}) +plug("lihop/godot-xterm-dist", {tag = "2.2.1", include = ["addons/godot_xterm"]}) ``` -Replace the commit hash with the hash of the GodotXterm version you wish to install. -See [tags](https://github.com/lihop/godot-xterm-dist/tags) for a list of versions and their corresponding commit hashes. +Replace the tag with that of the GodotXterm version you wish to install (see [tags](https://github.com/lihop/godot-xterm-dist/tags)). See the [gd-plug documentation](https://github.com/imjp94/gd-plug/blob/master/README.md) for more info on how to use it. ## Manual Installation Alternatively, GodotXterm can be installed manually in two steps: -1. Copy the [`addons/godot_xterm`](https://github.com/lihop/godot-xterm/tree/stable/addons/godot_xterm) directory to the `addons` directory of your Godot project. +1. Copy the {{ '[`addons/godot_xterm`]({}/addons/godot_xterm)'.format(repo) }} directory to the `addons` directory of your Godot project. 2. Copy the GDNative binaries into `addons/godot_xterm/native/bin` directory. The easiest way to obtain the GDNative binaries is to download them from [the Releases page](https://github.com/lihop/godot-xterm/releases). @@ -58,5 +46,7 @@ After this your `addons/godot_xterm/native/bin` directory should contain the fol - `libgodot-xterm.windows.32.dll` - `libgodot-xterm.windows.64.dll` +:::{note} Debug builds are also available on the Releases page if required. Download and unzip `libgodot-xterm-debug.zip` instead of `libgodot-xterm-release.zip` to the same location. +::: diff --git a/docs/setup/setup.md b/docs/setup/setup.md deleted file mode 100644 index 482edbf..0000000 --- a/docs/setup/setup.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Setup -nav_order: 2 -has_children: true -permalink: /setup ---- - -# Setup diff --git a/project.godot b/project.godot index 914844c..a09b361 100644 --- a/project.godot +++ b/project.godot @@ -13,7 +13,7 @@ config_version=5 config/name="GodotXterm" run/main_scene="res://examples/menu/menu.tscn" config/features=PackedStringArray("4.2") -config/icon="res://docs/media/icon.png" +config/icon="res://docs/_static/images/icon.png" [display]
](./_static/images/screenshot_editor.png){kind=link}
](./_static/images/screenshot_the_guest.png){kind=link}
](./_static/images/screenshot_retro_term.jpg){kind=link}
](./_static/images/screenshot_xterminate.png){kind=link}