<p>Evennia has an extensive help system covering both command-help and regular free-form help documentation. It supports subtopics and if failing to find a match it will provide suggestsions, first from alternative topics and then by finding mentions of the search term in help entries.</p>
<p>The help system is accessed in-game by use of the <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> command:</p>
<p>Sub-topics are accessed as <codeclass="docutils literal notranslate"><spanclass="pre">help</span><spanclass="pre"><topic>/<subtopic>/...</span></code>.</p>
<h2>Working with three types of help entries<aclass="headerlink"href="#working-with-three-types-of-help-entries"title="Permalink to this headline">¶</a></h2>
<p>There are three ways to generate help entries:</p>
<ulclass="simple">
<li><p>In the database</p></li>
<li><p>As Python modules</p></li>
<li><p>From Command doc strings</p></li>
</ul>
<sectionid="database-stored-help-entries">
<h3>Database-stored help entries<aclass="headerlink"href="#database-stored-help-entries"title="Permalink to this headline">¶</a></h3>
<p>Creating a new help entry from in-game is done with</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>sethelp The Gods;pantheon, Lore = In the beginning all was dark ...
</pre></div>
</div>
<p>This will create a new help entry in the database. Use the <codeclass="docutils literal notranslate"><spanclass="pre">/edit</span></code> switch to open the EvEditor for more convenient in-game writing (but note that devs can also create help entries outside the game using their regular code editor, see below).</p>
<p>The <aclass="reference internal"href="../api/evennia.help.models.html#evennia.help.models.HelpEntry"title="evennia.help.models.HelpEntry"><spanclass="xref myst py py-class">HelpEntry</span></a> stores database help. It is <em>not</em> a Typeclassed entity and can’t be extended using the typeclass mechanism.</p>
<p>Here’s how to create a database-help entry in code:</p>
<h3>File-stored help entries<aclass="headerlink"href="#file-stored-help-entries"title="Permalink to this headline">¶</a></h3>
<divclass="versionadded">
<p><spanclass="versionmodified added">New in version 1.0.</span></p>
</div>
<p>File-help entries are created by the game development team outside of the game. The help entries are defined in normal Python modules (<codeclass="docutils literal notranslate"><spanclass="pre">.py</span></code> file ending) containing a <codeclass="docutils literal notranslate"><spanclass="pre">dict</span></code> to represent each entry. They require a server <codeclass="docutils literal notranslate"><spanclass="pre">reload</span></code> before any changes apply.</p>
<ulclass="simple">
<li><p>Evennia will look through all modules given by
<codeclass="docutils literal notranslate"><spanclass="pre">settings.FILE_HELP_ENTRY_MODULES</span></code>. This should be a list of python-paths for
Evennia to import.</p></li>
<li><p>If this module contains a top-level variable <codeclass="docutils literal notranslate"><spanclass="pre">HELP_ENTRY_DICTS</span></code>, this will be
imported and must be a <codeclass="docutils literal notranslate"><spanclass="pre">list</span></code> of help-entry dicts.</p></li>
<li><p>If no <codeclass="docutils literal notranslate"><spanclass="pre">HELP_ENTRY_DICTS</span></code> list is found, <em>every</em> top-level variable in the
module that is a <codeclass="docutils literal notranslate"><spanclass="pre">dict</span></code> will be read as a help entry. The variable-names will
be ignored in this case.</p></li>
</ul>
<p>If you add multiple modules to be read, same-keyed help entries added later in
the list will override coming before.</p>
<p>Each entry dict must define keys to match that needed by all help entries.
<spanclass="s2">"key"</span><spanclass="p">:</span><spanclass="s2">"The Gods"</span><spanclass="p">,</span><spanclass="c1"># case-insensitive, can be searched by 'gods' too</span>
<p>The help entry text will be dedented and will retain paragraphs. You should try
to keep your strings a reasonable width (it will look better). Just reload the
server and the file-based help entries will be available to view.</p>
</section>
<sectionid="command-help-entries">
<h3>Command-help entries<aclass="headerlink"href="#command-help-entries"title="Permalink to this headline">¶</a></h3>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">__docstring__</span></code> of <aclass="reference internal"href="Commands.html"><spanclass="doc std std-doc">Command classes</span></a> are automatically extracted into a help entry. You set <codeclass="docutils literal notranslate"><spanclass="pre">help_category</span></code> directly on the class.</p>
<p>When you update your code, the command’s help will follow. The idea is that the command docs are easier to maintain and keep up-to-date if the developer can change them at the same time as they do the code.</p>
</section>
<sectionid="locking-help-entries">
<h3>Locking help entries<aclass="headerlink"href="#locking-help-entries"title="Permalink to this headline">¶</a></h3>
<p>The default <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> command gather all available commands and help entries
together so they can be searched or listed. By setting locks on the command/help
entry one can limit who can read help about it.</p>
<ulclass="simple">
<li><p>Commands failing the normal <codeclass="docutils literal notranslate"><spanclass="pre">cmd</span></code>-lock will be removed before even getting
to the help command. In this case the other two lock types below are ignored.</p></li>
<li><p>The <codeclass="docutils literal notranslate"><spanclass="pre">view</span></code> access type determines if the command/help entry should be visible in
the main help index. If not given, it is assumed everyone can view.</p></li>
<li><p>The <codeclass="docutils literal notranslate"><spanclass="pre">read</span></code> access type determines if the command/help entry can be actually read.
If a <codeclass="docutils literal notranslate"><spanclass="pre">read</span></code> lock is given and <codeclass="docutils literal notranslate"><spanclass="pre">view</span></code> is not, the <codeclass="docutils literal notranslate"><spanclass="pre">read</span></code>-lock is assumed to
apply to <codeclass="docutils literal notranslate"><spanclass="pre">view</span></code>-access as well (so if you can’t read the help entry it will
also not show up in the index). If <codeclass="docutils literal notranslate"><spanclass="pre">read</span></code>-lock is not given, it’s assume
everyone can read the help entry.</p></li>
</ul>
<p>For Commands you set the help-related locks the same way you would any lock:</p>
<p>Db-help entries and File-Help entries work the same way (except the <codeclass="docutils literal notranslate"><spanclass="pre">cmd</span></code>-type
<h3>Customizing the look of the help system<aclass="headerlink"href="#customizing-the-look-of-the-help-system"title="Permalink to this headline">¶</a></h3>
<p>This is done almost exclusively by overriding the <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> command <aclass="reference internal"href="../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdHelp"title="evennia.commands.default.help.CmdHelp"><spanclass="xref myst py py-class">evennia.commands.default.help.CmdHelp</span></a>.</p>
<p>Since the available commands may vary from moment to moment, <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> is responsible for collating the three sources of help-entries (commands/db/file) together and search through them on the fly. It also does all the formatting of the output.</p>
<p>To make it easier to tweak the look, the parts of the code that changes the visual presentation and entity searching has been broken out into separate methods on the command class. Override these in your version of <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> to change the display or tweak as you please. See the api link above for details.</p>
</section>
</section>
<sectionid="subtopics">
<h2>Subtopics<aclass="headerlink"href="#subtopics"title="Permalink to this headline">¶</a></h2>
<divclass="versionadded">
<p><spanclass="versionmodified added">New in version 1.0.</span></p>
</div>
<p>Rather than making a very long help entry, the <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> may also be broken up into <em>subtopics</em>. A list of the next level of subtopics are shown below the main help text and allows the user to read more about some particular detail that wouldn’t fit in the main text.</p>
<p>Subtopics use a markup slightly similar to markdown headings. The top level heading must be named <codeclass="docutils literal notranslate"><spanclass="pre">#</span><spanclass="pre">subtopics</span></code> (non case-sensitive) and the following headers must be sub-headings to this (so <codeclass="docutils literal notranslate"><spanclass="pre">##</span><spanclass="pre">subtopic</span><spanclass="pre">name</span></code> etc). All headings are non-case sensitive (the help command will format them). The topics can be nested at most to a depth of 5 (which is probably too many levels already). The parser uses fuzzy matching to find the subtopic, so one does not have to type it all out exactly.</p>
<p>Below is an example of a <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> with sub topics.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span>The theatre is the heart of the city, here you can find ...
(This is the main help text, what you get with `help theatre`)
# subtopics
## lore
The theatre holds many mysterious things...
(`help theatre/lore`)
### the grand opening
The grand opening is the name for a mysterious event where ghosts appeared ...
(`this is a subsub-topic to lore, accessible as `help theatre/lore/grand` or
any other partial match).
### the Phantom
Deep under the theatre, rumors has it a monster hides ...
(another subsubtopic, accessible as `help theatre/lore/phantom`)
## layout
The theatre is a two-story building situated at ...
(`help theatre/layout`)
## dramatis personae
There are many interesting people prowling the halls of the theatre ...
(`help theatre/dramatis` or `help theathre/drama` or `help theatre/personae` would work)
### Primadonna Ada
Everyone knows the primadonna! She is ...
(A subtopic under dramatis personae, accessible as `help theatre/drama/ada` etc)
### The gatekeeper
He always keeps an eye on the door and ...
(`help theatre/drama/gate`)
</pre></div>
</div>
</section>
<sectionid="technical-notes">
<h2>Technical notes<aclass="headerlink"href="#technical-notes"title="Permalink to this headline">¶</a></h2>
<sectionid="help-entry-clashes">
<h3>Help-entry clashes<aclass="headerlink"href="#help-entry-clashes"title="Permalink to this headline">¶</a></h3>
<p>Should you have clashing help-entries (of the same name) between the three types of available entries, the priority is</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">sethelp</span></code> command (which only deals with creating db-based help entries) will warn you if a new help entry might shadow/be shadowed by a same/similar-named command or file-based help entry.</p>
</section>
<sectionid="the-help-entry-container">
<h3>The Help Entry container<aclass="headerlink"href="#the-help-entry-container"title="Permalink to this headline">¶</a></h3>
<p>All help entries (no matter the source) are parsed into an object with the following properties:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> - This is the main topic-name. For Commands, this is literally the command’s <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">aliases</span></code> - Alternate names for the help entry. This can be useful if the main name is hard to remember.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">help_category</span></code> - The general grouping of the entry. This is optional. If not given it will use the default category given by <codeclass="docutils literal notranslate"><spanclass="pre">settings.COMMAND_DEFAULT_HELP_CATEGORY</span></code> for Commands and
<codeclass="docutils literal notranslate"><spanclass="pre">settings.DEFAULT_HELP_CATEGORY</span></code> for file+db help entries.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">locks</span></code> - Lock string (for commands) or LockHandler (all help entries). This defines who may read this entry. See the next section.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">tags</span></code> - This is not used by default, but could be used to further organize help entries.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> - The actual help entry text. This will be dedented and stripped of extra space at beginning and end.</p></li>
</ul>
</section>
<sectionid="help-pagination">
<h3>Help pagination<aclass="headerlink"href="#help-pagination"title="Permalink to this headline">¶</a></h3>
<p>A <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> that scrolls off the screen will automatically be paginated by the <aclass="reference internal"href="EvMore.html"><spanclass="doc std std-doc">EvMore</span></a> pager (you can control this with <codeclass="docutils literal notranslate"><spanclass="pre">settings.HELP_MORE_ENABLED=False</span></code>). If you use EvMore and want to control exactly where the pager should break the page, mark the break with the control character <codeclass="docutils literal notranslate"><spanclass="pre">\f</span></code>.</p>
</section>
<sectionid="search-engine">
<h3>Search engine<aclass="headerlink"href="#search-engine"title="Permalink to this headline">¶</a></h3>
<p>Since it needs to search so different types of data, the help system has to collect all possibilities in memory before searching through the entire set. It uses the <aclass="reference external"href="https://github.com/yeraydiazdiaz/lunr.py">Lunr</a> search engine to search through the main bulk of help entries. Lunr is a mature engine used for web-pages and produces much more sensible results than previous solutions.</p>
<p>Once the main entry has been found, subtopics are then searched with simple <codeclass="docutils literal notranslate"><spanclass="pre">==</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">startswith</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">in</span></code> matching (there are so relatively few of them at that point).</p>
<divclass="versionchanged">
<p><spanclass="versionmodified changed">Changed in version 1.0: </span>Replaced the old bag-of-words algorithm with lunr package.</p>
