Terminal

Inherits: Control < CanvasItem < Node < Object

A VT100/xterm-compatible terminal emulator.

Description

A terminal emulator Control node that provides VT100/xterm-compatible terminal emulation. It 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.

Can be used standalone for displaying terminal output, or connected to a PTY node to create a fully functional terminal emulator.

Tutorials

Properties

float

bell_cooldown

0.1

bool

bell_muted

false

float

blink_off_time

0.3

float

blink_on_time

0.6

bool

copy_on_selection

false

FocusMode

focus_mode

2 (overrides Control)

InverseMode

inverse_mode

0

int

max_scrollback

1000

Methods

void

clear()

String

copy_all()

String

copy_selection()

Vector2

get_cell_size() const

int

get_cols() const

Vector2i

get_cursor_pos() const

int

get_rows() const

void

select(from_line: int, from_column: int, to_line: int, to_column: int)

String

write(data: Variant)

Signals

bell() 🔗

Emitted when the bell character (\u0007) is written to the terminal. This signal can be used to trigger visual or audible notifications. Respects the bell_cooldown setting.

If bell_muted is true, this signal will not be emitted.

data_sent(data: PackedByteArray) 🔗

Emitted when the terminal generates output data, typically in response to user input. For example, pressing the down arrow key would emit this signal with data containing \u001b[lb[rb]B.

This data should typically be forwarded to a PTY for processing by the connected application.

key_pressed(data: PackedByteArray, event: Object) 🔗

Emitted when a key is pressed in the terminal. data contains the terminal sequence that would be sent via data_sent. event is the original InputEventKey captured by the terminal.

This signal allows you to intercept and potentially modify key handling behavior.

size_changed(new_size: Vector2i) 🔗

Emitted when the terminal’s size changes, typically in response to the Control’s size changing. new_size contains the new dimensions where x is the number of columns and y is the number of rows.

This information should be forwarded to a connected PTY so it can update its size accordingly.

Enumerations

enum InverseMode: 🔗

InverseMode INVERSE_MODE_INVERT = 0

Inverse video text (ANSI escape sequence \u001b[lb[rb]7m) is displayed by inverting the foreground and background colors. For example, red text on a green background will become cyan text on a magenta background.

InverseMode INVERSE_MODE_SWAP = 1

Inverse video text (ANSI escape sequence \u001b[lb[rb]7m) is displayed by swapping the foreground and background colors. For example, red text on a green background will become green text on a red background.

Property Descriptions

float bell_cooldown = 0.1 🔗

  • void set_bell_cooldown(value: float)

  • float get_bell_cooldown()

The minimum amount of time (in seconds) to wait before emitting another bell signal. This prevents performance issues when the bell character is written too frequently, such as with commands like while true; do echo -e "\a"; done.

bool bell_muted = false 🔗

  • void set_bell_muted(value: bool)

  • bool get_bell_muted()

If true, the bell signal will not be emitted when the bell character (\u0007) is written to the terminal. This can be useful to disable audible or visual bell notifications.

  • void set_blink_off_time(value: float)

  • float get_blink_off_time()

The duration (in seconds) that blinking text remains invisible during a blink cycle. This affects text displayed with the blink attribute (ANSI escape sequence \u001b[lb[rb]5m).

  • void set_blink_on_time(value: float)

  • float get_blink_on_time()

The duration (in seconds) that blinking text remains visible during a blink cycle. This affects text displayed with the blink attribute (ANSI escape sequence \u001b[lb[rb]5m).

bool copy_on_selection = false 🔗

  • void set_copy_on_selection(value: bool)

  • bool get_copy_on_selection()

If true, text will be automatically copied to the clipboard when selected (highlighted) in the terminal. This provides a convenient way to copy text without explicitly calling copy_selection().

InverseMode inverse_mode = 0 🔗

Determines which technique to use to display reverse video (ANSI escape sequence \u001b[lb[rb]7m). See InverseMode for available options.

int max_scrollback = 1000 🔗

  • void set_max_scrollback(value: int)

  • int get_max_scrollback()

The maximum number of lines to keep in the scrollback buffer. When this limit is exceeded, the oldest lines are discarded. Set to 0 to disable scrollback entirely. Larger values use more memory but allow scrolling back through more terminal history.

Method Descriptions

void clear() 🔗

Clears the terminal screen, removing all text except the bottom row. This also clears the scrollback buffer. The cursor is moved to the top-left corner. Equivalent to sending the ANSI escape sequence \u001b[lb[rb]2J\u001b[lb[rb]H.

String copy_all() 🔗

Copies all of the text in the terminal, including the scrollback buffer. Returns the complete terminal content as a string with newlines separating rows.

var terminal_content = terminal.copy_all()
print("Terminal contains: ", terminal_content)

String copy_selection() 🔗

Copies only the currently selected (i.e. highlighted) text in the terminal. Returns an empty string if no text is currently selected.

Text can be selected by dragging the mouse or using the select() method.

# Select some text first
terminal.select(0, 0, 0, 10)
var selected_text = terminal.copy_selection()

Vector2 get_cell_size() const 🔗

Returns the size of a single character cell in pixels. This is determined by the current font size and represents the width and height of one character.

Useful for calculating precise positioning and sizing when working with terminal coordinates.

int get_cols() const 🔗

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 size.

Vector2i get_cursor_pos() const 🔗

Returns the current cursor position as a Vector2i where x is the column and y is the row. Both values are zero-based, so the top-left corner is Vector2i(0, 0).

int get_rows() const 🔗

Returns the height of the terminal in characters (rows). This represents the number of character rows that can fit vertically in the terminal at the current font size. Automatically updates when the terminal is resized.

void select(from_line: int, from_column: int, to_line: int, to_column: int) 🔗

Selects text from one position to another in the terminal. from_line and from_column specify the starting position of the selection. to_line and to_column specify the ending position of the selection. All coordinates are zero-based.

The selected text will typically be highlighted, and can be copied using copy_selection().

String write(data: Variant) 🔗

Writes data to the terminal emulator for display. Accepts either a String or PackedByteArray.

The data is processed through the terminal state machine, which interprets ANSI escape sequences for colors, cursor movement, and other terminal control functions.

Returns any response data that should be sent back (typically for interactive applications).

# Write simple text
terminal.write("Hello World\n")
# Write colored text using ANSI escape sequences
terminal.write("\e[31mRed text\e[0m\n")
# Write raw bytes
terminal.write(PackedByteArray([0x1b, 0x5b, 0x32, 0x4a]))  # Clear screen