# 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.