The Content Map
The whole world is a set of folders, one per thing that matters. Knowing which folder something belongs in is the first half of building well.
The four folders, and the one that is different
/Characters/ each file = one character (.character.json)
/Equipment/ each file = one object (.equipment.json)
/Locations/ each file = one place (.location.json)
/Game Starts/ each file = one launch card (.game-start.json)
Four folders, four file types, four schemas. The fifth home is /GM Instructions/ — markdown, not JSON — holding the master's operational manuals. Keep that split sacred: a GM engine note is not a Location, and a Location is not prose.
The file name in its folder is the thing's name. Crosswater Wayhouse.location.json is a Location named Crosswater Wayhouse. Keep names human and stable — they are how the AI finds and reasons about the entry.
Why filenames carry a slug
Every filename ends in its file type's slug: .character.json, .equipment.json, .location.json, .game-start.json. This is not decoration. It is what lets one file point at another unambiguously — an inventory entry knows it references an equipment file, a map knows its pins are location files — without any shared database. The slug is the address.
Files point at each other, by reference
The schema stores references as strings: readable target names, not invented IDs. When you write a character's inventory, you put the equipment's name, and the sheet resolves it to the actual file at render time.
Two rules make references safe:
- Reference an existing file. A reference to a name that resolves to nothing renders as a broken chip and — worse — a computed field that depends on it silently returns nothing. Create the target before you point at it, or leave the field empty.
- Reference one thing, fully. An inventory row names one item. A character's origin names one derived category. Avoid inventing compound references like
sword-and-shield; build real entries and link to them.
The cross-cutting rule: categories are enumerated
Almost every value that the machine reasons over is an enumerated choice, not free text. Equipment must be one of Weapon, Armor, Gear, Consumable, Treasure. A character's attributes come from a fixed set. This is what lets the AI sort, weigh and compare cleanly. Where a schema offers an enum, use a value from the enum — it is a contract, not a suggestion.
When you add a new thing
Match the folder. If you are adding a blade, that is a new Equipment file in /Equipment/, not a sentence inside a character's notes. If you are adding a village, that is a Location file in /Locations/. The system reasons over files, and text buried inside another file's notes is invisible to that reasoning. A real, typed entry is the difference between a world the AI can run and a wall of words it can only recite.
If what you want to add fits none of the four folders — a faction, a spell, a faction NPC with no sheet — see Extending the System before you improvise.