World manifest

Generated by pnpm schemas:generate from the Zod schemas in packages/shared/src/schemas/. Do not edit by hand; change the schema's .describe() text instead.

The world.yaml at the root of a world package.

JSON Schema: world-manifest.schema.json.

In the path headings below, [] is a list item and .* is a map value.

Top-level fields

Field	Type	Required	Description
id	string	no	Stable world ID: lowercase letters, digits and hyphens, starting with a letter. Defaults to the name of the world's directory. Example: "my-world".
name	text	yes	Display name of the world.
version	string	no	Version of the world package. Example: "0.1.0".
summary	text	yes	One or two sentences shown on the world card.
defaultLocale	string	yes	Default content locale as a BCP 47 tag. A session uses it when the request sets no locale.
tags	list of string	no	Free-form catalogue tags, such as genre.
author	object	no	Who made the package. Shown on the package's cards before play, never during play.
license	string	no	License of the package: an SPDX identifier or a short name. Example: "MIT", "CC-BY-4.0".
homepage	string	no	Page of the package itself, such as its repository or documentation. https only. Example: "https://example.com/my-package".
pluginPolicy	object	no	Which plugins a session of this world starts with. It states intent and locks nothing; the player can change the selection.
worldData	string	no	Path of the world data descriptor, relative to the world root. Every package is read by convention: each file at a well-known path (data/dimensions.yaml, data/lorebook.yaml, characters/characters.json, and the path each installed plugin names for its data) is a source. The descriptor adds to that: an entry with the path of a conventional source changes it (enabled: false turns it off), any other entry adds a source. Example: "data/world.data.yaml".
characterSchema	object	no	Character types and attributes of this world. When present, sessions use it as written and no schema is generated.
dimensions	map of object	no	Dynamic world dimensions keyed by dimension ID. Each entry is one full definition.
pluginSettings	map of map of any	no	World defaults for plugin settings, keyed pluginId → settingKey → value. Resolution order: player override, then this value, then the plugin's own default.
defaultViewMode	"stage" or "parsed" or string	no	Initial view: stage, parsed or plugin:<pluginId>:<viewId>. The player's own choice wins. Session bridge views require consent.
cover	string	no	Cover picture of the world for the world list, the world page and the session backdrop, as a path relative to the world root: a .png, .jpg or .webp file one directory under media/. Without it the app shows its own default. Example: "media/gallery/world-cover.webp".
accentColor	string	no	Accent colour of the world's cards and headings: a hex colour (#rrggbb) or an oklch(L C H) colour, with Oklab lightness from 55% to 90%. World loading discards invalid values and logs a warning; authoring validation reports them as errors. Without a valid value the app derives one from the world ID. Example: "#c9a24b", "oklch(72% 0.12 75)".
themeMusic	string	no	Music of the world for the world list, as a path relative to the world root: an .mp3 or .wav file one directory under media/. The world list plays it for the world the player looks at. The music of a session comes from the plugin that plays music, not from this field. Example: "media/music/theme.mp3".

author

Field	Type	Required	Description
name	string	yes	Name of the person or team. Shown as written in every language. Example: "Jane Doe".
url	string	no	The author's own page. https only. Example: "https://example.com".
about	text	no	A short message from the author to players: who they are, what else they make, how to support them. Plain text.
links	list of object	no	Links the author wants players to see, such as a community, a support page or other work. At most 6.

author.links[]

Field	Type	Required	Description
label	text	yes	Text of the link. Example: "Discord".
url	string	yes	Address of the link. https only. The player sees the full address and confirms before it opens. Example: "https://example.com/community".

pluginPolicy

Field	Type	Required	Description
preset	string	no	ID of the built-in pack a new session starts from, such as traditional-story or dialogue-mode (packs/builtin.yaml).
plus	list of string	no	Plugin IDs this world adds to whichever pack the player picks. Never list a kind: core plugin: every session has those already.
pitch	object	no	How the session preparation screen presents preset for this world: its own label, description and reason in place of the pack's.
packs	list of string	no	IDs of the built-in packs the player may choose from, in this order. Without it every built-in pack is offered. preset must be one of them.
requires	list of string	no	Contract IDs the world needs, such as action-check@1. Any installed provider satisfies one. Without one, a session starts without that part of the world and tells the player.

pluginPolicy.pitch

Field	Type	Required	Description
label	text	no	Name of this world's selection, shown on the pack card.
description	text	no	What the selection offers. Shown to the player.
reason	text	no	Why the selection suits the world. Shown to the player.

characterSchema

Field	Type	Required	Description
types	list of string	no	Character types besides the reserved player. Defaults to npc and companion. Default: ["npc","companion"].
attributes	list of object	yes	Attribute definitions. Display order follows array order.

characterSchema.attributes[]

Field	Type	Required	Description
id	string	yes	Stable machine key of the attribute, such as hp.
name	text	yes	Display label of the attribute.
type	"string" or "number" or "boolean" or "enum" or "array" or "object" or "map"	yes	Value type. object needs subSchema; map is an open-key record typed by valueType.
min	number	no	Minimum value. For number only.
max	number	no	Maximum value. For number only.
defaultValue	any	no	Value given to a new character.
itemType	"string" or "number"	no	Element type. For array only.
options	list of string	no	Allowed values. For enum only.
subSchema	list of object	no	Child attribute definitions. For object only.
valueType	"string" or "number" or "boolean"	no	Value type of each entry. For map only; defaults to string.
category	"stats" or "bio" or "abilities" or "equipment" or "social"	yes	Group used by the character panel and by prompt context. stats are meters the status bar shows (health, stress); abilities are what checks and point buy use; social holds relationships; bio identity text; equipment what the character carries.
description	text	no	What the attribute means. Shown to the player and given to the model.

characterSchema.attributes[].subSchema[]

Same fields as characterSchema.attributes[].

dimensions.*

Field	Type	Required	Description
name	text	yes	Display name of the dimension.
description	text	no	What the dimension tracks.
schema	object	yes	Value schema in the supported JSON Schema subset. Unsupported keywords are rejected.
initialValue	any	yes	Starting value. It must satisfy schema.
updateRule	text	no	Natural-language rule for how the value changes in play. When non-empty, the dimension tracker settles it after each turn. Omit it for static setting.

dimensions.*.schema

Field	Type	Required	Description
type	"string" or "number" or "integer" or "boolean" or "null" or "object" or "array" or list of "string" or "number" or "integer" or "boolean" or "null" or "object" or "array"	no	JSON type of the value, or a list of types for a nullable value.
title	text	no	Display label of this node.
description	string	no	What this node holds. Given to the model.
enum	list of any	no	Allowed values.
const	any	no	The only allowed value.
minimum	number	no	Inclusive lower bound.
maximum	number	no	Inclusive upper bound.
exclusiveMinimum	number	no	Exclusive lower bound.
exclusiveMaximum	number	no	Exclusive upper bound.
minLength	integer	no	Minimum string length in characters.
maxLength	integer	no	Maximum string length in characters.
items	object	no	Schema of every array element.
minItems	integer	no	Minimum array length.
maxItems	integer	no	Maximum array length.
properties	map of object	no	Schemas of the named properties of an object.
required	list of string	no	Property names that must be present. Each must be declared in properties.
additionalProperties	boolean or object	no	false rejects undeclared keys. A schema describes dynamically named records.
x-i18n	boolean	no	Marks this node as translatable text: its value is a string written in the file's own language; translations go in the locale edition of the file. Nodes without it are never localized.
x-enumLabels	map of text	no	Display labels keyed by enum member. A label never replaces the stored value.
x-derive	object	no	Computes this value from the world clock in code, in the turn the clock moves: start + perUnit * source, kept inside min / max, or the label ranges gives for that number. No model writes a derived value. Allowed on the value itself or on a property reached through properties only.

dimensions.*.schema.items

Same fields as dimensions.*.schema.

dimensions.*.schema.properties.*

Same fields as dimensions.*.schema.

dimensions.*.schema.additionalProperties

Same fields as dimensions.*.schema.

dimensions.*.schema.x-derive

Field	Type	Required	Description
source	"clock.elapsedSinceStart"	yes	What the value is computed from. clock.elapsedSinceStart is the time on the world clock since the session began, in the clock's base unit: minutes on a calendar, phases on a phase clock.
start	number	no	The number when the source is 0. Default 0.
perUnit	number	no	What one unit of the source adds to the number; negative for a countdown. Default 1.
min	number	no	The number never goes below this.
max	number	no	The number never goes above this.
ranges	list of object	no	Turns the number into a label: the first range that holds the number gives the value. The last range has no bounds. Without ranges the value is the number itself.

dimensions.*.schema.x-derive.ranges[]

Field	Type	Required	Description
from	number	no	Inclusive lower bound of the number.
to	number	no	Inclusive upper bound of the number.
value	string or number or boolean	yes	The value of the field while the number is in range.