The Codex: pictures and notes for your world
The Codex is a set of public entries about your world: its characters, places, factions, species, items, events and concepts, each with an optional picture. Players read it during a journey. The storyteller never reads it, so it does...
The Codex is a set of public entries about your world: its characters, places, factions, species, items, events and concepts, each with an optional picture. Players read it during a journey. The storyteller never reads it, so it does not change the story, and it is not the place for instructions or secrets.
It suits things players collect or look up: plants, ores, ingredients, creatures, factions. The world's locations are in it on their own, as places (see below).
Writing entries
In the world editor, open the Lore group, then the Codex section, and click Add Entry.
- Title: the name players will see and, in the story, tap on.
- Type: Character, Place, Faction, Species, Item, Event, Concept or Other.
- Summary: one or two lines, shown on the entry card.
- A picture, beside the title, type and summary. Any shape works, up to 8 MB. It is stored at 1536px on its longest side at most, so a larger file is scaled down. Square suits items, landscape suits places and scenes, and a transparent cut-out keeps its transparency.
- Body: the full entry, in Markdown.
- Visibility: three switches.
- Draft: on keeps the entry private to you. Turn it off when the entry is ready.
- Spoiler: the entry is listed, but blurred until the reader taps it.
- Secret: players do not have the entry until the journey reveals it (see below).
For a Character entry, pick one of the world's characters under Linked character to use that character's portrait when the entry has no picture of its own.
You can also start from the character: on an NPC's page, or on the character's row in the editor's Codex section, Add to Codex creates a Draft Character entry already linked to them, with their name and their Public/Codex description (or their role). Their description, appearance and dialogue stay private, so you write the entry's Body yourself. A character hidden until unlocked gets a secret entry, revealed with a Reveal Codex entry beat. Once the entry exists, the button reads Open Codex entry.
Players see the entries of the published version of the world, so publish after adding entries. Entries from a world with adult content are only shown to players who have mature content enabled.
Places
Every location in the world's Locations section is a Place in the Codex. You do not need to write a Codex entry for it: the place takes the location's image and text, and its page shows its map.
- A place is in a player's Codex once the journey knows it. A location with Known to the player from the start on is there from the beginning. A hidden one appears when the story reveals it, the same rule the map follows. Places the storyteller invents during play are not added.
- Its page shows the location's image, its text and a small map: a place with its own Map of this place shows that map, a place without one shows the map of the nearest place above it that has one, zoomed on its pin, and failing that the world map. A secret map stays hidden until the journey has found it. Tapping the small map opens the full map.
- A nested place says In its parent, as a link, and See also lists its parent and the places inside it.
- By default the lead line is the first sentence of the location's Description, and the text is the rest of the description plus the Atmosphere line. The Hidden detail is never shown.
On the location itself, a Codex block adjusts this. Show in the Codex is on by default, and off keeps the place out of the Codex. Codex summary (optional) replaces the lead line. Codex text (optional) replaces the text, in Markdown: use it when the description reads as notes for the storyteller rather than something to read. Spoiler lists the place but blurs it until the reader taps it. None of these fields is sent to the storyteller, which still reads the description as before.
In the editor's Codex section, the places are listed below the entries under N places from Locations, and clicking one opens that location. Places do not count toward the entry limit, and a Place entry that duplicates a location is no longer needed. When you want a fully hand-written page for a place, the Add to Codex button on its row starts a Draft Place entry carrying the place's title, summary, text, picture and Spoiler setting; a location not known to the player from the start gets a Secret entry, revealed like any other. The entry keeps the place's links, so story underlines and pinned table rows keep pointing at it. While it is a Draft, players still see the automatic place; once published, it replaces that place: players see its own text and picture, without the place's map, and the location's Codex settings no longer apply. Such an entry counts toward the limit, and the row's button then reads Open Codex entry. No "New Codex entry" card announces a place: the scene and the map already do.
Where players see it
A Codex button in the play view's journey tools opens the Codex, with a filter by type. It is read-only.
In the story text, the first mention of each entry's title in a turn gets a dotted underline. Tapping it opens a small card with the picture and summary, and Open in Codex opens the full entry. Matching ignores case, handles simple plurals ("Glowcap" also finds "glowcaps"), treats a leading "The" as optional, only matches whole words, and skips titles shorter than three letters. A short name that could also be an ordinary word ("Cue", or "on cue") is checked against the sentence it sits in once the turn is finished, and only gets its underline if it really names the entry; a stat name in a skill check never does. A place is matched only when its full name appears: no plurals, and "The" is not dropped, since place names are often ordinary words.
Items in the player's inventory and a character's equipment show the entry's picture and open the same card when their name matches an entry. A count is ignored ("3x Glowcap"), and a longer name that contains a title also matches ("Pouch of glowcaps").
In world tables (the Tables section of the Memory popup, see World tables), a row whose name matches an entry shows its picture, and any entry title written in a cell becomes tappable ("2 Glowcaps, 1 Slime gel").
Spoiler entries are never matched automatically, since an underline would give away that a name matters. You can still link them on purpose (next section), and the reader still chooses to reveal them.
Players who find the underlines distracting can turn off Link Codex entries in the story in Settings. That only affects the story text.
Secret entries
A secret entry is not in the Codex, not underlined in the story, and not linked from inventory or tables until the journey reveals it. A spoiler is listed but blurred. A secret does not exist for the player yet.
Turn on Secret and a How players find it block appears:
- A story beat can always reveal it: use the Reveal Codex entry effect in Story Beats.
- Reveal with lore entry: pick a lore book entry. If that lore entry is itself secret, the Codex entry is revealed when a beat reveals the lore. Otherwise, the Codex entry is revealed when one of the lore entry's keywords appears in the storyteller's narration. The player's own typed action never counts, so a player cannot unlock an entry by typing its name. The keywords are the trigger words, so choose them with care.
- Reveal when the player picks it up: reveals the entry the first time an item with a matching name is in the player's inventory. Made for Item entries. Matching follows the inventory rules above: a count is ignored, and a longer name that contains the title matches.
An entry can also announce itself: turn on its Show a "New Codex entry" card when found switch and the turn that reveals it shows a card with its picture. Tapping it opens the entry. The switch is off by default, since a card for every item picked up gets noisy. Allow "New Codex entry" cards in the Codex list turns every card off at once.
Players see how many secret entries they have not found yet at the bottom of the Codex list ("3 entries still to discover").
A secret entry with no way to be found (no beat, no lore link, no pickup) is flagged in the editor.
Linking on purpose
In the table editor, each row has a book icon. Use it to pin the row to an entry or a place, for example when the row name differs from the entry title. The icon also shows when a row already matches an entry by name. The link is display only and is not sent to the storyteller.
In an entry's Body, Link another entry inserts a link to another entry or a place at the cursor, or around the selected text. Written links work in entry bodies and in your world's opening text.
Tips
- Name items consistently. If the storyteller calls it "Glowcap" and your entry is "Glowcap", it links.
- Give item entries a picture, so inventories and tables show it. A small square cut-out on a transparent background reads best next to an item name.
- Make a field guide that fills in as the player collects things: secret Item entries with Reveal when the player picks it up.
Universes: linked worlds on one page
A universe puts related worlds on one public page. If you write sequels, spinoffs, or other stories in the same setting, it shows players how they connect. The page includes a suggested reading order.
How do I announce a world update?
Publishing a new version of your world is quiet on purpose. Nobody is notified, no shelf changes, and journeys already in progress carry on undisturbed. When a change is big enough that you want players to hear about it, you announce...