Updated HTML docs

This commit is contained in:
Griatch 2020-07-14 00:21:00 +02:00
parent a551188691
commit 781788f2e5
2063 changed files with 215958 additions and 250783 deletions

View file

@ -1,19 +1,18 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<html>
<head>
<meta charset="utf-8" />
<title>Evennia API &#8212; Evennia 1.0-dev documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>API Summary &#8212; Evennia 1.0-dev 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>
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
@ -27,10 +26,8 @@
<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 1.0-dev documentation</a> &#187;</li>
<li class="nav-item nav-item-last"><a href="#">Evennia API</a></li>
<li class="nav-item nav-item-0"><a href="index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">API Summary</a></li>
</ul>
</div>
@ -39,80 +36,126 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="evennia-api">
<h1>Evennia API<a class="headerlink" href="#evennia-api" title="Permalink to this headline"></a></h1>
<p>Evennia makes much of its programming tools available directly from the top-level <code class="docutils literal notranslate"><span class="pre">evennia</span></code> package.
This is often referred to as Evennias “flat” <a class="reference external" href="https://en.wikipedia.org/wiki/Application_programming_interface">Application Programming
Interface</a> (API). The flat API
tries to collect and bring the most commonly used resources to the front in a way where everything
is available at a glance (in a flat display), making it a good place to start to learn Evennia.</p>
<blockquote>
<div><p>Evennias flat (and full) API can be perused through the auto-generated <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia">API Library
refence</a>.</p>
</div></blockquote>
<p>A good, interactive way to explore the flat API is to use <a class="reference external" href="http://ipython.org/">IPython</a>, a more
flexible version of the default Python shell. Inside your virtual environment you can install
IPython simply by</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">ipython</span>
</pre></div>
<div class="section" id="api-summary">
<h1>API Summary<a class="headerlink" href="#api-summary" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="api/evennia.html">evennia</a> - library root</p>
<ul class="simple">
<li><p><a class="reference external" href="api/evennia.accounts.html">evennia.accounts</a> - the out-of-character entities representing players</p></li>
<li><p><a class="reference external" href="api/evennia.commands.html">evennia.commands</a> - handle all inputs. Also includes default commands</p></li>
<li><p><a class="reference external" href="api/evennia.comms.html">evennia.comms</a> - in-game channels and messaging</p></li>
<li><p><a class="reference external" href="api/evennia.contrib.html">evennia.contrib</a> - game-specific tools and code contributed by the community</p></li>
<li><p><a class="reference external" href="api/evennia.help.html">evennia.help</a> - in-game help system</p></li>
<li><p><a class="reference external" href="api/evennia.locks.html">evennia.locks</a> - limiting access to various systems and resources</p></li>
<li><p><a class="reference external" href="api/evennia.objects.html">evennia.objects</a> - all in-game entities, like Rooms, Characters, Exits etc</p></li>
<li><p><a class="reference external" href="api/evennia.prototypes.html">evennia.prototypes</a> - customize entities using dicts</p></li>
<li><p><a class="reference external" href="api/evennia.scripts.html">evennia.scripts</a> - all out-of-character game objects</p></li>
<li><p><a class="reference external" href="api/evennia.server.html">evennia.server</a> - core Server and Portal programs, also network protocols</p></li>
<li><p><a class="reference external" href="api/evennia.typeclasses.html">evennia.typeclasses</a> - core database-python bridge</p></li>
<li><p><a class="reference external" href="api/evennia.utils.html">evennia.utils</a> - lots of useful coding tools and utilities</p></li>
<li><p><a class="reference external" href="api/evennia.web.html">evennia.web</a> - webclient, website and other web resources</p></li>
</ul>
<div class="section" id="shortcuts">
<h2>Shortcuts<a class="headerlink" href="#shortcuts" title="Permalink to this headline"></a></h2>
<p>Evennias flat API has shortcuts to common tools, available by only importing <code class="docutils literal notranslate"><span class="pre">evennia</span></code>.
The flat API is defined in <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/__init__.py">viewable here</a></p>
<div class="section" id="main-config">
<h3>Main config<a class="headerlink" href="#main-config" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/settings_default.py">evennia.settings_default</a> - all settings (modify/override in <code class="docutils literal notranslate"><span class="pre">mygame/server/settings.py</span></code>)</p></li>
</ul>
</div>
<p>Windows users should also install <a class="reference external" href="http://ipython.org/pyreadline.html">PyReadline</a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">pyreadline</span>
</pre></div>
<div class="section" id="search-functions">
<h3>Search functions<a class="headerlink" href="#search-functions" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="api/evennia.utils.search.html#evennia.utils.search.search_account">evennia.search_account</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.search.html#evennia.utils.search.search_object">evennia.search_object</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.search.html#evennia.utils.search_object_by_tag">evennia.search_object_by_tag</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.search.html#evennia.utils.search_script">evennia.search_script</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.search.html#evennia.utils.search_channel">evennia.search_channel</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.search.html#evennia.utils.search_message">evennia.search_message</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.search.html#evennia.utils.search.search_help">evennia.search_help</a></p></li>
</ul>
</div>
<p>With IPython installed, go to your game directory and run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">shell</span>
</pre></div>
<div class="section" id="create-functions">
<h3>Create functions<a class="headerlink" href="#create-functions" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="api/evennia.utils.create.html#evennia.utils.create.create_account">evennia.create_account</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.create.html#evennia.utils.create.create_object">evennia.create_object</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.create.html#evennia.utils.create.create_script">evennia.create_script</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.create.html#evennia.utils.create.create_channel">evennia.create_channel</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.create.html#evennia.utils.create.create_help_entry">evennia.create_help_entry</a></p></li>
<li><p><a class="reference external" href="api/evennia.utils.create.html#evennia.utils.create.create_message">evennia.create_message</a></p></li>
</ul>
</div>
<p>This should give you the IPython shell automatically. Inside IPython
you then do</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">evennia</span>
</pre></div>
<div class="section" id="typeclasses">
<h3>Typeclasses<a class="headerlink" href="#typeclasses" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="api/evennia.accounts.accounts.html#evennia.accounts.accounts.DefaultAccount">evennia.Defaultaccount</a> - player account class (<a class="reference internal" href="Components/Accounts.html"><span class="doc">docs</span></a>)</p></li>
<li><p><a class="reference external" href="api/evennia.accounts.accounts.html#evennia.accounts.accounts.DefaultGuest">evennia.DefaultGuest</a> - base guest account class</p></li>
<li><p><a class="reference external" href="api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject">evennia.DefaultObject</a> - base class for all objects (<a class="reference internal" href="Components/Objects.html"><span class="doc">docs</span></a>)</p></li>
<li><p><a class="reference external" href="api/evennia.objects.objects.html#evennia.objects.objects.DefaultCharacter">evennia.DefaultCharacter</a> - base class for in-game characters (<a class="reference external" href="Components/Objects.html#Character">docs</a>)</p></li>
<li><p><a class="reference external" href="api/evennia.objects.objects.html#evennia.objects.objects.DefaultRoom">evennia.DefaultRoom</a> - base class for rooms (<a class="reference external" href="Components/Objects.html#Room">docs</a>)</p></li>
<li><p><a class="reference external" href="api/evennia.objects.objects.html#evennia.objects.objects.DefaultExit">evennia.DefaultExit</a> - base class for exits (<a class="reference external" href="Components/Objects.html#Exit">docs</a>)</p></li>
<li><p><a class="reference external" href="api/evennia.scripts.scripts.html#evennia.scripts.scripts.DefaultScript">evennia.DefaultScript</a> - base class for OOC-objects (<a class="reference internal" href="Components/Scripts.html"><span class="doc">docs</span></a>)</p></li>
<li><p><a class="reference external" href="api/evennia.comms.comms.html#evennia.comms.comms.DefaultChannel">evennia.DefaultChannel</a> - base class for in-game channels (<a class="reference internal" href="Components/Channels.html"><span class="doc">docs</span></a>)</p></li>
</ul>
</div>
<p>Followed by</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span><span class="o">.&lt;</span><span class="n">TAB</span><span class="o">&gt;</span>
</pre></div>
<div class="section" id="commands">
<h3>Commands<a class="headerlink" href="#commands" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="api/evennia.commands.command.html#evennia.commands.command.Command">evennia.Command</a> - base <a class="reference internal" href="Components/Commands.html"><span class="doc">Command</span></a> class. See also <code class="docutils literal notranslate"><span class="pre">evennia.default_cmds.MuxCommand</span></code></p></li>
<li><p><a class="reference external" href="api/evennia.commands.cmdset.html#evennia.commands.cmdset.CmdSet">evennia.CmdSet</a> - base <a class="reference internal" href="Components/Command-Sets.html"><span class="doc">Cmdset</span></a> class</p></li>
<li><p><a class="reference external" href="api/Default-Command-Help.html">evennia.default_cmds</a> - access all default command classes as properties</p></li>
<li><p><a class="reference external" href="api/Commands.html#System-Commands">evennia.syscmdkeys</a> - access system command keys as properties</p></li>
</ul>
</div>
<p>That is, write <code class="docutils literal notranslate"><span class="pre">evennia.</span></code> and press the TAB key. What pops up is the contents of the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> top-
level package - in other words <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia#the-flat-api">the “flat” API</a>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>evennia.DefaultObject?
</pre></div>
<div class="section" id="utilities">
<h3>Utilities<a class="headerlink" href="#utilities" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="api/evennia.utils.utils.html">evennia.utils.utils</a> - mixed useful utilities</p></li>
<li><p><a class="reference external" href="api/evennia.utils.gametime.html">evennia.gametime</a> - server run- and game time (<a class="reference external" href="Components/Coding-Utils.html#gametime">docs</a>)</p></li>
<li><p><a class="reference external" href="api/evennia.utils.logger.html">evennia.logger</a> - logging tools</p></li>
<li><p><a class="reference external" href="api/evennia.utils.ansi.html">evennia.ansi</a> - ansi coloring tools</p></li>
<li><p><a class="reference external" href="api/evennia.prototypes.spawner.html#evennia.prototypes.spawner.Spawn">evennia.spawn</a> - spawn/prototype system (<a class="reference internal" href="Components/Spawner-and-Prototypes.html"><span class="doc">docs</span></a>)</p></li>
<li><p><a class="reference external" href="api/evennia.locks.lockfuncs.html">evennia.lockfuncs</a> - default lock functions for access control (<a class="reference internal" href="Components/Locks.html"><span class="doc">docs</span></a>)</p></li>
<li><p><a class="reference external" href="api/evennia.utils.evmenu.html#evennia.utils.evmenu.EvMenu">evennia.EvMenu</a> - menu system (<a class="reference internal" href="Components/EvMenu.html"><span class="doc">docs</span></a>)</p></li>
<li><p><a class="reference external" href="api/evennia.utils.evtable.html#evennia.utils.evtable.EvTable">evennia.EvTable</a> - text table creater</p></li>
<li><p><a class="reference external" href="api/evennia.utils.evform.html#evennia.utils.evform.EvForm">evennia.EvForm</a> - text form creator</p></li>
<li><p><a class="reference external" href="api/evennia.utils.eveditor.html#evennia.utils.eveditor.EvEditor">evennia.EvEditor</a> - in game text line editor (<a class="reference internal" href="Components/EvEditor.html"><span class="doc">docs</span></a>)</p></li>
</ul>
</div>
<div class="section" id="global-singleton-handlers">
<h3>Global singleton handlers<a class="headerlink" href="#global-singleton-handlers" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="api/evennia.scripts.tickerhandler.html">evennia.TICKER_HANDLER</a> - allow objects subscribe to tickers (<a class="reference internal" href="Components/TickerHandler.html"><span class="doc">docs</span></a>)</p></li>
<li><p><a class="reference external" href="api/evennia.scripts.monitorhandler.html">evennia.MONITOR_HANDLER</a> - monitor changes (<a class="reference internal" href="Components/MonitorHandler.html"><span class="doc">docs</span></a>)</p></li>
<li><p><a class="reference external" href="api/evennia.comms.channelhandler.html">evennia.CHANNEL_HANDLER</a> - maintains channels</p></li>
<li><p><a class="reference external" href="api/evennia.server.serverhandler.html">evennia.SESSION_HANDLER</a> - manages all sessionsmain session handler</p></li>
</ul>
</div>
<div class="section" id="database-core-models-for-more-advanced-lookups">
<h3>Database core models (for more advanced lookups)<a class="headerlink" href="#database-core-models-for-more-advanced-lookups" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="api/evennia.objects.models.html#evennia.objects.models.ObjectDB">evennia.ObjectDB</a></p></li>
<li><p><a class="reference external" href="api/evennia.accounts.models.html#evennia.accounts.models.AccountDB">evennia.accountDB</a></p></li>
<li><p><a class="reference external" href="api/evennia.scripts.models.html#evennia.scripts.models.ScriptDB">evennia.ScriptDB</a></p></li>
<li><p><a class="reference external" href="api/evennia.channels.models.html#evennia.channels.models.ChannelDB">evennia.ChannelDB</a></p></li>
<li><p><a class="reference external" href="api/evennia.comms.models.html#evennia.comms.models.Msg">evennia.Msg</a></p></li>
<li><p>evennia.managers - contains shortcuts to all database managers</p></li>
</ul>
</div>
<div class="section" id="contributions">
<h3>Contributions<a class="headerlink" href="#contributions" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/contrib/">evennia.contrib</a> -
game-specific contributions and plugins (<a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/contrib/README.md">docs</a>)</p></li>
</ul>
</div>
<p>Starting to write the name of an API entity and pressing <code class="docutils literal notranslate"><span class="pre">&lt;TAB&gt;</span></code> will auto-complete the name. Adding
a question mark (<code class="docutils literal notranslate"><span class="pre">?</span></code>) to its name will show you its documentation. Append <code class="docutils literal notranslate"><span class="pre">??</span></code> to get the actual
source code. This way you can quickly explore Evennia and see what is available.</p>
<div class="section" id="to-remember-when-importing-from-evennia">
<h2>To remember when importing from <code class="docutils literal notranslate"><span class="pre">evennia</span></code><a class="headerlink" href="#to-remember-when-importing-from-evennia" title="Permalink to this headline"></a></h2>
<p>Properties on the root of the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> package are <em>not</em> modules in their own right. They are just
shortcut properties stored in the <code class="docutils literal notranslate"><span class="pre">evennia/__init__.py</span></code> module. That means that you cannot use dot-
notation to <code class="docutils literal notranslate"><span class="pre">import</span></code> nested module-names over <code class="docutils literal notranslate"><span class="pre">evennia</span></code>. The rule of thumb is that you cannot use
<code class="docutils literal notranslate"><span class="pre">import</span></code> for more than one level down. Hence you can do</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">evennia</span>
<span class="k">print</span><span class="p">(</span><span class="n">evennia</span><span class="o">.</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">CmdLook</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>or import one level down</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">default_cmds</span>
<span class="k">print</span><span class="p">(</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">CmdLook</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>but you <em>cannot</em> import two levels down</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.default_cmds</span> <span class="kn">import</span> <span class="n">CmdLook</span> <span class="c1"># error!</span>
</pre></div>
</td></tr></table></div>
<p>This will give you an <code class="docutils literal notranslate"><span class="pre">ImportError</span></code> telling you that the module <code class="docutils literal notranslate"><span class="pre">default_cmds</span></code> cannot be found -
this is becasue <code class="docutils literal notranslate"><span class="pre">default_cmds</span></code> is just a <em>variable</em> stored in <code class="docutils literal notranslate"><span class="pre">evennia.__init__.py</span></code>; this cannot be
imported from. If you really want full control over which level of package you import you can always
bypass the root package and import directly from from the real location. For example
<code class="docutils literal notranslate"><span class="pre">evennia.DefaultObject</span></code> is a shortcut to <code class="docutils literal notranslate"><span class="pre">evennia.objects.objects.DefaultObject</span></code>. Using this full
path will have the import mechanism work normally. See <code class="docutils literal notranslate"><span class="pre">evennia/__init__.py</span></code> to see where the
package imports from.</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
@ -133,8 +176,19 @@ package imports from.</p>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Evennia API</a><ul>
<li><a class="reference internal" href="#to-remember-when-importing-from-evennia">To remember when importing from <code class="docutils literal notranslate"><span class="pre">evennia</span></code></a></li>
<li><a class="reference internal" href="#">API Summary</a><ul>
<li><a class="reference internal" href="#shortcuts">Shortcuts</a><ul>
<li><a class="reference internal" href="#main-config">Main config</a></li>
<li><a class="reference internal" href="#search-functions">Search functions</a></li>
<li><a class="reference internal" href="#create-functions">Create functions</a></li>
<li><a class="reference internal" href="#typeclasses">Typeclasses</a></li>
<li><a class="reference internal" href="#commands">Commands</a></li>
<li><a class="reference internal" href="#utilities">Utilities</a></li>
<li><a class="reference internal" href="#global-singleton-handlers">Global singleton handlers</a></li>
<li><a class="reference internal" href="#database-core-models-for-more-advanced-lookups">Database core models (for more advanced lookups)</a></li>
<li><a class="reference internal" href="#contributions">Contributions</a></li>
</ul>
</li>
</ul>
</li>
</ul>
@ -165,15 +219,13 @@ package imports from.</p>
<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 1.0-dev documentation</a> &#187;</li>
<li class="nav-item nav-item-last"><a href="#">Evennia API</a></li>
<li class="nav-item nav-item-0"><a href="index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">API Summary</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.4.4.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>