Skip to content

World controls API

Choose one presentation level. Start with World UI API.

Need Use
Complete workspace TerminalSpace scene
Some standard controls Bound controls or tab strip
Fully custom visuals Session models and custom drawing

Optional complete terminal space

Set the world's Terminal Space Scene to res://scenes/TerminalSpace.tscn, or assign it in code:

extends "res://scenes/SpatialTerminalWorld.gd"

func _init() -> void:
    terminal_space_scene = preload("res://scenes/TerminalSpace.tscn")

The host mounts it in window space before world entry and binds persistent sessions. It supplies tabs, headers, browser controls, monitor, tiling, stashes, Overview/Main controls, drag previews, camera pan/pinch, and pointer projection. Basic Terminal/TerminalSurface3D kits do not opt in automatically. _build_ui() may omit chrome; an empty terminal_space_scene keeps a basic presentation.

Customize supplied controls

Inherit TerminalSpace and choose that scene on the root. Theme inheritance skins it; exported paths bind authored controls without extra signal glue.

Property Supplied node
pane_header_scene Inherited PaneHeader.tscn adapter; supplies title metrics/theme to the bundled pane-header mod while retaining pane input and session behavior
tab_strip_path An instance of TerminalTabBar.tscn (or compatible bind_host/tabs adapter)
tile_button_path Button to toggle tiling
split_right_button_path Optional extra control to split the focused pane right; default controls live on each pane
split_down_button_path Optional extra control to split the focused pane down; default controls live on each pane
overview_button_path Button to show the surrounding stash space
main_button_path Button to return to the main area

Empty paths use defaults. show_tab_strip and show_workspace_controls hide chrome independently. Custom controls retain parent/layout. The underlying factory host.ui.create_terminal_space(scene) returns an unparented instance.

Pane chrome ownership

pane-header/main.js paints headers; PaneHeader.tscn owns geometry/input and retains a hidden Title label for font metrics. Theme overrides may change title size/color. WorkspacePane owns commands/drag; WorkspaceView owns projection. Title changes refresh props without resizing terminal viewports.

The bundled pane-strip mod is drawn per pane in the canvas, with camera/effect projection. Users can replace it with a mod; world scenes cannot replace it. Browser frame updates are independent of geometry.

Switching away removes presentation but preserves split trees, stashes, and PTYs. Returning restores them. tests/terminal_space_smoke.gd checks both modes.

Antialiasing

The project uses 4× MSAA for scenery. A world may override its viewport policy or _configure_scenery_antialiasing(). Ink disables MSAA and screen AA to preserve native glyph sampling. Custom renderers choose their own passes.

Optional ordinary Godot controls

Standard tab strip asset

TerminalTabBar.tscn wraps the shared TabStrip: trailing plus, close buttons, middle-click close, drag preview, shrink-before-scroll, and overflow scrolling. ChromiumTabStrip uses the same core with different metadata/session commands.

var strip = host.ui.create_tab_strip()
strip.theme = my_theme # optional; inherited Themes also work
$HUD.add_child(strip)

For authored scenes, call strip.bind_host(host) or set host_path. Style the TerminalTab Theme states and reserve right padding for close. minimum_tab_width / maximum_tab_width control sizing; strip.tabs.plus is the plus button.

Host operation Effect
create_session() New tab
request_close_session(id) Confirm and close; omitted ID means active tab
move_session(id,index) Reorder workspace/keyboard navigation without restarting PTYs

IDs remain stable independently of order. For a custom adapter, TabStrip.reconcile(items,selected_id) takes id/title and optional tooltip/icon. Handle selected/closed/moved/new_tab signals, then reconcile authoritative order. The strip core itself owns no sessions.

Individually bound controls

host.ui.bind($MyTabs, "tabs")             # TabBar
host.ui.bind($MyProgress, "progress")     # ProgressBar, follows active session
host.ui.bind($MyScroll, "scroll")         # HScrollBar or VScrollBar
host.ui.bind($MyTitle, "title")           # Label
host.ui.bind($OtherProgress, "progress", 2) # pinned to session 2

Factories create_tab_bar(), create_progress_bar(id=-1), create_scroll_bar(id=-1), and create_title_label(id=-1) return unparented controls. Binding starts on tree entry; bind once. Freeing the control disconnects it.

Bindings own data properties: entries/selection, title, progress state/value, and scroll range/page/value/visibility. Tabs and scrollbars avoid keyboard focus. The world owns theme, layout, and animation. Use models for different behavior.

Custom 3D logic, with no standard chrome

Override _build_ui() on a TerminalWorld; tabs and status may remain null.

var host: Node

func _ready() -> void:
    host.ui_changed.connect(_refresh)
    _refresh()

func _refresh() -> void:
    var session = host.active_session()
    if session == null:
        return
    $Label3D.text = session.title
    $Gauge.visible = session.progress_state != 0
    if session.progress_value >= 0:
        $Gauge.scale.x = maxf(session.progress_value / 100.0, 0.001)
    # Drive your own materials/animations for ERROR, PAUSED or INDETERMINATE.

func clicked_world_terminal(id: int) -> void:
    host.select_session(id)
API Identity
get_tabs(), select_workspace(id) Workspace IDs; a workspace may contain multiple terminals
get_terminal_tabs(), select_session(id) Terminal destinations

get_tabs() returns id/label/title/active/opened/progress_state/progress_value/ exited/chromium_count. ui_changed covers state and catalog/selection changes; session_added and active_session_changed are narrower signals.

Register destinations with set_tabs([{id: 0, label: "Desk"}, …]) and handle session_requested(id). Selection requests navigation; it does not move cameras. Fully custom renderers also own placement and the session_for(id,presenter) / activate_session(pair) lifecycle. The shared kit already handles these steps.