Dialog chain

When a player talks to an NPC, enters an area, or uses an item, the engine has to figure out which specific line of dialog to show. That resolution isn't a single lookup — it's a four-step chain that starts with an abstract event ID and ends with rendered UTF-16-LE text on screen. Every piece of dialog in the game travels this chain, and understanding it is the key to finding where any given line lives in the ROM.

The chain at a glance

1. Game event — an NPC interaction, area entry, item use, or scripted trigger fires an event ID.
2. Content-ID lookup — a 9-byte record table in arm9.bin (or an overlay) resolves the event's content ID to a numeric ROM file ID.
3. Talkstart resolution — the talkstart file at that file ID maps a (scenario, slot) pair to a specific message file ID using fixed 20-byte records.
4. Message file playback — the message file (a RESO v1.21 variant=1 container) holds the actual dialog: CMD records and UTF-16-LE text. Overlay 157 renders the result on screen.

Steps 2 and 3 are pure indirection — they exist so the engine can route thousands of distinct events to the right file using compact integer tables instead of path strings. The engine never references files by path at runtime; a grep of arm9.bin for path strings like "talkstart", "msg", or "message" returns zero matches. Everything is integer file IDs from the NDS FAT/FNT.

File-ID addressing

The NDS file allocation table (FAT) assigns every file in the ROM a sequential integer ID. The file name table (FNT) maps those IDs to directory paths — but only extraction tools use the FNT. The running game works exclusively with the integer IDs. The dialog-relevant ranges are:

Content-ID lookup tables

The first resolution step converts a content ID (the abstract "I want content X" value) into a file ID. The engine does this by scanning tables of fixed 9-byte records. Each record packs two (key, file_id) pairs:

byte 0      = 0x00
bytes 1..2  = u16 LE key
bytes 3..4  = u16 LE file_id
bytes 5..6  = u16 LE key
bytes 7..8  = u16 LE file_id

Eight such tables exist across the ROM — five baked into arm9.bin and three in overlays:

The biggest table (180 records at arm9 0x7ee5f) covers 14 different top-level folders — dialog, NPC data, scripts, models, and more all route through the same lookup mechanism. A few example entries from that table:

Talkstart files

The 40 talkstart files (data/talkstart/tkstNN.ofs) are the second hop in the chain. They are RESO v1.21 variant=1 containers, and each entry inside one holds a header followed by an array of fixed 20-byte records. Each talkstart file represents a scenario type — greeting, shopping, combat, and so on — and each record within it is a specific slot for that scenario, identifying which character or zone is involved and which message file to load.

Entry header

Each entry begins with a 16-byte header:

Record type bytes

Each 20-byte record has a type byte at offset +0x12 that determines how the rest of the record is interpreted. Three type bytes are classified:

Worked example: tkst20 entry 0

Entry 0 of tkst20.ofs is a verified chain. A selection of its records shows the pattern:

Triggers 5002 through 5035 walk through roughly 36 different message files spaced exactly 32 file IDs apart. This is "play the same scenario but in a different NPC's voice" — one trigger per active speaker for that scenario.

Message files

The message files (data/message/*.ofs) are the terminal node of the chain — where actual dialog text lives. Each is a RESO v1.21 variant=1 container with up to 100 sparse slots. Each slot holds a dialog entry consisting of alternating CMD records (delimited by 0x2400 open / 0x3B00 close) and UTF-16-LE body text.

The body text uses U+0000 as phrase boundaries, a dedicated break marker for page/line breaks within a phrase, and {kanji|reading} notation for furigana. The full byte-level wire format is documented on the wire format page.

Total across the game: 1,328 message containers holding 50,196 dialog entries.

The message folder tree

The data/message/ directory organizes its roughly 1,700 files by category:

Runtime rendering

Once the chain resolves to a message file and a slot within it, overlay 157 (the dialog renderer, always resident during conversations) takes over. The caller passes a bubble_sel byte that determines the rendering mode:

• 0 = WINDOW — a 260 x 138 pixel dialog box at the bottom of the screen, typically three lines of roughly 30 characters each.
• 1--4 = BUBBLE — a 128 x 76 pixel floating bubble above the speaker, two lines maximum, with a practical cap of 32 visible characters per page.

The renderer maintains a 660-byte instance struct per active dialog and runs a 9-state per-frame state machine to handle typewriter animation, color, and layout. The full rendering details are on the bubble vs window page.

Onemsg files

The 12 files in data/onemsg/ are single-shot floating messages — the tooltip text that appears over characters' heads as the player walks past them. These always render as bubbles (32-char page cap) and use the same RESO v1.21 format as regular message files, but are loaded through a separate code path that bypasses talkstart resolution entirely. They enter the renderer with bubble_sel = 4 hardcoded.

Open questions

Three parts of the chain are not yet fully traced:

• The tokenizer function. The exact ARM function that parses the raw 0x2400...0x3B00 byte stream into the 28-byte records the dispatch consumes has not been identified. The strongest candidates are functions reachable from arm9 @ 0x0200ba54.
• Slot selection. A message file can hold up to 100 slots. The logic that selects which slot to play for a given dialog trigger lives in the arm9 scene manager and has not been fully reverse-engineered.
• Additional talkstart type bytes. Only type bytes 0x02, 0x0b, and 0xff are classified. tkst32 alone uses roughly 40 different type bytes whose meanings are unknown.

Related

• Wire format — the byte-level CMD + text encoding inside message files.
• Opcode catalog — all 88 CMD opcodes with hex values and arg layouts.
• Bubble vs window — how ov157 picks the rendering container and the 32-char bubble cap.
• Shared payloads — TOC deduplication within message containers.