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...

It suits things players collect or look up: plants, ores, ingredients, creatures, places, factions.

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 1024px 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, Add to Codex creates a Draft Character entry already linked to them, with their name and their public cast 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.

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.

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, 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 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.