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

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

1. A list of names appears (registered name values) → pick one, then
2. that character's image list shows up (labeled character/background) → pick one, then
3. 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.

4. Stuck for a character? — the Random Box "Character" tab 🎲

The first tab of Random Box in the right sidebar rolls a whole character for you — instantly, with no AI.

• Pick a setting (modern · fantasy · wuxia · sci-fi), gender, age bracket and name style, hit [Roll], and you get name, birthday, star sign, birthstone, birth flower, epithet, role, look, speech habit, quirk, keepsake, MBTI, Enneagram, sore spot and small secret, all at once.
• The three that follow the birthday (star sign, birthstone, birth flower) can't be rolled on their own — they're indented and marked ↳. Re-roll the birthday and all three change with it (March 21 → Aries · Aquamarine · Daffodil).
• Don't like one line? Use its 🎲 to re-roll just that line. Re-rolling the name also changes the age (name flavour is tied to the age bracket).
• [Insert at cursor] drops a side-character sheet block into your note (one ⌘Z undoes it); [Create as note] turns the character into its own note — the title is the name and the frontmatter (type: character, name, age, gender, job) is filled in, so it shows up in this codex's character tab right away.
• Pools are kept separate per setting — wuxia gives you a "tavern waiter" or "courier-agency escort", sci-fi a "cryosleep attendant" — and modern names match the age bracket.
• Choose "child" and the job, secret and sore-spot pools switch to child-appropriate ones (no epithet is attached at all). Names and speech habits are written fresh for English and Japanese rather than translated.
• Name style lets you pick the flavour: Korean / Japanese / Chinese / Anglo for modern, Nordic / Elven / Latin for fantasy, and code names (Echo-7, NX-402) for sci-fi. Wuxia has only one style, so the selector is hidden there.
• Ask the AI and it draws from the same pools — "make me a wuxia swordswoman" and it rolls right here. Anything you already said is kept ("name her Baek Seo-rin" → the app holds that name and rolls only the empty slots). What it rolls is a draft, so the AI reworks it to fit your story.
• Once the sheet is written, try "AI roleplay as this character" in Writing Helper to talk to them directly.
• The Random Box also has Place · Dice · Wheel tabs → Random Box

Roll their ability scores too 📊

• Right below the character roller there's an ability-score panel. Set the stats (STR / DEX / CON / INT / CHA by default) and a point total, then hit 🎲 Distribute to split them at random.
• The result is drawn as a radar chart (with three or more stats). The highest stat touches the outer ring, so you can read at a glance which way the character leans.
• Rename a stat in place, add more with ＋ (up to ten) and remove one with ✕. Changing the stats clears the previous roll.
• The numbers always add up to exactly the total, and every stat gets at least 1 point (the only exception is a total smaller than the number of stats).
• Swap in a whole set of stats with a format preset 📋 — the dropdown offers game/web-novel stats, fantasy-RPG six abilities, a point-buy generic set, gothic-horror nine attributes, wuxia, modern/narrative and sci-fi, each with its conventional point total. Save your own arrangement with [Save preset] (named, up to 20) and pull it from "My presets" at the top of the dropdown.
• ＋ State column — everyday and awakened, side by side 📊: keep up to four situational stat sets next to each other, each with its own point total. One roll splits every state by its own total, and the 🎲 on a column header re-rolls just that state.
• The radar chart overlays each state in its own colour, and the numbers beside the axes, the legend underneath and the list values all match that colour, so you can tell at a glance which value belongs to which state. Inserting gives you - STR: everyday 12 · awakened 20 lines to match.
• [Insert at cursor] drops in the radar chart first, then the - STR: 24 value lines. The chart is a live chart block, not an image file — edit a number and the drawing follows, and it renders in exports, mind-map cards and the reference pane too. The value lines match the character-sheet format, so they show up in this codex's detail view.

🧙 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 →