Craft

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, description and image. 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 the name renames 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 Darr is brinnel-darr, "Nature's Tongue" is natures-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 mira character and a mira ship.
  • 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 District tells 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.