lennartandClaude Opus 5
f1fadf7909
Dialogue was already plain text, so the gap was never the .yarn files. It was
that the character material a writing session needs was either missing or stored
somewhere a writer could not comfortably work.
Three things were wrong. The writing handbook was not in the repo and was cited
by SC101.yarn as though it were. The best voice material — register, verbal tics,
success/failure/passive samples — was a \n-escaped string inside a JSON field.
The named NPCs had no sheets at all, existing only as their Yarn lines.
writing/ now holds the dialogue-facing layer, at the repo root so it gets no
.meta files and is not a Unity asset:
STYLE.md register, the five tone moves, the ban list, branching
shapes, the Wrong Truth rule, flag families, candidate rules
YARN-PRIMER.md the one page of syntax needed to write a scene
GLOSSARY.md in-world and project vocabulary
voices/ the eleven skill voices, one readable sheet each
characters/ Bartender, Chevalier Cassian Thal, Bradford Kane
scenes/ SC-101's brief: intent, beats, checks, constraints
lore/ the three identity readings and the rules that bind them
STYLE.md is a digest of the Mystery Writing Handbook in the Obsidian vault, with
pointers rather than copies. The vault stays the authoring home for design work,
and Ground Truth — the solution document — deliberately stays out of this repo.
The voice sheets are generated from skill_bible.json but are the source of truth
for the prose. tools/writing/sync_voices.py folds edits back; voicelib.py
guarantees notes -> dict -> notes is identity for all eleven, so --to-json on
unchanged sheets is byte-identical. VoiceSheetSyncTests fails the build on drift
in either direction, and was verified to fail on real drift rather than merely
to pass.
SC101.yarn's header is trimmed from prose rationale to the six rules that bind
while editing that file, with the reasoning moved to the scene brief.
EditMode 42/42. YarnCheck compiles 9 files / 35 nodes.
Co-Authored-By: Claude Opus 5 <[email protected]>
4.4 KiB
Writing — start here
This directory is the writing surface for Nightclub Arcadia. Everything a session needs
to write or revise dialogue lives here or in Assets/Dialogue/. You should not need to open
Unity, edit C#, or touch a .asset file to write a scene, a character, or a branch. If a
writing task seems to require any of those, that is a pipeline bug — say so rather than
working around it.
Read in this order
| # | File | What it gives you |
|---|---|---|
| 1 | STYLE.md |
The register, the five tone moves, the ban list, the rules that govern branching. Re-read before every session. |
| 2 | YARN-PRIMER.md |
The one page of Yarn syntax you actually need. |
| 3 | voices/ |
The eleven skill voices, one sheet each. Who they are and how they talk. |
| 4 | characters/ |
The named NPCs. |
| 5 | scenes/ |
Per-scene briefs — intent, beats, constraints. Not the dialogue. |
| 6 | GLOSSARY.md |
In-world terms, and where the deep lore lives. |
Where the words actually go
Playable dialogue lives in NightclubArcadia/Assets/Dialogue/, not here:
Assets/Dialogue/
├── Common.yarn every <<declare>>, project-wide. Never played. Add new flags here.
├── Commentary.yarn passive skill barks, one node per (context, voice)
├── Scenes/ SC101, SC102, Debug
├── Characters/ Bartender, Bradford Kane, Chevalier Cassian Thal
└── Objects/ Chair
A new .yarn file anywhere under Assets/Dialogue/ is picked up automatically — the Yarn
project globs **/*.yarn. Adding a scene or a character needs no registration step.
This directory holds the context; Assets/Dialogue/ holds the content. Keep it that way:
never paste dialogue into a sheet here, and never paste a character bio into a .yarn file.
Check your work before handing it back
From the repo root:
cd tools/YarnCheck && dotnet run -- ../../NightclubArcadia/Assets/Dialogue
That compiles every Yarn file and reports errors with line numbers. It needs only the .NET 9 SDK — no Unity, no licence, no Editor. Run it after any dialogue change.
You can also play a node from the terminal, choosing options by number:
dotnet run -- ../../NightclubArcadia/Assets/Dialogue Bartender_Talk 2 2 0 0
Leftover picks restart the node, which models the player walking away and coming back.
One thing that will confuse you. YarnCheck stubs the engine's commands, so
<<check>>never runs and$check_resultis alwaysfalse. Every check-gated branch will show you its failure side. That is the harness, not a bug in your writing. To read the success prose, read the file.
If you edited a voice sheet in voices/, also run:
python3 tools/writing/sync_voices.py --check
What is yours, and what is not
Yours — edit freely: everything in writing/, every .yarn file, the <<declare>> lines
in Common.yarn, and the prose fields of Assets/Candidates/candidates.json.
Not yours — ask an engineer: any .cs file, anything under Assets/Editor/, any
.asset / .prefab / .unity / .meta file, and ProjectSettings/. The implementations
of Yarn commands are code; using them is writing.
The deeper design material
The full design documents live in Obsidian, not in this repo, and remain the authoring home for design work:
~/Obsidian-Vaults/obsidian-vault/Projects/Active/NightclubArcadia/
[[Mystery Writing Handbook]]— the full reference.STYLE.mdis a dialogue-facing digest of it.[[Skill System Draft]]— the Skill Bible.voices/is generated from the shipped subset.[[Candidate System — Design Explanation]]— the three identity readings.[[Lorebook]],[[Timeline notes]],[[Divergence Point Analysis]]— world and history.[[Character Sheet Handbook]]— the full character schema.characters/_TEMPLATE.mdis its dialogue-facing subset.
[[Ground Truth]]is the solution document. Do not copy it, quote it, or summarise it into this repo — not into a sheet, not into a comment, not into a commit message. The game's central premise is that the protagonist's identity never resolves; a copy of the answer sitting in a git history is how that leaks. If you need to know whether something contradicts the solution, ask, and keep the answer out of the files.