Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of GodotXterm.

Checking the stable version of the documentation...

Terminal node

The Terminal node provides a visual terminal emulator that can display text, handle ANSI escape sequences, and process user input. You can use it standalone for displaying terminal output or connect it to a PTY for full terminal functionality.

Overview

Terminal Flow Diagram ”Terminal Flow Diagram” is a derivative of “computer keyboard 2” and “monitor”, from U.S. patent drawings, uploaded by johnny_automatic, used under CC0.

  1. User input

    The user enters some data into the terminal, typically by typing something on the keyboard.

  2. Terminal output

    The user input from (1) is processed by the terminal state machine and converted to the appropriate output. For example, if the user were to press the downward arrow key (↓), the terminal would then emit data_sent() with the value "\u001b[B".

  3. Terminal input

    In the other direction, data can be sent to the terminal. This corresponds to the write() method.

  4. Draw

    The input from (3) is then interpreted by the terminal state machine and drawn to the screen. For example, if the string "\u001b[38;2;0;255;0;mA" was written to the terminal, then it would draw a green colored capital letter ‘A’ on the screen.

Basic usage

Here are the essential methods for working with Terminal nodes:

extends Control

@onready var terminal = $Terminal

func _ready():
    # Write text to the terminal
    terminal.write("Hello, World!\n")

    # Write colored text using ANSI escape sequences
    terminal.write("\u001b[31mRed text\u001b[0m\n")
    terminal.write("\u001b[32mGreen text\u001b[0m\n")

    # Get terminal dimensions
    print("Terminal size: %d rows x %d columns" % [terminal.get_rows(), terminal.get_cols()])

    # Clear the terminal
    terminal.clear()

For an exhaustive list of terminal control sequences (not all of which are supported by GodotXterm) see “XTerm Control Sequences”.

Tip

Godot supports some control characters like \n (newline) and \r (carriage return), but not \e for escape. In this case, the unicode escape sequence \u001b can be used. See regular string literals for supported escape characters.

Signal handling

The Terminal emits several useful signals:

func _ready():
    # Connect to terminal signals
    terminal.data_sent.connect(_on_terminal_data_sent)
    terminal.bell.connect(_on_terminal_bell)
    terminal.size_changed.connect(_on_terminal_size_changed)

func _on_terminal_data_sent(data: PackedByteArray):
    # User typed something - data contains the key sequence
    print("User input: ", data.get_string_from_utf8())

func _on_terminal_bell():
    # Terminal bell was triggered
    print("Ding!")

func _on_terminal_size_changed(new_size: Vector2i):
    # Terminal was resized
    print("New size: %d cols x %d rows" % [new_size.x, new_size.y])

Next steps