jpmschweitzerandClaude Opus 4.6
9cec3df68c
Role namespace (shared pool) stays unchanged; instance namespace (role-slug + seeded counter) added as opt-in for per-instance authored content on auto-generated NPCs. No schema migration needed. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
101 lines
4.3 KiB
Markdown
101 lines
4.3 KiB
Markdown
# 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*
|