DOCSEARCHbyAlgolia
Submit Docs

GodotXterm

repository·main·Indexed 41 days ago

https://github.com/lihop/godot-xterm

A GDExtension that integrates a full VT100/xterm-compatible terminal emulator into the Godot engine. It provides a Terminal node for rendering ANSI/XTerm escape sequences and a PTY node for managing pseudo-terminal processes. Supports Godot 4.3+ (main branch) and Godot 3.x (godot-3.x branch) across Linux, macOS, Windows, and partial HTML5 support. Features include X11 color scheme imports, Nerd Fonts integration, and bidirectional communication with system shells.

Tokens
7.9K
Snippets
22
Records
50
Agent score
52%

What's inside GodotXterm

  1. Overview of GodotXterm

    main

    GodotXterm is a GDExtension-based terminal emulator designed for Godot. It provides terminal capabilities within the Godot engine by leveraging libtsm, libuv, and node-pty.

    Platform Support:

    • Linux: Primary development and testing target.
    • macOS & Windows: Supported.
    • HTML5: Partial support available.

    Compatibility:

    • Godot 4.3+: Use the main branch.
    • Godot 3.x: Use the godot-3.x branch.

  2. Use the Terminal node for basic terminal emulation

    main

    The Terminal node provides a visual terminal emulator in Godot. It can be used standalone to display text and handle ANSI escape sequences, or connected to a PTY for full terminal functionality.

    Core Workflow

    1. User Input: The user types data into the terminal.
    2. Terminal Output: The terminal processes input (e.g., arrow keys) and emits data_sent() with the corresponding escape sequence (e.g., "\u001b[B" for the down arrow).
    3. Terminal Input: You can send data to the terminal using the write() method.
    4. Draw: The terminal interprets the written data (including ANSI sequences) and renders it to the screen.
    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()

  3. Customize the Integrated Terminal theme

    main

    The integrated terminal's appearance is tied to your Godot Editor settings:

    • Fonts: It inherits the editor's code font and font size settings.
    • Colors: It automatically maps syntax highlighting colors from your editor theme to terminal colors. You can change the terminal's color scheme by navigating to Editor > Editor Settings > Text Editor > Theme.

  4. Understand Nerd Fonts integration in GodotXterm

    main

    Nerd Fonts are used to provide enhanced iconography within the terminal emulator by combining icons from multiple sources into a single font file. This allows the terminal to render a wide variety of symbols (such as Font Awesome, Material Design Icons, and Devicons) alongside standard text.

    When using Nerd Fonts in godot-xterm, ensure your system or Godot project has a Nerd Font installed that supports the specific glyphs you intend to display.

  5. How the PTY node works

    main

    A PTY (pseudoterminal) node spawns and controls shell processes (like bash, cmd, or any CLI program) with real-time streaming capabilities. Unlike OS.execute(), which only provides the final output, a PTY allows you to send input while the process is running and receive output as it is generated.

    Lifecycle and Data Flow

    1. Forking: Calling fork() creates a new shell process and a pseudoterminal pair (a master side connected to the PTY and a slave side connected to the shell).
    2. Writing Input: Using write() sends data from the PTY through the pseudoterminal master/slave to the shell. The shell treats this as if it were typed on a keyboard.
    3. Reading Output: The shell writes output to the slave side, which flows back to the PTY master. The PTY then emits the data_received signal.
    4. Communication: This cycle repeats for the process lifetime. You can send commands or special signals like ETX (Ctrl + C) to interrupt programs.

  6. Use the PTY node to control system processes

    main

    The PTY node spawns and controls real system processes using pseudoterminal file descriptors. This enables bidirectional communication with shells, interpreters, and command-line programs.

    To create a fully functional shell interface within a Godot application, connect a PTY node to a Terminal node.

  7. Configure the shell for the Integrated Terminal

    main

    The integrated terminal automatically selects a shell based on your operating system and environment configuration:

    • Environment Variable: The terminal first checks for the SHELL environment variable.
    • Fallback: If SHELL is not found, it defaults to a standard shell like Bash, PowerShell, or Zsh.

    Tip for Windows users: To use a Bash shell on Windows, launch the Godot editor via Git Bash. This sets the SHELL environment variable, which the terminal will then detect and use.

  8. Use the Terminal node for terminal emulation

    main

    The Terminal node is a VT100/xterm-compatible terminal emulator Control node. It supports ANSI and XTerm escape sequences for screen manipulation, cursor movement, text styling, and terminal effects.

    You can use it in two ways:

    1. Standalone: Use it purely for displaying terminal output.
    2. Full Terminal: Connect it to a PTY node to create a fully functional, interactive terminal emulator.

  10. Import X resources as Godot Themes

    main

    The X resources import plugin automatically converts X11 configuration files (.xrdb, .Xresources, or .xresources) into Godot Theme resources. This allows you to use standard terminal color schemes and font settings directly in GodotXterm.

    To apply an X resource theme:

    1. Add an X resource file (.xrdb, .Xresources, or .xresources) to your project.
    2. Select your Terminal node in the Godot editor.
    3. In the Inspector, locate the Theme property.
    4. Assign the imported X resource theme to the Theme property.

  12. Set up GodotXterm example scenes

    main

    To run the example scenes located in the /examples directory, you must ensure the GDExtension binaries are available in your project. You have two options:

    1. Build from source: Build the GDExtension binaries manually.
    2. Use pre-compiled binaries: Copy pre-compiled binaries into the project folder.