hyper
ae36125af0
Add rules.md covering document structure, theme/players/time header, icon-first mentions, veteran-first prose, and a closing timestamp. Link it from SKILL.md.
83 lines
2.8 KiB
Markdown
83 lines
2.8 KiB
Markdown
# Writing rules documents
|
||
|
||
A rules document is the markdown printed with `:md-print[./rules.md]` (see
|
||
`reference.md` for the element). It is read *at the table*, so it is written to
|
||
be scanned, not studied. These conventions keep it dense and fast to use.
|
||
|
||
## Document structure
|
||
|
||
Every rules document follows the same five-part skeleton, in order:
|
||
|
||
1. **Briefing** — what the game is and what the players are doing.
|
||
2. **Components** — the pieces in play (cards, tokens, sheets, dice).
|
||
3. **Setup** — how to get from the box to the first turn.
|
||
4. **Game flow** — the loop of play, turn by turn.
|
||
5. **Game end** — how the game finishes and who wins.
|
||
|
||
Use these as `##` headings so a reader can jump straight to the part they need.
|
||
|
||
## Theme, players, and time
|
||
|
||
Open the briefing with one sentence that explains the theme — the fiction the
|
||
players step into — then state the player count range and the time estimate:
|
||
|
||
```markdown
|
||
## Briefing
|
||
|
||
You are rival merchants trading spice across a desert that wants you dead.
|
||
|
||
**2–4 players · 30–45 minutes**
|
||
```
|
||
|
||
## Icon-first mentions
|
||
|
||
When a paragraph mentions a concept for the first time, and that concept has an
|
||
icon under `assets/`, prefix the concept with the icon. The icon becomes a
|
||
visual anchor the reader can find without reading the whole sentence.
|
||
|
||
```markdown
|
||
Spend a :[coin]coin to bribe the :[guard]guard.
|
||
```
|
||
|
||
Write the icon immediately before the word, with no space: `:[coin]coin`, not
|
||
`:[coin] coin`. Only the **first** mention in a paragraph gets the icon; later
|
||
mentions stay plain so the prose does not turn into a wall of icons. See
|
||
`reference.md` for the `:[name]` inline directive.
|
||
|
||
## Veteran-first prose
|
||
|
||
Write the default text for a veteran player who only needs to refresh their
|
||
memory: the rule, the number, the trigger. Assume they already know the game.
|
||
|
||
Everything that is *not* needed to play — edge cases, worked examples, the
|
||
reasoning behind a rule, theme and flavour — is look-up material for new players
|
||
and corner cases. Box it in a GitHub alert so it stays out of the way of the
|
||
main line:
|
||
|
||
```markdown
|
||
A :[shield]shield reduces incoming damage by 2.
|
||
|
||
> [!NOTE]
|
||
> Shields do not stack. A character carrying two shields still reduces damage
|
||
> by 2, and a shield offers no protection against fire.
|
||
```
|
||
|
||
Pick the alert type to signal intent: `[!NOTE]` for clarifications and edge
|
||
cases, `[!TIP]` for advice, `[!IMPORTANT]` for rules that are easy to miss,
|
||
`[!WARNING]` / `[!CAUTION]` for consequences. See `markdown.md` for the alert
|
||
syntax.
|
||
|
||
The test: if a veteran can play correctly from the plain text alone, the split
|
||
is right. If a rule only exists inside an alert, it belongs in the main text.
|
||
|
||
## Rule timestamp
|
||
|
||
End every document with a timestamp, so a printed copy can be checked against
|
||
the current rules:
|
||
|
||
```markdown
|
||
---
|
||
|
||
*2026-10-24*
|
||
```
|