Skip to content

Terminal host and worlds

The host keeps sessions alive while worlds control presentation. For app controls, see Tabs and panes.

Run from source

mise run dev
mise run dev -- --bg='#101822' --opacity=0.75
mise run dev -- --plugin=worlds/bistro
Option Use
--no-plugin Start Flat
--plugin=PATH Load a source world or pack
--config=PATH Select client configuration
--bg, --opacity Override backdrop color and opacity
--motion-render-scale=1 Keep full scenery resolution during motion

Host contracts

World lifetime

World switches preserve terminal nodes, PTYs, browsers, and scrollback. Configure SwitchWorld menu entries explicitly in client.toml.

Failed runtime switches leave the current world active. Failed initial loads fall back to Flat. Plugins run unrestricted Godot code.

Component Responsibility
TerminalHost.gd Validate manifests, mount packs, create worlds
TerminalWorld.gd Terminal presentation, framing, IME, effects
TerminalSurface3D.gd Placeable screen and viewpoint
WorldSettings.gd World settings and effects
TerminalWorldProbes.gd Optional diagnostics

See plugin design and world authoring.

Pack and load a world

Follow Publishing a world. Test with the packaged host; source launches still scan the checkout.

Manifests use api: 1 and an entry under res://worlds/. Prefer a PackedScene whose root exposes host. Packs mount without replacing resources. World changes need no native compilation.

Tab lifecycle

Tabs have independent terminal state. Moving tabs between windows in the same app preserves their shells.

Closing checks for running jobs on macOS/Linux. Running, stopped, or unknown process state requires confirmation; cancelling leaves the PTY alive. See Sessions and multiple windows.

Background rendering and focus

Static workspaces stop drawing. Output, input, cursor blinking, browser frames, and animation wake the compositor.

State Rendering
Rest Native-resolution terminal overlay
Camera flight Combined depth-tested terminal/scenery pass
Sustained motion Scenery uses motion_render_scale
Camera still Restore render_scale, draw once, sleep
Focus lost Finish active flight; pause scenery, camera effects, weather

Terminal output and UI continue under the background frame cap. Unfocused resizes refresh scenery once. --no-focus-skip bypasses its focus pause.

Avoid writing unchanged camera or shader values every tick; those writes can wake Godot rendering. See render costs and idle rendering.

Terminal backdrop and effects

Flat uses a full-window backdrop; authored worlds may use bounded sheets. Cell backgrounds, selections, images, and glyphs keep their own coverage.

The effects component handles particles, trails, ripple, and splash. User settings live under appearance.

Verification

godot --headless --path frontends/godot/project --script tests/run.gd

Interaction scenarios and evidence requirements live in tests/llm-e2e/README.md.