World plugin design¶
Use the shared world kit to present terminals in a custom scene. Start with Authoring a world for a working setup.
Who owns what¶
| Layer | Responsibility |
|---|---|
| Host | PTYs, sessions, input, IME, configuration, windows, plugin loading |
| Shared kit | Terminal surfaces, framing, camera movement, effects, and UI bindings |
| World plugin | Scenery, lighting, viewpoints, and custom presentation |
Worlds can switch without restarting shells. Built-in worlds use the same interface as downloaded plugins.
Extend the kit¶
Use a scene rooted in TerminalWorld3D.gd with TerminalSpace3D destinations.
Override only the behavior your world needs:
extends "res://scenes/TerminalWorld3D.gd"
const WorldConfig := preload("res://graffitty/world_config.gd")
func read_settings(user: TerminalConfig) -> RefCounted:
return WorldConfig.load_settings(settings_script, user, ["my-world"])
func configure_terminal(user: TerminalConfig) -> TerminalConfig:
return super.configure_terminal(user)
func configure_effects(effects: RefCounted) -> void:
super.configure_effects(effects)
Override _navigation_route() for custom routes. Use the shared
CameraMotion component for flights and framing.
Preserve terminal behavior¶
If you replace the renderer or UI, your implementation must still handle these:
| Requirement | Shared implementation |
|---|---|
| Window-relative grid size and aspect | _terminal_content_rect(), _canvas_span_in_frame() |
| Native-resolution text and font scaling | _sync_terminal_viewport_size(), _apply_terminal_font_scale() |
| Premultiplied texture alpha | terminal_sheet_common.gdshaderinc |
| Horizontal camera framing | Camera3D.KEEP_WIDTH |
| Cursor-projected IME candidate position | _update_ime_anchor() |
| PTY resize after a window change | _on_window_size_changed() |
Use screen-space background rendering from world_background.gdshaderinc.
Keep terminal image geometry aligned with the grid; enable image storage and
register a PNG decoder when replacing the native terminal setup.
Terminal API¶
Signals¶
| Signal | Event |
|---|---|
keystroke(cell, unicode) |
Key delivered to the terminal |
cursor_moved(cell) |
Cursor position changed |
output(bytes), grid_resized(cols, rows) |
Output or grid change |
bell(), exited(code), title_changed(title) |
Bell, shell exit, or title |
ui_state_changed(), frame_changed() |
Semantic state / rendered pixels changed |
Commands¶
| Call | Use |
|---|---|
respawn() |
Restart the shell in place |
send_text(text) |
Write raw terminal input |
paste_text(text) |
Paste with control stripping and bracketed-paste handling |
Each tab has its own terminal, viewport, shell, and scrollback. For transitions, capture the outgoing terminal before switching and the incoming terminal after. A newly opened tab may not have drawn its first output yet.
Trust and recovery¶
Plugin execution¶
Godot world plugins run as unrestricted code in the app process. Only install plugins you trust. The kit provides reusable behavior, not a sandbox.
Loading and failure¶
The host owns shell-exit policy and plugin loading. --no-plugin starts Flat;
failed initial loads fall back to Flat. A running plugin has no watchdog or
emergency unload shortcut.
The plugin manifest uses api: 1; unsupported versions are rejected. Package a
world as a PCK plus its manifest. GDScript needs no separate compiler; native
extensions need platform-specific binaries and signing.
See Publishing a world and terminal preferences.