mirror of
https://github.com/evennia/evennia.git
synced 2026-03-16 21:06:30 +01:00
475 lines
31 KiB
HTML
475 lines
31 KiB
HTML
|
<!DOCTYPE html>
|
|||
|
|
|
|||
|
|
<html lang="en" data-content_root="../">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
|||
|
|
|
|||
|
|
<title>Help System — Evennia latest documentation</title>
|
|||
|
|
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
|
|||
|
|
<link rel="stylesheet" type="text/css" href="../_static/nature.css?v=279e0f84" />
|
|||
|
|
<link rel="stylesheet" type="text/css" href="../_static/custom.css?v=e4a91a55" />
|
|||
|
|
<script src="../_static/documentation_options.js?v=c6e86fd7"></script>
|
|||
|
|
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
|||
|
|
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
|||
|
|
<link rel="icon" href="../_static/favicon.ico"/>
|
|||
|
|
<link rel="index" title="Index" href="../genindex.html" />
|
|||
|
|
<link rel="search" title="Search" href="../search.html" />
|
|||
|
|
<link rel="next" title="Permissions" href="Permissions.html" />
|
|||
|
|
<link rel="prev" title="Spawner and Prototypes" href="Prototypes.html" />
|
|||
|
|
</head><body>
|
|||
|
|
<div class="related" role="navigation" aria-label="Related">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
accesskey="I">index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="Permissions.html" title="Permissions"
|
|||
|
|
accesskey="N">next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="Prototypes.html" title="Spawner and Prototypes"
|
|||
|
|
accesskey="P">previous</a> |</li>
|
|||
|
|
<li class="nav-item nav-item-0"><a href="../index.html">Evennia</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-1"><a href="Components-Overview.html" accesskey="U">Core Components</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-this"><a href="">Help System</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="document">
|
|||
|
|
<div class="documentwrapper">
|
|||
|
|
<div class="bodywrapper">
|
|||
|
|
<div class="body" role="main">
|
|||
|
|
|
|||
|
|
<section class="tex2jax_ignore mathjax_ignore" id="help-system">
|
|||
|
|
<h1>Help System<a class="headerlink" href="#help-system" title="Link to this heading">¶</a></h1>
|
|||
|
|
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>><span class="w"> </span><span class="nb">help</span><span class="w"> </span>theatre
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>------------------------------------------------------------------------------
|
|||
|
|
Help<span class="w"> </span><span class="k">for</span><span class="w"> </span>The<span class="w"> </span>theatre<span class="w"> </span><span class="o">(</span>aliases:<span class="w"> </span>the<span class="w"> </span>hub,<span class="w"> </span>curtains<span class="o">)</span>
|
|||
|
|
|
|||
|
|
The<span class="w"> </span>theatre<span class="w"> </span>is<span class="w"> </span>at<span class="w"> </span>the<span class="w"> </span>centre<span class="w"> </span>of<span class="w"> </span>the<span class="w"> </span>city,<span class="w"> </span>both<span class="w"> </span>literally<span class="w"> </span>and<span class="w"> </span>figuratively<span class="w"> </span>...
|
|||
|
|
<span class="o">(</span>A<span class="w"> </span>lot<span class="w"> </span>more<span class="w"> </span>text<span class="w"> </span>about<span class="w"> </span>it<span class="w"> </span>follows<span class="w"> </span>...<span class="o">)</span>
|
|||
|
|
|
|||
|
|
Subtopics:
|
|||
|
|
<span class="w"> </span>theatre/lore
|
|||
|
|
<span class="w"> </span>theatre/layout
|
|||
|
|
<span class="w"> </span>theatre/dramatis<span class="w"> </span>personae
|
|||
|
|
------------------------------------------------------------------------------
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>><span class="w"> </span><span class="nb">help</span><span class="w"> </span>evennia
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>------------------------------------------------------------------------------
|
|||
|
|
No<span class="w"> </span><span class="nb">help</span><span class="w"> </span>found
|
|||
|
|
|
|||
|
|
There<span class="w"> </span>is<span class="w"> </span>no<span class="w"> </span><span class="nb">help</span><span class="w"> </span>topic<span class="w"> </span>matching<span class="w"> </span><span class="s1">'evennia'</span>.
|
|||
|
|
...<span class="w"> </span>But<span class="w"> </span>matches<span class="w"> </span>where<span class="w"> </span>found<span class="w"> </span>within<span class="w"> </span>the<span class="w"> </span><span class="nb">help</span><span class="w"> </span>texts<span class="w"> </span>of<span class="w"> </span>the<span class="w"> </span>suggestions<span class="w"> </span>below.
|
|||
|
|
|
|||
|
|
Suggestions:
|
|||
|
|
<span class="w"> </span>grapevine2chan,<span class="w"> </span>about,<span class="w"> </span>irc2chan
|
|||
|
|
-----------------------------------------------------------------------------
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<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 <code class="docutils literal notranslate"><span class="pre">help</span></code> command:</p>
|
|||
|
|
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>help <topic>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Sub-topics are accessed as <code class="docutils literal notranslate"><span class="pre">help</span> <span class="pre"><topic>/<subtopic>/...</span></code>.</p>
|
|||
|
|
<section id="working-with-three-types-of-help-entries">
|
|||
|
|
<h2>Working with three types of help entries<a class="headerlink" href="#working-with-three-types-of-help-entries" title="Link to this heading">¶</a></h2>
|
|||
|
|
<p>There are three ways to generate help entries:</p>
|
|||
|
|
<ul class="simple">
|
|||
|
|
<li><p>In the database</p></li>
|
|||
|
|
<li><p>As Python modules</p></li>
|
|||
|
|
<li><p>From Command doc strings</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<section id="database-stored-help-entries">
|
|||
|
|
<h3>Database-stored help entries<a class="headerlink" href="#database-stored-help-entries" title="Link to this heading">¶</a></h3>
|
|||
|
|
<p>Creating a new help entry from in-game is done with</p>
|
|||
|
|
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sethelp <topic>[;aliases] [,category] [,lockstring] = <text>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>For example</p>
|
|||
|
|
<div class="highlight-none notranslate"><div class="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 <code class="docutils literal notranslate"><span class="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 <a class="reference internal" href="../api/evennia.help.models.html#evennia.help.models.HelpEntry" title="evennia.help.models.HelpEntry"><span class="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>
|
|||
|
|
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">evennia</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_help_entry</span>
|
|||
|
|
<span class="n">entry</span> <span class="o">=</span> <span class="n">create_help_entry</span><span class="p">(</span><span class="s2">"emote"</span><span class="p">,</span>
|
|||
|
|
<span class="s2">"Emoting is important because ..."</span><span class="p">,</span>
|
|||
|
|
<span class="n">category</span><span class="o">=</span><span class="s2">"Roleplaying"</span><span class="p">,</span> <span class="n">locks</span><span class="o">=</span><span class="s2">"view:all()"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
</section>
|
|||
|
|
<section id="file-stored-help-entries">
|
|||
|
|
<h3>File-stored help entries<a class="headerlink" href="#file-stored-help-entries" title="Link to this heading">¶</a></h3>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">Added 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 (<code class="docutils literal notranslate"><span class="pre">.py</span></code> file ending) containing a <code class="docutils literal notranslate"><span class="pre">dict</span></code> to represent each entry. They require a server <code class="docutils literal notranslate"><span class="pre">reload</span></code> before any changes apply.</p>
|
|||
|
|
<ul class="simple">
|
|||
|
|
<li><p>Evennia will look through all modules given by
|
|||
|
|
<code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">HELP_ENTRY_DICTS</span></code>, this will be
|
|||
|
|
imported and must be a <code class="docutils literal notranslate"><span class="pre">list</span></code> of help-entry dicts.</p></li>
|
|||
|
|
<li><p>If no <code class="docutils literal notranslate"><span class="pre">HELP_ENTRY_DICTS</span></code> list is found, <em>every</em> top-level variable in the
|
|||
|
|
module that is a <code class="docutils literal notranslate"><span class="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.
|
|||
|
|
Here’s an example of a help module:</p>
|
|||
|
|
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span>
|
|||
|
|
<span class="c1"># in a module pointed to by settings.FILE_HELP_ENTRY_MODULES</span>
|
|||
|
|
|
|||
|
|
<span class="n">HELP_ENTRY_DICTS</span> <span class="o">=</span> <span class="p">[</span>
|
|||
|
|
<span class="p">{</span>
|
|||
|
|
<span class="s2">"key"</span><span class="p">:</span> <span class="s2">"The Gods"</span><span class="p">,</span> <span class="c1"># case-insensitive, can be searched by 'gods' too</span>
|
|||
|
|
<span class="s2">"aliases"</span><span class="p">:</span> <span class="p">[</span><span class="s1">'pantheon'</span><span class="p">,</span> <span class="s1">'religion'</span><span class="p">]</span>
|
|||
|
|
<span class="s2">"category"</span><span class="p">:</span> <span class="s2">"Lore"</span><span class="p">,</span>
|
|||
|
|
<span class="s2">"locks"</span><span class="p">:</span> <span class="s2">"read:all()"</span><span class="p">,</span> <span class="c1"># optional</span>
|
|||
|
|
<span class="s2">"text"</span><span class="p">:</span> <span class="s1">'''</span>
|
|||
|
|
<span class="s1"> The gods formed the world ...</span>
|
|||
|
|
|
|||
|
|
<span class="s1"> # Subtopics</span>
|
|||
|
|
|
|||
|
|
<span class="s1"> ## Pantheon</span>
|
|||
|
|
|
|||
|
|
<span class="s1"> The pantheon consists of 40 gods that ...</span>
|
|||
|
|
|
|||
|
|
<span class="s1"> ### God of love</span>
|
|||
|
|
|
|||
|
|
<span class="s1"> The most prominent god is ...</span>
|
|||
|
|
|
|||
|
|
<span class="s1"> ### God of war</span>
|
|||
|
|
|
|||
|
|
<span class="s1"> Also known as 'the angry god', this god is known to ...</span>
|
|||
|
|
|
|||
|
|
<span class="s1"> '''</span>
|
|||
|
|
<span class="p">},</span>
|
|||
|
|
<span class="p">{</span>
|
|||
|
|
<span class="s2">"key"</span><span class="p">:</span> <span class="s2">"The mortals"</span><span class="p">,</span>
|
|||
|
|
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="p">]</span>
|
|||
|
|
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<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>
|
|||
|
|
<section id="command-help-entries">
|
|||
|
|
<h3>Command-help entries<a class="headerlink" href="#command-help-entries" title="Link to this heading">¶</a></h3>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">__docstring__</span></code> of <a class="reference internal" href="Commands.html"><span class="std std-doc">Command classes</span></a> are automatically extracted into a help entry. You set <code class="docutils literal notranslate"><span class="pre">help_category</span></code> directly on the class.</p>
|
|||
|
|
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">evennia</span><span class="w"> </span><span class="kn">import</span> <span class="n">Command</span>
|
|||
|
|
|
|||
|
|
<span class="k">class</span><span class="w"> </span><span class="nc">MyCommand</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
|
|||
|
|
<span class="w"> </span><span class="sd">""" </span>
|
|||
|
|
<span class="sd"> This command is great! </span>
|
|||
|
|
|
|||
|
|
<span class="sd"> Usage: </span>
|
|||
|
|
<span class="sd"> mycommand [argument]</span>
|
|||
|
|
|
|||
|
|
<span class="sd"> When this command is called, great things happen. If you </span>
|
|||
|
|
<span class="sd"> pass an argument, even GREATER things HAPPEN!</span>
|
|||
|
|
|
|||
|
|
<span class="sd"> """</span>
|
|||
|
|
|
|||
|
|
<span class="n">key</span> <span class="o">=</span> <span class="s2">"mycommand"</span>
|
|||
|
|
|
|||
|
|
<span class="n">locks</span><span class="p">:</span> <span class="s2">"cmd:all();read:all()"</span> <span class="c1"># default </span>
|
|||
|
|
<span class="n">help_category</span> <span class="o">=</span> <span class="s2">"General"</span> <span class="c1"># default</span>
|
|||
|
|
<span class="n">auto_help</span> <span class="o">=</span> <span class="kc">True</span> <span class="c1"># default </span>
|
|||
|
|
|
|||
|
|
<span class="c1"># ...</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<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>
|
|||
|
|
<section id="locking-help-entries">
|
|||
|
|
<h3>Locking help entries<a class="headerlink" href="#locking-help-entries" title="Link to this heading">¶</a></h3>
|
|||
|
|
<p>The default <code class="docutils literal notranslate"><span class="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>
|
|||
|
|
<ul class="simple">
|
|||
|
|
<li><p>Commands failing the normal <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">read</span></code> access type determines if the command/help entry can be actually read.
|
|||
|
|
If a <code class="docutils literal notranslate"><span class="pre">read</span></code> lock is given and <code class="docutils literal notranslate"><span class="pre">view</span></code> is not, the <code class="docutils literal notranslate"><span class="pre">read</span></code>-lock is assumed to
|
|||
|
|
apply to <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="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>
|
|||
|
|
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">MyCommand</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
|
|||
|
|
<span class="w"> </span><span class="sd">"""</span>
|
|||
|
|
<span class="sd"> <docstring for command></span>
|
|||
|
|
<span class="sd"> """</span>
|
|||
|
|
<span class="n">key</span> <span class="o">=</span> <span class="s2">"mycommand"</span>
|
|||
|
|
<span class="c1"># everyone can use the command, builders can view it in the help index</span>
|
|||
|
|
<span class="c1"># but only devs can actually read the help (a weird setup for sure!)</span>
|
|||
|
|
<span class="n">locks</span> <span class="o">=</span> <span class="s2">"cmd:all();view:perm(Builders);read:perm(Developers)</span>
|
|||
|
|
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Db-help entries and File-Help entries work the same way (except the <code class="docutils literal notranslate"><span class="pre">cmd</span></code>-type
|
|||
|
|
lock is not used. A file-help example:</p>
|
|||
|
|
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">help_entry</span> <span class="o">=</span> <span class="p">{</span>
|
|||
|
|
<span class="c1"># ...</span>
|
|||
|
|
<span class="n">locks</span> <span class="o">=</span> <span class="s2">"read:perm(Developer)"</span><span class="p">,</span>
|
|||
|
|
<span class="c1"># ...</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 1.0: </span>Changed the old ‘view’ lock to control the help-index inclusion and added
|
|||
|
|
the new ‘read’ lock-type to control access to the entry itself.</p>
|
|||
|
|
</div>
|
|||
|
|
</section>
|
|||
|
|
<section id="customizing-the-look-of-the-help-system">
|
|||
|
|
<h3>Customizing the look of the help system<a class="headerlink" href="#customizing-the-look-of-the-help-system" title="Link to this heading">¶</a></h3>
|
|||
|
|
<p>This is done almost exclusively by overriding the <code class="docutils literal notranslate"><span class="pre">help</span></code> command <a class="reference internal" href="../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdHelp" title="evennia.commands.default.help.CmdHelp"><span class="xref myst py py-class">evennia.commands.default.help.CmdHelp</span></a>.</p>
|
|||
|
|
<p>Since the available commands may vary from moment to moment, <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">help</span></code> to change the display or tweak as you please. See the api link above for details.</p>
|
|||
|
|
</section>
|
|||
|
|
</section>
|
|||
|
|
<section id="subtopics">
|
|||
|
|
<h2>Subtopics<a class="headerlink" href="#subtopics" title="Link to this heading">¶</a></h2>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">Added in version 1.0.</span></p>
|
|||
|
|
</div>
|
|||
|
|
<p>Rather than making a very long help entry, the <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">subtopics</span></code> (non case-sensitive) and the following headers must be sub-headings to this (so <code class="docutils literal notranslate"><span class="pre">##</span> <span class="pre">subtopic</span> <span class="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 <code class="docutils literal notranslate"><span class="pre">text</span></code> with sub topics.</p>
|
|||
|
|
<div class="highlight-default notranslate"><div class="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>
|
|||
|
|
<section id="technical-notes">
|
|||
|
|
<h2>Technical notes<a class="headerlink" href="#technical-notes" title="Link to this heading">¶</a></h2>
|
|||
|
|
<section id="help-entry-clashes">
|
|||
|
|
<h3>Help-entry clashes<a class="headerlink" href="#help-entry-clashes" title="Link to this heading">¶</a></h3>
|
|||
|
|
<p>Should you have clashing help-entries (of the same name) between the three types of available entries, the priority is</p>
|
|||
|
|
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Command-auto-help > Db-help > File-help
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="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>
|
|||
|
|
<section id="the-help-entry-container">
|
|||
|
|
<h3>The Help Entry container<a class="headerlink" href="#the-help-entry-container" title="Link to this heading">¶</a></h3>
|
|||
|
|
<p>All help entries (no matter the source) are parsed into an object with the following properties:</p>
|
|||
|
|
<ul class="simple">
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">key</span></code> - This is the main topic-name. For Commands, this is literally the command’s <code class="docutils literal notranslate"><span class="pre">key</span></code>.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="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><code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">settings.COMMAND_DEFAULT_HELP_CATEGORY</span></code> for Commands and
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">settings.DEFAULT_HELP_CATEGORY</span></code> for file+db help entries.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="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><code class="docutils literal notranslate"><span class="pre">tags</span></code> - This is not used by default, but could be used to further organize help entries.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="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>
|
|||
|
|
<section id="help-pagination">
|
|||
|
|
<h3>Help pagination<a class="headerlink" href="#help-pagination" title="Link to this heading">¶</a></h3>
|
|||
|
|
<p>A <code class="docutils literal notranslate"><span class="pre">text</span></code> that scrolls off the screen will automatically be paginated by the <a class="reference internal" href="EvMore.html"><span class="std std-doc">EvMore</span></a> pager (you can control this with <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">\f</span></code>.</p>
|
|||
|
|
</section>
|
|||
|
|
<section id="search-engine">
|
|||
|
|
<h3>Search engine<a class="headerlink" href="#search-engine" title="Link to this heading">¶</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 <a class="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 <code class="docutils literal notranslate"><span class="pre">==</span></code>, <code class="docutils literal notranslate"><span class="pre">startswith</span></code> and <code class="docutils literal notranslate"><span class="pre">in</span></code> matching (there are so relatively few of them at that point).</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 1.0: </span>Replaced the old bag-of-words algorithm with lunr package.</p>
|
|||
|
|
</div>
|
|||
|
|
</section>
|
|||
|
|
</section>
|
|||
|
|
</section>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
|||
|
|
<div class="sphinxsidebarwrapper">
|
|||
|
|
<p class="logo"><a href="../index.html">
|
|||
|
|
<img class="logo" src="../_static/evennia_logo.png" alt="Logo of Evennia"/>
|
|||
|
|
</a></p>
|
|||
|
|
<search id="searchbox" style="display: none" role="search">
|
|||
|
|
<h3 id="searchlabel">Quick search</h3>
|
|||
|
|
<div class="searchformwrapper">
|
|||
|
|
<form class="search" action="../search.html" method="get">
|
|||
|
|
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
</search>
|
|||
|
|
<script>document.getElementById('searchbox').style.display = "block"</script>
|
|||
|
|
<h3><a href="../index.html">Table of Contents</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><a class="reference internal" href="#">Help System</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#working-with-three-types-of-help-entries">Working with three types of help entries</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#database-stored-help-entries">Database-stored help entries</a></li>
|
|||
|
|
<li><a class="reference internal" href="#file-stored-help-entries">File-stored help entries</a></li>
|
|||
|
|
<li><a class="reference internal" href="#command-help-entries">Command-help entries</a></li>
|
|||
|
|
<li><a class="reference internal" href="#locking-help-entries">Locking help entries</a></li>
|
|||
|
|
<li><a class="reference internal" href="#customizing-the-look-of-the-help-system">Customizing the look of the help system</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><a class="reference internal" href="#subtopics">Subtopics</a></li>
|
|||
|
|
<li><a class="reference internal" href="#technical-notes">Technical notes</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#help-entry-clashes">Help-entry clashes</a></li>
|
|||
|
|
<li><a class="reference internal" href="#the-help-entry-container">The Help Entry container</a></li>
|
|||
|
|
<li><a class="reference internal" href="#help-pagination">Help pagination</a></li>
|
|||
|
|
<li><a class="reference internal" href="#search-engine">Search engine</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<div>
|
|||
|
|
<h4>Previous topic</h4>
|
|||
|
|
<p class="topless"><a href="Prototypes.html"
|
|||
|
|
title="previous chapter">Spawner and Prototypes</a></p>
|
|||
|
|
</div>
|
|||
|
|
<div>
|
|||
|
|
<h4>Next topic</h4>
|
|||
|
|
<p class="topless"><a href="Permissions.html"
|
|||
|
|
title="next chapter">Permissions</a></p>
|
|||
|
|
</div>
|
|||
|
|
<div role="note" aria-label="source link">
|
|||
|
|
<!--h3>This Page</h3-->
|
|||
|
|
<ul class="this-page-menu">
|
|||
|
|
<li><a href="../_sources/Components/Help-System.md.txt"
|
|||
|
|
rel="nofollow">Show Page Source</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</div><h3>Links</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="https://www.evennia.com/docs/latest/index.html">Documentation Top</a> </li>
|
|||
|
|
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
|
|||
|
|
<li><a href="https://github.com/evennia/evennia">Github</a> </li>
|
|||
|
|
<li><a href="http://games.evennia.com">Game Index</a> </li>
|
|||
|
|
<li>
|
|||
|
|
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
|
|||
|
|
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
|
|||
|
|
<a href="https://evennia.blogspot.com/">Blog</a>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3>Doc Versions</h3>
|
|||
|
|
<ul>
|
|||
|
|
|
|||
|
|
<li>
|
|||
|
|
<a href="https://www.evennia.com/docs/latest/index.html">latest (main branch)</a>
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<li>
|
|||
|
|
<a href="https://www.evennia.com/docs/5.x/index.html">v5.0.0 branch (outdated)</a>
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li>
|
|||
|
|
<a href="https://www.evennia.com/docs/4.x/index.html">v4.0.0 branch (outdated)</a>
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li>
|
|||
|
|
<a href="https://www.evennia.com/docs/3.x/index.html">v3.0.0 branch (outdated)</a>
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li>
|
|||
|
|
<a href="https://www.evennia.com/docs/2.x/index.html">v2.0.0 branch (outdated)</a>
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li>
|
|||
|
|
<a href="https://www.evennia.com/docs/1.x/index.html">v1.0.0 branch (outdated)</a>
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li>
|
|||
|
|
<a href="https://www.evennia.com/docs/0.x/index.html">v0.9.5 branch (outdated)</a>
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="related" role="navigation" aria-label="Related">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
>index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="Permissions.html" title="Permissions"
|
|||
|
|
>next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="Prototypes.html" title="Spawner and Prototypes"
|
|||
|
|
>previous</a> |</li>
|
|||
|
|
<li class="nav-item nav-item-0"><a href="../index.html">Evennia</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-1"><a href="Components-Overview.html" >Core Components</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-this"><a href="">Help System</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="footer" role="contentinfo">
|
|||
|
|
© Copyright 2024, The Evennia developer community.
|
|||
|
|
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|