The codex

The bible of your universe: entries, your own types and fields, calendars and dates, what is true when and where, and finding every mention in your books.

What a codex is, and whether you need one

The idea

A codex is the bible of your world: the characters, places, things, factions, rules, events and maps, each with a page of its own, and each page knowing what is true where and when. Write keeps one per universe, so every series set in that world reads from the same book of facts—and so does any AI you've connected, which is where a codex really starts to pay for itself.

If you've ever kept a spreadsheet of eye colours, or scrolled back three books to check which hand a character lost, this is that, kept for you.

Do you need one?

Not right away, and maybe not at all. A standalone novel with a dozen characters does fine with the notes panel—and notes have tags now, so they can be a small codex of their own (see Notes that become codex entries). A codex earns its keep when:

Start with notes. When a note wants to be shared across books, turn it into an entry; the rest of the codex can grow from there.

How it's put together

Where to find it

From the Library, Manage → Codexes lists your universes, each with an Open codex button. From inside a book, the Codex button in the editor's toolbar opens a rail that shows who and what the scene you're writing mentions, with a link to the whole codex framed to that book—see The codex while you write.

Put your series in a universe

Why a book has to belong somewhere

A codex lives in a universe, and a book reads the codex through its series: if the series is in the universe, every book in it sees the codex, and every entry can say "this is true in book 3" by name. Until a series is in a universe, its books have no codex to read—the Codex rail in the editor will tell you so, and so will the codex's own page.

So the order is: make a universe, put the series in it, open the codex.

Make a universe

From the Library, click Codexes in the Manage row. You'll see the Universes page: every universe you have, under its pen name, with an Open codex button beside each.

Click New universe, type its name (Aeon 14, say), choose which pen name it belongs to if you have more than one, and click Add. That's the whole of it—a new universe comes with a Gregorian calendar and the built-in entry types, ready to go.

Screenshot: the Universes page Screenshot: the Universes page (Library → Manage → Codexes), showing a universe listed under its pen name with its Open codex button, and the New universe button.

You can also make one from Pen names, where each pen name lists its universes.

Put a series in it

Back in the Library, look at the series heading. If the series isn't in a universe yet and its pen name has one, you'll see a dashed button there—+ Aeon 14, or whatever you called it. Click it and the series joins the universe; the button becomes a small tag with the universe's name, and clicking that tag opens the codex.

Screenshot: a series heading with the universe button Screenshot: a series heading in the Library with the dashed + Aeon 14 button beside it, before the series has joined the universe.

If a pen name has several universes, the … menu on the series heading lets you choose which one. A series can be in one universe at a time, and moving it is as easy as joining it.

A standalone book

A book that isn't in a series can join a universe directly: in the editor, open Book → Details and choose the universe under Imprint. A book in a series always takes the series' universe, so there's nothing to set on the book itself.

When the codex is in the way

Any book can stop reading its codex—say, a book in the series that's really a side story set somewhere else. In Book → Details, untick Reads the codex. It keeps its place in the series; the Codex rail, the underlines, and anything an AI sees through that book go quiet until you tick it again.

When a universe grows

New series join the same way, whenever they're made or later. One universe can hold as many series as the world does, under one pen name. If you write two unrelated worlds under one name, make two universes; if you write one world under two names, that's one universe under one of the names, and it's worth thinking for a moment about which.

Make your first entries

Opening the codex

From the Library, Manage → Codexes, then Open codex beside the universe. You'll land on a page with a search box in the middle and the entry types down the left—Characters, Places, Items, Factions, Rules, Events, Maps, Other, each with a count. The page is search-first on purpose: a codex that has been going for a few books holds hundreds of entries, and the quickest way to one is to type its name.

Screenshot: the codex's opening page Screenshot: the codex's opening page, with the search box in the middle and the entry types down the left (Characters, Places, Items and so on), each with its count.

Click a type and the search box moves up to make room for the list; the box then reads Search in Characters, and the list is everyone of that type, fifty at a time.

Adding an entry

Click + New entry at the top right. A small window asks for one thing—the name—and which type it is. Tanis Richards, Character; the Intrepid, Item; Transcend, Faction. Click Add and the entry opens, ready for everything else. Naming is the only decision you have to make up front.

The entry page

It's laid out like an encyclopedia article: the body in the middle, a box of at-a-glance information on the right, and an Edit button at the top. The page opens in reading mode; click Edit when you want to change something, and Done when you've finished.

Screenshot: an entry page Screenshot: an entry page in reading mode, with the body in the middle, the at-a-glance box on the right showing its rows and Edit links, and the Edit button at the top.

While editing, the top of the page has:

At-a-glance information

The box on the right holds the entry's fields: for a character, things like pronouns, role, born, appearance and status; for a place, where it is and who controls it; and for every type, pictures, an overview and tags. Each row shows the value and an Edit link.

A row with nothing in it offers Add general information—the plain fact, true everywhere and always. Beneath each row there's also Add book, series, or date-specific information, for the version of the fact that's true only in one book or for a while. That's the heart of the codex, and it has a page of its own: What's true when and where.

Some fields are dropdowns, some are tags, some point at other entries (a character's faction, a city's country); the field decides. If a dropdown is missing the choice you want, you can add it right there.

Pictures

Every type has a Pictures field. Pictures come from your media library, and a universe has its own shelf there, so a character portrait or a map is uploaded once and used by every book in the universe. The first picture shows at the top of the at-a-glance box, the way an infobox does.

The body

Below the summary, the body is the long-form description, written in the universe's voice—as much as you like, in paragraphs. Information that differs by book or by time belongs in the fields, not the body, so the body can be the stable account.

Finding it again

Type any part of the name, an alias, or a word from the summary into the search box. Results show the name, the type and the summary; click one to open it.

The codex while you write

The Codex button

In the editor's toolbar, beside Notes, there's Codex. Click it and a rail opens on the right with the heading In this scene: every codex entry whose name or alias appears in the scene you have open, the most-mentioned first, with a small ×count. It updates by itself a moment after each save, so when you type a new character's name into a scene, they appear in the rail without your doing anything.

Click an entry and its card unfolds: the summary, then the at-a-glance information as it stands for this book. If a character's rank is different in book 3, the rail shows the book-3 rank when you're writing book 3. Each card has Open in the codex →, which opens the full entry in a new tab.

Screenshot: the Codex rail in the editor Screenshot: the editor with the Codex rail open on the right under In this scene, listing entries with their ×counts, and one entry's card unfolded to show its summary, its at-a-glance information and the Open in the codex → link.

If the rail says the book isn't in a universe, see Put your series in a universe.

Searching from the rail

The box at the top of the rail searches the whole universe, not just the scene—handy when you need to check a place the scene doesn't name yet. Clear the box and you're back to In this scene.

Adding an entry from the page

Select a name in your prose, then click + New entry at the bottom of the rail. The name is filled in; pick the type and click Add. The entry opens in the codex in a new tab, ready for its summary and details, and the rail picks it up on the next save. If nothing is selected, the search box's text is used instead.

Names underlined in the text

If you'd like the codex visible in the page itself, turn on Codex names under View in the toolbar. Every name the rail knows is in the scene gets a faint dotted underline. It's off by default, since not everyone wants marks in their prose, and the setting is remembered on this browser.

How names are matched

The same rules in the rail and the underlines, so they always agree:

If a name keeps matching things it shouldn't, open the entry and untick Find this name in the text automatically. It leaves the rail and the underlines everywhere in the universe; mentions search still finds it when you ask.

Opening the whole codex from here

Open the codex → at the top of the rail opens the codex in a new tab with Working in already set to this book, so the counts, the search and every entry you open show the world as this book knows it.

Calendars and dates

Why the codex has calendars

Some facts are only true for a while. A captain holds a rank until she's promoted; a city stands until it falls; a character is twelve in one book and forty in the next. To say when a fact applies, the codex needs a way to write dates—and your world may not count years the way ours does. So each universe has at least one calendar, and a fact can say "from here, to there" on it.

If your books are set in the ordinary world, you can leave all of this alone. Every universe starts with a Gregorian calendar, and that's the one you'll be offered.

Where it lives

In the codex, click Setup at the top right. The rail that opens has a Calendar system card. The default calendar is already there, named Gregorian; rename it if your story calls it something else, and there's a table beneath, How other worlds would write theirs, showing how a Star Wars, Star Trek, Tolkien, Dune or Westeros calendar would be set up, in case you'd like to borrow one.

Screenshot: the Calendar system card Screenshot: the codex's Setup rail with the Calendar system card open, showing the default calendar named Gregorian and, beneath it, the table How other worlds would write theirs.

What a calendar needs

Calendar name—what you see. Gregorian, Stellar date, Imperial reckoning.

Dates are written as—how you'll type a date for this calendar. Five ways:

For the three with a month and a day, you can separate the parts with a dot, a slash or a dash—whichever you type is fine.

Before the zero point—if your calendar has dates before its year one, the word that marks them: BCE, BC, BBY, Before Landing. Then "12 BCE" is understood as twelve years before. Leave it empty for a calendar that only counts forward (a stardate, say).

The calendar also has a short key (shown when there's more than one calendar). It's what facts point at behind the scenes and doesn't change once set; the name is yours to change whenever you like.

Writing a date

Wherever the codex asks for a date—a fact's from and to, when an entry exists—type it the way the calendar says. The codex keeps exactly what you typed and shows it back the same way; underneath, it works out an order so it knows that 68 CE comes before 70 CE and 2 BCE before 1 CE. A bare year is always accepted, whatever the calendar's style, so "8927" works on a month.day.year calendar when you don't know the day.

If something can't be read, the box tells you and shows the style the calendar expects. (And yes: historians skipped year zero, and so does the codex—1 BCE is followed by 1 CE.)

A second calendar

Science fiction and fantasy often need two: the world's own reckoning and, thanks to time travel or prequels, the one the readers know. Click Add a second calendar in the Calendar system card, give it a name and a style, and it joins the first. Every fact's when then says which calendar it's on, and an entry can exist on more than one—a character might have a stellar-date birth and a Gregorian one.

One calendar is marked primary: it's the one offered first. Make primary changes which.

Where dates show up

Those three are the subject of What's true when and where.

What's true when and where

The problem a codex solves

In book 1 the ship is called the Intrepid and Tanis is a lieutenant. By book 4 the ship has a new name and Tanis commands it. A spreadsheet gives you one cell per fact and makes you choose. The codex lets a field hold the general answer and the exceptions—by book, by series, or by date—and shows the right one for wherever you happen to be reading from.

General information

Open an entry, click Edit, and look at the at-a-glance box. A row with nothing in it says Add general information. Click it, give the value, and that's the fact that's true everywhere, at every time, unless something more specific says otherwise. For most fields on most entries, this is all you'll ever need.

Book-, series- or date-specific information

Beneath a row there's a link in the accent colour: Add book, series, or date-specific information. Click it and a small form opens with two parts:

Applies to—where this version of the fact holds. A tree of your series, with their books beneath them. Tick a whole series, or one book, or several at once; a tick on each makes one fact per place, so "Tanis is a commander in books 4, 5 and 6" is one visit to this form.

When—optionally, a stretch of time on one of the universe's calendars: from a date, to a date, either end open. Type dates the way the calendar expects (see Calendars and dates). Leave both blank for "whenever."

Screenshot: the book, series, or date-specific information form Screenshot: the Add book, series, or date-specific information form open under an at-a-glance row, showing the Applies to tree of series with their books (a book or two ticked) and the When from and to boxes.

Then the information itself, and Save. The row now shows a small table under the general value: Dates · Series · Book · Information, one line per exception, each with its own Edit.

Which one wins

When the codex is asked "what's true here?", it picks the most specific fact that applies: a fact for this book beats a fact for its series, which beats the general one. Among facts of the same reach, the one that starts latest wins—the newer rank, the newer name. If you've written two that tie, the one you entered most recently wins, and the page shows the others beneath it as overridden, so nothing is hidden from you.

Working in: reading the codex from one place

At the top of the codex's left rail is Working in. It's the lens the whole page looks through:

Reset filters puts it all back. Opening the codex from the editor's rail arrives with Working in set to that book.

Screenshot: the Working in controls Screenshot: the top of the codex's left rail with Working in set to one book, the calendar row beneath it showing Any time, At… and Not on this calendar, and Reset filters.

Working in changes what you see. It doesn't change what you add: when you edit an entry, the forms always ask where a fact applies, so you can't accidentally file a general fact as a book-only one just because of where you were reading from.

View as, on an entry

On an entry's page, when it has information that differs by book, series or date, a row of chips appears under the heading—View as: general, then each book or series with its own version. Click one to see the page as that book sees it, without touching the Working in setting for the rest of the codex.

When an entry exists

Some things don't exist at all for part of the story: a character not yet born, a city not yet founded, a ship not yet built. Each entry has an Exists line in its at-a-glance box—Applies to all dates by default, or a from and to on each calendar it's known on. Give Tanis a stellar-date birth and she stays out of any list framed to a time before it; the Working in date filter is how that shows.

An entry can exist on more than one calendar at once—a stellar-date span and a Gregorian one—and each is edited on its own line.

Your own types and fields

The built-in types are a starting point

Every universe begins with Characters, Places, Items, Factions, Rules, Events, Maps and Other, each with a sensible handful of fields. Many worlds need more: ships, spells, species, clues, deities. The codex lets you add your own types, give any type the fields it needs, and connect entries to one another—a city's country, a character's faction—with the connection visible from both ends. Think of it as building a small relational database by filling in forms, with a wiki page attached to every row.

The Setup rail

In the codex, click Setup at the top right. The main area becomes a rail of your types, one box per type, with its fields inside. Nothing about entries is lost; Back to entries returns you.

Screenshot: the Setup rail Screenshot: the codex's Setup rail, with one box per type and that type's fields listed inside it, and Back to entries visible.

Renaming and hiding types

Each type box has One is called and Several are called—so Faction can be House and Houses, and the whole codex follows, from the left-hand list to the forms. A built-in type you have no use for can be unticked (shown) to hide it; it comes back the same way. Your own types have Remove type instead, which is allowed only while nothing uses them.

Adding a type

At the bottom of the rail, A type called: give the singular and plural, and it appears as a box of its own with the three fields every type has—Pictures, Overview and Tags. Add fields to it as below.

Adding a field

In any type's box, click Add a field and say:

Screenshot: the Add a field form Screenshot: Add a field open in a type's box in the Setup rail, with a Field label typed in and the What the field holds choices showing.

For a list, give The choices, one per line. Choices are strict: only these spellings are accepted, on the page and from any connected AI, which is what keeps a bible from drifting into Admiral, admiral and Adm. More can be added later, from the setup or straight from an entry that needs a new one.

For a connection, say Points at which type—Country points at Places, Faction at Factions—and give the Reverse list name: what the other side calls the list of things pointing at it. A city's Country field with the reverse name Cities means every country's page gains a Cities list, filled in automatically from the cities that name it. Choose another entry for one (a city has one country) or several other entries for many (a character has several affiliations).

The built-in fields already use this: a character's Affiliation shows up on the faction as Members; a place's Within shows on the larger place as Contains.

Changing a field

Click a field in the rail to rename it, change its choices, change its reverse name, or change what it holds. Values already stored keep the shape they were saved in, so a field that goes from a line of text to another entry won't convert its old text into connections—change kinds early, or add a new field and move the information over.

A note on choosing kinds

Find every mention in your books

What Mentions does

Every entry page has a Mentions box. It searches your manuscripts for the entry's name and every alias, and lists each scene where one appears—so you can see every page a character walks through, every time a ship is named, every place a city comes up. It's the fastest way to answer "where did I last describe her?" or "has this town been mentioned since book 2?"

In the Mentions box, Where to look offers your series, with their books beneath. Pick one book, or a whole series to search every book in it in shelf order. The results come back grouped by book and chapter: each scene that mentions the entry, how many times, and the first line around the first mention so you can tell which scene it is without opening it. Scenes without titles are shown as scene 2 of 5 so a chapter with several doesn't look like a list of repeats.

At the top, the first appearance in reading order—often the thing you actually wanted.

Screenshot: the Mentions box with results Screenshot: an entry's Mentions box after a search, with Where to look set to a series, the first appearance at the top, and results grouped by book and chapter, each scene showing its count and the line around the first mention.

Opening a result

Click a result and the book opens in a new tab, on that scene, with the find rail already showing every match for the name. Your codex tab stays where it was.

Aliases

When an entry has aliases, each result shows which names were found and how many times—Tanis ×4 · the Admiral ×1—as small chips. Click a chip to open the scene with the find rail on that name alone, which is how you'd check that every "the Admiral" in book 3 really means her.

How matching works here

Keeping aliases honest

Mentions is also where you'll notice an alias you forgot. If a search for Tanis Richards finds twelve scenes but you know she's in twenty, the other eight probably call her something you haven't listed. Add it to Aliases on the entry and search again.

Notes that become codex entries

Start small

You don't need a codex to keep track of a book. The notes panel in the editor is a perfectly good place for a character sheet, a map of the town, a list of rules you've made up—and notes have two things that make them a small codex of their own.

Tags on notes

Every note has a tag box in its header. Type a tag and press Enter; as you type, the codex's types are suggested—character, place, item, faction, rule, event, map—along with plot and research. A note can carry as many as you like.

Once a few notes have tags, the notes list grows a row of chips with counts. Click character and you see only the characters. It's enough structure for a standalone book, and it costs nothing but the tag.

Screenshot: tagged notes in the notes panel Screenshot: the notes panel in the editor, with a note's tag box in its header and the notes list's row of tag chips with counts.

Ad-hoc connections, briefly

On the codex side, an entry also has Ad-hoc connections: simple links to other entries—rival of, visited by, mentored by—for the relationships that don't need a field of their own. If you find yourself making the same connection on every entry of a type, it's time to add it as a proper field in Setup, which gives it a dropdown and shows it from both sides.

When a note outgrows the book

The day a note wants to be shared across books—the character comes back in the sequel, the town is in three series—turn it into a codex entry. Open the note and click Make this a codex entry in its header. A small window asks for the entry type; the note's title becomes the entry's name, its text becomes the body, and its tags become the entry's tags.

Screenshot: making a note into a codex entry Screenshot: a note open with Make this a codex entry in its header, and the small window that asks for the entry type.

If the book isn't in a universe yet, the same window asks you to Create a universe: give it a name, and the book's series (or the book itself, if it's a standalone) is put in it as part of the same step. You don't have to go and set that up first.

By default the note is archived afterwards, since the entry now holds it; untick Archive the note afterwards if you'd rather keep both. Either way the note keeps a link—Open in the codex → appears in its header—so you can always get from the note to the entry it became.

What carries over, and what doesn't

The title, the text and the tags come across. At-a-glance information—rank, birth date, affiliations—is filled in on the entry afterwards, since a note has no fields to take it from. The note's own history stays with the note.