lennart/nightclub-arcadia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add a writer-facing content pipeline under writing/

Browse Source 
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]>
This commit is contained in:
lennart
2026-08-25 20:23:42 +02:00
co-authored by Claude Opus 5
parent b915ad78c7
commit f1fadf7909
28 changed files with 2766 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
writing/README.md
+96
View File
@@ -0,0 +1,96 @@
# 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`](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`](YARN-PRIMER.md) | The one page of Yarn syntax you actually need. |
| 3 | [`voices/`](voices/) | The eleven skill voices, one sheet each. Who they are and how they talk. |
| 4 | [`characters/`](characters/) | The named NPCs. |
| 5 | [`scenes/`](scenes/) | Per-scene briefs — intent, beats, constraints. Not the dialogue. |
| 6 | [`GLOSSARY.md`](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:
```bash
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:
```bash
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_result` is always `false`. **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:
```bash
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.md` is 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.md` is 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.