Handbooks
A project can carry two books. The Player's Handbook teaches people how to play: how the rules work at the table, how to make a character, what a session feels like. The Builder's Manual teaches creators how to build on the project: how its file types fit together, what makes a new entry fit, what the design is trying to do. Each book is a list of chapters written in Markdown, and they are read by people, not by the GM.
How it is used
- Players read the Player's Handbook. It sits on the project's public page, and in a game a button opens it at any time, so players can look a rule up mid-scene. A game shows the handbook from the version of the world it is on.
- Builders read the Builder's Manual. It sits on the project's public page next to the handbook. Someone who copies your project gets both books with it, and the manual is how they learn to add to your work without breaking it.
- The GM doesn't read either book. Rules the GM must follow in play go in GM instructions, the file types and the scripts. A rule written only in the handbook is a rule the GM never sees.
- Orbit can read and write both books in the project, but not from inside a game, so in a game it answers rules questions from the game's GM Instructions and files (see your game).
- Publishing freezes the books. Your edits change your working copy. The public page and games keep the books from the release they show until you publish a new version (see publishing). A game that pulls the new version gets the new books. Before a world's first version, games read the live books.
- A First Steps item can open a book, at its start or at one chapter. See First Steps.
- Mentions survive copies. A mention stores the file's fixed reference id, which a copied project keeps, so links in a copied book still open the right files.
Both books are optional, and a project can have one without the other. An empty book is the same as no book: nothing shows for it.
Changing a handbook
Where the books are: the Player's Handbook and the Builder's Manual on the project's home page. To see what a book already has, open the book and look at its chapter list. Edit one chapter at a time and leave the others alone.
Open the book from the project's home page and click Edit. A book with no chapters yet opens straight in the editor. Add, retitle, move and delete chapters, then click Save manual. Saving with no chapters deletes the book.
What goes in which book
The two books are not a long and a short version of each other. They answer different questions for different people.
- Player's Handbook: how do I play this? Write to a player sizing the game up or learning it: "you", present tense. How a scene runs, how a roll works, how to make a character, what the world expects of them.
- Builder's Manual: how do I add to this without breaking it? Write to a fellow creator who copied your project. State the intent and the constraints: why a file type is shaped the way it is, what a good new entry has, which values are balanced against each other, how to move the whole thing to another setting.
- A rule both need goes in the Player's Handbook. The Builder's Manual says how to extend it, without pasting the rule again.
Some material belongs in neither book:
- The pitch. The tagline and the hook a stranger reads before clicking belong on the project page (its headline, description and author's notes; see the project). A handbook that opens by selling itself wastes its first chapter.
- Secrets and GM rulings. The twist, how the GM should judge or escalate, what players shouldn't know: that goes in GM instructions. The books are public. Assume every player reads every chapter.
- A list of fields. Players and builders can already see each file type's fields. The Builder's Manual explains why they are there and how to fill them well, not what they are.
Writing a chapter
A chapter is a title and a Markdown body. The book shows the title, so
the body starts with its first paragraph, not a # heading.
You need three things before the first scene: a calling, a debt, and a
name you would answer to on a bad night.
## Pick a calling
Your calling is what people call you when they need something.
| Calling | Opens with | Struggles with |
| --- | --- | --- |
| Courier | Doors, roads, rumors | Standing still |
| Assessor | Ledgers, lies | Being liked |
## Take a debt
Nobody in Ashfall starts even.
- One job per chapter, titled the way a reader would ask for it ("Making a Character", not "Character Creation Rules v2").
- Chapter 1 answers "what is this, and what do I do first?" A reader lands there with nothing else to go on.
- A chapter for each thing to explain, no more. A small game's book is two to four chapters; a big one rarely needs more than twelve. Thirty one-page chapters make a wiki nobody reads. Aim for 400 to 1,500 words a chapter, and don't pad to reach a count.
- Every rule is the world's. Each rule sentence matches the GM instructions, a type or a script. Advice ("work together") reads as advice, and the book never promises what the world doesn't have (a creation flow it lacks). Before saying the book matches the rules, check each rule sentence against them, and name anything you added.
##for sections,###sparingly.- Tables and lists for what is looked up (moves, costs, results). Prose for what is absorbed (how a scene flows, what the world believes). Most chapters need both.
- Each chapter has a short id that links to it use, such as
making-a-character. Keep it when you rewrite or retitle the chapter. The app's editor makes the id from the title the first time a chapter is saved, and keeps it after that.
Mentioning files
A mention links a file from the text. It shows as the file's current name
and opens the file when clicked, so point at a real file instead of
naming it in plain words. To mention a file, type @ in the chapter editor and pick the file:
The exiles hold the north bank; <@0198f4b2-6c31-7a5e-9d40-1f2b3c4d5e6f>
speaks for them.
- Mentions in a book use the file's reference id, not its slug. A mention that matches no file shows as "@Missing file" in the middle of the sentence.
- The mention shows the file's name, so write the sentence so it still reads if the file is renamed.
- Mention a file the first time a chapter leans on it, then use plain words. A paragraph of links reads like a link farm.
- In a game, a mention opens the game's own copy of the file.
Pictures
To add a picture, click Insert image in the editor's toolbar, or Insert image row to pick several. In the Markdown it is
, and how you place it decides how it shows:
- One image alone in a paragraph becomes a full-width figure.
- Several images in one paragraph, on one line separated by spaces, become a row of pictures at the same height.
- An image inside a sentence shows small, inline. That is rarely what you want.
 
Use pictures Craft already hosts: ones uploaded or generated in Craft, or taken from a file's picture.
Doing it well
- Read the world first. Read the file types, the key files and the GM instructions before you write. A handbook that contradicts how the game actually plays is worse than none. To check a handbook against the GM instructions and the files, see lore against itself.
- Write like the world's own rulebook. Name a faction, quote a ruling, show a roll. No talk about the project, the app or the AI that helped write it. If a sentence would survive being printed in a book someone paid for, it belongs.
- Teach what the game does. If the handbook says a roll works one way, the GM instructions and the scripts must make it work that way. Change both together.
- Keep the books current. When a rule or a file type changes, update the chapter that explains it in the same piece of work.
- Publish to share. Once a world has a version, players and games see the books only from a version that has them; before the first one, test games read the live books.
Mistakes
- Rules only the handbook has. The GM never reads it, so play won't follow them.
- Secrets in the handbook. Every player can read it.
- Rebuilding a whole book to change one chapter. Chapters you didn't mean to touch get lost or reverted.
- A new id for a rewritten chapter. That adds a second chapter, and links to the old id stop working.
- The title repeated as a
#heading at the top of the body. It shows twice. - A made-up reference id or image URL. It shows as "@Missing file" or a broken picture.
- Expecting players to see edits right away. Games and the public page show the published books.
Reference
A book:
| Field | Type | Limit | What it holds |
|---|---|---|---|
version |
1 | The format's version. Always 1. | |
updatedAt |
string | at most 40 characters | When the book's chapters last changed. Craft sets it; anything written here is replaced. |
chapters |
chapter[] | at most 50 chapters | The chapters, in reading order. |
A chapter:
| Field | Type | Limit | What it holds |
|---|---|---|---|
id |
string | at most 64 characters | The chapter's stable name. It addresses the chapter and appears in links to it, so keep it when the chapter is rewritten or retitled. |
title |
string | at most 120 characters | The chapter's title, shown in the chapter list and above it. |
content |
string | at most 100,000 characters | The chapter's text, in Markdown, without the title as a heading. It may mention files by their reference ids. |
Limits per book: 50 chapters, a title of up to 120 characters, a chapter id of up to 64 characters and up to 100,000 characters of text per chapter. A book with no chapters is no book.