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¶
- Inherit
res://scenes/TerminalWorld3D.tscnand save it underres://worlds/your-world/. - Add scenery and lights as ordinary Godot nodes.
- Move or duplicate
TerminalSpace3D.tscninstances to create terminal destinations. - Adjust each destination's ViewPose camera and
visit_order. - Point
plugin.jsonat your scene and launch it:
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:
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.