The FableDraft world file

FableDraft imports a whole world from one JSON file. The same format comes out when you export a world, so a file can go out and back in. You can also write one by hand, generate it with a script, or ask an AI assistant to turn your notes into one.

• JSON Schema: /schemas/world-1.json
• A complete example to download: /examples/example-world.json

Only two things are required: the world name, and a type and name on each entity. Everything else is optional.

The smallest file

{
  "name": "Tiny",
  "entities": {
    "mira": {"type": "character", "name": "Mira", "fields": {"homeLocationId": "port"}},
    "port": {"type": "location", "name": "Port", "body": "Home of [[id:mira]]."}
  },
  "links": [{"fromId": "mira", "toId": "port", "type": "located_in"}]
}

This makes a world called Tiny with a character, a town, and a link between them. mira and port are ids. You make them up; they only matter when something else needs to point at that entity.

A fuller example

This is the downloadable example file. It has two characters, a town, a faction, a quest with one step, a link, a journal entry and a calendar era.

{
  "$schema": "https://fabledraft.com/schemas/world-1.json",
  "name": "The Saltglass Reach",
  "description": "A coast where the sea froze into glass. Smugglers light paths across it.",
  "calendar": {
    "dateOrder": "mdy",
    "yearLabel": "AR",
    "eras": [{"name": "The Glass Years", "start": 1, "end": null, "color": "#3b6ea5"}]
  },
  "entities": [
    {"id": "gullhaven", "type": "location", "name": "Gullhaven",
     "summary": "A harbour town on the edge of the glass.",
     "fields": {"kind": "town", "founded": "-120"}},
    {"id": "guild", "type": "faction", "name": "The Lantern Guild",
     "description": "Smugglers who mark the safe paths across the ice.",
     "fields": {"leaderId": "Vessa Crane", "baseLocationId": "Gullhaven"}},
    {"id": "mira", "type": "character", "name": "Mira Saltwhistle", "tags": ["party"],
     "summary": "A lamplighter who owes the guild money.",
     "fields": {"role": "pc", "born": "04-17-38", "homeLocationId": "gullhaven", "factionIds": ["guild"]}},
    {"id": "vessa", "type": "character", "name": "Vessa Crane",
     "body": "Captain of [[The Lantern Guild]]. Trusts [[id:mira|Mira]] more than she should.",
     "fields": {"role": "ally", "homeLocationId": "gullhaven", "factionIds": ["guild"]}},
    {"id": "lights", "type": "quest", "name": "Lights on the Glass", "status": "active",
     "fields": {"giverId": "vessa", "difficulty": "easy", "locationIds": ["gullhaven"],
       "objectives": [{"id": "s1", "text": "Relight the north lantern", "done": false, "action": "go", "locationId": "gullhaven"}]}}
  ],
  "links": [
    {"fromId": "mira", "toId": "Vessa Crane", "type": "friend", "label": "old cellmates"}
  ],
  "journal": [
    {"date": "03-02-61", "title": "Session 1", "entityIds": ["mira", "lights"],
     "body": "[[Mira Saltwhistle]] took the lantern job from [[Vessa Crane]]."}
  ]
}

Some things to notice:

• Entities are a list here. They can also be an object keyed by id, as in the smallest file.
• References use an id ("vessa") or a name ("Vessa Crane"). Both work.
• The faction uses description for its main text. That is the same as body.
• "$schema" is optional. It lets editors like VS Code check the file as you type.

Ids and references

An id is any short string you choose: mira, loc-1, 42. FableDraft keeps an id when it is 8 to 12 letters, digits, _ or -. Any other id is replaced with a new one, and every place that pointed at it is updated to match. You never need to care what the final ids are. Give every entity a different id.

A reference is any key that points at an entity:

• parentId on an entity
• fromId and toId on a link
• any field whose key ends in Id (one entity) or Ids (a list), including inside quest steps, rewards and talks. Three keys are not entity references and are kept as written: stepId (a quest step), switchId (a world switch) and talkId (a talk)
• entityIds on a journal entry
• entityId and underId on a map marker, and locationId on a map

A reference can hold an entity's id or its name. A name matches without caring about upper or lower case. If two entities share a name, the first one in the file wins. Use ids when names repeat.

Top level

The whole object may also sit inside a "world" key: {"world": {...}}. Exports from older versions look like that.

Entities

Every entity has a type. The eight types are arc, quest, character, location, faction, item, event and note.

The default statuses are idea, planned, active, completed, failed, dead and retired.

Fields by type

Kinds:

• text: a string.
• choice: one of the listed values. Another word is kept as written, with a warning.
• date: an in-world date, see Calendar and dates.
• ref / refs: one reference, or a list of references, to the listed type.
• yes/no: true or false. 1, 0 and the strings "yes", "no", "on", "off", "true" and "false" work too.
• number: a number, or a string that holds one.

Every type can also have parentRelation (text): what the line to the parent says in the graph, like "part of". Empty shows "parent".

A quest step (objectives) is an object:

count and targetText stay only under collect, kill or a word off the list. Under any other action, or none, they are removed with no warning. Text over its limit is cut, with a warning.

The target of a step, by action:

If you read this data to build a game:

• When a list holds more than one entry, the first is the target and the rest are context. count applies to that one target.
• locationId on any action but go says where it happens. It is context, not a target.
• An action with no target is valid. Treat it like other.
• done is the author's own progress tick. A game ignores it.

A quest reward (rewards) is an object:

Any other key in fields is kept as written, with a warning.

Talks

A talk is one conversation between a character and the player. A character's talks is a list of talks. The game plays the first talk in the list whose conditions pass, so put the most specific talks first.

"talks": [{
  "id": "t-k3j9x2",
  "title": "First meeting",
  "conditions": [{"kind": "quest", "questId": "lantern", "state": "not_started"}],
  "lines": [
    {"id": "l1", "speaker": "character", "text": "You look lost, traveller.",
     "conditions": [], "effects": [], "next": null,
     "choices": [
       {"id": "c1", "text": "I'm looking for the lantern keeper.",
        "conditions": [], "effects": [{"kind": "start_quest", "questId": "lantern"}], "next": "l2"},
       {"id": "c2", "text": "Never mind.", "conditions": [], "effects": [], "next": "end"}
     ]},
    {"id": "l2", "speaker": "character", "text": "Follow the coast north.", "next": "end"}
  ]
}]

A talk:

A line:

A choice has id, text (up to 2000 characters), conditions (the choice is hidden when one fails), effects (they run when it is picked) and next (a line id, "end", or null for the line below).

All conditions in one list must pass. Each list holds up to 10 conditions or effects. Longer lists are cut, with a warning. A condition or effect is an object with a kind:

questId and itemId are references to a quest and an item (an id or a name). stepId is the id of a step in that quest's objectives. switchId is the id of a switch in Settings. A missing has or on means true.

On import, a condition or effect whose reference cannot be found, points at the wrong type, or names an unknown switch is dropped, with a warning. A condition or effect with a kind FableDraft does not know is kept as written, with a warning; it is dropped (with a notice) the next time the character is saved in FableDraft.

Links

A link is a named relation between two entities. It shows on both entity pages and in the graph.

The default relation types are ally, enemy, rival, family, friend, lover, mentor, member_of, leads, located_in, owns, knows, serves, created and other.

Journal

Session notes.

Maps

A marker:

Positions are fractions of the image, so they stay put when the image is resized. Numbers outside 0 to 1 are pulled back to the nearest edge.

Calendar and dates

An era:

An in-world date is one of:

• MM-DD-YYYY, for example 04-17-1203
• MM-YYYY, for example 04-1203
• YYYY, for example 1203

The year always comes last. Use - or / between the parts. Years can be negative (-300) and up to six digits. Months go from 1 to 12 and days from 1 to 31. Leading zeros are optional.

Old exports wrote dates year first (1203-4-17). Without "dateOrder": "mdy", a date that cannot be read month first but looks year first is turned around (1203-4-17 becomes 04-17-1203), with a warning. An old export (one with a top-level created key and no dateOrder) has all its dates read year first. With "dateOrder": "mdy", dates are never turned around.

Settings

A switch:

Leave settings out to keep the defaults.

Name lists

Name lists hold names for the name generator. Most files can leave them out.

• nameCultures: a list of {id, name, style, order}. style is a short note on how names in this culture sound.
• nameLists: a list of {id, title, kind, culture, structure, style, names, parts, isPublic, order}. kind is one of character, place, region, town, faction, item, other. structure is single or given_family. culture is the id of an entry in nameCultures. names is a list of strings or {name, note, starred} objects, up to 500. parts is {prefixes: [...], suffixes: [...]}.

Wikilinks

Any text that allows Markdown can link to an entity:

Name links match without caring about case. A name with no matching entity shows as a "click to create" link. [[id:...]] links are updated on import when an id is replaced.

Images

Images are base64 data URLs, for example data:image/png;base64,iVBORw0.... PNG, JPEG, GIF and WebP work. An image over the size limit (10 MB by default) is re-encoded as WebP on import, so it usually still fits. A character portrait goes in portraitData on the entity. Images on any other type are not stored.

Limits

• The file can be up to 64 MB by default. The server admin can change this.
• One import makes one new world. It never changes an existing world.

What stops an import, and what only warns

Nothing is saved until the whole file has been checked. Either the whole world is imported or none of it is.

These stop the import, with a message naming the key:

• The file is not valid JSON, or the top level is not an object.
• The world has no name.
• An entity has no name, or its type is not one of the eight types.
• A key has the wrong kind of value: fields is not an object, order is not a number, tags is not a list of strings, summary or body is not a string.
• parentId chains loop back on themselves.
• A marker has no x or y.
• An image is not PNG, JPEG, GIF or WebP, or is too large even after shrinking.
• A calendar era has no name, a start that is not a whole number, an end before its start, or a color that is not like #a1b2c3.
• daysPerMonth is not a whole number from 1 to 31 (or null), or weekDays has more than 14 names.
• The calendar's today is not a date.
• monthNames has more than 12 names, or settings.statuses or settings.relationTypes is an empty list.
• settings.switches is not a list of objects, has more than 200 switches, or a switch has no name (or one over 120 characters).

These import, with a warning in the import report:

• An unknown key inside fields is kept as written.
• A choice not in the list, or a date in the wrong form, is kept as written.
• A list or object where a single value belongs is dropped. So is a number field that holds no number, and a yes/no field that is not yes or no.
• A second marker for the same entity on one map is dropped.
• A reference that matches no id and no name is dropped. A link with such a reference is dropped as a whole, and so is a map marker.
• A status the world does not have is added to the world's statuses.
• An entity id used twice: the later entity gets a new id. References to that id point at the first entity.
• A year-first date in a file without dateOrder is turned around.
• Talks: what breaks the rules in Talks is repaired or dropped (text cut to its limit, a bad next or speaker reset, a clashing talk id replaced, extra talks, lines, choices or rules cut). Unknown condition and effect kinds are kept.

These import without a warning:

• Unknown keys outside fields are ignored.
• A parent of the wrong type is removed, so the entity sits at the top level.
• Marker positions outside 0 to 1 are pulled back to the nearest edge.
• Ids that are not 8 to 12 letters, digits, _ or - are replaced.

About the schema

world-1.json is a JSON Schema (draft 2020-12). Its $id is https://fabledraft.com/schemas/world-1.json, and every FableDraft site serves the same file at /schemas/world-1.json.

The schema allows extra keys everywhere, like the importer. It is a little stricter than the importer in a few places. The schema lists the usual choices; the importer accepts other words and warns. The schema also flags a badly formed date, a yes/no or number written as a string, and a marker position outside 0 to 1, where the importer keeps, converts or fixes the value and carries on. A file that passes the schema imports without those warnings.

The schema cannot check that a reference points at a real entity. The importer does that.