Skip to content

Author a world

Start with the shared 3D kit. It supplies terminals, input, tabs, tiling, effects, and camera movement; you add the scenery and viewpoints.

Build the scene

  1. Inherit res://scenes/TerminalWorld3D.tscn and save it under res://worlds/your-world/.
  2. Add scenery and lights as ordinary Godot nodes.
  3. Move or duplicate TerminalSpace3D.tscn instances to create terminal destinations.
  4. Adjust each destination's ViewPose camera and visit_order.
  5. Point plugin.json at your scene and launch it:
mise run dev -- --plugin=worlds/your-world

Use tests/fixtures/StarterWorld.tscn for a two-destination example. Live shells and layouts survive world switches.

The shape of a world scene

MyWorld                 TerminalWorld3D
├── Scenery             Node3D
└── Spaces              Node3D
    ├── Destination0    TerminalSpace3D
    │   └── ViewPose    Camera3D
    └── Destination1    TerminalSpace3D
        └── ViewPose    Camera3D

Prefer a scene entry in the manifest:

{"api": 1, "id": "my-world", "entry": "res://worlds/your-world/world.tscn"}

For Bistro, edit worlds/bistro/world.tscn; its packaged entry points at the baked scene in worlds/bistro/generated/preview/.

Where a terminal goes

A TerminalSurface3D is a place for a tab. Move and rotate it like other geometry.

Property Purpose
canvas Screen size and aspect ratio in world units
visit_order Destination order; ties follow scene-tree order
surface_id Stable name; defaults to the node name
surface_lift Offset from backing geometry to avoid z-fighting; default 0.06

Tabs occupy destinations in order. Extra tabs share destinations after all places are used. Each surface needs a Camera3D child such as ViewPose. Its fov is horizontal under KEEP_WIDTH; use the editor's Preview to check framing.

The terminal mesh stays a flat quad. The sheet shader handles curvature and ripple.

Test and package

Launch from source, check framing at several window sizes, then follow Publishing a world. Packs contain authored assets; the shared kit ships with the host.

For supported renderer exports:

python3 tools/import_godot_world.py \
  --source worlds/bistro/world.tscn \
  --output worlds/bistro/shared

Add --check to detect stale exports. The importer exports supported placements, poses, and lights; it does not execute scripts or convert custom shaders.

See scripted scene serialization.

Optional customization

Finish and test the basic scene before changing these hooks.

Camera movement and optional replacements

Straight flights between ViewPose cameras work automatically. For a route around scenery, add a Path3D and assign it as the destination's Approach Path. Leave obstacle clearance; routes do not perform collision avoidance.

Setting Replace it to customize…
Terminal Space Scene Tabs, buttons, status strip, and workspace UI
Effects Preset The world's effect defaults
Weather Scene Weather extending Weather.gd
WorldEnvironment Lighting and environment; otherwise the kit provides defaults
_navigation_route() Procedural camera routes

Use CameraMotion rather than a second camera controller. For a custom renderer, see World UI API and plugin design.

World-owned settings

Read your [worlds.<id>] table from client.toml:

const WorldConfig := preload("res://graffitty/world_config.gd")

func _ready() -> void:
    var mine: Dictionary = WorldConfig.table("my-world")

The world owns its schema and defaults. Override read_settings(user) to use WorldConfig.load_settings(settings_script, user, ["my-world"]) for typed validation. Unknown keys, invalid types, and failed validation skip that table with a warning.

Tables apply in order; later tables override only their supplied keys. New windows load changes without changing existing windows.

Bundled world Tables, in order
Bistro [worlds.scene-worlds], [worlds.bistro]
Silksong [worlds.scene-worlds], [worlds.world]

Both use SceneWorldSettings.gd. Keep scenery and lighting in authored nodes; use code for navigation data, camera interpolation, and computed settings.