How players find out how your world works.
Players type help. What comes back is drawn from two places, and
knowing which is which saves you a lot of writing:
| Source | Covers | Who writes it |
|---|---|---|
| Verb docstrings | Commands. | Nobody, separately — the comment at the top of a verb is its help. |
The topic library on #54 | Everything that is not a command: your world's rules, its history, how combat works, what a newcomer should do first. | You, as editable prose. |
That split is the good part. A command can never drift out of date, because its help is the same text the person who wrote it read. And prose about your world lives as data you can rewrite while the game runs, without touching code.
help looks for
Typing help on its own prints an index. Typing
help <word> tries three things in order and stops at the first
hit:
#54.> help look
look
Look at your surroundings or examine something in the room.
Usage: look [object]
Because topics are checked first, a topic named look would hide the
look command's help. Give topics names that are not command names.
A topic is a property on #54. The property name is the word players
type. Create it with @adprop:
> @adprop #54.rules = "Be excellent to each other. No harassment, no cheating."
Property 'rules' added to #54:help_utils = 'Be excellent to each other...'
> help rules
rules
Be excellent to each other. No harassment, no cheating.
To revise it later, @set — which changes a property that already
exists, where @adprop creates one:
> @set #54.rules = "Be excellent. No cheating. No spoilers in public channels."Keep the name a single lowercase word, since it is exactly what a player has to type. The starter world ships with no topics at all — the library is yours to fill.
A topic whose value is a dictionary becomes a category: an index of sub-topics, each reachable on its own.
> @adprop #54.magic = {'spells': 'Casting consumes mana.', 'mana': 'Mana regenerates while resting.'}> help magic
magic
mana, spells
> help spells
magic > spells
Casting consumes mana.Only the category name appears in the main index, so categories are how you keep that index short while still letting people reach every piece directly.
Staff at gm3 and above can attach an explanation to any object with
a help_text property, and read it back with help # and
the number. Players cannot — to them the command does not exist.
> @adprop #202.help_text = "A brass model of the heavens. Turn the crank to advance it."
> help #202
#202 (an orrery)
A brass model of the heavens. Turn the crank to advance it.
This is for the things a builder needs reminding about six months later: a
machine with an odd trigger, a fixture other people will have to maintain.
help #202.pull reads a specific verb's help, but only for a verb
defined on that object — inherited commands are not found this way.
The index lists every command in reach, and
exception verbs are commands as far
as it is concerned. Anything not hidden shows up there.
Create hooks with @adverb/hidden and your help index stays
readable — the starter world hides all of its own, which is why its
index lists only commands a player can actually type.