world.json

world.json identifies the world and provides its top-level presentation and initial settings.

{
  "id": "9d56bc2e-83ac-4eb0-b7bf-fac48772a6ef",
  "name": "Blackwater Observatory",
  "description": "A coastal town watches a silent observatory above the cliffs.",
  "author": {"name": "Example Author", "url": "https://example.com"},
  "metadata": {"tags": ["mystery", "historical"]},
  "opening_message": [
    {"type": "narration", "text": "Rain moves in from the sea."},
    {"type": "utterance", "character": "mara", "text": "We should go before dark."}
  ],
  "alternate_openings": [{"title": "Arriving late", "text": "You reach the observatory after dark."}],
  "narration_voice": "narrator",
  "variables": {"storm_warning": false}
}

Field	Requirement	Meaning
`id`	Stable; generated if absent	World identity across folder moves
`name`	Required	Display name
`description`	Optional	Player-facing summary
`author.name`	Required when `author` exists	Attribution
`author.url`	Optional	Attribution link
`metadata.tags`	Optional list	Catalogue filtering and presentation
`opening_message`	Optional	Text or ordered narration/utterance parts
`alternate_openings`	Optional list	Other first messages the player may choose when starting a session: `{title, text, character?}`, plain narration, at most 30 of at most 20,000 characters; a missing title is the first words of the text
`narration_voice`	Optional	Initial TTS voice for narration
`preset`	Optional	Name of a preset in the person's library that sessions of this world start with unless one is chosen; see the prompt system specification
`lorebooks`	Optional list	Names of lorebooks in the person's library that sessions of this world start with unless the start dialog chooses others; see lorebooks
`variables`	Optional object	Initial values for world-scoped variables
`tools`	Optional object	Optional tools switched on or off for the world's agents, by kind of agent: `{"gameMaster": {"roll_dice": false}}`. A story starts from it, and a choice made at the start is added on top. Names this version does not know are kept and have no effect

The start dialog offers the alternate openings beside the world's own. An opening with a character (the id of a playable character) is offered only to a player who takes that character, and a start that names it for anyone else is refused; a character that is not a playable character of the world refuses the start with the problem. A session started from one stores it as its first finished turn like any other opening.

An utterance's character must name a defined character. Invalid opening parts prevent session creation. The opening is stored as the first finished chat turn without a model call.

Older export manifests and separate author.json files are not part of this native format.