18-2 Character Codex & References

Characters in your novel, items and monsters in a game's world... the more creative notes pile up, the more you find yourself thinking "wait, what did this character's face look like again?" ObsiKO lets you build a character dictionary (codex) using nothing but note frontmatter, and lets you write dialogue with a face icon just by typing << in the body! 🎭

← Home: ObsiKO 101 · Related: 18-1 E-book & Web Novel Viewer · 18-3 Messenger & Visual Novel Views

1-Minute Summary ⏱️

Add name + type + an image property to a note's frontmatter, and that note becomes one entry in the codex.
The Codex button (⌘⇧K) in the top toolbar shows every character, item, and monster in the vault at a glance, as a card gallery!
Type << in the body and registered names line up for autocomplete → then images → then even alignment. The result renders beautifully as a face-icon chip.
This reference comes alive the same way in 18-1 E-book & Web Novel Viewer and 18-3 Messenger & Visual Novel Views too!

1. Registering a Character — Frontmatter Is the Profile 🪪

Create a note for a character (or item, monster...) and write this in its frontmatter.

---
name: Seoyeon
type: character
portrait: assets/seoyeon-default.png
color: "#e91e63"
---

Property	What it does
`name`	The name used in the codex and autocomplete (uses the note title if omitted). Multiple names allowed — `name: [Jisoo, 지수, JS]` makes the first the primary display name and the rest aliases; a `<<reference>>` written with ANY of them resolves to the same entity!
`type`	Classification — Character · Background · Item · Event · Monster · Skill (English values like `character`/`item`... work too)
`portrait`	Character image(s) — you can register several, for different expressions/outfits
`background`	Background image(s), for notes whose type is Background — multiple allowed
`image`	The representative image for items, events, monsters, skills, etc.
`color`	The name's display color (reflected in editor chips, messenger names, and visual novel names)

💡 An entry with type: background isn't a character — it's a collection of background images. Reference it in the body and it becomes a divider (scene transition); in the messenger view it becomes wallpaper; in the visual novel view it becomes the stage background.

💡 Right-click "Insert Frontmatter" fills in title, type: note, and created (today) by default. note is a value for ordinary documents that the codex doesn't pick up, so to turn a note into a codex entry, use the ▾ button on the type value to switch it to Character, Item, etc. Date properties can be picked straight from a calendar, and today's date is pre-filled.

Editing Frontmatter Is This Easy 🛠️

Lines with an image property (portrait, background, image, cover, etc.) show a "+ Choose Image" button. Click it to search and pick from the vault's image list (filename + gray folder name); the button stays even after a value is already set, so you can keep adding more images.
Drag an image onto a frontmatter line from the sidebar or outside the app, and it drops right in as that property's value instead of being inserted into the body.
For color properties (like color), click the color swatch before the value to bring up a palette and pick right away. Even with an empty value, just click the dotted swatch to get started.
Properties with a fixed set of values, like type or view, let you pick from a list via the ▾ button!

Face Icons and Manual Cropping ✂️

Portraits get cropped into a round face icon in various places, and ObsiKO automatically detects the face and crops so the eyes land in the center. If the detection is off, try clicking the icon in the frontmatter — you can drag, scroll, or use a slider to set the crop yourself, and clicking "Apply to All" applies it to every sibling image in the same folder at once.

2. Calling It Up in the Body — the `<<name:image>>` Reference 🎬

Type << in the body and the magic begins.

A list of names appears (registered name values) → pick one, then
that character's image list shows up (labeled character/background) → pick one, then
it even autocompletes alignment (center (default) · left · right)!

Type ! after the image name and a list of emotion effects (jump, shake, nod) appears — pick one and it flows straight into alignment — like <<Seoyeon:smile.png!jump--|>>. (The effect becomes an animation where the speech bubble/character bounces in Messenger & Visual Novel Views.)

A completed <<Seoyeon:seoyeon-default.png>> renders in the editor like this. - Character: a chip with a round face icon + name (name color from color) — just continue with the dialogue right after it. - Background: a divider with "name · image name" in the middle — perfect as a scene-transition marker!

<<Background:alley-night.png>>
<<Seoyeon:seoyeon-default.png>> Sorry I'm late! Did you wait long?
<<Minjun:minjun-smile.png--|>> Just got here. Let's go in.

The alignment suffix (|-- = left, --| = right) becomes the speech-bubble direction or character position in 18-3 Messenger & Visual Novel Views. Move your cursor over the chip and the original syntax appears so you can edit it right away.

How It Looks in the Viewers 👀

E-book & web novel view (18-1 E-book & Web Novel Viewer): a character reference appears as a face icon + "quoted dialogue" with no name, and a background reference stays as a divider. Music attached on its own plays as background music. 🎵
Messenger & visual novel view: the reference becomes the script itself — see 18-3 Messenger & Visual Novel Views for details!

3. Codex View — a Card Gallery of Your World 🗂️

Click the Codex button in the top toolbar (or ⌘⇧K, or "Codex" in the command palette) and the main screen switches to the codex tab.

Category tabs: All · Character · Background · Item · Event · Monster · Skill — sorted automatically by the frontmatter type.
Custom categories, your way 🗃️: Write a new value like type: faction in a note and a tab with that name is created automatically (though document-classification values like note/wiki are excluded, and only notes with a name or an image property count). Use the ⚙ button at the end of the tab row to show/hide, rename, or reorder categories, and you can even add a new category yourself (once added, it also shows up in the type ▾ picker in frontmatter). Settings are remembered per vault.
Cards: a representative image (in order: image → portrait → background), a name, and a one-line description. Search and sorting (by name/appearance count) are supported too.
Add a new entry: Click the + tile at the end of each category list and a new note pre-filled with frontmatter matching that category is created (portrait: for a character, background: for a background, and so on).
Click the ? button in the top-right for a quick summary of how to use the codex. The category and sort order you were viewing are remembered the next time you open it too!

Click a Card — Detail View 🔎

Image gallery: every registered image, grouped. Each thumbnail lets you ⧉ copy the reference syntax, ↳ insert into the body, and 🔍 open it large in the Reference View panel — all right there!
Where it appears: a list of notes and lines where this name is used as a <<reference>> — click one to jump straight to that line.
Appears together with: chips of other characters who often show up in the same notes — a relationship web at a glance.
If an image file has gone missing, the card and gallery show a broken-image indicator, making cleanup easy too.

🧙 Tip: Ask the AI Agent to "fill in the name/type/portrait frontmatter for every character note," and you can build a codex from an existing manuscript in no time! The agent also knows the <<reference>> syntax, so requests like "turn this novel into a messenger script" work too (18-3 Messenger & Visual Novel Views).

← Previous: E-book & Web Novel Viewer · Home · Next: Messenger & Visual Novel Views →