Format overview

A world is exactly one directory below <root>/worlds/ and must contain world.json.

worlds/<folder>/
  world.json
  characters/<folder>/character.json
  locations/<folder>/location.json
  items/<folder>/item.json
  factions/<folder>/faction.json
  lore/*.json
  plots.json
  variables.json
  triggers.json
  prompts/<language>/<group>/<name>.md
  images/

Only implemented files are read; unknown fields are ignored unless a document's validation says otherwise. JSON field names use snake_case. Canonical TypeScript models and the session database use their own representations.

Identity

world.json has a stable id. If it is absent, the catalogue generates a UUID and writes it into the file. Duplicate world IDs are rejected rather than silently rewritten.

Entity id values are unique within their type and default to the entity folder name where supported. References use IDs, not names or folder names. Keep IDs stable after publication.

Definition and state

World files contain definitions and a start state. A session copies them into its database. Changes during play never modify the source world.

Validation

Readers collect every problem with its document path. A malformed optional entity is not silently discarded when starting a session: character errors, broken references and invalid opening messages prevent creation so the session cannot begin half-populated.

Use UTF-8 JSON. Symbolic links and paths escaping the world directory are not accepted for media lookup.