Craft

Project settings reference

The project's settings are one document: name, description and tags at the top, and everything else under settings. Each entry below is read from the schema that checks the document when it is saved, so the keys, types and limits are exactly what is accepted.

The project

name

The project's name, shown on its page, its cards and in the workspace.

Key Type Limits
name string

description

A short description, shown with the name on cards and the project page.

Key Type Limits
description string null clears it

One or two sentences. It is the line under the name on Discover cards.

tags

Tags from Craft's tag list, which Discover uses to group and filter projects.

Key Type Limits
tags string[] at most 3, each from the tag list

The tag list, by group:

Group Tags
Genre Fantasy, High Fantasy, Dark Fantasy, Urban Fantasy, Sword & Sorcery, Wuxia, Murim, Sci-Fi, Space Opera, Cyberpunk, Steampunk, Solarpunk, Post-Apocalyptic, Dystopian, Horror, Lovecraftian, Gothic, Supernatural, Mystery, Noir, Crime, Thriller, Romance, Romantasy, Comedy, Drama, Slice of Life, Adventure, Superhero, Western, Pirates, Mythology, Fairy Tale, Historical, Military, Espionage, Anime, Isekai, Action, Mecha, Creative, LitRPG, Grimdark, Science Fantasy, Xianxia, Sports
Setting Medieval, Ancient World, Victorian, Modern Day, Near Future, Deep Space, Space Station, Cyberspace, Multiverse, Dreamscape, Megacity, Small Town, Frontier, Wasteland, High Seas, Underworld, Japan, Earth, Feudal Japan, Wild West, Academy, Floating Islands, Underdark, Arctic, Jungle, School, Alternate History, Prehistoric, Desert, Underwater, Afterlife, Ruins, Colony, Battlefield
Tone Tense, Relaxed, Lighthearted, Suspenseful, Wholesome, Tragic, Satire, Heroic, Morally Gray, Dark, Gritty, Epic, Whimsical, Melancholic, Hopeful, Eerie, Romantic
Gameplay Combat Heavy, Dungeon Crawl, Exploration, Survival, Investigation, Heist, Puzzle, Sandbox, Tactical, Cozy, Simulation, Base Building, Monster Hunting, Hunting, Trading, Crafting, Farming, Naval, Time Travel, No Magic, Narrative, Political Intrigue, Dating Sim, Visual Novel, Solo Friendly, Multiplayer, Stealth, Diplomacy, Roguelike, Character Chat
Themes Vampire, Werewolf, Villain, Royalty, Anti-Hero, Dragons, Zombies, Demons, Gods, Magic School, Found Family, Revenge, Rebellion, War, Coming of Age, Artificial Intelligence, Time Loop, Prophecy, Monsters
Art Style Anime Art, Realistic Art, Painterly Art, Comic Art, Pixel Art, Photographic
Mechanics 5e Compatible, Dice-Based, Diceless, D20, D6, 2d6, Dice Pool, Percentile, Roll Under, Card Based, Class Based, Classless, Point Buy, Level Based, Skill Based, Magic

Copy a tag exactly, capitals and spaces included: "Dark Fantasy", not "dark fantasy". Only the first 3 that are on the list are kept.

The project page

settings.image

The cover image: the picture at the top of the project page and on its cards. An image object.

Key Type Limits
settings.image object null clears it

An image object, like a file's picture. Set it by generating or uploading a cover, never by writing a URL by hand.

settings.projectIcon

A small square icon, by URL, shown on cards, sidebar entries and previews.

Key Type Limits
settings.projectIcon string a URL; null clears it

settings.headlineLabel

A short label shown above the headline on the project page.

Key Type Limits
settings.headlineLabel string at most 80 characters; null clears it

settings.headline

One or two lines at the top of the project page that make someone want to play.

Key Type Limits
settings.headline string at most 400 characters; null clears it

settings.body

The project page's main text, in Markdown: the pitch, what the world is and what play feels like.

Key Type Limits
settings.body string null clears it

Markdown. Keep it to a pitch a visitor reads in a minute; rules and setting detail go in the handbooks.

settings.authorsNotes

The author's notes on the project page: credits, content notes, what changed.

Key Type Limits
settings.authorsNotes string null clears it

settings.gameSystemName

The name of the rules system the project plays by, shown on the project page.

Key Type Limits
settings.gameSystemName string at most 80 characters; null clears it

settings.attribution

Credit for the work the project draws on, shown on the project page.

Key Type Limits
settings.attribution string null clears it

settings.hideHeroTitle

Hides the project's name over the cover image, for a cover that already shows the title.

Key Type Limits
settings.hideHeroTitle boolean

The showcase images and videos on the project page, under Glimpses, in the order they are shown.

Key Type Limits
settings.gallery item[] at most 48 items

Its items and layouts are in the gallery reference. To change the gallery, edit the Glimpses section of the project page, in edit mode.

settings.galleryLayout

How the gallery is laid out. None means mosaic, the default.

Key Type Limits
settings.galleryLayout "mosaic" | "featured" | "grid" | "filmstrip" null clears it

settings.isClonable

Whether other people may clone the project to build on their own copy. Only the owner can change it, and a system can always be cloned.

Key Type Limits
settings.isClonable boolean

Turning it off stops other people from copying the world. It doesn't hide it: who can see it is its visibility, covered in Publishing.

settings.theme

The project's colors and fonts, made in the app's theme editor. Leave it as it is.

Key Type Limits
settings.theme object null clears it

The app's theme editor writes it. Don't change it by hand.

Images

settings.imageStyleInstructions

The project's art direction: a few sentences on medium, palette, mood and rendering style, added to every image generated for the project.

Key Type Limits
settings.imageStyleInstructions string longer text is cut to 5,000 characters; null clears it

How it is used, and how to write it, is in Project settings. A file type can add a style of its own: see Images.

settings.defaultImageModel

The image model a generation uses when it names none.

Key Type Limits
settings.defaultImageModel string null clears it

Image models and their prices are listed in energy and credits. When you generate a picture in the app, the model you pick there is used instead.

settings.autoImageGeneration

An older switch for illustrating new files automatically. It is kept with the project and copied to its games, but nothing reads it now.

Key Type Limits
settings.autoImageGeneration boolean null clears it

Leave it as it is.

The Game Master

settings.gm

The Game Master's name, portrait and narration voice in play.

Key Type Limits
settings.gm object
settings.gm.name string null clears it. What the Game Master goes by in play. Leave it and the image empty for a faceless narrator.
settings.gm.image object null clears it. The Game Master's portrait, an image object.
settings.gm.voiceId string null clears it. The id of the voice the Game Master narrates with. None means Craft's default voice.

Example:

{
  "gm": {
    "name": "The Chronicler",
    "voiceId": "leo"
  }
}

Pick a voice from the list in the Game Master settings, and play its preview first.

settings.gmToolSettings

Which optional Game Master tools are on. A key left out keeps its default.

Key Type Limits
settings.gmToolSettings object
settings.gmToolSettings.askPlayerToRoll boolean Shows a dice roller when the GM asks the player for a roll. Default: on.
settings.gmToolSettings.askUserQuestion boolean Lets the GM pause play with a multiple-choice question. Default: off.
settings.gmToolSettings.generateNames boolean Deprecated (GM Harness V1): lets the GM suggest names for characters and places. Default: on.
settings.gmToolSettings.gmExpressions boolean Shows the GM's portrait standing in the story while it narrates, its face changing with its tone. Needs a portrait. Default: off.
settings.gmToolSettings.research boolean Deprecated (GM Harness V1): lets the GM send quick lookups to a fast helper instead of reading whole files. Default: on.

Example, turning on multiple-choice questions and leaving the rest at their defaults:

{ "gmToolSettings": { "askUserQuestion": true } }

settings.gameOptions

The rules the GM runs the world by: world instructions, player options and their choices. None means Craft's defaults alone.

Key Type Limits
settings.gameOptions object null clears it

The format, limits and how to write good rules: GM instructions.

Other parts of the world

settings.rootMapFileReferenceId

The location file whose map is the project's root map, by the file's reference id.

Key Type Limits
settings.rootMapFileReferenceId string a reference id; null clears it

The file's reference id, not its path. See Maps.

settings.preludeFlow

The cinematic opening played in the game lobby, as a flow manifest.

Key Type Limits
settings.preludeFlow object null clears it

The manifest format: Flows.

settings.playerHandbook

The Player's Handbook: chapters on how to play, read by players.

Key Type Limits
settings.playerHandbook object null clears it

The chapter format and how to write one: Handbooks.

settings.builderManual

The Builder's Manual: chapters on how to build on the system, read by creators who use it.

Key Type Limits
settings.builderManual object null clears it

The chapter format and how to write one: Handbooks.

settings.firstSteps

The First Steps checklist that greets people who start a world from this system.

Key Type Limits
settings.firstSteps object null clears it

Only a system's author writes First Steps; a world shows the checklist it was copied with. The document:

{
  "version": 1,
  "welcome": "Welcome to the Ashen Reach. Five steps to your first session.",
  "steps": [
    {
      "kind": "action",
      "id": "cover",
      "title": "Add cover art",
      "action": { "type": "set-cover-image" }
    },
    {
      "kind": "action",
      "id": "hero",
      "title": "Create your first character",
      "body": "Anyone the story follows. You can change everything later.",
      "action": { "type": "create-file", "fileTypeSlug": "character" }
    },
    {
      "kind": "info",
      "id": "tone",
      "title": "This system runs grim",
      "body": "Read Combat before your first fight."
    }
  ]
}
  • image is optional: an image for the top of the checklist. Without it, the cover image is used.
  • Limits: at most 8 steps; a welcome of up to 500 characters; step titles up to 80 and bodies up to 300 characters.
  • Give each step its own short id. Info steps have no action and are never ticked off.

Action types:

type Fields What it does
create-file fileTypeSlug, setAsRootMap (optional) Opens the New File dialog for a file type, by its slug. With setAsRootMap, the new file becomes the root map.
open-folder folderPath Opens a folder, by its path of folder names from the top ("Places/Cities").
open-file folderPath, fileName Opens a file, by its folder path ("" for the top) and its name.
read-handbook book, chapterId (optional) Opens the Player's Handbook or the Builder's Manual, at a chapter or at the start.
open-assistant none Opens Orbit, the assistant.
set-cover-image none Opens a picker that sets the project's cover image.
edit-overview none Opens the project page in edit mode. Used by the fixed checklist a system shows its own author; the editor doesn't offer it.

Targets are names, matched ignoring case, because a world copied from the system has new ids. Use the file type's slug, the folder and file names as they appear in the system, and the handbook chapter's id.