File Types

A file type is the blueprint for a file in your project. If your world has characters, spells, items, locations, factions, or quests, each of those can be its own file type.

Every file type answers three practical questions: what information does this file store, how should that information appear on the page, and does Craft need to apply special treatment to this file type?

What a file type controls

Content type decides whether files are freeform Markdown files or structured JSON files.
Schema defines the fields a file can have, like name, level, armor class, portrait, or known spells.
Layout decides how those fields are arranged when the file is displayed.
Designation tells Craft when this type has a built-in role, like a character, location, GM instruction, or game start.

Content Type

A file type can use either Markdown or JSON content.

Markdown is simple, unstructured writing. Use Markdown for notes, lore, rules text, journal entries, or anything that reads best as a page of prose.

JSON is structured content. It means the file has a specific shape with named fields. Use JSON for things that should feel like sheets or records, like a character, item, spell, monster, faction, location, or quest.

If you pick JSON, the schema below decides which fields those files can have.

Schema

The schema is the list of fields every file of this type can use. You can think of it like a blueprint or a form. A character form might ask for level, hit points, and inventory. A spell form might ask for level, casting time, range, and effect.

Start with the fields you know you need. You can add more fields later as your project evolves. Below are the different field types you can use along with example scenarios of when to use them.

Built-in Fields

JSON file types always include built-in name, description, and image fields. Craft manages these fields for every file, so you do not add them as custom fields.

Voice

Character JSON file types can include voice as a built-in field. It is stored with the file version alongside name, description, and image, and it controls the voice Craft uses when that character speaks in GM narration.

voice is optional and nullable: leaving it blank uses the Game Master voice. The field name voice is reserved, so non-character file types should use a different name for custom fields.

Text

Text fields store words, short labels, or longer written notes. Use text when the answer should be typed freely.

Examples

name for a character, item, or spell name.
personality to describe how a character behaves.
appearance to describe what a character, creature, or place looks like.

Number

Number fields store values you want to count, compare, or use in expressions. They can have a minimum and maximum when the value should stay inside a known range.

Examples

level for a character, monster, or spell level.
age for a character's age.
hitPoints for current or maximum health.

Boolean

Boolean fields store a yes or no answer. They are useful for simple switches that should be either on or off.

Examples

isMagicItem for a magic item that shares the same file type as regular items.
requiresAttunement for magic items.
isHostile for an NPC or monster.

Enum

Enum fields store one value from a fixed list. Use an enum when you know there's only a fixed set of options that a field can have.

Examples

rarity with choices like common, rare, and legendary.
equipSlot with choices like head, feet, and hands.
damageType with choices like fire, cold, and poison.

Reference

Reference fields refer to a file of another file type. Use a reference when the linked thing deserves to live as its own file. For example, a character can represent inventory through a list of references to items.

Examples

equippedWeapon to point a character at one weapon.
faction to show which group an NPC belongs to.
knownSpells as a list of spell references.

For a deeper walkthrough, see Reference Fields.

List

List fields store more than one value. A list can hold simple values, objects, or references to other files. Lists can also have a minimum and maximum number of entries when the count matters.

Examples

inventory for a list of item references.
tags for a list of short text labels.
completedQuests for a list of quest references.

Object

Object fields group several smaller fields together under an object. You can think of an object as a nested file type that only exists as part of another file type. Use an object when those fields only make sense grouped together.

Examples

reward to group gold, item, and reputation.
damage to group dice count, die size, and damage type.
requirements to group level, class, and alignment.

Computed

Computed fields calculate a value from other fields. Use one when the value should update automatically instead of being typed by hand. In the editor they appear as Computed; in the schema they are a normal typed field with an expression key.

Examples

dexModifier to calculate from a dexterity score.
armorClass to combine base AC, dexterity, and armor.
inventoryWeight to total weights from item references.

For expression syntax, output shapes, and reference examples, see Computed Fields.

Layouts

The layout controls how files of this type look in Craft. The schema decides what information exists. The layout decides how that information appears.

A character layout might put portrait, name, level, and hit points at the top, then show inventory and relationships below. A spell layout might put level, school, and casting time together so they are easy to scan.

Designations

A designation is a special role Craft understands. Most custom file types do not need one. Use a designation only when the type should connect to a built-in feature, like characters in game play, locations on maps, GM instructions, or game starts.

For normal world data like monsters, spells, factions, quests, equipment, and rules, leave the designation empty and let the file type name describe what it is.

A simple way to choose fields

Use text for free writing, number for numeric values, boolean for yes or no, enum for a fixed choice, image for artwork, reference for links to other files, list for many values, object for grouped values, and a computed expression for anything calculated.

PreviousContext Visibility NextDesigning Schemas

File Types

A file type is the blueprint for a file in your project. If your world has characters, spells, items, locations, factions, or quests, each of those can be its own file type.

What a file type controls

Content type decides whether files are freeform Markdown files or structured JSON files.
Schema defines the fields a file can have, like name, level, armor class, portrait, or known spells.
Layout decides how those fields are arranged when the file is displayed.
Designation tells Craft when this type has a built-in role, like a character, location, GM instruction, or game start.

Content Type

A file type can use either Markdown or JSON content.

Markdown is simple, unstructured writing. Use Markdown for notes, lore, rules text, journal entries, or anything that reads best as a page of prose.

If you pick JSON, the schema below decides which fields those files can have.

Schema

Start with the fields you know you need. You can add more fields later as your project evolves. Below are the different field types you can use along with example scenarios of when to use them.

Built-in Fields

JSON file types always include built-in name, description, and image fields. Craft manages these fields for every file, so you do not add them as custom fields.

Voice

voice is optional and nullable: leaving it blank uses the Game Master voice. The field name voice is reserved, so non-character file types should use a different name for custom fields.

Text

Text fields store words, short labels, or longer written notes. Use text when the answer should be typed freely.

Examples

name for a character, item, or spell name.
personality to describe how a character behaves.
appearance to describe what a character, creature, or place looks like.

Number

Number fields store values you want to count, compare, or use in expressions. They can have a minimum and maximum when the value should stay inside a known range.

Examples

level for a character, monster, or spell level.
age for a character's age.
hitPoints for current or maximum health.

Boolean

Boolean fields store a yes or no answer. They are useful for simple switches that should be either on or off.

Examples

isMagicItem for a magic item that shares the same file type as regular items.
requiresAttunement for magic items.
isHostile for an NPC or monster.

Enum

Enum fields store one value from a fixed list. Use an enum when you know there's only a fixed set of options that a field can have.

Examples

rarity with choices like common, rare, and legendary.
equipSlot with choices like head, feet, and hands.
damageType with choices like fire, cold, and poison.

Reference

Examples

equippedWeapon to point a character at one weapon.
faction to show which group an NPC belongs to.
knownSpells as a list of spell references.

For a deeper walkthrough, see Reference Fields.

List

List fields store more than one value. A list can hold simple values, objects, or references to other files. Lists can also have a minimum and maximum number of entries when the count matters.

Examples

inventory for a list of item references.
tags for a list of short text labels.
completedQuests for a list of quest references.

Object

Examples

reward to group gold, item, and reputation.
damage to group dice count, die size, and damage type.
requirements to group level, class, and alignment.

Computed

Examples

dexModifier to calculate from a dexterity score.
armorClass to combine base AC, dexterity, and armor.
inventoryWeight to total weights from item references.

For expression syntax, output shapes, and reference examples, see Computed Fields.

Layouts

The layout controls how files of this type look in Craft. The schema decides what information exists. The layout decides how that information appears.

Designations

For normal world data like monsters, spells, factions, quests, equipment, and rules, leave the designation empty and let the file type name describe what it is.

A simple way to choose fields

PreviousContext Visibility NextDesigning Schemas