Writing GM Instructions
The rules are files. gm_instructions files are what the GM actually follows during play, and changing them changes the game more directly than any schema edit.
The keyed, modular scheme
Every instruction carries a key in its name — [ID: CMBT], [ID: FLOOR], [ID: NARR-BYTE] — and instructions reference each other by that key. The key is stable; the title after it is not.
The set is deliberately shaped like an index plus depth:
[ID: CORE]is about twenty lines. It states the loop and points everywhere else. It is the only instruction that is pinned, meaning it is always in the GM's context.- Everything else is searchable and pulled in when relevant.
[ID: NARR]and[ID: CHAR]sit at partial, so the GM knows they exist without carrying their bodies.
This is progressive disclosure, and it is not decoration. One short pinned index plus deep files fetched on demand beats six pinned chapters crowding the context window until the GM starts forgetting the ones it needs.
The current set
| Key | Covers |
|---|---|
CORE | the loop, and where every rule lives |
RUN | the ordered start of a run: seed word, floor selection, resets |
FLOOR | floors are pre-built; never generate or rearrange one |
MOVE | advancing between rooms |
ROOM | resolving a room on arrival |
DESC | taking the stair to the next floor, and finishing a run |
CMBT | initiative, attacks, damage, death |
EVNT | running any room event, whatever it is |
LOOT | treasure, inventory, the four slots |
CHAR | which character fields are writable |
MAP | why the GM never touches map data |
TOKN | the one token the GM may move |
NARR | voice and the spoiler rule |
NARR-BYTE | hard length limits |
DARK | register — materials, the one wrong thing, the banned vocabulary |
TRG-MOVE, TRG-HP, TRG-LOOT | triggered rules |
The three narration files are deliberately separate because they fail differently. NARR governs what may be said, NARR-BYTE governs how much, and DARK governs what kind. Collapsing them into one voice document was tried; the length caps got lost inside the prose about atmosphere, which is exactly the failure the caps exist to prevent.
Triggers
Two instructions are triggered rather than always-on. TRG-MOVE fires after each player message to catch movement; TRG-HP fires whenever a character file is updated, to check for death.
Triggered instructions are capped at 500 characters of body. Write them as directives that point at the real rule, never as documents.
Set them with craft meta set-gm-trigger, and verify with craft meta get — trigger metadata is app-managed and does not travel in the file.
Visibility does not travel
This one costs people time. contextVisibility is app-managed. Files pushed by the CLI land as searchable regardless of what you intended, and there is no workspace field that changes it.
So after adding an instruction that needs to be standing context, set its visibility in the app by hand. A core-rules file that nobody pinned is not actually being followed.
Writing them well
Three things separate an instruction the GM follows from one it drifts past:
State the failure, not just the rule. "Never write a field beginning with _" is a rule. Adding "your write is stripped silently, no error is raised, and you will believe you recorded something you did not" is what makes it stick.
Show the bad case next to the good one. [ID: NARR-BYTE] puts a 54-word paragraph beside its 24-word replacement. That does more than any amount of description of the house style.
Say why, briefly, when the rule looks arbitrary. The GM follows a strange rule more reliably when it knows what breaks otherwise — and so will the next person who edits the file.
Test by executing
The fastest way to find a broken instruction is to follow it yourself, literally, and build what it tells you to build. Two real defects in [ID: FLOOR] surfaced that way: a deck construction that produced five identical rooms in a row, and a terminal room with no rule for which tile it should use. Both read fine until someone actually did what they said.