mirror of
https://github.com/evennia/evennia.git
synced 2026-03-18 13:56:30 +01:00
230 lines
No EOL
14 KiB
HTML
230 lines
No EOL
14 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>Help System — Evennia 0.9.5 documentation</title>
|
||
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||
<script src="_static/jquery.js"></script>
|
||
<script src="_static/underscore.js"></script>
|
||
<script src="_static/doctools.js"></script>
|
||
<script src="_static/language_data.js"></script>
|
||
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
||
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
|
||
<link rel="shortcut icon" href="_static/favicon.ico"/>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
</head><body>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<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="nav-item nav-item-0"><a href="index.html">Evennia 0.9.5</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="Permalink to this headline">¶</a></h1>
|
||
<p>An important part of Evennia is the online help system. This allows the players and staff alike to
|
||
learn how to use the game’s commands as well as other information pertinent to the game. The help
|
||
system has many different aspects, from the normal editing of help entries from inside the game, to
|
||
auto-generated help entries during code development using the <em>auto-help system</em>.</p>
|
||
<section id="viewing-the-help-database">
|
||
<h2>Viewing the help database<a class="headerlink" href="#viewing-the-help-database" title="Permalink to this headline">¶</a></h2>
|
||
<p>The main command is <code class="docutils literal notranslate"><span class="pre">help</span></code>:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> help [searchstring]
|
||
</pre></div>
|
||
</div>
|
||
<p>This will show a list of help entries, ordered after categories. You will find two sections,
|
||
<em>Command help entries</em> and <em>Other help entries</em> (initially you will only have the first one). You
|
||
can use help to get more info about an entry; you can also give partial matches to get suggestions.
|
||
If you give category names you will only be shown the topics in that category.</p>
|
||
</section>
|
||
<section id="command-auto-help-system">
|
||
<h2>Command Auto-help system<a class="headerlink" href="#command-auto-help-system" title="Permalink to this headline">¶</a></h2>
|
||
<p>A common item that requires help entries are in-game commands. Keeping these entries up-to-date with
|
||
the actual source code functionality can be a chore. Evennia’s commands are therefore auto-
|
||
documenting straight from the sources through its <em>auto-help system</em>. Only commands that you and
|
||
your character can actually currently use are picked up by the auto-help system. That means an admin
|
||
will see a considerably larger amount of help topics than a normal player when using the default
|
||
<code class="docutils literal notranslate"><span class="pre">help</span></code> command.</p>
|
||
<p>The auto-help system uses the <code class="docutils literal notranslate"><span class="pre">__doc__</span></code> strings of your command classes and formats this to a nice-
|
||
looking help entry. This makes for a very easy way to keep the help updated - just document your
|
||
commands well and updating the help file is just a <code class="docutils literal notranslate"><span class="pre">@reload</span></code> away. There is no need to manually
|
||
create and maintain help database entries for commands; as long as you keep the docstrings updated
|
||
your help will be dynamically updated for you as well.</p>
|
||
<p>Example (from a module with command definitions):</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">class</span> <span class="nc">CmdMyCmd</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
|
||
<span class="sd">"""</span>
|
||
<span class="sd"> mycmd - my very own command</span>
|
||
<span class="sd"> </span>
|
||
<span class="sd"> Usage:</span>
|
||
<span class="sd"> mycmd[/switches] <args></span>
|
||
<span class="sd"> </span>
|
||
<span class="sd"> Switches:</span>
|
||
<span class="sd"> test - test the command</span>
|
||
<span class="sd"> run - do something else</span>
|
||
<span class="sd"> </span>
|
||
<span class="sd"> This is my own command that does this and that.</span>
|
||
<span class="sd"> </span>
|
||
<span class="sd"> """</span>
|
||
<span class="c1"># [...]</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>The text at the very top of the command class definition is the class’ <code class="docutils literal notranslate"><span class="pre">__doc__</span></code>-string and will be
|
||
shown to users looking for help. Try to use a consistent format - all default commands are using the
|
||
structure shown above.</p>
|
||
<p>You should also supply the <code class="docutils literal notranslate"><span class="pre">help_category</span></code> class property if you can; this helps to group help
|
||
entries together for people to more easily find them. See the <code class="docutils literal notranslate"><span class="pre">help</span></code> command in-game to see the
|
||
default categories. If you don’t specify the category, “General” is assumed.</p>
|
||
<p>If you don’t want your command to be picked up by the auto-help system at all (like if you want to
|
||
write its docs manually using the info in the next section or you use a <a class="reference internal" href="Command-Sets.html"><span class="doc std std-doc">cmdset</span></a> that
|
||
has its own help functionality) you can explicitly set <code class="docutils literal notranslate"><span class="pre">auto_help</span></code> class property to <code class="docutils literal notranslate"><span class="pre">False</span></code> in your
|
||
command definition.</p>
|
||
<p>Alternatively, you can keep the advantages of <em>auto-help</em> in commands, but control the display of
|
||
command helps. You can do so by overriding the command’s <code class="docutils literal notranslate"><span class="pre">get_help()</span></code> method. By default, this
|
||
method will return the class docstring. You could modify it to add custom behavior: the text
|
||
returned by this method will be displayed to the character asking for help in this command.</p>
|
||
</section>
|
||
<section id="database-help-entries">
|
||
<h2>Database help entries<a class="headerlink" href="#database-help-entries" title="Permalink to this headline">¶</a></h2>
|
||
<p>These are all help entries not involving commands (this is handled automatically by the <a class="reference internal" href="#command-auto-help-system"><span class="std std-doc">Command
|
||
Auto-help system</span></a>). Non-automatic help entries describe how
|
||
your particular game is played - its rules, world descriptions and so on.</p>
|
||
<p>A help entry consists of four parts:</p>
|
||
<ul class="simple">
|
||
<li><p>The <em>topic</em>. This is the name of the help entry. This is what players search for when they are
|
||
looking for help. The topic can contain spaces and also partial matches will be found.</p></li>
|
||
<li><p>The <em>help category</em>. Examples are <em>Administration</em>, <em>Building</em>, <em>Comms</em> or <em>General</em>. This is an
|
||
overall grouping of similar help topics, used by the engine to give a better overview.</p></li>
|
||
<li><p>The <em>text</em> - the help text itself, of any length.</p></li>
|
||
<li><p>locks - a <a class="reference internal" href="Locks.html"><span class="doc std std-doc">lock definition</span></a>. This can be used to limit access to this help entry, maybe
|
||
because it’s staff-only or otherwise meant to be restricted. Help commands check for <code class="docutils literal notranslate"><span class="pre">access_type</span></code>s
|
||
<code class="docutils literal notranslate"><span class="pre">view</span></code> and <code class="docutils literal notranslate"><span class="pre">edit</span></code>. An example of a lock string would be <code class="docutils literal notranslate"><span class="pre">view:perm(Builders)</span></code>.</p></li>
|
||
</ul>
|
||
<p>You can create new help entries in code by using <code class="docutils literal notranslate"><span class="pre">evennia.create_help_entry()</span></code>.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia</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>
|
||
<p>From inside the game those with the right permissions can use the <code class="docutils literal notranslate"><span class="pre">@sethelp</span></code> command to add and
|
||
modify help entries.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>> @sethelp/add emote = The emote command is ...
|
||
</pre></div>
|
||
</div>
|
||
<p>Using <code class="docutils literal notranslate"><span class="pre">@sethelp</span></code> you can add, delete and append text to existing entries. By default new entries
|
||
will go in the <em>General</em> help category. You can change this using a different form of the <code class="docutils literal notranslate"><span class="pre">@sethelp</span></code>
|
||
command:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>> @sethelp/add emote, Roleplaying = Emoting is important because ...
|
||
</pre></div>
|
||
</div>
|
||
<p>If the category <em>Roleplaying</em> did not already exist, it is created and will appear in the help
|
||
index.</p>
|
||
<p>You can, finally, define a lock for the help entry by following the category with a <a class="reference internal" href="Locks.html"><span class="doc std std-doc">lock
|
||
definition</span></a>:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>> @sethelp/add emote, Roleplaying, view:all() = Emoting is ...
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<p class="logo"><a href="index.html">
|
||
<img class="logo" src="_static/evennia_logo.png" alt="Logo"/>
|
||
</a></p>
|
||
<div 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" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</div>
|
||
<script>$('#searchbox').show(0);</script>
|
||
<p><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="#viewing-the-help-database">Viewing the help database</a></li>
|
||
<li><a class="reference internal" href="#command-auto-help-system">Command Auto-help system</a></li>
|
||
<li><a class="reference internal" href="#database-help-entries">Database help entries</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<div role="note" aria-label="source link">
|
||
<!--h3>This Page</h3-->
|
||
<ul class="this-page-menu">
|
||
<li><a href="_sources/Help-System.md.txt"
|
||
rel="nofollow">Show Page Source</a></li>
|
||
</ul>
|
||
</div><h3>Links</h3>
|
||
<ul>
|
||
<li><a href="https://www.evennia.com">Home page</a> </li>
|
||
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
|
||
<li><a href="http://games.evennia.com">Game Index</a> </li>
|
||
<li><a href="http://webchat.freenode.net/?channels=evennia&uio=MT1mYWxzZSY5PXRydWUmMTE9MTk1JjEyPXRydWUbb">IRC</a> -
|
||
<a href="https://discord.gg/NecFePw">Discord</a> -
|
||
<a href="https://groups.google.com/forum/#%21forum/evennia">Forums</a>
|
||
</li>
|
||
<li><a href="http://evennia.blogspot.com/">Evennia Dev blog</a> </li>
|
||
</ul>
|
||
<h3>Versions</h3>
|
||
<ul>
|
||
<li><a href="../1.0-dev/index.html">1.0-dev (develop branch)</a></li>
|
||
<li><a href="Help-System.html">0.9.5 (v0.9.5 branch)</a></li>
|
||
</ul>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<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="nav-item nav-item-0"><a href="index.html">Evennia 0.9.5</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Help System</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2020, The Evennia developer community.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
|
||
</div>
|
||
</body>
|
||
</html> |