Lore Codex

A lore codex is a book of entries that fill in as the player finds their pieces: a torn page, a carving, an overheard story. Each new piece is marked until it is read, and an entry is complete when every piece is found and read. Finding the same piece twice never makes a read entry new again.

Also called: Codex, Journal entries, Bestiary and lore book, Collectible lore.

A hooded fox with a blue lantern sets a torn scrap into a gap in a huge open picture book. The scrap glows green, and a small glowing seal floats at the corner of the page. — Ninefold Margin, an invented illustrated mystery game. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Lore Codex" to my game.

What it should do: A codex gives the story a place to live outside the action. The player collects it at their own pace, sees how much is still missing, and comes back to a half-understood mystery later.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> hidden
  hidden: Still hidden
  new: Unread pieces
  read: All read
  done: Complete
  hidden --> hidden: nothing found
  hidden --> new: first piece found
  new --> new: more found or no change
  new --> read: pieces read
  new --> done: last pieces read
  read --> read: no change
  read --> new: a new piece found
  done --> done: no change
  done --> [*]
```

Use these starting values:
- badgeCap: 9 entries
- nameAfter: 1 pieces

Watch out for these common mistakes:
- Finding a piece again brings the marker back: Tell your AI: when a piece is found, check first whether it is already found, and if so change nothing at all.
- An update makes a finished entry unfinished: Tell your AI: never save whether an entry is finished or how long it is. Save only which pieces were found and read, and work out the rest from the game's list each time.
- A piece that does not exist: Tell your AI: ignore any entry or piece number the list does not have, and report it so the mistake can be fixed.
- The badge grows wider than the button: Tell your AI: count entries with something new, not pieces, and cut the number at a cap, showing "9+" above it.
- The name gives the mystery away: Tell your AI: show question marks until enough pieces are found, and for a very short entry show the name once all its pieces are found.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

A codex gives the story a place to live outside the action. The player collects it at their own pace, sees how much is still missing, and comes back to a half-understood mystery later.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Still hidden → Still hidden: nothing found
Still hidden → Unread pieces: first piece found
Unread pieces → Unread pieces: more found or no change
Unread pieces → All read: pieces read
Unread pieces → Complete: last pieces read
All read → All read: no change
All read → Unread pieces: a new piece found
Complete → Complete: no change

Good starting values

Value	Start with	What it changes
badgeCap	9 entries	The most entries the new-marker badge on the codex button counts. Above it the badge says "this many or more", so it never grows wider than the button.
nameAfter	1 pieces	How many pieces of an entry must be found before its real name shows instead of question marks. A higher number keeps a mystery hidden for longer. A short entry shows its name once all of its pieces are found.

What usually goes wrong

Finding a piece again brings the marker back

The player passes the same torn page twice. The codex treats it as new, the entry lights up again, and the player opens it for nothing.

Fix: Tell your AI: when a piece is found, check first whether it is already found, and if so change nothing at all.

An update makes a finished entry unfinished

The save stores "done" and a new version adds a fourth piece to the entry. The codex still shows a gold star while a piece is missing, and the player never looks for it.

Fix: Tell your AI: never save whether an entry is finished or how long it is. Save only which pieces were found and read, and work out the rest from the game's list each time.

A piece that does not exist

A mistyped number or entry name quietly creates a found piece nobody can ever read, and the entry never reaches complete.

Fix: Tell your AI: ignore any entry or piece number the list does not have, and report it so the mistake can be fixed.

The badge grows wider than the button

After a big find the badge says 47 and spills out of the codex button.

Fix: Tell your AI: count entries with something new, not pieces, and cut the number at a cap, showing "9+" above it.

The name gives the mystery away

An entry called "The Drowned Choir" appears in the book the moment the first scrap is found, and the player knows the twist before they have earned it.

Fix: Tell your AI: show question marks until enough pieces are found, and for a very short entry show the name once all its pieces are found.

How to check it works

An entry with three pieces and nothing found. the player finds piece 1: the entry is no longer hidden, it is marked as having something new, and it shows one of three found.
A piece was found and read. the player finds the same piece again: the game says it is already found, and the entry stays read, with nothing new.
An entry with two unread pieces. the player opens and reads it: nothing is marked new any more, and the entry is not complete while pieces are missing.
A read entry with one piece found. the player finds another piece: the entry is marked new again, and only the new piece counts as unread.
An entry whose pieces are found out of order. the last piece is found and then everything is read: the entry is complete, and a one-piece entry is complete after one find and one read.
An entry with three pieces. the game reports piece 3, piece -1, piece 1.5 or something that is not a number: every one is ignored as unknown and nothing is saved.
A list of entries without "sea-glass". a find or a read names "sea-glass", or a name that is built into the language such as "toString": it is ignored as unknown and no entry is created.
An entry with nothing found, or with everything read. the player tries to read it: the game says there is nothing to read and the saved lists stay as they were.
Twelve entries all have something unread and the cap is 9. you ask for the badge, then read three entries: it shows 9 with a flag for "more", then 9 without it, and a fresh game shows 0.
The name shows after two pieces. one piece is found, then a second: the name stays hidden after the first and shows after the second.
The name shows after four pieces, but an entry has only one. that one piece is found: the name shows, because the entry cannot give more.
An entry with three pieces is complete and saved. an update makes the entry four pieces long and the save is loaded: it is no longer complete, it shows as read with a piece missing, and the badge does not light up.
A save holds an entry the game dropped, repeated and out-of-range piece numbers, and "read" marks for pieces never found. the save is loaded: the dropped entry and impossible numbers are gone, the repeats are gone, and only found pieces stay marked as read.

Works well with

World State Flags: The codex remembers what was read, while the flags remember what the world should do about it. Keep both lists, so reading a page does not have to change the world. Set a flag when a piece is found, then let doors and talk ask for it.
Dialogue System: Characters can also ask what the player knows, so a character can react to an entry the player has completed. Let a conversation hand out a piece, then show it in the codex.
Achievements: "Complete every entry" is a natural reward and needs no code beyond a count of entries that are done. Check for complete entries after each find, not each frame.

Common questions

how do i build a lore codex for my game

Keep a list of entries, each with a fixed number of pieces. Save only which pieces were found and read, mark new pieces until the player opens them, and call an entry complete when every piece is found and read.

why shouldn't i save that an entry is complete

Because a later update may add a piece to it. If you save only the found pieces, the entry simply becomes incomplete again and the player gets a reason to look for the new one.

what do i tell my ai to add a codex

Paste this: Add a lore codex. Each entry has a set number of pieces from my list. Mark new pieces until they are read, ignore a piece that is already found, show question marks for the name until enough pieces are found, and keep the new-entry badge at a cap of 9.

should the codex show how many pieces are missing

Usually yes, as "2 of 5". It gives the player a goal without telling them where to look. Hide the number only if finding out how long the secret is would spoil it.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

16 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it