File content
A file's type sets its form. A JSON type stores fields its schema defines. A Markdown type stores a page of prose. Both are saved the same way underneath, and both have the fields every file has.
Fields every file has
Every file has name, description, image, whatever its type:
| Field | What it is |
|---|---|
name |
Required, never empty. The file's name and its identity. |
description |
Optional. A short line shown on cards and lists. |
image |
Optional. The file's main picture, as an image object ({ "url": … }). Leave it out, or write {}, for none, never null. |
A type's schema can't redefine these three. Character types also have an
optional voice, the voice its lines are read in. For how pictures are
stored and generated, see images.
JSON files
A JSON file is one object that must match its type's schema, plus the fields above:
{
"name": "Brinnel Darr",
"description": "A tavern bruiser who owes the Guild money.",
"level": 1,
"hp": 14,
"race": "human",
"inventory": [{ "item": "iron-cudgel", "quantity": 1 }]
}
- Every write is checked against the schema. A failed one saves nothing
and names each wrong field (
reward: must be number). - A number written as text (
"5"for a number field) is read as the number. An enum value that differs only by case is matched to the listed one. Any other wrong shape fails. - Copy enum values exactly as the schema lists them.
- A reference field holds another file's slug (
"race": "human"). Craft stores the file itself, so the link survives renames. See references. - Computed fields are worked out when the file is read. They are shown with the file but never saved: leave them out of writes.
Markdown files
A Markdown file is a page of prose with a short header of its fields. This is how it reads in the editor's source view:
---
name: The Fall of Gondor
description: How the white city fell.
---
# The Fall of Gondor
The body is plain Markdown…
- The header holds only
name,descriptionandimage. Any other key is dropped when it is saved. Put structured data in a JSON type. - Without a
name, the file name is used. - The body can mention other files, which shows as a link. See links and mentions.
Names and slugs
- A file's name is its identity. Renaming a file changes its stored
name, and changing thenamerenames the file. - Each name has a slug: lowercase, quotes dropped, and every other run of
characters that aren't letters or digits turned into one dash
(
Brinnel Darrisbrinnel-darr, "Nature's Tongue" isnatures-tongue). References and mentions are written with it. - Within one type, every name's slug is unique across the whole world,
whatever folder the files are in. Two types can share a name: a
miracharacter and amiraship. - Behind the slug, each file has a fixed id that never changes, even when the file is renamed or copied into a game. That id is what links store.
Folders
- Folders hold any mix of types, and nest.
- Two folders side by side can't share a name (case aside), and a folder's name can't be blank.
- Deleting a folder sends everything in it to the trash.
- The GM sees each folder and how many files it holds, so a name like
Harbor Districttells it where to look.
Limits
| Limit | Value |
|---|---|
| Files in a world or game | 10,000 |
| Folders in a world or game | 1,000 |
| How deep folders nest | 15 levels |
Files and folders in the trash don't count. For every limit in one place, see limits.