docs(rtd): move documentation to read the docs

This commit is contained in:
Leroy Hopson 2024-03-29 19:07:43 +13:00
parent 0bd0d39f41
commit bc15d8950f
No known key found for this signature in database
GPG key ID: D2747312A6DB51AA
44 changed files with 580 additions and 752 deletions

1
.gitattributes vendored
View file

@ -16,7 +16,6 @@
# Files to exclude from asset-lib download. # Files to exclude from asset-lib download.
/addons/gd-plug export-ignore /addons/gd-plug export-ignore
/CHANGELOG.md export-ignore
/default_env.tres export-ignore /default_env.tres export-ignore
/docs export-ignore /docs export-ignore
/.env.example export-ignore /.env.example export-ignore

1
.gitignore vendored
View file

@ -39,6 +39,7 @@ addons/*
!addons/godot_xterm/ !addons/godot_xterm/
docs/demo docs/demo
docs/logs docs/logs
docs/_build
# Imported translations (automatically generated from CSV files) # Imported translations (automatically generated from CSV files)
*.translation *.translation

29
README.md Normal file
View file

@ -0,0 +1,29 @@
<img align="left" width="64" height="64" src="./docs/_static/images/icon.png">
# GodotXterm - Terminal Emulator
<br/>
[![Godot Version](https://img.shields.io/badge/Godot-4.2+-blue.svg)](#supported-godot-versions)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/lihop/godot-xterm/blob/stable/LICENSE.md)
[![Build and Test](https://github.com/lihop/godot-xterm/actions/workflows/main.yml/badge.svg?event=schedule)](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](https://docs.godot-xterm.nix.nz/en/stable/introduction.html#features) of [the documentation](https://docs.godot-xterm.nix.nz/en/stable) for more detail.
The plugin currently supports Godot 3.x, with a Godot 4 (GDExtension) version under development on the [`main`](https://github.com/lihop/godot-xterm/tree/main) branch.
The latest code for the Godot 3 version can be found on the [`godot-3.x`](https://github.com/lihop/godot-xterm/tree/godot-3.x) branch.
<video width="100%" controls>
<source src="https://user-images.githubusercontent.com/3696783/126894061-a69eb6ad-9979-4723-ade7-829494a9fc87.mp4" />
</video>
<div id="video-preview">
https://user-images.githubusercontent.com/3696783/126894061-a69eb6ad-9979-4723-ade7-829494a9fc87.mp4
</div>
[![Live Demo](./docs/_static/images/button_live_demo.png)](https://lihop.github.io/godot-xterm-dist/demo)
[![View Documentation](./docs/_static/images/button_view_documentation.png)](https://docs.godot-xterm.nix.nz/en/stable)

View file

5
docs/.gitignore vendored
View file

@ -1,5 +0,0 @@
_site
.sass-cache
.jekyll-cache
.jekyll-metadata
vendor

13
docs/.readthedocs.yaml Normal file
View file

@ -0,0 +1,13 @@
version: "2"
build:
os: "ubuntu-22.04"
tools:
python: "3.10"
python:
install:
- requirements: docs/requirements.txt
sphinx:
configuration: docs/conf.py

View file

@ -1,25 +0,0 @@
---
permalink: /404.html
layout: default
---
<style type="text/css" media="screen">
.container {
margin: 10px auto;
max-width: 600px;
text-align: center;
}
h1 {
margin: 30px 0;
font-size: 4em;
line-height: 1;
letter-spacing: -1px;
}
</style>
<div class="container">
<h1>404</h1>
<p><strong>Page not found :(</strong></p>
<p>The requested page could not be found.</p>
</div>

View file

@ -1,2 +0,0 @@
source "https://rubygems.org"
gem "github-pages", "~> 227", group: :jekyll_plugins

View file

@ -1,261 +0,0 @@
GEM
remote: https://rubygems.org/
specs:
activesupport (6.0.5.1)
concurrent-ruby (~> 1.0, >= 1.0.2)
i18n (>= 0.7, < 2)
minitest (~> 5.1)
tzinfo (~> 1.1)
zeitwerk (~> 2.2, >= 2.2.2)
addressable (2.8.0)
public_suffix (>= 2.0.2, < 5.0)
coffee-script (2.4.1)
coffee-script-source
execjs
coffee-script-source (1.11.1)
colorator (1.1.0)
commonmarker (0.23.5)
concurrent-ruby (1.1.10)
dnsruby (1.61.9)
simpleidn (~> 0.1)
em-websocket (0.5.3)
eventmachine (>= 0.12.9)
http_parser.rb (~> 0)
ethon (0.15.0)
ffi (>= 1.15.0)
eventmachine (1.2.7)
execjs (2.8.1)
faraday (2.4.0)
faraday-net_http (~> 2.0)
ruby2_keywords (>= 0.0.4)
faraday-net_http (2.1.0)
ffi (1.15.5)
forwardable-extended (2.6.0)
gemoji (3.0.1)
github-pages (227)
github-pages-health-check (= 1.17.9)
jekyll (= 3.9.2)
jekyll-avatar (= 0.7.0)
jekyll-coffeescript (= 1.1.1)
jekyll-commonmark-ghpages (= 0.2.0)
jekyll-default-layout (= 0.1.4)
jekyll-feed (= 0.15.1)
jekyll-gist (= 1.5.0)
jekyll-github-metadata (= 2.13.0)
jekyll-include-cache (= 0.2.1)
jekyll-mentions (= 1.6.0)
jekyll-optional-front-matter (= 0.3.2)
jekyll-paginate (= 1.1.0)
jekyll-readme-index (= 0.3.0)
jekyll-redirect-from (= 0.16.0)
jekyll-relative-links (= 0.6.1)
jekyll-remote-theme (= 0.4.3)
jekyll-sass-converter (= 1.5.2)
jekyll-seo-tag (= 2.8.0)
jekyll-sitemap (= 1.4.0)
jekyll-swiss (= 1.0.0)
jekyll-theme-architect (= 0.2.0)
jekyll-theme-cayman (= 0.2.0)
jekyll-theme-dinky (= 0.2.0)
jekyll-theme-hacker (= 0.2.0)
jekyll-theme-leap-day (= 0.2.0)
jekyll-theme-merlot (= 0.2.0)
jekyll-theme-midnight (= 0.2.0)
jekyll-theme-minimal (= 0.2.0)
jekyll-theme-modernist (= 0.2.0)
jekyll-theme-primer (= 0.6.0)
jekyll-theme-slate (= 0.2.0)
jekyll-theme-tactile (= 0.2.0)
jekyll-theme-time-machine (= 0.2.0)
jekyll-titles-from-headings (= 0.5.3)
jemoji (= 0.12.0)
kramdown (= 2.3.2)
kramdown-parser-gfm (= 1.1.0)
liquid (= 4.0.3)
mercenary (~> 0.3)
minima (= 2.5.1)
nokogiri (>= 1.13.6, < 2.0)
rouge (= 3.26.0)
terminal-table (~> 1.4)
github-pages-health-check (1.17.9)
addressable (~> 2.3)
dnsruby (~> 1.60)
octokit (~> 4.0)
public_suffix (>= 3.0, < 5.0)
typhoeus (~> 1.3)
html-pipeline (2.14.2)
activesupport (>= 2)
nokogiri (>= 1.4)
http_parser.rb (0.8.0)
i18n (0.9.5)
concurrent-ruby (~> 1.0)
jekyll (3.9.2)
addressable (~> 2.4)
colorator (~> 1.0)
em-websocket (~> 0.5)
i18n (~> 0.7)
jekyll-sass-converter (~> 1.0)
jekyll-watch (~> 2.0)
kramdown (>= 1.17, < 3)
liquid (~> 4.0)
mercenary (~> 0.3.3)
pathutil (~> 0.9)
rouge (>= 1.7, < 4)
safe_yaml (~> 1.0)
jekyll-avatar (0.7.0)
jekyll (>= 3.0, < 5.0)
jekyll-coffeescript (1.1.1)
coffee-script (~> 2.2)
coffee-script-source (~> 1.11.1)
jekyll-commonmark (1.4.0)
commonmarker (~> 0.22)
jekyll-commonmark-ghpages (0.2.0)
commonmarker (~> 0.23.4)
jekyll (~> 3.9.0)
jekyll-commonmark (~> 1.4.0)
rouge (>= 2.0, < 4.0)
jekyll-default-layout (0.1.4)
jekyll (~> 3.0)
jekyll-feed (0.15.1)
jekyll (>= 3.7, < 5.0)
jekyll-gist (1.5.0)
octokit (~> 4.2)
jekyll-github-metadata (2.13.0)
jekyll (>= 3.4, < 5.0)
octokit (~> 4.0, != 4.4.0)
jekyll-include-cache (0.2.1)
jekyll (>= 3.7, < 5.0)
jekyll-mentions (1.6.0)
html-pipeline (~> 2.3)
jekyll (>= 3.7, < 5.0)
jekyll-optional-front-matter (0.3.2)
jekyll (>= 3.0, < 5.0)
jekyll-paginate (1.1.0)
jekyll-readme-index (0.3.0)
jekyll (>= 3.0, < 5.0)
jekyll-redirect-from (0.16.0)
jekyll (>= 3.3, < 5.0)
jekyll-relative-links (0.6.1)
jekyll (>= 3.3, < 5.0)
jekyll-remote-theme (0.4.3)
addressable (~> 2.0)
jekyll (>= 3.5, < 5.0)
jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
rubyzip (>= 1.3.0, < 3.0)
jekyll-sass-converter (1.5.2)
sass (~> 3.4)
jekyll-seo-tag (2.8.0)
jekyll (>= 3.8, < 5.0)
jekyll-sitemap (1.4.0)
jekyll (>= 3.7, < 5.0)
jekyll-swiss (1.0.0)
jekyll-theme-architect (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-cayman (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-dinky (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-hacker (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-leap-day (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-merlot (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-midnight (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-minimal (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-modernist (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-primer (0.6.0)
jekyll (> 3.5, < 5.0)
jekyll-github-metadata (~> 2.9)
jekyll-seo-tag (~> 2.0)
jekyll-theme-slate (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-tactile (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-time-machine (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-titles-from-headings (0.5.3)
jekyll (>= 3.3, < 5.0)
jekyll-watch (2.2.1)
listen (~> 3.0)
jemoji (0.12.0)
gemoji (~> 3.0)
html-pipeline (~> 2.2)
jekyll (>= 3.0, < 5.0)
kramdown (2.3.2)
rexml
kramdown-parser-gfm (1.1.0)
kramdown (~> 2.0)
liquid (4.0.3)
listen (3.7.1)
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.3.6)
minima (2.5.1)
jekyll (>= 3.5, < 5.0)
jekyll-feed (~> 0.9)
jekyll-seo-tag (~> 2.1)
minitest (5.16.2)
nokogiri (1.13.8-x86_64-linux)
racc (~> 1.4)
octokit (4.25.1)
faraday (>= 1, < 3)
sawyer (~> 0.9)
pathutil (0.16.2)
forwardable-extended (~> 2.6)
public_suffix (4.0.7)
racc (1.6.0)
rb-fsevent (0.11.1)
rb-inotify (0.10.1)
ffi (~> 1.0)
rexml (3.2.5)
rouge (3.26.0)
ruby2_keywords (0.0.5)
rubyzip (2.3.2)
safe_yaml (1.0.5)
sass (3.7.4)
sass-listen (~> 4.0.0)
sass-listen (4.0.0)
rb-fsevent (~> 0.9, >= 0.9.4)
rb-inotify (~> 0.9, >= 0.9.7)
sawyer (0.9.2)
addressable (>= 2.3.5)
faraday (>= 0.17.3, < 3)
simpleidn (0.2.1)
unf (~> 0.1.4)
terminal-table (1.8.0)
unicode-display_width (~> 1.1, >= 1.1.1)
thread_safe (0.3.6)
typhoeus (1.4.0)
ethon (>= 0.9.0)
tzinfo (1.2.10)
thread_safe (~> 0.1)
unf (0.1.4)
unf_ext
unf_ext (0.0.8.2)
unicode-display_width (1.8.0)
zeitwerk (2.6.0)
PLATFORMS
x86_64-linux
DEPENDENCIES
github-pages (~> 227)
BUNDLED WITH
2.3.19

20
docs/Makefile Normal file
View file

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

View file

@ -1,144 +0,0 @@
<img align="left" width="64" height="64" src="./media/icon.png">
# GodotXterm - Terminal Emulator
<br/>
[![Godot Version](https://img.shields.io/badge/Godot-4.2+-blue.svg)](#supported-godot-versions)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/lihop/godot-xterm/blob/stable/LICENSE.md)
[![Build and Test](https://github.com/lihop/godot-xterm/actions/workflows/main.yml/badge.svg?event=schedule)](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](#features) for more detail.
<video width="100%" controls>
<source src="https://user-images.githubusercontent.com/3696783/126894061-a69eb6ad-9979-4723-ade7-829494a9fc87.mp4" />
</video>
<div id="video-preview">
https://user-images.githubusercontent.com/3696783/126894061-a69eb6ad-9979-4723-ade7-829494a9fc87.mp4
</div>
[![Live Demo](./media/live_demo_button.png)](https://lihop.github.io/godot-xterm-dist/demo)
[![View it on GitHub](./media/view_it_on_github_button.png)](https://github.com/lihop/godot-xterm)
#### Table of Contents
1. [Features](#features)
2. [Screenshots](#screenshots)
3. [Demos and Examples](#demos-and-examples)
4. [Supported Godot Versions](#supported-godot-versions)
5. [Installation](#installation)
6. [Documentation](#documentation)
7. [License](#license)
## Features
- ### [Terminal](https://lihop.github.io/godot-xterm/api/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](https://lihop.github.io/godot-xterm/api/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
| | |
| -------------------------------------- | -------------------------------------- |
| ![](./media/screenshot_editor.png) | ![](./media/screenshot_the_guest.png) |
| ![](./media/screenshot_retro_term.jpg) | ![](./media/screenshot_xterminate.png) |
## Demos and Examples
The GodotXterm repository contains several example scenes in the [`/examples`](https://github.com/lihop/godot-xterm/tree/stable/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](https://lihop.github.io/godot-xterm/setup) 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 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 versions 3.5.x and 3.4.x are supported, but custom export templates
are required for HTML5 exports from versions < 3.5.
Versions 3.3.x 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](https://lihop.github.io/godot-xterm/setup).
## Documentation
Documentation is available on [GitHub Pages](https://lihop.github.io/godot-xterm).
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.
## License
Copyright (c) 2020-2022, Leroy Hopson and [contributors](https://github.com/lihop/godot-xterm/graphs/contributors) (MIT License).
See the [full license](https://github.com/lihop/godot-xterm/blob/stable/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](https://github.com/lihop/godot-xterm/blob/stable/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](https://github.com/lihop/godot-xterm/blob/stable/addons/godot_xterm/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](https://github.com/lihop/godot-xterm/blob/stable/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](https://github.com/lihop/godot-xterm/blob/stable/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](https://github.com/lihop/godot-xterm/blob/stable/themes/fonts/nerd_fonts/README.md).
- Noto Color Emoji. Released under the [SIL Open Font License](https://github.com/lihop/godot-xterm/blob/stable/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](https://github.com/lihop/godot-xterm/blob/stable/themes/fonts/unifont/LICENSE_OFL-1.1.txt).

View file

@ -1,12 +0,0 @@
# Site settings.
title: GodotXterm
email: godotxterm@leroy.geek.nz
description: Terminal emulator for the Godot game engine.
github_username: lihop
# Build settings.
remote_theme: just-the-docs/just-the-docs
# Just-the-docs settings.
color_scheme: dark
logo: /media/logo.png

View file

@ -1,3 +0,0 @@
#video-preview {
display: none;
}

BIN
docs/_static/images/button_live_demo.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.5 KiB

View file

@ -5,8 +5,8 @@
viewBox="0 0 446.16424 184.60277" viewBox="0 0 446.16424 184.60277"
version="1.1" version="1.1"
id="svg8" id="svg8"
inkscape:version="1.2.1 (9c6d41e410, 2022-07-14)" inkscape:version="1.3.2 (091e20ef0f, 2023-11-25)"
sodipodi:docname="flow_diagram.svg" sodipodi:docname="diagram_flow.svg"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg"
@ -103,10 +103,10 @@
</defs> </defs>
<sodipodi:namedview <sodipodi:namedview
inkscape:window-maximized="1" inkscape:window-maximized="1"
inkscape:window-y="0" inkscape:window-y="540"
inkscape:window-x="0" inkscape:window-x="0"
inkscape:window-height="900" inkscape:window-height="538"
inkscape:window-width="1600" inkscape:window-width="670"
fit-margin-bottom="15" fit-margin-bottom="15"
fit-margin-right="15" fit-margin-right="15"
fit-margin-left="15" fit-margin-left="15"
@ -115,8 +115,8 @@
inkscape:document-rotation="0" inkscape:document-rotation="0"
inkscape:current-layer="g4546" inkscape:current-layer="g4546"
inkscape:document-units="mm" inkscape:document-units="mm"
inkscape:cy="345.97832" inkscape:cy="374.80985"
inkscape:cx="666.91874" inkscape:cx="649.46807"
inkscape:zoom="0.65900083" inkscape:zoom="0.65900083"
inkscape:pageshadow="2" inkscape:pageshadow="2"
inkscape:pageopacity="0" inkscape:pageopacity="0"
@ -157,6 +157,14 @@
xml:space="preserve" /> xml:space="preserve" />
<g <g
id="g4546"> id="g4546">
<rect
style="fill:#343131;fill-opacity:1;stroke:#e6e1e8;stroke-width:0;paint-order:markers stroke fill"
id="rect1"
width="446.16425"
height="184.60277"
x="-124.95015"
y="10.113789"
ry="0" />
<g <g
transform="matrix(0.26458333,0,0,0.26458333,61.015349,21.905872)" transform="matrix(0.26458333,0,0,0.26458333,61.015349,21.905872)"
id="g5914" id="g5914"

Before

Width:  |  Height:  |  Size: 383 KiB

After

Width:  |  Height:  |  Size: 383 KiB

BIN
docs/_static/images/diagram_pty.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 91 KiB

View file

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

View file

Before

Width:  |  Height:  |  Size: 3 KiB

After

Width:  |  Height:  |  Size: 3 KiB

View file

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 14 KiB

View file

Before

Width:  |  Height:  |  Size: 6.3 KiB

After

Width:  |  Height:  |  Size: 6.3 KiB

View file

Before

Width:  |  Height:  |  Size: 260 KiB

After

Width:  |  Height:  |  Size: 260 KiB

View file

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

View file

Before

Width:  |  Height:  |  Size: 461 KiB

After

Width:  |  Height:  |  Size: 461 KiB

View file

Before

Width:  |  Height:  |  Size: 210 KiB

After

Width:  |  Height:  |  Size: 210 KiB

View file

@ -1,9 +0,0 @@
---
layout: default
title: API
nav_order: 3
has_children: true
permalink: /api
---
# API

7
docs/api/index.md Normal file
View file

@ -0,0 +1,7 @@
# API
```{toctree}
:maxdepth: 1
terminal
pty
```

View file

@ -1,64 +1,64 @@
---
layout: default
title: PTY
parent: API
nav_order: 1
permalink: /api/pty
---
# PTY # PTY
**Inherits:** [Node] < [Object] **Inherits:** {{Node}} < {{Object}}
_Linux and macOS only._ _Linux and macOS only._
Node for forking processes (e.g. bash, nodejs, python) with pseudoterminal file descriptors. 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. Can be used with the {{Terminal}} node to get an actual shell.
:::{note}
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). 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). See issue [\#25](https://github.com/lihop/godot-xterm/issues/25).
:::
## Overview ## Overview
![PTY Diagram](../media/pty_diagram.png) ![PTY Diagram](../_static/images/diagram_pty.png)
<sub>"PTY Diagram" is a derivative of [Termios-script-diagram.svg](https://commons.wikimedia.org/wiki/File:Termios-script-diagram.svg) by [Krishnavedala](https://en.wikipedia.org/wiki/User:Krishnavedala?rdfrom=commons:User:Krishnavedala), used under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/). <sub>"PTY Diagram" is a derivative of [Termios-script-diagram.svg](https://commons.wikimedia.org/wiki/File:Termios-script-diagram.svg) by [Krishnavedala](https://en.wikipedia.org/wiki/User:Krishnavedala?rdfrom=commons:User:Krishnavedala), used under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/).
## Properties ## Properties
| Type | Name | Default | | Type | Name | Default |
| ------------ | ------------------------------------ | ------------------------------------------------------ | | -------------- | ------------------------------------ | ------------------------------------------------------ |
| [NodePath] | [terminal_path](#prop-terminal_path) | None | | {{NodePath}} | [terminal_path](#prop-terminal_path) | None |
| [int] | [cols](#prop-cols) | `80` | | {{int}} | [cols](#prop-cols) | 80 |
| [int] | [rows](#prop-rows) | `24` | | {{int}} | [rows](#prop-rows) | 24 |
| [Dictionary] | [env](#prop-env) | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` | | {{Dictionary}} | [env](#prop-env) | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` |
| [bool] | [use_os_env](#prop-use_os_env) | `true` | | {{bool}} | [use_os_env](#prop-use_os_env) | true |
## Methods ## Methods
| Returns | Signature | | Returns | Signature |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [Error] | [fork](#mthd-fork) **(** [String] file=`$SHELL`, [PoolStringArray] args=[], [String] cwd=`$PWD`, [int] cols=80, [int] rows=24 **)** | | {{Error}} | [fork](#mthd-fork) **(** {{String}} file=$SHELL, {{PoolStringArray}} args=[ ], {{String}} cwd=$PWD, {{int}} cols=80, {{int}} rows=24 **)** |
| void | [kill](#mthd-kill) **(** [int] signum **)** | | void | [kill](#mthd-kill) **(** {{int}} signum=1 **)** |
| [Error] | [open](#mthd-open) **(** [int] cols=80, [int] rows=24 **)** | | {{Error}} | [open](#mthd-open) **(** {{int}} cols=80, {{int}} rows=24 **)** |
| void | [resize](#mthd-resize) **(** [int] cols, [int] rows **)** | | void | [resize](#mthd-resize) **(** {{int}} cols, {{int}} rows **)** |
| void | [resizev](#mthd-resizev) **(** [Vector2] size **)** | | void | [resizev](#mthd-resizev) **(** {{Vector2}} size **)** |
| void | [write](#mthd-write) **(** [String]\|[PoolByteArray] data **)** | | void | [write](#mthd-write) **(** {{String}}\|{{PoolByteArray}} data **)** |
## Signals ## Signals
- <a name="sgnl-data_received" /> **data_received** **(** [PoolByteArray] data **)** <hr id="sgnl-data_received" />
Emitted when data is read from the pseudoterminal master device. **data_received** **(** {{PoolByteArray}} data **)**
--- Emitted when data is read from the pseudoterminal master device.
- <a name="sgnl-exited" /> **exited** **(** [int] exit_code, [int] signum **)** <hr id="sgnl-exited" />
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.
<hr/>
## Enumerations ## Enumerations
### <a name="enum-signal" /> enum **Signal**: <hr id="enum-signal" />
enum **Signal**:
- **SIGHUP** = 1 --- Hangup. - **SIGHUP** = 1 --- Hangup.
- **SIGINT** = 2 --- Terminal interrupt signal. - **SIGINT** = 2 --- Terminal interrupt signal.
@ -73,121 +73,119 @@ See issue [\#25](https://github.com/lihop/godot-xterm/issues/25).
- **SIGALRM** = 14 --- Alarm clock. - **SIGALRM** = 14 --- Alarm clock.
- **SIGTERM** = 15 --- Termination signal. - **SIGTERM** = 15 --- Termination signal.
</hr>
## Property Descriptions ## Property Descriptions
### <a name="prop-terminal_path" /> [NodePath] **terminal_path** <hr id="prop-terminal_path" />
{{NodePath}} **terminal_path**
| | | | | |
| --------- | ------------------------ | | --------- | --------------------------------------------- |
| _Default_ | None | | _Default_ | None |
| _Setter_ | set_terminal_path(value) | | _Setter_ | void set_terminal_path ( {{NodePath}} value ) |
| _Getter_ | None | | _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. {{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.
--- <hr id="prop-cols" />
- <a name="prop-cols" /> [int] **cols** {{int}} **cols**
| | | | | |
| --------- | --------------- | | --------- | ------------------------------- |
| _Default_ | `80` | | _Default_ | 80 |
| _Setter_ | set_cols(value) | | _Setter_ | void set_cols ( {{int}} value ) |
| _Getter_ | None | | _Getter_ | None |
The column size in characters. The column size in characters.
--- <hr id="prop-rows" />
- <a name="prop-rows" /> [int] **rows** {{int}} **rows**
| | | | | |
| --------- | --------------- | | --------- | ------------------------------- |
| _Default_ | `24` | | _Default_ | 24 |
| _Setter_ | set_rows(value) | | _Setter_ | void set_rows ( {{int}} value ) |
| _Getter_ | None | | _Getter_ | None |
The row size in characters. The row size in characters.
--- <hr id="prop-env" />
- <a name="prop-env" /> [Dictionary] **env** {{Dictionary}} **env**
| | | | | |
| --------- | ------------------------------------------------------ | | --------- | ------------------------------------------------------ |
| _Default_ | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` | | _Default_ | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` |
| _Setter_ | None | | _Setter_ | None |
| _Getter_ | None | | _Getter_ | None |
Environment variables to be set for the child program. Environment variables to be set for the child program.
--- <hr id="prop-use_os_env" />
- <a name="prop-use_os_env" /> [bool] **use_os_env** {{bool}} **use_os_env**
| | | | | |
| --------- | ------ | | --------- | ---- |
| _Default_ | `true` | | _Default_ | true |
| _Setter_ | None | | _Setter_ | None |
| _Getter_ | 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. 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.
</hr>
## Method Descriptions ## Method Descriptions
- <a name="mthd-fork" /> [Error] **fork** **(** [String] file=`$SHELL`, [PoolStringArray] args=[], [String] cwd=`$PWD`, [int] cols=80, [int] rows=24 **)** <hr id="mthd-fork" />
Opens a pseudoterminal and starts a new process using the program specified by `file`. {{Error}} **fork** **(** {{String}} file=$SHELL, {{PoolStringArray}} args=[ ], {{String}} cwd=$PWD, {{int}} cols=80, {{int}} rows=24 **)**
`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.
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.
:::
- <a name="mthd-kill" /> void **kill** **(** [int] signum=1 **)** <hr id="mthd-kill" />
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.
:::
- <a name="mthd-open" /> [Error] **open** **(** [int] cols=80, [int] rows=24 **)** <hr id="mthd-open" />
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.
- <a name="mthd-resize" /> void **resize** **(** [int] cols, [int] rows **)** <hr id="mthd-resize" />
Resizes the dimensions of the pseudoterminal. void **resize** **(** {{int}} cols, {{int}} rows **)**
--- Resizes the dimensions of the pseudoterminal.
- <a name="mthd-resizev" /> void **resizev** **(** [Vector2] size **)** <hr id="mthd-resizev" />
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.
- <a name="mthd-write" /> void **write** **(** [String] \| [PoolByteArray] data **)** <hr id="mthd-write" />
Writes data to the pseudoterminal master device. void **write** **(** {{String}}\|{{PoolByteArray}} data **)**
[Dictionary]: https://docs.godotengine.org/en/stable/classes/class_dictionary.html Writes data to the pseudoterminal master device.
[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

View file

@ -1,14 +1,6 @@
---
layout: default
title: Terminal
parent: API
nav_order: 2
permalink: /api/terminal
---
# Terminal # Terminal
**Inherits:** [Control] < [CanvasItem] < [Node] < [Object] **Inherits:** {{Control}} < {{CanvasItem}} < {{Node}} < {{Object}}
A Terminal emulator Control node. A Terminal emulator Control node.
@ -17,7 +9,7 @@ For an exhaustive list of terminal control sequences (not all of which are suppo
## Overview ## Overview
![Terminal Flow Diagram](../media/flow_diagram.svg) ![Terminal Flow Diagram](../_static/images/diagram_flow.svg)
<sub>"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/).<sub/> <sub>"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/).<sub/>
### (1) User Input ### (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 | | Type | Name | Default |
| ------------ | ------------------------------------ | ------- | | ------------ | ------------------------------------ | ------- |
| [bool] | [bell_muted](#prop-bell_muted) | `false` | | {{bool}} | [bell_muted](#prop-bell_muted) | false |
| [float] | [bell_cooldown](#prop-bell_cooldown) | `0.1` | | {{float}} | [bell_cooldown](#prop-bell_cooldown) | 0.1 |
| [UpdateMode] | [update_mode](#prop-update_mode) | `AUTO` | | [UpdateMode] | [update_mode](#prop-update_mode) | AUTO |
## Methods ## Methods
| Returns | Signature | | Returns | Signature |
| -------- | ----------------------------------------------------------------- | | ---------- | ------------------------------------------------------------------- |
| void | [clear](#mthd-clear) **()** | | void | [clear](#mthd-clear) **( )** |
| [String] | [copy_all](#mthd-copy_all) **()** | | {{String}} | [copy_all](#mthd-copy_all) **( )** |
| [String] | [copy_selection](#mthd-copy_selection) **()** | | {{String}} | [copy_selection](#mthd-copy_selection) **( )** |
| [int] | [get_cols](#mthd-get_cols) **()** | | {{int}} | [get_cols](#mthd-get_cols) **( )** |
| [int] | [get_rows](#mthd-get_rows) **()** | | {{int}} | [get_rows](#mthd-get_rows) **( )** |
| void | [write](#mthd-write) **(** [String] \| [PoolByteArray] data **)** | | void | [write](#mthd-write) **(** {{String}}\|{{PoolByteArray}} data **)** |
## Signals ## Signals
- <a name="sgnl-bell" /> **bell** **()** <hr id="sgnl-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.
- <a name="sgnl-data_sent" /> **data_sent** **(** [PoolByteArray] data **)** <hr id="sgnl-data-sent" />
Emitted when some data comes out of the terminal. **data_sent** **(** {{PoolByteArray}} data **)**
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.
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.
:::
- <a name="sgnl-key_pressed" /> **key_pressed** **(** [String] data, [InputEventKey] event **)** <hr id="sgnl-key_pressed" />
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.
- <a name="sgnl-size_changed"> **size_changed** **(** [Vector2] new_size **)** <hr id="sgnl-size_changed" />
Emitted when the terminal's size changes, typically in response to its `rect_size` changing. **size_changed** **(** {{Vector2}} new_size **)**
`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. 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.
<hr/>
## Enumerations ## Enumerations
<a name="enum-update_mode" /> enum **UpdateMode**: <hr id="enum-update_mode" />
- **DISABLED** = **0** --- The terminal's `update()` method will never be called. No new cells will be drawn. enum **UpdateMode**:
- **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. - **DISABLED** = 0 --- The terminal's `update()` method will never be called. No new cells will be drawn.
- **ALL_NEXT_FRAME** = **3** --- Draws every cell afetr the next `update()` call, then returns to **AUTO**. - **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`.
<hr/>
## Property Descriptions ## Property Descriptions
- <a name="prop-bell_muted" /> [bool] **bell_muted** <hr id="prop-bell_muted" />
| | | {{bool}} **bell_muted**
| --------- | ------- |
| _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. | | |
| --------- | ----- |
| _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.
- <a name="prop-bell_cooldown" /> [float] **bell_cooldown** <hr id="prop-bell_cooldown" />
| | | {{float}} **bell_cooldown**
| --------- | ----- |
| _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. | | |
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. | _Default_ | 0.1 |
This property allows throttling of that signal. | _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.
- <a name="prop-update_mode" /> [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.
:::
| | | <hr id="prop-update_mode" />
| --------- | ---------------------- |
| _Default_ | `AUTO` |
| _Setter_ | set_update_mode(value) |
| _Getter_ | None |
Determines which cells of the terminal will be updated when its state changes. [UpdateMode] **update_mode**
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. | --------- | ------------------------------------------- |
| _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).
:::
<hr/>
## Method Descriptions ## Method Descriptions
- <a name="mthd-clear" /> void **clear** **()** <hr id="mthd-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.
- <a name="mthd-copy_all" /> [String] **copy_all** **()** <hr id="mthd-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.
- <a name="mthd-copy_selection" /> [String] **copy_selection** **()** <hr id="mthd-copy_selection" />
Copies only selected (i.e. highlighted) text in the terminal. {{String}} **copy_selection** **( )**
Will return an empty string if nothing is highligted.
--- Copies only selected (i.e. highlighted) text in the terminal.
Will return an empty string if nothing is highlighted.
- <a name="mthd-get_cols" /> [int] **get_cols** **()** <hr id="mthd-get_cols" />
Returns the width of the terminal in characters. {{int}} **get_cols** **( )**
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.
--- 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.
- <a name="mthd-get_rows" /> [int] **get_rows** **()** <hr id="mthd-get_rows" />
Returns the height of the terminal in characters. {{int}} **get_rows** **( )**
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.
--- 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.
- <a name="mthd-write" /> void **write** **(** [String] \| [PoolByteArray] data **)** <hr id="mthd-write" />
Writes data to the terminal emulator. Accepts either a [String] or [PoolByteArray]. void **write** **(** {{String}}\|{{PoolByteArray}} data **)**
Typically it would be connected to the output of a [PTY]'s [`data_received()`](/api/pty#sgnl-data_received) signal.
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 Example:
$Terminal.write("Hello World")
$Terminal.write("Hello World".to_utf8()) ```gdscript
$Terminal.write(PoolByteArray([0x1b, 0x9e]) $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 [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

65
docs/conf.py Normal file
View file

@ -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') + ')',
}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3 KiB

View file

@ -1,8 +1,30 @@
--- <img align="left" width="64" height="64" src="./_static/images/icon.png">
layout: default
title: Introduction
nav_order: 1
permalink: /
---
{% include_relative README.md %} # GodotXterm - Terminal Emulator
<br/>
[![Godot Version](https://img.shields.io/badge/Godot-3.4.x-blue.svg)](#supported-godot-versions)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/lihop/godot-xterm/blob/stable/LICENSE.md)
[![Build and Test](https://github.com/lihop/godot-xterm/actions/workflows/main.yml/badge.svg?event=schedule)](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.
<video width="100%" controls>
<source src="https://user-images.githubusercontent.com/3696783/126894061-a69eb6ad-9979-4723-ade7-829494a9fc87.mp4" />
</video>
[![Live Demo](./_static/images/button_live_demo.png)](https://lihop.github.io/godot-xterm-dist/demo)
[![View it on GitHub](./_static/images/button_view_it_on_github.png)](https://github.com/lihop/godot-xterm)
```{toctree}
:maxdepth: 2
:caption: Table of Contents
introduction
setup/index
api/index
CHANGELOG
```

112
docs/introduction.md Normal file
View file

@ -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
| | |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| <a href="./_static/images/screenshot_editor.png">![](./_static/images/screenshot_editor.png)</a> | <a href="./_static/images/screenshot_the_guest.png">![](./_static/images/screenshot_the_guest.png)</a> |
| <a href="./_static/images/screenshot_retro_term.jpg">![](./_static/images/screenshot_retro_term.jpg)</a> | <a href="./_static/images/screenshot_xterminate.png">![](./_static/images/screenshot_xterminate.png)</a> |
## 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/).

35
docs/make.bat Normal file
View file

@ -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

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.5 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 88 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.9 KiB

2
docs/requirements.txt Normal file
View file

@ -0,0 +1,2 @@
myst-parser==2.0.0
sphinx-rtd-theme==2.0.0

View file

@ -1,11 +1,3 @@
---
layout: default
title: Building From Source
parent: Setup
nav_order: 2
permalink: /setup/building-from-source
---
# Building From Source # Building From Source
Building GodotXterm from source consists of four steps: 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. 3. Compile godot-cpp using scons.
4. Compile libtsm and libgodotxterm 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 ## 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`: Run the build script in `addons/godot-xterm/native`:
``` ```sh
cd addons/godot_xterm/native cd addons/godot_xterm/native
./build.sh ./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™". Provided the dependencies above are installed then it should "just work™".
:::
Binaries for your platform will be installed in `addons/godot_xterm/native/bin`. 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 ## 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`. 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`.
[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

7
docs/setup/index.md Normal file
View file

@ -0,0 +1,7 @@
# Setup
```{toctree}
:maxdepth: 1
precompiled_binaries
building_from_source
```

View file

@ -1,50 +1,38 @@
---
layout: default
title: Precompiled Binaries
parent: Setup
nav_order: 1
permalink: /setup/precompiled-binaries
---
# Precompiled Binaries # Precompiled Binaries
{: .no_toc } Installing GodotXterm using precompiled binaries means that you won't be required
Installing GodotXterm using precompiled binaries means that you wont be required
to use a C/C++ compiler to build the project from source. It is simply a matter 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 of copying files to the correct location in your project. These files can be
installed from several sources: installed from several sources.
1. TOC :::{warning}
{:toc} Precompiled binaries will only work with certain versions of Godot
**Note:** precompiled binaries will only work with certain versions of Godot
(usually the current stable release). If you need binaries for a different or (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 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). refer to the section on [Building From Source](/setup/building-from-source).
:::
## Godot Asset Library ## Godot Asset Library
GodotXterm can be installed from the [Godot Asset Library](https://godotengine.org/asset-library/asset/1007). 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 ## Gd-plug Plugin Manager
If you are using the gd-plug plugin manager you can add the following line to your `plug.gd` file: 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. Replace the tag with that of the GodotXterm version you wish to install (see [tags](https://github.com/lihop/godot-xterm-dist/tags)).
See [tags](https://github.com/lihop/godot-xterm-dist/tags) for a list of versions and their corresponding commit hashes.
See the [gd-plug documentation](https://github.com/imjp94/gd-plug/blob/master/README.md) for more info on how to use it. 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 ## Manual Installation
Alternatively, GodotXterm can be installed manually in two steps: 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. 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). 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.32.dll`
- `libgodot-xterm.windows.64.dll` - `libgodot-xterm.windows.64.dll`
:::{note}
Debug builds are also available on the Releases page if required. 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. Download and unzip `libgodot-xterm-debug.zip` instead of `libgodot-xterm-release.zip` to the same location.
:::

View file

@ -1,9 +0,0 @@
---
layout: default
title: Setup
nav_order: 2
has_children: true
permalink: /setup
---
# Setup

View file

@ -13,7 +13,7 @@ config_version=5
config/name="GodotXterm" config/name="GodotXterm"
run/main_scene="res://examples/menu/menu.tscn" run/main_scene="res://examples/menu/menu.tscn"
config/features=PackedStringArray("4.2") config/features=PackedStringArray("4.2")
config/icon="res://docs/media/icon.png" config/icon="res://docs/_static/images/icon.png"
[display] [display]