settled-reach/wiki/authoring/line-id-authoring-guide.md

Line ID Authoring Guide

Decision: D-084 (dual-namespace line ID scheme) Resolves: Q-028 (collision-resistant IDs for auto-generated NPCs) Ticket: #544

---

The Short Version

• Role pool lines: Use {role-slug}_d_{###} — e.g., dock-worker_d_001. These lines are shared by all NPCs with that role. This is the default for all auto-generated NPC content.
• Named NPC lines: Use {npc-slug}_d_{###} — e.g., kael-davan_d_001. Unchanged from current practice.
• Instance-specific lines (rare): Use {role-slug}-{counter}_d_{###} — e.g., dock-worker-07_d_001. Only needed when a specific generated NPC needs content different from the role pool.

---

How Line IDs Work

A line ID identifies content, not speaker. The speaker is identified by their StableId in the history log. So dock-worker_d_001 being said by 40 different dock workers is correct: the log records (StableId: 12, dock-worker_d_001), (StableId: 37, dock-worker_d_001), etc. No collision.

This means the role pool approach already handles most cases — the "collision problem" is mainly a concern for the rare case where you want a specific generated NPC to say something different from others of the same role.

---

Namespace Reference

Named NPC lines (Tier 1 and Tier 2 authored NPCs)

Format:  {npc-slug}_{content-type}_{###}
Example: kael-davan_d_001     (Kael's dialogue line 1)
         sera-venn_d_015      (Sera's dialogue line 15)
         pc-smuggler_m_s_001  (Smuggler monologue line 1)

File location: One file per NPC (e.g., dialogue/maintenance-corridors/kael-davan.yaml)

Numbering: Sequential within the file. Gaps are acceptable (deleted lines leave permanent gaps). Never reuse a number.

---

Role pool lines (auto-generated NPCs, Tier 3 flat, Tier 2 mundane)

Format:  {role-slug}_{content-type}_{###}
Example: dock-worker_d_001    (any dock worker, dialogue line 1)
         bar-regular_d_008    (any bar regular, dialogue line 8)
         transit-worker_d_003 (any transit worker, dialogue line 3)

File location: One file per role-at-location (e.g., dialogue/the-terminal/dock-worker.yaml)

These lines are shared by all instances of the role. Write them to suit any dock worker, not a specific one.

---

Instance-specific lines (opt-in, rare)

Use only when the generation system has flagged a specific NPC as needing content that differs from the role pool. Examples: a generated dock worker who is also a triangle member with a specific tell; a generated bar regular who witnessed a specific event.

Format:  {role-slug}-{zero-padded counter}_{content-type}_{###}
Example: dock-worker-07_d_001  (instance 7 of dock-worker role, line 1)
         bar-regular-02_d_005  (instance 2 of bar-regular role, line 5)

The counter (01, 02, ... N) is assigned by the generation system in world-seed-deterministic order. The NPC's generated profile file will tell you which counter to use.

File location: Same directory as the role pool file, separate file with instance slug as name (e.g., dialogue/the-terminal/dock-worker-07.yaml)

---

Quick Decision Guide

Situation	ID format to use
Named authored NPC (Kael, Sera, Voss...)	{npc-slug}_d_{###}
Lines any dock worker can say	dock-worker_d_{###}
Lines any bar regular can say	bar-regular_d_{###}
Generated NPC with specific triangle role	{role-slug}-{counter}_d_{###}
Generated NPC who's just background	{role-slug}_d_{###} — no instance ID needed

---

Schema Compatibility

The existing ID regex ^[a-z][a-z0-9-]*_[dme]_\d{3}$ accepts all three formats. No schema change is required. The content validator (make validate-content) checks for duplicate IDs across all files in a district.

---

Numbering Rules

1. Start at 001, increment by 1 for each new line.
2. Never reuse a number, even if a line is deleted. Gaps are fine.
3. Lines within a single file have a contiguous prefix — dock-worker_d_001 through dock-worker_d_042, etc.
4. Cross-file: kael-davan.yaml at the terminal and kael-davan.yaml at maintenance corridors both use the kael-davan_d_### namespace. Continue numbering from where the other file left off (check the existing files first, use a fresh sequence if the NPC is new to a location).

---

D-084 — authored by Gestalt, Sprint 18