world_defaults.module

Grafts .world_settings-backed default slots onto the world global.

Slot fields

Per-mode (read picks the half matching wld.mode()):

Slot	TOML key	Asset type	Required tag
world.avatar_default_edit	[world] avatar_default_edit	bundle	playerAvatar
world.avatar_default_play	[world] avatar_default_play	bundle	playerAvatar
world.camera_default_edit	[world] camera_default_edit	component	cameraBehavior
world.camera_default_play	[world] camera_default_play	component	cameraBehavior

Mode-agnostic:

Slot	TOML key	Asset type	Required tag
world.startup_scene	[world] startup_scene	scene	—
world.loading_screen	[world] loading_screen	loadingScreen	none

world.loading_screen names the screen every boot of the world shows while it loads (types/loadingScreen); unset, the world shows the engine's own loading screen.

Orientation

world.orientation ([world] orientation) is the screen orientation the world plays in: "landscape", "portrait" or "any" (the default, and what an unset value reads as). It is written in edit mode like the slots above, and any other value is refused by name. While the engine is in play mode the display is locked to it with ui.lockOrientation: as the world becomes ready (before its startup scene loads) and on every entry to play. Edit mode and an unloading world release the lock, so the editor follows the device. ui.orientation() reports the lock and whether the platform holds it.

Semantics

• Read — returns an AssetRef envelope, or nil if the slot is unset (empty TOML value).
• Write — accepts an AssetRef envelope or a bare identity string. Tag enforcement at the setter: writing a bundle that lacks the slot's required tag raises a typed error naming the missing tag.
• Clear — assigning nil (or empty string) persists an empty TOML value (key stays in the file, marked as "explicitly unset").
• Play-mode gate — .world_settings is locked in play mode. Writes from a play-mode VM raise a typed error at the API boundary; switch to edit mode with the wld.edit tool first.

Why per-mode?

Edit mode is state-frozen (no update(dt), no physics step). A controller bundle whose only logic lives in update is inert in edit mode — useful in play, useless in edit. The per-mode keys let a world keep a static authoring-friendly setup (e.g. camera_default_edit = "@builtin::controller.menu") and a fully-driven gameplay setup (camera_default_play = "@builtin::controller.orbital_follow") in parallel.

Workflow → see man getting-started § 5 and § 6. Options catalog → man options.