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, pack it, and launch the pack:
Graffitty loads worlds only from packs. Edit the scene in the Godot editor; rebuild the pack to run your changes.
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:
A world can live in its own repository. Its scenes still use res://worlds/<id>/
paths and the shared kit, so its Godot steps run in a Graffitty checkout's
project. While those steps run, the world's pipeline links the repository at
frontends/godot/project/worlds/<id> (ignored by Git) and removes the link
afterwards. Bistro works this way:
python3 pipeline.py pack --graffitty <checkout> # dist/bistro.pck, bistro.json
python3 pipeline.py run --graffitty <checkout> -- --editor # the editor, with Bistro linked
Edit its entry, world.tscn; it loads the baked scenery from
generated/preview/. Graffitty's own tests load Bistro by id, from the
installed pack.
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 your pack, check framing at several window sizes, then follow Publishing a world. Packs contain authored assets; the shared kit ships with the host.
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 |
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.
| World | Tables, in order |
|---|---|
| Bistro | [worlds.bistro] |
Bistro uses the shared WorldSettings.gd. Keep scenery and lighting in authored nodes;
use code for navigation data, camera interpolation, and computed settings.