Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-04-04 23:17:17 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated HTML docs.

Browse source
This commit is contained in:
Evennia docbuilder action 2022-11-25 18:52:52 +00:00
parent 55dc9942a8
commit cf88322ffe
83 changed files with 2621 additions and 3207 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/1.0-dev/.buildinfo
View file

@ -1,4 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 0004a5f6b965a26712178e2e59d11179
config: 2073b8f3514aba16a52753d4c9e4e820
tags: 645f666f9bcd5a90fca523b33c5a78b7

8
docs/1.0-dev/Coding/Changelog.html
View file

@ -17,7 +17,7 @@
<link rel="shortcut 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="Continuous Integration" href="Continuous-Integration.html" />
<link rel="next" title="Continuous Integration (CI)" href="Continuous-Integration.html" />
<link rel="prev" title="Quirks" href="Quirks.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,7 +30,7 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Continuous-Integration.html" title="Continuous Integration"
<a href="Continuous-Integration.html" title="Continuous Integration (CI)"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Quirks.html" title="Quirks"
@ -129,7 +129,7 @@
title="previous chapter">Quirks</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Continuous-Integration.html"
title="next chapter">Continuous Integration</a></p>
title="next chapter">Continuous Integration (CI)</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -1080,7 +1080,7 @@ and have no changelogs.</p>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Continuous-Integration.html" title="Continuous Integration"
<a href="Continuous-Integration.html" title="Continuous Integration (CI)"
>next</a> |</li>
<li class="right" >
<a href="Quirks.html" title="Quirks"

160
docs/1.0-dev/Coding/Coding-FAQ.html
View file

@ -17,8 +17,8 @@
<link rel="shortcut 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="Debugging" href="Debugging.html" />
<link rel="prev" title="Coding Introduction" href="Coding-Introduction.html" />
<link rel="next" title="Quirks" href="Quirks.html" />
<link rel="prev" title="Evennia Code Style" href="Evennia-Code-Style.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -30,10 +30,10 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Debugging.html" title="Debugging"
<a href="Quirks.html" title="Quirks"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Coding-Introduction.html" title="Coding Introduction"
<a href="Evennia-Code-Style.html" title="Evennia Code Style"
accesskey="P">previous</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-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
@ -63,28 +63,25 @@
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Coding FAQ</a><ul>
<li><a class="reference internal" href="#table-of-contents">Table of Contents</a></li>
<li><a class="reference internal" href="#removing-default-commands">Removing default commands</a></li>
<li><a class="reference internal" href="#preventing-character-from-moving-based-on-a-condition">Preventing character from moving based on a condition</a></li>
<li><a class="reference internal" href="#reference-initiating-object-in-an-evmenu-command">Reference initiating object in an EvMenu command.</a></li>
<li><a class="reference internal" href="#adding-color-to-default-evennia-channels">Adding color to default Evennia Channels</a></li>
<li><a class="reference internal" href="#selectively-turn-off-commands-in-a-room">Selectively turn off commands in a room</a></li>
<li><a class="reference internal" href="#select-command-based-on-a-condition">Select Command based on a condition</a></li>
<li><a class="reference internal" href="#automatically-updating-code-when-reloading">Automatically updating code when reloading</a></li>
<li><a class="reference internal" href="#changing-all-exit-messages">Changing all exit messages</a></li>
<li><a class="reference internal" href="#add-parsing-with-the-to-delimiter">Add parsing with the “to” delimiter</a></li>
<li><a class="reference internal" href="#store-last-used-session-ip-address">Store last used session IP address</a></li>
<li><a class="reference internal" href="#non-latin-characters-in-evtable">Non-latin characters in EvTable</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Coding-Introduction.html"
title="previous chapter">Coding Introduction</a></p>
<p class="topless"><a href="Evennia-Code-Style.html"
title="previous chapter">Evennia Code Style</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Debugging.html"
title="next chapter">Debugging</a></p>
<p class="topless"><a href="Quirks.html"
title="next chapter">Quirks</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -120,29 +117,9 @@
<p><em>This FAQ page is for users to share their solutions to coding problems. Keep it brief and link to
the docs if you can rather than too lengthy explanations. Don’t forget to check if an answer already
exists before answering - maybe you can clarify that answer rather than to make a new Q&amp;A section.</em></p>
<section id="table-of-contents">
<h2>Table of Contents<a class="headerlink" href="#table-of-contents" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="#removing-default-commands"><span class="std std-doc">Removing default commands</span></a></p></li>
<li><p>[Preventing character from moving based on a condition](./Coding-FAQ.md#preventing-character-from-
moving-based-on-a-condition)</p></li>
<li><p>[Reference initiating object in an EvMenu command](./Coding-FAQ.md#reference-initiating-object-in-an-
evmenu-command)</p></li>
<li><p><a class="reference internal" href="#adding-color-to-default-evennia-channels"><span class="std std-doc">Adding color to default Evennia Channels</span></a></p></li>
<li><p><a class="reference internal" href="#selectively-turn-off-commands-in-a-room"><span class="std std-doc">Selectively turn off commands in a room</span></a></p></li>
<li><p><a class="reference internal" href="#select-command-based-on-a-condition"><span class="std std-doc">Select Command based on a condition</span></a></p></li>
<li><p>[Automatically updating code when reloading](./Coding-FAQ.md#automatically-updating-code-when-
reloading)</p></li>
<li><p><a class="reference internal" href="#changing-all-exit-messages"><span class="std std-doc">Changing all exit messages</span></a></p></li>
<li><p><a class="reference internal" href="#add-parsing-with-the-to-delimiter"><span class="std std-doc">Add parsing with the “to” delimiter</span></a></p></li>
<li><p><a class="reference internal" href="#store-last-used-session-ip-address"><span class="std std-doc">Store last used session IP address</span></a></p></li>
<li><p><a class="reference internal" href="#non-latin-characters-in-evtable"><span class="std std-doc">Use wide characters with EvTable</span></a></p></li>
</ul>
</section>
<section id="removing-default-commands">
<h2>Removing default commands<a class="headerlink" href="#removing-default-commands" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> How does one <em>remove</em> (not replace) e.g. the default <code class="docutils literal notranslate"><span class="pre">get</span></code> <a class="reference internal" href="../Components/Commands.html"><span class="doc std std-doc">Command</span></a> from the
Character <a class="reference internal" href="../Components/Command-Sets.html"><span class="doc std std-doc">Command Set</span></a>?</p>
<p><strong>Q:</strong> How does one <em>remove</em> (not replace) e.g. the default <code class="docutils literal notranslate"><span class="pre">get</span></code> <a class="reference internal" href="../Components/Commands.html"><span class="doc std std-doc">Command</span></a> from the Character <a class="reference internal" href="../Components/Command-Sets.html"><span class="doc std std-doc">Command Set</span></a>?</p>
<p><strong>A:</strong> Go to <code class="docutils literal notranslate"><span class="pre">mygame/commands/default_cmdsets.py</span></code>. Find the <code class="docutils literal notranslate"><span class="pre">CharacterCmdSet</span></code> class. It has one
method named <code class="docutils literal notranslate"><span class="pre">at_cmdset_creation</span></code>. At the end of that method, add the following line:
<code class="docutils literal notranslate"><span class="pre">self.remove(default_cmds.CmdGet())</span></code>. See the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.html"><span class="doc std std-doc">Adding Commands Tutorial</span></a>
@ -183,29 +160,6 @@ properties on this menu object:</p>
</div>
<p>Inside the menu you can now access the object through <code class="docutils literal notranslate"><span class="pre">caller.ndb._evmenu.stored_obj</span></code>.</p>
</section>
<section id="adding-color-to-default-evennia-channels">
<h2>Adding color to default Evennia Channels<a class="headerlink" href="#adding-color-to-default-evennia-channels" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> How do I add colors to the names of Evennia channels?</p>
<p><strong>A:</strong> The Channel typeclass’ <code class="docutils literal notranslate"><span class="pre">channel_prefix</span></code> method decides what is shown at the beginning of a
channel send. Edit <code class="docutils literal notranslate"><span class="pre">mygame/typeclasses/channels.py</span></code> (and then <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code>):</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># define our custom color names</span>
<span class="n">CHANNEL_COLORS</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;public&quot;</span><span class="p">:</span> <span class="s2">&quot;|015Public|n&quot;</span><span class="p">,</span>
<span class="s2">&quot;newbie&quot;</span><span class="p">:</span> <span class="s2">&quot;|550N|n|551e|n|552w|n|553b|n|554i|n|555e|n&quot;</span><span class="p">,</span>
<span class="s2">&quot;staff&quot;</span><span class="p">:</span> <span class="s2">&quot;|010S|n|020t|n|030a|n|040f|n|050f|n&quot;</span><span class="p">}</span>
<span class="c1"># Add to the Channel class</span>
<span class="c1"># ...</span>
<span class="k">def</span> <span class="nf">channel_prefix</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">msg</span><span class="p">,</span> <span class="n">emit</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">key</span> <span class="ow">in</span> <span class="n">COLORS</span><span class="p">:</span>
<span class="n">p_str</span> <span class="o">=</span> <span class="n">CHANNEL_COLORS</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">lower</span><span class="p">())</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">p_str</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">capitalize</span><span class="p">()</span>
<span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;[</span><span class="si">{</span><span class="n">p_str</span><span class="si">}</span><span class="s2">] &quot;</span>
</pre></div>
</div>
<p>Additional hint: To make colors easier to change from one place you could instead put the
<code class="docutils literal notranslate"><span class="pre">CHANNEL_COLORS</span></code> dict in your settings file and import it as <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">django.conf.settings</span> <span class="pre">import</span> <span class="pre">CHANNEL_COLORS</span></code>.</p>
</section>
<section id="selectively-turn-off-commands-in-a-room">
<h2>Selectively turn off commands in a room<a class="headerlink" href="#selectively-turn-off-commands-in-a-room" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> I want certain commands to turn off in a given room. They should still work normally for
@ -239,18 +193,16 @@ is an example of a room where certain commands are disabled for non-staff:</p>
<span class="bp">self</span><span class="o">.</span><span class="n">locks</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;call:not perm(Builders)&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>After <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code>, make some <code class="docutils literal notranslate"><span class="pre">BlockingRooms</span></code> (or switch a room to it with <code class="docutils literal notranslate"><span class="pre">&#64;typeclass</span></code>). Entering one
<p>After <code class="docutils literal notranslate"><span class="pre">reload</span></code>, make some <code class="docutils literal notranslate"><span class="pre">BlockingRooms</span></code> (or switch a room to it with <code class="docutils literal notranslate"><span class="pre">&#64;typeclass</span></code>). Entering one
will now replace the given commands for anyone that does not have the <code class="docutils literal notranslate"><span class="pre">Builders</span></code> or higher
permission. Note that the ‘call’ lock is special in that even the superuser will be affected by it
(otherwise superusers would always see other player’s cmdsets and a game would be unplayable for
superusers).</p>
(otherwise superusers would always see other player’s cmdsets and a game would be unplayable for superusers).</p>
</section>
<section id="select-command-based-on-a-condition">
<h2>Select Command based on a condition<a class="headerlink" href="#select-command-based-on-a-condition" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> I want a command to be available only based on a condition. For example I want the “werewolf”
command to only be available on a full moon, from midnight to three in-game time.</p>
<p><strong>A:</strong> This is easiest accomplished by putting the “werewolf” command on the Character as normal,
but to <a class="reference internal" href="../Components/Locks.html"><span class="doc std std-doc">lock</span></a> it with the “cmd” type lock. Only if the “cmd” lock type is passed will the
<p><strong>A:</strong> This is easiest accomplished by putting the “werewolf” command on the Character as normal, but to <a class="reference internal" href="../Components/Locks.html"><span class="doc std std-doc">lock</span></a> it with the “cmd” type lock. Only if the “cmd” lock type is passed will the
command be available.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in mygame/commands/command.py</span>
@ -264,8 +216,7 @@ command be available.</p>
<span class="c1"># ...</span>
</pre></div>
</div>
<p>Add this to the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.html"><span class="doc std std-doc">default cmdset as usual</span></a>. The <code class="docutils literal notranslate"><span class="pre">is_full_moon</span></code> <a class="reference internal" href="../Components/Locks.html#lock-functions"><span class="std std-doc">lock
function</span></a> does not yet exist. We must create that:</p>
<p>Add this to the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.html"><span class="doc std std-doc">default cmdset as usual</span></a>. The <code class="docutils literal notranslate"><span class="pre">is_full_moon</span></code> <a class="reference internal" href="../Components/Locks.html#lock-functions"><span class="std std-doc">lock function</span></a> does not yet exist. We must create that:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in mygame/server/conf/lockfuncs.py</span>
<span class="k">def</span> <span class="nf">is_full_moon</span><span class="p">(</span><span class="n">accessing_obj</span><span class="p">,</span> <span class="n">accessed_obj</span><span class="p">,</span>
@ -276,7 +227,7 @@ function</span></a> does not yet exist. We must create that:</p>
</pre></div>
</div>
<p>After a <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code>, the <code class="docutils literal notranslate"><span class="pre">werewolf</span></code> command will be available only at the right time, that is when the
<p>After a <code class="docutils literal notranslate"><span class="pre">reload</span></code>, the <code class="docutils literal notranslate"><span class="pre">werewolf</span></code> command will be available only at the right time, that is when the
<code class="docutils literal notranslate"><span class="pre">is_full_moon</span></code> lock function returns True.</p>
</section>
<section id="automatically-updating-code-when-reloading">
@ -299,43 +250,28 @@ you have your project in a configured Git environment, it’s a matter of automa
<span class="n">process</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">call</span><span class="p">([</span><span class="s2">&quot;git&quot;</span><span class="p">,</span> <span class="s2">&quot;pull&quot;</span><span class="p">],</span> <span class="n">shell</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</pre></div>
</div>
<p>That’s all. We call <code class="docutils literal notranslate"><span class="pre">subprocess</span></code> to execute a shell command (that code works on Windows and Linux,
assuming the current directory is your game directory, which is probably the case when you run
Evennia). <code class="docutils literal notranslate"><span class="pre">call</span></code> waits for the process to complete, because otherwise, Evennia would reload on
partially-modified code, which would be problematic.</p>
<p>Now, when you enter <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code> on your development server, the game repository is updated from the
configured remote repository (Github, for instance). Your development cycle could resemble
something like:</p>
<p>That’s all. We call <code class="docutils literal notranslate"><span class="pre">subprocess</span></code> to execute a shell command (that code works on Windows and Linux, assuming the current directory is your game directory, which is probably the case when you run Evennia). <code class="docutils literal notranslate"><span class="pre">call</span></code> waits for the process to complete, because otherwise, Evennia would reload on partially-modified code, which would be problematic.</p>
<p>Now, when you enter <code class="docutils literal notranslate"><span class="pre">reload</span></code> on your development server, the game repository is updated from the configured remote repository (Github, for instance). Your development cycle could resemble something like:</p>
<ol class="simple">
<li><p>Coding on the local machine.</p></li>
<li><p>Testing modifications.</p></li>
<li><p>Committing once, twice or more (being sure the code is still working, unittests are pretty useful
here).</p></li>
<li><p>Committing once, twice or more (being sure the code is still working, unittests are pretty useful here).</p></li>
<li><p>When the time comes, login to the development server and run <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code>.</p></li>
</ol>
<p>The reloading might take one or two additional seconds, since Evennia will pull from your remote Git
repository. But it will reload on it and you will have your modifications ready, without needing
<p>The reloading might take one or two additional seconds, since Evennia will pull from your remote Git repository. But it will reload on it and you will have your modifications ready, without needing
connecting to your server using SSH or something similar.</p>
</section>
<section id="changing-all-exit-messages">
<h2>Changing all exit messages<a class="headerlink" href="#changing-all-exit-messages" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> How can I change the default exit messages to something like “XXX leaves east” or “XXX
arrives from the west”?</p>
<p><strong>A:</strong> the default exit messages are stored in two hooks, namely <code class="docutils literal notranslate"><span class="pre">announce_move_from</span></code> and
<code class="docutils literal notranslate"><span class="pre">announce_move_to</span></code>, on the <code class="docutils literal notranslate"><span class="pre">Character</span></code> typeclass (if what you want to change is the message other
characters will see when a character exits).</p>
<p>These two hooks provide some useful features to easily update the message to be displayed. They
take both the default message and mapping as argument. You can easily call the parent hook with
these information:</p>
<p><strong>A:</strong> the default exit messages are stored in two hooks, namely <code class="docutils literal notranslate"><span class="pre">announce_move_from</span></code> and <code class="docutils literal notranslate"><span class="pre">announce_move_to</span></code>, on the <code class="docutils literal notranslate"><span class="pre">Character</span></code> typeclass (if what you want to change is the message other characters will see when a character exits).</p>
<p>These two hooks provide some useful features to easily update the message to be displayed. They take both the default message and mapping as argument. You can easily call the parent hook with these information:</p>
<ul class="simple">
<li><p>The message represents the string of characters sent to characters in the room when a character
leaves.</p></li>
<li><p>The mapping is a dictionary containing additional mappings (you will probably not need it for
simple customization).</p></li>
<li><p>The message represents the string of characters sent to characters in the room when a character leaves.</p></li>
<li><p>The mapping is a dictionary containing additional mappings (you will probably not need it for simple customization).</p></li>
</ul>
<p>It is advisable to look in the <a class="reference external" href="https://github.com/evennia/evennia/tree/master/evennia/objects/objects.py">code of both
hooks</a>, and read the
hooks’ documentation. The explanations on how to quickly update the message are shown below:</p>
<p>It is advisable to look in the <a class="reference internal" href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultCharacter" title="evennia.objects.objects.DefaultCharacter"><span class="xref myst py py-class">code of both hooks</span></a>, and read the hooks’ documentation. The explanations on how to quickly update the message are shown below:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># In typeclasses/characters.py</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd">Characters</span>
@ -394,16 +330,12 @@ hooks’ documentation. The explanations on how to quickly update the message a
<span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">announce_move_to</span><span class="p">(</span><span class="n">source_location</span><span class="p">,</span> <span class="n">msg</span><span class="o">=</span><span class="s2">&quot;</span><span class="si">{object}</span><span class="s2"> arrives from the </span><span class="si">{exit}</span><span class="s2">.&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>We override both hooks, but call the parent hook to display a different message. If you read the
provided docstrings, you will better understand why and how we use mappings (information between
braces). You can provide additional mappings as well, if you want to set a verb to move, for
instance, or other, extra information.</p>
<p>We override both hooks, but call the parent hook to display a different message. If you read the provided docstrings, you will better understand why and how we use mappings (information between braces). You can provide additional mappings as well, if you want to set a verb to move, for instance, or other, extra information.</p>
</section>
<section id="add-parsing-with-the-to-delimiter">
<h2>Add parsing with the “to” delimiter<a class="headerlink" href="#add-parsing-with-the-to-delimiter" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> How do I change commands to undestand say <code class="docutils literal notranslate"><span class="pre">give</span> <span class="pre">obj</span> <span class="pre">to</span> <span class="pre">target</span></code> as well as the default <code class="docutils literal notranslate"><span class="pre">give</span> <span class="pre">obj</span> <span class="pre">=</span> <span class="pre">target</span></code>?</p>
<p><strong>A:</strong> You can make change the default <code class="docutils literal notranslate"><span class="pre">MuxCommand</span></code> parent with your own class making a small change
in its <code class="docutils literal notranslate"><span class="pre">parse</span></code> method:</p>
<p><strong>A:</strong> You can make change the default <code class="docutils literal notranslate"><span class="pre">MuxCommand</span></code> parent with your own class making a small change in its <code class="docutils literal notranslate"><span class="pre">parse</span></code> method:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="c1"># in mygame/commands/command.py</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">class</span> <span class="nc">MuxCommand</span><span class="p">(</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">MuxCommand</span><span class="p">):</span>
@ -418,39 +350,9 @@ in its <code class="docutils literal notranslate"><span class="pre">parse</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">COMMAND_DEFAULT_CLASS</span> <span class="o">=</span> <span class="s2">&quot;commands.command.MuxCommand&quot;</span>
</pre></div>
</div>
<p>Do a <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code> and all default commands will now use your new tweaked parent class. A copy of the
<p>Do a <code class="docutils literal notranslate"><span class="pre">reload</span></code> and all default commands will now use your new tweaked parent class. A copy of the
MuxCommand class is also found commented-out in the <code class="docutils literal notranslate"><span class="pre">mygame/commands/command.py</span></code> file.</p>
</section>
<section id="store-last-used-session-ip-address">
<h2>Store last used session IP address<a class="headerlink" href="#store-last-used-session-ip-address" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> If a user has already logged out of an Evennia account, their IP is no longer visible to
staff that wants to ban-by-ip (instead of the user) with <code class="docutils literal notranslate"><span class="pre">&#64;ban/ip</span></code>?</p>
<p><strong>A:</strong> One approach is to write the IP from the last session onto the “account” account object.</p>
<p><code class="docutils literal notranslate"><span class="pre">typeclasses/accounts.py</span></code></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">def</span> <span class="nf">at_post_login</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">session</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">at_post_login</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sessions</span><span class="o">.</span><span class="n">all</span><span class="p">()[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">address</span>
</pre></div>
</div>
<p>Adding timestamp for login time and appending to a list to keep the last N login IP addresses and
timestamps is possible, also. Additionally, if you don’t want the list to grow beyond a
<code class="docutils literal notranslate"><span class="pre">do_not_exceed</span></code> length, conditionally pop a value after you’ve added it, if the length has grown too
long.</p>
<p><strong>NOTE:</strong> You’ll need to add <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">time</span></code> to generate the login timestamp.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">def</span> <span class="nf">at_post_login</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">session</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">at_post_login</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="n">do_not_exceed</span> <span class="o">=</span> <span class="mi">24</span> <span class="c1"># Keep the last two dozen entries</span>
<span class="n">session</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sessions</span><span class="o">.</span><span class="n">all</span><span class="p">()[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="c1"># Most recent session</span>
<span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span> <span class="o">=</span> <span class="p">[]</span>
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="p">(</span><span class="n">session</span><span class="o">.</span><span class="n">address</span><span class="p">,</span> <span class="nb">int</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">())))</span>
<span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span><span class="p">)</span> <span class="o">&gt;</span> <span class="n">do_not_exceed</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span>
</pre></div>
</div>
<p>This only stores the data. You may want to interface the <code class="docutils literal notranslate"><span class="pre">&#64;ban</span></code> command or make a menu-driven viewer
for staff to browse the list and display how long ago the login occurred.</p>
</section>
<section id="non-latin-characters-in-evtable">
<h2>Non-latin characters in EvTable<a class="headerlink" href="#non-latin-characters-in-evtable" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> When using e.g. Chinese characters in EvTable, some lines appear to be too wide, for example</p>
@ -461,11 +363,7 @@ for staff to browse the list and display how long ago the login occurred.</p>
<span class="o">+~~~~~~+~~~~~~+</span>
</pre></div>
</div>
<p><strong>A:</strong> The reason for this is because certain non-latin characters are <em>visually</em> much wider than
their len() suggests. There is little Evennia can (reliably) do about this. If you are using such
characters, you need to make sure to use a suitable mono-spaced font where are width are equal. You
can set this in your web client and need to recommend it for telnet-client users. See <a class="reference external" href="https://github.com/evennia/evennia/issues/1522">this
discussion</a> where some suitable fonts are suggested.</p>
<p><strong>A:</strong> The reason for this is because certain non-latin characters are <em>visually</em> much wider than their len() suggests. There is little Evennia can (reliably) do about this. If you are using such characters, you need to make sure to use a suitable mono-spaced font where are width are equal. You can set this in your web client and need to recommend it for telnet-client users. See <a class="reference external" href="https://github.com/evennia/evennia/issues/1522">this discussion</a> where some suitable fonts are suggested.</p>
</section>
</section>
@ -485,10 +383,10 @@ discussion</a> where some suitable fonts are suggested.</p>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Debugging.html" title="Debugging"
<a href="Quirks.html" title="Quirks"
>next</a> |</li>
<li class="right" >
<a href="Coding-Introduction.html" title="Coding Introduction"
<a href="Evennia-Code-Style.html" title="Evennia Code Style"
>previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>

268
docs/1.0-dev/Coding/Coding-Introduction.html
View file

@ -1,268 +0,0 @@
<!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>Coding Introduction &#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" />
<link rel="next" title="Coding FAQ" href="Coding-FAQ.html" />
<link rel="prev" title="Updating Your Game" href="Updating-Your-Game.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="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Updating-Your-Game.html" title="Updating Your Game"
accesskey="P">previous</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-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Coding Introduction</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Coding Introduction</a><ul>
<li><a class="reference internal" href="#start-with-the-tutorial">Start with the tutorial</a></li>
<li><a class="reference internal" href="#explore-evennia-interactively">Explore Evennia interactively</a><ul>
<li><a class="reference internal" href="#jupyter-notebook-support">Jupyter Notebook Support</a></li>
<li><a class="reference internal" href="#more-exploration">More exploration</a></li>
</ul>
</li>
<li><a class="reference internal" href="#use-a-python-syntax-checker">Use a python syntax checker</a></li>
<li><a class="reference internal" href="#plan-before-you-code">Plan before you code</a></li>
<li><a class="reference internal" href="#code-in-your-game-folder-not-in-the-evennia-repository">Code in your game folder, not in the evennia/ repository</a></li>
<li><a class="reference internal" href="#learn-to-read-tracebacks">Learn to read tracebacks</a></li>
<li><a class="reference internal" href="#docs-are-here-to-help-you">Docs are here to help you</a></li>
<li><a class="reference internal" href="#the-most-important-point">The most important point</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Updating-Your-Game.html"
title="previous chapter">Updating Your Game</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Coding-FAQ.html"
title="next chapter">Coding FAQ</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Coding/Coding-Introduction.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="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>Versions</h3>
<ul>
<li><a href="Coding-Introduction.html">1.0-dev (develop branch)</a></li>
<ul>
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="coding-introduction">
<h1>Coding Introduction<a class="headerlink" href="#coding-introduction" title="Permalink to this headline"></a></h1>
<p>Evennia allows for a lot of freedom when designing your game - but to code efficiently you still
need to adopt some best practices as well as find a good place to start to learn.</p>
<p>Here are some pointers to get you going.</p>
<section id="start-with-the-tutorial">
<h2>Start with the tutorial<a class="headerlink" href="#start-with-the-tutorial" title="Permalink to this headline"></a></h2>
<p>It’s highly recommended that you jump in on the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Overview.html"><span class="doc std std-doc">Starting Tutorial</span></a>. Even if
you only the beginning or some part of it, it covers much of the things needed to get started, including giving you are first introduction to Python.</p>
</section>
<section id="explore-evennia-interactively">
<h2>Explore Evennia interactively<a class="headerlink" href="#explore-evennia-interactively" title="Permalink to this headline"></a></h2>
<p>As mentioned in the Starting tutorial, it’s a good idea to use <a class="reference external" href="https://ipython.org/">ipython</a> to explore things using a python shell:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># [open a new console/terminal]
cd mygame
evennia shell
</pre></div>
</div>
<p>This will open an Evennia-aware python shell (using ipython). From within this shell, try</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>import evennia
evennia.&lt;TAB&gt;
</pre></div>
</div>
<section id="jupyter-notebook-support">
<h3>Jupyter Notebook Support<a class="headerlink" href="#jupyter-notebook-support" title="Permalink to this headline"></a></h3>
<p>You can also explore evennia interactively in a <a class="reference external" href="https://jupyter.readthedocs.io/en/latest/index.html">Jupyter notebook</a>. This offers
an in-browser view of your code similar to Matlab or similar programs. There are
a few extra steps that must be taken in order for this to work:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># [open a new console/terminal]
# [activate your evennia virtualenv in this console/terminal]
cd evennia
pip install -r requirements_extra.txt # if not done already above
</pre></div>
</div>
<p>Next, <code class="docutils literal notranslate"><span class="pre">cd</span></code> to your game folder. <em>It’s important that you are in the <em>root</em> of this folder for the next command</em>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia shell_plus --notebook &amp;
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">&amp;</span></code> at the end starts the process as a background process on Linux/Unix.
Skip it if your OS doesn’t support this syntax. Your browser should now open
with the Jupyter interface. If not, open a browser to the link given on the
command line.</p>
<p>In the window, open the <code class="docutils literal notranslate"><span class="pre">new</span></code> menu in the top right and start a <code class="docutils literal notranslate"><span class="pre">Django</span> <span class="pre">Shell-Plus</span></code> notebook (or
open an existing one if you had one from before). In the first cell you must initialize
Evennia like so:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">evennia</span>
<span class="n">evennia</span><span class="o">.</span><span class="n">_init</span><span class="p">()</span>
</pre></div>
</div>
<p><em>Note that the above initialization must be run every time a new new notebook/kernel is started or restarted.</em></p>
<p>After this you can import and access all of the Evennia system, same as with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">shell</span></code>.</p>
</section>
<section id="more-exploration">
<h3>More exploration<a class="headerlink" href="#more-exploration" title="Permalink to this headline"></a></h3>
<p>You can complement your exploration by peeking at the sections of the much more detailed
<a class="reference internal" href="../Components/Components-Overview.html"><span class="doc std std-doc">Evennia Component overview</span></a>. The <a class="reference internal" href="../Howtos/Howtos-Overview.html"><span class="doc std std-doc">Tutorials</span></a> section also contains a growing collection
of system- or implementation-specific help.</p>
</section>
</section>
<section id="use-a-python-syntax-checker">
<h2>Use a python syntax checker<a class="headerlink" href="#use-a-python-syntax-checker" title="Permalink to this headline"></a></h2>
<p>Evennia works by importing your own modules and running them as part of the server. Whereas Evennia
should just gracefully tell you what errors it finds, it can nevertheless be a good idea for you to
check your code for simple syntax errors <em>before</em> you load it into the running server. There are
many python syntax checkers out there. A fast and easy one is
<a class="reference external" href="https://pypi.python.org/pypi/pyflakes">pyflakes</a>, a more verbose one is
<a class="reference external" href="https://www.pylint.org/">pylint</a>. You can also check so that your code looks up to snuff using
<a class="reference external" href="https://pypi.python.org/pypi/pep8">pep8</a>. Even with a syntax checker you will not be able to catch
every possible problem - some bugs or problems will only appear when you actually run the code. But
using such a checker can be a good start to weed out the simple problems.</p>
</section>
<section id="plan-before-you-code">
<h2>Plan before you code<a class="headerlink" href="#plan-before-you-code" title="Permalink to this headline"></a></h2>
<p>Before you start coding away at your dream game, take a look at our <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part2/Beginner-Tutorial-Game-Planning.html"><span class="doc std std-doc">Game Planning</span></a>
page. It might hopefully help you avoid some common pitfalls and time sinks.</p>
</section>
<section id="code-in-your-game-folder-not-in-the-evennia-repository">
<h2>Code in your game folder, not in the evennia/ repository<a class="headerlink" href="#code-in-your-game-folder-not-in-the-evennia-repository" title="Permalink to this headline"></a></h2>
<p>As part of the Evennia setup you will create a game folder to host your game code. This is your
home. You should <em>never</em> need to modify anything in the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> library (anything you download
from us, really). You import useful functionality from here and if you see code you like, copy&amp;paste
it out into your game folder and edit it there.</p>
<p>If you find that Evennia doesn’t support some functionality you need, make a Feature Request about it. Same goes for bugs. If you add features or fix bugs yourself, please consider <a class="reference internal" href="../Contributing.html"><span class="doc std std-doc">Contributing</span></a> your changes upstream!</p>
</section>
<section id="learn-to-read-tracebacks">
<h2>Learn to read tracebacks<a class="headerlink" href="#learn-to-read-tracebacks" title="Permalink to this headline"></a></h2>
<p>Python is very good at reporting when and where things go wrong. A <em>traceback</em> shows everything you
need to know about crashing code. The text can be pretty long, but you usually are only interested
in the last bit, where it says what the error is and at which module and line number it happened -
armed with this info you can resolve most problems.</p>
<p>Evennia will usually not show the full traceback in-game though. Instead the server outputs errors
to the terminal/console from which you started Evennia in the first place. If you want more to show
in-game you can add <code class="docutils literal notranslate"><span class="pre">IN_GAME_ERRORS</span> <span class="pre">=</span> <span class="pre">True</span></code> to your settings file. This will echo most (but not all)
tracebacks both in-game as well as to the terminal/console. This is a potential security problem
though, so don’t keep this active when your game goes into production.</p>
<blockquote>
<div><p>A common confusing error is finding that objects in-game are suddenly of the type <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code>
rather than your custom typeclass. This happens when you introduce a critical Syntax error to the
module holding your custom class. Since such a module is not valid Python, Evennia can’t load it at
all. Instead of crashing, Evennia will then print the full traceback to the terminal/console and
temporarily fall back to the safe <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code> until you fix the problem and reload.</p>
</div></blockquote>
</section>
<section id="docs-are-here-to-help-you">
<h2>Docs are here to help you<a class="headerlink" href="#docs-are-here-to-help-you" title="Permalink to this headline"></a></h2>
<p>Some people find reading documentation extremely dull and shun it out of principle. That’s your
call, but reading docs really <em>does</em> help you, promise! Evennia’s documentation is pretty thorough
and knowing what is possible can often give you a lot of new cool game ideas. That said, if you
can’t find the answer in the docs, don’t be shy to ask questions! The <a class="reference external" href="https://sites.google.com/site/evenniaserver/discussions">discussion
group</a> and the <a class="reference external" href="https://webchat.freenode.net/?channels=evennia">irc
chat</a> are also there for you.</p>
</section>
<section id="the-most-important-point">
<h2>The most important point<a class="headerlink" href="#the-most-important-point" title="Permalink to this headline"></a></h2>
<p>And finally, of course, have fun!</p>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
>next</a> |</li>
<li class="right" >
<a href="Updating-Your-Game.html" title="Updating Your Game"
>previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Coding Introduction</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2022, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>

100
docs/1.0-dev/Coding/Coding-Overview.html
View file

@ -17,7 +17,7 @@
<link rel="shortcut 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="Version Control" href="Version-Control.html" />
<link rel="next" title="Coding using Version Control" href="Version-Control.html" />
<link rel="prev" title="Web Features" href="../Concepts/Web-Features.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,7 +30,7 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Version-Control.html" title="Version Control"
<a href="Version-Control.html" title="Coding using Version Control"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../Concepts/Web-Features.html" title="Web Features"
@ -62,8 +62,6 @@
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Coding and development help</a><ul>
<li><a class="reference internal" href="#setting-up-a-workflow">Setting up a workflow</a></li>
<li><a class="reference internal" href="#coding-away">Coding away</a></li>
<li><a class="reference internal" href="#evennia-changelog">Evennia Changelog</a></li>
<li><a class="reference internal" href="#third-party-integrations">Third-party integrations</a></li>
</ul>
@ -75,7 +73,7 @@
title="previous chapter">Web Features</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Version-Control.html"
title="next chapter">Version Control</a></p>
title="next chapter">Coding using Version Control</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -110,60 +108,15 @@
<h1>Coding and development help<a class="headerlink" href="#coding-and-development-help" title="Permalink to this headline"></a></h1>
<p>This documentation aims to help you set up a sane development environment to
make your game, also if you never coded before. If you are an experienced coder, much of this will be familiar to you, but some things may still be useful.</p>
<section id="setting-up-a-workflow">
<h2>Setting up a workflow<a class="headerlink" href="#setting-up-a-workflow" title="Permalink to this headline"></a></h2>
<p>See also the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Beginner-Tutorial-Overview.html"><span class="doc std std-doc">Beginner Tutorial</span></a>.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Version-Control.html">Version Control</a><ul>
<li class="toctree-l1"><a class="reference internal" href="Version-Control.html">Coding using Version Control</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#setting-up-git">Setting up Git</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#putting-your-game-folder-under-version-control">Putting your game folder under version control</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#forking-evennia">Forking Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#working-with-your-evennia-fork">Working with your Evennia fork</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#sharing-your-evennia-fixes-on-github">Sharing your Evennia fixes on Github</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#making-an-evennia-pull-request">Making an Evennia Pull Request</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#git-tips-and-tricks">GIT tips and tricks</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Updating-Your-Game.html">Updating Your Game</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Updating-Your-Game.html#updating-with-the-latest-evennia-code-changes">Updating with the latest Evennia code changes</a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Your-Game.html#upgrading-evennia-dependencies">Upgrading Evennia dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Your-Game.html#migrating-the-database-schema">Migrating the Database Schema</a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Your-Game.html#resetting-your-database">Resetting your database</a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Your-Game.html#more-about-schema-migrations">More about schema migrations</a></li>
</ul>
</li>
</ul>
</div>
</section>
<section id="coding-away">
<h2>Coding away<a class="headerlink" href="#coding-away" title="Permalink to this headline"></a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Coding-Introduction.html">Coding Introduction</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#start-with-the-tutorial">Start with the tutorial</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#explore-evennia-interactively">Explore Evennia interactively</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#use-a-python-syntax-checker">Use a python syntax checker</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#plan-before-you-code">Plan before you code</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#code-in-your-game-folder-not-in-the-evennia-repository">Code in your game folder, not in the evennia/ repository</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#learn-to-read-tracebacks">Learn to read tracebacks</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#docs-are-here-to-help-you">Docs are here to help you</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#the-most-important-point">The most important point</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Coding-FAQ.html">Coding FAQ</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#table-of-contents">Table of Contents</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#removing-default-commands">Removing default commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#preventing-character-from-moving-based-on-a-condition">Preventing character from moving based on a condition</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#reference-initiating-object-in-an-evmenu-command">Reference initiating object in an EvMenu command.</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#adding-color-to-default-evennia-channels">Adding color to default Evennia Channels</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#selectively-turn-off-commands-in-a-room">Selectively turn off commands in a room</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#select-command-based-on-a-condition">Select Command based on a condition</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#automatically-updating-code-when-reloading">Automatically updating code when reloading</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#changing-all-exit-messages">Changing all exit messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#add-parsing-with-the-to-delimiter">Add parsing with the “to” delimiter</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#store-last-used-session-ip-address">Store last used session IP address</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#non-latin-characters-in-evtable">Non-latin characters in EvTable</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#common-git-commands">Common Git commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#putting-your-game-dir-under-version-control">Putting your game dir under version control</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#contributing-to-evennia">Contributing to Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#troubleshooting">Troubleshooting</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Debugging.html">Debugging</a><ul>
@ -182,12 +135,30 @@ make your game, also if you never coded before. If you are an experienced coder,
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Profiling.html">Profiling</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Profiling.html#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="Profiling.html#simple-timer-tests">Simple timer tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="Profiling.html#using-cprofile">Using cProfile</a></li>
<li class="toctree-l2"><a class="reference internal" href="Profiling.html#the-dummyrunner">The Dummyrunner</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Evennia-Code-Style.html">Evennia Code Style</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Code-Style.html#main-code-style-specification">Main code style specification</a></li>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Code-Style.html#code-docstrings">Code Docstrings</a></li>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Code-Style.html#default-command-docstrings">Default Command Docstrings</a></li>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Code-Style.html#tools-for-auto-linting">Tools for auto-linting</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Coding-FAQ.html">Coding FAQ</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#removing-default-commands">Removing default commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#preventing-character-from-moving-based-on-a-condition">Preventing character from moving based on a condition</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#reference-initiating-object-in-an-evmenu-command">Reference initiating object in an EvMenu command.</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#selectively-turn-off-commands-in-a-room">Selectively turn off commands in a room</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#select-command-based-on-a-condition">Select Command based on a condition</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#automatically-updating-code-when-reloading">Automatically updating code when reloading</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#changing-all-exit-messages">Changing all exit messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#add-parsing-with-the-to-delimiter">Add parsing with the “to” delimiter</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#non-latin-characters-in-evtable">Non-latin characters in EvTable</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Quirks.html">Quirks</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Quirks.html#forgetting-to-use-reload-to-see-changes-to-your-typeclasses">Forgetting to use <code class="docutils literal notranslate"><span class="pre">reload</span></code> to see changes to your typeclasses</a></li>
<li class="toctree-l2"><a class="reference internal" href="Quirks.html#web-admin-to-create-new-account">Web admin to create new Account</a></li>
@ -200,7 +171,6 @@ make your game, also if you never coded before. If you are an experienced coder,
</li>
</ul>
</div>
</section>
<section id="evennia-changelog">
<h2>Evennia Changelog<a class="headerlink" href="#evennia-changelog" title="Permalink to this headline"></a></h2>
<div class="toctree-wrapper compound">
@ -242,18 +212,8 @@ make your game, also if you never coded before. If you are an experienced coder,
<h2>Third-party integrations<a class="headerlink" href="#third-party-integrations" title="Permalink to this headline"></a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Continuous-Integration.html">Continuous Integration</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Continuous-Integration.html#what-is-continuous-integration-ci">What is Continuous Integration (CI)?</a></li>
<li class="toctree-l2"><a class="reference internal" href="Continuous-Integration.html#list-of-continuous-integration-tools">List of continuous integration tools</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Setting-up-PyCharm.html">Setting up PyCharm with Evennia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Setting-up-PyCharm.html#setting-up-the-project-interpreter">Setting up the project interpreter</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setting-up-PyCharm.html#attaching-pycharm-debugger-to-evennia">Attaching PyCharm debugger to Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setting-up-PyCharm.html#setting-up-an-evennia-run-configuration">Setting up an Evennia run configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setting-up-PyCharm.html#alternative-run-configuration-utilizing-logfiles-as-source-of-data">Alternative run configuration - utilizing logfiles as source of data</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Continuous-Integration.html">Continuous Integration (CI)</a></li>
<li class="toctree-l1"><a class="reference internal" href="Setting-up-PyCharm.html">Setting up PyCharm with Evennia</a></li>
</ul>
</div>
</section>
@ -275,7 +235,7 @@ make your game, also if you never coded before. If you are an experienced coder,
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Version-Control.html" title="Version Control"
<a href="Version-Control.html" title="Coding using Version Control"
>next</a> |</li>
<li class="right" >
<a href="../Concepts/Web-Features.html" title="Web Features"

4
docs/1.0-dev/Coding/Continuous-Integration-TeamCity.html
View file

@ -37,7 +37,7 @@
accesskey="P">previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" accesskey="U">Continuous Integration</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" accesskey="U">Continuous Integration (CI)</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration - TeamCity (linux)</a></li>
</ul>
<div class="develop">develop branch</div>
@ -315,7 +315,7 @@ build steps could be added or removed at this point, adding some features like U
>previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" >Continuous Integration</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" >Continuous Integration (CI)</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration - TeamCity (linux)</a></li>
</ul>
<div class="develop">develop branch</div>

12
docs/1.0-dev/Coding/Continuous-Integration-Travis.html
View file

@ -18,7 +18,7 @@
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Continuous Integration - TeamCity (linux)" href="Continuous-Integration-TeamCity.html" />
<link rel="prev" title="Continuous Integration" href="Continuous-Integration.html" />
<link rel="prev" title="Continuous Integration (CI)" href="Continuous-Integration.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -33,11 +33,11 @@
<a href="Continuous-Integration-TeamCity.html" title="Continuous Integration - TeamCity (linux)"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Continuous-Integration.html" title="Continuous Integration"
<a href="Continuous-Integration.html" title="Continuous Integration (CI)"
accesskey="P">previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" accesskey="U">Continuous Integration</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" accesskey="U">Continuous Integration (CI)</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous integration with Travis</a></li>
</ul>
<div class="develop">develop branch</div>
@ -63,7 +63,7 @@
<script>$('#searchbox').show(0);</script>
<h4>Previous topic</h4>
<p class="topless"><a href="Continuous-Integration.html"
title="previous chapter">Continuous Integration</a></p>
title="previous chapter">Continuous Integration (CI)</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Continuous-Integration-TeamCity.html"
title="next chapter">Continuous Integration - TeamCity (linux)</a></p>
@ -151,11 +151,11 @@ You should be able to refer to that for making tests fitting your game.</p>
<a href="Continuous-Integration-TeamCity.html" title="Continuous Integration - TeamCity (linux)"
>next</a> |</li>
<li class="right" >
<a href="Continuous-Integration.html" title="Continuous Integration"
<a href="Continuous-Integration.html" title="Continuous Integration (CI)"
>previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" >Continuous Integration</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" >Continuous Integration (CI)</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous integration with Travis</a></li>
</ul>
<div class="develop">develop branch</div>

36
docs/1.0-dev/Coding/Continuous-Integration.html
View file

@ -6,7 +6,7 @@
<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>Continuous Integration &#8212; Evennia 1.0-dev documentation</title>
<title>Continuous Integration (CI) &#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>
@ -37,7 +37,7 @@
accesskey="P">previous</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-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration</a></li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration (CI)</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
@ -62,9 +62,8 @@
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Continuous Integration</a><ul>
<li><a class="reference internal" href="#what-is-continuous-integration-ci">What is Continuous Integration (CI)?</a></li>
<li><a class="reference internal" href="#list-of-continuous-integration-tools">List of continuous integration tools</a></li>
<li><a class="reference internal" href="#">Continuous Integration (CI)</a><ul>
<li><a class="reference internal" href="#list-of-ci-evennia-tutorials">List of CI Evennia tutorials</a></li>
</ul>
</li>
</ul>
@ -105,16 +104,10 @@
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="continuous-integration">
<h1>Continuous Integration<a class="headerlink" href="#continuous-integration" title="Permalink to this headline"></a></h1>
<p>One of the advantages of Evennia over traditional MU* development systems is that Evennia can
integrate into enterprise-level integration environments and source control.</p>
<section id="what-is-continuous-integration-ci">
<h2>What is Continuous Integration (CI)?<a class="headerlink" href="#what-is-continuous-integration-ci" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://www.thoughtworks.com/continuous-integration">Continuous Integration (CI)</a> is a development
practice that requires developers to integrate code into a shared repository.
Each check-in is then verified by an automated build, allowing teams to detect problems early. This
can be set up to safely deploy data to a production server only after tests have passed, for example.</p>
<section class="tex2jax_ignore mathjax_ignore" id="continuous-integration-ci">
<h1>Continuous Integration (CI)<a class="headerlink" href="#continuous-integration-ci" title="Permalink to this headline"></a></h1>
<p>One of the advantages of Evennia over traditional MU* development systems is that Evennia can integrate into enterprise-level integration environments and source control.</p>
<p><a class="reference external" href="https://www.thoughtworks.com/continuous-integration">Continuous Integration (CI)</a> is a development practice that requires developers to integrate code into a shared repository. Each check-in is then verified by an automated build, allowing teams to detect problems early. This can be set up to safely deploy data to a production server only after tests have passed, for example.</p>
<p>For Evennia, continuous integration allows an automated build process to:</p>
<ul class="simple">
<li><p>Pull down a latest build from Source Control.</p></li>
@ -124,19 +117,16 @@ can be set up to safely deploy data to a production server only after tests have
<li><p>Publish those files to the server directory</p></li>
<li><p>Reload the game.</p></li>
</ul>
</section>
<section id="list-of-continuous-integration-tools">
<h2>List of continuous integration tools<a class="headerlink" href="#list-of-continuous-integration-tools" title="Permalink to this headline"></a></h2>
<p>There are a lot of tools and services providing CI functionality. Here are a few that people have used
with Evennia:</p>
<section id="list-of-ci-evennia-tutorials">
<h2>List of CI Evennia tutorials<a class="headerlink" href="#list-of-ci-evennia-tutorials" title="Permalink to this headline"></a></h2>
<p>There are a lot of tools and services providing CI functionality. Here are a few that people have used with Evennia:</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Continuous-Integration-Travis.html">Continuous integration with Travis</a></li>
<li class="toctree-l1"><a class="reference internal" href="Continuous-Integration-TeamCity.html">Continuous Integration - TeamCity (linux)</a></li>
</ul>
</div>
<p><a class="reference external" href="https://www.atlassian.com/continuous-delivery/continuous-integration/tools">This is an overview of other tools</a>
(external link).</p>
<p><a class="reference external" href="https://www.atlassian.com/continuous-delivery/continuous-integration/tools">This is an overview of other tools</a> (external link).</p>
</section>
</section>
@ -163,7 +153,7 @@ with Evennia:</p>
>previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration</a></li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration (CI)</a></li>
</ul>
<div class="develop">develop branch</div>
</div>

87
docs/1.0-dev/Coding/Debugging.html
View file

@ -18,7 +18,7 @@
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Unit Testing" href="Unit-Testing.html" />
<link rel="prev" title="Coding FAQ" href="Coding-FAQ.html" />
<link rel="prev" title="Coding using Version Control" href="Version-Control.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -33,7 +33,7 @@
<a href="Unit-Testing.html" title="Unit Testing"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
<a href="Version-Control.html" title="Coding using Version Control"
accesskey="P">previous</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-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
@ -69,7 +69,6 @@
<li><a class="reference internal" href="#examining-variables">Examining variables</a></li>
<li><a class="reference internal" href="#executing-the-current-line">Executing the current line</a></li>
<li><a class="reference internal" href="#letting-the-program-run">Letting the program run</a></li>
<li><a class="reference internal" href="#stepping-through-a-function">Stepping through a function</a></li>
</ul>
</li>
<li><a class="reference internal" href="#cheat-sheet-of-pdb-pudb-commands">Cheat-sheet of pdb/pudb commands</a></li>
@ -78,8 +77,8 @@
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Coding-FAQ.html"
title="previous chapter">Coding FAQ</a></p>
<p class="topless"><a href="Version-Control.html"
title="previous chapter">Coding using Version Control</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Unit-Testing.html"
title="next chapter">Unit Testing</a></p>
@ -115,12 +114,8 @@
<section class="tex2jax_ignore mathjax_ignore" id="debugging">
<h1>Debugging<a class="headerlink" href="#debugging" title="Permalink to this headline"></a></h1>
<p>Sometimes, an error is not trivial to resolve. A few simple <code class="docutils literal notranslate"><span class="pre">print</span></code> statements is not enough to find
the cause of the issue. Running a <em>debugger</em> can then be very helpful and save a lot of time.
Debugging
means running Evennia under control of a special <em>debugger</em> program. This allows you to stop the
action at a given point, view the current state and step forward through the program to see how its
logic works.</p>
<p>Sometimes, an error is not trivial to resolve. A few simple <code class="docutils literal notranslate"><span class="pre">print</span></code> statements is not enough to find the cause of the issue. The traceback is not informative or even non-existing.</p>
<p>Running a <em>debugger</em> can then be very helpful and save a lot of time. Debugging means running Evennia under control of a special <em>debugger</em> program. This allows you to stop the action at a given point, view the current state and step forward through the program to see how its logic works.</p>
<p>Evennia natively supports these debuggers:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://docs.python.org/2/library/pdb.html">Pdb</a> is a part of the Python distribution and
@ -138,18 +133,14 @@ point.</p>
</pre></div>
</div>
</li>
<li><p>(Re-)start Evennia in interactive (foreground) mode with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code>. This is important -
without this step the debugger will not start correctly - it will start in this interactive
terminal.</p></li>
<li><p>Perform the steps that will trigger the line where you added the <code class="docutils literal notranslate"><span class="pre">set_trace()</span></code> call. The debugger
will start in the terminal from which Evennia was interactively started.</p></li>
<li><p>(Re-)start Evennia in interactive (foreground) mode with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code>. This is important - without this step the debugger will not start correctly - it will start in this interactive terminal.</p></li>
<li><p>Perform the steps that will trigger the line where you added the <code class="docutils literal notranslate"><span class="pre">set_trace()</span></code> call. The debugger will start in the terminal from which Evennia was interactively started.</p></li>
</ol>
<p>The <code class="docutils literal notranslate"><span class="pre">evennia.set_trace</span></code> function takes the following arguments:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">evennia</span><span class="o">.</span><span class="n">set_trace</span><span class="p">(</span><span class="n">debugger</span><span class="o">=</span><span class="s1">&#39;auto&#39;</span><span class="p">,</span> <span class="n">term_size</span><span class="o">=</span><span class="p">(</span><span class="mi">140</span><span class="p">,</span> <span class="mi">40</span><span class="p">))</span>
</pre></div>
</div>
<p>Here, <code class="docutils literal notranslate"><span class="pre">debugger</span></code> is one of <code class="docutils literal notranslate"><span class="pre">pdb</span></code>, <code class="docutils literal notranslate"><span class="pre">pudb</span></code> or <code class="docutils literal notranslate"><span class="pre">auto</span></code>. If <code class="docutils literal notranslate"><span class="pre">auto</span></code>, use <code class="docutils literal notranslate"><span class="pre">pudb</span></code> if available, otherwise
use <code class="docutils literal notranslate"><span class="pre">pdb</span></code>. The <code class="docutils literal notranslate"><span class="pre">term_size</span></code> tuple sets the viewport size for <code class="docutils literal notranslate"><span class="pre">pudb</span></code> only (it’s ignored by <code class="docutils literal notranslate"><span class="pre">pdb</span></code>).</p>
<p>Here, <code class="docutils literal notranslate"><span class="pre">debugger</span></code> is one of <code class="docutils literal notranslate"><span class="pre">pdb</span></code>, <code class="docutils literal notranslate"><span class="pre">pudb</span></code> or <code class="docutils literal notranslate"><span class="pre">auto</span></code>. If <code class="docutils literal notranslate"><span class="pre">auto</span></code>, use <code class="docutils literal notranslate"><span class="pre">pudb</span></code> if available, otherwise use <code class="docutils literal notranslate"><span class="pre">pdb</span></code>. The <code class="docutils literal notranslate"><span class="pre">term_size</span></code> tuple sets the viewport size for <code class="docutils literal notranslate"><span class="pre">pudb</span></code> only (it’s ignored by <code class="docutils literal notranslate"><span class="pre">pdb</span></code>).</p>
</section>
<section id="a-simple-example-using-pdb">
<h2>A simple example using pdb<a class="headerlink" href="#a-simple-example-using-pdb" title="Permalink to this headline"></a></h2>
@ -178,9 +169,7 @@ default cmdset. Then restart Evennia in interactive mode with <code class="docut
</pre></div>
</div>
<p>If you type <code class="docutils literal notranslate"><span class="pre">test</span></code> in your game, everything will freeze. You won’t get any feedback from the game,
and you won’t be able to enter any command (nor anyone else). It’s because the debugger has started
in your console, and you will find it here. Below is an example with <code class="docutils literal notranslate"><span class="pre">pdb</span></code>.</p>
<p>If you type <code class="docutils literal notranslate"><span class="pre">test</span></code> in your game, everything will freeze. You won’t get any feedback from the game, and you won’t be able to enter any command (nor anyone else). It’s because the debugger has started in your console, and you will find it here. Below is an example with <code class="docutils literal notranslate"><span class="pre">pdb</span></code>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">...</span>
<span class="o">&gt;</span> <span class="o">.../</span><span class="n">mygame</span><span class="o">/</span><span class="n">commands</span><span class="o">/</span><span class="n">command</span><span class="o">.</span><span class="n">py</span><span class="p">(</span><span class="mi">79</span><span class="p">)</span><span class="n">func</span><span class="p">()</span>
<span class="o">-&gt;</span> <span class="n">obj</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">)</span>
@ -191,8 +180,7 @@ in your console, and you will find it here. Below is an example with <code class
<p><code class="docutils literal notranslate"><span class="pre">pdb</span></code> notes where it has stopped execution and, what line is about to be executed (in our case, <code class="docutils literal notranslate"><span class="pre">obj</span> <span class="pre">=</span> <span class="pre">self.search(self.args)</span></code>), and ask what you would like to do.</p>
<section id="listing-surrounding-lines-of-code">
<h3>Listing surrounding lines of code<a class="headerlink" href="#listing-surrounding-lines-of-code" title="Permalink to this headline"></a></h3>
<p>When you have the <code class="docutils literal notranslate"><span class="pre">pdb</span></code> prompt <code class="docutils literal notranslate"><span class="pre">(Pdb)</span></code>, you can type in different commands to explore the code. The
first one you should know is <code class="docutils literal notranslate"><span class="pre">list</span></code> (you can type <code class="docutils literal notranslate"><span class="pre">l</span></code> for short):</p>
<p>When you have the <code class="docutils literal notranslate"><span class="pre">pdb</span></code> prompt <code class="docutils literal notranslate"><span class="pre">(Pdb)</span></code>, you can type in different commands to explore the code. The first one you should know is <code class="docutils literal notranslate"><span class="pre">list</span></code> (you can type <code class="docutils literal notranslate"><span class="pre">l</span></code> for short):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">Pdb</span><span class="p">)</span> <span class="n">l</span>
<span class="mi">43</span>
<span class="mi">44</span> <span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;test&quot;</span>
@ -208,17 +196,12 @@ first one you should know is <code class="docutils literal notranslate"><span cl
<span class="p">(</span><span class="n">Pdb</span><span class="p">)</span>
</pre></div>
</div>
<p>Okay, this didn’t do anything spectacular, but when you become more confident with <code class="docutils literal notranslate"><span class="pre">pdb</span></code> and find
yourself in lots of different files, you sometimes need to see what’s around in code. Notice that
there is a little arrow (<code class="docutils literal notranslate"><span class="pre">-&gt;</span></code>) before the line that is about to be executed.</p>
<p>This is important: <strong>about to be</strong>, not <strong>has just been</strong>. You need to tell <code class="docutils literal notranslate"><span class="pre">pdb</span></code> to go on (we’ll
soon see how).</p>
<p>Okay, this didn’t do anything spectacular, but when you become more confident with <code class="docutils literal notranslate"><span class="pre">pdb</span></code> and find yourself in lots of different files, you sometimes need to see what’s around in code. Notice that there is a little arrow (<code class="docutils literal notranslate"><span class="pre">-&gt;</span></code>) before the line that is about to be executed.</p>
<p>This is important: <strong>about to be</strong>, not <strong>has just been</strong>. You need to tell <code class="docutils literal notranslate"><span class="pre">pdb</span></code> to go on (we’ll soon see how).</p>
</section>
<section id="examining-variables">
<h3>Examining variables<a class="headerlink" href="#examining-variables" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal notranslate"><span class="pre">pdb</span></code> allows you to examine variables (or really, to run any Python instruction). It is very useful
to know the values of variables at a specific line. To see a variable, just type its name (as if
you were in the Python interpreter:</p>
<p><code class="docutils literal notranslate"><span class="pre">pdb</span></code> allows you to examine variables (or really, to run any Python instruction). It is very useful to know the values of variables at a specific line. To see a variable, just type its name (as if you were in the Python interpreter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">Pdb</span><span class="p">)</span> <span class="bp">self</span>
<span class="o">&lt;</span><span class="n">commands</span><span class="o">.</span><span class="n">command</span><span class="o">.</span><span class="n">CmdTest</span> <span class="nb">object</span> <span class="n">at</span> <span class="mh">0x045A0990</span><span class="o">&gt;</span>
<span class="p">(</span><span class="n">Pdb</span><span class="p">)</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span>
@ -253,26 +236,19 @@ shorten it by just typing <code class="docutils literal notranslate"><span class
<span class="p">(</span><span class="n">Pdb</span><span class="p">)</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">Pdb</span></code> is complaining that you try to call the <code class="docutils literal notranslate"><span class="pre">search</span></code> method on a command… whereas there’s no
<code class="docutils literal notranslate"><span class="pre">search</span></code> method on commands. The character executing the command is in <code class="docutils literal notranslate"><span class="pre">self.caller</span></code>, so we might
change our line:</p>
<p><code class="docutils literal notranslate"><span class="pre">Pdb</span></code> is complaining that you try to call the <code class="docutils literal notranslate"><span class="pre">search</span></code> method on a command… whereas there’s no <code class="docutils literal notranslate"><span class="pre">search</span></code> method on commands. The character executing the command is in <code class="docutils literal notranslate"><span class="pre">self.caller</span></code>, so we might change our line:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">obj</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="letting-the-program-run">
<h3>Letting the program run<a class="headerlink" href="#letting-the-program-run" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal notranslate"><span class="pre">pdb</span></code> is waiting to execute the same instruction… it provoked an error but it’s ready to try
again, just in case. We have fixed it in theory, but we need to reload, so we need to enter a
command. To tell <code class="docutils literal notranslate"><span class="pre">pdb</span></code> to terminate and keep on running the program, use the <code class="docutils literal notranslate"><span class="pre">continue</span></code> (or <code class="docutils literal notranslate"><span class="pre">c</span></code>)
command:</p>
<p><code class="docutils literal notranslate"><span class="pre">pdb</span></code> is waiting to execute the same instruction… it provoked an error but it’s ready to try again, just in case. We have fixed it in theory, but we need to reload, so we need to enter a command. To tell <code class="docutils literal notranslate"><span class="pre">pdb</span></code> to terminate and keep on running the program, use the <code class="docutils literal notranslate"><span class="pre">continue</span></code> (or <code class="docutils literal notranslate"><span class="pre">c</span></code>) command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">Pdb</span><span class="p">)</span> <span class="n">c</span>
<span class="o">...</span>
</pre></div>
</div>
<p>You see an error being caught, that’s the error we have fixed… or hope to have. Let’s reload the
game and try again. You need to run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code> again and then run <code class="docutils literal notranslate"><span class="pre">test</span></code> to get into the
command again.</p>
<p>You see an error being caught, that’s the error we have fixed… or hope to have. Let’s reload the game and try again. You need to run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code> again and then run <code class="docutils literal notranslate"><span class="pre">test</span></code> to get into the command again.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="o">.../</span><span class="n">mygame</span><span class="o">/</span><span class="n">commands</span><span class="o">/</span><span class="n">command</span><span class="o">.</span><span class="n">py</span><span class="p">(</span><span class="mi">79</span><span class="p">)</span><span class="n">func</span><span class="p">()</span>
<span class="o">-&gt;</span> <span class="n">obj</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">)</span>
<span class="p">(</span><span class="n">Pdb</span><span class="p">)</span>
@ -301,8 +277,7 @@ fix that bug too, it would be better):</p>
<span class="o">...</span>
</pre></div>
</div>
<p>Notice that you’ll have an error in the game this time. Let’s try with a valid parameter. I have
another character, <code class="docutils literal notranslate"><span class="pre">barkeep</span></code>, in this room:</p>
<p>Notice that you’ll have an error in the game this time. Let’s try with a valid parameter. I have another character, <code class="docutils literal notranslate"><span class="pre">barkeep</span></code>, in this room:</p>
<p><code class="docutils literal notranslate"><span class="pre">test</span> <span class="pre">barkeep</span></code></p>
<p>And again, the command freezes, and we have the debugger opened in the console.</p>
<p>Let’s execute this line right away:</p>
@ -324,32 +299,17 @@ another character, <code class="docutils literal notranslate"><span class="pre">
<span class="p">(</span><span class="n">Pdb</span><span class="p">)</span>
</pre></div>
</div>
<p>As an exercise, fix this error, reload and run the debugger again. Nothing better than some
experimenting!</p>
<p>As an exercise, fix this error, reload and run the debugger again. Nothing better than some experimenting!</p>
<p>Your debugging will often follow the same strategy:</p>
<ol class="simple">
<li><p>Receive an error you don’t understand.</p></li>
<li><p>Put a breaking point <strong>BEFORE</strong> the error occurs.</p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code></p></li>
<li><p>Run the code again and see the debugger open.</p></li>
<li><p>Run the program line by line,examining variables, checking the logic of instructions.</p></li>
<li><p>Run the program line by line, examining variables, checking the logic of instructions.</p></li>
<li><p>Continue and try again, each step a bit further toward the truth and the working feature.</p></li>
</ol>
</section>
<section id="stepping-through-a-function">
<h3>Stepping through a function<a class="headerlink" href="#stepping-through-a-function" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal notranslate"><span class="pre">n</span></code> is useful, but it will avoid stepping inside of functions if it can. But most of the time, when
we have an error we don’t understand, it’s because we use functions or methods in a way that wasn’t
intended by the developer of the API. Perhaps using wrong arguments, or calling the function in a
situation that would cause a bug. When we have a line in the debugger that calls a function or
method, we can “step” to examine it further. For instance, in the previous example, when <code class="docutils literal notranslate"><span class="pre">pdb</span></code> was
about to execute <code class="docutils literal notranslate"><span class="pre">obj</span> <span class="pre">=</span> <span class="pre">self.caller.search(self.args)</span></code>, we may want to see what happens inside of
the <code class="docutils literal notranslate"><span class="pre">search</span></code> method.</p>
<p>To do so, use the <code class="docutils literal notranslate"><span class="pre">step</span></code> (or <code class="docutils literal notranslate"><span class="pre">s</span></code>) command. This command will show you the definition of the
function/method and you can then use <code class="docutils literal notranslate"><span class="pre">n</span></code> as before to see it line-by-line. In our little example,
stepping through a function or method isn’t that useful, but when you have an impressive set of
commands, functions and so on, it might really be handy to examine some feature and make sure they
operate as planned.</p>
</section>
</section>
<section id="cheat-sheet-of-pdb-pudb-commands">
<h2>Cheat-sheet of pdb/pudb commands<a class="headerlink" href="#cheat-sheet-of-pdb-pudb-commands" title="Permalink to this headline"></a></h2>
@ -391,8 +351,7 @@ command is not needed much in <code class="docutils literal notranslate"><span c
</tr>
</tbody>
</table>
<p>If you want to learn more about debugging with Pdb, you will find an <a class="reference external" href="https://pymotw.com/3/pdb/">interesting tutorial on that
topic here</a>.</p>
<p>If you want to learn more about debugging with Pdb, you will find an <a class="reference external" href="https://pymotw.com/3/pdb/">interesting tutorial on that topic here</a>.</p>
</section>
</section>
@ -415,7 +374,7 @@ topic here</a>.</p>
<a href="Unit-Testing.html" title="Unit Testing"
>next</a> |</li>
<li class="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
<a href="Version-Control.html" title="Coding using Version Control"
>previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>

403
docs/1.0-dev/Coding/Evennia-Code-Style.html Normal file
View file

@ -0,0 +1,403 @@
<!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>Evennia Code Style &#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" />
<link rel="next" title="Coding FAQ" href="Coding-FAQ.html" />
<link rel="prev" title="Profiling" href="Profiling.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="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Profiling.html" title="Profiling"
accesskey="P">previous</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-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Evennia Code Style</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Evennia Code Style</a><ul>
<li><a class="reference internal" href="#main-code-style-specification">Main code style specification</a></li>
<li><a class="reference internal" href="#code-docstrings">Code Docstrings</a><ul>
<li><a class="reference internal" href="#module-docstrings">Module docstrings</a></li>
<li><a class="reference internal" href="#class-docstrings">Class docstrings</a></li>
<li><a class="reference internal" href="#function-method-docstrings">Function / method docstrings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#default-command-docstrings">Default Command Docstrings</a></li>
<li><a class="reference internal" href="#tools-for-auto-linting">Tools for auto-linting</a><ul>
<li><a class="reference internal" href="#black">black</a></li>
<li><a class="reference internal" href="#pycharm">PyCharm</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Profiling.html"
title="previous chapter">Profiling</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Coding-FAQ.html"
title="next chapter">Coding FAQ</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Coding/Evennia-Code-Style.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="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>Versions</h3>
<ul>
<li><a href="Evennia-Code-Style.html">1.0-dev (develop branch)</a></li>
<ul>
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="evennia-code-style">
<h1>Evennia Code Style<a class="headerlink" href="#evennia-code-style" title="Permalink to this headline"></a></h1>
<p>All code submitted or committed to the Evennia project should aim to follow the
guidelines outlined in <a class="reference external" href="http://www.python.org/dev/peps/pep-0008">Python PEP 8</a>. Keeping the code style uniform
makes it much easier for people to collaborate and read the code.</p>
<p>A good way to check if your code follows PEP8 is to use the <a class="reference external" href="https://pypi.python.org/pypi/pep8">PEP8 tool</a>
on your sources.</p>
<section id="main-code-style-specification">
<h2>Main code style specification<a class="headerlink" href="#main-code-style-specification" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p>4-space indentation, NO TABS!</p></li>
<li><p>Unix line endings.</p></li>
<li><p>100 character line widths</p></li>
<li><p>CamelCase is only used for classes, nothing else.</p></li>
<li><p>All non-global variable names and all function names are to be
lowercase, words separated by underscores. Variable names should
always be more than two letters long.</p></li>
<li><p>Module-level global variables (only) are to be in CAPITAL letters.</p></li>
<li><p>Imports should be done in this order:</p>
<ul>
<li><p>Python modules (builtins and standard library)</p></li>
<li><p>Twisted modules</p></li>
<li><p>Django modules</p></li>
<li><p>Evennia library modules (<code class="docutils literal notranslate"><span class="pre">evennia</span></code>)</p></li>
<li><p>Evennia contrib modules (<code class="docutils literal notranslate"><span class="pre">evennia.contrib</span></code>)</p></li>
</ul>
</li>
<li><p>All modules, classes, functions and methods should have doc strings formatted
as outlined below.</p></li>
<li><p>All default commands should have a consistent docstring formatted as
outlined below.</p></li>
</ul>
</section>
<section id="code-docstrings">
<h2>Code Docstrings<a class="headerlink" href="#code-docstrings" title="Permalink to this headline"></a></h2>
<p>All modules, classes, functions and methods should have docstrings
formatted with <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html">Google style</a> -inspired indents, using
<a class="reference external" href="https://help.github.com/articles/github-flavored-markdown/">Markdown</a> formatting where needed. Evennia’s <code class="docutils literal notranslate"><span class="pre">api2md</span></code>
parser will use this to create pretty API documentation.</p>
<section id="module-docstrings">
<h3>Module docstrings<a class="headerlink" href="#module-docstrings" title="Permalink to this headline"></a></h3>
<p>Modules should all start with at least a few lines of docstring at
their top describing the contents and purpose of the module.</p>
<p>Example of module docstring (top of file):</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">This module handles the creation of `Objects` that</span>
<span class="sd">are useful in the game ...</span>
<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>Sectioning (<code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">title</span></code>, <code class="docutils literal notranslate"><span class="pre">##</span> <span class="pre">subtile</span></code> etc) should not be used in
freeform docstrings - this will confuse the sectioning of the auto
documentation page and the auto-api will create this automatically.
Write just the section name bolded on its own line to mark a section.
Beyond sections markdown should be used as needed to format
the text.</p>
<p>Code examples should use <a class="reference external" href="https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting">multi-line syntax highlighting</a>
to mark multi-line code blocks, using the “python” identifier. Just
indenting code blocks (common in markdown) will not produce the
desired look.</p>
<p>When using any code tags (inline or blocks) it’s recommended that you
don’t let the code extend wider than about 70 characters or it will
need to be scrolled horizontally in the wiki (this does not affect any
other text, only code).</p>
</section>
<section id="class-docstrings">
<h3>Class docstrings<a class="headerlink" href="#class-docstrings" title="Permalink to this headline"></a></h3>
<p>The root class docstring should describe the over-arching use of the
class. It should usually not describe the exact call sequence nor list
important methods, this tends to be hard to keep updated as the API
develops. Don’t use section markers (<code class="docutils literal notranslate"><span class="pre">#</span></code>, <code class="docutils literal notranslate"><span class="pre">##</span></code> etc).</p>
<p>Example of class docstring:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> This class describes the creation of `Objects`. It is useful</span>
<span class="sd"> in many situations, such as ...</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
</section>
<section id="function-method-docstrings">
<h3>Function / method docstrings<a class="headerlink" href="#function-method-docstrings" title="Permalink to this headline"></a></h3>
<p>Example of function or method docstring:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span>
<span class="k">def</span> <span class="nf">funcname</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">,</span> <span class="n">d</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> This is a brief introduction to the function/class/method</span>
<span class="sd"> Args:</span>
<span class="sd"> a (str): This is a string argument that we can talk about</span>
<span class="sd"> over multiple lines.</span>
<span class="sd"> b (int or str): Another argument.</span>
<span class="sd"> c (list): A list argument.</span>
<span class="sd"> d (bool, optional): An optional keyword argument.</span>
<span class="sd"> Keyword Args:</span>
<span class="sd"> test (list): A test keyword.</span>
<span class="sd"> Returns:</span>
<span class="sd"> str: The result of the function.</span>
<span class="sd"> Raises:</span>
<span class="sd"> RuntimeException: If there is a critical error,</span>
<span class="sd"> this is raised.</span>
<span class="sd"> IOError: This is only raised if there is a</span>
<span class="sd"> problem with the database.</span>
<span class="sd"> Notes:</span>
<span class="sd"> This is an example function. If `d=True`, something</span>
<span class="sd"> amazing will happen.</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>The syntax is very “loose” but the indentation matters. That is, you
should end the block headers (like <code class="docutils literal notranslate"><span class="pre">Args:</span></code>) with a line break followed by
an indent. When you need to break a line you should start the next line
with another indent. For consistency with the code we recommend all
indents to be 4 spaces wide (no tabs!).</p>
<p>Here are all the supported block headers:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Args</span>
<span class="sd"> argname (freeform type): Description endind with period.</span>
<span class="sd"> Keyword Args:</span>
<span class="sd"> argname (freeform type): Description.</span>
<span class="sd"> Returns/Yields:</span>
<span class="sd"> type: Description.</span>
<span class="sd"> Raises:</span>
<span class="sd"> Exceptiontype: Description.</span>
<span class="sd"> Notes/Note/Examples/Example:</span>
<span class="sd"> Freeform text.</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>Parts marked with “freeform” means that you can in principle put any
text there using any formatting except for sections markers (<code class="docutils literal notranslate"><span class="pre">#</span></code>, <code class="docutils literal notranslate"><span class="pre">##</span></code>
etc). You must also keep indentation to mark which block you are part
of. You should normally use the specified format rather than the
freeform counterpart (this will produce nicer output) but in some
cases the freeform may produce a more compact and readable result
(such as when describing an <code class="docutils literal notranslate"><span class="pre">*args</span></code> or <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> statement in general
terms). The first <code class="docutils literal notranslate"><span class="pre">self</span></code> argument of class methods should never be
documented.</p>
<p>Note that</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">Args:</span>
<span class="sd"> argname (type, optional): Description.</span>
<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>and</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">Keyword Args:</span>
<span class="sd"> sargname (type): Description.</span>
<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>mean the same thing! Which one is used depends on the function or
method documented, but there are no hard rules; If there is a large
<code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> block in the function, using the <code class="docutils literal notranslate"><span class="pre">Keyword</span> <span class="pre">Args:</span></code> block may be a
good idea, for a small number of arguments though, just using <code class="docutils literal notranslate"><span class="pre">Args:</span></code>
and marking keywords as <code class="docutils literal notranslate"><span class="pre">optional</span></code> will shorten the docstring and make
it easier to read.</p>
</section>
</section>
<section id="default-command-docstrings">
<h2>Default Command Docstrings<a class="headerlink" href="#default-command-docstrings" title="Permalink to this headline"></a></h2>
<p>These represent a special case since Commands in Evennia use their class
docstrings to represent the in-game help entry for that command.</p>
<p>All the commands in the <em>default command</em> sets should have their doc-strings
formatted on a similar form. For contribs, this is loosened, but if there is
no particular reason to use a different form, one should aim to use the same
style for contrib-command docstrings as well.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Short header</span>
<span class="sd"> Usage:</span>
<span class="sd"> key[/switches, if any] &lt;mandatory args&gt; [optional] choice1||choice2||choice3</span>
<span class="sd"> Switches:</span>
<span class="sd"> switch1 - description</span>
<span class="sd"> switch2 - description</span>
<span class="sd"> Examples:</span>
<span class="sd"> Usage example and output</span>
<span class="sd"> Longer documentation detailing the command.</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Two spaces are used for <em>indentation</em> in all default commands.</p></li>
<li><p>Square brackets <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">]</span></code> surround <em>optional, skippable arguments</em>.</p></li>
<li><p>Angled brackets <code class="docutils literal notranslate"><span class="pre">&lt;</span> <span class="pre">&gt;</span></code> surround a <em>description</em> of what to write rather than the exact syntax.</p></li>
<li><p>Explicit choices are separated by <code class="docutils literal notranslate"><span class="pre">|</span></code>. To avoid this being parsed as a color code, use <code class="docutils literal notranslate"><span class="pre">||</span></code> (this
will come out as a single <code class="docutils literal notranslate"><span class="pre">|</span></code>) or put spaces around the character (“<code class="docutils literal notranslate"><span class="pre">|</span></code>”) if there’s plenty of room.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">Switches</span></code> and <code class="docutils literal notranslate"><span class="pre">Examples</span></code> blocks are optional and based on the Command.</p></li>
</ul>
<p>Here is the <code class="docutils literal notranslate"><span class="pre">nick</span></code> command as an example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Define a personal alias/nick</span>
<span class="sd"> Usage:</span>
<span class="sd"> nick[/switches] &lt;nickname&gt; = [&lt;string&gt;]</span>
<span class="sd"> alias &#39;&#39;</span>
<span class="sd"> Switches:</span>
<span class="sd"> object - alias an object</span>
<span class="sd"> account - alias an account</span>
<span class="sd"> clearall - clear all your aliases</span>
<span class="sd"> list - show all defined aliases (also &quot;nicks&quot; works)</span>
<span class="sd"> Examples:</span>
<span class="sd"> nick hi = say Hello, I&#39;m Sarah!</span>
<span class="sd"> nick/object tom = the tall man</span>
<span class="sd"> A &#39;nick&#39; is a personal shortcut you create for your own use [...]</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>For commands that <em>require arguments</em>, the policy is for it to return a <code class="docutils literal notranslate"><span class="pre">Usage:</span></code>
string if the command is entered without any arguments. So for such commands,
the Command body should contain something to the effect of</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Usage: nick[/switches] &lt;nickname&gt; = [&lt;string&gt;]&quot;</span><span class="p">)</span>
<span class="k">return</span>
</pre></div>
</div>
</section>
<section id="tools-for-auto-linting">
<h2>Tools for auto-linting<a class="headerlink" href="#tools-for-auto-linting" title="Permalink to this headline"></a></h2>
<section id="black">
<h3>black<a class="headerlink" href="#black" title="Permalink to this headline"></a></h3>
<p>Automatic pep8 compliant formatting and linting can be performed using the
<code class="docutils literal notranslate"><span class="pre">black</span></code> formatter:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>black --line-length 100
</pre></div>
</div>
</section>
<section id="pycharm">
<h3>PyCharm<a class="headerlink" href="#pycharm" title="Permalink to this headline"></a></h3>
<p>The Python IDE <a class="reference external" href="https://www.jetbrains.com/pycharm/">Pycharm</a> can auto-generate empty doc-string stubs. The
default is to use <code class="docutils literal notranslate"><span class="pre">reStructuredText</span></code> form, however. To change to Evennia’s
Google-style docstrings, follow <a class="reference external" href="https://www.jetbrains.com/help/pycharm/2016.3/python-integrated-tools.html">this guide</a>.</p>
</section>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
>next</a> |</li>
<li class="right" >
<a href="Profiling.html" title="Profiling"
>previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Evennia Code Style</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2022, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>

119
docs/1.0-dev/Coding/Profiling.html
View file

@ -17,7 +17,7 @@
<link rel="shortcut 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="Quirks" href="Quirks.html" />
<link rel="next" title="Evennia Code Style" href="Evennia-Code-Style.html" />
<link rel="prev" title="Unit Testing" href="Unit-Testing.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,7 +30,7 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Quirks.html" title="Quirks"
<a href="Evennia-Code-Style.html" title="Evennia Code Style"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Unit-Testing.html" title="Unit Testing"
@ -63,7 +63,6 @@
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Profiling</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#simple-timer-tests">Simple timer tests</a></li>
<li><a class="reference internal" href="#using-cprofile">Using cProfile</a><ul>
<li><a class="reference internal" href="#analyzing-the-profile">Analyzing the profile</a></li>
@ -81,8 +80,8 @@
<p class="topless"><a href="Unit-Testing.html"
title="previous chapter">Unit Testing</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Quirks.html"
title="next chapter">Quirks</a></p>
<p class="topless"><a href="Evennia-Code-Style.html"
title="next chapter">Evennia Code Style</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -115,24 +114,16 @@
<section class="tex2jax_ignore mathjax_ignore" id="profiling">
<h1>Profiling<a class="headerlink" href="#profiling" title="Permalink to this headline"></a></h1>
<p><em>This is considered an advanced topic mainly of interest to server developers.</em></p>
<section id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
<p>Sometimes it can be useful to try to determine just how efficient a particular
piece of code is, or to figure out if one could speed up things more than they
are. There are many ways to test the performance of Python and the running
server.</p>
<p>Before digging into this section, remember Donald Knuth’s
<a class="reference external" href="https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize">words of wisdom</a>:</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>This is considered an advanced topic. It’s mainly of interest to server developers.</p>
</div>
<p>Sometimes it can be useful to try to determine just how efficient a particular piece of code is, or to figure out if one could speed up things more than they are. There are many ways to test the performance of Python and the running server.</p>
<p>Before digging into this section, remember Donald Knuth’s <a class="reference external" href="https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize">words of wisdom</a>:</p>
<blockquote>
<div><p><em>[…]about 97% of the time: Premature optimization is the root of all evil</em>.</p>
</div></blockquote>
<p>That is, don’t start to try to optimize your code until you have actually
identified a need to do so. This means your code must actually be working before
you start to consider optimization. Optimization will also often make your code
more complex and harder to read. Consider readability and maintainability and
you may find that a small gain in speed is just not worth it.</p>
</section>
<p>That is, don’t start to try to optimize your code until you have actually identified a need to do so. This means your code must actually be working before you start to consider optimization. Optimization will also often make your code more complex and harder to read. Consider readability and maintainability and you may find that a small gain in speed is just not worth it.</p>
<section id="simple-timer-tests">
<h2>Simple timer tests<a class="headerlink" href="#simple-timer-tests" title="Permalink to this headline"></a></h2>
<p>Python’s <code class="docutils literal notranslate"><span class="pre">timeit</span></code> module is very good for testing small things. For example, in
@ -147,46 +138,24 @@ could use the following code:</p>
<span class="o">&lt;&lt;&lt;</span> <span class="mf">5.358283996582031</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">setup</span></code> keyword is used to set up things that should not be included in the
time measurement, like <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">=</span> <span class="pre">[]</span></code> in the first call.</p>
<p>By default the <code class="docutils literal notranslate"><span class="pre">timeit</span></code> function will re-run the given test 1000000 times and
returns the <em>total time</em> to do so (so <em>not</em> the average per test). A hint is to
not use this default for testing something that includes database writes - for
that you may want to use a lower number of repeats (say 100 or 1000) using the
<code class="docutils literal notranslate"><span class="pre">number=100</span></code> keyword.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">setup</span></code> keyword is used to set up things that should not be included in the time measurement, like <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">=</span> <span class="pre">[]</span></code> in the first call.</p>
<p>By default the <code class="docutils literal notranslate"><span class="pre">timeit</span></code> function will re-run the given test 1000000 times and returns the <em>total time</em> to do so (so <em>not</em> the average per test). A hint is to not use this default for testing something that includes database writes - for that you may want to use a lower number of repeats (say 100 or 1000) using the <code class="docutils literal notranslate"><span class="pre">number=100</span></code> keyword.</p>
<p>In the example above, we see that this number of calls, using a list comprehension is about twice as fast as building a list using <code class="docutils literal notranslate"><span class="pre">.append()</span></code>.</p>
</section>
<section id="using-cprofile">
<h2>Using cProfile<a class="headerlink" href="#using-cprofile" title="Permalink to this headline"></a></h2>
<p>Python comes with its own profiler, named cProfile (this is for cPython, no
tests have been done with <code class="docutils literal notranslate"><span class="pre">pypy</span></code> at this point). Due to the way Evennia’s
processes are handled, there is no point in using the normal way to start the
profiler (<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">cProfile</span> <span class="pre">evennia.py</span></code>). Instead you start the profiler
through the launcher:</p>
<p>Python comes with its own profiler, named cProfile (this is for cPython, no tests have been done with <code class="docutils literal notranslate"><span class="pre">pypy</span></code> at this point). Due to the way Evennia’s processes are handled, there is no point in using the normal way to start the profiler (<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">cProfile</span> <span class="pre">evennia.py</span></code>). Instead you start the profiler through the launcher:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia --profiler start
</pre></div>
</div>
<p>This will start Evennia with the Server component running (in daemon mode) under
cProfile. You could instead try <code class="docutils literal notranslate"><span class="pre">--profile</span></code> with the <code class="docutils literal notranslate"><span class="pre">portal</span></code> argument to
profile the Portal (you would then need to
<a class="reference internal" href="../Setup/Start-Stop-Reload.html"><span class="doc std std-doc">start the Server separately</span></a>).</p>
<p>Please note that while the profiler is running, your process will use a lot more
memory than usual. Memory usage is even likely to climb over time. So don’t
leave it running perpetually but monitor it carefully (for example using the
<code class="docutils literal notranslate"><span class="pre">top</span></code> command on Linux or the Task Manager’s memory display on Windows).</p>
<p>Once you have run the server for a while, you need to stop it so the profiler
can give its report. Do <em>not</em> kill the program from your task manager or by
sending it a kill signal - this will most likely also mess with the profiler.
Instead either use <code class="docutils literal notranslate"><span class="pre">evennia.py</span> <span class="pre">stop</span></code> or (which may be even better), use
<code class="docutils literal notranslate"><span class="pre">&#64;shutdown</span></code> from inside the game.</p>
<p>Once the server has fully shut down (this may be a lot slower than usual) you
will find that profiler has created a new file <code class="docutils literal notranslate"><span class="pre">mygame/server/logs/server.prof</span></code>.</p>
<p>This will start Evennia with the Server component running (in daemon mode) under cProfile. You could instead try <code class="docutils literal notranslate"><span class="pre">--profile</span></code> with the <code class="docutils literal notranslate"><span class="pre">portal</span></code> argument to profile the Portal (you would then need to <a class="reference internal" href="../Setup/Running-Evennia.html"><span class="doc std std-doc">start the Server separately</span></a>).</p>
<p>Please note that while the profiler is running, your process will use a lot more memory than usual. Memory usage is even likely to climb over time. So don’t leave it running perpetually but monitor it carefully (for example using the <code class="docutils literal notranslate"><span class="pre">top</span></code> command on Linux or the Task Manager’s memory display on Windows).</p>
<p>Once you have run the server for a while, you need to stop it so the profiler can give its report. Do <em>not</em> kill the program from your task manager or by sending it a kill signal - this will most likely also mess with the profiler. Instead either use <code class="docutils literal notranslate"><span class="pre">evennia.py</span> <span class="pre">stop</span></code> or (which may be even better), use <code class="docutils literal notranslate"><span class="pre">&#64;shutdown</span></code> from inside the game.</p>
<p>Once the server has fully shut down (this may be a lot slower than usual) you will find that profiler has created a new file <code class="docutils literal notranslate"><span class="pre">mygame/server/logs/server.prof</span></code>.</p>
<section id="analyzing-the-profile">
<h3>Analyzing the profile<a class="headerlink" href="#analyzing-the-profile" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">server.prof</span></code> file is a binary file. There are many ways to analyze and
display its contents, all of which has only been tested in Linux (If you are a
Windows/Mac user, let us know what works).</p>
<p>You can look at the contents of the profile file with Python’s in-built <code class="docutils literal notranslate"><span class="pre">pstats</span></code>
module in the evennia shell (it’s recommended you install <code class="docutils literal notranslate"><span class="pre">ipython</span></code> with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">ipython</span></code> in your virtualenv first, for prettier output):</p>
<p>The <code class="docutils literal notranslate"><span class="pre">server.prof</span></code> file is a binary file. There are many ways to analyze and display its contents, all of which has only been tested in Linux (If you are a Windows/Mac user, let us know what works).</p>
<p>You can look at the contents of the profile file with Python’s in-built <code class="docutils literal notranslate"><span class="pre">pstats</span></code> module in the evennia shell (it’s recommended you install <code class="docutils literal notranslate"><span class="pre">ipython</span></code> with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">ipython</span></code> in your virtualenv first, for prettier output):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia shell
</pre></div>
</div>
@ -199,9 +168,7 @@ module in the evennia shell (it’s recommended you install <code class="docutil
</pre></div>
</div>
<p>See the
<a class="reference external" href="https://docs.python.org/3/library/profile.html#instant-user-s-manual">Python profiling documentation</a>
for more information.</p>
<p>See the <a class="reference external" href="https://docs.python.org/3/library/profile.html#instant-user-s-manual">Python profiling documentation</a> for more information.</p>
<p>You can also visualize the data in various ways.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://pypi.org/project/RunSnakeRun/">Runsnake</a> visualizes the profile to
@ -214,21 +181,12 @@ KCachegrind work with Python profiles you also need the wrapper script
<code class="docutils literal notranslate"><span class="pre">pyprof2calltree</span></code> via <code class="docutils literal notranslate"><span class="pre">pip</span></code> whereas KCacheGrind is something you need to get
via your package manager or their homepage.</p></li>
</ul>
<p>How to analyze and interpret profiling data is not a trivial issue and depends
on what you are profiling for. Evennia being an asynchronous server can also
confuse profiling. Ask on the mailing list if you need help and be ready to be
able to supply your <code class="docutils literal notranslate"><span class="pre">server.prof</span></code> file for comparison, along with the exact
conditions under which it was obtained.</p>
<p>How to analyze and interpret profiling data is not a trivial issue and depends on what you are profiling for. Evennia being an asynchronous server can also confuse profiling. Ask on the mailing list if you need help and be ready to be able to supply your <code class="docutils literal notranslate"><span class="pre">server.prof</span></code> file for comparison, along with the exact conditions under which it was obtained.</p>
</section>
</section>
<section id="the-dummyrunner">
<h2>The Dummyrunner<a class="headerlink" href="#the-dummyrunner" title="Permalink to this headline"></a></h2>
<p>It is difficult to test “actual” game performance without having players in your
game. For this reason Evennia comes with the <em>Dummyrunner</em> system. The
Dummyrunner is a stress-testing system: a separate program that logs into your
game with simulated players (aka “bots” or “dummies”). Once connected, these
dummies will semi-randomly perform various tasks from a list of possible
actions. Use <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> to stop the Dummyrunner.</p>
<p>It is difficult to test “actual” game performance without having players in your game. For this reason Evennia comes with the <em>Dummyrunner</em> system. The Dummyrunner is a stress-testing system: a separate program that logs into your game with simulated players (aka “bots” or “dummies”). Once connected, these dummies will semi-randomly perform various tasks from a list of possible actions. Use <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> to stop the Dummyrunner.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>You should not run the Dummyrunner on a production database. It
@ -243,9 +201,7 @@ will spawn many objects and also needs to run with general permissions.
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> from evennia.server.profiling.settings_mixin import *
</pre></div>
</div>
<p>This will override your settings and disable Evennia’s rate limiters and
DoS-protections, which would otherwise block mass-connecting clients from
one IP. Notably, it will also change to a different (faster) password hasher.</p>
<p>This will override your settings and disable Evennia’s rate limiters and DoS-protections, which would otherwise block mass-connecting clients from one IP. Notably, it will also change to a different (faster) password hasher.</p>
</li>
<li><p>(recommended): Build a new database. If you use default Sqlite3 and want to
keep your existing database, just rename <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code> to
@ -260,28 +216,16 @@ be able to connect with an <em>existing</em> user since the password hasher chan
<p>Use <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> (or <code class="docutils literal notranslate"><span class="pre">Cmd-C</span></code>) to stop it.</p>
</li>
</ol>
<p>If you want to see what the dummies are actually doing you can run with a single
dummy:</p>
<p>If you want to see what the dummies are actually doing you can run with a single dummy:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia --dummyrunner 1
</pre></div>
</div>
<p>The inputs/outputs from the dummy will then be printed. By default the runner
uses the ‘looker’ profile, which just logs in and sends the ‘look’ command
over and over. To change the settings, copy the file
<code class="docutils literal notranslate"><span class="pre">evennia/server/profiling/dummyrunner_settings.py</span></code> to your <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/</span></code>
directory, then add this line to your settings file to use it in the new
location:</p>
<p>The inputs/outputs from the dummy will then be printed. By default the runner uses the ‘looker’ profile, which just logs in and sends the ‘look’ command over and over. To change the settings, copy the file <code class="docutils literal notranslate"><span class="pre">evennia/server/profiling/dummyrunner_settings.py</span></code> to your <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/</span></code> directory, then add this line to your settings file to use it in the new location:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>DUMMYRUNNER_SETTINGS_MODULE = &quot;server/conf/dummyrunner_settings.py&quot;
</pre></div>
</div>
<p>The dummyrunner settings file is a python code module in its own right - it
defines the actions available to the dummies. These are just tuples of command
strings (like “look here”) for the dummy to send to the server along with a
probability of them happening. The dummyrunner looks for a global variable
<code class="docutils literal notranslate"><span class="pre">ACTIONS</span></code>, a list of tuples, where the first two elements define the
commands for logging in/out of the server.</p>
<p>Below is a simplified minimal setup (the default settings file adds a lot more
functionality and info):</p>
<p>The dummyrunner settings file is a python code module in its own right - it defines the actions available to the dummies. These are just tuples of command strings (like “look here”) for the dummy to send to the server along with a probability of them happening. The dummyrunner looks for a global variable <code class="docutils literal notranslate"><span class="pre">ACTIONS</span></code>, a list of tuples, where the first two elements define the commands for logging in/out of the server.</p>
<p>Below is a simplified minimal setup (the default settings file adds a lot more functionality and info):</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># minimal dummyrunner setup file</span>
<span class="c1"># Time between each dummyrunner &quot;tick&quot;, in seconds. Each dummy will be called</span>
@ -325,8 +269,7 @@ functionality and info):</p>
</pre></div>
</div>
<p>At the bottom of the default file are a few default profiles you can test out
by just setting the <code class="docutils literal notranslate"><span class="pre">PROFILE</span></code> variable to one of the options.</p>
<p>At the bottom of the default file are a few default profiles you can test out by just setting the <code class="docutils literal notranslate"><span class="pre">PROFILE</span></code> variable to one of the options.</p>
<section id="dummyrunner-hints">
<h3>Dummyrunner hints<a class="headerlink" href="#dummyrunner-hints" title="Permalink to this headline"></a></h3>
<ul class="simple">
@ -372,7 +315,7 @@ For this, actual real-game testing is required.</p></li>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Quirks.html" title="Quirks"
<a href="Evennia-Code-Style.html" title="Evennia Code Style"
>next</a> |</li>
<li class="right" >
<a href="Unit-Testing.html" title="Unit Testing"

10
docs/1.0-dev/Coding/Quirks.html
View file

@ -18,7 +18,7 @@
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Changelog" href="Changelog.html" />
<link rel="prev" title="Profiling" href="Profiling.html" />
<link rel="prev" title="Coding FAQ" href="Coding-FAQ.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -33,7 +33,7 @@
<a href="Changelog.html" title="Changelog"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Profiling.html" title="Profiling"
<a href="Coding-FAQ.html" title="Coding FAQ"
accesskey="P">previous</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-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
@ -78,8 +78,8 @@
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Profiling.html"
title="previous chapter">Profiling</a></p>
<p class="topless"><a href="Coding-FAQ.html"
title="previous chapter">Coding FAQ</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Changelog.html"
title="next chapter">Changelog</a></p>
@ -258,7 +258,7 @@ package imports from.</p>
<a href="Changelog.html" title="Changelog"
>next</a> |</li>
<li class="right" >
<a href="Profiling.html" title="Profiling"
<a href="Coding-FAQ.html" title="Coding FAQ"
>previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>

62
docs/1.0-dev/Coding/Setting-up-PyCharm.html
View file

@ -66,7 +66,7 @@
<li><a class="reference internal" href="#setting-up-the-project-interpreter">Setting up the project interpreter</a></li>
<li><a class="reference internal" href="#attaching-pycharm-debugger-to-evennia">Attaching PyCharm debugger to Evennia</a></li>
<li><a class="reference internal" href="#setting-up-an-evennia-run-configuration">Setting up an Evennia run configuration</a></li>
<li><a class="reference internal" href="#alternative-run-configuration-utilizing-logfiles-as-source-of-data">Alternative run configuration - utilizing logfiles as source of data</a></li>
<li><a class="reference internal" href="#alternative-config-utilizing-logfiles-as-source-of-data">Alternative config - utilizing logfiles as source of data</a></li>
</ul>
</li>
</ul>
@ -109,16 +109,11 @@
<section class="tex2jax_ignore mathjax_ignore" id="setting-up-pycharm-with-evennia">
<h1>Setting up PyCharm with Evennia<a class="headerlink" href="#setting-up-pycharm-with-evennia" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="https://www.jetbrains.com/pycharm/">PyCharm</a> is a Python developer’s IDE from Jetbrains available
for Windows, Mac and Linux. It is a commercial product but offer free trials, a scaled-down
community edition and also generous licenses for OSS projects like Evennia.</p>
<p><a class="reference external" href="https://www.jetbrains.com/pycharm/">PyCharm</a> is a Python developer’s IDE from Jetbrains available for Windows, Mac and Linux. It is a commercial product but offer free trials, a scaled-down community edition and also generous licenses for OSS projects like Evennia.</p>
<blockquote>
<div><p>This page was originally tested on Windows (so use Windows-style path examples), but should work
the same for all platforms.</p>
<div><p>This page was originally tested on Windows (so use Windows-style path examples), but should work the same for all platforms.</p>
</div></blockquote>
<p>First, install Evennia on your local machine with [[Getting Started]]. If you’re new to PyCharm,
loading your project is as easy as selecting the <code class="docutils literal notranslate"><span class="pre">Open</span></code> option when PyCharm starts, and browsing to
your game folder (the one created with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">--init</span></code>). We refer to it as <code class="docutils literal notranslate"><span class="pre">mygame</span></code> here.</p>
<p>First, install Evennia on your local machine with [[Getting Started]]. If you’re new to PyCharm, loading your project is as easy as selecting the <code class="docutils literal notranslate"><span class="pre">Open</span></code> option when PyCharm starts, and browsing to your game folder (the one created with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">--init</span></code>). We refer to it as <code class="docutils literal notranslate"><span class="pre">mygame</span></code> here.</p>
<p>If you want to be able to examine evennia’s core code or the scripts inside your virtualenv, you’ll
need to add them to your project too:</p>
<ol class="simple">
@ -148,63 +143,42 @@ project is already configured in PyCharm.</p>
<p>Of course you can attach to the <code class="docutils literal notranslate"><span class="pre">portal</span></code> process as well. If you want to debug the Evennia launcher
or runner for some reason (or just learn how they work!), see Run Configuration below.</p>
<blockquote>
<div><p>NOTE: Whenever you reload Evennia, the old Server process will die and a new one start. So when
you restart you have to detach from the old and then reattach to the new process that was created.</p>
<div><p>NOTE: Whenever you reload Evennia, the old Server process will die and a new one start. So when you restart you have to detach from the old and then reattach to the new process that was created.</p>
</div></blockquote>
<blockquote>
<div><p>To make the process less tedious you can apply a filter in settings to show only the <a class="reference external" href="http://server.py">server.py</a>
process in the list. To do that navigate to: <code class="docutils literal notranslate"><span class="pre">Settings/Preferences</span> <span class="pre">|</span> <span class="pre">Build,</span> <span class="pre">Execution,</span> <span class="pre">Deployment</span> <span class="pre">|</span> <span class="pre">Python</span> <span class="pre">Debugger</span></code> and then in <code class="docutils literal notranslate"><span class="pre">Attach</span> <span class="pre">to</span> <span class="pre">process</span></code> field put in: <code class="docutils literal notranslate"><span class="pre">twistd.exe&quot;</span> <span class="pre">--nodaemon</span></code>. This is an
example for windows, I don’t have a working mac/linux box.
<img alt="Example process filter configuration" src="https://i.imgur.com/vkSheR8.png" /></p>
<div><p>To make the process less tedious you can apply a filter in settings to show only the <a class="reference external" href="http://server.py">server.py</a> process in the list. To do that navigate to: <code class="docutils literal notranslate"><span class="pre">Settings/Preferences</span> <span class="pre">|</span> <span class="pre">Build,</span> <span class="pre">Execution,</span> <span class="pre">Deployment</span> <span class="pre">|</span> <span class="pre">Python</span> <span class="pre">Debugger</span></code> and then in <code class="docutils literal notranslate"><span class="pre">Attach</span> <span class="pre">to</span> <span class="pre">process</span></code> field put in: <code class="docutils literal notranslate"><span class="pre">twistd.exe&quot;</span> <span class="pre">--nodaemon</span></code>. This is an example for windows, I don’t have a working mac/linux box.</p>
</div></blockquote>
<p><img alt="Example process filter configuration" src="https://i.imgur.com/vkSheR8.png" /></p>
</section>
<section id="setting-up-an-evennia-run-configuration">
<h2>Setting up an Evennia run configuration<a class="headerlink" href="#setting-up-an-evennia-run-configuration" title="Permalink to this headline"></a></h2>
<p>This configuration allows you to launch Evennia from inside PyCharm. Besides convenience, it also
allows suspending and debugging the evennia_launcher or evennia_runner at points earlier than you
could by running them externally and attaching. In fact by the time the server and/or portal are
running the launcher will have exited already.</p>
<p>This configuration allows you to launch Evennia from inside PyCharm. Besides convenience, it also allows suspending and debugging the evennia_launcher or evennia_runner at points earlier than you could by running them externally and attaching. In fact by the time the server and/or portal are running the launcher will have exited already.</p>
<ol class="simple">
<li><p>Go to <code class="docutils literal notranslate"><span class="pre">Run</span> <span class="pre">&gt;</span> <span class="pre">Edit</span> <span class="pre">Configutations...</span></code></p></li>
<li><p>Click the plus-symbol to add a new configuration and choose Python</p></li>
<li><p>Add the script: <code class="docutils literal notranslate"><span class="pre">\&lt;yourrepo\&gt;\evenv\Scripts\evennia_launcher.py</span></code> (substitute your virtualenv if
it’s not named <code class="docutils literal notranslate"><span class="pre">evenv</span></code>)</p></li>
<li><p>Add the script: <code class="docutils literal notranslate"><span class="pre">\&lt;yourrepo\&gt;\evenv\Scripts\evennia_launcher.py</span></code> (substitute your virtualenv if it’s not named <code class="docutils literal notranslate"><span class="pre">evenv</span></code>)</p></li>
<li><p>Set script parameters to: <code class="docutils literal notranslate"><span class="pre">start</span> <span class="pre">-l</span></code> (-l enables console logging)</p></li>
<li><p>Ensure the chosen interpreter is from your virtualenv</p></li>
<li><p>Set Working directory to your <code class="docutils literal notranslate"><span class="pre">mygame</span></code> folder (not evenv nor evennia)</p></li>
<li><p>You can refer to the PyCharm documentation for general info, but you’ll want to set at least a
config name (like “MyMUD start” or similar).</p></li>
<li><p>You can refer to the PyCharm documentation for general info, but you’ll want to set at least a config name (like “MyMUD start” or similar).</p></li>
</ol>
<p>Now set up a “stop” configuration by following the same steps as above, but set your Script
parameters to: stop (and name the configuration appropriately).</p>
<p>A dropdown box holding your new configurations should appear next to your PyCharm run button.
Select MyMUD start and press the debug icon to begin debugging. Depending on how far you let the
program run, you may need to run your “MyMUD stop” config to actually stop the server, before you’ll
be able start it again.</p>
<p>Now set up a “stop” configuration by following the same steps as above, but set your Script parameters to: stop (and name the configuration appropriately).</p>
<p>A dropdown box holding your new configurations should appear next to your PyCharm run button. Select MyMUD start and press the debug icon to begin debugging. Depending on how far you let the program run, you may need to run your “MyMUD stop” config to actually stop the server, before you’ll be able start it again.</p>
</section>
<section id="alternative-run-configuration-utilizing-logfiles-as-source-of-data">
<h2>Alternative run configuration - utilizing logfiles as source of data<a class="headerlink" href="#alternative-run-configuration-utilizing-logfiles-as-source-of-data" title="Permalink to this headline"></a></h2>
<p>This configuration takes a bit different approach as instead of focusing on getting the data back
through logfiles. Reason for that is this way you can easily separate data streams, for example you
rarely want to follow both server and portal at the same time, and this will allow it. This will
also make sure to stop the evennia before starting it, essentially working as reload command (it
will also include instructions how to disable that part of functionality). We will start by defining
a configuration that will stop evennia. This assumes that <code class="docutils literal notranslate"><span class="pre">upfire</span></code> is your pycharm project name, and
also the game name, hence the <code class="docutils literal notranslate"><span class="pre">upfire/upfire</span></code> path.</p>
<section id="alternative-config-utilizing-logfiles-as-source-of-data">
<h2>Alternative config - utilizing logfiles as source of data<a class="headerlink" href="#alternative-config-utilizing-logfiles-as-source-of-data" title="Permalink to this headline"></a></h2>
<p>This configuration takes a bit different approach as instead of focusing on getting the data back through logfiles. Reason for that is this way you can easily separate data streams, for example you rarely want to follow both server and portal at the same time, and this will allow it. This will also make sure to stop the evennia before starting it, essentially working as reload command (it will also include instructions how to disable that part of functionality). We will start by defining a configuration that will stop evennia. This assumes that <code class="docutils literal notranslate"><span class="pre">upfire</span></code> is your pycharm project name, and also the game name, hence the <code class="docutils literal notranslate"><span class="pre">upfire/upfire</span></code> path.</p>
<ol class="simple">
<li><p>Go to <code class="docutils literal notranslate"><span class="pre">Run</span> <span class="pre">&gt;</span> <span class="pre">Edit</span> <span class="pre">Configutations...</span></code>\</p></li>
<li><p>Click the plus-symbol to add a new configuration and choose the python interpreter to use (should
be project default)</p></li>
<li><p>Click the plus-symbol to add a new configuration and choose the python interpreter to use (should be project default)</p></li>
<li><p>Name the configuration as “stop evennia” and fill rest of the fields accordingly to the image:
<img alt="Stop run configuration" src="https://i.imgur.com/gbkXhlG.png" /></p></li>
<li><p>Press <code class="docutils literal notranslate"><span class="pre">Apply</span></code></p></li>
</ol>
<p>Now we will define the start/reload command that will make sure that evennia is not running already,
and then start the server in one go.</p>
<p>Now we will define the start/reload command that will make sure that evennia is not running already, and then start the server in one go.</p>
<ol class="simple">
<li><p>Go to <code class="docutils literal notranslate"><span class="pre">Run</span> <span class="pre">&gt;</span> <span class="pre">Edit</span> <span class="pre">Configutations...</span></code>\</p></li>
<li><p>Click the plus-symbol to add a new configuration and choose the python interpreter to use (should
be project default)</p></li>
<li><p>Click the plus-symbol to add a new configuration and choose the python interpreter to use (should be project default)</p></li>
<li><p>Name the configuration as “start evennia” and fill rest of the fields accordingly to the image:
<img alt="Start run configuration" src="https://i.imgur.com/5YEjeHq.png" /></p></li>
<li><p>Navigate to the <code class="docutils literal notranslate"><span class="pre">Logs</span></code> tab and add the log files you would like to follow. The picture shows

14
docs/1.0-dev/Coding/Unit-Testing.html
View file

@ -115,17 +115,9 @@
<section class="tex2jax_ignore mathjax_ignore" id="unit-testing">
<h1>Unit Testing<a class="headerlink" href="#unit-testing" title="Permalink to this headline"></a></h1>
<p><em>Unit testing</em> means testing components of a program in isolation from each other to make sure every
part works on its own before using it with others. Extensive testing helps avoid new updates causing
unexpected side effects as well as alleviates general code rot (a more comprehensive wikipedia
article on unit testing can be found <a class="reference external" href="https://en.wikipedia.org/wiki/Unit_test">here</a>).</p>
<p>A typical unit test set calls some function or method with a given input, looks at the result and
makes sure that this result looks as expected. Rather than having lots of stand-alone test programs,
Evennia makes use of a central <em>test runner</em>. This is a program that gathers all available tests all
over the Evennia source code (called <em>test suites</em>) and runs them all in one go. Errors and
tracebacks are reported.</p>
<p>By default Evennia only tests itself. But you can also add your own tests to your game code and have
Evennia run those for you.</p>
<p><em>Unit testing</em> means testing components of a program in isolation from each other to make sure every part works on its own before using it with others. Extensive testing helps avoid new updates causing unexpected side effects as well as alleviates general code rot (a more comprehensive wikipedia article on unit testing can be found <a class="reference external" href="https://en.wikipedia.org/wiki/Unit_test">here</a>).</p>
<p>A typical unit test set calls some function or method with a given input, looks at the result and makes sure that this result looks as expected. Rather than having lots of stand-alone test programs, Evennia makes use of a central <em>test runner</em>. This is a program that gathers all available tests all over the Evennia source code (called <em>test suites</em>) and runs them all in one go. Errors and tracebacks are reported.</p>
<p>By default Evennia only tests itself. But you can also add your own tests to your game code and have Evennia run those for you.</p>
<section id="running-the-evennia-test-suite">
<h2>Running the Evennia test suite<a class="headerlink" href="#running-the-evennia-test-suite" title="Permalink to this headline"></a></h2>
<p>To run the full Evennia test suite, go to your game folder and issue the command</p>

273
docs/1.0-dev/Coding/Updating-Your-Game.html
View file

@ -1,273 +0,0 @@
<!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>Updating Your Game &#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" />
<link rel="next" title="Coding Introduction" href="Coding-Introduction.html" />
<link rel="prev" title="Version Control" href="Version-Control.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="right" >
<a href="Coding-Introduction.html" title="Coding Introduction"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Version-Control.html" title="Version Control"
accesskey="P">previous</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-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Updating Your Game</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Updating Your Game</a><ul>
<li><a class="reference internal" href="#updating-with-the-latest-evennia-code-changes">Updating with the latest Evennia code changes</a></li>
<li><a class="reference internal" href="#upgrading-evennia-dependencies">Upgrading Evennia dependencies</a></li>
<li><a class="reference internal" href="#migrating-the-database-schema">Migrating the Database Schema</a></li>
<li><a class="reference internal" href="#resetting-your-database">Resetting your database</a></li>
<li><a class="reference internal" href="#more-about-schema-migrations">More about schema migrations</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Version-Control.html"
title="previous chapter">Version Control</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Coding-Introduction.html"
title="next chapter">Coding Introduction</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Coding/Updating-Your-Game.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="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>Versions</h3>
<ul>
<li><a href="Updating-Your-Game.html">1.0-dev (develop branch)</a></li>
<ul>
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="updating-your-game">
<h1>Updating Your Game<a class="headerlink" href="#updating-your-game" title="Permalink to this headline"></a></h1>
<p>Fortunately, it’s extremely easy to keep your Evennia server up-to-date. If you haven’t already, see
the <a class="reference internal" href="../Setup/Installation.html"><span class="doc std std-doc">Getting Started guide</span></a> and get everything running.</p>
<section id="updating-with-the-latest-evennia-code-changes">
<h2>Updating with the latest Evennia code changes<a class="headerlink" href="#updating-with-the-latest-evennia-code-changes" title="Permalink to this headline"></a></h2>
<p>Very commonly we make changes to the Evennia code to improve things. There are many ways to get told
when to update: You can subscribe to the RSS feed or manually check up on the feeds from
<a class="reference external" href="https://www.evennia.com">https://www.evennia.com</a>. You can also simply fetch the latest regularly.</p>
<p>When you’re wanting to apply updates, simply <code class="docutils literal notranslate"><span class="pre">cd</span></code> to your cloned <code class="docutils literal notranslate"><span class="pre">evennia</span></code> root directory and type:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> git pull
</pre></div>
</div>
<p>assuming you’ve got the command line client. If you’re using a graphical client, you will probably
want to navigate to the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> directory and either right click and find your client’s pull
function, or use one of the menus (if applicable).</p>
<p>You can review the latest changes with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> git log
</pre></div>
</div>
<p>or the equivalent in the graphical client. You can also see the latest changes online
<a class="reference external" href="https://github.com/evennia/evennia/blob/master/CHANGELOG.md">here</a>.</p>
<p>You will always need to do <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">reload</span></code> (or <code class="docutils literal notranslate"><span class="pre">reload</span></code> from -in-game) from your game-dir to have
the new code affect your game. If you want to be really sure you should run a full <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">reboot</span></code>
so that both Server and Portal can restart (this will disconnect everyone though, so if you know the
Portal has had no updates you don’t have to do that).</p>
</section>
<section id="upgrading-evennia-dependencies">
<h2>Upgrading Evennia dependencies<a class="headerlink" href="#upgrading-evennia-dependencies" title="Permalink to this headline"></a></h2>
<p>On occasion we update the versions of third-party libraries Evennia depend on (or we may add a new
dependency). This will be announced on the mailing list/forum. If you run into errors when starting
Evennia, always make sure you have the latest versions of everything. In some cases, like for
Django, starting the server may also give warning saying that you are using a working, but too-old
version that should not be used in production.</p>
<p>Upgrading <code class="docutils literal notranslate"><span class="pre">evennia</span></code> will automatically fetch all the latest packages that it now need. First <code class="docutils literal notranslate"><span class="pre">cd</span></code> to
your cloned <code class="docutils literal notranslate"><span class="pre">evennia</span></code> folder. Make sure your <code class="docutils literal notranslate"><span class="pre">virtualenv</span></code> is active and use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip install --upgrade -e .
</pre></div>
</div>
<p>Remember the period (<code class="docutils literal notranslate"><span class="pre">.</span></code>) at the end - that applies the upgrade to the current location (your
<code class="docutils literal notranslate"><span class="pre">evennia</span></code> dir).</p>
<blockquote>
<div><p>The <code class="docutils literal notranslate"><span class="pre">-e</span></code> means that we are <em>linking</em> the evennia sources rather than copying them into the
environment. This means we can most of the time just update the sources (with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code>) and see
those changes directly applied to our installed <code class="docutils literal notranslate"><span class="pre">evennia</span></code> package. Without installing/upgrading the
package with <code class="docutils literal notranslate"><span class="pre">-e</span></code>, we would have to remember to upgrade the package every time we downloaded any new
source-code changes.</p>
</div></blockquote>
<p>Follow the upgrade output to make sure it finishes without errors. To check what packages are
currently available in your python environment after the upgrade, use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip list
</pre></div>
</div>
<p>This will show you the version of all installed packages. The <code class="docutils literal notranslate"><span class="pre">evennia</span></code> package will also show the
location of its source code.</p>
</section>
<section id="migrating-the-database-schema">
<h2>Migrating the Database Schema<a class="headerlink" href="#migrating-the-database-schema" title="Permalink to this headline"></a></h2>
<p>Whenever we change the database layout of Evennia upstream (such as when we add new features) you
will need to <em>migrate</em> your existing database. When this happens it will be clearly noted in the
<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code> (it will say something to the effect of “Run migrations”). Database changes will also be
announced on the Evennia <a class="reference external" href="https://groups.google.com/forum/#%21forum/evennia">mailing list</a>.</p>
<p>When the database schema changes, you just go to your game folder and run</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> evennia migrate
</pre></div>
</div>
<blockquote>
<div><p>Hint: If the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command is not found, you most likely need to activate your
<a class="reference internal" href="../Glossary.html#virtualenv"><span class="std std-doc">virtualenv</span></a>.</p>
</div></blockquote>
</section>
<section id="resetting-your-database">
<h2>Resetting your database<a class="headerlink" href="#resetting-your-database" title="Permalink to this headline"></a></h2>
<p>Should you ever want to start over completely from scratch, there is no need to re-download Evennia
or anything like that. You just need to clear your database. Once you are done, you just rebuild it
from scratch by running</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia migrate
</pre></div>
</div>
<p>The first step in wiping your database is to stop Evennia completely with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia stop
</pre></div>
</div>
<p>If you run the default <code class="docutils literal notranslate"><span class="pre">SQlite3</span></code> database (to change this you need to edit your <code class="docutils literal notranslate"><span class="pre">settings.py</span></code> file),
the database is actually just a normal file in <code class="docutils literal notranslate"><span class="pre">mygame/server/</span></code> called <code class="docutils literal notranslate"><span class="pre">evennia.db3</span></code>. <em>Simply delete
that file</em> - that’s it. Now run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> to recreate a new, fresh one.</p>
<p>If you run some other database system you can instead flush the database:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia flush
</pre></div>
</div>
<p>This will empty the database. However, it will not reset the internal counters of the database, so
you will start with higher dbref values. If this is okay, this is all you need.</p>
<p>Django also offers an easy way to start the database’s own management should we want more direct
control:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> evennia dbshell
</pre></div>
</div>
<p>In e.g. MySQL you can then do something like this (assuming your MySQL database is named “Evennia”:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>mysql&gt; DROP DATABASE Evennia;
mysql&gt; exit
</pre></div>
</div>
<blockquote>
<div><p>NOTE: Under Windows OS, in order to access SQLite dbshell you need to <a class="reference external" href="https://www.sqlite.org/download.html">download the SQLite
command-line shell program</a>. It’s a single executable file
(sqlite3.exe) that you should place in the root of either your MUD folder or Evennia’s (it’s the
same, in both cases Django will find it).</p>
</div></blockquote>
</section>
<section id="more-about-schema-migrations">
<h2>More about schema migrations<a class="headerlink" href="#more-about-schema-migrations" title="Permalink to this headline"></a></h2>
<p>If and when an Evennia update modifies the database <em>schema</em> (that is, the under-the-hood details as
to how data is stored in the database), you must update your existing database correspondingly to
match the change. If you don’t, the updated Evennia will complain that it cannot read the database
properly. Whereas schema changes should become more and more rare as Evennia matures, it may still
happen from time to time.</p>
<p>One way one could handle this is to apply the changes manually to your database using the database’s
command line. This often means adding/removing new tables or fields as well as possibly convert
existing data to match what the new Evennia version expects. It should be quite obvious that this
quickly becomes cumbersome and error-prone. If your database doesn’t contain anything critical yet
it’s probably easiest to simply reset it and start over rather than to bother converting.</p>
<p>Enter <em>migrations</em>. Migrations keeps track of changes in the database schema and applies them
automatically for you. Basically, whenever the schema changes we distribute small files called
“migrations” with the source. Those tell the system exactly how to implement the change so you don’t
have to do so manually. When a migration has been added we will tell you so on Evennia’s mailing
lists and in commit messages -
you then just run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> to be up-to-date again.</p>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Coding-Introduction.html" title="Coding Introduction"
>next</a> |</li>
<li class="right" >
<a href="Version-Control.html" title="Version Control"
>previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Updating Your Game</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2022, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>

680
docs/1.0-dev/Coding/Version-Control.html
View file

@ -6,7 +6,7 @@
<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>Version Control &#8212; Evennia 1.0-dev documentation</title>
<title>Coding using Version Control &#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>
@ -17,7 +17,7 @@
<link rel="shortcut 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="Updating Your Game" href="Updating-Your-Game.html" />
<link rel="next" title="Debugging" href="Debugging.html" />
<link rel="prev" title="Coding and development help" href="Coding-Overview.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,14 +30,14 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Updating-Your-Game.html" title="Updating Your Game"
<a href="Debugging.html" title="Debugging"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Coding-Overview.html" title="Coding and development help"
accesskey="P">previous</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-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Version Control</a></li>
<li class="nav-item nav-item-this"><a href="">Coding using Version Control</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
@ -62,36 +62,30 @@
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Version Control</a><ul>
<li><a class="reference internal" href="#setting-up-git">Setting up Git</a><ul>
<li><a class="reference internal" href="#step-1-install-git">Step 1: Install Git</a></li>
<li><a class="reference internal" href="#step-2-define-user-e-mail-settings-for-git">Step 2: Define user/e-mail Settings for Git</a></li>
<li><a class="reference internal" href="#">Coding using Version Control</a><ul>
<li><a class="reference internal" href="#setting-up-git">Setting up Git</a></li>
<li><a class="reference internal" href="#common-git-commands">Common Git commands</a><ul>
<li><a class="reference internal" href="#git-init"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">init</span></code></a></li>
<li><a class="reference internal" href="#git-add"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span></code></a></li>
<li><a class="reference internal" href="#git-commit"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code></a></li>
<li><a class="reference internal" href="#git-status-git-diff-and-git-log"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">status</span></code>, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">diff</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code></a></li>
<li><a class="reference internal" href="#git-branch-checkout-and-merge"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">branch</span></code>, <code class="docutils literal notranslate"><span class="pre">checkout</span></code> and <code class="docutils literal notranslate"><span class="pre">merge</span></code></a></li>
<li><a class="reference internal" href="#git-glone-git-push-and-git-pull"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">glone</span></code>, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code></a></li>
<li><a class="reference internal" href="#other-git-commands">Other git commands</a></li>
</ul>
</li>
<li><a class="reference internal" href="#putting-your-game-folder-under-version-control">Putting your game folder under version control</a><ul>
<li><a class="reference internal" href="#tracking-files">Tracking files</a></li>
<li><a class="reference internal" href="#committing-your-code">Committing your Code</a></li>
<li><a class="reference internal" href="#changing-your-mind">Changing your mind</a></li>
<li><a class="reference internal" href="#putting-your-game-dir-under-version-control">Putting your game dir under version control</a><ul>
<li><a class="reference internal" href="#pushing-your-code-online">Pushing your code online</a></li>
</ul>
</li>
<li><a class="reference internal" href="#forking-evennia">Forking Evennia</a><ul>
<li><a class="reference internal" href="#step-1-fork-the-evennia-master-repository">Step 1: Fork the evennia/master repository</a></li>
<li><a class="reference internal" href="#step-2-clone-your-online-fork-of-evennia">Step 2: Clone your online fork of Evennia</a></li>
<li><a class="reference internal" href="#step-3-configure-remotes">Step 3: Configure remotes</a></li>
<li><a class="reference internal" href="#contributing-to-evennia">Contributing to Evennia</a><ul>
<li><a class="reference internal" href="#fixing-an-evennia-bug-or-feature">Fixing an Evennia bug or feature</a></li>
</ul>
</li>
<li><a class="reference internal" href="#working-with-your-evennia-fork">Working with your Evennia fork</a><ul>
<li><a class="reference internal" href="#updating-to-latest-evennia">Updating to latest Evennia</a></li>
<li><a class="reference internal" href="#making-changes">Making changes</a></li>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul>
<li><a class="reference internal" href="#getting-403-forbidden-access">Getting 403: Forbidden access</a></li>
</ul>
</li>
<li><a class="reference internal" href="#sharing-your-evennia-fixes-on-github">Sharing your Evennia fixes on Github</a><ul>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a></li>
</ul>
</li>
<li><a class="reference internal" href="#making-an-evennia-pull-request">Making an Evennia Pull Request</a></li>
<li><a class="reference internal" href="#git-tips-and-tricks">GIT tips and tricks</a></li>
</ul>
</li>
</ul>
@ -100,8 +94,8 @@
<p class="topless"><a href="Coding-Overview.html"
title="previous chapter">Coding and development help</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Updating-Your-Game.html"
title="next chapter">Updating Your Game</a></p>
<p class="topless"><a href="Debugging.html"
title="next chapter">Debugging</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -132,25 +126,16 @@
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="version-control">
<h1>Version Control<a class="headerlink" href="#version-control" title="Permalink to this headline"></a></h1>
<p>Version control software allows you to track the changes you make to your code, as well as being
able to easily backtrack these changes, share your development efforts and more.</p>
<p>It’s strongly recommended that you put your game code under version control. Version
control is also the way to contribue to Evennia itself.</p>
<p>For an introduction to the concept, start with the Wikipedia article
<a class="reference external" href="https://en.wikipedia.org/wiki/Version_control">here</a>. Evennia uses the version
control system <a class="reference external" href="https://git-scm.com/">Git</a> and this is what will be covered
henceforth. Note that this page primarily shows commands for Linux, but the
syntax should be the same for Windows and Mac.</p>
<p>For more help on using Git, please refer to the <a class="reference external" href="https://help.github.com/articles/set-up-git#platform-all">Official GitHub
documentation</a>.</p>
<section class="tex2jax_ignore mathjax_ignore" id="coding-using-version-control">
<h1>Coding using Version Control<a class="headerlink" href="#coding-using-version-control" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/Version_control">Version control</a> allows you to track changes to your code. You can save ‘snapshots’ of your progress which means you can roll back undo things easily. Version control also allows you to easily back up your code to an online <em>repository</em> such as Github. It also allows you to collaborate with others on the same code without clashing or worry about who changed what.</p>
<aside class="sidebar">
<p class="sidebar-title">Do it!</p>
<p>It’s <em>strongly</em> recommended that you <a class="reference internal" href="#putting-your-game-dir-under-version-control"><span class="std std-doc">put your game folder under version control</span></a>. Using git is is also the way to contribue to Evennia itself.</p>
</aside>
<p>Evennia uses the most commonly used version control system, <a class="reference external" href="https://git-scm.com/">Git</a> . For additional help on using Git, please refer to the <a class="reference external" href="https://help.github.com/articles/set-up-git#platform-all">Official GitHub documentation</a>.</p>
<section id="setting-up-git">
<h2>Setting up Git<a class="headerlink" href="#setting-up-git" title="Permalink to this headline"></a></h2>
<p>You can find expanded instructions for
installation <a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git">here</a>.</p>
<section id="step-1-install-git">
<h3>Step 1: Install Git<a class="headerlink" href="#step-1-install-git" title="Permalink to this headline"></a></h3>
<ul>
<li><p><strong>Fedora Linux</strong></p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> yum install git-core
@ -163,21 +148,16 @@ installation <a class="reference external" href="https://git-scm.com/book/en/Get
</div>
</li>
<li><p><strong>Windows</strong>: It is recommended to use <a class="reference external" href="https://gitforwindows.org/">Git for Windows</a>.</p></li>
<li><p><strong>Mac</strong>: Mac platforms offer two methods for installation, one via MacPorts, which you can find
out about <a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac">here</a>, or
you can use the <a class="reference external" href="https://sourceforge.net/projects/git-osx-installer/">Git OSX Installer</a>.</p></li>
<li><p><strong>Mac</strong>: Mac platforms offer two methods for installation, one via MacPorts, which you can find out about <a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac">here</a>, or you can use the <a class="reference external" href="https://sourceforge.net/projects/git-osx-installer/">Git OSX Installer</a>.</p></li>
</ul>
</section>
<section id="step-2-define-user-e-mail-settings-for-git">
<h3>Step 2: Define user/e-mail Settings for Git<a class="headerlink" href="#step-2-define-user-e-mail-settings-for-git" title="Permalink to this headline"></a></h3>
<p>To avoid a common issue later, you will need to set a couple of settings; first you will need to
tell Git your username, followed by your e-mail address, so that when you commit code later you will
be properly credited.</p>
<blockquote>
<div><p>Note that your commit information will be visible to everyone if you ever contribute to Evennia or
use an online service like github to host your code. So if you are not comfortable with using your
real, full name online, put a nickname here.</p>
<div><p>You can find expanded instructions for installation <a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git">here</a>.</p>
</div></blockquote>
<aside class="sidebar">
<p class="sidebar-title">Git user nickname</p>
<p>If you ever make your code available online (or contribute to Evennia), your name will be visible to those reading the code-commit history. So if you are not comfortable with using your real, full name online, put a nickname (or your github handler) here.</p>
</aside>
<p>To avoid a common issue later, you will need to set a couple of settings; first you will need to tell Git your username, followed by your e-mail address, so that when you commit code later you will be properly credited.</p>
<ol>
<li><p>Set the default name for git to use when you commit:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> git config --global user.name &quot;Your Name Here&quot;
@ -190,298 +170,290 @@ real, full name online, put a nickname here.</p>
</div>
</li>
</ol>
</section>
</section>
<section id="putting-your-game-folder-under-version-control">
<h2>Putting your game folder under version control<a class="headerlink" href="#putting-your-game-folder-under-version-control" title="Permalink to this headline"></a></h2>
<blockquote>
<div><p>Note: The game folder’s version control is completely separate from Evennia’s repository.</p>
<div><p>To get a running start with Git, here’s <a class="reference external" href="https://www.youtube.com/watch?v=1ffBJ4sVUb4#t=1m58s">a good YouTube talk about it</a>. It’s a bit long but it will help you understand the underlying ideas behind GIT (which in turn makes it a lot more intuitive to use).</p>
</div></blockquote>
<p>After you have set up your game you will have created a new folder to host your particular game
(let’s call this folder <code class="docutils literal notranslate"><span class="pre">mygame</span></code> for now).</p>
<p>This folder is <em>not</em> under version control at this point.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git init mygame
</section>
<section id="common-git-commands">
<h2>Common Git commands<a class="headerlink" href="#common-git-commands" title="Permalink to this headline"></a></h2>
<aside class="sidebar">
<p class="sidebar-title">Git repository</p>
<p>This is just a fancy name for the folder you have designated to be under version control. We will make your <code class="docutils literal notranslate"><span class="pre">mygame</span></code> game folder into such a repository. The Evennia code is also in a (separate) git repository.</p>
</aside>
<p>Git can be controlled via a GUI. But it’s often easier to use the base terminal/console commands, since it makes it clear if something goes wrong.</p>
<p>All these actions need to be done from inside the <em>git repository</em> .</p>
<p>Git may seem daunting at first. But when working with git, you’ll be using the same 2-3 commands 99% of the time. And you can make git <em>aliases</em> to have them be even easier to remember.</p>
<section id="git-init">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">init</span></code><a class="headerlink" href="#git-init" title="Permalink to this headline"></a></h3>
<p>This initializes a folder/directory on your drive as a ‘git repository’</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git init .
</pre></div>
</div>
<p>Your mygame folder is now ready for version control! Add all the content and make a first
commit:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd mygame
<p>The <code class="docutils literal notranslate"><span class="pre">.</span></code> means to apply to the current directory. If you are inside <code class="docutils literal notranslate"><span class="pre">mygame</span></code>, this makes your game dir into a git repository. That’s all there is to it, really. You only need to do this once.</p>
</section>
<section id="git-add">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span></code><a class="headerlink" href="#git-add" title="Permalink to this headline"></a></h3>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git add &lt;file&gt;
</pre></div>
</div>
<p>This tells Git to start to <em>track</em> the file under version control. You need to do this when you create a new file. You can also add all files in your current directory:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git add .
</pre></div>
</div>
<p>Or</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git add *
</pre></div>
</div>
<p>All files in the current directory are now tracked by Git. You only need to do this once for every file you want to track.</p>
</section>
<section id="git-commit">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code><a class="headerlink" href="#git-commit" title="Permalink to this headline"></a></h3>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m &quot;This is the initial commit&quot;
</pre></div>
</div>
<p>This <em>commits</em> your changes. It stores a snapshot of all (<code class="docutils literal notranslate"><span class="pre">-a</span></code>) your code at the current time, adding a message <code class="docutils literal notranslate"><span class="pre">-m</span></code> so you know what you did. Later you can <em>check out</em> your code the way it was at a given time. The message is mandatory and you will thank yourself later if write clear and descriptive log messages. If you don’t add <code class="docutils literal notranslate"><span class="pre">-m</span></code>, a text editor opens for you to write the message instead.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> is something you’ll be using all the time, so it can be useful to make a <em>git alias</em> for it:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git config --global alias.cma &#39;commit -a -m&#39;
</pre></div>
</div>
<p>After you’ve run this, you can commit much simpler, like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git cma &quot;This is the initial commit&quot;
</pre></div>
</div>
<p>Much easier to remember!</p>
</section>
<section id="git-status-git-diff-and-git-log">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">status</span></code>, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">diff</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code><a class="headerlink" href="#git-status-git-diff-and-git-log" title="Permalink to this headline"></a></h3>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git status -s
</pre></div>
</div>
<p>This gives a short (<code class="docutils literal notranslate"><span class="pre">-s</span></code>) of the files that changes since your last <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code>.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git diff --word-diff`
</pre></div>
</div>
<p>This shows exactly what changed in each file since you last made a <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code>. The <code class="docutils literal notranslate"><span class="pre">--word-diff</span></code> option means it will mark if a single word changed on a line.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git log
</pre></div>
</div>
<p>This shows the log of all <code class="docutils literal notranslate"><span class="pre">commits</span></code> done. Each log will show you who made the change, the commit-message and a unique <em>hash</em> (like <code class="docutils literal notranslate"><span class="pre">ba214f12ab12e123...</span></code>) that uniquely describes that commit.</p>
<p>You can make the <code class="docutils literal notranslate"><span class="pre">log</span></code> command more succinct with some more options:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>ls=log --pretty=format:%C(green)%h\ %C(yellow)[%ad]%Cred%d\ %Creset%s%Cblue\ [%an] --decorate --date=relative
</pre></div>
</div>
<p>This adds coloration and another fancy effects (use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">help</span> <span class="pre">log</span></code> to see what they mean).</p>
<p>Let’s add aliases:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git config --global alias.st &#39;status -s&#39;
git config --global alias.df &#39;diff --word-diff&#39;
git config --global alias.ls &#39;log --pretty=format:%C(green)%h\ %C(yellow)[%ad]%Cred%d\ %Creset%s%Cblue\ [%an] --decorate --date=relative&#39;
</pre></div>
</div>
<p>You can now use the much shorter</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git st # short status
git dif # diff with word-marking
git ls # log with pretty formatting
</pre></div>
</div>
<p>for these useful functions.</p>
</section>
<section id="git-branch-checkout-and-merge">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">branch</span></code>, <code class="docutils literal notranslate"><span class="pre">checkout</span></code> and <code class="docutils literal notranslate"><span class="pre">merge</span></code><a class="headerlink" href="#git-branch-checkout-and-merge" title="Permalink to this headline"></a></h3>
<p>Git allows you to work with <em>branches</em>. These are separate development paths your code may take, completely separate from each other. You can later <em>merge</em> the code from a branch back into another branch. Evennia’s <code class="docutils literal notranslate"><span class="pre">master</span></code> and <code class="docutils literal notranslate"><span class="pre">develop</span></code> branches are examples of this.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branch -b branchaname
</pre></div>
</div>
<p>This creates a new branch, exactly identical to the branch you were on. It also moves you to that branch.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branch -D branchname
</pre></div>
</div>
<p>Deletes a branch.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branch
</pre></div>
</div>
<p>Shows all your branches, marking which one you are currently on.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout branchname
</pre></div>
</div>
<p>This checks out another branch. As long as you are in a branch all <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code>s will commit the code to that branch only.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout .
</pre></div>
</div>
<p>This checks out your <em>current branch</em> and has the effect of throwing away all your changes since your last commit. This is like undoing what you did since the last save point.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout b2342bc21c124
</pre></div>
</div>
<p>This checks out a particular <em>commit</em>, identified by the hash you find with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code>. This open a ‘temporary branch’ where the code is as it was when you made this commit. As an example, you can use this to check where a bug was introduced. Check out an existing branch to go back to your normal timeline, or use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">branch</span> <span class="pre">-b</span> <span class="pre">newbranch</span></code> to break this code off into a new branch you can continue working from.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git merge branchname
</pre></div>
</div>
<p>This <em>merges</em> the code from <code class="docutils literal notranslate"><span class="pre">branchname</span></code> into the branch you are currently in. Doing so may lead to <em>merge conflicts</em> if the same code changed in different ways in the two branches. See <a class="reference external" href="https://phoenixnap.com/kb/how-to-resolve-merge-conflicts-in-git">how to resolve merge conflicts in git</a> for more help.</p>
</section>
<section id="git-glone-git-push-and-git-pull">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">glone</span></code>, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code><a class="headerlink" href="#git-glone-git-push-and-git-pull" title="Permalink to this headline"></a></h3>
<p>All of these other commands have dealt with code only sitting in your local repository-folder. These commands instead allows you to exchange code with a <em>remote</em> repository - usually one that is online (like on github).</p>
<blockquote>
<div><p>How you actually set up a remote repository is described <a class="reference internal" href="#pushing-your-code-online"><span class="std std-doc">in the next section</span></a>.</p>
</div></blockquote>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git clone repository/path
</pre></div>
</div>
<p>This copies the remote repository to your current location. If you used the <a class="reference internal" href="../Setup/Installation-Git.html"><span class="doc std std-doc">Git installation instructions</span></a> to install Evennia, this is what you used to get your local copy of the Evennia repository.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git pull
</pre></div>
</div>
<p>Once you cloned or otherwise set up a remote repository, using <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code> will re-sync the remote with what you have locally. If what you download clashes with local changes, git will force you to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> your changes before you can continue with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code>.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push
</pre></div>
</div>
<p>This uploads your local changes <em>of your current branch</em> to the same-named branch on the remote repository. To be able to do this you must have write-permissions to the remote repository.</p>
</section>
<section id="other-git-commands">
<h3>Other git commands<a class="headerlink" href="#other-git-commands" title="Permalink to this headline"></a></h3>
<p>There are <em>many</em> other git commands. Read up on them online:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git reflog
</pre></div>
</div>
<p>Shows hashes of individual git actions. This allows you to go back in the git event history itself.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git reset
</pre></div>
</div>
<p>Force reset a branch to an earlier commit. This could throw away some history, so be careful.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git grep -n -I -i &lt;query&gt;
</pre></div>
</div>
<p>Quickly search for a phrase/text in all files tracked by git. Very useful to quickly find where things are. Set up an alias <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">gr</span></code> with</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">gr</span> <span class="s1">&#39;grep -n -I -i&#39;</span>
</pre></div>
</div>
</section>
</section>
<section id="putting-your-game-dir-under-version-control">
<h2>Putting your game dir under version control<a class="headerlink" href="#putting-your-game-dir-under-version-control" title="Permalink to this headline"></a></h2>
<p>This makes use of the git commands listed in the previous section.</p>
<aside class="sidebar">
<p class="sidebar-title">git aliases</p>
<p>If you set up the git aliases for commands suggested in the previous section, you can use them instead!</p>
</aside>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd mygame
git init .
git add *
git commit -a -m &quot;Initial commit&quot;
</pre></div>
</div>
<p>In turn these commands:</p>
<ul class="simple">
<li><p>Move us into the <code class="docutils literal notranslate"><span class="pre">mygame</span></code> folder</p></li>
<li><p>Tell <code class="docutils literal notranslate"><span class="pre">git</span></code> that everything <code class="docutils literal notranslate"><span class="pre">*</span></code> means everything) in this folder should be put
under version control.</p></li>
<li><p><em>Commit</em> all (<code class="docutils literal notranslate"><span class="pre">-a</span></code>) those newly added files to git and add a message <code class="docutils literal notranslate"><span class="pre">-m</span></code> so you remember
what you did at this point. Doing a commit is like saving a snapshot of the
current state of everything.</p></li>
</ul>
<p>Read on for details!</p>
<section id="tracking-files">
<h3>Tracking files<a class="headerlink" href="#tracking-files" title="Permalink to this headline"></a></h3>
<p>When working on your code or fix bugs in your local branches you may end up creating new files. If
you do you must tell Git to track them by using the add command.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git add &lt;filename&gt;
</pre></div>
</div>
<p>You only need to do this once per file.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git status
</pre></div>
</div>
<p>will show if you have any modified, added or otherwise changed files. Some
files, like database files, logs and temporary PID files are usually <em>not</em>
tracked in version control. These should either not show up or have a question
mark in front of them.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You will notice that some files are not covered by your git version control,
notably your settings file (<code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code>) and your sqlite3
database file <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>. What is auto-ignored by is controlled
by the hidden file <code class="docutils literal notranslate"><span class="pre">mygame/.gitignore</span></code>. Evennia creates this file as part of
the creation of your game directory. Everything matched in this file will be
ignored by git. If you want to, for example, include your settings file for
collaborators to access, remove that entry in <code class="docutils literal notranslate"><span class="pre">.gitignore</span></code>.</p>
</div>
<p>Your game-dir is now tracked by git.</p>
<p>You will notice that some files are not covered by your git version control, notably your secret-settings file (<code class="docutils literal notranslate"><span class="pre">mygame/server/conf/secret_settings.py</span></code>) and your sqlite3 database file <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>. This is intentional and controlled from the file <code class="docutils literal notranslate"><span class="pre">mygame/.gitignore</span></code>.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>You should <em>never</em> put your sqlite3 database file into git by removing its entry
in <code class="docutils literal notranslate"><span class="pre">.gitignore</span></code>. GIT is for backing up your code, not your database. That way
lies madness and a good chance you’ll confuse yourself so that after a few
commits and reverts don’t know what is in your database or not. If you want to
backup your database, do so by simply copying the file on your hard drive to a
backup-name.</p>
lies madness and a good chance you’ll confuse yourself. Make one mistake or local change and after a few commits and reverts you will have lost track of what is in your database or not. If you want to backup your SQlite3 database, do so by simply copying the database file to a safe location.</p>
</div>
</section>
<section id="committing-your-code">
<h3>Committing your Code<a class="headerlink" href="#committing-your-code" title="Permalink to this headline"></a></h3>
<p><em>Committing</em> your code means storing the current snapshot of your code within
git. This creates a “save point” or “history” of your development process. You
can later jump back and forth in your history, for example to figure out just
when a bug was introduced or see what results the code used to produce compared
to now. Or just wiping everything since the last commit, if you did something
stupid.</p>
<p>It’s usually a good idea to commit your changes often. Committing is fast and
local only - you will never commit anything online at this point. To commit your
changes, use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit --all
</pre></div>
</div>
<p>Also <code class="docutils literal notranslate"><span class="pre">-a</span></code> works. This will open a text editor for you to describe your change.
Be brief but informative in your message - you’ll appreciate it later. When you
save and close the editor, the commit will be saved. You can create the message
directly with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m &quot;This fixes a bug in the combat code.&quot;
</pre></div>
</div>
</section>
<section id="changing-your-mind">
<h3>Changing your mind<a class="headerlink" href="#changing-your-mind" title="Permalink to this headline"></a></h3>
<p>If you have non-committed changes that you realize you want to throw away, you
‘check out’ the file you want - this will re-load it from the last committed
state:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout &lt;file_to_revert&gt;
git checkout foo/bar/dummy.py
</pre></div>
</div>
<p>If you want to revert <em>all</em> changes you did since last commit, do</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout .
</pre></div>
</div>
<p>(that is, add a single <code class="docutils literal notranslate"><span class="pre">.</span></code> at the end).</p>
</section>
<section id="pushing-your-code-online">
<h3>Pushing your code online<a class="headerlink" href="#pushing-your-code-online" title="Permalink to this headline"></a></h3>
<p>So far your code is only located on your private machine. A good idea is to back
it up online. The easiest way to do this is to push it to your own remote
repository on GitHub.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Just to avoid confusion, be aware that Github’s documentation has changed to
calling the primary branch ‘main’ rather than ‘master’. While Evennia still
uses ‘master’ branch (and this is what we refer to below), you can use either
name for your personal primary branch - they are equivalent.</p>
<p>So far your code is only located on your private machine. A good idea is to back it up online. The easiest way to do this is to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> it to your own remote repository on GitHub. So for this you need a (free) Github account.</p>
<p>If you don’t want your code to be publicly visible, Github also allows you set up a <em>private</em> repository, only visible to you.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Github’s defaults have changed to calling the primary branch ‘main’ rather than ‘master’. While Evennia still uses ‘master’ branch (and this is what we refer to below), you can use either name for your personal primary branch - they are equivalent.</p>
</div>
<ol class="simple">
<li><p>Make sure you have your game directory setup under git version control as
described in the previous section. Make sure to commit any changes you did.</p></li>
<li><p>Create a new, empty repository on Github. Github explains how
<a class="reference external" href="https://help.github.com/articles/create-a-repo/">here</a> (do <em>not</em> “Initialize
the repository with a README” or else you’ll create unrelated histories).</p></li>
<li><p>From your local game dir, do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">remote</span> <span class="pre">add</span> <span class="pre">origin</span> <span class="pre">&lt;github</span> <span class="pre">URL&gt;</span></code> where
<code class="docutils literal notranslate"><span class="pre">&lt;github</span> <span class="pre">URL&gt;</span></code> is the URL to your online repo. This tells your game dir that
it should be pushing to the remote online dir.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">remote</span> <span class="pre">-v</span></code> to verify the online dir.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">origin</span> <span class="pre">master</span></code> (or <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">origin</span> <span class="pre">main</span></code>) now pushes your game dir
online so you can see it on <a class="reference external" href="http://github.com">github.com</a>.</p></li>
</ol>
<p>You can commit your work locally (<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span> <span class="pre">--all</span> <span class="pre">-m</span> <span class="pre">&quot;Make</span> <span class="pre">a</span> <span class="pre">change</span> <span class="pre">that</span> <span class="pre">...&quot;</span></code>) as many times as you want. When you want to push those changes to your
online repo, you do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code>. You can also <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">&lt;url_to_online_repo&gt;</span></code>
from your online repo to somewhere else (like your production server) and
henceforth do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code> to update that to the latest thing you pushed.</p>
<p>Note that GitHub’s repos are, by default publicly visible by all. Creating a
publicly visible online clone might not be what you want for all parts of your
development process - you may prefer a more private venue when sharing your
revolutionary work with your team. If that’s the case you can change your
repository to “Private” in the github settings. Then your code will only be
visible to those you specifically grant access.</p>
</section>
</section>
<section id="forking-evennia">
<h2>Forking Evennia<a class="headerlink" href="#forking-evennia" title="Permalink to this headline"></a></h2>
<p>This helps you set up an online <em>fork</em> of the main Evennia repository so you can
easily commit fixes and help with upstream development. You can do this step
also if you <em>didn’t</em> put your game dir under version control like in the
previous section - the evennia repo and your game dir repo are completely
separate.</p>
<section id="step-1-fork-the-evennia-master-repository">
<h3>Step 1: Fork the evennia/master repository<a class="headerlink" href="#step-1-fork-the-evennia-master-repository" title="Permalink to this headline"></a></h3>
<blockquote>
<div><p>Before proceeding with the following step, make sure you have registered and
created an account on <a class="reference external" href="https://github.com/">GitHub.com</a>. This is necessary in order to create a fork
of Evennia’s master repository, and to push your commits to your fork either for
yourself or for contributing to
Evennia.</p>
</div></blockquote>
<p>A <em>fork</em> is a clone of the master repository that you can make your own commits
and changes to. At the top of <a class="reference external" href="https://github.com/evennia/evennia">this page</a>,
click the “Fork” button, as it appears below.
<img alt="" src="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" /></p>
</section>
<section id="step-2-clone-your-online-fork-of-evennia">
<h3>Step 2: Clone your online fork of Evennia<a class="headerlink" href="#step-2-clone-your-online-fork-of-evennia" title="Permalink to this headline"></a></h3>
<p>The fork only exists online as of yet. In a terminal, change your directory to
the folder you wish to develop in. From this directory run the following
command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/yourusername/evennia.git
<p>Create a new, empty repository on Github. <a class="reference external" href="https://help.github.com/articles/create-a-repo/">Github explains how here</a> . <em>Don’t</em> allow it to add a README, license etc, that will just clash with what we upload later.</p>
<aside class="sidebar">
<p class="sidebar-title">Origin</p>
<p>We label the remote repository ‘origin’. This is the git default and means we won’t need to specify it explicitly later.</p>
</aside>
<p>Make sure you are in your local game dir (previously initialized as a git repo).</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git remote add origin &lt;github URL&gt;
</pre></div>
</div>
<p>This will download your fork to your computer. It creates a new folder
<code class="docutils literal notranslate"><span class="pre">evennia/</span></code> at your current location.</p>
<p>This tells Git that there is a remote repository at <code class="docutils literal notranslate"><span class="pre">&lt;github</span> <span class="pre">URL&gt;</span></code>. See the github docs as to which URL to use. Verify that the remote works with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">remote</span> <span class="pre">-v</span></code></p>
<p>Now we push to the remote (labeled ‘origin’ which is the default):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push
</pre></div>
</div>
<p>Depending on how you set up your authentication with github, you may be asked to enter your github username and password. If you set up SSH authentication, this command will just work.</p>
<p>You use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> to upload your local changes so the remote repository is in sync with your local one. If you edited a file online using the Github editor (or a collaborator pushed code), you use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code> to sync in the other direction.</p>
</section>
<section id="step-3-configure-remotes">
<h3>Step 3: Configure remotes<a class="headerlink" href="#step-3-configure-remotes" title="Permalink to this headline"></a></h3>
<p>Your Evennia-fork is now separate from upstream, ‘official’ Evennia. You will
want to set it up so that you can easily sync our updates and changes to your
fork.</p>
<p>We do this by setting up a new <em>remote</em>. We actually already have one remote,
that is our own github form of Evennia. This got created when you cloned the
repo and defaults to being called <code class="docutils literal notranslate"><span class="pre">origin</span></code>.</p>
<p>We will now create a new remote called <code class="docutils literal notranslate"><span class="pre">upstream</span></code>.</p>
</section>
<section id="contributing-to-evennia">
<h2>Contributing to Evennia<a class="headerlink" href="#contributing-to-evennia" title="Permalink to this headline"></a></h2>
<p>If you want to help contributing to Evennia you must do so by <em>forking</em> - making your own remote copy of the Evennia repository on Github. So for this, you need a (free) Github account. Doing so is a completely separate process from <a class="reference internal" href="#putting-your-game-dir-under-version-control"><span class="std std-doc">putting your game dir under version control</span></a> (which you should also do!).</p>
<p>At the top right of <a class="reference external" href="https://github.com/evennia/evennia">the evennia github page</a>, click the “Fork” button:</p>
<p><img alt="fork button" src="../_images/fork_button.png" /></p>
<p>This will create a new online fork Evennia under your github account.</p>
<p>The fork only exists online as of yet. In a terminal, <code class="docutils literal notranslate"><span class="pre">cd</span></code> to the folder you wish to develop in. This folder should <em>not</em> be your game dir, nor the place you cloned Evennia into if you used the <a class="reference internal" href="../Setup/Installation-Git.html"><span class="doc std std-doc">Git installation</span></a>.</p>
<p>From this directory run the following command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/yourusername/evennia.git evennia
</pre></div>
</div>
<p>This will download your fork to your computer. It creates a new folder <code class="docutils literal notranslate"><span class="pre">evennia/</span></code> at your current location. If you installed Evennia using the <a class="reference internal" href="../Setup/Installation-Git.html"><span class="doc std std-doc">Git installation</span></a>, this folder will be identical in content to the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> folder you cloned during that installation. The difference is that this repo is connected to your remote fork and not to the ‘original’ <em>upstream</em> Evennia.</p>
<p>When we cloned our fork, git automatically set up a ‘remote repository’ labeled <code class="docutils literal notranslate"><span class="pre">origin</span></code> pointing to it. So if we do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code>, we’ll push to our fork.</p>
<p>We now want to add a second remote repository linked to the original Evennia repo. We will label this remote repository <code class="docutils literal notranslate"><span class="pre">upstream</span></code>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd evennia
git remote add upstream https://github.com/evennia/evennia.git
</pre></div>
</div>
<p>This adds a remote to the main evennia repo.</p>
<p>If you also want to access Evennia’s <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch (the bleeding edge
development) do the following:</p>
<p>If you also want to access Evennia’s <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch (the bleeding edge development) do the following:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git fetch upstream develop
git checkout develop
</pre></div>
</div>
<p>Use
git checkout master
git checkout develop</p>
<p>to switch between the branches. If you want to contribute a fix, ask first which
branch to use. Normally <code class="docutils literal notranslate"><span class="pre">master</span></code> is for bug fixes and <code class="docutils literal notranslate"><span class="pre">develop</span></code> is for new
features, but late in the development of a new Evennia version, all changes
often go into <code class="docutils literal notranslate"><span class="pre">develop</span></code>.</p>
</section>
</section>
<section id="working-with-your-evennia-fork">
<h2>Working with your Evennia fork<a class="headerlink" href="#working-with-your-evennia-fork" title="Permalink to this headline"></a></h2>
<p><em>Branches</em> are stand-alone editions of the same code. You make a commit to a
branch. Switching to a branch will change the code on-disk. You can easily
make a new branch off a parent branch, and then merge it back into the same
branch later (or throw it away). This is a very common way to work on new
features in safety and isolation.</p>
<section id="updating-to-latest-evennia">
<h3>Updating to latest Evennia<a class="headerlink" href="#updating-to-latest-evennia" title="Permalink to this headline"></a></h3>
<p>When Evennia’s official repository updates, first make sure to commit all your
changes to your branch and then checkout the “clean” master branch:</p>
<p>Use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master
git pull upstream master
git checkout develop
</pre></div>
</div>
<p>Or, if you are working against Evennia’s development branch:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout develop
git pull upstream develop
<p>to switch between the branches.</p>
<p>To pull the latest from upstream Evennia, just checkout the branch you want and do</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git pull upstream
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">pull</span></code> command will fetch all the changes from the “upstream” remote and
merge it into your local master/develop branch. It should now be a perfect copy
of the latest Evennia changes.</p>
</section>
<section id="making-changes">
<h3>Making changes<a class="headerlink" href="#making-changes" title="Permalink to this headline"></a></h3>
<p>As a rule of thumb you should <em>never</em> work directly in Evennia’s <code class="docutils literal notranslate"><span class="pre">master</span></code> or
<code class="docutils literal notranslate"><span class="pre">develop</span></code> branches. Instead you make a <em>new</em> branch off the branch you want
and change <em>that</em>.</p>
<aside class="sidebar">
<p class="sidebar-title">Pushing to upstream</p>
<p>You can’t do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">upstream</span></code> unless you have write-access to the upstream Evennia repository. So there is no risk of you accidentally pushing your own code into the main, public repository.</p>
</aside>
<section id="fixing-an-evennia-bug-or-feature">
<h3>Fixing an Evennia bug or feature<a class="headerlink" href="#fixing-an-evennia-bug-or-feature" title="Permalink to this headline"></a></h3>
<p>This should be done in your fork of Evennia. You should <em>always</em> do this in a <em>separate git branch</em> based off the Evennia branch you want to improve.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master (or develop)
check checkout -b strange_bug
git branch - b myfixbranch
</pre></div>
</div>
<p>You now have a new branch <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> that is an exact replica of the branch you
had checked out when you created it. Here you can now make your own
modifications.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branches
</pre></div>
</div>
<p>will show you which branches are available and which one you are currently
using. Use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">&lt;branch&gt;</span></code> to move between them, but remember to commit
your changes before you do.</p>
<p>You often want to make sure also your work-branch has the latest upstream
changes. To do this, you need to first update your copy of the
<code class="docutils literal notranslate"><span class="pre">master</span></code>/<code class="docutils literal notranslate"><span class="pre">develop</span></code> branch and then <em>merge</em> those changes into your work branch.
Make sure you have committed everything first!</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m &quot;My latest changes ...&quot; # on your strange_bug branch
git checkout master (or develop)
git pull upstream develop
git checkout strange_bug
<p>Now fix whatever needs fixing. Abide by the <a class="reference internal" href="Evennia-Code-Style.html"><span class="doc std std-doc">Evennia code style</span></a>. You can <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> commit your changes along the way as normal.</p>
<p>Upstream Evennia is not standing still, so you want to make sure that your work is up-to-date with upstream changes. Make sure to first commit your <code class="docutils literal notranslate"><span class="pre">myfixbranch</span></code> changes, then</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master (or develop)
git pull upstream
git checkout myfixbranch
git merge master (or develop)
</pre></div>
</div>
<p>If everything went well, your <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch will now have the latest version
of Evennia merged with whatever changes you have done.</p>
<p>Now work away on your code and commit with reasonable commit messages</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m &quot;Fixed the issue in ...&quot;
git commit -a -m &quot;Adding unit tests. This resolves #123.&quot;
</pre></div>
</div>
<p>Use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git diff
</pre></div>
</div>
<p>to see what you changed since last commit, and</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git log
</pre></div>
</div>
<p>to see past commits (including those made by Evennia upstream, remember that
your branch is a copy of the upstream one, including its history!)</p>
</section>
</section>
<section id="sharing-your-evennia-fixes-on-github">
<h2>Sharing your Evennia fixes on Github<a class="headerlink" href="#sharing-your-evennia-fixes-on-github" title="Permalink to this headline"></a></h2>
<p>Up to this point your <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch only exists on your local computer. No
one else can see it. If you want a copy of this branch to also appear in your
online fork on GitHub, make sure to have checked out your “myfixes” branch and
then run the following:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push -u origin strange_bug
</pre></div>
</div>
<p>You only need to do this once, the <code class="docutils literal notranslate"><span class="pre">-u</span></code> makes this the default push-location. In
the future, you can just push things online like this:</p>
<p>Up to this point your <code class="docutils literal notranslate"><span class="pre">myfixbranch</span></code> branch only exists on your local computer. No
one else can see it.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push
</pre></div>
</div>
<p>This will automatically create a matching <code class="docutils literal notranslate"><span class="pre">myfixbranch</span></code> in your forked version of Evennia and push to it. On github you will be able to see appear it in the <code class="docutils literal notranslate"><span class="pre">branches</span></code> dropdown. You can keep pushing to your remote <code class="docutils literal notranslate"><span class="pre">myfixbranch</span></code> as much as you like.</p>
<p>Once you feel you have something to share, you need to <a class="reference external" href="https://github.com/evennia/evennia/pulls">create a pull request</a> (PR):
This is a formal request for upstream Evennia to adopt and pull your code into the main repository.</p>
<ol class="simple">
<li><p>Click <code class="docutils literal notranslate"><span class="pre">New</span> <span class="pre">pull</span> <span class="pre">request</span></code></p></li>
<li><p>Choose <code class="docutils literal notranslate"><span class="pre">compare</span> <span class="pre">across</span> <span class="pre">forks</span></code></p></li>
<li><p>Select your fork from dropdown list of <code class="docutils literal notranslate"><span class="pre">head</span> <span class="pre">repository</span></code> repos. Pick the right branch to <code class="docutils literal notranslate"><span class="pre">compare</span></code>.</p></li>
<li><p>On the Evennia side (to the left) make sure to pick the right <code class="docutils literal notranslate"><span class="pre">base</span></code> branch: If you want to contribute a change to the <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch, you must pick <code class="docutils literal notranslate"><span class="pre">develop</span></code> as the <code class="docutils literal notranslate"><span class="pre">base</span></code>.</p></li>
<li><p>Then click <code class="docutils literal notranslate"><span class="pre">Create</span> <span class="pre">pull</span> <span class="pre">request</span></code> and fill in as much information as you can in the form.</p></li>
<li><p>Optional: Once you saved your PR, you can go into your code (on github) and add some per-line comments; this can help reviewers by explaining complex code or decisions you made.</p></li>
</ol>
<p>Now you just need to wait for your code to be reviewed. Expect to get feedback and be asked to make changes, add more documentation etc. Getting as PR merged can take a few iterations.</p>
<aside class="sidebar">
<p class="sidebar-title">Not all PRs can merge</p>
<p>While most PRs get merged, Evennia can’t <strong>guarantee</strong> that your PR code will be deemed suitable to merge into upstream Evennia. For this reason it’s a good idea to check in with the community <em>before</em> you spend a lot of time on a large piece of code (fixing bugs is always a safe bet though!)</p>
</aside>
</section>
</section>
<section id="troubleshooting">
<h3>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline"></a></h3>
<p>If you hadn’t setup a public key on GitHub or aren’t asked for a
username/password, you might get an error <code class="docutils literal notranslate"><span class="pre">403:</span> <span class="pre">Forbidden</span> <span class="pre">Access</span></code> at this stage.
In that case, some users have reported that the workaround is to create a file
<code class="docutils literal notranslate"><span class="pre">.netrc</span></code> under your home directory and add your github credentials there:</p>
<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline"></a></h2>
<section id="getting-403-forbidden-access">
<h3>Getting 403: Forbidden access<a class="headerlink" href="#getting-403-forbidden-access" title="Permalink to this headline"></a></h3>
<p>Some users have experienced this on <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> to their remote repository. They are not asked for username/password (and don’t have a ssh key set up).</p>
<p>Some users have reported that the workaround is to create a file <code class="docutils literal notranslate"><span class="pre">.netrc</span></code> under your home directory and add your github credentials there:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>machine github.com
login &lt;my_github_username&gt;
password &lt;my_github_password&gt;
@ -489,98 +461,6 @@ password &lt;my_github_password&gt;
</div>
</section>
</section>
<section id="making-an-evennia-pull-request">
<h2>Making an Evennia Pull Request<a class="headerlink" href="#making-an-evennia-pull-request" title="Permalink to this headline"></a></h2>
<p>If you think that the fixes you did in your <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch should be a
part of the regular Evennia, you should create a <em>Pull Request</em> (PR). This is a
call for the Evennia maintainer to pull your change into an upstream branch.</p>
<blockquote>
<div><p>It is wise to make separate branches for every fix or series of fixes you want
to contribute.</p>
</div></blockquote>
<p>Assuming you have followed the instructions above and have pushed your changes
online, <a class="reference external" href="https://github.com/evennia/evennia/pulls">create a pull request</a> and
follow the instructions. Make sure to specifically select your <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code>
branch to be the source of the merge and use the branch you based that branch
off (<code class="docutils literal notranslate"><span class="pre">master</span></code> or <code class="docutils literal notranslate"><span class="pre">develop</span></code>) as the target.</p>
<p>Evennia developers will then be able to examine your request and merge it if
it’s deemed suitable. They may also come back with feedback and request you do
some changes.</p>
<p>Once approved and merged, your change will now be available in the upstream
branch:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master (or develope)
git pull upstream master (or develop)
</pre></div>
</div>
<p>Since your changes are now in upstream, your local <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch is now
superfluous and should be deleted:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branch -D strange_bug
</pre></div>
</div>
<p>You can also safely delete your online <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch in your fork
(you can do this from the PR page on github).</p>
</section>
<section id="git-tips-and-tricks">
<h2>GIT tips and tricks<a class="headerlink" href="#git-tips-and-tricks" title="Permalink to this headline"></a></h2>
<p>Some of the GIT commands can feel a little long and clunky if you need to do them often. Luckily you
can create aliases for those. Here are some useful commands to run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git st</span>
<span class="c1"># - view brief status info</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">st</span> <span class="s1">&#39;status -s&#39;</span>
</pre></div>
</div>
<p>Above, you only need to ever enter the <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">config</span> <span class="pre">...</span></code> command once - you have then added the new
alias. Afterwards, just do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">st</span></code> to get status info. All the examples below follow the same
template.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git cl</span>
<span class="c1"># - clone a repository</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">cl</span> <span class="n">clone</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git cma &quot;commit message&quot;</span>
<span class="c1"># - commit all changes without opening editor for message</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">cma</span> <span class="s1">&#39;commit -a -m&#39;</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git ca</span>
<span class="c1"># - amend text to your latest commit message</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">ca</span> <span class="s1">&#39;commit --amend&#39;</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git fl</span>
<span class="c1"># - file log; shows diffs of files in latest commits</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">fl</span> <span class="s1">&#39;log -u&#39;</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git co [branchname]</span>
<span class="c1"># - checkout</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">co</span> <span class="n">checkout</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git br &lt;branchname&gt;</span>
<span class="c1"># - create branch</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">br</span> <span class="n">branch</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git ls</span>
<span class="c1"># - view log tree</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">ls</span> <span class="s1">&#39;log --pretty=format:&quot;%C(green)%h\ %C(yellow)[</span><span class="si">%a</span><span class="s1">d]%Cred</span><span class="si">%d</span><span class="se">\</span>
<span class="s1">%Creset</span><span class="si">%s</span><span class="s1">%Cblue\ [</span><span class="si">%c</span><span class="s1">n]&quot; --decorate --date=relative --graph&#39;</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git diff</span>
<span class="c1"># - show current uncommitted changes</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">diff</span> <span class="s1">&#39;diff --word-diff&#39;</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git grep &lt;query&gt;</span>
<span class="c1"># - search (grep) codebase for a search criterion</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">grep</span> <span class="s1">&#39;grep -Ii&#39;</span>
</pre></div>
</div>
<p>To get a further feel for GIT there is also <a class="reference external" href="https://www.youtube.com/watch?v=1ffBJ4sVUb4#t=1m58s">a good YouTube talk about it</a> - it’s a bit long but it will help you understand the underlying ideas behind GIT
(which in turn makes it a lot more intuitive to use).</p>
</section>
</section>
@ -599,14 +479,14 @@ template.</p>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Updating-Your-Game.html" title="Updating Your Game"
<a href="Debugging.html" title="Debugging"
>next</a> |</li>
<li class="right" >
<a href="Coding-Overview.html" title="Coding and development help"
>previous</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-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Version Control</a></li>
<li class="nav-item nav-item-this"><a href="">Coding using Version Control</a></li>
</ul>
<div class="develop">develop branch</div>
</div>

2
docs/1.0-dev/Components/Connection-Screen.html
View file

@ -124,7 +124,7 @@
your game. This is simple:</p>
<ol class="simple">
<li><p>Edit <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/connection_screens.py</span></code>.</p></li>
<li><p><a class="reference internal" href="../Setup/Start-Stop-Reload.html"><span class="doc std std-doc">Reload</span></a> Evennia.</p></li>
<li><p><a class="reference internal" href="../Setup/Running-Evennia.html"><span class="doc std std-doc">Reload</span></a> Evennia.</p></li>
</ol>
<p>Evennia will look into this module and locate all <em>globally defined strings</em> in it. These strings
are used as the text in your connection screen and are shown to the user at startup. If more than

2
docs/1.0-dev/Components/Portal-And-Server.html
View file

@ -99,7 +99,7 @@
<section class="tex2jax_ignore mathjax_ignore" id="portal-and-server">
<h1>Portal And Server<a class="headerlink" href="#portal-and-server" title="Permalink to this headline"></a></h1>
<p>Evennia consists of two processes, known as <em>Portal</em> and <em>Server</em>. They can be controlled from
inside the game or from the command line as described <a class="reference internal" href="../Setup/Start-Stop-Reload.html"><span class="doc std std-doc">here</span></a>.</p>
inside the game or from the command line as described <a class="reference internal" href="../Setup/Running-Evennia.html"><span class="doc std std-doc">here</span></a>.</p>
<p>If you are new to the concept, the main purpose of separating the two is to have accounts connect to the Portal but keep the MUD running on the Server. This way one can restart/reload the game (the Server part) without Accounts getting disconnected.</p>
<p>![portal and server layout](https://474a3b9f-a-62cb3a1a-s- <a class="reference external" href="http://sites.googlegroups.com/site/evenniaserver/file-cabinet/evennia_server_portal.png">sites.googlegroups.com/site/evenniaserver/file-cabinet/evennia_server_portal.png</a>)</p>
<p>The Server and Portal are glued together via an AMP (Asynchronous Messaging Protocol) connection. This allows the two programs to communicate seamlessly.</p>

5
docs/1.0-dev/Concepts/Concepts-Overview.html
View file

@ -131,10 +131,7 @@
<li class="toctree-l2"><a class="reference internal" href="Soft-Code.html#your-solution">Your Solution</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Using-MUX-as-a-Standard.html">Using MUX as a Standard</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Using-MUX-as-a-Standard.html#documentation-policy">Documentation policy</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Using-MUX-as-a-Standard.html">Using MUX as a Standard</a></li>
<li class="toctree-l1"><a class="reference internal" href="Messagepath.html">Messagepath</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Messagepath.html#the-ingoing-message-path">The ingoing message path</a></li>
<li class="toctree-l2"><a class="reference internal" href="Messagepath.html#the-outgoing-message-path">The outgoing message path</a></li>

71
docs/1.0-dev/Concepts/Using-MUX-as-a-Standard.html
View file

@ -60,14 +60,6 @@
</div>
</div>
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Using MUX as a Standard</a><ul>
<li><a class="reference internal" href="#documentation-policy">Documentation policy</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Soft-Code.html"
title="previous chapter">Soft Code</a></p>
@ -113,69 +105,6 @@ deliberately lacks an online softcode language (a policy explained on our <a cla
page</span></a>). Evennia also does not shy from using its own syntax when deemed appropriate: the
MUX syntax has grown organically over a long time and is, frankly, rather arcane in places. All in
all the default command syntax should at most be referred to as “MUX-like” or “MUX-inspired”.</p>
<section id="documentation-policy">
<h2>Documentation policy<a class="headerlink" href="#documentation-policy" title="Permalink to this headline"></a></h2>
<p>All the commands in the default command sets should have their doc-strings formatted on a similar
form:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Short header</span>
<span class="sd"> </span>
<span class="sd"> Usage:</span>
<span class="sd"> key[/switches, if any] &lt;mandatory args&gt; [optional] choice1||choice2||choice3</span>
<span class="sd"> </span>
<span class="sd"> Switches:</span>
<span class="sd"> switch1 - description</span>
<span class="sd"> switch2 - description</span>
<span class="sd"> </span>
<span class="sd"> Examples:</span>
<span class="sd"> usage example and output</span>
<span class="sd"> </span>
<span class="sd"> Longer documentation detailing the command.</span>
<span class="sd"> </span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Two spaces are used for <em>indentation</em> in all default commands.</p></li>
<li><p>Square brackets <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">]</span></code> surround <em>optional, skippable arguments</em>.</p></li>
<li><p>Angled brackets <code class="docutils literal notranslate"><span class="pre">&lt;</span> <span class="pre">&gt;</span></code> surround a <em>description</em> of what to write rather than the exact syntax.</p></li>
<li><p>*Explicit choices are separated by <code class="docutils literal notranslate"><span class="pre">|</span></code>. To avoid this being parsed as a color code, use <code class="docutils literal notranslate"><span class="pre">||</span></code> (this
will come out as a single <code class="docutils literal notranslate"><span class="pre">|</span></code>) or put spaces around the character (“<code class="docutils literal notranslate"><span class="pre">|</span></code>”) if there’s plenty of
room.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">Switches</span></code> and <code class="docutils literal notranslate"><span class="pre">Examples</span></code> blocks are optional based on the Command.</p></li>
</ul>
<p>Here is the <code class="docutils literal notranslate"><span class="pre">nick</span></code> command as an example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Define a personal alias/nick</span>
<span class="sd"> </span>
<span class="sd"> Usage:</span>
<span class="sd"> nick[/switches] &lt;nickname&gt; = [&lt;string&gt;]</span>
<span class="sd"> alias &#39;&#39;</span>
<span class="sd"> </span>
<span class="sd"> Switches:</span>
<span class="sd"> object - alias an object</span>
<span class="sd"> account - alias an account</span>
<span class="sd"> clearall - clear all your aliases</span>
<span class="sd"> list - show all defined aliases (also &quot;nicks&quot; works)</span>
<span class="sd"> </span>
<span class="sd"> Examples:</span>
<span class="sd"> nick hi = say Hello, I&#39;m Sarah!</span>
<span class="sd"> nick/object tom = the tall man</span>
<span class="sd"> </span>
<span class="sd"> A &#39;nick&#39; is a personal shortcut you create for your own use [...]</span>
<span class="sd"> </span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>For commands that <em>require arguments</em>, the policy is for it to return a <code class="docutils literal notranslate"><span class="pre">Usage:</span></code> string if the
command is entered without any arguments. So for such commands, the Command body should contain
something to the effect of</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Usage: nick[/switches] &lt;nickname&gt; = [&lt;string&gt;]&quot;</span><span class="p">)</span>
<span class="k">return</span>
</pre></div>
</div>
</section>
</section>

10
docs/1.0-dev/Contribs/Contrib-AWSStorage.html
View file

@ -18,7 +18,7 @@
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Building menu" href="Contrib-Building-Menu.html" />
<link rel="prev" title="Contribs" href="Contribs-Overview.html" />
<link rel="prev" title="Guidelines for Evennia contribs" href="Contribs-Guidelines.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -33,7 +33,7 @@
<a href="Contrib-Building-Menu.html" title="Building menu"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Contribs-Overview.html" title="Contribs"
<a href="Contribs-Guidelines.html" title="Guidelines for Evennia contribs"
accesskey="P">previous</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-1"><a href="Contribs-Overview.html" accesskey="U">Contribs</a> &#187;</li>
@ -80,8 +80,8 @@
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Contribs-Overview.html"
title="previous chapter">Contribs</a></p>
<p class="topless"><a href="Contribs-Guidelines.html"
title="previous chapter">Guidelines for Evennia contribs</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Contrib-Building-Menu.html"
title="next chapter">Building menu</a></p>
@ -349,7 +349,7 @@ file will be overwritten, so edit that file rather than this one.</small></p>
<a href="Contrib-Building-Menu.html" title="Building menu"
>next</a> |</li>
<li class="right" >
<a href="Contribs-Overview.html" title="Contribs"
<a href="Contribs-Guidelines.html" title="Guidelines for Evennia contribs"
>previous</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-1"><a href="Contribs-Overview.html" >Contribs</a> &#187;</li>

251
docs/1.0-dev/Contribs/Contribs-Guidelines.html Normal file
View file

@ -0,0 +1,251 @@
<!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>Guidelines for Evennia contribs &#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" />
<link rel="next" title="AWSstorage system" href="Contrib-AWSStorage.html" />
<link rel="prev" title="Contribs" href="Contribs-Overview.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="right" >
<a href="Contrib-AWSStorage.html" title="AWSstorage system"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Contribs-Overview.html" title="Contribs"
accesskey="P">previous</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-1"><a href="Contribs-Overview.html" accesskey="U">Contribs</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Guidelines for Evennia contribs</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Guidelines for Evennia contribs</a><ul>
<li><a class="reference internal" href="#what-is-suitable-for-a-contrib">What is suitable for a contrib?</a></li>
<li><a class="reference internal" href="#layout-of-a-contrib">Layout of a contrib</a></li>
<li><a class="reference internal" href="#submitting-a-contrib">Submitting a contrib</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Contribs-Overview.html"
title="previous chapter">Contribs</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Contrib-AWSStorage.html"
title="next chapter">AWSstorage system</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Contribs/Contribs-Guidelines.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="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>Versions</h3>
<ul>
<li><a href="Contribs-Guidelines.html">1.0-dev (develop branch)</a></li>
<ul>
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="guidelines-for-evennia-contribs">
<h1>Guidelines for Evennia contribs<a class="headerlink" href="#guidelines-for-evennia-contribs" title="Permalink to this headline"></a></h1>
<p>Evennia has a <a class="reference internal" href="Contribs-Overview.html"><span class="doc std std-doc">contrib</span></a> directory which contains optional, community-shared code organized by category. Anyone is welcome to contribute.</p>
<section id="what-is-suitable-for-a-contrib">
<h2>What is suitable for a contrib?<a class="headerlink" href="#what-is-suitable-for-a-contrib" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p>In general, you can contribute anything that you think may be useful to another developer. Unlike the ‘core’ Evennia, contribs can also be highly game-type-specific.</p></li>
<li><p>Very small or incomplete snippets of code (e.g. meant to paste into some other code) are better shared as a post in the <a class="reference external" href="https://github.com/evennia/evennia/discussions/2488">Community Contribs &amp; Snippets</a> discussion forum category.</p></li>
<li><p>If your code is intended <em>primarily</em> as an example or to show a concept/principle rather than a working system, consider if it may be better to instead <a class="reference internal" href="../Contributing-Docs.html"><span class="doc std std-doc">contribute to the documentation</span></a> by writing a new tutorial or howto.</p></li>
<li><p>If possible, try to make your contribution as genre-agnostic as possible and assume
your code will be applied to a very different game than you had in mind when creating it.</p></li>
<li><p>The contribution should preferably work in isolation from other contribs (only make use of core Evennia) so it can easily be dropped into use. If it does depend on other contribs or third-party modules, these must be clearly documented and part of the installation instructions.</p></li>
<li><p>If you are unsure about if your contrib idea is suitable or sound, <em>ask in discussions or chat before putting any work into it</em>. We are, for example, unlikely to accept contribs that require large modifications of the game directory structure.</p></li>
</ul>
</section>
<section id="layout-of-a-contrib">
<h2>Layout of a contrib<a class="headerlink" href="#layout-of-a-contrib" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p>The contrib must be contained only within a single folder under one of the contrib categories below. Ask if you are unsure which category fits best for your contrib.</p></li>
</ul>
<table class="colwidths-auto docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p></p></th>
<th class="head"><p></p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">base_systems/</span></code></p></td>
<td><p><em>Systems that are not necessarily tied to a specific in-game mechanic but which are useful for the game as a whole. Examples include login systems, new command syntaxes, and build helpers.</em></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">full_systems/</span></code></p></td>
<td><p><em>‘Complete’ game engines that can be used directly to start creating content without no further additions (unless you want to).</em></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">game_systems/</span></code></p></td>
<td><p><em>In-game gameplay systems like crafting, mail, combat and more. Each system is meant to be adopted piecemeal and adopted for your game. This does not include roleplaying-specific systems, those are found in the <code class="docutils literal notranslate"><span class="pre">rpg</span></code> category.</em></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">grid/</span></code></p></td>
<td><p><em>Systems related to the game world’s topology and structure. Contribs related to rooms, exits and map building.</em></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">rpg/</span></code></p></td>
<td><p><em>Systems specifically related to roleplaying and rule implementation like character traits, dice rolling and emoting.</em></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">tutorials/</span></code></p></td>
<td><p><em>Helper resources specifically meant to teach a development concept or to exemplify an Evennia system. Any extra resources tied to documentation tutorials are found here. Also the home of the Tutorial-World and Evadventure demo codes.</em></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">tools/</span></code></p></td>
<td><p><em>Miscellaneous tools for manipulating text, security auditing, and more.</em></p></td>
</tr>
</tbody>
</table>
<ul>
<li><p>The folder (package) should be on the following form:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span><span class="o">/</span>
<span class="n">contrib</span><span class="o">/</span>
<span class="n">category</span><span class="o">/</span> <span class="c1"># rpg/, game_systems/ etc</span>
<span class="n">mycontribname</span><span class="o">/</span>
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
<span class="n">README</span><span class="o">.</span><span class="n">md</span>
<span class="n">module1</span><span class="o">.</span><span class="n">py</span>
<span class="n">module2</span><span class="o">.</span><span class="n">py</span>
<span class="o">...</span>
<span class="n">tests</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>It’s often a good idea to import useful resources in <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> to make it easier to import them.</p>
</li>
<li><p>Your code should abide by the <a class="reference internal" href="../Coding/Evennia-Code-Style.html"><span class="doc std std-doc">Evennia Style Guide</span></a>. Write it to be easy to read.</p></li>
<li><p>Your contribution <em>must</em> be covered by <a class="reference internal" href="../Coding/Unit-Testing.html"><span class="doc std std-doc">unit tests</span></a>. Put your tests in a module <code class="docutils literal notranslate"><span class="pre">tests.py</span></code> under your contrib folder (as seen above) - Evennia will find them automatically.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">README.md</span></code> file will be parsed and converted into a document linked from <a class="reference internal" href="Contribs-Overview.html"><span class="doc std std-doc">the contrib overview page</span></a>. It needs to be on the following form:</p>
<div class="highlight-markdown notranslate"><div class="highlight"><pre><span></span><span class="gh"># MyContribName</span>
Contribution by &lt;yourname&gt;, &lt;year&gt;
A paragraph (can be multi-line)
summarizing the contrib (required)
Optional other text
<span class="gu">## Installation</span>
Detailed installation instructions for using the contrib (required)
<span class="gu">## Usage</span>
<span class="gu">## Examples</span>
etc.
</pre></div>
</div>
</li>
</ul>
<blockquote>
<div><p>The credit and first paragraph-summary will be automatically included on the Contrib overview page index for each contribution, so it needs to be just on this form.</p>
</div></blockquote>
</section>
<section id="submitting-a-contrib">
<h2>Submitting a contrib<a class="headerlink" href="#submitting-a-contrib" title="Permalink to this headline"></a></h2>
<aside class="sidebar">
<p class="sidebar-title">Not all PRs can be accepted</p>
<p>While most PRs get merged, this is not guaranteed: Merging a contrib means the Evennia project takes on the responsibility of maintaining and supporting the new code. For various reasons this may be deemed unfeasible.</p>
<p>If your code were to <em>not</em> be accepted for some reason, we can still link it from our links page; it can also be posted in our discussion forum.</p>
</aside>
<ul class="simple">
<li><p>A contrib must always be presented <a class="reference internal" href="../Coding/Version-Control.html#contributing-to-evennia"><span class="std std-doc">as a pull request</span></a> (PR).</p></li>
<li><p>PRs are reviewed so don’t be surprised (or disheartened) if you are asked to modify or change your code before it can be merged. Your code can end up going through several iterations before it is accepted.</p></li>
<li><p>To make the licensing situation clear we assume all contributions are released with the same <a class="reference internal" href="../Licensing.html"><span class="doc std std-doc">license as Evennia</span></a>. If this is not possible for some reason, talk to us and we’ll handle it on a case-by-case basis.</p></li>
</ul>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Contrib-AWSStorage.html" title="AWSstorage system"
>next</a> |</li>
<li class="right" >
<a href="Contribs-Overview.html" title="Contribs"
>previous</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-1"><a href="Contribs-Overview.html" >Contribs</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Guidelines for Evennia contribs</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2022, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>

26
docs/1.0-dev/Contribs/Contribs-Overview.html
View file

@ -17,7 +17,7 @@
<link rel="shortcut 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="AWSstorage system" href="Contrib-AWSStorage.html" />
<link rel="next" title="Guidelines for Evennia contribs" href="Contribs-Guidelines.html" />
<link rel="prev" title="Setting up PyCharm with Evennia" href="../Coding/Setting-up-PyCharm.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,7 +30,7 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Contrib-AWSStorage.html" title="AWSstorage system"
<a href="Contribs-Guidelines.html" title="Guidelines for Evennia contribs"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../Coding/Setting-up-PyCharm.html" title="Setting up PyCharm with Evennia"
@ -141,8 +141,8 @@
<p class="topless"><a href="../Coding/Setting-up-PyCharm.html"
title="previous chapter">Setting up PyCharm with Evennia</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Contrib-AWSStorage.html"
title="next chapter">AWSstorage system</a></p>
<p class="topless"><a href="Contribs-Guidelines.html"
title="next chapter">Guidelines for Evennia contribs</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -192,7 +192,7 @@ with the Evennia distribution.</p>
<p>Each contrib contains installation instructions for how to integrate it
with your other code. If you want to tweak the code of a contrib, just
copy its entire folder to your game directory and modify/use it from there.</p>
<p>If you want to contribute yourself, see <a class="reference internal" href="../Contributing.html"><span class="doc std std-doc">here</span></a>!</p>
<p>If you want to add a contrib, see <a class="reference internal" href="Contribs-Guidelines.html"><span class="doc std std-doc">the contrib guidelines</span></a>!</p>
<section id="index">
<h2>Index<a class="headerlink" href="#index" title="Permalink to this headline"></a></h2>
<table class="colwidths-auto docutils align-default">
@ -296,6 +296,8 @@ copy its entire folder to your game directory and modify/use it from there.</p>
in-game mechanic but which are useful for the game as a whole. Examples include
login systems, new command syntaxes, and build helpers.</em></p>
<div class="toctree-wrapper compound">
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Contrib-AWSStorage.html">AWSstorage system</a></li>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Building-Menu.html">Building menu</a></li>
@ -414,6 +416,8 @@ library under the hood.</p>
<p><em>‘Complete’ game engines that can be used directly to start creating content
without no further additions (unless you want to).</em></p>
<div class="toctree-wrapper compound">
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Evscaperoom.html">EvscapeRoom</a></li>
</ul>
@ -436,6 +440,8 @@ Each system is meant to be adopted piecemeal and adopted for your game.
This does not include roleplaying-specific systems, those are found in
the <code class="docutils literal notranslate"><span class="pre">rpg</span></code> category.</em></p>
<div class="toctree-wrapper compound">
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Barter.html">Barter system</a></li>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Clothing.html">Clothing</a></li>
@ -542,6 +548,8 @@ the participants until the fight ends.</p>
<p><em>Systems related to the game world’s topology and structure. Contribs related
to rooms, exits and map building.</em></p>
<div class="toctree-wrapper compound">
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Extended-Room.html">Extended Room</a></li>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Ingame-Map-Display.html">Basic Map</a></li>
@ -619,6 +627,8 @@ current location (useful for displaying the grid as an in-game, updating map).</
<p><em>Systems specifically related to roleplaying
and rule implementation like character traits, dice rolling and emoting.</em></p>
<div class="toctree-wrapper compound">
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Buffs.html">Buffs</a></li>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Character-Creator.html">Character Creator</a></li>
@ -691,6 +701,8 @@ to exemplify an Evennia system. Any extra resources tied to documentation
tutorials are found here. Also the home of the Tutorial-World and Evadventure
demo codes.</em></p>
<div class="toctree-wrapper compound">
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Batchprocessor.html">Batch processor examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Bodyfunctions.html">Script example</a></li>
@ -764,6 +776,8 @@ is a great way to start learning the system.</p>
<h2>utils<a class="headerlink" href="#utils" title="Permalink to this headline"></a></h2>
<p><em>Miscellaneous, tools for manipulating text, security auditing, and more.</em></p>
<div class="toctree-wrapper compound">
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Auditing.html">Input/Output Auditing</a></li>
<li class="toctree-l1"><a class="reference internal" href="Contrib-Fieldfill.html">Easy fillable form</a></li>
@ -846,7 +860,7 @@ will be overwritten.</small></p>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Contrib-AWSStorage.html" title="AWSstorage system"
<a href="Contribs-Guidelines.html" title="Guidelines for Evennia contribs"
>next</a> |</li>
<li class="right" >
<a href="../Coding/Setting-up-PyCharm.html" title="Setting up PyCharm with Evennia"

189
docs/1.0-dev/Contributing.html
View file

@ -62,20 +62,15 @@
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">How To Contribute And Get Help</a><ul>
<li><a class="reference internal" href="#community-and-spreading-the-word">Community and Spreading the word</a></li>
<li><a class="reference internal" href="#getting-help">Getting Help</a></li>
<li><a class="reference internal" href="#giving-help">Giving Help</a><ul>
<li><a class="reference internal" href="#help-with-documentation">Help with Documentation</a></li>
<li><a class="reference internal" href="#helping-with-code">Helping with code</a><ul>
<li><a class="reference internal" href="#using-a-forked-reposity">Using a Forked reposity</a></li>
<li><a class="reference internal" href="#contributing-with-patches">Contributing with Patches</a></li>
<li><a class="reference internal" href="#making-an-evennia-contrib">Making an Evennia contrib</a><ul>
<li><a class="reference internal" href="#guidelines-for-making-a-contrib">Guidelines for making a contrib</a></li>
<li><a class="reference internal" href="#helping-with-code">Helping with code</a></li>
<li><a class="reference internal" href="#helping-with-donations">Helping with Donations</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#donations">Donations</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
@ -116,170 +111,44 @@
<section class="tex2jax_ignore mathjax_ignore" id="how-to-contribute-and-get-help">
<h1>How To Contribute And Get Help<a class="headerlink" href="#how-to-contribute-and-get-help" title="Permalink to this headline"></a></h1>
<p>If you cannot find what you are looking for in the documentation, here’s what to do:</p>
<section id="getting-help">
<h2>Getting Help<a class="headerlink" href="#getting-help" title="Permalink to this headline"></a></h2>
<p>If you cannot find what you are looking for in the documentation, here’s where to go next:</p>
<ul class="simple">
<li><p>If you need help, want to start a discussion or get some input on something
you are working on, make a post to the <a class="reference external" href="https://github.com/evennia/evennia/discussions">discussions forum</a>.</p></li>
<li><p>If you want more direct discussions with developers and other users, drop
into our very friendly <a class="reference external" href="https://discord.com/invite/AJJpcRUhtF">Discord channel</a>.</p></li>
<li><p>If you think the documentation is not clear enough, create a <a class="reference external" href="https://github.com/evennia/evennia/issues">documentation issue</a>.</p></li>
<li><p>If you have trouble with a missing feature or a problem you think is a bug,
<a class="reference external" href="https://github.com/evennia/evennia/issues">request, or report it</a>.</p></li>
<li><p><a class="reference external" href="https://github.com/evennia/evennia/discussions">The Discussions forums</a> are great for getting help, starting longer-form discussions, showing off your work or get some input on what you are working on. This is also the place to follow Evennia development.</p></li>
<li><p><a class="reference external" href="https://discord.com/invite/AJJpcRUhtF">The Discord server</a> has a very helpful <code class="docutils literal notranslate"><span class="pre">#getting-help</span></code> channel for both big and small Evennia problems. It allows for more direct discussion. You can also track both the evennia code changes and the discussion forum from discord.</p></li>
</ul>
<section id="community-and-spreading-the-word">
<h2>Community and Spreading the word<a class="headerlink" href="#community-and-spreading-the-word" title="Permalink to this headline"></a></h2>
<p>Being active and helpful in the <a class="reference external" href="https://github.com/evennia/evennia/discussions">discssion forums</a> or <a class="reference external" href="https://discord.com/invite/AJJpcRUhtF">chat</a> is already a big help.</p>
<p>Consider writing about Evennia on your blog or in your favorite (relevant)
forum. Write a review somewhere (good or bad, we like feedback either way). Rate
it on listings. Talk about it to your friends … that kind of thing.</p>
</section>
<section id="giving-help">
<h2>Giving Help<a class="headerlink" href="#giving-help" title="Permalink to this headline"></a></h2>
<p>In general, being active and helpful in the <a class="reference external" href="https://github.com/evennia/evennia/discussions">discssion forums</a> or <a class="reference external" href="https://discord.com/invite/AJJpcRUhtF">discord chat</a> is already a big help!</p>
<p>If you want to spread the word, consider writing about Evennia on your blog or in your favorite (relevant) forum. Write a review somewhere (good or bad, we like feedback either way). Rate it on listings. Talk about it to your friends … that kind of thing.</p>
<section id="help-with-documentation">
<h2>Help with Documentation<a class="headerlink" href="#help-with-documentation" title="Permalink to this headline"></a></h2>
<p>Evennia depends heavily on good documentation and we are always looking for
extra eyes and hands to improve it. Even small things such as fixing typos are a
great help!</p>
<h3>Help with Documentation<a class="headerlink" href="#help-with-documentation" title="Permalink to this headline"></a></h3>
<p>Evennia is highly dependent on good-quality documentation!</p>
<ul class="simple">
<li><p>Easiest is to just <a class="reference external" href="https://github.com/evennia/evennia/issues">report documentation issues</a> as you find them. If
we don’t know about them, we can’t fix them!</p></li>
<li><p>If you want to help editing the docs directly, <a class="reference internal" href="Contributing-Docs.html"><span class="doc std std-doc">check here</span></a> on how to do it.</p></li>
<li><p>If you have knowledge to share, how about writing a new <a class="reference internal" href="Howtos/Howtos-Overview.html"><span class="doc std std-doc">Tutorial</span></a>?</p></li>
<li><p><a class="reference external" href="https://github.com/evennia/evennia/issues">Reporting a Documentation issue</a> is the easiest way to help out. The more eyes we get on things, the better - if we don’t know about the problems, we can’t fix them! Even reporting typos is a great help.</p></li>
<li><p><a class="reference internal" href="Contributing-Docs.html"><span class="doc std std-doc">Contributing directly to the docs</span></a> is also possible; you just need a text editor. You can fix issues or even propose a new tutorial!</p></li>
</ul>
</section>
<section id="helping-with-code">
<h2>Helping with code<a class="headerlink" href="#helping-with-code" title="Permalink to this headline"></a></h2>
<p>If you find bugs, or have a feature-request, <a class="reference external" href="https://github.com/evennia/evennia/issues">make an issue</a> for it. If
it’s not in an issue, the issue will most likely be forgotten.</p>
<p>Even if you don’t feel confident with tackling a bug or feature, just
correcting typos, adjusting formatting or simply <em>using</em> the thing and reporting
when stuff doesn’t make sense helps us a lot.</p>
<h3>Helping with code<a class="headerlink" href="#helping-with-code" title="Permalink to this headline"></a></h3>
<p>Even if you don’t feel confident with tackling a bug or feature, just correcting typos, adjusting formatting or simply <em>using</em> the thing and reporting when stuff doesn’t make sense helps us a lot!</p>
<ul class="simple">
<li><p>The code itself should follow Evennia’s <a class="reference external" href="https://github.com/evennia/evennia/blob/master/CODING_STYLE.md">Code style guidelines</a> both
for code and documentation. You should write code for that others can read an understand.</p></li>
<li><p>Before merging, your code will be reviewed. Merging of your code into Evennia
is not guaranteed. Be ready to receive feedback and to be asked to make
corrections or fix bugs or any documentation issues and possibly tests (this
is normal and nothing to worry about).</p></li>
<li><p><a class="reference external" href="https://github.com/evennia/evennia/issues">Reporting a code issue or bug</a> is the easiest way to help out. Don’t assume we are aware of a problem - if it’s not written down in an issue, the problem will most likely be forgotten. Do this even if you plan to make a <em>Pull Request</em> and fix the issue yourself.</p></li>
<li><p><a class="reference external" href="https://github.com/evennia/evennia/issues">Make a feature request</a> if you want to see a new Evennia feature. You can also bring it up with the community first so you are sure it’s something that would be interesting to be included with Evennia core.</p></li>
<li><p><a class="reference internal" href="Coding/Version-Control.html#contributing-to-evennia"><span class="std std-doc">Make a Pull Request</span></a> (PR) to fix bugs or new features. Make sure to follow the <a class="reference internal" href="Coding/Evennia-Code-Style.html"><span class="doc std std-doc">Evennia Code-Style guide</span></a>.</p></li>
<li><p><a class="reference internal" href="Contribs/Contribs-Guidelines.html"><span class="doc std std-doc">The Guide for making an Evennia contrib</span></a> outlines how you do to make your own Evennia <a class="reference internal" href="Contribs/Contribs-Overview.html"><span class="doc std std-doc">contrib</span></a> to distribute with Evennia.</p></li>
</ul>
<section id="using-a-forked-reposity">
<h3>Using a Forked reposity<a class="headerlink" href="#using-a-forked-reposity" title="Permalink to this headline"></a></h3>
<p>The most elegant way to contribute code to Evennia is to use GitHub to create a
<em>fork</em> of the Evennia repository and make your changes to that. Refer to the
<a class="reference internal" href="Coding/Version-Control.html#forking-evennia"><span class="std std-doc">Forking Evennia</span></a> version control instructions for detailed instructions.</p>
<p>Once you have a fork set up, you can not only work on your own game in a
separate branch, you can also commit your fixes to Evennia itself.</p>
</section>
<section id="helping-with-donations">
<h3>Helping with Donations<a class="headerlink" href="#helping-with-donations" title="Permalink to this headline"></a></h3>
<p>Evennia is a free and open-source project. Any monetary donations you want to offer are <em>completely voluntary</em>. While highly appreciated, we don’t expect you to donate and don’t hide any secret features behind a donation-paywall. Just see it as a way of showing appreciation by dropping a few coins in the cup.</p>
<ul class="simple">
<li><p>Make separate branches for all Evennia additions you do - don’t edit your
local <code class="docutils literal notranslate"><span class="pre">master</span></code> or <code class="docutils literal notranslate"><span class="pre">develop</span></code> branches directly. It will make your life a lot easier.</p></li>
<li><p>If you have a change that you think is suitable for the main Evennia
repository, issue a <a class="reference external" href="https://github.com/evennia/evennia/pulls">Pull Request</a>. This will let Evennia devs know you have stuff to share.</p></li>
<li><p>Bug fixes should generally be done against the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch of Evennia,
while new features/contribs should go into the <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch. If you are
unsure, just pick one and we’ll figure it out.</p></li>
<li><p><a class="reference external" href="https://www.patreon.com/griatch">Become an Evennia patron</a> which donates a (usually small) sum every month to show continued support.</p></li>
<li><p><a class="reference external" href="https://www.paypal.com/paypalme/GriatchEvennia">Make a one-time donation</a> if a monthly donation is not your thing. This is a PayPal link but you don’t need PayPal yourself to use it.</p></li>
</ul>
</section>
<section id="contributing-with-patches">
<h3>Contributing with Patches<a class="headerlink" href="#contributing-with-patches" title="Permalink to this headline"></a></h3>
<p>To help with Evennia development it’s strongly recommended to do so using a
forked repository as described above. But for small, well isolated fixes you are
also welcome to submit your suggested Evennia fixes/addendums as a
<a class="reference external" href="https://secure.wikimedia.org/wikipedia/en/wiki/Patch_%28computing%29">patch</a>.</p>
<p>You can include your patch in an Issue or a Mailing list post. Please avoid
pasting the full patch text directly in your post though, best is to use a site
like <a class="reference external" href="https://pastebin.com/">Pastebin</a> and just supply the link.</p>
</section>
<section id="making-an-evennia-contrib">
<h3>Making an Evennia contrib<a class="headerlink" href="#making-an-evennia-contrib" title="Permalink to this headline"></a></h3>
<p>Evennia has a <a class="reference internal" href="Contribs/Contribs-Overview.html"><span class="doc std std-doc">contrib</span></a> directory which contains
user-shared code organized by category. You can contribute anything that you
think may be useful to another dev, also highly game-specific code. A contrib
must always be added via a forked repository.</p>
<section id="guidelines-for-making-a-contrib">
<h4>Guidelines for making a contrib<a class="headerlink" href="#guidelines-for-making-a-contrib" title="Permalink to this headline"></a></h4>
<ul>
<li><p>If you are unsure about if your contrib idea is suitable or sound, <em>ask in
discussions or chat before putting any work into it</em>. We are, for example,
unlikely to accept contribs that require large modifications of the game
directory structure.</p></li>
<li><p>If your code is intended <em>primarily</em> as an example or to show a
concept/principle rather than a working system, you <em>can</em> add to the
<code class="docutils literal notranslate"><span class="pre">contribs/tutorials/</span></code> subfolder, but consider if it may be better to instead
write a new tutorial doc page.</p></li>
<li><p>The contribution should preferably work in isolation from other contribs (only
make use of core Evennia) so it can easily be dropped into use. If it does
depend on other contribs or third-party modules, these must be clearly
documented and part of the installation instructions.</p></li>
<li><p>The contrib must be contained within a separate folder under one of the
contrib categories (<code class="docutils literal notranslate"><span class="pre">game_systems</span></code>, <code class="docutils literal notranslate"><span class="pre">rpg</span></code>, <code class="docutils literal notranslate"><span class="pre">utils</span></code> etc). Ask if you are
unsure which category to put your contrib under.</p></li>
<li><p>The folder (package) should be on the following form:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mycontribname</span><span class="o">/</span>
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
<span class="n">README</span><span class="o">.</span><span class="n">md</span>
<span class="n">module1</span><span class="o">.</span><span class="n">py</span>
<span class="n">module2</span><span class="o">.</span><span class="n">py</span>
<span class="o">...</span>
<span class="n">tests</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>It’s often a good idea to import useful resources in <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> to make
it easier to access them (this may vary though).</p>
<p>The <code class="docutils literal notranslate"><span class="pre">README.md</span></code> will be parsed and converted into a document linked from
<a class="reference internal" href="Contribs/Contribs-Overview.html"><span class="doc std std-doc">the contrib overview page</span></a>. It should follow
the following structure:</p>
<div class="highlight-markdown notranslate"><div class="highlight"><pre><span></span><span class="gh"># MyContribName</span>
Contribution by &lt;yourname&gt;, &lt;year&gt;
A paragraph (can be multi-line)
summarizing the contrib (required)
Optional other text
<span class="gu">## Installation</span>
Detailed installation instructions for using the contrib (required)
<span class="gu">## Usage</span>
<span class="gu">## Examples</span>
etc.
</pre></div>
</div>
<p>The credit and first paragraph-summary will be used on the index page. Every
contrib’s readme must contain an installation instruction. See existing contribs
for help.</p>
</li>
<li><p>If possible, try to make contribution as genre-agnostic as possible and assume
your code will be applied to a very different game than you had in mind when creating it.</p></li>
<li><p>To make the licensing situation clear we assume all contributions are released
with the same <a class="reference internal" href="Licensing.html"><span class="doc std std-doc">license as Evennia</span></a>. If this is not possible
for some reason, talk to us and we’ll handle it on a case-by-case basis.</p></li>
<li><p>Your contribution must be covered by <a class="reference internal" href="Coding/Unit-Testing.html"><span class="doc std std-doc">unit tests</span></a>. Put
your tests in a module <code class="docutils literal notranslate"><span class="pre">tests.py</span></code> under your contrib folder - Evennia will
find them automatically.</p></li>
<li><p>In addition to the normal review process, it’s worth noting that merging a
contrib means the Evennia project takes on the responsibility of maintaining
and supporting it. For various reasons this may be deemed beyond our manpower.</p></li>
<li><p>If your code were to <em>not</em> be accepted for some reason, you can ask us to
instead link to your repo from our link page so people can find your code that
way.</p></li>
</ul>
</section>
</section>
</section>
<section id="donations">
<h2>Donations<a class="headerlink" href="#donations" title="Permalink to this headline"></a></h2>
<p>Evennia is a free, open-source project and any monetary donations you want to
offer are <em>completely voluntary</em>. See it as a way of showing appreciation by
dropping a few coins in the cup.</p>
<ul class="simple">
<li><p>You can support Evennia as an <a class="reference external" href="https://www.patreon.com/griatch">Evennia patreon</a>. A patreon donates a
(usually small) sum every month to show continued support.</p></li>
<li><p>If a monthly donation is not your thing, you can also show your appreciation
by doing a <a class="reference external" href="https://www.paypal.com/donate?token=zbU72YdRqPgsbpTw3M_4vR-5QJ7XvUhL9W6JlnPJw70M9LOqY1xD7xKGx0V1jLFSthY3xAztQpSsqW9n">one-time donation</a> (this is a PayPal link but you don’t need
PayPal yourself to use it).</p></li>
</ul>
</section>
</section>

10
docs/1.0-dev/Evennia-Introduction.html
View file

@ -17,7 +17,7 @@
<link rel="shortcut 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="Server Setup and Life" href="Setup/Setup-Overview.html" />
<link rel="next" title="Start Stop Reload" href="Setup/Running-Evennia.html" />
<link rel="prev" title="Evennia Documentation" href="index.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,7 +30,7 @@
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Setup/Setup-Overview.html" title="Server Setup and Life"
<a href="Setup/Running-Evennia.html" title="Start Stop Reload"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Evennia Documentation"
@ -78,8 +78,8 @@
<p class="topless"><a href="index.html"
title="previous chapter">Evennia Documentation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Setup/Setup-Overview.html"
title="next chapter">Server Setup and Life</a></p>
<p class="topless"><a href="Setup/Running-Evennia.html"
title="next chapter">Start Stop Reload</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -203,7 +203,7 @@ presence (a website and a mud web client) to play around with …</p>
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Setup/Setup-Overview.html" title="Server Setup and Life"
<a href="Setup/Running-Evennia.html" title="Start Stop Reload"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Evennia Documentation"

2
docs/1.0-dev/Glossary.html
View file

@ -308,7 +308,7 @@ latest changes, just <code class="docutils literal notranslate"><span class="pre
</pre></div>
</div>
<p>That should be it (see <a class="reference internal" href="#virtualenv"><span class="std std-doc">virtualenv</span></a> if you get a warning that the <code class="docutils literal notranslate"><span class="pre">evennia</span></code>
command is not available). See also <a class="reference internal" href="Coding/Updating-Your-Game.html"><span class="doc std std-doc">Updating your game</span></a> for more details.</p>
command is not available). See also <a class="reference internal" href="Setup/Updating-Evennia.html"><span class="doc std std-doc">Updating your game</span></a> for more details.</p>
<blockquote>
<div><p>Technically, migrations are shipped as little Python snippets of code that explains which database
actions must be taken to upgrade from one version of the schema to the next. When you run the

144
docs/1.0-dev/Setup/Choosing-a-Database.html
View file

@ -63,23 +63,25 @@
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Choosing a database</a><ul>
<li><a class="reference internal" href="#sqlite3">SQLite3</a><ul>
<li><a class="reference internal" href="#sqlite3-default">SQLite3 (default)</a><ul>
<li><a class="reference internal" href="#install-of-sqlite3">Install of SQlite3</a></li>
<li><a class="reference internal" href="#resetting-sqlite3-database">Resetting SQLite3 database</a></li>
<li><a class="reference internal" href="#resetting-sqlite3">Resetting SQLite3</a></li>
</ul>
</li>
<li><a class="reference internal" href="#postgresql">PostgreSQL</a><ul>
<li><a class="reference internal" href="#install-and-initial-setup-of-postgresql">Install and initial setup of PostgreSQL</a></li>
<li><a class="reference internal" href="#evennia-postgresql-configuration">Evennia PostgreSQL configuration</a></li>
<li><a class="reference internal" href="#advanced-postgresql-usage-remote-server">Advanced Postgresql Usage (Remote Server)</a></li>
<li><a class="reference internal" href="#resetting-postgresql">Resetting PostgreSQL</a></li>
<li><a class="reference internal" href="#advanced-postgresql-usage-remote-server">Advanced PostgreSQL Usage (Remote Server)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#mysql-mariadb">MySQL / MariaDB</a><ul>
<li><a class="reference internal" href="#installing-and-initial-setup-of-mysql-mariadb">Installing and initial setup of MySQL/MariaDB</a></li>
<li><a class="reference internal" href="#add-mysql-mariadb-configuration-to-evennia">Add MySQL/MariaDB configuration to Evennia</a></li>
<li><a class="reference internal" href="#resetting-mysql-mariadb">Resetting MySQL/MariaDB</a></li>
</ul>
</li>
<li><a class="reference internal" href="#add-mysql-configuration-to-evennia">Add MySQL configuration to Evennia</a></li>
<li><a class="reference internal" href="#others">Others</a></li>
<li><a class="reference internal" href="#other-databases">Other databases</a></li>
</ul>
</li>
</ul>
@ -130,13 +132,10 @@
</ul>
<p>Since Evennia uses <a class="reference external" href="https://djangoproject.com">Django</a>, most of our notes are based off of what we know from the community and their documentation. While the information below may be useful, you can always find the most up-to-date and “correct” information at Django’s <a class="reference external" href="https://docs.djangoproject.com/en/dev/ref/databases/#ref-databases">Notes about supported
Databases</a> page.</p>
<section id="sqlite3">
<h2>SQLite3<a class="headerlink" href="#sqlite3" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://sqlite.org/">SQLite3</a> is a light weight single-file database. It is our default database
and Evennia will set this up for you automatically if you give no other options. SQLite stores the
database in a single file (<code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>). This means it’s very easy to reset this
database - just delete (or move) that <code class="docutils literal notranslate"><span class="pre">evennia.db3</span></code> file and run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> again! No server process is needed and the administrative overhead and resource consumption is tiny. It is also very fast since it’s run in-memory. For the vast majority of Evennia installs it will probably be all
that’s ever needed.</p>
<section id="sqlite3-default">
<h2>SQLite3 (default)<a class="headerlink" href="#sqlite3-default" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://sqlite.org/">SQLite3</a> is a light weight single-file database. It is our default database and Evennia will set this up for you automatically if you give no other options.</p>
<p>SQLite stores the database in a single file (<code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>). This means it’s very easy to reset this database - just delete (or move) that <code class="docutils literal notranslate"><span class="pre">evennia.db3</span></code> file and run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> again! No server process is needed and the administrative overhead and resource consumption is tiny. It is also very fast since it’s run in-memory. For the vast majority of Evennia installs it will probably be all that’s ever needed.</p>
<p>SQLite will generally be much faster than MySQL/PostgreSQL but its performance comes with two
drawbacks:</p>
<ul class="simple">
@ -160,13 +159,9 @@ evennia database is <code class="docutils literal notranslate"><span class="pre"
<p>This will bring you into the sqlite command line. Use <code class="docutils literal notranslate"><span class="pre">.help</span></code> for instructions and <code class="docutils literal notranslate"><span class="pre">.quit</span></code> to exit.
See <a class="reference external" href="https://gist.github.com/vincent178/10889334">here</a> for a cheat-sheet of commands.</p>
</section>
<section id="resetting-sqlite3-database">
<h3>Resetting SQLite3 database<a class="headerlink" href="#resetting-sqlite3-database" title="Permalink to this headline"></a></h3>
<p>To reset your database and start from scratch, simply stop Evennia and delete the <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>. Then run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> again.</p>
<aside class="sidebar">
<p class="sidebar-title">Hint</p>
<p>Make a copy of the <code class="docutils literal notranslate"><span class="pre">evennia.db3</span></code> file once you created your superuser. When you want to reset, you can just stop evennia and copy that file back over <code class="docutils literal notranslate"><span class="pre">evennia.db3</span></code>. That way you don’t have to run migrations and create the superuser every time!</p>
</aside>
<section id="resetting-sqlite3">
<h3>Resetting SQLite3<a class="headerlink" href="#resetting-sqlite3" title="Permalink to this headline"></a></h3>
<p>If you want to reset your SQLite3 database, see <a class="reference internal" href="Updating-Evennia.html#sqlite3-default"><span class="std std-doc">here</span></a>.</p>
</section>
</section>
<section id="postgresql">
@ -176,11 +171,9 @@ While not as fast as SQLite for normal usage, it will scale better than SQLite,
game has an very large database and/or extensive web presence through a separate server process.</p>
<section id="install-and-initial-setup-of-postgresql">
<h3>Install and initial setup of PostgreSQL<a class="headerlink" href="#install-and-initial-setup-of-postgresql" title="Permalink to this headline"></a></h3>
<p>First, install the posgresql server. Version <code class="docutils literal notranslate"><span class="pre">9.6</span></code> is tested with Evennia. Packages are readily
available for all distributions. You need to also get the <code class="docutils literal notranslate"><span class="pre">psql</span></code> client (this is called <code class="docutils literal notranslate"><span class="pre">postgresql-</span> <span class="pre">client</span></code> on debian-derived systems). Windows/Mac users can <a class="reference external" href="https://www.postgresql.org/download/">find what they need on the postgresql
download page</a>. You should be setting up a password for your
database-superuser (always called <code class="docutils literal notranslate"><span class="pre">postgres</span></code>) when you install.</p>
<p>For interaction with Evennia you need to also install <code class="docutils literal notranslate"><span class="pre">psycopg2</span></code> to your Evennia install (<code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">psycopg2-binary</span></code> in your virtualenv). This acts as the python bridge to the database server.</p>
<p>First, install the posgresql server. Version <code class="docutils literal notranslate"><span class="pre">9.6</span></code> is tested with Evennia. Packages are readily available for all distributions. You need to also get the <code class="docutils literal notranslate"><span class="pre">psql</span></code> client (this is called <code class="docutils literal notranslate"><span class="pre">postgresql-</span> <span class="pre">client</span></code> on debian-derived systems). Windows/Mac users can <a class="reference external" href="https://www.postgresql.org/download/">find what they need on the postgresql download page</a>. You should be setting up a password for your database-superuser (always called <code class="docutils literal notranslate"><span class="pre">postgres</span></code>) when you install.</p>
<p>For interaction with Evennia you need to also install <code class="docutils literal notranslate"><span class="pre">psycopg2</span></code> to your Evennia install
(<code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">psycopg2-binary</span></code> in your virtualenv). This acts as the python bridge to the database server.</p>
<p>Next, start the postgres client:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> psql -U postgres --password
</pre></div>
@ -209,12 +202,7 @@ have to since the resulting command, and your password, will be logged in the sh
</pre></div>
</div>
<p><a class="reference external" href="https://gist.github.com/Kartones/dd3ff5ec5ea238d4c546">Here</a> is a cheat-sheet for psql commands.</p>
<p>We create a database user ‘evennia’ and a new database named <code class="docutils literal notranslate"><span class="pre">evennia</span></code> (you can call them whatever
you want though). We then grant the ‘evennia’ user full privileges to the new database so it can
read/write etc to it.
If you in the future wanted to completely wipe the database, an easy way to do is to log in as the
<code class="docutils literal notranslate"><span class="pre">postgres</span></code> superuser again, then do <code class="docutils literal notranslate"><span class="pre">DROP</span> <span class="pre">DATABASE</span> <span class="pre">evennia;</span></code>, then <code class="docutils literal notranslate"><span class="pre">CREATE</span></code> and <code class="docutils literal notranslate"><span class="pre">GRANT</span></code> steps above
again to recreate the database and grant privileges.</p>
<p>We create a database user ‘evennia’ and a new database named <code class="docutils literal notranslate"><span class="pre">evennia</span></code> (you can call them whatever you want though). We then grant the ‘evennia’ user full privileges to the new database so it can read/write etc to it. If you in the future wanted to completely wipe the database, an easy way to do is to log in as the <code class="docutils literal notranslate"><span class="pre">postgres</span></code> superuser again, then do <code class="docutils literal notranslate"><span class="pre">DROP</span> <span class="pre">DATABASE</span> <span class="pre">evennia;</span></code>, then <code class="docutils literal notranslate"><span class="pre">CREATE</span></code> and <code class="docutils literal notranslate"><span class="pre">GRANT</span></code> steps above again to recreate the database and grant privileges.</p>
</section>
<section id="evennia-postgresql-configuration">
<h3>Evennia PostgreSQL configuration<a class="headerlink" href="#evennia-postgresql-configuration" title="Permalink to this headline"></a></h3>
@ -237,8 +225,7 @@ again to recreate the database and grant privileges.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia migrate
</pre></div>
</div>
<p>to populate your database. Should you ever want to inspect the database directly you can from now on
also use</p>
<p>to populate your database. Should you ever want to inspect the database directly you can from now on also use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia dbshell
</pre></div>
</div>
@ -246,35 +233,27 @@ also use</p>
<p>With the database setup you should now be able to start start Evennia normally with your new
database.</p>
</section>
<section id="resetting-postgresql">
<h3>Resetting PostgreSQL<a class="headerlink" href="#resetting-postgresql" title="Permalink to this headline"></a></h3>
<p>If you want to reset your PostgreSQL datbase, see <a class="reference internal" href="Updating-Evennia.html#postgresql"><span class="std std-doc">here</span></a></p>
</section>
<section id="advanced-postgresql-usage-remote-server">
<h3>Advanced Postgresql Usage (Remote Server)<a class="headerlink" href="#advanced-postgresql-usage-remote-server" title="Permalink to this headline"></a></h3>
<h3>Advanced PostgreSQL Usage (Remote Server)<a class="headerlink" href="#advanced-postgresql-usage-remote-server" title="Permalink to this headline"></a></h3>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The example below is for a server within a private network that is not open to
the Internet. Be sure to understand the details before making any changes to
an Internet-accessible server.</p>
</div>
<p>The above discussion is for hosting a local server. In certain configurations
it may make sense host the database on a server remote to the one Evennia is
running on. One example case is where code development may be done on multiple
machines by multiple users. In this configuration, a local data base (such as
SQLite3) is not feasible since all the machines and developers do not have
access to the file.</p>
<p>Choose a remote machine to host the database and PostgreSQl server. Follow the
instructions <a class="reference internal" href="#install-and-initial-setup-of-postgresql"><span class="std std-doc">above</span></a> on that server to set up the database.
Depending on distribution, PostgreSQL will only accept connections on the local
machine (localhost). In order to enable remote access, two files need to be
changed.</p>
<p>The above discussion is for hosting a local server. In certain configurations it may make sense host the database on a server remote to the one Evennia is running on. One example case is where code development may be done on multiple machines by multiple users. In this configuration, a local data base (such as SQLite3) is not feasible since all the machines and developers do not have access to the file.</p>
<p>Choose a remote machine to host the database and PostgreSQl server. Follow the instructions <a class="reference internal" href="#install-and-initial-setup-of-postgresql"><span class="std std-doc">above</span></a> on that server to set up the database. Depending on distribution, PostgreSQL will only accept connections on the local machine (localhost). In order to enable remote access, two files need to be changed.</p>
<p>First, determine which cluster is running your database. Use <code class="docutils literal notranslate"><span class="pre">pg_lscluster</span></code>:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ pg_lsclusters
Ver Cluster Port Status Owner Data directory Log file
<span class="m">12</span> main <span class="m">5432</span> online postgres /var/lib/postgresql/12/main /var/log/postgresql/postgresql-12-main.log
</pre></div>
</div>
<p>Next, edit the database’s <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code>. This is found on Ubuntu systems
in <code class="docutils literal notranslate"><span class="pre">/etc/postgresql/&lt;ver&gt;/&lt;cluster&gt;</span></code>, where <code class="docutils literal notranslate"><span class="pre">&lt;ver&gt;</span></code> and <code class="docutils literal notranslate"><span class="pre">&lt;cluster&gt;</span></code> are
what are reported in the <code class="docutils literal notranslate"><span class="pre">pg_lscluster</span></code> output. So, for the above example,
the file is <code class="docutils literal notranslate"><span class="pre">/etc/postgresql/12/main/postgresql.conf</span></code>.</p>
<p>Next, edit the database’s <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code>. This is found on Ubuntu systems in <code class="docutils literal notranslate"><span class="pre">/etc/postgresql/&lt;ver&gt;/&lt;cluster&gt;</span></code>, where <code class="docutils literal notranslate"><span class="pre">&lt;ver&gt;</span></code> and <code class="docutils literal notranslate"><span class="pre">&lt;cluster&gt;</span></code> are what are reported in the <code class="docutils literal notranslate"><span class="pre">pg_lscluster</span></code> output. So, for the above example, the file is <code class="docutils literal notranslate"><span class="pre">/etc/postgresql/12/main/postgresql.conf</span></code>.</p>
<p>In this file, look for the line with <code class="docutils literal notranslate"><span class="pre">listen_addresses</span></code>. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">listen_address</span> <span class="o">=</span> <span class="s1">&#39;localhost&#39;</span> <span class="c1"># What IP address(es) to listen on;</span>
<span class="c1"># comma-separated list of addresses;</span>
@ -297,8 +276,7 @@ appropriately to limit access to this port as necessary. (You may also list
explicit addresses and subnets to listen. See the postgresql documentation
for more details.)</p>
</div>
<p>Finally, modify the <code class="docutils literal notranslate"><span class="pre">pg_hba.conf</span></code> (in the same directory as <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code>).
Look for a line with:</p>
<p>Finally, modify the <code class="docutils literal notranslate"><span class="pre">pg_hba.conf</span></code> (in the same directory as <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code>). Look for a line with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># IPv4 local connections:</span>
<span class="n">host</span> <span class="nb">all</span> <span class="nb">all</span> <span class="mf">127.0.0.1</span><span class="o">/</span><span class="mi">32</span> <span class="n">md5</span>
</pre></div>
@ -316,28 +294,17 @@ the PosgreSQL documentation on how to limit this.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ pg_ctlcluster <span class="m">12</span> main restart
</pre></div>
</div>
<p>Finally, update the database settings in your Evennia secret_settings.py (as
described <a class="reference internal" href="#evennia-postgresql-configuration"><span class="std std-doc">above</span></a> modifying <code class="docutils literal notranslate"><span class="pre">SERVER</span></code> and
<code class="docutils literal notranslate"><span class="pre">PORT</span></code> to match your server.</p>
<p>Now your Evennia installation should be able to connect and talk with a remote
server.</p>
<p>Finally, update the database settings in your Evennia secret_settings.py (as described <a class="reference internal" href="#evennia-postgresql-configuration"><span class="std std-doc">above</span></a> modifying <code class="docutils literal notranslate"><span class="pre">SERVER</span></code> and <code class="docutils literal notranslate"><span class="pre">PORT</span></code> to match your server.</p>
<p>Now your Evennia installation should be able to connect and talk with a remote server.</p>
</section>
</section>
<section id="mysql-mariadb">
<h2>MySQL / MariaDB<a class="headerlink" href="#mysql-mariadb" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://www.mysql.com/">MySQL</a> is a commonly used proprietary database system, on par with
PostgreSQL. There is an open-source alternative called <a class="reference external" href="https://mariadb.org/">MariaDB</a> that mimics
all functionality and command syntax of the former. So this section covers both.</p>
<p><a class="reference external" href="https://www.mysql.com/">MySQL</a> is a commonly used proprietary database system, on par with PostgreSQL. There is an open-source alternative called <a class="reference external" href="https://mariadb.org/">MariaDB</a> that mimics all functionality and command syntax of the former. So this section covers both.</p>
<section id="installing-and-initial-setup-of-mysql-mariadb">
<h3>Installing and initial setup of MySQL/MariaDB<a class="headerlink" href="#installing-and-initial-setup-of-mysql-mariadb" title="Permalink to this headline"></a></h3>
<p>First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the
<code class="docutils literal notranslate"><span class="pre">mysql-server</span></code> or <code class="docutils literal notranslate"><span class="pre">mariadb-server</span></code> packages for their respective distributions. Windows/Mac users
will find what they need from the <a class="reference external" href="https://www.mysql.com/downloads/">MySQL downloads</a> or <a class="reference external" href="https://mariadb.org/download/">MariaDB
downloads</a> pages. You also need the respective database clients
(<code class="docutils literal notranslate"><span class="pre">mysql</span></code>, <code class="docutils literal notranslate"><span class="pre">mariadb-client</span></code>), so you can setup the database itself. When you install the server you
should usually be asked to set up the database root user and password.</p>
<p>You will finally also need a Python interface to allow Evennia to talk to the database. Django
recommends the <code class="docutils literal notranslate"><span class="pre">mysqlclient</span></code> one. Install this into the evennia virtualenv with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">mysqlclient</span></code>.</p>
<p>First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the <code class="docutils literal notranslate"><span class="pre">mysql-server</span></code> or <code class="docutils literal notranslate"><span class="pre">mariadb-server</span></code> packages for their respective distributions. Windows/Mac users will find what they need from the <a class="reference external" href="https://www.mysql.com/downloads/">MySQL downloads</a> or <a class="reference external" href="https://mariadb.org/download/">MariaDB downloads</a> pages. You also need the respective database clients (<code class="docutils literal notranslate"><span class="pre">mysql</span></code>, <code class="docutils literal notranslate"><span class="pre">mariadb-client</span></code>), so you can setup the database itself. When you install the server you should usually be asked to set up the database root user and password.</p>
<p>You will finally also need a Python interface to allow Evennia to talk to the database. Django recommends the <code class="docutils literal notranslate"><span class="pre">mysqlclient</span></code> one. Install this into the evennia virtualenv with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">mysqlclient</span></code>.</p>
<p>Start the database client (this is named the same for both mysql and mariadb):</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mysql -u root -p
</pre></div>
@ -355,29 +322,16 @@ server).</p>
</pre></div>
</div>
<p><a class="reference external" href="https://gist.github.com/hofmannsven/9164408">Here</a> is a mysql command cheat sheet.</p>
<p>Above we created a new local user and database (we called both ‘evennia’ here, you can name them
what you prefer). We set the character set to <code class="docutils literal notranslate"><span class="pre">utf8</span></code> to avoid an issue with prefix character length
that can pop up on some installs otherwise. Next we grant the ‘evennia’ user all privileges on the
<code class="docutils literal notranslate"><span class="pre">evennia</span></code> database and make sure the privileges are applied. Exiting the client brings us back to
the normal terminal/console.</p>
<p>Above we created a new local user and database (we called both ‘evennia’ here, you can name them what you prefer). We set the character set to <code class="docutils literal notranslate"><span class="pre">utf8</span></code> to avoid an issue with prefix character length that can pop up on some installs otherwise. Next we grant the ‘evennia’ user all privileges on the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> database and make sure the privileges are applied. Exiting the client brings us back to the normal terminal/console.</p>
<blockquote>
<div><p>Note: If you are not using MySQL for anything else you might consider granting the ‘evennia’ user
full privileges with <code class="docutils literal notranslate"><span class="pre">GRANT</span> <span class="pre">ALL</span> <span class="pre">PRIVILEGES</span> <span class="pre">ON</span> <span class="pre">*.*</span> <span class="pre">TO</span> <span class="pre">'evennia'&#64;'localhost';</span></code>. If you do, it means
you can use <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">dbshell</span></code> later to connect to mysql, drop your database and re-create it as a
way of easy reset. Without this extra privilege you will be able to drop the database but not re-
create it without first switching to the database-root user.</p>
<div><p>If you are not using MySQL for anything else you might consider granting the ‘evennia’ user full privileges with <code class="docutils literal notranslate"><span class="pre">GRANT</span> <span class="pre">ALL</span> <span class="pre">PRIVILEGES</span> <span class="pre">ON</span> <span class="pre">*.*</span> <span class="pre">TO</span> <span class="pre">'evennia'&#64;'localhost';</span></code>. If you do, it means you can use <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">dbshell</span></code> later to connect to mysql, drop your database and re-create it as a way of easy reset. Without this extra privilege you will be able to drop the database but not re create it without first switching to the database-root user.</p>
</div></blockquote>
</section>
</section>
<section id="add-mysql-configuration-to-evennia">
<h2>Add MySQL configuration to Evennia<a class="headerlink" href="#add-mysql-configuration-to-evennia" title="Permalink to this headline"></a></h2>
<p>To tell Evennia to use your new database you need to edit <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code> (or
<code class="docutils literal notranslate"><span class="pre">secret_settings.py</span></code> if you don’t want your db info passed around on git repositories).</p>
<section id="add-mysql-mariadb-configuration-to-evennia">
<h3>Add MySQL/MariaDB configuration to Evennia<a class="headerlink" href="#add-mysql-mariadb-configuration-to-evennia" title="Permalink to this headline"></a></h3>
<p>To tell Evennia to use your new database you need to edit <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code> (or <code class="docutils literal notranslate"><span class="pre">secret_settings.py</span></code> if you don’t want your db info passed around on git repositories).</p>
<blockquote>
<div><p>Note: The Django documentation suggests using an external <code class="docutils literal notranslate"><span class="pre">db.cnf</span></code> or other external conf-
formatted file. Evennia users have however found that this leads to problems (see e.g. <a class="reference external" href="https://git.io/vQdiN">issue
#1184</a>). To avoid trouble we recommend you simply put the configuration in
your settings as below.</p>
<div><p>The Django documentation suggests using an external <code class="docutils literal notranslate"><span class="pre">db.cnf</span></code> or other external conf- formatted file. Evennia users have however found that this leads to problems (see e.g. <a class="reference external" href="https://git.io/vQdiN">issue #1184</a>). To avoid trouble we recommend you simply put the configuration in your settings as below.</p>
</div></blockquote>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="c1">#</span>
<span class="c1"># MySQL Database Configuration</span>
@ -394,24 +348,26 @@ your settings as below.</p>
<span class="p">}</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">mysql</span></code> backend is used by <code class="docutils literal notranslate"><span class="pre">MariaDB</span></code> as well.</p>
<p>Change this to fit your database setup. Next, run:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia migrate
</pre></div>
</div>
<p>to populate your database. Should you ever want to inspect the database directly you can from now on
also use</p>
<p>to populate your database. Should you ever want to inspect the database directly you can from now on also use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia dbshell
</pre></div>
</div>
<p>as a shortcut to get into the postgres command line for the right database and user.</p>
<p>With the database setup you should now be able to start start Evennia normally with your new
database.</p>
<p>With the database setup you should now be able to start start Evennia normally with your new database.</p>
</section>
<section id="others">
<h2>Others<a class="headerlink" href="#others" title="Permalink to this headline"></a></h2>
<p>No testing has been performed with Oracle, but it is also supported through Django. There are
community maintained drivers for <a class="reference external" href="https://code.google.com/p/django-mssql/">MS SQL</a> and possibly a few
others. If you try other databases out, consider expanding this page with instructions.</p>
<section id="resetting-mysql-mariadb">
<h3>Resetting MySQL/MariaDB<a class="headerlink" href="#resetting-mysql-mariadb" title="Permalink to this headline"></a></h3>
<p>If you want to reset your MySQL/MariaDB datbase, see <span class="xref myst">here</span>.</p>
</section>
</section>
<section id="other-databases">
<h2>Other databases<a class="headerlink" href="#other-databases" title="Permalink to this headline"></a></h2>
<p>No testing has been performed with Oracle, but it is also supported through Django. There are community maintained drivers for <a class="reference external" href="https://code.google.com/p/django-mssql/">MS SQL</a> and possibly a few others. If you try other databases out, consider contributing to this page with instructions.</p>
</section>
</section>

10
docs/1.0-dev/Setup/Installation-Non-Interactive.html
View file

@ -17,7 +17,7 @@
<link rel="shortcut 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="Start Stop Reload" href="Start-Stop-Reload.html" />
<link rel="next" title="Changing Game Settings" href="Settings.html" />
<link rel="prev" title="Upgrading an existing installation" href="Installation-Upgrade.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,7 +30,7 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Start-Stop-Reload.html" title="Start Stop Reload"
<a href="Settings.html" title="Changing Game Settings"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Installation-Upgrade.html" title="Upgrading an existing installation"
@ -64,8 +64,8 @@
<p class="topless"><a href="Installation-Upgrade.html"
title="previous chapter">Upgrading an existing installation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Start-Stop-Reload.html"
title="next chapter">Start Stop Reload</a></p>
<p class="topless"><a href="Settings.html"
title="next chapter">Changing Game Settings</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -130,7 +130,7 @@ build script:</p>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Start-Stop-Reload.html" title="Start Stop Reload"
<a href="Settings.html" title="Changing Game Settings"
>next</a> |</li>
<li class="right" >
<a href="Installation-Upgrade.html" title="Upgrading an existing installation"

8
docs/1.0-dev/Setup/Installation.html
View file

@ -118,6 +118,8 @@
<p class="admonition-title">Important</p>
<p>If you are converting an existing game from a previous Evennia version, <a class="reference internal" href="Installation-Upgrade.html"><span class="doc std std-doc">see here</span></a>.</p>
</div>
<p>The fastest way to install Evennia is to use the <code class="docutils literal notranslate"><span class="pre">pip</span></code> installer that comes with Python (read on).
You can also <a class="reference internal" href="Installation-Git.html"><span class="doc std std-doc">clone Evennia from github</span></a> or use <a class="reference internal" href="Installation-Docker.html"><span class="doc std std-doc">docker</span></a>. Some users have also experimented with <a class="reference internal" href="Installation-Android.html"><span class="doc std std-doc">installing Evennia on Android</span></a>.</p>
<section id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline"></a></h2>
<aside class="sidebar">
@ -125,7 +127,7 @@
<p>Installing Evennia doesn’t make anything visible online. Apart from installation and updating, you can develop your game without any internet connection if you want to.</p>
</aside>
<ul class="simple">
<li><p>Evennia requires <a class="reference external" href="https://www.python.org/downloads/">Python</a> 3.9, 3.10 or 3.11 (recommended)</p>
<li><p>Evennia requires <a class="reference external" href="https://www.python.org/downloads/">Python</a> 3.9, 3.10 or 3.11 (recommended). Any OS that supports Python should work.</p>
<ul>
<li><p>Windows: In the installer, make sure you select <code class="docutils literal notranslate"><span class="pre">add</span> <span class="pre">python</span> <span class="pre">to</span> <span class="pre">path</span></code>. If you have multiple versions of Python installed, use <code class="docutils literal notranslate"><span class="pre">py</span></code> command instead of <code class="docutils literal notranslate"><span class="pre">python</span></code> to have Windows automatically use the latest.</p></li>
</ul>
@ -137,8 +139,6 @@
</section>
<section id="install-with-pip">
<h2>Install with <code class="docutils literal notranslate"><span class="pre">pip</span></code><a class="headerlink" href="#install-with-pip" title="Permalink to this headline"></a></h2>
<p>The fastest way to install Evennia is to use the <code class="docutils literal notranslate"><span class="pre">pip</span></code> installer that comes with Python.
You can also <a class="reference internal" href="Installation-Git.html"><span class="doc std std-doc">clone Evennia from github</span></a> or use <a class="reference internal" href="Installation-Docker.html"><span class="doc std std-doc">docker</span></a>. Some users have also experimented with <a class="reference internal" href="Installation-Android.html"><span class="doc std std-doc">installing Evennia on Android</span></a>.</p>
<p>Evennia is managed from the terminal (console/Command Prompt on Windows). Once you have Python, you install Evennia with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip install evennia
</pre></div>
@ -204,7 +204,7 @@ evennia migrate
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia stop
</pre></div>
</div>
<p>See <a class="reference internal" href="Start-Stop-Reload.html"><span class="doc std std-doc">Server start-stop-reload</span></a> page for more details.</p>
<p>See <a class="reference internal" href="Running-Evennia.html"><span class="doc std std-doc">Server start-stop-reload</span></a> page for more details.</p>
</section>
<section id="see-server-logs">
<h2>See server logs<a class="headerlink" href="#see-server-logs" title="Permalink to this headline"></a></h2>

26
docs/1.0-dev/Setup/Start-Stop-Reload.html → docs/1.0-dev/Setup/Running-Evennia.html
View file

@ -17,8 +17,8 @@
<link rel="shortcut 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="Changing Game Settings" href="Settings.html" />
<link rel="prev" title="Non-interactive setup" href="Installation-Non-Interactive.html" />
<link rel="next" title="Updating Evennia" href="Updating-Evennia.html" />
<link rel="prev" title="Evennia Introduction" href="../Evennia-Introduction.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -30,13 +30,12 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Settings.html" title="Changing Game Settings"
<a href="Updating-Evennia.html" title="Updating Evennia"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Installation-Non-Interactive.html" title="Non-interactive setup"
<a href="../Evennia-Introduction.html" title="Evennia Introduction"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Start Stop Reload</a></li>
</ul>
<div class="develop">develop branch</div>
@ -81,15 +80,15 @@
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Installation-Non-Interactive.html"
title="previous chapter">Non-interactive setup</a></p>
<p class="topless"><a href="../Evennia-Introduction.html"
title="previous chapter">Evennia Introduction</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Settings.html"
title="next chapter">Changing Game Settings</a></p>
<p class="topless"><a href="Updating-Evennia.html"
title="next chapter">Updating Evennia</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Start-Stop-Reload.md.txt"
<li><a href="../_sources/Setup/Running-Evennia.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
@ -105,7 +104,7 @@
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Start-Stop-Reload.html">1.0-dev (develop branch)</a></li>
<li><a href="Running-Evennia.html">1.0-dev (develop branch)</a></li>
<ul>
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
@ -295,13 +294,12 @@ In-game you should now get the message that the Server has successfully restarte
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Settings.html" title="Changing Game Settings"
<a href="Updating-Evennia.html" title="Updating Evennia"
>next</a> |</li>
<li class="right" >
<a href="Installation-Non-Interactive.html" title="Non-interactive setup"
<a href="../Evennia-Introduction.html" title="Evennia Introduction"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Start Stop Reload</a></li>
</ul>
<div class="develop">develop branch</div>

10
docs/1.0-dev/Setup/Settings.html
View file

@ -18,7 +18,7 @@
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Evennia Default settings file" href="Settings-Default.html" />
<link rel="prev" title="Start Stop Reload" href="Start-Stop-Reload.html" />
<link rel="prev" title="Non-interactive setup" href="Installation-Non-Interactive.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -33,7 +33,7 @@
<a href="Settings-Default.html" title="Evennia Default settings file"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Start-Stop-Reload.html" title="Start Stop Reload"
<a href="Installation-Non-Interactive.html" title="Non-interactive setup"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
@ -70,8 +70,8 @@
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Start-Stop-Reload.html"
title="previous chapter">Start Stop Reload</a></p>
<p class="topless"><a href="Installation-Non-Interactive.html"
title="previous chapter">Non-interactive setup</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Settings-Default.html"
title="next chapter">Evennia Default settings file</a></p>
@ -206,7 +206,7 @@ services to the Server instead. More info can be found
<a href="Settings-Default.html" title="Evennia Default settings file"
>next</a> |</li>
<li class="right" >
<a href="Start-Stop-Reload.html" title="Start Stop Reload"
<a href="Installation-Non-Interactive.html" title="Non-interactive setup"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>

50
docs/1.0-dev/Setup/Setup-Overview.html
View file

@ -18,7 +18,7 @@
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Installation" href="Installation.html" />
<link rel="prev" title="Evennia Introduction" href="../Evennia-Introduction.html" />
<link rel="prev" title="Updating Evennia" href="Updating-Evennia.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -33,7 +33,7 @@
<a href="Installation.html" title="Installation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../Evennia-Introduction.html" title="Evennia Introduction"
<a href="Updating-Evennia.html" title="Updating Evennia"
accesskey="P">previous</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="">Server Setup and Life</a></li>
@ -64,14 +64,14 @@
<li><a class="reference internal" href="#">Server Setup and Life</a><ul>
<li><a class="reference internal" href="#installation-and-running">Installation and running</a></li>
<li><a class="reference internal" href="#configuration">Configuration</a></li>
<li><a class="reference internal" href="#going-public">Going public</a></li>
<li><a class="reference internal" href="#going-online">Going Online</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../Evennia-Introduction.html"
title="previous chapter">Evennia Introduction</a></p>
<p class="topless"><a href="Updating-Evennia.html"
title="previous chapter">Updating Evennia</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Installation.html"
title="next chapter">Installation</a></p>
@ -162,17 +162,24 @@
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Installation-Non-Interactive.html">Non-interactive setup</a></li>
<li class="toctree-l1"><a class="reference internal" href="Start-Stop-Reload.html">Start Stop Reload</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#starting-evennia">Starting Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#reloading">Reloading</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#stopping">Stopping</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#foreground-mode">Foreground mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#resetting">Resetting</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#rebooting">Rebooting</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#status-and-info">Status and info</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#killing-linux-mac-only">Killing (Linux/Mac only)</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#django-options">Django options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#advanced-handling-of-evennia-processes">Advanced handling of Evennia processes</a></li>
<li class="toctree-l1"><a class="reference internal" href="Running-Evennia.html">Start Stop Reload</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Running-Evennia.html#starting-evennia">Starting Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Running-Evennia.html#reloading">Reloading</a></li>
<li class="toctree-l2"><a class="reference internal" href="Running-Evennia.html#stopping">Stopping</a></li>
<li class="toctree-l2"><a class="reference internal" href="Running-Evennia.html#foreground-mode">Foreground mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="Running-Evennia.html#resetting">Resetting</a></li>
<li class="toctree-l2"><a class="reference internal" href="Running-Evennia.html#rebooting">Rebooting</a></li>
<li class="toctree-l2"><a class="reference internal" href="Running-Evennia.html#status-and-info">Status and info</a></li>
<li class="toctree-l2"><a class="reference internal" href="Running-Evennia.html#killing-linux-mac-only">Killing (Linux/Mac only)</a></li>
<li class="toctree-l2"><a class="reference internal" href="Running-Evennia.html#django-options">Django options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Running-Evennia.html#advanced-handling-of-evennia-processes">Advanced handling of Evennia processes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Updating-Evennia.html">Updating Evennia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Updating-Evennia.html#if-you-installed-with-pip">If you installed with <code class="docutils literal notranslate"><span class="pre">pip</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Evennia.html#if-you-installed-with-git">If you installed with <code class="docutils literal notranslate"><span class="pre">git</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Evennia.html#if-you-installed-with-docker">If you installed with <code class="docutils literal notranslate"><span class="pre">docker</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Evennia.html#resetting-your-database">Resetting your database</a></li>
</ul>
</li>
</ul>
@ -189,11 +196,10 @@
</li>
<li class="toctree-l1"><a class="reference internal" href="Settings-Default.html">Evennia Default settings file</a></li>
<li class="toctree-l1"><a class="reference internal" href="Choosing-a-Database.html">Choosing a database</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Choosing-a-Database.html#sqlite3">SQLite3</a></li>
<li class="toctree-l2"><a class="reference internal" href="Choosing-a-Database.html#sqlite3-default">SQLite3 (default)</a></li>
<li class="toctree-l2"><a class="reference internal" href="Choosing-a-Database.html#postgresql">PostgreSQL</a></li>
<li class="toctree-l2"><a class="reference internal" href="Choosing-a-Database.html#mysql-mariadb">MySQL / MariaDB</a></li>
<li class="toctree-l2"><a class="reference internal" href="Choosing-a-Database.html#add-mysql-configuration-to-evennia">Add MySQL configuration to Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Choosing-a-Database.html#others">Others</a></li>
<li class="toctree-l2"><a class="reference internal" href="Choosing-a-Database.html#other-databases">Other databases</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Channels-to-IRC.html">Connect Evennia channels to IRC</a><ul>
@ -219,8 +225,8 @@
</ul>
</div>
</section>
<section id="going-public">
<h2>Going public<a class="headerlink" href="#going-public" title="Permalink to this headline"></a></h2>
<section id="going-online">
<h2>Going Online<a class="headerlink" href="#going-online" title="Permalink to this headline"></a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Evennia-Game-Index.html">Evennia Game Index</a><ul>
@ -287,7 +293,7 @@
<a href="Installation.html" title="Installation"
>next</a> |</li>
<li class="right" >
<a href="../Evennia-Introduction.html" title="Evennia Introduction"
<a href="Updating-Evennia.html" title="Updating Evennia"
>previous</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="">Server Setup and Life</a></li>

247
docs/1.0-dev/Setup/Updating-Evennia.html Normal file
View file

@ -0,0 +1,247 @@
<!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>Updating Evennia &#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" />
<link rel="next" title="Server Setup and Life" href="Setup-Overview.html" />
<link rel="prev" title="Start Stop Reload" href="Running-Evennia.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="right" >
<a href="Setup-Overview.html" title="Server Setup and Life"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Running-Evennia.html" title="Start Stop Reload"
accesskey="P">previous</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="">Updating Evennia</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Updating Evennia</a><ul>
<li><a class="reference internal" href="#if-you-installed-with-pip">If you installed with <code class="docutils literal notranslate"><span class="pre">pip</span></code></a></li>
<li><a class="reference internal" href="#if-you-installed-with-git">If you installed with <code class="docutils literal notranslate"><span class="pre">git</span></code></a></li>
<li><a class="reference internal" href="#if-you-installed-with-docker">If you installed with <code class="docutils literal notranslate"><span class="pre">docker</span></code></a></li>
<li><a class="reference internal" href="#resetting-your-database">Resetting your database</a><ul>
<li><a class="reference internal" href="#sqlite3-default">SQLite3 (default)</a></li>
<li><a class="reference internal" href="#postgresql">PostgreSQL</a></li>
<li><a class="reference internal" href="#mysql-mariadb">MySQL/MariaDB</a></li>
<li><a class="reference internal" href="#what-are-database-migrations">What are database migrations?</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Running-Evennia.html"
title="previous chapter">Start Stop Reload</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Setup-Overview.html"
title="next chapter">Server Setup and Life</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Updating-Evennia.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="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>Versions</h3>
<ul>
<li><a href="Updating-Evennia.html">1.0-dev (develop branch)</a></li>
<ul>
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="updating-evennia">
<h1>Updating Evennia<a class="headerlink" href="#updating-evennia" title="Permalink to this headline"></a></h1>
<p>When Evennia is updated to a new version you will usually see it announced in the <a class="reference external" href="https://github.com/evennia/evennia/blob/master/discussions">Discussion forum</a> and in the <a class="reference external" href="https://www.evennia.com/devblog/index.html">dev blog</a>. You can also see the changes on <a class="reference external" href="https://github.com/evennia/evennia/blob/master/">github</a> or through one of our other <a class="reference internal" href="../Links.html"><span class="doc std std-doc">linked pages</span></a>.</p>
<section id="if-you-installed-with-pip">
<h2>If you installed with <code class="docutils literal notranslate"><span class="pre">pip</span></code><a class="headerlink" href="#if-you-installed-with-pip" title="Permalink to this headline"></a></h2>
<p>If you followed the <a class="reference internal" href="Installation.html"><span class="doc std std-doc">normal install instructions</span></a>, here’s what you do to upgrade:</p>
<ol class="simple">
<li><p>Read the <a class="reference internal" href="../Coding/Changelog.html"><span class="doc std std-doc">changelog</span></a> to see what changed and if it means you need to make any changes to your game code.</p></li>
<li><p>If you use a <span class="xref myst">virtualenv</span>, make sure it’s active.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> to your game dir (e.g. <code class="docutils literal notranslate"><span class="pre">mygame</span></code>)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">stop</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">--upgrade</span> <span class="pre">evennia</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> tor your game dir</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> (<em>ignore</em> any warnings about running <code class="docutils literal notranslate"><span class="pre">makemigrations</span></code>, it should <em>not</em> be done)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code></p></li>
</ol>
<p>If the upstream changes are large, you may also need to go into your gamedoor</p>
</section>
<section id="if-you-installed-with-git">
<h2>If you installed with <code class="docutils literal notranslate"><span class="pre">git</span></code><a class="headerlink" href="#if-you-installed-with-git" title="Permalink to this headline"></a></h2>
<p>This applies if you followed the <a class="reference internal" href="Installation-Git.html"><span class="doc std std-doc">git-install instructions</span></a>. Before Evennia 1.0, this was the only way to install Evennia.</p>
<p>At any time, development is either happening in the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch (latest stable) or <code class="docutils literal notranslate"><span class="pre">develop</span></code> (experimental). Which one is active and ‘latest’ at a given time depends - after a release, <code class="docutils literal notranslate"><span class="pre">master</span></code> will see most updates, close to a new release, <code class="docutils literal notranslate"><span class="pre">develop</span></code> will usually be the fastest changing.</p>
<ol class="simple">
<li><p>Read the <a class="reference internal" href="../Coding/Changelog.html"><span class="doc std std-doc">changelog</span></a> to see what changed and if it means you need to make any changes to your game code.</p></li>
<li><p>If you use a <span class="xref myst">virtualenv</span>, make sure it’s active.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> to your game dir (e.g. <code class="docutils literal notranslate"><span class="pre">mygame</span></code>)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">stop</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> to the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> repo folder you cloned during the git installation process.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">--upgrade</span> <span class="pre">-e</span> <span class="pre">.</span></code> (remember the <code class="docutils literal notranslate"><span class="pre">.</span></code> at the end!)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> back to your game dir</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> (<em>ignore</em> any warnings about running <code class="docutils literal notranslate"><span class="pre">makemigrations</span></code> , it should <em>not</em> be done)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code></p></li>
</ol>
</section>
<section id="if-you-installed-with-docker">
<h2>If you installed with <code class="docutils literal notranslate"><span class="pre">docker</span></code><a class="headerlink" href="#if-you-installed-with-docker" title="Permalink to this headline"></a></h2>
<p>If you followed the [docker installation instructions] you need to pull the latest docker image for the branch you want:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">pull</span> <span class="pre">evennia/evennia</span></code> (master branch)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">pull</span> <span class="pre">evennia/evennia:develop</span></code> (experimental <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch)</p></li>
</ul>
<p>Then restart your containers.</p>
</section>
<section id="resetting-your-database">
<h2>Resetting your database<a class="headerlink" href="#resetting-your-database" title="Permalink to this headline"></a></h2>
<p>Should you ever want to start over completely from scratch, there is no need to re-download Evennia. You just need to clear your database.</p>
<p>First:</p>
<ol class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> to your game dir (e.g. <code class="docutils literal notranslate"><span class="pre">mygame</span></code>)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">stop</span></code></p></li>
</ol>
<section id="sqlite3-default">
<h3>SQLite3 (default)<a class="headerlink" href="#sqlite3-default" title="Permalink to this headline"></a></h3>
<aside class="sidebar">
<p class="sidebar-title">Hint</p>
<p>Make a copy of the <code class="docutils literal notranslate"><span class="pre">evennia.db3</span></code> file once you created your superuser. When you want to reset (and as long as you haven’t had to run any new migrations), you can just stop evennia and copy that file back over <code class="docutils literal notranslate"><span class="pre">evennia.db3</span></code>. That way you don’t have to run the same migrations and create the superuser every time!</p>
</aside>
<ol class="simple">
<li><p>delete the file <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code></p></li>
</ol>
</section>
<section id="postgresql">
<h3>PostgreSQL<a class="headerlink" href="#postgresql" title="Permalink to this headline"></a></h3>
<ol>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">dbshell</span></code> (opens the psql client interface)</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">psql</span><span class="o">&gt;</span> <span class="n">DROP</span> <span class="n">DATABASE</span> <span class="n">evennia</span><span class="p">;</span>
<span class="n">psql</span><span class="o">&gt;</span> <span class="n">exit</span>
</pre></div>
</div>
</li>
<li><p>You should now follow the <a class="reference internal" href="Choosing-a-Database.html#postgresql"><span class="std std-doc">PostgreSQL install instructions</span></a> to create a new evennia database.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code></p></li>
</ol>
</section>
<section id="mysql-mariadb">
<h3>MySQL/MariaDB<a class="headerlink" href="#mysql-mariadb" title="Permalink to this headline"></a></h3>
<ol>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">dbshell</span></code> (opens the mysql client interface)</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mysql</span><span class="o">&gt;</span> <span class="n">DROP</span> <span class="n">DATABASE</span> <span class="n">evennia</span><span class="p">;</span>
<span class="n">mysql</span><span class="o">&gt;</span> <span class="n">exit</span>
</pre></div>
</div>
</li>
<li><p>You should now follow the <span class="xref myst">MySQL install instructions</span> to create a new evennia database.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code></p></li>
</ol>
</section>
<section id="what-are-database-migrations">
<h3>What are database migrations?<a class="headerlink" href="#what-are-database-migrations" title="Permalink to this headline"></a></h3>
<p>If and when an Evennia update modifies the database <em>schema</em> (that is, the under-the-hood details as to how data is stored in the database), you must update your existing database correspondingly to match the change. If you don’t, the updated Evennia will complain that it cannot read the database properly. Whereas schema changes should become more and more rare as Evennia matures, it may still happen from time to time.</p>
<p>One way one could handle this is to apply the changes manually to your database using the database’s command line. This often means adding/removing new tables or fields as well as possibly convert existing data to match what the new Evennia version expects. It should be quite obvious that this quickly becomes cumbersome and error-prone. If your database doesn’t contain anything critical yet it’s probably easiest to simply reset it and start over rather than to bother converting.</p>
<p>Enter <em>migrations</em>. Migrations keeps track of changes in the database schema and applies them automatically for you. Basically, whenever the schema changes we distribute small files called “migrations” with the source. Those tell the system exactly how to implement the change so you don’t have to do so manually. When a migration has been added we will tell you so on Evennia’s mailing lists and in commit messages - you then just run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> to be up-to-date again.</p>
</section>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Setup-Overview.html" title="Server Setup and Life"
>next</a> |</li>
<li class="right" >
<a href="Running-Evennia.html" title="Start Stop Reload"
>previous</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="">Updating Evennia</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2022, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>

BIN
docs/1.0-dev/_images/fork_button.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 3 KiB

149
docs/1.0-dev/_sources/Coding/Coding-FAQ.md.txt
View file

@ -4,27 +4,8 @@
the docs if you can rather than too lengthy explanations. Don't forget to check if an answer already
exists before answering - maybe you can clarify that answer rather than to make a new Q&A section.*
## Table of Contents
- [Removing default commands](./Coding-FAQ.md#removing-default-commands)
- [Preventing character from moving based on a condition](./Coding-FAQ.md#preventing-character-from-
moving-based-on-a-condition)
- [Reference initiating object in an EvMenu command](./Coding-FAQ.md#reference-initiating-object-in-an-
evmenu-command)
- [Adding color to default Evennia Channels](./Coding-FAQ.md#adding-color-to-default-evennia-channels)
- [Selectively turn off commands in a room](./Coding-FAQ.md#selectively-turn-off-commands-in-a-room)
- [Select Command based on a condition](./Coding-FAQ.md#select-command-based-on-a-condition)
- [Automatically updating code when reloading](./Coding-FAQ.md#automatically-updating-code-when-
reloading)
- [Changing all exit messages](./Coding-FAQ.md#changing-all-exit-messages)
- [Add parsing with the "to" delimiter](./Coding-FAQ.md#add-parsing-with-the-to-delimiter)
- [Store last used session IP address](./Coding-FAQ.md#store-last-used-session-ip-address)
- [Use wide characters with EvTable](./Coding-FAQ.md#non-latin-characters-in-evtable)
## Removing default commands
**Q:** How does one *remove* (not replace) e.g. the default `get` [Command](../Components/Commands.md) from the
Character [Command Set](../Components/Command-Sets.md)?
**Q:** How does one *remove* (not replace) e.g. the default `get` [Command](../Components/Commands.md) from the Character [Command Set](../Components/Command-Sets.md)?
**A:** Go to `mygame/commands/default_cmdsets.py`. Find the `CharacterCmdSet` class. It has one
method named `at_cmdset_creation`. At the end of that method, add the following line:
@ -70,32 +51,6 @@ class MyObjectCommand(Command):
Inside the menu you can now access the object through `caller.ndb._evmenu.stored_obj`.
## Adding color to default Evennia Channels
**Q:** How do I add colors to the names of Evennia channels?
**A:** The Channel typeclass' `channel_prefix` method decides what is shown at the beginning of a
channel send. Edit `mygame/typeclasses/channels.py` (and then `@reload`):
```python
# define our custom color names
CHANNEL_COLORS = {"public": "|015Public|n",
"newbie": "|550N|n|551e|n|552w|n|553b|n|554i|n|555e|n",
"staff": "|010S|n|020t|n|030a|n|040f|n|050f|n"}
# Add to the Channel class
# ...
def channel_prefix(self, msg, emit=False):
if self.key in COLORS:
p_str = CHANNEL_COLORS.get(self.key.lower())
else:
p_str = self.key.capitalize()
return f"[{p_str}] "
```
Additional hint: To make colors easier to change from one place you could instead put the
`CHANNEL_COLORS` dict in your settings file and import it as `from django.conf.settings import
CHANNEL_COLORS`.
## Selectively turn off commands in a room
**Q:** I want certain commands to turn off in a given room. They should still work normally for
staff.
@ -130,18 +85,16 @@ class BlockingRoom(Room):
# are NOT Builders or higher
self.locks.add("call:not perm(Builders)")
```
After `@reload`, make some `BlockingRooms` (or switch a room to it with `@typeclass`). Entering one
After `reload`, make some `BlockingRooms` (or switch a room to it with `@typeclass`). Entering one
will now replace the given commands for anyone that does not have the `Builders` or higher
permission. Note that the 'call' lock is special in that even the superuser will be affected by it
(otherwise superusers would always see other player's cmdsets and a game would be unplayable for
superusers).
(otherwise superusers would always see other player's cmdsets and a game would be unplayable for superusers).
## Select Command based on a condition
**Q:** I want a command to be available only based on a condition. For example I want the "werewolf"
command to only be available on a full moon, from midnight to three in-game time.
**A:** This is easiest accomplished by putting the "werewolf" command on the Character as normal,
but to [lock](../Components/Locks.md) it with the "cmd" type lock. Only if the "cmd" lock type is passed will the
**A:** This is easiest accomplished by putting the "werewolf" command on the Character as normal, but to [lock](../Components/Locks.md) it with the "cmd" type lock. Only if the "cmd" lock type is passed will the
command be available.
```python
@ -156,8 +109,7 @@ class CmdWerewolf(Command):
def func(self):
# ...
```
Add this to the [default cmdset as usual](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md). The `is_full_moon` [lock
function](../Components/Locks.md#lock-functions) does not yet exist. We must create that:
Add this to the [default cmdset as usual](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md). The `is_full_moon` [lock function](../Components/Locks.md#lock-functions) does not yet exist. We must create that:
```python
# in mygame/server/conf/lockfuncs.py
@ -169,17 +121,17 @@ def is_full_moon(accessing_obj, accessed_obj,
# return True or False
```
After a `@reload`, the `werewolf` command will be available only at the right time, that is when the
After a `reload`, the `werewolf` command will be available only at the right time, that is when the
`is_full_moon` lock function returns True.
## Automatically updating code when reloading
**Q:** I have a development server running Evennia. Can I have the server update its code-base when
I reload?
**A:** Having a development server that pulls updated code whenever you reload it can be really
useful if you have limited shell access to your server, or want to have it done automatically. If
you have your project in a configured Git environment, it's a matter of automatically calling `git
pull` when you reload. And that's pretty straightforward:
you have your project in a configured Git environment, it's a matter of automatically calling `git pull` when you reload. And that's pretty straightforward:
In `/server/conf/at_server_startstop.py`:
@ -196,45 +148,30 @@ def at_server_reload_stop():
process = subprocess.call(["git", "pull"], shell=False)
```
That's all. We call `subprocess` to execute a shell command (that code works on Windows and Linux,
assuming the current directory is your game directory, which is probably the case when you run
Evennia). `call` waits for the process to complete, because otherwise, Evennia would reload on
partially-modified code, which would be problematic.
That's all. We call `subprocess` to execute a shell command (that code works on Windows and Linux, assuming the current directory is your game directory, which is probably the case when you run Evennia). `call` waits for the process to complete, because otherwise, Evennia would reload on partially-modified code, which would be problematic.
Now, when you enter `@reload` on your development server, the game repository is updated from the
configured remote repository (Github, for instance). Your development cycle could resemble
something like:
Now, when you enter `reload` on your development server, the game repository is updated from the configured remote repository (Github, for instance). Your development cycle could resemble something like:
1. Coding on the local machine.
2. Testing modifications.
3. Committing once, twice or more (being sure the code is still working, unittests are pretty useful
here).
3. Committing once, twice or more (being sure the code is still working, unittests are pretty useful here).
4. When the time comes, login to the development server and run `@reload`.
The reloading might take one or two additional seconds, since Evennia will pull from your remote Git
repository. But it will reload on it and you will have your modifications ready, without needing
The reloading might take one or two additional seconds, since Evennia will pull from your remote Git repository. But it will reload on it and you will have your modifications ready, without needing
connecting to your server using SSH or something similar.
## Changing all exit messages
**Q:** How can I change the default exit messages to something like "XXX leaves east" or "XXX
arrives from the west"?
**A:** the default exit messages are stored in two hooks, namely `announce_move_from` and
`announce_move_to`, on the `Character` typeclass (if what you want to change is the message other
characters will see when a character exits).
**A:** the default exit messages are stored in two hooks, namely `announce_move_from` and `announce_move_to`, on the `Character` typeclass (if what you want to change is the message other characters will see when a character exits).
These two hooks provide some useful features to easily update the message to be displayed. They
take both the default message and mapping as argument. You can easily call the parent hook with
these information:
These two hooks provide some useful features to easily update the message to be displayed. They take both the default message and mapping as argument. You can easily call the parent hook with these information:
* The message represents the string of characters sent to characters in the room when a character
leaves.
* The mapping is a dictionary containing additional mappings (you will probably not need it for
simple customization).
* The message represents the string of characters sent to characters in the room when a character leaves.
* The mapping is a dictionary containing additional mappings (you will probably not need it for simple customization).
It is advisable to look in the [code of both
hooks](https://github.com/evennia/evennia/tree/master/evennia/objects/objects.py), and read the
hooks' documentation. The explanations on how to quickly update the message are shown below:
It is advisable to look in the [code of both hooks](evennia.objects.objects.DefaultCharacter), and read the hooks' documentation. The explanations on how to quickly update the message are shown below:
```python
# In typeclasses/characters.py
@ -295,18 +232,13 @@ class Character(DefaultCharacter):
super().announce_move_to(source_location, msg="{object} arrives from the {exit}.")
```
We override both hooks, but call the parent hook to display a different message. If you read the
provided docstrings, you will better understand why and how we use mappings (information between
braces). You can provide additional mappings as well, if you want to set a verb to move, for
instance, or other, extra information.
We override both hooks, but call the parent hook to display a different message. If you read the provided docstrings, you will better understand why and how we use mappings (information between braces). You can provide additional mappings as well, if you want to set a verb to move, for instance, or other, extra information.
## Add parsing with the "to" delimiter
**Q:** How do I change commands to undestand say `give obj to target` as well as the default `give
obj = target`?
**Q:** How do I change commands to undestand say `give obj to target` as well as the default `give obj = target`?
**A:** You can make change the default `MuxCommand` parent with your own class making a small change
in its `parse` method:
**A:** You can make change the default `MuxCommand` parent with your own class making a small change in its `parse` method:
```python
# in mygame/commands/command.py
@ -324,42 +256,9 @@ Next you change the parent of the default commands in settings:
COMMAND_DEFAULT_CLASS = "commands.command.MuxCommand"
```
Do a `@reload` and all default commands will now use your new tweaked parent class. A copy of the
Do a `reload` and all default commands will now use your new tweaked parent class. A copy of the
MuxCommand class is also found commented-out in the `mygame/commands/command.py` file.
## Store last used session IP address
**Q:** If a user has already logged out of an Evennia account, their IP is no longer visible to
staff that wants to ban-by-ip (instead of the user) with `@ban/ip`?
**A:** One approach is to write the IP from the last session onto the "account" account object.
`typeclasses/accounts.py`
```python
def at_post_login(self, session=None, **kwargs):
super().at_post_login(session=session, **kwargs)
self.db.lastsite = self.sessions.all()[-1].address
```
Adding timestamp for login time and appending to a list to keep the last N login IP addresses and
timestamps is possible, also. Additionally, if you don't want the list to grow beyond a
`do_not_exceed` length, conditionally pop a value after you've added it, if the length has grown too
long.
**NOTE:** You'll need to add `import time` to generate the login timestamp.
```python
def at_post_login(self, session=None, **kwargs):
super().at_post_login(session=session, **kwargs)
do_not_exceed = 24 # Keep the last two dozen entries
session = self.sessions.all()[-1] # Most recent session
if not self.db.lastsite:
self.db.lastsite = []
self.db.lastsite.insert(0, (session.address, int(time.time())))
if len(self.db.lastsite) > do_not_exceed:
self.db.lastsite.pop()
```
This only stores the data. You may want to interface the `@ban` command or make a menu-driven viewer
for staff to browse the list and display how long ago the login occurred.
## Non-latin characters in EvTable
**Q:** When using e.g. Chinese characters in EvTable, some lines appear to be too wide, for example
@ -370,8 +269,4 @@ for staff to browse the list and display how long ago the login occurred.
| | |
+~~~~~~+~~~~~~+
```
**A:** The reason for this is because certain non-latin characters are *visually* much wider than
their len() suggests. There is little Evennia can (reliably) do about this. If you are using such
characters, you need to make sure to use a suitable mono-spaced font where are width are equal. You
can set this in your web client and need to recommend it for telnet-client users. See [this
discussion](https://github.com/evennia/evennia/issues/1522) where some suitable fonts are suggested.
**A:** The reason for this is because certain non-latin characters are *visually* much wider than their len() suggests. There is little Evennia can (reliably) do about this. If you are using such characters, you need to make sure to use a suitable mono-spaced font where are width are equal. You can set this in your web client and need to recommend it for telnet-client users. See [this discussion](https://github.com/evennia/evennia/issues/1522) where some suitable fonts are suggested.

121
docs/1.0-dev/_sources/Coding/Coding-Introduction.md.txt
View file

@ -1,121 +0,0 @@
# Coding Introduction
Evennia allows for a lot of freedom when designing your game - but to code efficiently you still
need to adopt some best practices as well as find a good place to start to learn.
Here are some pointers to get you going.
## Start with the tutorial
It's highly recommended that you jump in on the [Starting Tutorial](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Overview.md). Even if
you only the beginning or some part of it, it covers much of the things needed to get started, including giving you are first introduction to Python.
## Explore Evennia interactively
As mentioned in the Starting tutorial, it's a good idea to use [ipython](https://ipython.org/) to explore things using a python shell:
# [open a new console/terminal]
cd mygame
evennia shell
This will open an Evennia-aware python shell (using ipython). From within this shell, try
import evennia
evennia.<TAB>
### Jupyter Notebook Support
You can also explore evennia interactively in a [Jupyter notebook](https://jupyter.readthedocs.io/en/latest/index.html#). This offers
an in-browser view of your code similar to Matlab or similar programs. There are
a few extra steps that must be taken in order for this to work:
# [open a new console/terminal]
# [activate your evennia virtualenv in this console/terminal]
cd evennia
pip install -r requirements_extra.txt # if not done already above
Next, `cd` to your game folder. _It's important that you are in the _root_ of this folder for the next command_:
evennia shell_plus --notebook &
The `&` at the end starts the process as a background process on Linux/Unix.
Skip it if your OS doesn't support this syntax. Your browser should now open
with the Jupyter interface. If not, open a browser to the link given on the
command line.
In the window, open the `new` menu in the top right and start a `Django Shell-Plus` notebook (or
open an existing one if you had one from before). In the first cell you must initialize
Evennia like so:
```python
import evennia
evennia._init()
```
_Note that the above initialization must be run every time a new new notebook/kernel is started or restarted._
After this you can import and access all of the Evennia system, same as with `evennia shell`.
### More exploration
You can complement your exploration by peeking at the sections of the much more detailed
[Evennia Component overview](../Components/Components-Overview.md). The [Tutorials](../Howtos/Howtos-Overview.md) section also contains a growing collection
of system- or implementation-specific help.
## Use a python syntax checker
Evennia works by importing your own modules and running them as part of the server. Whereas Evennia
should just gracefully tell you what errors it finds, it can nevertheless be a good idea for you to
check your code for simple syntax errors *before* you load it into the running server. There are
many python syntax checkers out there. A fast and easy one is
[pyflakes](https://pypi.python.org/pypi/pyflakes), a more verbose one is
[pylint](https://www.pylint.org/). You can also check so that your code looks up to snuff using
[pep8](https://pypi.python.org/pypi/pep8). Even with a syntax checker you will not be able to catch
every possible problem - some bugs or problems will only appear when you actually run the code. But
using such a checker can be a good start to weed out the simple problems.
## Plan before you code
Before you start coding away at your dream game, take a look at our [Game Planning](../Howtos/Beginner-Tutorial/Part2/Beginner-Tutorial-Game-Planning.md)
page. It might hopefully help you avoid some common pitfalls and time sinks.
## Code in your game folder, not in the evennia/ repository
As part of the Evennia setup you will create a game folder to host your game code. This is your
home. You should *never* need to modify anything in the `evennia` library (anything you download
from us, really). You import useful functionality from here and if you see code you like, copy&paste
it out into your game folder and edit it there.
If you find that Evennia doesn't support some functionality you need, make a Feature Request about it. Same goes for bugs. If you add features or fix bugs yourself, please consider [Contributing](../Contributing.md) your changes upstream!
## Learn to read tracebacks
Python is very good at reporting when and where things go wrong. A *traceback* shows everything you
need to know about crashing code. The text can be pretty long, but you usually are only interested
in the last bit, where it says what the error is and at which module and line number it happened -
armed with this info you can resolve most problems.
Evennia will usually not show the full traceback in-game though. Instead the server outputs errors
to the terminal/console from which you started Evennia in the first place. If you want more to show
in-game you can add `IN_GAME_ERRORS = True` to your settings file. This will echo most (but not all)
tracebacks both in-game as well as to the terminal/console. This is a potential security problem
though, so don't keep this active when your game goes into production.
> A common confusing error is finding that objects in-game are suddenly of the type `DefaultObject`
rather than your custom typeclass. This happens when you introduce a critical Syntax error to the
module holding your custom class. Since such a module is not valid Python, Evennia can't load it at
all. Instead of crashing, Evennia will then print the full traceback to the terminal/console and
temporarily fall back to the safe `DefaultObject` until you fix the problem and reload.
## Docs are here to help you
Some people find reading documentation extremely dull and shun it out of principle. That's your
call, but reading docs really *does* help you, promise! Evennia's documentation is pretty thorough
and knowing what is possible can often give you a lot of new cool game ideas. That said, if you
can't find the answer in the docs, don't be shy to ask questions! The [discussion
group](https://sites.google.com/site/evenniaserver/discussions) and the [irc
chat](https://webchat.freenode.net/?channels=evennia) are also there for you.
## The most important point
And finally, of course, have fun!

18
docs/1.0-dev/_sources/Coding/Coding-Overview.md.txt
View file

@ -3,29 +3,17 @@
This documentation aims to help you set up a sane development environment to
make your game, also if you never coded before. If you are an experienced coder, much of this will be familiar to you, but some things may still be useful.
## Setting up a workflow
See also the [Beginner Tutorial](../Howtos/Beginner-Tutorial/Beginner-Tutorial-Overview.md).
```{toctree}
:maxdepth: 2
Version-Control.md
Updating-Your-Game.md
```
## Coding away
```{toctree}
:maxdepth: 2
Coding-Introduction.md
Coding-FAQ.md
Debugging.md
Unit-Testing.md
Profiling.md
Evennia-Code-Style.md
Coding-FAQ.md
Quirks.md
```
@ -40,7 +28,7 @@ Changelog.md
## Third-party integrations
```{toctree}
:maxdepth: 2
:maxdepth: 1
Continuous-Integration.md
Setting-up-PyCharm.md

20
docs/1.0-dev/_sources/Coding/Continuous-Integration.md.txt
View file

@ -1,14 +1,8 @@
# Continuous Integration
# Continuous Integration (CI)
One of the advantages of Evennia over traditional MU* development systems is that Evennia can
integrate into enterprise-level integration environments and source control.
One of the advantages of Evennia over traditional MU* development systems is that Evennia can integrate into enterprise-level integration environments and source control.
## What is Continuous Integration (CI)?
[Continuous Integration (CI)](https://www.thoughtworks.com/continuous-integration) is a development
practice that requires developers to integrate code into a shared repository.
Each check-in is then verified by an automated build, allowing teams to detect problems early. This
can be set up to safely deploy data to a production server only after tests have passed, for example.
[Continuous Integration (CI)](https://www.thoughtworks.com/continuous-integration) is a development practice that requires developers to integrate code into a shared repository. Each check-in is then verified by an automated build, allowing teams to detect problems early. This can be set up to safely deploy data to a production server only after tests have passed, for example.
For Evennia, continuous integration allows an automated build process to:
@ -19,10 +13,9 @@ For Evennia, continuous integration allows an automated build process to:
* Publish those files to the server directory
* Reload the game.
## List of continuous integration tools
## List of CI Evennia tutorials
There are a lot of tools and services providing CI functionality. Here are a few that people have used
with Evennia:
There are a lot of tools and services providing CI functionality. Here are a few that people have used with Evennia:
```{toctree}
:maxdepth: 1
@ -32,5 +25,4 @@ Continuous-Integration-TeamCity.md
```
[This is an overview of other tools](https://www.atlassian.com/continuous-delivery/continuous-integration/tools)
(external link).
[This is an overview of other tools](https://www.atlassian.com/continuous-delivery/continuous-integration/tools) (external link).

86
docs/1.0-dev/_sources/Coding/Debugging.md.txt
View file

@ -1,12 +1,8 @@
# Debugging
Sometimes, an error is not trivial to resolve. A few simple `print` statements is not enough to find the cause of the issue. The traceback is not informative or even non-existing.
Sometimes, an error is not trivial to resolve. A few simple `print` statements is not enough to find
the cause of the issue. Running a *debugger* can then be very helpful and save a lot of time.
Debugging
means running Evennia under control of a special *debugger* program. This allows you to stop the
action at a given point, view the current state and step forward through the program to see how its
logic works.
Running a *debugger* can then be very helpful and save a lot of time. Debugging means running Evennia under control of a special *debugger* program. This allows you to stop the action at a given point, view the current state and step forward through the program to see how its logic works.
Evennia natively supports these debuggers:
@ -24,11 +20,8 @@ To run Evennia with the debugger, follow these steps:
```python
from evennia import set_trace;set_trace()
```
2. (Re-)start Evennia in interactive (foreground) mode with `evennia istart`. This is important -
without this step the debugger will not start correctly - it will start in this interactive
terminal.
3. Perform the steps that will trigger the line where you added the `set_trace()` call. The debugger
will start in the terminal from which Evennia was interactively started.
2. (Re-)start Evennia in interactive (foreground) mode with `evennia istart`. This is important - without this step the debugger will not start correctly - it will start in this interactive terminal.
3. Perform the steps that will trigger the line where you added the `set_trace()` call. The debugger will start in the terminal from which Evennia was interactively started.
The `evennia.set_trace` function takes the following arguments:
@ -37,8 +30,7 @@ The `evennia.set_trace` function takes the following arguments:
evennia.set_trace(debugger='auto', term_size=(140, 40))
```
Here, `debugger` is one of `pdb`, `pudb` or `auto`. If `auto`, use `pudb` if available, otherwise
use `pdb`. The `term_size` tuple sets the viewport size for `pudb` only (it's ignored by `pdb`).
Here, `debugger` is one of `pdb`, `pudb` or `auto`. If `auto`, use `pudb` if available, otherwise use `pdb`. The `term_size` tuple sets the viewport size for `pudb` only (it's ignored by `pdb`).
## A simple example using pdb
@ -71,9 +63,7 @@ class CmdTest(Command):
```
If you type `test` in your game, everything will freeze. You won't get any feedback from the game,
and you won't be able to enter any command (nor anyone else). It's because the debugger has started
in your console, and you will find it here. Below is an example with `pdb`.
If you type `test` in your game, everything will freeze. You won't get any feedback from the game, and you won't be able to enter any command (nor anyone else). It's because the debugger has started in your console, and you will find it here. Below is an example with `pdb`.
```
...
@ -83,13 +73,11 @@ in your console, and you will find it here. Below is an example with `pdb`.
```
`pdb` notes where it has stopped execution and, what line is about to be executed (in our case, `obj
= self.search(self.args)`), and ask what you would like to do.
`pdb` notes where it has stopped execution and, what line is about to be executed (in our case, `obj = self.search(self.args)`), and ask what you would like to do.
### Listing surrounding lines of code
When you have the `pdb` prompt `(Pdb)`, you can type in different commands to explore the code. The
first one you should know is `list` (you can type `l` for short):
When you have the `pdb` prompt `(Pdb)`, you can type in different commands to explore the code. The first one you should know is `list` (you can type `l` for short):
```
(Pdb) l
@ -107,18 +95,13 @@ first one you should know is `list` (you can type `l` for short):
(Pdb)
```
Okay, this didn't do anything spectacular, but when you become more confident with `pdb` and find
yourself in lots of different files, you sometimes need to see what's around in code. Notice that
there is a little arrow (`->`) before the line that is about to be executed.
Okay, this didn't do anything spectacular, but when you become more confident with `pdb` and find yourself in lots of different files, you sometimes need to see what's around in code. Notice that there is a little arrow (`->`) before the line that is about to be executed.
This is important: **about to be**, not **has just been**. You need to tell `pdb` to go on (we'll
soon see how).
This is important: **about to be**, not **has just been**. You need to tell `pdb` to go on (we'll soon see how).
### Examining variables
`pdb` allows you to examine variables (or really, to run any Python instruction). It is very useful
to know the values of variables at a specific line. To see a variable, just type its name (as if
you were in the Python interpreter:
`pdb` allows you to examine variables (or really, to run any Python instruction). It is very useful to know the values of variables at a specific line. To see a variable, just type its name (as if you were in the Python interpreter:
```
(Pdb) self
@ -158,9 +141,7 @@ AttributeError: "'CmdTest' object has no attribute 'search'"
(Pdb)
```
`Pdb` is complaining that you try to call the `search` method on a command... whereas there's no
`search` method on commands. The character executing the command is in `self.caller`, so we might
change our line:
`Pdb` is complaining that you try to call the `search` method on a command... whereas there's no `search` method on commands. The character executing the command is in `self.caller`, so we might change our line:
```python
obj = self.caller.search(self.args)
@ -168,19 +149,14 @@ obj = self.caller.search(self.args)
### Letting the program run
`pdb` is waiting to execute the same instruction... it provoked an error but it's ready to try
again, just in case. We have fixed it in theory, but we need to reload, so we need to enter a
command. To tell `pdb` to terminate and keep on running the program, use the `continue` (or `c`)
command:
`pdb` is waiting to execute the same instruction... it provoked an error but it's ready to try again, just in case. We have fixed it in theory, but we need to reload, so we need to enter a command. To tell `pdb` to terminate and keep on running the program, use the `continue` (or `c`) command:
```
(Pdb) c
...
```
You see an error being caught, that's the error we have fixed... or hope to have. Let's reload the
game and try again. You need to run `evennia istart` again and then run `test` to get into the
command again.
You see an error being caught, that's the error we have fixed... or hope to have. Let's reload the game and try again. You need to run `evennia istart` again and then run `test` to get into the command again.
```
> .../mygame/commands/command.py(79)func()
@ -218,12 +194,11 @@ fix that bug too, it would be better):
...
```
Notice that you'll have an error in the game this time. Let's try with a valid parameter. I have
another character, `barkeep`, in this room:
Notice that you'll have an error in the game this time. Let's try with a valid parameter. I have another character, `barkeep`, in this room:
```test barkeep```
And again, the command freezes, and we have the debugger opened in the console.
And again, the command freezes, and we have the debugger opened in the console.
Let's execute this line right away:
@ -248,32 +223,16 @@ TypeError: 'get_display_name() takes exactly 2 arguments (1 given)'
(Pdb)
```
As an exercise, fix this error, reload and run the debugger again. Nothing better than some
experimenting!
As an exercise, fix this error, reload and run the debugger again. Nothing better than some experimenting!
Your debugging will often follow the same strategy:
1. Receive an error you don't understand.
2. Put a breaking point **BEFORE** the error occurs.
3. Run the code again and see the debugger open.
4. Run the program line by line,examining variables, checking the logic of instructions.
5. Continue and try again, each step a bit further toward the truth and the working feature.
### Stepping through a function
`n` is useful, but it will avoid stepping inside of functions if it can. But most of the time, when
we have an error we don't understand, it's because we use functions or methods in a way that wasn't
intended by the developer of the API. Perhaps using wrong arguments, or calling the function in a
situation that would cause a bug. When we have a line in the debugger that calls a function or
method, we can "step" to examine it further. For instance, in the previous example, when `pdb` was
about to execute `obj = self.caller.search(self.args)`, we may want to see what happens inside of
the `search` method.
To do so, use the `step` (or `s`) command. This command will show you the definition of the
function/method and you can then use `n` as before to see it line-by-line. In our little example,
stepping through a function or method isn't that useful, but when you have an impressive set of
commands, functions and so on, it might really be handy to examine some feature and make sure they
operate as planned.
3. Run `evennia istart`
4. Run the code again and see the debugger open.
5. Run the program line by line, examining variables, checking the logic of instructions.
6. Continue and try again, each step a bit further toward the truth and the working feature.
## Cheat-sheet of pdb/pudb commands
@ -292,5 +251,4 @@ this directly). |
| `<RETURN>` | Repeat the last command (don't type `n` repeatedly, just type it once and then press
`<RETURN>` to repeat it). |
If you want to learn more about debugging with Pdb, you will find an [interesting tutorial on that
topic here](https://pymotw.com/3/pdb/).
If you want to learn more about debugging with Pdb, you will find an [interesting tutorial on that topic here](https://pymotw.com/3/pdb/).

278
docs/1.0-dev/_sources/Coding/Evennia-Code-Style.md.txt Normal file
View file

@ -0,0 +1,278 @@
# Evennia Code Style
All code submitted or committed to the Evennia project should aim to follow the
guidelines outlined in [Python PEP 8][pep8]. Keeping the code style uniform
makes it much easier for people to collaborate and read the code.
A good way to check if your code follows PEP8 is to use the [PEP8 tool][pep8tool]
on your sources.
## Main code style specification
* 4-space indentation, NO TABS!
* Unix line endings.
* 100 character line widths
* CamelCase is only used for classes, nothing else.
* All non-global variable names and all function names are to be
lowercase, words separated by underscores. Variable names should
always be more than two letters long.
* Module-level global variables (only) are to be in CAPITAL letters.
* Imports should be done in this order:
- Python modules (builtins and standard library)
- Twisted modules
- Django modules
- Evennia library modules (`evennia`)
- Evennia contrib modules (`evennia.contrib`)
* All modules, classes, functions and methods should have doc strings formatted
as outlined below.
* All default commands should have a consistent docstring formatted as
outlined below.
## Code Docstrings
All modules, classes, functions and methods should have docstrings
formatted with [Google style][googlestyle] -inspired indents, using
[Markdown][githubmarkdown] formatting where needed. Evennia's `api2md`
parser will use this to create pretty API documentation.
### Module docstrings
Modules should all start with at least a few lines of docstring at
their top describing the contents and purpose of the module.
Example of module docstring (top of file):
```python
"""
This module handles the creation of `Objects` that
are useful in the game ...
"""
```
Sectioning (`# title`, `## subtile` etc) should not be used in
freeform docstrings - this will confuse the sectioning of the auto
documentation page and the auto-api will create this automatically.
Write just the section name bolded on its own line to mark a section.
Beyond sections markdown should be used as needed to format
the text.
Code examples should use [multi-line syntax highlighting][markdown-hilight]
to mark multi-line code blocks, using the "python" identifier. Just
indenting code blocks (common in markdown) will not produce the
desired look.
When using any code tags (inline or blocks) it's recommended that you
don't let the code extend wider than about 70 characters or it will
need to be scrolled horizontally in the wiki (this does not affect any
other text, only code).
### Class docstrings
The root class docstring should describe the over-arching use of the
class. It should usually not describe the exact call sequence nor list
important methods, this tends to be hard to keep updated as the API
develops. Don't use section markers (`#`, `##` etc).
Example of class docstring:
```python
class MyClass(object):
"""
This class describes the creation of `Objects`. It is useful
in many situations, such as ...
"""
```
### Function / method docstrings
Example of function or method docstring:
```python
def funcname(a, b, c, d=False, **kwargs):
"""
This is a brief introduction to the function/class/method
Args:
a (str): This is a string argument that we can talk about
over multiple lines.
b (int or str): Another argument.
c (list): A list argument.
d (bool, optional): An optional keyword argument.
Keyword Args:
test (list): A test keyword.
Returns:
str: The result of the function.
Raises:
RuntimeException: If there is a critical error,
this is raised.
IOError: This is only raised if there is a
problem with the database.
Notes:
This is an example function. If `d=True`, something
amazing will happen.
"""
```
The syntax is very "loose" but the indentation matters. That is, you
should end the block headers (like `Args:`) with a line break followed by
an indent. When you need to break a line you should start the next line
with another indent. For consistency with the code we recommend all
indents to be 4 spaces wide (no tabs!).
Here are all the supported block headers:
```
"""
Args
argname (freeform type): Description endind with period.
Keyword Args:
argname (freeform type): Description.
Returns/Yields:
type: Description.
Raises:
Exceptiontype: Description.
Notes/Note/Examples/Example:
Freeform text.
"""
```
Parts marked with "freeform" means that you can in principle put any
text there using any formatting except for sections markers (`#`, `##`
etc). You must also keep indentation to mark which block you are part
of. You should normally use the specified format rather than the
freeform counterpart (this will produce nicer output) but in some
cases the freeform may produce a more compact and readable result
(such as when describing an `*args` or `**kwargs` statement in general
terms). The first `self` argument of class methods should never be
documented.
Note that
```
"""
Args:
argname (type, optional): Description.
"""
```
and
```
"""
Keyword Args:
sargname (type): Description.
"""
```
mean the same thing! Which one is used depends on the function or
method documented, but there are no hard rules; If there is a large
`**kwargs` block in the function, using the `Keyword Args:` block may be a
good idea, for a small number of arguments though, just using `Args:`
and marking keywords as `optional` will shorten the docstring and make
it easier to read.
## Default Command Docstrings
These represent a special case since Commands in Evennia use their class
docstrings to represent the in-game help entry for that command.
All the commands in the _default command_ sets should have their doc-strings
formatted on a similar form. For contribs, this is loosened, but if there is
no particular reason to use a different form, one should aim to use the same
style for contrib-command docstrings as well.
```python
"""
Short header
Usage:
key[/switches, if any] <mandatory args> [optional] choice1||choice2||choice3
Switches:
switch1 - description
switch2 - description
Examples:
Usage example and output
Longer documentation detailing the command.
"""
```
- Two spaces are used for *indentation* in all default commands.
- Square brackets `[ ]` surround *optional, skippable arguments*.
- Angled brackets `< >` surround a _description_ of what to write rather than the exact syntax.
- Explicit choices are separated by `|`. To avoid this being parsed as a color code, use `||` (this
will come out as a single `|`) or put spaces around the character ("` | `") if there's plenty of room.
- The `Switches` and `Examples` blocks are optional and based on the Command.
Here is the `nick` command as an example:
```python
"""
Define a personal alias/nick
Usage:
nick[/switches] <nickname> = [<string>]
alias ''
Switches:
object - alias an object
account - alias an account
clearall - clear all your aliases
list - show all defined aliases (also "nicks" works)
Examples:
nick hi = say Hello, I'm Sarah!
nick/object tom = the tall man
A 'nick' is a personal shortcut you create for your own use [...]
"""
```
For commands that *require arguments*, the policy is for it to return a `Usage:`
string if the command is entered without any arguments. So for such commands,
the Command body should contain something to the effect of
```python
if not self.args:
self.caller.msg("Usage: nick[/switches] <nickname> = [<string>]")
return
```
## Tools for auto-linting
### black
Automatic pep8 compliant formatting and linting can be performed using the
`black` formatter:
black --line-length 100
### PyCharm
The Python IDE [Pycharm][pycharm] can auto-generate empty doc-string stubs. The
default is to use `reStructuredText` form, however. To change to Evennia's
Google-style docstrings, follow [this guide][pycharm-guide].
[pep8]: http://www.python.org/dev/peps/pep-0008
[pep8tool]: https://pypi.python.org/pypi/pep8
[googlestyle]: https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html
[githubmarkdown]: https://help.github.com/articles/github-flavored-markdown/
[markdown-hilight]: https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting
[command-docstrings]: https://github.com/evennia/evennia/wiki/Using%20MUX%20As%20a%20Standard#documentation-policy
[pycharm]: https://www.jetbrains.com/pycharm/
[pycharm-guide]: https://www.jetbrains.com/help/pycharm/2016.3/python-integrated-tools.html

108
docs/1.0-dev/_sources/Coding/Profiling.md.txt
View file

@ -1,24 +1,16 @@
# Profiling
*This is considered an advanced topic mainly of interest to server developers.*
```{important}
This is considered an advanced topic. It's mainly of interest to server developers.
```
## Introduction
Sometimes it can be useful to try to determine just how efficient a particular piece of code is, or to figure out if one could speed up things more than they are. There are many ways to test the performance of Python and the running server.
Sometimes it can be useful to try to determine just how efficient a particular
piece of code is, or to figure out if one could speed up things more than they
are. There are many ways to test the performance of Python and the running
server.
Before digging into this section, remember Donald Knuth's
[words of wisdom](https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize):
Before digging into this section, remember Donald Knuth's [words of wisdom](https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize):
> *[...]about 97% of the time: Premature optimization is the root of all evil*.
That is, don't start to try to optimize your code until you have actually
identified a need to do so. This means your code must actually be working before
you start to consider optimization. Optimization will also often make your code
more complex and harder to read. Consider readability and maintainability and
you may find that a small gain in speed is just not worth it.
That is, don't start to try to optimize your code until you have actually identified a need to do so. This means your code must actually be working before you start to consider optimization. Optimization will also often make your code more complex and harder to read. Consider readability and maintainability and you may find that a small gain in speed is just not worth it.
## Simple timer tests
@ -36,53 +28,31 @@ could use the following code:
<<< 5.358283996582031
```
The `setup` keyword is used to set up things that should not be included in the
time measurement, like `a = []` in the first call.
The `setup` keyword is used to set up things that should not be included in the time measurement, like `a = []` in the first call.
By default the `timeit` function will re-run the given test 1000000 times and
returns the *total time* to do so (so *not* the average per test). A hint is to
not use this default for testing something that includes database writes - for
that you may want to use a lower number of repeats (say 100 or 1000) using the
`number=100` keyword.
By default the `timeit` function will re-run the given test 1000000 times and returns the *total time* to do so (so *not* the average per test). A hint is to not use this default for testing something that includes database writes - for that you may want to use a lower number of repeats (say 100 or 1000) using the `number=100` keyword.
In the example above, we see that this number of calls, using a list comprehension is about twice as fast as building a list using `.append()`.
## Using cProfile
Python comes with its own profiler, named cProfile (this is for cPython, no
tests have been done with `pypy` at this point). Due to the way Evennia's
processes are handled, there is no point in using the normal way to start the
profiler (`python -m cProfile evennia.py`). Instead you start the profiler
through the launcher:
Python comes with its own profiler, named cProfile (this is for cPython, no tests have been done with `pypy` at this point). Due to the way Evennia's processes are handled, there is no point in using the normal way to start the profiler (`python -m cProfile evennia.py`). Instead you start the profiler through the launcher:
evennia --profiler start
This will start Evennia with the Server component running (in daemon mode) under
cProfile. You could instead try `--profile` with the `portal` argument to
profile the Portal (you would then need to
[start the Server separately](../Setup/Start-Stop-Reload.md)).
This will start Evennia with the Server component running (in daemon mode) under cProfile. You could instead try `--profile` with the `portal` argument to profile the Portal (you would then need to [start the Server separately](../Setup/Running-Evennia.md)).
Please note that while the profiler is running, your process will use a lot more
memory than usual. Memory usage is even likely to climb over time. So don't
leave it running perpetually but monitor it carefully (for example using the
`top` command on Linux or the Task Manager's memory display on Windows).
Please note that while the profiler is running, your process will use a lot more memory than usual. Memory usage is even likely to climb over time. So don't leave it running perpetually but monitor it carefully (for example using the `top` command on Linux or the Task Manager's memory display on Windows).
Once you have run the server for a while, you need to stop it so the profiler
can give its report. Do *not* kill the program from your task manager or by
sending it a kill signal - this will most likely also mess with the profiler.
Instead either use `evennia.py stop` or (which may be even better), use
`@shutdown` from inside the game.
Once you have run the server for a while, you need to stop it so the profiler can give its report. Do *not* kill the program from your task manager or by sending it a kill signal - this will most likely also mess with the profiler. Instead either use `evennia.py stop` or (which may be even better), use `@shutdown` from inside the game.
Once the server has fully shut down (this may be a lot slower than usual) you
will find that profiler has created a new file `mygame/server/logs/server.prof`.
Once the server has fully shut down (this may be a lot slower than usual) you will find that profiler has created a new file `mygame/server/logs/server.prof`.
### Analyzing the profile
The `server.prof` file is a binary file. There are many ways to analyze and
display its contents, all of which has only been tested in Linux (If you are a
Windows/Mac user, let us know what works).
The `server.prof` file is a binary file. There are many ways to analyze and display its contents, all of which has only been tested in Linux (If you are a Windows/Mac user, let us know what works).
You can look at the contents of the profile file with Python's in-built `pstats`
module in the evennia shell (it's recommended you install `ipython` with `pip
install ipython` in your virtualenv first, for prettier output):
You can look at the contents of the profile file with Python's in-built `pstats` module in the evennia shell (it's recommended you install `ipython` with `pip install ipython` in your virtualenv first, for prettier output):
evennia shell
@ -97,9 +67,7 @@ p.strip_dirs().sort_stats(-1).print_stats()
```
See the
[Python profiling documentation](https://docs.python.org/3/library/profile.html#instant-user-s-manual)
for more information.
See the [Python profiling documentation](https://docs.python.org/3/library/profile.html#instant-user-s-manual) for more information.
You can also visualize the data in various ways.
- [Runsnake](https://pypi.org/project/RunSnakeRun/) visualizes the profile to
@ -112,20 +80,11 @@ You can also visualize the data in various ways.
`pyprof2calltree` via `pip` whereas KCacheGrind is something you need to get
via your package manager or their homepage.
How to analyze and interpret profiling data is not a trivial issue and depends
on what you are profiling for. Evennia being an asynchronous server can also
confuse profiling. Ask on the mailing list if you need help and be ready to be
able to supply your `server.prof` file for comparison, along with the exact
conditions under which it was obtained.
How to analyze and interpret profiling data is not a trivial issue and depends on what you are profiling for. Evennia being an asynchronous server can also confuse profiling. Ask on the mailing list if you need help and be ready to be able to supply your `server.prof` file for comparison, along with the exact conditions under which it was obtained.
## The Dummyrunner
It is difficult to test "actual" game performance without having players in your
game. For this reason Evennia comes with the *Dummyrunner* system. The
Dummyrunner is a stress-testing system: a separate program that logs into your
game with simulated players (aka "bots" or "dummies"). Once connected, these
dummies will semi-randomly perform various tasks from a list of possible
actions. Use `Ctrl-C` to stop the Dummyrunner.
It is difficult to test "actual" game performance without having players in your game. For this reason Evennia comes with the *Dummyrunner* system. The Dummyrunner is a stress-testing system: a separate program that logs into your game with simulated players (aka "bots" or "dummies"). Once connected, these dummies will semi-randomly perform various tasks from a list of possible actions. Use `Ctrl-C` to stop the Dummyrunner.
```{warning}
@ -140,9 +99,7 @@ This is the recommended process for using the dummy runner:
from evennia.server.profiling.settings_mixin import *
This will override your settings and disable Evennia's rate limiters and
DoS-protections, which would otherwise block mass-connecting clients from
one IP. Notably, it will also change to a different (faster) password hasher.
This will override your settings and disable Evennia's rate limiters and DoS-protections, which would otherwise block mass-connecting clients from one IP. Notably, it will also change to a different (faster) password hasher.
1. (recommended): Build a new database. If you use default Sqlite3 and want to
keep your existing database, just rename `mygame/server/evennia.db3` to
`mygame/server/evennia.db3_backup` and run `evennia migrate` and `evennia
@ -156,29 +113,17 @@ This is the recommended process for using the dummy runner:
Use `Ctrl-C` (or `Cmd-C`) to stop it.
If you want to see what the dummies are actually doing you can run with a single
dummy:
If you want to see what the dummies are actually doing you can run with a single dummy:
evennia --dummyrunner 1
The inputs/outputs from the dummy will then be printed. By default the runner
uses the 'looker' profile, which just logs in and sends the 'look' command
over and over. To change the settings, copy the file
`evennia/server/profiling/dummyrunner_settings.py` to your `mygame/server/conf/`
directory, then add this line to your settings file to use it in the new
location:
The inputs/outputs from the dummy will then be printed. By default the runner uses the 'looker' profile, which just logs in and sends the 'look' command over and over. To change the settings, copy the file `evennia/server/profiling/dummyrunner_settings.py` to your `mygame/server/conf/` directory, then add this line to your settings file to use it in the new location:
DUMMYRUNNER_SETTINGS_MODULE = "server/conf/dummyrunner_settings.py"
The dummyrunner settings file is a python code module in its own right - it
defines the actions available to the dummies. These are just tuples of command
strings (like "look here") for the dummy to send to the server along with a
probability of them happening. The dummyrunner looks for a global variable
`ACTIONS`, a list of tuples, where the first two elements define the
commands for logging in/out of the server.
The dummyrunner settings file is a python code module in its own right - it defines the actions available to the dummies. These are just tuples of command strings (like "look here") for the dummy to send to the server along with a probability of them happening. The dummyrunner looks for a global variable `ACTIONS`, a list of tuples, where the first two elements define the commands for logging in/out of the server.
Below is a simplified minimal setup (the default settings file adds a lot more
functionality and info):
Below is a simplified minimal setup (the default settings file adds a lot more functionality and info):
```python
# minimal dummyrunner setup file
@ -224,8 +169,7 @@ ACTIONS = (
```
At the bottom of the default file are a few default profiles you can test out
by just setting the `PROFILE` variable to one of the options.
At the bottom of the default file are a few default profiles you can test out by just setting the `PROFILE` variable to one of the options.
### Dummyrunner hints

63
docs/1.0-dev/_sources/Coding/Setting-up-PyCharm.md.txt
View file

@ -1,18 +1,14 @@
# Setting up PyCharm with Evennia
[PyCharm](https://www.jetbrains.com/pycharm/) is a Python developer's IDE from Jetbrains available
for Windows, Mac and Linux. It is a commercial product but offer free trials, a scaled-down
community edition and also generous licenses for OSS projects like Evennia.
[PyCharm](https://www.jetbrains.com/pycharm/) is a Python developer's IDE from Jetbrains available for Windows, Mac and Linux. It is a commercial product but offer free trials, a scaled-down community edition and also generous licenses for OSS projects like Evennia.
> This page was originally tested on Windows (so use Windows-style path examples), but should work
the same for all platforms.
> This page was originally tested on Windows (so use Windows-style path examples), but should work the same for all platforms.
First, install Evennia on your local machine with [[Getting Started]]. If you're new to PyCharm,
loading your project is as easy as selecting the `Open` option when PyCharm starts, and browsing to
your game folder (the one created with `evennia --init`). We refer to it as `mygame` here.
First, install Evennia on your local machine with [[Getting Started]]. If you're new to PyCharm, loading your project is as easy as selecting the `Open` option when PyCharm starts, and browsing to your game folder (the one created with `evennia --init`). We refer to it as `mygame` here.
If you want to be able to examine evennia's core code or the scripts inside your virtualenv, you'll
need to add them to your project too:
1. Go to `File > Open...`
1. Select the folder (i.e. the `evennia` root)
1. Select "Open in current window" and "Add to currently opened projects"
@ -33,69 +29,46 @@ Enjoy seeing all your imports checked properly, setting breakpoints, and live va
1. Launch Evennia in your preferred way (usually from a console/terminal)
1. Open your project in PyCharm
1. In the PyCharm menu, select `Run > Attach to Local Process...`
1. From the list, pick the `twistd` process with the `server.py` parameter (Example: `twistd.exe
--nodaemon --logfile=\<mygame\>\server\logs\server.log --python=\<evennia
repo\>\evennia\server\server.py`)
1. From the list, pick the `twistd` process with the `server.py` parameter (Example: `twistd.exe --nodaemon --logfile=\<mygame\>\server\logs\server.log --python=\<evennia repo\>\evennia\server\server.py`)
Of course you can attach to the `portal` process as well. If you want to debug the Evennia launcher
or runner for some reason (or just learn how they work!), see Run Configuration below.
> NOTE: Whenever you reload Evennia, the old Server process will die and a new one start. So when
you restart you have to detach from the old and then reattach to the new process that was created.
> NOTE: Whenever you reload Evennia, the old Server process will die and a new one start. So when you restart you have to detach from the old and then reattach to the new process that was created.
> To make the process less tedious you can apply a filter in settings to show only the server.py process in the list. To do that navigate to: `Settings/Preferences | Build, Execution, Deployment | Python Debugger` and then in `Attach to process` field put in: `twistd.exe" --nodaemon`. This is an example for windows, I don't have a working mac/linux box.
> To make the process less tedious you can apply a filter in settings to show only the server.py
process in the list. To do that navigate to: `Settings/Preferences | Build, Execution, Deployment |
Python Debugger` and then in `Attach to process` field put in: `twistd.exe" --nodaemon`. This is an
example for windows, I don't have a working mac/linux box.
![Example process filter configuration](https://i.imgur.com/vkSheR8.png)
## Setting up an Evennia run configuration
This configuration allows you to launch Evennia from inside PyCharm. Besides convenience, it also
allows suspending and debugging the evennia_launcher or evennia_runner at points earlier than you
could by running them externally and attaching. In fact by the time the server and/or portal are
running the launcher will have exited already.
This configuration allows you to launch Evennia from inside PyCharm. Besides convenience, it also allows suspending and debugging the evennia_launcher or evennia_runner at points earlier than you could by running them externally and attaching. In fact by the time the server and/or portal are running the launcher will have exited already.
1. Go to `Run > Edit Configutations...`
1. Click the plus-symbol to add a new configuration and choose Python
1. Add the script: `\<yourrepo\>\evenv\Scripts\evennia_launcher.py` (substitute your virtualenv if
it's not named `evenv`)
1. Add the script: `\<yourrepo\>\evenv\Scripts\evennia_launcher.py` (substitute your virtualenv if it's not named `evenv`)
1. Set script parameters to: `start -l` (-l enables console logging)
1. Ensure the chosen interpreter is from your virtualenv
1. Set Working directory to your `mygame` folder (not evenv nor evennia)
1. You can refer to the PyCharm documentation for general info, but you'll want to set at least a
config name (like "MyMUD start" or similar).
1. You can refer to the PyCharm documentation for general info, but you'll want to set at least a config name (like "MyMUD start" or similar).
Now set up a "stop" configuration by following the same steps as above, but set your Script
parameters to: stop (and name the configuration appropriately).
Now set up a "stop" configuration by following the same steps as above, but set your Script parameters to: stop (and name the configuration appropriately).
A dropdown box holding your new configurations should appear next to your PyCharm run button.
Select MyMUD start and press the debug icon to begin debugging. Depending on how far you let the
program run, you may need to run your "MyMUD stop" config to actually stop the server, before you'll
be able start it again.
A dropdown box holding your new configurations should appear next to your PyCharm run button. Select MyMUD start and press the debug icon to begin debugging. Depending on how far you let the program run, you may need to run your "MyMUD stop" config to actually stop the server, before you'll be able start it again.
## Alternative run configuration - utilizing logfiles as source of data
## Alternative config - utilizing logfiles as source of data
This configuration takes a bit different approach as instead of focusing on getting the data back
through logfiles. Reason for that is this way you can easily separate data streams, for example you
rarely want to follow both server and portal at the same time, and this will allow it. This will
also make sure to stop the evennia before starting it, essentially working as reload command (it
will also include instructions how to disable that part of functionality). We will start by defining
a configuration that will stop evennia. This assumes that `upfire` is your pycharm project name, and
also the game name, hence the `upfire/upfire` path.
This configuration takes a bit different approach as instead of focusing on getting the data back through logfiles. Reason for that is this way you can easily separate data streams, for example you rarely want to follow both server and portal at the same time, and this will allow it. This will also make sure to stop the evennia before starting it, essentially working as reload command (it will also include instructions how to disable that part of functionality). We will start by defining a configuration that will stop evennia. This assumes that `upfire` is your pycharm project name, and also the game name, hence the `upfire/upfire` path.
1. Go to `Run > Edit Configutations...`\
1. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should
be project default)
1. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should be project default)
1. Name the configuration as "stop evennia" and fill rest of the fields accordingly to the image:
![Stop run configuration](https://i.imgur.com/gbkXhlG.png)
1. Press `Apply`
Now we will define the start/reload command that will make sure that evennia is not running already,
and then start the server in one go.
Now we will define the start/reload command that will make sure that evennia is not running already, and then start the server in one go.
1. Go to `Run > Edit Configutations...`\
1. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should
be project default)
1. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should be project default)
1. Name the configuration as "start evennia" and fill rest of the fields accordingly to the image:
![Start run configuration](https://i.imgur.com/5YEjeHq.png)
1. Navigate to the `Logs` tab and add the log files you would like to follow. The picture shows

16
docs/1.0-dev/_sources/Coding/Unit-Testing.md.txt
View file

@ -1,19 +1,11 @@
# Unit Testing
*Unit testing* means testing components of a program in isolation from each other to make sure every
part works on its own before using it with others. Extensive testing helps avoid new updates causing
unexpected side effects as well as alleviates general code rot (a more comprehensive wikipedia
article on unit testing can be found [here](https://en.wikipedia.org/wiki/Unit_test)).
*Unit testing* means testing components of a program in isolation from each other to make sure every part works on its own before using it with others. Extensive testing helps avoid new updates causing unexpected side effects as well as alleviates general code rot (a more comprehensive wikipedia article on unit testing can be found [here](https://en.wikipedia.org/wiki/Unit_test)).
A typical unit test set calls some function or method with a given input, looks at the result and
makes sure that this result looks as expected. Rather than having lots of stand-alone test programs,
Evennia makes use of a central *test runner*. This is a program that gathers all available tests all
over the Evennia source code (called *test suites*) and runs them all in one go. Errors and
tracebacks are reported.
By default Evennia only tests itself. But you can also add your own tests to your game code and have
Evennia run those for you.
A typical unit test set calls some function or method with a given input, looks at the result and makes sure that this result looks as expected. Rather than having lots of stand-alone test programs, Evennia makes use of a central *test runner*. This is a program that gathers all available tests all over the Evennia source code (called *test suites*) and runs them all in one go. Errors and tracebacks are reported.
By default Evennia only tests itself. But you can also add your own tests to your game code and have Evennia run those for you.
## Running the Evennia test suite
To run the full Evennia test suite, go to your game folder and issue the command

134
docs/1.0-dev/_sources/Coding/Updating-Your-Game.md.txt
View file

@ -1,134 +0,0 @@
# Updating Your Game
Fortunately, it's extremely easy to keep your Evennia server up-to-date. If you haven't already, see
the [Getting Started guide](../Setup/Installation.md) and get everything running.
## Updating with the latest Evennia code changes
Very commonly we make changes to the Evennia code to improve things. There are many ways to get told
when to update: You can subscribe to the RSS feed or manually check up on the feeds from
https://www.evennia.com. You can also simply fetch the latest regularly.
When you're wanting to apply updates, simply `cd` to your cloned `evennia` root directory and type:
git pull
assuming you've got the command line client. If you're using a graphical client, you will probably
want to navigate to the `evennia` directory and either right click and find your client's pull
function, or use one of the menus (if applicable).
You can review the latest changes with
git log
or the equivalent in the graphical client. You can also see the latest changes online
[here](https://github.com/evennia/evennia/blob/master/CHANGELOG.md).
You will always need to do `evennia reload` (or `reload` from -in-game) from your game-dir to have
the new code affect your game. If you want to be really sure you should run a full `evennia reboot`
so that both Server and Portal can restart (this will disconnect everyone though, so if you know the
Portal has had no updates you don't have to do that).
## Upgrading Evennia dependencies
On occasion we update the versions of third-party libraries Evennia depend on (or we may add a new
dependency). This will be announced on the mailing list/forum. If you run into errors when starting
Evennia, always make sure you have the latest versions of everything. In some cases, like for
Django, starting the server may also give warning saying that you are using a working, but too-old
version that should not be used in production.
Upgrading `evennia` will automatically fetch all the latest packages that it now need. First `cd` to
your cloned `evennia` folder. Make sure your `virtualenv` is active and use
pip install --upgrade -e .
Remember the period (`.`) at the end - that applies the upgrade to the current location (your
`evennia` dir).
> The `-e` means that we are _linking_ the evennia sources rather than copying them into the
environment. This means we can most of the time just update the sources (with `git pull`) and see
those changes directly applied to our installed `evennia` package. Without installing/upgrading the
package with `-e`, we would have to remember to upgrade the package every time we downloaded any new
source-code changes.
Follow the upgrade output to make sure it finishes without errors. To check what packages are
currently available in your python environment after the upgrade, use
pip list
This will show you the version of all installed packages. The `evennia` package will also show the
location of its source code.
## Migrating the Database Schema
Whenever we change the database layout of Evennia upstream (such as when we add new features) you
will need to *migrate* your existing database. When this happens it will be clearly noted in the
`git log` (it will say something to the effect of "Run migrations"). Database changes will also be
announced on the Evennia [mailing list](https://groups.google.com/forum/#!forum/evennia).
When the database schema changes, you just go to your game folder and run
evennia migrate
> Hint: If the `evennia` command is not found, you most likely need to activate your
[virtualenv](../Glossary.md#virtualenv).
## Resetting your database
Should you ever want to start over completely from scratch, there is no need to re-download Evennia
or anything like that. You just need to clear your database. Once you are done, you just rebuild it
from scratch by running
evennia migrate
The first step in wiping your database is to stop Evennia completely with
evennia stop
If you run the default `SQlite3` database (to change this you need to edit your `settings.py` file),
the database is actually just a normal file in `mygame/server/` called `evennia.db3`. *Simply delete
that file* - that's it. Now run `evennia migrate` to recreate a new, fresh one.
If you run some other database system you can instead flush the database:
evennia flush
This will empty the database. However, it will not reset the internal counters of the database, so
you will start with higher dbref values. If this is okay, this is all you need.
Django also offers an easy way to start the database's own management should we want more direct
control:
evennia dbshell
In e.g. MySQL you can then do something like this (assuming your MySQL database is named "Evennia":
mysql> DROP DATABASE Evennia;
mysql> exit
> NOTE: Under Windows OS, in order to access SQLite dbshell you need to [download the SQLite
command-line shell program](https://www.sqlite.org/download.html). It's a single executable file
(sqlite3.exe) that you should place in the root of either your MUD folder or Evennia's (it's the
same, in both cases Django will find it).
## More about schema migrations
If and when an Evennia update modifies the database *schema* (that is, the under-the-hood details as
to how data is stored in the database), you must update your existing database correspondingly to
match the change. If you don't, the updated Evennia will complain that it cannot read the database
properly. Whereas schema changes should become more and more rare as Evennia matures, it may still
happen from time to time.
One way one could handle this is to apply the changes manually to your database using the database's
command line. This often means adding/removing new tables or fields as well as possibly convert
existing data to match what the new Evennia version expects. It should be quite obvious that this
quickly becomes cumbersome and error-prone. If your database doesn't contain anything critical yet
it's probably easiest to simply reset it and start over rather than to bother converting.
Enter *migrations*. Migrations keeps track of changes in the database schema and applies them
automatically for you. Basically, whenever the schema changes we distribute small files called
"migrations" with the source. Those tell the system exactly how to implement the change so you don't
have to do so manually. When a migration has been added we will tell you so on Evennia's mailing
lists and in commit messages -
you then just run `evennia migrate` to be up-to-date again.

620
docs/1.0-dev/_sources/Coding/Version-Control.md.txt
View file

@ -1,27 +1,15 @@
# Version Control
# Coding using Version Control
Version control software allows you to track the changes you make to your code, as well as being
able to easily backtrack these changes, share your development efforts and more.
[Version control](https://en.wikipedia.org/wiki/Version_control) allows you to track changes to your code. You can save 'snapshots' of your progress which means you can roll back undo things easily. Version control also allows you to easily back up your code to an online _repository_ such as Github. It also allows you to collaborate with others on the same code without clashing or worry about who changed what.
It's strongly recommended that you put your game code under version control. Version
control is also the way to contribue to Evennia itself.
```{sidebar} Do it!
It's _strongly_ recommended that you [put your game folder under version control](#putting-your-game-dir-under-version-control). Using git is is also the way to contribue to Evennia itself.
```
For an introduction to the concept, start with the Wikipedia article
[here](https://en.wikipedia.org/wiki/Version_control). Evennia uses the version
control system [Git](https://git-scm.com/) and this is what will be covered
henceforth. Note that this page primarily shows commands for Linux, but the
syntax should be the same for Windows and Mac.
For more help on using Git, please refer to the [Official GitHub
documentation](https://help.github.com/articles/set-up-git#platform-all).
Evennia uses the most commonly used version control system, [Git](https://git-scm.com/) . For additional help on using Git, please refer to the [Official GitHub documentation](https://help.github.com/articles/set-up-git#platform-all).
## Setting up Git
You can find expanded instructions for
installation [here](https://git-scm.com/book/en/Getting-Started-Installing-Git).
### Step 1: Install Git
- **Fedora Linux**
yum install git-core
@ -31,19 +19,15 @@ installation [here](https://git-scm.com/book/en/Getting-Started-Installing-Git).
apt-get install git
- **Windows**: It is recommended to use [Git for Windows](https://gitforwindows.org/).
- **Mac**: Mac platforms offer two methods for installation, one via MacPorts, which you can find
out about [here](https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac), or
you can use the [Git OSX Installer](https://sourceforge.net/projects/git-osx-installer/).
- **Mac**: Mac platforms offer two methods for installation, one via MacPorts, which you can find out about [here](https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac), or you can use the [Git OSX Installer](https://sourceforge.net/projects/git-osx-installer/).
### Step 2: Define user/e-mail Settings for Git
> You can find expanded instructions for installation [here](https://git-scm.com/book/en/Getting-Started-Installing-Git).
To avoid a common issue later, you will need to set a couple of settings; first you will need to
tell Git your username, followed by your e-mail address, so that when you commit code later you will
be properly credited.
```{sidebar} Git user nickname
If you ever make your code available online (or contribute to Evennia), your name will be visible to those reading the code-commit history. So if you are not comfortable with using your real, full name online, put a nickname (or your github handler) here.
```
To avoid a common issue later, you will need to set a couple of settings; first you will need to tell Git your username, followed by your e-mail address, so that when you commit code later you will be properly credited.
> Note that your commit information will be visible to everyone if you ever contribute to Evennia or
use an online service like github to host your code. So if you are not comfortable with using your
real, full name online, put a nickname here.
1. Set the default name for git to use when you commit:
@ -53,417 +37,313 @@ real, full name online, put a nickname here.
git config --global user.email "your_email@example.com"
> To get a running start with Git, here's [a good YouTube talk about it](https://www.youtube.com/watch?v=1ffBJ4sVUb4#t=1m58s). It's a bit long but it will help you understand the underlying ideas behind GIT (which in turn makes it a lot more intuitive to use).
## Putting your game folder under version control
## Common Git commands
> Note: The game folder's version control is completely separate from Evennia's repository.
```{sidebar} Git repository
This is just a fancy name for the folder you have designated to be under version control. We will make your `mygame` game folder into such a repository. The Evennia code is also in a (separate) git repository.
```
Git can be controlled via a GUI. But it's often easier to use the base terminal/console commands, since it makes it clear if something goes wrong.
After you have set up your game you will have created a new folder to host your particular game
(let's call this folder `mygame` for now).
All these actions need to be done from inside the _git repository_ .
This folder is *not* under version control at this point.
Git may seem daunting at first. But when working with git, you'll be using the same 2-3 commands 99% of the time. And you can make git _aliases_ to have them be even easier to remember.
git init mygame
Your mygame folder is now ready for version control! Add all the content and make a first
commit:
### `git init`
cd mygame
This initializes a folder/directory on your drive as a 'git repository'
git init .
The `.` means to apply to the current directory. If you are inside `mygame`, this makes your game dir into a git repository. That's all there is to it, really. You only need to do this once.
### `git add`
git add <file>
This tells Git to start to _track_ the file under version control. You need to do this when you create a new file. You can also add all files in your current directory:
git add .
Or
git add *
All files in the current directory are now tracked by Git. You only need to do this once for every file you want to track.
### `git commit`
git commit -a -m "This is the initial commit"
This _commits_ your changes. It stores a snapshot of all (`-a`) your code at the current time, adding a message `-m` so you know what you did. Later you can _check out_ your code the way it was at a given time. The message is mandatory and you will thank yourself later if write clear and descriptive log messages. If you don't add `-m`, a text editor opens for you to write the message instead.
The `git commit` is something you'll be using all the time, so it can be useful to make a _git alias_ for it:
git config --global alias.cma 'commit -a -m'
After you've run this, you can commit much simpler, like this:
git cma "This is the initial commit"
Much easier to remember!
### `git status`, `git diff` and `git log`
git status -s
This gives a short (`-s`) of the files that changes since your last `git commit`.
git diff --word-diff`
This shows exactly what changed in each file since you last made a `git commit`. The `--word-diff` option means it will mark if a single word changed on a line.
git log
This shows the log of all `commits` done. Each log will show you who made the change, the commit-message and a unique _hash_ (like `ba214f12ab12e123...`) that uniquely describes that commit.
You can make the `log` command more succinct with some more options:
ls=log --pretty=format:%C(green)%h\ %C(yellow)[%ad]%Cred%d\ %Creset%s%Cblue\ [%an] --decorate --date=relative
This adds coloration and another fancy effects (use `git help log` to see what they mean).
Let's add aliases:
git config --global alias.st 'status -s'
git config --global alias.df 'diff --word-diff'
git config --global alias.ls 'log --pretty=format:%C(green)%h\ %C(yellow)[%ad]%Cred%d\ %Creset%s%Cblue\ [%an] --decorate --date=relative'
You can now use the much shorter
git st # short status
git dif # diff with word-marking
git ls # log with pretty formatting
for these useful functions.
### `git branch`, `checkout` and `merge`
Git allows you to work with _branches_. These are separate development paths your code may take, completely separate from each other. You can later _merge_ the code from a branch back into another branch. Evennia's `master` and `develop` branches are examples of this.
git branch -b branchaname
This creates a new branch, exactly identical to the branch you were on. It also moves you to that branch.
git branch -D branchname
Deletes a branch.
git branch
Shows all your branches, marking which one you are currently on.
git checkout branchname
This checks out another branch. As long as you are in a branch all `git commit`s will commit the code to that branch only.
git checkout .
This checks out your _current branch_ and has the effect of throwing away all your changes since your last commit. This is like undoing what you did since the last save point.
git checkout b2342bc21c124
This checks out a particular _commit_, identified by the hash you find with `git log`. This open a 'temporary branch' where the code is as it was when you made this commit. As an example, you can use this to check where a bug was introduced. Check out an existing branch to go back to your normal timeline, or use `git branch -b newbranch` to break this code off into a new branch you can continue working from.
git merge branchname
This _merges_ the code from `branchname` into the branch you are currently in. Doing so may lead to _merge conflicts_ if the same code changed in different ways in the two branches. See [how to resolve merge conflicts in git](https://phoenixnap.com/kb/how-to-resolve-merge-conflicts-in-git) for more help.
### `git glone`, `git push` and `git pull`
All of these other commands have dealt with code only sitting in your local repository-folder. These commands instead allows you to exchange code with a _remote_ repository - usually one that is online (like on github).
> How you actually set up a remote repository is described [in the next section](#pushing-your-code-online).
git clone repository/path
This copies the remote repository to your current location. If you used the [Git installation instructions](../Setup/Installation-Git.md) to install Evennia, this is what you used to get your local copy of the Evennia repository.
git pull
Once you cloned or otherwise set up a remote repository, using `git pull` will re-sync the remote with what you have locally. If what you download clashes with local changes, git will force you to `git commit` your changes before you can continue with `git pull`.
git push
This uploads your local changes _of your current branch_ to the same-named branch on the remote repository. To be able to do this you must have write-permissions to the remote repository.
### Other git commands
There are _many_ other git commands. Read up on them online:
git reflog
Shows hashes of individual git actions. This allows you to go back in the git event history itself.
git reset
Force reset a branch to an earlier commit. This could throw away some history, so be careful.
git grep -n -I -i <query>
Quickly search for a phrase/text in all files tracked by git. Very useful to quickly find where things are. Set up an alias `git gr` with
```
git config --global alias.gr 'grep -n -I -i'
```
## Putting your game dir under version control
This makes use of the git commands listed in the previous section.
```{sidebar} git aliases
If you set up the git aliases for commands suggested in the previous section, you can use them instead!
```
cd mygame
git init .
git add *
git commit -a -m "Initial commit"
In turn these commands:
- Move us into the `mygame` folder
- Tell `git` that everything `*` means everything) in this folder should be put
under version control.
- _Commit_ all (`-a`) those newly added files to git and add a message `-m` so you remember
what you did at this point. Doing a commit is like saving a snapshot of the
current state of everything.
Your game-dir is now tracked by git.
Read on for details!
### Tracking files
When working on your code or fix bugs in your local branches you may end up creating new files. If
you do you must tell Git to track them by using the add command.
git add <filename>
You only need to do this once per file.
git status
will show if you have any modified, added or otherwise changed files. Some
files, like database files, logs and temporary PID files are usually *not*
tracked in version control. These should either not show up or have a question
mark in front of them.
```{note}
You will notice that some files are not covered by your git version control,
notably your settings file (`mygame/server/conf/settings.py`) and your sqlite3
database file `mygame/server/evennia.db3`. What is auto-ignored by is controlled
by the hidden file `mygame/.gitignore`. Evennia creates this file as part of
the creation of your game directory. Everything matched in this file will be
ignored by git. If you want to, for example, include your settings file for
collaborators to access, remove that entry in `.gitignore`.
```
You will notice that some files are not covered by your git version control, notably your secret-settings file (`mygame/server/conf/secret_settings.py`) and your sqlite3 database file `mygame/server/evennia.db3`. This is intentional and controlled from the file `mygame/.gitignore`.
```{warning}
You should *never* put your sqlite3 database file into git by removing its entry
in `.gitignore`. GIT is for backing up your code, not your database. That way
lies madness and a good chance you'll confuse yourself so that after a few
commits and reverts don't know what is in your database or not. If you want to
backup your database, do so by simply copying the file on your hard drive to a
backup-name.
lies madness and a good chance you'll confuse yourself. Make one mistake or local change and after a few commits and reverts you will have lost track of what is in your database or not. If you want to backup your SQlite3 database, do so by simply copying the database file to a safe location.
```
### Committing your Code
_Committing_ your code means storing the current snapshot of your code within
git. This creates a "save point" or "history" of your development process. You
can later jump back and forth in your history, for example to figure out just
when a bug was introduced or see what results the code used to produce compared
to now. Or just wiping everything since the last commit, if you did something
stupid.
It's usually a good idea to commit your changes often. Committing is fast and
local only - you will never commit anything online at this point. To commit your
changes, use
git commit --all
Also `-a` works. This will open a text editor for you to describe your change.
Be brief but informative in your message - you'll appreciate it later. When you
save and close the editor, the commit will be saved. You can create the message
directly with
git commit -a -m "This fixes a bug in the combat code."
### Changing your mind
If you have non-committed changes that you realize you want to throw away, you
'check out' the file you want - this will re-load it from the last committed
state:
git checkout <file_to_revert>
git checkout foo/bar/dummy.py
If you want to revert _all_ changes you did since last commit, do
git checkout .
(that is, add a single `.` at the end).
### Pushing your code online
So far your code is only located on your private machine. A good idea is to back
it up online. The easiest way to do this is to push it to your own remote
repository on GitHub.
So far your code is only located on your private machine. A good idea is to back it up online. The easiest way to do this is to `git push` it to your own remote repository on GitHub. So for this you need a (free) Github account.
```{important}
Just to avoid confusion, be aware that Github's documentation has changed to
calling the primary branch 'main' rather than 'master'. While Evennia still
uses 'master' branch (and this is what we refer to below), you can use either
name for your personal primary branch - they are equivalent.
If you don't want your code to be publicly visible, Github also allows you set up a _private_ repository, only visible to you.
```{note}
Github's defaults have changed to calling the primary branch 'main' rather than 'master'. While Evennia still uses 'master' branch (and this is what we refer to below), you can use either name for your personal primary branch - they are equivalent.
```
1. Make sure you have your game directory setup under git version control as
described in the previous section. Make sure to commit any changes you did.
2. Create a new, empty repository on Github. Github explains how
[here](https://help.github.com/articles/create-a-repo/) (do *not* "Initialize
the repository with a README" or else you'll create unrelated histories).
3. From your local game dir, do `git remote add origin <github URL>` where
`<github URL>` is the URL to your online repo. This tells your game dir that
it should be pushing to the remote online dir.
4. `git remote -v` to verify the online dir.
5. `git push origin master` (or `git push origin main`) now pushes your game dir
online so you can see it on github.com.
Create a new, empty repository on Github. [Github explains how here](https://help.github.com/articles/create-a-repo/) . _Don't_ allow it to add a README, license etc, that will just clash with what we upload later.
You can commit your work locally (`git commit --all -m "Make a change that
..."`) as many times as you want. When you want to push those changes to your
online repo, you do `git push`. You can also `git clone <url_to_online_repo>`
from your online repo to somewhere else (like your production server) and
henceforth do `git pull` to update that to the latest thing you pushed.
```{sidebar} Origin
We label the remote repository 'origin'. This is the git default and means we won't need to specify it explicitly later.
```
Note that GitHub's repos are, by default publicly visible by all. Creating a
publicly visible online clone might not be what you want for all parts of your
development process - you may prefer a more private venue when sharing your
revolutionary work with your team. If that's the case you can change your
repository to "Private" in the github settings. Then your code will only be
visible to those you specifically grant access.
Make sure you are in your local game dir (previously initialized as a git repo).
git remote add origin <github URL>
## Forking Evennia
This tells Git that there is a remote repository at `<github URL>`. See the github docs as to which URL to use. Verify that the remote works with `git remote -v`
This helps you set up an online *fork* of the main Evennia repository so you can
easily commit fixes and help with upstream development. You can do this step
also if you _didn't_ put your game dir under version control like in the
previous section - the evennia repo and your game dir repo are completely
separate.
Now we push to the remote (labeled 'origin' which is the default):
### Step 1: Fork the evennia/master repository
git push
> Before proceeding with the following step, make sure you have registered and
> created an account on [GitHub.com](https://github.com/). This is necessary in order to create a fork
of Evennia's master repository, and to push your commits to your fork either for
yourself or for contributing to
Evennia.
Depending on how you set up your authentication with github, you may be asked to enter your github username and password. If you set up SSH authentication, this command will just work.
A _fork_ is a clone of the master repository that you can make your own commits
and changes to. At the top of [this page](https://github.com/evennia/evennia),
click the "Fork" button, as it appears below.
![](https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png)
You use `git push` to upload your local changes so the remote repository is in sync with your local one. If you edited a file online using the Github editor (or a collaborator pushed code), you use `git pull` to sync in the other direction.
### Step 2: Clone your online fork of Evennia
## Contributing to Evennia
The fork only exists online as of yet. In a terminal, change your directory to
the folder you wish to develop in. From this directory run the following
command:
If you want to help contributing to Evennia you must do so by _forking_ - making your own remote copy of the Evennia repository on Github. So for this, you need a (free) Github account. Doing so is a completely separate process from [putting your game dir under version control](#putting-your-game-dir-under-version-control) (which you should also do!).
git clone https://github.com/yourusername/evennia.git
At the top right of [the evennia github page](https://github.com/evennia/evennia), click the "Fork" button:
This will download your fork to your computer. It creates a new folder
`evennia/` at your current location.
![fork button](../_static/images/fork_button.png)
### Step 3: Configure remotes
This will create a new online fork Evennia under your github account.
Your Evennia-fork is now separate from upstream, 'official' Evennia. You will
want to set it up so that you can easily sync our updates and changes to your
fork.
The fork only exists online as of yet. In a terminal, `cd` to the folder you wish to develop in. This folder should _not_ be your game dir, nor the place you cloned Evennia into if you used the [Git installation](../Setup/Installation-Git.md).
We do this by setting up a new _remote_. We actually already have one remote,
that is our own github form of Evennia. This got created when you cloned the
repo and defaults to being called `origin`.
From this directory run the following command:
We will now create a new remote called `upstream`.
git clone https://github.com/yourusername/evennia.git evennia
This will download your fork to your computer. It creates a new folder `evennia/` at your current location. If you installed Evennia using the [Git installation](../Setup/Installation-Git.md), this folder will be identical in content to the `evennia` folder you cloned during that installation. The difference is that this repo is connected to your remote fork and not to the 'original' _upstream_ Evennia.
When we cloned our fork, git automatically set up a 'remote repository' labeled `origin` pointing to it. So if we do `git pull` and `git push`, we'll push to our fork.
We now want to add a second remote repository linked to the original Evennia repo. We will label this remote repository `upstream`:
cd evennia
git remote add upstream https://github.com/evennia/evennia.git
This adds a remote to the main evennia repo.
If you also want to access Evennia's `develop` branch (the bleeding edge
development) do the following:
If you also want to access Evennia's `develop` branch (the bleeding edge development) do the following:
git fetch upstream develop
git checkout develop
Use
git checkout master
git checkout develop
to switch between the branches. If you want to contribute a fix, ask first which
branch to use. Normally `master` is for bug fixes and `develop` is for new
features, but late in the development of a new Evennia version, all changes
often go into `develop`.
to switch between the branches.
To pull the latest from upstream Evennia, just checkout the branch you want and do
## Working with your Evennia fork
git pull upstream
_Branches_ are stand-alone editions of the same code. You make a commit to a
branch. Switching to a branch will change the code on-disk. You can easily
make a new branch off a parent branch, and then merge it back into the same
branch later (or throw it away). This is a very common way to work on new
features in safety and isolation.
```{sidebar} Pushing to upstream
You can't do `git push upstream` unless you have write-access to the upstream Evennia repository. So there is no risk of you accidentally pushing your own code into the main, public repository.
```
### Updating to latest Evennia
### Fixing an Evennia bug or feature
When Evennia's official repository updates, first make sure to commit all your
changes to your branch and then checkout the "clean" master branch:
git checkout master
git pull upstream master
Or, if you are working against Evennia's development branch:
git checkout develop
git pull upstream develop
The `pull` command will fetch all the changes from the "upstream" remote and
merge it into your local master/develop branch. It should now be a perfect copy
of the latest Evennia changes.
### Making changes
As a rule of thumb you should _never_ work directly in Evennia's `master` or
`develop` branches. Instead you make a _new_ branch off the branch you want
and change _that_.
This should be done in your fork of Evennia. You should _always_ do this in a _separate git branch_ based off the Evennia branch you want to improve.
git checkout master (or develop)
check checkout -b strange_bug
git branch - b myfixbranch
You now have a new branch `strange_bug` that is an exact replica of the branch you
had checked out when you created it. Here you can now make your own
modifications.
Now fix whatever needs fixing. Abide by the [Evennia code style](./Evennia-Code-Style.md). You can `git commit` commit your changes along the way as normal.
git branches
Upstream Evennia is not standing still, so you want to make sure that your work is up-to-date with upstream changes. Make sure to first commit your `myfixbranch` changes, then
will show you which branches are available and which one you are currently
using. Use `git checkout <branch>` to move between them, but remember to commit
your changes before you do.
You often want to make sure also your work-branch has the latest upstream
changes. To do this, you need to first update your copy of the
`master`/`develop` branch and then _merge_ those changes into your work branch.
Make sure you have committed everything first!
git commit -a -m "My latest changes ..." # on your strange_bug branch
git checkout master (or develop)
git pull upstream develop
git checkout strange_bug
git pull upstream
git checkout myfixbranch
git merge master (or develop)
If everything went well, your `strange_bug` branch will now have the latest version
of Evennia merged with whatever changes you have done.
Now work away on your code and commit with reasonable commit messages
git commit -a -m "Fixed the issue in ..."
git commit -a -m "Adding unit tests. This resolves #123."
Use
git diff
to see what you changed since last commit, and
git log
to see past commits (including those made by Evennia upstream, remember that
your branch is a copy of the upstream one, including its history!)
## Sharing your Evennia fixes on Github
Up to this point your `strange_bug` branch only exists on your local computer. No
one else can see it. If you want a copy of this branch to also appear in your
online fork on GitHub, make sure to have checked out your "myfixes" branch and
then run the following:
git push -u origin strange_bug
You only need to do this once, the `-u` makes this the default push-location. In
the future, you can just push things online like this:
Up to this point your `myfixbranch` branch only exists on your local computer. No
one else can see it.
git push
### Troubleshooting
This will automatically create a matching `myfixbranch` in your forked version of Evennia and push to it. On github you will be able to see appear it in the `branches` dropdown. You can keep pushing to your remote `myfixbranch` as much as you like.
If you hadn't setup a public key on GitHub or aren't asked for a
username/password, you might get an error `403: Forbidden Access` at this stage.
In that case, some users have reported that the workaround is to create a file
`.netrc` under your home directory and add your github credentials there:
Once you feel you have something to share, you need to [create a pull request](https://github.com/evennia/evennia/pulls) (PR):
This is a formal request for upstream Evennia to adopt and pull your code into the main repository.
1. Click `New pull request`
2. Choose `compare across forks`
3. Select your fork from dropdown list of `head repository` repos. Pick the right branch to `compare`.
4. On the Evennia side (to the left) make sure to pick the right `base` branch: If you want to contribute a change to the `develop` branch, you must pick `develop` as the `base`.
5. Then click `Create pull request` and fill in as much information as you can in the form.
6. Optional: Once you saved your PR, you can go into your code (on github) and add some per-line comments; this can help reviewers by explaining complex code or decisions you made.
Now you just need to wait for your code to be reviewed. Expect to get feedback and be asked to make changes, add more documentation etc. Getting as PR merged can take a few iterations.
```{sidebar} Not all PRs can merge
While most PRs get merged, Evennia can't **guarantee** that your PR code will be deemed suitable to merge into upstream Evennia. For this reason it's a good idea to check in with the community _before_ you spend a lot of time on a large piece of code (fixing bugs is always a safe bet though!)
```
## Troubleshooting
### Getting 403: Forbidden access
Some users have experienced this on `git push` to their remote repository. They are not asked for username/password (and don't have a ssh key set up).
Some users have reported that the workaround is to create a file `.netrc` under your home directory and add your github credentials there:
```bash
machine github.com
login <my_github_username>
password <my_github_password>
```
## Making an Evennia Pull Request
If you think that the fixes you did in your `strange_bug` branch should be a
part of the regular Evennia, you should create a _Pull Request_ (PR). This is a
call for the Evennia maintainer to pull your change into an upstream branch.
> It is wise to make separate branches for every fix or series of fixes you want
to contribute.
Assuming you have followed the instructions above and have pushed your changes
online, [create a pull request](https://github.com/evennia/evennia/pulls) and
follow the instructions. Make sure to specifically select your `strange_bug`
branch to be the source of the merge and use the branch you based that branch
off (`master` or `develop`) as the target.
Evennia developers will then be able to examine your request and merge it if
it's deemed suitable. They may also come back with feedback and request you do
some changes.
Once approved and merged, your change will now be available in the upstream
branch:
git checkout master (or develope)
git pull upstream master (or develop)
Since your changes are now in upstream, your local `strange_bug` branch is now
superfluous and should be deleted:
git branch -D strange_bug
You can also safely delete your online `strange_bug` branch in your fork
(you can do this from the PR page on github).
## GIT tips and tricks
Some of the GIT commands can feel a little long and clunky if you need to do them often. Luckily you
can create aliases for those. Here are some useful commands to run:
```
# git st
# - view brief status info
git config --global alias.st 'status -s'
```
Above, you only need to ever enter the `git config ...` command once - you have then added the new
alias. Afterwards, just do `git st` to get status info. All the examples below follow the same
template.
```
# git cl
# - clone a repository
git config --global alias.cl clone
```
```
# git cma "commit message"
# - commit all changes without opening editor for message
git config --global alias.cma 'commit -a -m'
```
```
# git ca
# - amend text to your latest commit message
git config --global alias.ca 'commit --amend'
```
```
# git fl
# - file log; shows diffs of files in latest commits
git config --global alias.fl 'log -u'
```
```
# git co [branchname]
# - checkout
git config --global alias.co checkout
```
```
# git br <branchname>
# - create branch
git config --global alias.br branch
```
```
# git ls
# - view log tree
git config --global alias.ls 'log --pretty=format:"%C(green)%h\ %C(yellow)[%ad]%Cred%d\
%Creset%s%Cblue\ [%cn]" --decorate --date=relative --graph'
```
```
# git diff
# - show current uncommitted changes
git config --global alias.diff 'diff --word-diff'
```
```
# git grep <query>
# - search (grep) codebase for a search criterion
git config --global alias.grep 'grep -Ii'
```
To get a further feel for GIT there is also [a good YouTube talk about it](https://www.youtube.com/watch?v=1ffBJ4sVUb4#t=1m58s) - it's a bit long but it will help you understand the underlying ideas behind GIT
(which in turn makes it a lot more intuitive to use).
```

2
docs/1.0-dev/_sources/Components/Connection-Screen.md.txt
View file

@ -20,7 +20,7 @@ Effective, but not very exciting. You will most likely want to change this to be
your game. This is simple:
1. Edit `mygame/server/conf/connection_screens.py`.
1. [Reload](../Setup/Start-Stop-Reload.md) Evennia.
1. [Reload](../Setup/Running-Evennia.md) Evennia.
Evennia will look into this module and locate all *globally defined strings* in it. These strings
are used as the text in your connection screen and are shown to the user at startup. If more than

2
docs/1.0-dev/_sources/Components/Portal-And-Server.md.txt
View file

@ -2,7 +2,7 @@
Evennia consists of two processes, known as *Portal* and *Server*. They can be controlled from
inside the game or from the command line as described [here](../Setup/Start-Stop-Reload.md).
inside the game or from the command line as described [here](../Setup/Running-Evennia.md).
If you are new to the concept, the main purpose of separating the two is to have accounts connect to the Portal but keep the MUD running on the Server. This way one can restart/reload the game (the Server part) without Accounts getting disconnected.

69
docs/1.0-dev/_sources/Concepts/Using-MUX-as-a-Standard.md.txt
View file

@ -9,71 +9,4 @@ Evennia is *not* a MUX system though. It works very differently in many ways. Fo
deliberately lacks an online softcode language (a policy explained on our [softcode policy
page](./Soft-Code.md)). Evennia also does not shy from using its own syntax when deemed appropriate: the
MUX syntax has grown organically over a long time and is, frankly, rather arcane in places. All in
all the default command syntax should at most be referred to as "MUX-like" or "MUX-inspired".
## Documentation policy
All the commands in the default command sets should have their doc-strings formatted on a similar
form:
```python
"""
Short header
Usage:
key[/switches, if any] <mandatory args> [optional] choice1||choice2||choice3
Switches:
switch1 - description
switch2 - description
Examples:
usage example and output
Longer documentation detailing the command.
"""
```
- Two spaces are used for *indentation* in all default commands.
- Square brackets `[ ]` surround *optional, skippable arguments*.
- Angled brackets `< >` surround a _description_ of what to write rather than the exact syntax.
- *Explicit choices are separated by `|`. To avoid this being parsed as a color code, use `||` (this
will come out as a single `|`) or put spaces around the character ("` | `") if there's plenty of
room.
- The `Switches` and `Examples` blocks are optional based on the Command.
Here is the `nick` command as an example:
```python
"""
Define a personal alias/nick
Usage:
nick[/switches] <nickname> = [<string>]
alias ''
Switches:
object - alias an object
account - alias an account
clearall - clear all your aliases
list - show all defined aliases (also "nicks" works)
Examples:
nick hi = say Hello, I'm Sarah!
nick/object tom = the tall man
A 'nick' is a personal shortcut you create for your own use [...]
"""
```
For commands that *require arguments*, the policy is for it to return a `Usage:` string if the
command is entered without any arguments. So for such commands, the Command body should contain
something to the effect of
```python
if not self.args:
self.caller.msg("Usage: nick[/switches] <nickname> = [<string>]")
return
```
all the default command syntax should at most be referred to as "MUX-like" or "MUX-inspired".

84
docs/1.0-dev/_sources/Contribs/Contribs-Guidelines.md.txt Normal file
View file

@ -0,0 +1,84 @@
# Guidelines for Evennia contribs
Evennia has a [contrib](./Contribs-Overview.md) directory which contains optional, community-shared code organized by category. Anyone is welcome to contribute.
## What is suitable for a contrib?
- In general, you can contribute anything that you think may be useful to another developer. Unlike the 'core' Evennia, contribs can also be highly game-type-specific.
- Very small or incomplete snippets of code (e.g. meant to paste into some other code) are better shared as a post in the [Community Contribs & Snippets](https://github.com/evennia/evennia/discussions/2488) discussion forum category.
- If your code is intended *primarily* as an example or to show a concept/principle rather than a working system, consider if it may be better to instead [contribute to the documentation](../Contributing-Docs.md) by writing a new tutorial or howto.
- If possible, try to make your contribution as genre-agnostic as possible and assume
your code will be applied to a very different game than you had in mind when creating it.
- The contribution should preferably work in isolation from other contribs (only make use of core Evennia) so it can easily be dropped into use. If it does depend on other contribs or third-party modules, these must be clearly documented and part of the installation instructions.
- If you are unsure about if your contrib idea is suitable or sound, *ask in discussions or chat before putting any work into it*. We are, for example, unlikely to accept contribs that require large modifications of the game directory structure.
## Layout of a contrib
- The contrib must be contained only within a single folder under one of the contrib categories below. Ask if you are unsure which category fits best for your contrib.
| | |
| --- | --- |
| `base_systems/` | _Systems that are not necessarily tied to a specific in-game mechanic but which are useful for the game as a whole. Examples include login systems, new command syntaxes, and build helpers._ |
| `full_systems/` | _‘Complete’ game engines that can be used directly to start creating content without no further additions (unless you want to)._ |
| `game_systems/` | _In-game gameplay systems like crafting, mail, combat and more. Each system is meant to be adopted piecemeal and adopted for your game. This does not include roleplaying-specific systems, those are found in the `rpg` category._ |
| `grid/` | _Systems related to the game world’s topology and structure. Contribs related to rooms, exits and map building._ |
| `rpg/` | _Systems specifically related to roleplaying and rule implementation like character traits, dice rolling and emoting._ |
| `tutorials/` | _Helper resources specifically meant to teach a development concept or to exemplify an Evennia system. Any extra resources tied to documentation tutorials are found here. Also the home of the Tutorial-World and Evadventure demo codes._ |
| `tools/` | _Miscellaneous tools for manipulating text, security auditing, and more._|
- The folder (package) should be on the following form:
```
evennia/
contrib/
category/ # rpg/, game_systems/ etc
mycontribname/
__init__.py
README.md
module1.py
module2.py
...
tests.py
```
It's often a good idea to import useful resources in `__init__.py` to make it easier to import them.
- Your code should abide by the [Evennia Style Guide](../Coding/Evennia-Code-Style.md). Write it to be easy to read.
- Your contribution _must_ be covered by [unit tests](../Coding/Unit-Testing.md). Put your tests in a module `tests.py` under your contrib folder (as seen above) - Evennia will find them automatically.
- The `README.md` file will be parsed and converted into a document linked from [the contrib overview page](./Contribs-Overview.md). It needs to be on the following form:
```markdown
# MyContribName
Contribution by <yourname>, <year>
A paragraph (can be multi-line)
summarizing the contrib (required)
Optional other text
## Installation
Detailed installation instructions for using the contrib (required)
## Usage
## Examples
etc.
```
> The credit and first paragraph-summary will be automatically included on the Contrib overview page index for each contribution, so it needs to be just on this form.
## Submitting a contrib
```{sidebar} Not all PRs can be accepted
While most PRs get merged, this is not guaranteed: Merging a contrib means the Evennia project takes on the responsibility of maintaining and supporting the new code. For various reasons this may be deemed unfeasible.
If your code were to *not* be accepted for some reason, we can still link it from our links page; it can also be posted in our discussion forum.
```
- A contrib must always be presented [as a pull request](../Coding/Version-Control.md#contributing-to-evennia) (PR).
- PRs are reviewed so don't be surprised (or disheartened) if you are asked to modify or change your code before it can be merged. Your code can end up going through several iterations before it is accepted.
- To make the licensing situation clear we assume all contributions are released with the same [license as Evennia](../Licensing.md). If this is not possible for some reason, talk to us and we'll handle it on a case-by-case basis.

37
docs/1.0-dev/_sources/Contribs/Contribs-Overview.md.txt
View file

@ -18,7 +18,7 @@ Each contrib contains installation instructions for how to integrate it
with your other code. If you want to tweak the code of a contrib, just
copy its entire folder to your game directory and modify/use it from there.
If you want to contribute yourself, see [here](../Contributing.md)!
If you want to add a contrib, see [the contrib guidelines](./Contribs-Guidelines.md)!
[forum]: https://github.com/evennia/evennia/discussions/categories/community-contribs-snippets
@ -48,6 +48,11 @@ _Systems that are not necessarily tied to a specific
in-game mechanic but which are useful for the game as a whole. Examples include
login systems, new command syntaxes, and build helpers._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -204,6 +209,11 @@ library under the hood.
_'Complete' game engines that can be used directly to start creating content
without no further additions (unless you want to)._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -235,6 +245,11 @@ Each system is meant to be adopted piecemeal and adopted for your game.
This does not include roleplaying-specific systems, those are found in
the `rpg` category._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -382,6 +397,11 @@ the participants until the fight ends.
_Systems related to the game world's topology and structure. Contribs related
to rooms, exits and map building._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -492,6 +512,11 @@ current location (useful for displaying the grid as an in-game, updating map).
_Systems specifically related to roleplaying
and rule implementation like character traits, dice rolling and emoting._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -593,6 +618,11 @@ to exemplify an Evennia system. Any extra resources tied to documentation
tutorials are found here. Also the home of the Tutorial-World and Evadventure
demo codes._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1
@ -699,6 +729,11 @@ is a great way to start learning the system.
_Miscellaneous, tools for manipulating text, security auditing, and more._
```{toctree}
:hidden:
Contribs-Guidelines.md
```
```{toctree}
:maxdepth: 1

177
docs/1.0-dev/_sources/Contributing.md.txt
View file

@ -1,173 +1,40 @@
# How To Contribute And Get Help
If you cannot find what you are looking for in the documentation, here's what to do:
## Getting Help
- If you need help, want to start a discussion or get some input on something
you are working on, make a post to the [discussions forum][forum].
- If you want more direct discussions with developers and other users, drop
into our very friendly [Discord channel][chat].
- If you think the documentation is not clear enough, create a [documentation issue][issues].
- If you have trouble with a missing feature or a problem you think is a bug,
[request, or report it][issues].
If you cannot find what you are looking for in the documentation, here's where to go next:
## Community and Spreading the word
- [The Discussions forums][forum] are great for getting help, starting longer-form discussions, showing off your work or get some input on what you are working on. This is also the place to follow Evennia development.
- [The Discord server][chat] has a very helpful `#getting-help` channel for both big and small Evennia problems. It allows for more direct discussion. You can also track both the evennia code changes and the discussion forum from discord.
Being active and helpful in the [discssion forums][forum] or [chat][chat] is already a big help.
## Giving Help
Consider writing about Evennia on your blog or in your favorite (relevant)
forum. Write a review somewhere (good or bad, we like feedback either way). Rate
it on listings. Talk about it to your friends ... that kind of thing.
In general, being active and helpful in the [discssion forums][forum] or [discord chat][chat] is already a big help!
## Help with Documentation
If you want to spread the word, consider writing about Evennia on your blog or in your favorite (relevant) forum. Write a review somewhere (good or bad, we like feedback either way). Rate it on listings. Talk about it to your friends ... that kind of thing.
Evennia depends heavily on good documentation and we are always looking for
extra eyes and hands to improve it. Even small things such as fixing typos are a
great help!
### Help with Documentation
- Easiest is to just [report documentation issues][issues] as you find them. If
we don't know about them, we can't fix them!
- If you want to help editing the docs directly, [check here](./Contributing-Docs.md) on how to do it.
- If you have knowledge to share, how about writing a new [Tutorial](Howtos/Howtos-Overview.md)?
Evennia is highly dependent on good-quality documentation!
## Helping with code
- [Reporting a Documentation issue][issues] is the easiest way to help out. The more eyes we get on things, the better - if we don't know about the problems, we can't fix them! Even reporting typos is a great help.
- [Contributing directly to the docs](./Contributing-Docs.md) is also possible; you just need a text editor. You can fix issues or even propose a new tutorial!
If you find bugs, or have a feature-request, [make an issue][issues] for it. If
it's not in an issue, the issue will most likely be forgotten.
### Helping with code
Even if you don't feel confident with tackling a bug or feature, just
correcting typos, adjusting formatting or simply *using* the thing and reporting
when stuff doesn't make sense helps us a lot.
Even if you don't feel confident with tackling a bug or feature, just correcting typos, adjusting formatting or simply *using* the thing and reporting when stuff doesn't make sense helps us a lot!
- The code itself should follow Evennia's [Code style guidelines][codestyle] both
for code and documentation. You should write code for that others can read an understand.
- Before merging, your code will be reviewed. Merging of your code into Evennia
is not guaranteed. Be ready to receive feedback and to be asked to make
corrections or fix bugs or any documentation issues and possibly tests (this
is normal and nothing to worry about).
- [Reporting a code issue or bug][issues] is the easiest way to help out. Don't assume we are aware of a problem - if it's not written down in an issue, the problem will most likely be forgotten. Do this even if you plan to make a _Pull Request_ and fix the issue yourself.
- [Make a feature request][issues] if you want to see a new Evennia feature. You can also bring it up with the community first so you are sure it's something that would be interesting to be included with Evennia core.
- [Make a Pull Request](Coding/Version-Control.md#contributing-to-evennia) (PR) to fix bugs or new features. Make sure to follow the [Evennia Code-Style guide](Coding/Evennia-Code-Style.md).
- [The Guide for making an Evennia contrib](Contribs/Contribs-Guidelines.md) outlines how you do to make your own Evennia [contrib](Contribs/Contribs-Overview.md) to distribute with Evennia.
### Using a Forked reposity
### Helping with Donations
The most elegant way to contribute code to Evennia is to use GitHub to create a
*fork* of the Evennia repository and make your changes to that. Refer to the
[Forking Evennia](Coding/Version-Control.md#forking-evennia) version control instructions for detailed instructions.
Evennia is a free and open-source project. Any monetary donations you want to offer are _completely voluntary_. While highly appreciated, we don't expect you to donate and don't hide any secret features behind a donation-paywall. Just see it as a way of showing appreciation by dropping a few coins in the cup.
Once you have a fork set up, you can not only work on your own game in a
separate branch, you can also commit your fixes to Evennia itself.
- Make separate branches for all Evennia additions you do - don't edit your
local `master` or `develop` branches directly. It will make your life a lot easier.
- If you have a change that you think is suitable for the main Evennia
repository, issue a [Pull Request][pullrequest]. This will let Evennia devs know you have stuff to share.
- Bug fixes should generally be done against the `master` branch of Evennia,
while new features/contribs should go into the `develop` branch. If you are
unsure, just pick one and we'll figure it out.
### Contributing with Patches
To help with Evennia development it's strongly recommended to do so using a
forked repository as described above. But for small, well isolated fixes you are
also welcome to submit your suggested Evennia fixes/addendums as a
[patch][patch].
You can include your patch in an Issue or a Mailing list post. Please avoid
pasting the full patch text directly in your post though, best is to use a site
like [Pastebin](https://pastebin.com/) and just supply the link.
### Making an Evennia contrib
Evennia has a [contrib](Contribs/Contribs-Overview.md) directory which contains
user-shared code organized by category. You can contribute anything that you
think may be useful to another dev, also highly game-specific code. A contrib
must always be added via a forked repository.
#### Guidelines for making a contrib
- If you are unsure about if your contrib idea is suitable or sound, *ask in
discussions or chat before putting any work into it*. We are, for example,
unlikely to accept contribs that require large modifications of the game
directory structure.
- If your code is intended *primarily* as an example or to show a
concept/principle rather than a working system, you _can_ add to the
`contribs/tutorials/` subfolder, but consider if it may be better to instead
write a new tutorial doc page.
- The contribution should preferably work in isolation from other contribs (only
make use of core Evennia) so it can easily be dropped into use. If it does
depend on other contribs or third-party modules, these must be clearly
documented and part of the installation instructions.
- The contrib must be contained within a separate folder under one of the
contrib categories (`game_systems`, `rpg`, `utils` etc). Ask if you are
unsure which category to put your contrib under.
- The folder (package) should be on the following form:
```
mycontribname/
__init__.py
README.md
module1.py
module2.py
...
tests.py
```
It's often a good idea to import useful resources in `__init__.py` to make
it easier to access them (this may vary though).
The `README.md` will be parsed and converted into a document linked from
[the contrib overview page](Contribs/Contribs-Overview.md). It should follow
the following structure:
```markdown
# MyContribName
Contribution by <yourname>, <year>
A paragraph (can be multi-line)
summarizing the contrib (required)
Optional other text
## Installation
Detailed installation instructions for using the contrib (required)
## Usage
## Examples
etc.
```
The credit and first paragraph-summary will be used on the index page. Every
contrib's readme must contain an installation instruction. See existing contribs
for help.
- If possible, try to make contribution as genre-agnostic as possible and assume
your code will be applied to a very different game than you had in mind when creating it.
- To make the licensing situation clear we assume all contributions are released
with the same [license as Evennia](./Licensing.md). If this is not possible
for some reason, talk to us and we'll handle it on a case-by-case basis.
- Your contribution must be covered by [unit tests](Coding/Unit-Testing.md). Put
your tests in a module `tests.py` under your contrib folder - Evennia will
find them automatically.
- In addition to the normal review process, it's worth noting that merging a
contrib means the Evennia project takes on the responsibility of maintaining
and supporting it. For various reasons this may be deemed beyond our manpower.
- If your code were to *not* be accepted for some reason, you can ask us to
instead link to your repo from our link page so people can find your code that
way.
## Donations
Evennia is a free, open-source project and any monetary donations you want to
offer are _completely voluntary_. See it as a way of showing appreciation by
dropping a few coins in the cup.
- You can support Evennia as an [Evennia patreon][patron]. A patreon donates a
(usually small) sum every month to show continued support.
- If a monthly donation is not your thing, you can also show your appreciation
by doing a [one-time donation][donate] (this is a PayPal link but you don't need
PayPal yourself to use it).
- [Become an Evennia patron][patron] which donates a (usually small) sum every month to show continued support.
- [Make a one-time donation][paypal] if a monthly donation is not your thing. This is a PayPal link but you don't need PayPal yourself to use it.
[patron]: https://www.patreon.com/griatch
@ -181,7 +48,7 @@ dropping a few coins in the cup.
[forum]:https://github.com/evennia/evennia/discussions
[issues]:https://github.com/evennia/evennia/issues/choose
[chat]: https://discord.com/invite/AJJpcRUhtF
[paypal]: https://www.paypal.com/se/cgi-bin/webscr?cmd=_flow&SESSION=Z-VlOvfGjYq2qvCDOUGpb6C8Due7skT0qOklQEy5EbaD1f0eyEQaYlmCc8O&dispatch=5885d80a13c0db1f8e263663d3faee8d64ad11bbf4d2a5a1a0d303a50933f9b2
[paypal]: https://www.paypal.com/paypalme/GriatchEvennia
[patreon]: https://www.patreon.com/griatch
[issues-bounties]:https://github.com/evennia/evennia/labels/bounty
[bountysource]: https://www.bountysource.com/teams/evennia

2
docs/1.0-dev/_sources/Glossary.md.txt
View file

@ -185,7 +185,7 @@ latest changes, just `cd` into your game dir and run
evennia migrate
That should be it (see [virtualenv](./Glossary.md#virtualenv) if you get a warning that the `evennia`
command is not available). See also [Updating your game](Coding/Updating-Your-Game.md) for more details.
command is not available). See also [Updating your game](Setup/Updating-Evennia.md) for more details.
> Technically, migrations are shipped as little Python snippets of code that explains which database
actions must be taken to upgrade from one version of the schema to the next. When you run the

131
docs/1.0-dev/_sources/Setup/Choosing-a-Database.md.txt
View file

@ -10,13 +10,11 @@ This page gives an overview of the supported SQL databases as well as instructio
Since Evennia uses [Django](https://djangoproject.com), most of our notes are based off of what we know from the community and their documentation. While the information below may be useful, you can always find the most up-to-date and "correct" information at Django's [Notes about supported
Databases](https://docs.djangoproject.com/en/dev/ref/databases/#ref-databases) page.
## SQLite3
## SQLite3 (default)
[SQLite3](https://sqlite.org/) is a light weight single-file database. It is our default database
and Evennia will set this up for you automatically if you give no other options. SQLite stores the
database in a single file (`mygame/server/evennia.db3`). This means it's very easy to reset this
database - just delete (or move) that `evennia.db3` file and run `evennia migrate` again! No server process is needed and the administrative overhead and resource consumption is tiny. It is also very fast since it's run in-memory. For the vast majority of Evennia installs it will probably be all
that's ever needed.
[SQLite3](https://sqlite.org/) is a light weight single-file database. It is our default database and Evennia will set this up for you automatically if you give no other options.
SQLite stores the database in a single file (`mygame/server/evennia.db3`). This means it's very easy to reset this database - just delete (or move) that `evennia.db3` file and run `evennia migrate` again! No server process is needed and the administrative overhead and resource consumption is tiny. It is also very fast since it's run in-memory. For the vast majority of Evennia installs it will probably be all that's ever needed.
SQLite will generally be much faster than MySQL/PostgreSQL but its performance comes with two
drawbacks:
@ -44,13 +42,9 @@ To inspect the default Evennia database (once it's been created), go to your gam
This will bring you into the sqlite command line. Use `.help` for instructions and `.quit` to exit.
See [here](https://gist.github.com/vincent178/10889334) for a cheat-sheet of commands.
### Resetting SQLite3 database
### Resetting SQLite3
To reset your database and start from scratch, simply stop Evennia and delete the `mygame/server/evennia.db3`. Then run `evennia migrate` again.
```{sidebar} Hint
Make a copy of the `evennia.db3` file once you created your superuser. When you want to reset, you can just stop evennia and copy that file back over `evennia.db3`. That way you don't have to run migrations and create the superuser every time!
```
If you want to reset your SQLite3 database, see [here](./Updating-Evennia.md#sqlite3-default).
## PostgreSQL
@ -60,14 +54,10 @@ game has an very large database and/or extensive web presence through a separate
### Install and initial setup of PostgreSQL
First, install the posgresql server. Version `9.6` is tested with Evennia. Packages are readily
available for all distributions. You need to also get the `psql` client (this is called `postgresql-
client` on debian-derived systems). Windows/Mac users can [find what they need on the postgresql
download page](https://www.postgresql.org/download/). You should be setting up a password for your
database-superuser (always called `postgres`) when you install.
First, install the posgresql server. Version `9.6` is tested with Evennia. Packages are readily available for all distributions. You need to also get the `psql` client (this is called `postgresql- client` on debian-derived systems). Windows/Mac users can [find what they need on the postgresql download page](https://www.postgresql.org/download/). You should be setting up a password for your database-superuser (always called `postgres`) when you install.
For interaction with Evennia you need to also install `psycopg2` to your Evennia install (`pip
install psycopg2-binary` in your virtualenv). This acts as the python bridge to the database server.
For interaction with Evennia you need to also install `psycopg2` to your Evennia install
(`pip install psycopg2-binary` in your virtualenv). This acts as the python bridge to the database server.
Next, start the postgres client:
@ -104,12 +94,7 @@ GRANT ALL PRIVILEGES ON DATABASE evennia TO evennia;
```
[Here](https://gist.github.com/Kartones/dd3ff5ec5ea238d4c546) is a cheat-sheet for psql commands.
We create a database user 'evennia' and a new database named `evennia` (you can call them whatever
you want though). We then grant the 'evennia' user full privileges to the new database so it can
read/write etc to it.
If you in the future wanted to completely wipe the database, an easy way to do is to log in as the
`postgres` superuser again, then do `DROP DATABASE evennia;`, then `CREATE` and `GRANT` steps above
again to recreate the database and grant privileges.
We create a database user 'evennia' and a new database named `evennia` (you can call them whatever you want though). We then grant the 'evennia' user full privileges to the new database so it can read/write etc to it. If you in the future wanted to completely wipe the database, an easy way to do is to log in as the `postgres` superuser again, then do `DROP DATABASE evennia;`, then `CREATE` and `GRANT` steps above again to recreate the database and grant privileges.
### Evennia PostgreSQL configuration
@ -134,8 +119,7 @@ If you used some other name for the database and user, enter those instead. Run
evennia migrate
to populate your database. Should you ever want to inspect the database directly you can from now on
also use
to populate your database. Should you ever want to inspect the database directly you can from now on also use
evennia dbshell
@ -144,7 +128,11 @@ as a shortcut to get into the postgres command line for the right database and u
With the database setup you should now be able to start start Evennia normally with your new
database.
### Advanced Postgresql Usage (Remote Server)
### Resetting PostgreSQL
If you want to reset your PostgreSQL datbase, see [here](./Updating-Evennia.md#postgresql)
### Advanced PostgreSQL Usage (Remote Server)
```{warning}
@ -153,18 +141,9 @@ database.
an Internet-accessible server.
```
The above discussion is for hosting a local server. In certain configurations
it may make sense host the database on a server remote to the one Evennia is
running on. One example case is where code development may be done on multiple
machines by multiple users. In this configuration, a local data base (such as
SQLite3) is not feasible since all the machines and developers do not have
access to the file.
The above discussion is for hosting a local server. In certain configurations it may make sense host the database on a server remote to the one Evennia is running on. One example case is where code development may be done on multiple machines by multiple users. In this configuration, a local data base (such as SQLite3) is not feasible since all the machines and developers do not have access to the file.
Choose a remote machine to host the database and PostgreSQl server. Follow the
instructions [above](#install-and-initial-setup-of-postgresql) on that server to set up the database.
Depending on distribution, PostgreSQL will only accept connections on the local
machine (localhost). In order to enable remote access, two files need to be
changed.
Choose a remote machine to host the database and PostgreSQl server. Follow the instructions [above](#install-and-initial-setup-of-postgresql) on that server to set up the database. Depending on distribution, PostgreSQL will only accept connections on the local machine (localhost). In order to enable remote access, two files need to be changed.
First, determine which cluster is running your database. Use `pg_lscluster`:
@ -174,10 +153,7 @@ Ver Cluster Port Status Owner Data directory Log file
12 main 5432 online postgres /var/lib/postgresql/12/main /var/log/postgresql/postgresql-12-main.log
```
Next, edit the database's `postgresql.conf`. This is found on Ubuntu systems
in `/etc/postgresql/<ver>/<cluster>`, where `<ver>` and `<cluster>` are
what are reported in the `pg_lscluster` output. So, for the above example,
the file is `/etc/postgresql/12/main/postgresql.conf`.
Next, edit the database's `postgresql.conf`. This is found on Ubuntu systems in `/etc/postgresql/<ver>/<cluster>`, where `<ver>` and `<cluster>` are what are reported in the `pg_lscluster` output. So, for the above example, the file is `/etc/postgresql/12/main/postgresql.conf`.
In this file, look for the line with `listen_addresses`. For example:
@ -205,8 +181,7 @@ on any interface.
for more details.)
```
Finally, modify the `pg_hba.conf` (in the same directory as `postgresql.conf`).
Look for a line with:
Finally, modify the `pg_hba.conf` (in the same directory as `postgresql.conf`). Look for a line with:
```
# IPv4 local connections:
host all all 127.0.0.1/32 md5
@ -226,31 +201,19 @@ Now, restart your cluster:
$ pg_ctlcluster 12 main restart
```
Finally, update the database settings in your Evennia secret_settings.py (as
described [above](#evennia-postgresql-configuration) modifying `SERVER` and
`PORT` to match your server.
Finally, update the database settings in your Evennia secret_settings.py (as described [above](#evennia-postgresql-configuration) modifying `SERVER` and `PORT` to match your server.
Now your Evennia installation should be able to connect and talk with a remote
server.
Now your Evennia installation should be able to connect and talk with a remote server.
## MySQL / MariaDB
[MySQL](https://www.mysql.com/) is a commonly used proprietary database system, on par with
PostgreSQL. There is an open-source alternative called [MariaDB](https://mariadb.org/) that mimics
all functionality and command syntax of the former. So this section covers both.
[MySQL](https://www.mysql.com/) is a commonly used proprietary database system, on par with PostgreSQL. There is an open-source alternative called [MariaDB](https://mariadb.org/) that mimics all functionality and command syntax of the former. So this section covers both.
### Installing and initial setup of MySQL/MariaDB
First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the
`mysql-server` or `mariadb-server` packages for their respective distributions. Windows/Mac users
will find what they need from the [MySQL downloads](https://www.mysql.com/downloads/) or [MariaDB
downloads](https://mariadb.org/download/) pages. You also need the respective database clients
(`mysql`, `mariadb-client`), so you can setup the database itself. When you install the server you
should usually be asked to set up the database root user and password.
First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the `mysql-server` or `mariadb-server` packages for their respective distributions. Windows/Mac users will find what they need from the [MySQL downloads](https://www.mysql.com/downloads/) or [MariaDB downloads](https://mariadb.org/download/) pages. You also need the respective database clients (`mysql`, `mariadb-client`), so you can setup the database itself. When you install the server you should usually be asked to set up the database root user and password.
You will finally also need a Python interface to allow Evennia to talk to the database. Django
recommends the `mysqlclient` one. Install this into the evennia virtualenv with `pip install
mysqlclient`.
You will finally also need a Python interface to allow Evennia to talk to the database. Django recommends the `mysqlclient` one. Install this into the evennia virtualenv with `pip install mysqlclient`.
Start the database client (this is named the same for both mysql and mariadb):
@ -274,27 +237,15 @@ FLUSH PRIVILEGES;
```
[Here](https://gist.github.com/hofmannsven/9164408) is a mysql command cheat sheet.
Above we created a new local user and database (we called both 'evennia' here, you can name them
what you prefer). We set the character set to `utf8` to avoid an issue with prefix character length
that can pop up on some installs otherwise. Next we grant the 'evennia' user all privileges on the
`evennia` database and make sure the privileges are applied. Exiting the client brings us back to
the normal terminal/console.
Above we created a new local user and database (we called both 'evennia' here, you can name them what you prefer). We set the character set to `utf8` to avoid an issue with prefix character length that can pop up on some installs otherwise. Next we grant the 'evennia' user all privileges on the `evennia` database and make sure the privileges are applied. Exiting the client brings us back to the normal terminal/console.
> Note: If you are not using MySQL for anything else you might consider granting the 'evennia' user
full privileges with `GRANT ALL PRIVILEGES ON *.* TO 'evennia'@'localhost';`. If you do, it means
you can use `evennia dbshell` later to connect to mysql, drop your database and re-create it as a
way of easy reset. Without this extra privilege you will be able to drop the database but not re-
create it without first switching to the database-root user.
> If you are not using MySQL for anything else you might consider granting the 'evennia' user full privileges with `GRANT ALL PRIVILEGES ON *.* TO 'evennia'@'localhost';`. If you do, it means you can use `evennia dbshell` later to connect to mysql, drop your database and re-create it as a way of easy reset. Without this extra privilege you will be able to drop the database but not re create it without first switching to the database-root user.
## Add MySQL configuration to Evennia
### Add MySQL/MariaDB configuration to Evennia
To tell Evennia to use your new database you need to edit `mygame/server/conf/settings.py` (or
`secret_settings.py` if you don't want your db info passed around on git repositories).
To tell Evennia to use your new database you need to edit `mygame/server/conf/settings.py` (or `secret_settings.py` if you don't want your db info passed around on git repositories).
> Note: The Django documentation suggests using an external `db.cnf` or other external conf-
formatted file. Evennia users have however found that this leads to problems (see e.g. [issue
#1184](https://git.io/vQdiN)). To avoid trouble we recommend you simply put the configuration in
your settings as below.
> The Django documentation suggests using an external `db.cnf` or other external conf- formatted file. Evennia users have however found that this leads to problems (see e.g. [issue #1184](https://git.io/vQdiN)). To avoid trouble we recommend you simply put the configuration in your settings as below.
```python
#
@ -311,22 +262,24 @@ your settings as below.
}
}
```
The `mysql` backend is used by `MariaDB` as well.
Change this to fit your database setup. Next, run:
evennia migrate
to populate your database. Should you ever want to inspect the database directly you can from now on
also use
to populate your database. Should you ever want to inspect the database directly you can from now on also use
evennia dbshell
as a shortcut to get into the postgres command line for the right database and user.
With the database setup you should now be able to start start Evennia normally with your new
database.
With the database setup you should now be able to start start Evennia normally with your new database.
## Others
### Resetting MySQL/MariaDB
No testing has been performed with Oracle, but it is also supported through Django. There are
community maintained drivers for [MS SQL](https://code.google.com/p/django-mssql/) and possibly a few
others. If you try other databases out, consider expanding this page with instructions.
If you want to reset your MySQL/MariaDB datbase, see [here](./Updating-Evennia.md#mysql-mariadb).
## Other databases
No testing has been performed with Oracle, but it is also supported through Django. There are community maintained drivers for [MS SQL](https://code.google.com/p/django-mssql/) and possibly a few others. If you try other databases out, consider contributing to this page with instructions.

10
docs/1.0-dev/_sources/Setup/Installation.md.txt
View file

@ -4,12 +4,15 @@
If you are converting an existing game from a previous Evennia version, [see here](./Installation-Upgrade.md).
```
The fastest way to install Evennia is to use the `pip` installer that comes with Python (read on).
You can also [clone Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md). Some users have also experimented with [installing Evennia on Android](./Installation-Android.md).
## Requirements
```{sidebar} Develop in isolation
Installing Evennia doesn't make anything visible online. Apart from installation and updating, you can develop your game without any internet connection if you want to.
```
- Evennia requires [Python](https://www.python.org/downloads/) 3.9, 3.10 or 3.11 (recommended)
- Evennia requires [Python](https://www.python.org/downloads/) 3.9, 3.10 or 3.11 (recommended). Any OS that supports Python should work.
- Windows: In the installer, make sure you select `add python to path`. If you have multiple versions of Python installed, use `py` command instead of `python` to have Windows automatically use the latest.
- Using a light-weight [Python virtual environment](./Installation-Git.md#virtualenv) is optional, but _highly recommended_ in order to keep your Evennia installation independent from the system libraries. Using virtualenvs like this is common Python praxis.
- Don't install Evennia as administrator or superuser.
@ -17,9 +20,6 @@ Installing Evennia doesn't make anything visible online. Apart from installation
## Install with `pip`
The fastest way to install Evennia is to use the `pip` installer that comes with Python.
You can also [clone Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md). Some users have also experimented with [installing Evennia on Android](./Installation-Android.md).
Evennia is managed from the terminal (console/Command Prompt on Windows). Once you have Python, you install Evennia with
@ -87,7 +87,7 @@ Full stop of the server (use `evennia start` to restart):
evennia stop
See [Server start-stop-reload](./Start-Stop-Reload.md) page for more details.
See [Server start-stop-reload](./Running-Evennia.md) page for more details.
## See server logs

0
docs/1.0-dev/_sources/Setup/Start-Stop-Reload.md.txt → docs/1.0-dev/_sources/Setup/Running-Evennia.md.txt
View file

5
docs/1.0-dev/_sources/Setup/Setup-Overview.md.txt
View file

@ -14,7 +14,8 @@ Installation-Troubleshooting
Installation-Android
Installation-Upgrade
Installation-Non-Interactive
Start-Stop-Reload
Running-Evennia
Updating-Evennia
```
## Configuration
@ -31,7 +32,7 @@ Channels-to-RSS
Channels-to-Twitter
```
## Going public
## Going Online
```{toctree}
:maxdepth: 2

94
docs/1.0-dev/_sources/Setup/Updating-Evennia.md.txt Normal file
View file

@ -0,0 +1,94 @@
# Updating Evennia
When Evennia is updated to a new version you will usually see it announced in the [Discussion forum](github:discussions) and in the [dev blog](https://www.evennia.com/devblog/index.html). You can also see the changes on [github](github:) or through one of our other [linked pages](../Links.md).
## If you installed with `pip`
If you followed the [normal install instructions](./Installation.md), here's what you do to upgrade:
1. Read the [changelog](../Coding/Changelog.md) to see what changed and if it means you need to make any changes to your game code.
2. If you use a [virtualenv](#Installation-Git#virtualenv), make sure it's active.
3. `cd` to your game dir (e.g. `mygame`)
4. `evennia stop`
5. `pip install --upgrade evennia`
6. `cd` tor your game dir
7. `evennia migrate` (_ignore_ any warnings about running `makemigrations`, it should _not_ be done)
8. `evennia start`
If the upstream changes are large, you may also need to go into your gamedoor
## If you installed with `git`
This applies if you followed the [git-install instructions](./Installation-Git.md). Before Evennia 1.0, this was the only way to install Evennia.
At any time, development is either happening in the `master` branch (latest stable) or `develop` (experimental). Which one is active and 'latest' at a given time depends - after a release, `master` will see most updates, close to a new release, `develop` will usually be the fastest changing.
1. Read the [changelog](../Coding/Changelog.md) to see what changed and if it means you need to make any changes to your game code.
2. If you use a [virtualenv](#Installation-Git#virtualenv), make sure it's active.
3. `cd` to your game dir (e.g. `mygame`)
4. `evennia stop`
5. `cd` to the `evennia` repo folder you cloned during the git installation process.
6. `git pull`
7. `pip install --upgrade -e .` (remember the `.` at the end!)
9. `cd` back to your game dir
10. `evennia migrate` (_ignore_ any warnings about running `makemigrations` , it should _not_ be done)
11. `evennia start`
## If you installed with `docker`
If you followed the [docker installation instructions] you need to pull the latest docker image for the branch you want:
- `docker pull evennia/evennia` (master branch)
- `docker pull evennia/evennia:develop` (experimental `develop` branch)
Then restart your containers.
## Resetting your database
Should you ever want to start over completely from scratch, there is no need to re-download Evennia. You just need to clear your database.
First:
1. `cd` to your game dir (e.g. `mygame`)
2. `evennia stop`
### SQLite3 (default)
```{sidebar} Hint
Make a copy of the `evennia.db3` file once you created your superuser. When you want to reset (and as long as you haven't had to run any new migrations), you can just stop evennia and copy that file back over `evennia.db3`. That way you don't have to run the same migrations and create the superuser every time!
```
3. delete the file `mygame/server/evennia.db3`
4. `evennia migrate`
5. `evennia start`
### PostgreSQL
3. `evennia dbshell` (opens the psql client interface)
```
psql> DROP DATABASE evennia;
psql> exit
```
4. You should now follow the [PostgreSQL install instructions](./Choosing-a-Database.md#postgresql) to create a new evennia database.
5. `evennia migrate`
6. `evennia start`
### MySQL/MariaDB
3. `evennia dbshell` (opens the mysql client interface)
```
mysql> DROP DATABASE evennia;
mysql> exit
```
4. You should now follow the [MySQL install instructions](./Choosing-a-Database.md#mysql-mariadb) to create a new evennia database.
5. `evennia migrate`
6. `evennia start`
### What are database migrations?
If and when an Evennia update modifies the database *schema* (that is, the under-the-hood details as to how data is stored in the database), you must update your existing database correspondingly to match the change. If you don't, the updated Evennia will complain that it cannot read the database properly. Whereas schema changes should become more and more rare as Evennia matures, it may still happen from time to time.
One way one could handle this is to apply the changes manually to your database using the database's command line. This often means adding/removing new tables or fields as well as possibly convert existing data to match what the new Evennia version expects. It should be quite obvious that this quickly becomes cumbersome and error-prone. If your database doesn't contain anything critical yet it's probably easiest to simply reset it and start over rather than to bother converting.
Enter *migrations*. Migrations keeps track of changes in the database schema and applies them automatically for you. Basically, whenever the schema changes we distribute small files called "migrations" with the source. Those tell the system exactly how to implement the change so you don't have to do so manually. When a migration has been added we will tell you so on Evennia's mailing lists and in commit messages - you then just run `evennia migrate` to be up-to-date again.

14
docs/1.0-dev/_sources/index.md.txt
View file

@ -13,14 +13,15 @@
This is the manual of [Evennia](https://www.evennia.com), the open source Python `MU*` creation system. Use the Search bar on the left to find or discover interesting articles.
- [Introduction](./Evennia-Introduction.md) - what is this Evennia thing?
- [Getting help and Contribute](./Contributing.md) - when you get stuck or want to chip in
- [Contributing and Getting help](./Contributing.md) - when you get stuck or want to chip in
## Setup
- [Setup Quickstart](Setup/Setup-Overview.md#installation-and-running) - installing Evennia and get going
- [Starting, Stopping and Reloading](Setup/Start-Stop-Reload.md) - how to manage the Evennia server
- [Configuration](Setup/Setup-Overview.md#configuration) - how to set up your server the way you like it
- [Going public](Setup/Setup-Overview.md#going-public) - taking your game online
- [Installation](Setup/Setup-Overview.md#installation-and-running) - getting started
- [Running the Game](Setup/Running-Evennia.md) - how to start, stop and reload Evennia
- [Updating the Server](Setup/Updating-Evennia.md) - how to update Evennia
- [Configuration](Setup/Setup-Overview.md#configuration) - how to set up Evennia the way you like it
- [Going Online](Setup/Setup-Overview.md#going-online) - bringing your game online
## Tutorials and Howtos
@ -55,7 +56,10 @@ This is the manual of [Evennia](https://www.evennia.com), the open source Python
:maxdepth: 3
Evennia-Introduction
Setup/Running-Evennia
Setup/Updating-Evennia
Setup/Setup-Overview
Howtos/Howtos-Overview
Components/Components-Overview
Concepts/Concepts-Overview

BIN
docs/1.0-dev/_static/images/fork_button.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 3 KiB

4
docs/1.0-dev/api/evennia.commands.default.account.html
View file

@ -133,7 +133,7 @@ method. Otherwise all text will be returned to all connected sessions.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.account.CmdOOCLook.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['ls', 'l']</em><a class="headerlink" href="#evennia.commands.default.account.CmdOOCLook.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['l', 'ls']</em><a class="headerlink" href="#evennia.commands.default.account.CmdOOCLook.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -164,7 +164,7 @@ method. Otherwise all text will be returned to all connected sessions.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.account.CmdOOCLook.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'ls l', 'category': 'general', 'key': 'look', 'no_prefix': ' ls l', 'tags': '', 'text': '\n look while out-of-character\n\n Usage:\n look\n\n Look in the ooc state.\n '}</em><a class="headerlink" href="#evennia.commands.default.account.CmdOOCLook.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'l ls', 'category': 'general', 'key': 'look', 'no_prefix': ' l ls', 'tags': '', 'text': '\n look while out-of-character\n\n Usage:\n look\n\n Look in the ooc state.\n '}</em><a class="headerlink" href="#evennia.commands.default.account.CmdOOCLook.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

4
docs/1.0-dev/api/evennia.commands.default.admin.html
View file

@ -317,7 +317,7 @@ to accounts respectively.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.admin.CmdEmit.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['remit', 'pemit']</em><a class="headerlink" href="#evennia.commands.default.admin.CmdEmit.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['pemit', 'remit']</em><a class="headerlink" href="#evennia.commands.default.admin.CmdEmit.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -348,7 +348,7 @@ to accounts respectively.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.admin.CmdEmit.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'remit pemit', 'category': 'admin', 'key': 'emit', 'no_prefix': ' remit pemit', 'tags': '', 'text': '\n admin command for emitting message to multiple objects\n\n Usage:\n emit[/switches] [&lt;obj&gt;, &lt;obj&gt;, ... =] &lt;message&gt;\n remit [&lt;obj&gt;, &lt;obj&gt;, ... =] &lt;message&gt;\n pemit [&lt;obj&gt;, &lt;obj&gt;, ... =] &lt;message&gt;\n\n Switches:\n room - limit emits to rooms only (default)\n accounts - limit emits to accounts only\n contents - send to the contents of matched objects too\n\n Emits a message to the selected objects or to\n your immediate surroundings. If the object is a room,\n send to its contents. remit and pemit are just\n limited forms of emit, for sending to rooms and\n to accounts respectively.\n '}</em><a class="headerlink" href="#evennia.commands.default.admin.CmdEmit.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'pemit remit', 'category': 'admin', 'key': 'emit', 'no_prefix': ' pemit remit', 'tags': '', 'text': '\n admin command for emitting message to multiple objects\n\n Usage:\n emit[/switches] [&lt;obj&gt;, &lt;obj&gt;, ... =] &lt;message&gt;\n remit [&lt;obj&gt;, &lt;obj&gt;, ... =] &lt;message&gt;\n pemit [&lt;obj&gt;, &lt;obj&gt;, ... =] &lt;message&gt;\n\n Switches:\n room - limit emits to rooms only (default)\n accounts - limit emits to accounts only\n contents - send to the contents of matched objects too\n\n Emits a message to the selected objects or to\n your immediate surroundings. If the object is a room,\n send to its contents. remit and pemit are just\n limited forms of emit, for sending to rooms and\n to accounts respectively.\n '}</em><a class="headerlink" href="#evennia.commands.default.admin.CmdEmit.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

4
docs/1.0-dev/api/evennia.commands.default.batchprocess.html
View file

@ -138,7 +138,7 @@ skipping, reloading etc.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.batchprocess.CmdBatchCommands.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['batchcommand', 'batchcmd']</em><a class="headerlink" href="#evennia.commands.default.batchprocess.CmdBatchCommands.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['batchcmd', 'batchcommand']</em><a class="headerlink" href="#evennia.commands.default.batchprocess.CmdBatchCommands.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -169,7 +169,7 @@ skipping, reloading etc.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.batchprocess.CmdBatchCommands.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'batchcommand batchcmd', 'category': 'building', 'key': 'batchcommands', 'no_prefix': ' batchcommand batchcmd', 'tags': '', 'text': '\n build from batch-command file\n\n Usage:\n batchcommands[/interactive] &lt;python.path.to.file&gt;\n\n Switch:\n interactive - this mode will offer more control when\n executing the batch file, like stepping,\n skipping, reloading etc.\n\n Runs batches of commands from a batch-cmd text file (*.ev).\n\n '}</em><a class="headerlink" href="#evennia.commands.default.batchprocess.CmdBatchCommands.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'batchcmd batchcommand', 'category': 'building', 'key': 'batchcommands', 'no_prefix': ' batchcmd batchcommand', 'tags': '', 'text': '\n build from batch-command file\n\n Usage:\n batchcommands[/interactive] &lt;python.path.to.file&gt;\n\n Switch:\n interactive - this mode will offer more control when\n executing the batch file, like stepping,\n skipping, reloading etc.\n\n Runs batches of commands from a batch-cmd text file (*.ev).\n\n '}</em><a class="headerlink" href="#evennia.commands.default.batchprocess.CmdBatchCommands.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

12
docs/1.0-dev/api/evennia.commands.default.building.html
View file

@ -592,7 +592,7 @@ You can specify the /force switch to bypass this confirmation.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.building.CmdDestroy.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;delete', '&#64;del']</em><a class="headerlink" href="#evennia.commands.default.building.CmdDestroy.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;del', '&#64;delete']</em><a class="headerlink" href="#evennia.commands.default.building.CmdDestroy.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -633,7 +633,7 @@ You can specify the /force switch to bypass this confirmation.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.building.CmdDestroy.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;delete &#64;del', 'category': 'building', 'key': '&#64;destroy', 'no_prefix': 'destroy delete del', 'tags': '', 'text': '\n permanently delete objects\n\n Usage:\n destroy[/switches] [obj, obj2, obj3, [dbref-dbref], ...]\n\n Switches:\n override - The destroy command will usually avoid accidentally\n destroying account objects. This switch overrides this safety.\n force - destroy without confirmation.\n Examples:\n destroy house, roof, door, 44-78\n destroy 5-10, flower, 45\n destroy/force north\n\n Destroys one or many objects. If dbrefs are used, a range to delete can be\n given, e.g. 4-10. Also the end points will be deleted. This command\n displays a confirmation before destroying, to make sure of your choice.\n You can specify the /force switch to bypass this confirmation.\n '}</em><a class="headerlink" href="#evennia.commands.default.building.CmdDestroy.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;del &#64;delete', 'category': 'building', 'key': '&#64;destroy', 'no_prefix': 'destroy del delete', 'tags': '', 'text': '\n permanently delete objects\n\n Usage:\n destroy[/switches] [obj, obj2, obj3, [dbref-dbref], ...]\n\n Switches:\n override - The destroy command will usually avoid accidentally\n destroying account objects. This switch overrides this safety.\n force - destroy without confirmation.\n Examples:\n destroy house, roof, door, 44-78\n destroy 5-10, flower, 45\n destroy/force north\n\n Destroys one or many objects. If dbrefs are used, a range to delete can be\n given, e.g. 4-10. Also the end points will be deleted. This command\n displays a confirmation before destroying, to make sure of your choice.\n You can specify the /force switch to bypass this confirmation.\n '}</em><a class="headerlink" href="#evennia.commands.default.building.CmdDestroy.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -1345,7 +1345,7 @@ server settings.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.building.CmdTypeclass.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;swap', '&#64;parent', '&#64;type', '&#64;typeclasses', '&#64;update']</em><a class="headerlink" href="#evennia.commands.default.building.CmdTypeclass.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;update', '&#64;type', '&#64;swap', '&#64;typeclasses', '&#64;parent']</em><a class="headerlink" href="#evennia.commands.default.building.CmdTypeclass.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -1376,7 +1376,7 @@ server settings.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.building.CmdTypeclass.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;swap &#64;parent &#64;type &#64;typeclasses &#64;update', 'category': 'building', 'key': '&#64;typeclass', 'no_prefix': 'typeclass swap parent type typeclasses update', 'tags': '', 'text': &quot;\n set or change an object's typeclass\n\n Usage:\n typeclass[/switch] &lt;object&gt; [= typeclass.path]\n typeclass/prototype &lt;object&gt; = prototype_key\n\n typeclasses or typeclass/list/show [typeclass.path]\n swap - this is a shorthand for using /force/reset flags.\n update - this is a shorthand for using the /force/reload flag.\n\n Switch:\n show, examine - display the current typeclass of object (default) or, if\n given a typeclass path, show the docstring of that typeclass.\n update - *only* re-run at_object_creation on this object\n meaning locks or other properties set later may remain.\n reset - clean out *all* the attributes and properties on the\n object - basically making this a new clean object. This will also\n reset cmdsets!\n force - change to the typeclass also if the object\n already has a typeclass of the same name.\n list - show available typeclasses. Only typeclasses in modules actually\n imported or used from somewhere in the code will show up here\n (those typeclasses are still available if you know the path)\n prototype - clean and overwrite the object with the specified\n prototype key - effectively making a whole new object.\n\n Example:\n type button = examples.red_button.RedButton\n type/prototype button=a red button\n\n If the typeclass_path is not given, the current object's typeclass is\n assumed.\n\n View or set an object's typeclass. If setting, the creation hooks of the\n new typeclass will be run on the object. If you have clashing properties on\n the old class, use /reset. By default you are protected from changing to a\n typeclass of the same name as the one you already have - use /force to\n override this protection.\n\n The given typeclass must be identified by its location using python\n dot-notation pointing to the correct module and class. If no typeclass is\n given (or a wrong typeclass is given). Errors in the path or new typeclass\n will lead to the old typeclass being kept. The location of the typeclass\n module is searched from the default typeclass directory, as defined in the\n server settings.\n\n &quot;}</em><a class="headerlink" href="#evennia.commands.default.building.CmdTypeclass.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;update &#64;type &#64;swap &#64;typeclasses &#64;parent', 'category': 'building', 'key': '&#64;typeclass', 'no_prefix': 'typeclass update type swap typeclasses parent', 'tags': '', 'text': &quot;\n set or change an object's typeclass\n\n Usage:\n typeclass[/switch] &lt;object&gt; [= typeclass.path]\n typeclass/prototype &lt;object&gt; = prototype_key\n\n typeclasses or typeclass/list/show [typeclass.path]\n swap - this is a shorthand for using /force/reset flags.\n update - this is a shorthand for using the /force/reload flag.\n\n Switch:\n show, examine - display the current typeclass of object (default) or, if\n given a typeclass path, show the docstring of that typeclass.\n update - *only* re-run at_object_creation on this object\n meaning locks or other properties set later may remain.\n reset - clean out *all* the attributes and properties on the\n object - basically making this a new clean object. This will also\n reset cmdsets!\n force - change to the typeclass also if the object\n already has a typeclass of the same name.\n list - show available typeclasses. Only typeclasses in modules actually\n imported or used from somewhere in the code will show up here\n (those typeclasses are still available if you know the path)\n prototype - clean and overwrite the object with the specified\n prototype key - effectively making a whole new object.\n\n Example:\n type button = examples.red_button.RedButton\n type/prototype button=a red button\n\n If the typeclass_path is not given, the current object's typeclass is\n assumed.\n\n View or set an object's typeclass. If setting, the creation hooks of the\n new typeclass will be run on the object. If you have clashing properties on\n the old class, use /reset. By default you are protected from changing to a\n typeclass of the same name as the one you already have - use /force to\n override this protection.\n\n The given typeclass must be identified by its location using python\n dot-notation pointing to the correct module and class. If no typeclass is\n given (or a wrong typeclass is given). Errors in the path or new typeclass\n will lead to the old typeclass being kept. The location of the typeclass\n module is searched from the default typeclass directory, as defined in the\n server settings.\n\n &quot;}</em><a class="headerlink" href="#evennia.commands.default.building.CmdTypeclass.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -1833,7 +1833,7 @@ one is given.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.building.CmdFind.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;locate', '&#64;search']</em><a class="headerlink" href="#evennia.commands.default.building.CmdFind.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;search', '&#64;locate']</em><a class="headerlink" href="#evennia.commands.default.building.CmdFind.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -1864,7 +1864,7 @@ one is given.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.building.CmdFind.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;locate &#64;search', 'category': 'building', 'key': '&#64;find', 'no_prefix': 'find locate search', 'tags': '', 'text': '\n search the database for objects\n\n Usage:\n find[/switches] &lt;name or dbref or *account&gt; [= dbrefmin[-dbrefmax]]\n locate - this is a shorthand for using the /loc switch.\n\n Switches:\n room - only look for rooms (location=None)\n exit - only look for exits (destination!=None)\n char - only look for characters (BASE_CHARACTER_TYPECLASS)\n exact - only exact matches are returned.\n loc - display object location if exists and match has one result\n startswith - search for names starting with the string, rather than containing\n\n Searches the database for an object of a particular name or exact #dbref.\n Use *accountname to search for an account. The switches allows for\n limiting object matches to certain game entities. Dbrefmin and dbrefmax\n limits matches to within the given dbrefs range, or above/below if only\n one is given.\n '}</em><a class="headerlink" href="#evennia.commands.default.building.CmdFind.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;search &#64;locate', 'category': 'building', 'key': '&#64;find', 'no_prefix': 'find search locate', 'tags': '', 'text': '\n search the database for objects\n\n Usage:\n find[/switches] &lt;name or dbref or *account&gt; [= dbrefmin[-dbrefmax]]\n locate - this is a shorthand for using the /loc switch.\n\n Switches:\n room - only look for rooms (location=None)\n exit - only look for exits (destination!=None)\n char - only look for characters (BASE_CHARACTER_TYPECLASS)\n exact - only exact matches are returned.\n loc - display object location if exists and match has one result\n startswith - search for names starting with the string, rather than containing\n\n Searches the database for an object of a particular name or exact #dbref.\n Use *accountname to search for an account. The switches allows for\n limiting object matches to certain game entities. Dbrefmin and dbrefmax\n limits matches to within the given dbrefs range, or above/below if only\n one is given.\n '}</em><a class="headerlink" href="#evennia.commands.default.building.CmdFind.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

8
docs/1.0-dev/api/evennia.commands.default.general.html
View file

@ -175,7 +175,7 @@ look <a href="#id1"><span class="problematic" id="id2">*</span></a>&lt;account&g
<dl class="py attribute">
<dt id="evennia.commands.default.general.CmdLook.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['ls', 'l']</em><a class="headerlink" href="#evennia.commands.default.general.CmdLook.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['l', 'ls']</em><a class="headerlink" href="#evennia.commands.default.general.CmdLook.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -206,7 +206,7 @@ look <a href="#id1"><span class="problematic" id="id2">*</span></a>&lt;account&g
<dl class="py attribute">
<dt id="evennia.commands.default.general.CmdLook.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'ls l', 'category': 'general', 'key': 'look', 'no_prefix': ' ls l', 'tags': '', 'text': '\n look at location or object\n\n Usage:\n look\n look &lt;obj&gt;\n look *&lt;account&gt;\n\n Observes your location or objects in your vicinity.\n '}</em><a class="headerlink" href="#evennia.commands.default.general.CmdLook.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'l ls', 'category': 'general', 'key': 'look', 'no_prefix': ' l ls', 'tags': '', 'text': '\n look at location or object\n\n Usage:\n look\n look &lt;obj&gt;\n look *&lt;account&gt;\n\n Observes your location or objects in your vicinity.\n '}</em><a class="headerlink" href="#evennia.commands.default.general.CmdLook.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -598,7 +598,7 @@ placing it in their inventory.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.general.CmdSay.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = [&quot;'&quot;, '&quot;']</em><a class="headerlink" href="#evennia.commands.default.general.CmdSay.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['&quot;', &quot;'&quot;]</em><a class="headerlink" href="#evennia.commands.default.general.CmdSay.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -629,7 +629,7 @@ placing it in their inventory.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.general.CmdSay.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '\' &quot;', 'category': 'general', 'key': 'say', 'no_prefix': ' \' &quot;', 'tags': '', 'text': '\n speak as your character\n\n Usage:\n say &lt;message&gt;\n\n Talk to those in your current location.\n '}</em><a class="headerlink" href="#evennia.commands.default.general.CmdSay.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&quot; \'', 'category': 'general', 'key': 'say', 'no_prefix': ' &quot; \'', 'tags': '', 'text': '\n speak as your character\n\n Usage:\n say &lt;message&gt;\n\n Talk to those in your current location.\n '}</em><a class="headerlink" href="#evennia.commands.default.general.CmdSay.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

2
docs/1.0-dev/api/evennia.commands.default.tests.html
View file

@ -902,7 +902,7 @@ main test suite started with</p>
<p>Test the batch processor.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.tests.TestBatchProcess.red_button">
<code class="sig-name descname">red_button</code><em class="property"> = &lt;module 'evennia.contrib.tutorials.red_button.red_button' from '/tmp/tmpoztk3116/ce2d001e3510f9e8a27fa27418d49dd5bb334d6b/evennia/contrib/tutorials/red_button/red_button.py'&gt;</em><a class="headerlink" href="#evennia.commands.default.tests.TestBatchProcess.red_button" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">red_button</code><em class="property"> = &lt;module 'evennia.contrib.tutorials.red_button.red_button' from '/tmp/tmp_1kpuess/a77d568709ea6c7905c2d58d3cafa74bd7466278/evennia/contrib/tutorials/red_button/red_button.py'&gt;</em><a class="headerlink" href="#evennia.commands.default.tests.TestBatchProcess.red_button" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">

16
docs/1.0-dev/api/evennia.commands.default.unloggedin.html
View file

@ -122,7 +122,7 @@ connect “account name” “pass word”</p>
<dl class="py attribute">
<dt id="evennia.commands.default.unloggedin.CmdUnconnectedConnect.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['co', 'con', 'conn']</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedConnect.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['conn', 'con', 'co']</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedConnect.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -157,7 +157,7 @@ there is no object yet before the account has logged in)</p>
<dl class="py attribute">
<dt id="evennia.commands.default.unloggedin.CmdUnconnectedConnect.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'co con conn', 'category': 'general', 'key': 'connect', 'no_prefix': ' co con conn', 'tags': '', 'text': '\n connect to the game\n\n Usage (at login screen):\n connect accountname password\n connect &quot;account name&quot; &quot;pass word&quot;\n\n Use the create command to first create an account before logging in.\n\n If you have spaces in your name, enclose it in double quotes.\n '}</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedConnect.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'conn con co', 'category': 'general', 'key': 'connect', 'no_prefix': ' conn con co', 'tags': '', 'text': '\n connect to the game\n\n Usage (at login screen):\n connect accountname password\n connect &quot;account name&quot; &quot;pass word&quot;\n\n Use the create command to first create an account before logging in.\n\n If you have spaces in your name, enclose it in double quotes.\n '}</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedConnect.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -181,7 +181,7 @@ create “account name” “pass word”</p>
<dl class="py attribute">
<dt id="evennia.commands.default.unloggedin.CmdUnconnectedCreate.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['cr', 'cre']</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedCreate.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['cre', 'cr']</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedCreate.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -212,7 +212,7 @@ create “account name” “pass word”</p>
<dl class="py attribute">
<dt id="evennia.commands.default.unloggedin.CmdUnconnectedCreate.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'cr cre', 'category': 'general', 'key': 'create', 'no_prefix': ' cr cre', 'tags': '', 'text': '\n create a new account account\n\n Usage (at login screen):\n create &lt;accountname&gt; &lt;password&gt;\n create &quot;account name&quot; &quot;pass word&quot;\n\n This creates a new account account.\n\n If you have spaces in your name, enclose it in double quotes.\n '}</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedCreate.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'cre cr', 'category': 'general', 'key': 'create', 'no_prefix': ' cre cr', 'tags': '', 'text': '\n create a new account account\n\n Usage (at login screen):\n create &lt;accountname&gt; &lt;password&gt;\n create &quot;account name&quot; &quot;pass word&quot;\n\n This creates a new account account.\n\n If you have spaces in your name, enclose it in double quotes.\n '}</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedCreate.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -236,7 +236,7 @@ version is a bit more complicated.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.unloggedin.CmdUnconnectedQuit.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['q', 'qu']</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedQuit.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['qu', 'q']</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedQuit.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -262,7 +262,7 @@ version is a bit more complicated.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.unloggedin.CmdUnconnectedQuit.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'q qu', 'category': 'general', 'key': 'quit', 'no_prefix': ' q qu', 'tags': '', 'text': '\n quit when in unlogged-in state\n\n Usage:\n quit\n\n We maintain a different version of the quit command\n here for unconnected accounts for the sake of simplicity. The logged in\n version is a bit more complicated.\n '}</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedQuit.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'qu q', 'category': 'general', 'key': 'quit', 'no_prefix': ' qu q', 'tags': '', 'text': '\n quit when in unlogged-in state\n\n Usage:\n quit\n\n We maintain a different version of the quit command\n here for unconnected accounts for the sake of simplicity. The logged in\n version is a bit more complicated.\n '}</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedQuit.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -335,7 +335,7 @@ for simplicity. It shows a pane of info.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.unloggedin.CmdUnconnectedHelp.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['h', '?']</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedHelp.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['?', 'h']</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedHelp.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -361,7 +361,7 @@ for simplicity. It shows a pane of info.</p>
<dl class="py attribute">
<dt id="evennia.commands.default.unloggedin.CmdUnconnectedHelp.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'h ?', 'category': 'general', 'key': 'help', 'no_prefix': ' h ?', 'tags': '', 'text': '\n get help when in unconnected-in state\n\n Usage:\n help\n\n This is an unconnected version of the help command,\n for simplicity. It shows a pane of info.\n '}</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedHelp.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '? h', 'category': 'general', 'key': 'help', 'no_prefix': ' ? h', 'tags': '', 'text': '\n get help when in unconnected-in state\n\n Usage:\n help\n\n This is an unconnected version of the help command,\n for simplicity. It shows a pane of info.\n '}</em><a class="headerlink" href="#evennia.commands.default.unloggedin.CmdUnconnectedHelp.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

16
docs/1.0-dev/api/evennia.contrib.base_systems.email_login.email_login.html
View file

@ -139,7 +139,7 @@ the module given by settings.CONNECTION_SCREEN_MODULE.</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedConnect.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['co', 'con', 'conn']</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedConnect.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['conn', 'con', 'co']</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedConnect.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -169,7 +169,7 @@ there is no object yet before the account has logged in)</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedConnect.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'co con conn', 'category': 'general', 'key': 'connect', 'no_prefix': ' co con conn', 'tags': '', 'text': '\n Connect to the game.\n\n Usage (at login screen):\n connect &lt;email&gt; &lt;password&gt;\n\n Use the create command to first create an account before logging in.\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedConnect.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'conn con co', 'category': 'general', 'key': 'connect', 'no_prefix': ' conn con co', 'tags': '', 'text': '\n Connect to the game.\n\n Usage (at login screen):\n connect &lt;email&gt; &lt;password&gt;\n\n Use the create command to first create an account before logging in.\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedConnect.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -191,7 +191,7 @@ there is no object yet before the account has logged in)</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedCreate.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['cr', 'cre']</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedCreate.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['cre', 'cr']</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedCreate.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -227,7 +227,7 @@ name enclosed in quotes:</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedCreate.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'cr cre', 'category': 'general', 'key': 'create', 'no_prefix': ' cr cre', 'tags': '', 'text': '\n Create a new account.\n\n Usage (at login screen):\n create &quot;accountname&quot; &lt;email&gt; &lt;password&gt;\n\n This creates a new account account.\n\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedCreate.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'cre cr', 'category': 'general', 'key': 'create', 'no_prefix': ' cre cr', 'tags': '', 'text': '\n Create a new account.\n\n Usage (at login screen):\n create &quot;accountname&quot; &lt;email&gt; &lt;password&gt;\n\n This creates a new account account.\n\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedCreate.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -246,7 +246,7 @@ version is a bit more complicated.</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedQuit.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['q', 'qu']</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedQuit.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['qu', 'q']</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedQuit.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -272,7 +272,7 @@ version is a bit more complicated.</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedQuit.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'q qu', 'category': 'general', 'key': 'quit', 'no_prefix': ' q qu', 'tags': '', 'text': '\n We maintain a different version of the `quit` command\n here for unconnected accounts for the sake of simplicity. The logged in\n version is a bit more complicated.\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedQuit.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'qu q', 'category': 'general', 'key': 'quit', 'no_prefix': ' qu q', 'tags': '', 'text': '\n We maintain a different version of the `quit` command\n here for unconnected accounts for the sake of simplicity. The logged in\n version is a bit more complicated.\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedQuit.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -335,7 +335,7 @@ for simplicity. It shows a pane of info.</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedHelp.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['h', '?']</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedHelp.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['?', 'h']</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedHelp.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -361,7 +361,7 @@ for simplicity. It shows a pane of info.</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedHelp.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'h ?', 'category': 'general', 'key': 'help', 'no_prefix': ' h ?', 'tags': '', 'text': '\n This is an unconnected version of the help command,\n for simplicity. It shows a pane of info.\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedHelp.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '? h', 'category': 'general', 'key': 'help', 'no_prefix': ' ? h', 'tags': '', 'text': '\n This is an unconnected version of the help command,\n for simplicity. It shows a pane of info.\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.email_login.email_login.CmdUnconnectedHelp.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

4
docs/1.0-dev/api/evennia.contrib.base_systems.ingame_python.commands.html
View file

@ -116,7 +116,7 @@
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.ingame_python.commands.CmdCallback.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;calls', '&#64;callback', '&#64;callbacks']</em><a class="headerlink" href="#evennia.contrib.base_systems.ingame_python.commands.CmdCallback.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;calls', '&#64;callbacks', '&#64;callback']</em><a class="headerlink" href="#evennia.contrib.base_systems.ingame_python.commands.CmdCallback.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -197,7 +197,7 @@ on user permission.</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.ingame_python.commands.CmdCallback.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;calls &#64;callback &#64;callbacks', 'category': 'building', 'key': '&#64;call', 'no_prefix': 'call calls callback callbacks', 'tags': '', 'text': '\n Command to edit callbacks.\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.ingame_python.commands.CmdCallback.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;calls &#64;callbacks &#64;callback', 'category': 'building', 'key': '&#64;call', 'no_prefix': 'call calls callbacks callback', 'tags': '', 'text': '\n Command to edit callbacks.\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.ingame_python.commands.CmdCallback.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

4
docs/1.0-dev/api/evennia.contrib.base_systems.mux_comms_cmds.mux_comms_cmds.html
View file

@ -160,7 +160,7 @@ aliases to an already joined channel.</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.mux_comms_cmds.mux_comms_cmds.CmdAddCom.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['aliaschan', 'chanalias']</em><a class="headerlink" href="#evennia.contrib.base_systems.mux_comms_cmds.mux_comms_cmds.CmdAddCom.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['chanalias', 'aliaschan']</em><a class="headerlink" href="#evennia.contrib.base_systems.mux_comms_cmds.mux_comms_cmds.CmdAddCom.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -191,7 +191,7 @@ aliases to an already joined channel.</p>
<dl class="py attribute">
<dt id="evennia.contrib.base_systems.mux_comms_cmds.mux_comms_cmds.CmdAddCom.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'aliaschan chanalias', 'category': 'comms', 'key': 'addcom', 'no_prefix': ' aliaschan chanalias', 'tags': '', 'text': '\n Add a channel alias and/or subscribe to a channel\n\n Usage:\n addcom [alias=] &lt;channel&gt;\n\n Joins a given channel. If alias is given, this will allow you to\n refer to the channel by this alias rather than the full channel\n name. Subsequent calls of this command can be used to add multiple\n aliases to an already joined channel.\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.mux_comms_cmds.mux_comms_cmds.CmdAddCom.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'chanalias aliaschan', 'category': 'comms', 'key': 'addcom', 'no_prefix': ' chanalias aliaschan', 'tags': '', 'text': '\n Add a channel alias and/or subscribe to a channel\n\n Usage:\n addcom [alias=] &lt;channel&gt;\n\n Joins a given channel. If alias is given, this will allow you to\n refer to the channel by this alias rather than the full channel\n name. Subsequent calls of this command can be used to add multiple\n aliases to an already joined channel.\n '}</em><a class="headerlink" href="#evennia.contrib.base_systems.mux_comms_cmds.mux_comms_cmds.CmdAddCom.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

24
docs/1.0-dev/api/evennia.contrib.full_systems.evscaperoom.commands.html
View file

@ -211,7 +211,7 @@ the operation will be general or on the room.</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdGiveUp.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['chicken out', 'abort', 'quit', 'q']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdGiveUp.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['q', 'chicken out', 'abort', 'quit']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdGiveUp.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
@ -235,7 +235,7 @@ set in self.parse())</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdGiveUp.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'chicken out abort quit q', 'category': 'evscaperoom', 'key': 'give up', 'no_prefix': ' chicken out abort quit q', 'tags': '', 'text': '\n Give up\n\n Usage:\n give up\n\n Abandons your attempts at escaping and of ever winning the pie-eating contest.\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdGiveUp.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'q chicken out abort quit', 'category': 'evscaperoom', 'key': 'give up', 'no_prefix': ' q chicken out abort quit', 'tags': '', 'text': '\n Give up\n\n Usage:\n give up\n\n Abandons your attempts at escaping and of ever winning the pie-eating contest.\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdGiveUp.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -256,7 +256,7 @@ set in self.parse())</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdLook.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['ls', 'l']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdLook.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['l', 'ls']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdLook.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -290,7 +290,7 @@ set in self.parse())</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdLook.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'ls l', 'category': 'evscaperoom', 'key': 'look', 'no_prefix': ' ls l', 'tags': '', 'text': '\n Look at the room, an object or the currently focused object\n\n Usage:\n look [obj]\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdLook.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'l ls', 'category': 'evscaperoom', 'key': 'look', 'no_prefix': ' l ls', 'tags': '', 'text': '\n Look at the room, an object or the currently focused object\n\n Usage:\n look [obj]\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdLook.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -428,7 +428,7 @@ emote /me points to /box and /lever.</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdEmote.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = [':', 'pose']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdEmote.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['pose', ':']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdEmote.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -467,7 +467,7 @@ set in self.parse())</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdEmote.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': ': pose', 'category': 'general', 'key': 'emote', 'no_prefix': ' : pose', 'tags': '', 'text': '\n Perform a free-form emote. Use /me to\n include yourself in the emote and /name\n to include other objects or characters.\n Use &quot;...&quot; to enact speech.\n\n Usage:\n emote &lt;emote&gt;\n :&lt;emote\n\n Example:\n emote /me smiles at /peter\n emote /me points to /box and /lever.\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdEmote.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'pose :', 'category': 'general', 'key': 'emote', 'no_prefix': ' pose :', 'tags': '', 'text': '\n Perform a free-form emote. Use /me to\n include yourself in the emote and /name\n to include other objects or characters.\n Use &quot;...&quot; to enact speech.\n\n Usage:\n emote &lt;emote&gt;\n :&lt;emote\n\n Example:\n emote /me smiles at /peter\n emote /me points to /box and /lever.\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdEmote.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -490,7 +490,7 @@ looks and what actions is available.</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdFocus.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['ex', 'examine', 'unfocus', 'e']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdFocus.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['examine', 'ex', 'e', 'unfocus']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdFocus.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -519,7 +519,7 @@ set in self.parse())</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdFocus.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'ex examine unfocus e', 'category': 'evscaperoom', 'key': 'focus', 'no_prefix': ' ex examine unfocus e', 'tags': '', 'text': '\n Focus your attention on a target.\n\n Usage:\n focus &lt;obj&gt;\n\n Once focusing on an object, use look to get more information about how it\n looks and what actions is available.\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdFocus.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'examine ex e unfocus', 'category': 'evscaperoom', 'key': 'focus', 'no_prefix': ' examine ex e unfocus', 'tags': '', 'text': '\n Focus your attention on a target.\n\n Usage:\n focus &lt;obj&gt;\n\n Once focusing on an object, use look to get more information about how it\n looks and what actions is available.\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdFocus.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -581,7 +581,7 @@ set in self.parse())</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdGet.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['i', 'inventory', 'inv', 'give']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdGet.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['i', 'inventory', 'give', 'inv']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdGet.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
@ -605,7 +605,7 @@ set in self.parse())</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdGet.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'i inventory inv give', 'category': 'evscaperoom', 'key': 'get', 'no_prefix': ' i inventory inv give', 'tags': '', 'text': '\n Use focus / examine instead.\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdGet.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'i inventory give inv', 'category': 'evscaperoom', 'key': 'get', 'no_prefix': ' i inventory give inv', 'tags': '', 'text': '\n Use focus / examine instead.\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdGet.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -626,7 +626,7 @@ set in self.parse())</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdRerouter.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;open', '&#64;dig']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdRerouter.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;dig', '&#64;open']</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdRerouter.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
@ -649,7 +649,7 @@ to all the variables defined therein.</p>
<dl class="py attribute">
<dt id="evennia.contrib.full_systems.evscaperoom.commands.CmdRerouter.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;open &#64;dig', 'category': 'general', 'key': 'open', 'no_prefix': ' open dig', 'tags': '', 'text': '\n Interact with an object in focus.\n\n Usage:\n &lt;action&gt; [arg]\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdRerouter.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;dig &#64;open', 'category': 'general', 'key': 'open', 'no_prefix': ' dig open', 'tags': '', 'text': '\n Interact with an object in focus.\n\n Usage:\n &lt;action&gt; [arg]\n\n '}</em><a class="headerlink" href="#evennia.contrib.full_systems.evscaperoom.commands.CmdRerouter.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

4
docs/1.0-dev/api/evennia.contrib.grid.extended_room.extended_room.html
View file

@ -340,7 +340,7 @@ look <a href="#id1"><span class="problematic" id="id2">*</span></a>&lt;account&g
<dl class="py attribute">
<dt id="evennia.contrib.grid.extended_room.extended_room.CmdExtendedRoomLook.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['ls', 'l']</em><a class="headerlink" href="#evennia.contrib.grid.extended_room.extended_room.CmdExtendedRoomLook.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['l', 'ls']</em><a class="headerlink" href="#evennia.contrib.grid.extended_room.extended_room.CmdExtendedRoomLook.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -360,7 +360,7 @@ look <a href="#id1"><span class="problematic" id="id2">*</span></a>&lt;account&g
<dl class="py attribute">
<dt id="evennia.contrib.grid.extended_room.extended_room.CmdExtendedRoomLook.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'ls l', 'category': 'general', 'key': 'look', 'no_prefix': ' ls l', 'tags': '', 'text': '\n look\n\n Usage:\n look\n look &lt;obj&gt;\n look &lt;room detail&gt;\n look *&lt;account&gt;\n\n Observes your location, details at your location or objects in your vicinity.\n '}</em><a class="headerlink" href="#evennia.contrib.grid.extended_room.extended_room.CmdExtendedRoomLook.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'l ls', 'category': 'general', 'key': 'look', 'no_prefix': ' l ls', 'tags': '', 'text': '\n look\n\n Usage:\n look\n look &lt;obj&gt;\n look &lt;room detail&gt;\n look *&lt;account&gt;\n\n Observes your location, details at your location or objects in your vicinity.\n '}</em><a class="headerlink" href="#evennia.contrib.grid.extended_room.extended_room.CmdExtendedRoomLook.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

4
docs/1.0-dev/api/evennia.contrib.rpg.dice.dice.html
View file

@ -305,7 +305,7 @@ everyone but the person rolling.</p>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.dice.dice.CmdDice.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['&#64;dice', 'roll']</em><a class="headerlink" href="#evennia.contrib.rpg.dice.dice.CmdDice.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['roll', '&#64;dice']</em><a class="headerlink" href="#evennia.contrib.rpg.dice.dice.CmdDice.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -331,7 +331,7 @@ everyone but the person rolling.</p>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.dice.dice.CmdDice.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&#64;dice roll', 'category': 'general', 'key': 'dice', 'no_prefix': ' dice roll', 'tags': '', 'text': &quot;\n roll dice\n\n Usage:\n dice[/switch] &lt;nr&gt;d&lt;sides&gt; [modifier] [success condition]\n\n Switch:\n hidden - tell the room the roll is being done, but don't show the result\n secret - don't inform the room about neither roll nor result\n\n Examples:\n dice 3d6 + 4\n dice 1d100 - 2 &lt; 50\n\n This will roll the given number of dice with given sides and modifiers.\n So e.g. 2d6 + 3 means to 'roll a 6-sided die 2 times and add the result,\n then add 3 to the total'.\n Accepted modifiers are +, -, * and /.\n A success condition is given as normal Python conditionals\n (&lt;,&gt;,&lt;=,&gt;=,==,!=). So e.g. 2d6 + 3 &gt; 10 means that the roll will succeed\n only if the final result is above 8. If a success condition is given, the\n outcome (pass/fail) will be echoed along with how much it succeeded/failed\n with. The hidden/secret switches will hide all or parts of the roll from\n everyone but the person rolling.\n &quot;}</em><a class="headerlink" href="#evennia.contrib.rpg.dice.dice.CmdDice.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'roll &#64;dice', 'category': 'general', 'key': 'dice', 'no_prefix': ' roll dice', 'tags': '', 'text': &quot;\n roll dice\n\n Usage:\n dice[/switch] &lt;nr&gt;d&lt;sides&gt; [modifier] [success condition]\n\n Switch:\n hidden - tell the room the roll is being done, but don't show the result\n secret - don't inform the room about neither roll nor result\n\n Examples:\n dice 3d6 + 4\n dice 1d100 - 2 &lt; 50\n\n This will roll the given number of dice with given sides and modifiers.\n So e.g. 2d6 + 3 means to 'roll a 6-sided die 2 times and add the result,\n then add 3 to the total'.\n Accepted modifiers are +, -, * and /.\n A success condition is given as normal Python conditionals\n (&lt;,&gt;,&lt;=,&gt;=,==,!=). So e.g. 2d6 + 3 &gt; 10 means that the roll will succeed\n only if the final result is above 8. If a success condition is given, the\n outcome (pass/fail) will be echoed along with how much it succeeded/failed\n with. The hidden/secret switches will hide all or parts of the roll from\n everyone but the person rolling.\n &quot;}</em><a class="headerlink" href="#evennia.contrib.rpg.dice.dice.CmdDice.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

4
docs/1.0-dev/api/evennia.contrib.rpg.rpsystem.rpsystem.html
View file

@ -695,7 +695,7 @@ a different language.</p>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.rpsystem.rpsystem.CmdSay.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = [&quot;'&quot;, '&quot;']</em><a class="headerlink" href="#evennia.contrib.rpg.rpsystem.rpsystem.CmdSay.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['&quot;', &quot;'&quot;]</em><a class="headerlink" href="#evennia.contrib.rpg.rpsystem.rpsystem.CmdSay.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -726,7 +726,7 @@ a different language.</p>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.rpsystem.rpsystem.CmdSay.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '\' &quot;', 'category': 'general', 'key': 'say', 'no_prefix': ' \' &quot;', 'tags': '', 'text': '\n speak as your character\n\n Usage:\n say &lt;message&gt;\n\n Talk to those in your current location.\n '}</em><a class="headerlink" href="#evennia.contrib.rpg.rpsystem.rpsystem.CmdSay.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '&quot; \'', 'category': 'general', 'key': 'say', 'no_prefix': ' &quot; \'', 'tags': '', 'text': '\n speak as your character\n\n Usage:\n say &lt;message&gt;\n\n Talk to those in your current location.\n '}</em><a class="headerlink" href="#evennia.contrib.rpg.rpsystem.rpsystem.CmdSay.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

16
docs/1.0-dev/api/evennia.contrib.tutorials.red_button.red_button.html
View file

@ -153,7 +153,7 @@ such as when closing the lid and un-blinding a character.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.red_button.red_button.CmdPushLidClosed.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['press', 'push', 'press button']</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdPushLidClosed.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['push', 'press button', 'press']</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdPushLidClosed.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -182,7 +182,7 @@ check if the lid is open or closed.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.red_button.red_button.CmdPushLidClosed.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'press push press button', 'category': 'general', 'key': 'push button', 'no_prefix': ' press push press button', 'tags': '', 'text': '\n Push the red button (lid closed)\n\n Usage:\n push button\n\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdPushLidClosed.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'push press button press', 'category': 'general', 'key': 'push button', 'no_prefix': ' push press button press', 'tags': '', 'text': '\n Push the red button (lid closed)\n\n Usage:\n push button\n\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdPushLidClosed.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -252,7 +252,7 @@ check if the lid is open or closed.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.red_button.red_button.CmdSmashGlass.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['smash lid', 'break lid', 'smash']</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdSmashGlass.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['smash', 'break lid', 'smash lid']</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdSmashGlass.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -279,7 +279,7 @@ break.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.red_button.red_button.CmdSmashGlass.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'smash lid break lid smash', 'category': 'general', 'key': 'smash glass', 'no_prefix': ' smash lid break lid smash', 'tags': '', 'text': '\n Smash the protective glass.\n\n Usage:\n smash glass\n\n Try to smash the glass of the button.\n\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdSmashGlass.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'smash break lid smash lid', 'category': 'general', 'key': 'smash glass', 'no_prefix': ' smash break lid smash lid', 'tags': '', 'text': '\n Smash the protective glass.\n\n Usage:\n smash glass\n\n Try to smash the glass of the button.\n\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdSmashGlass.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -379,7 +379,7 @@ be mutually exclusive.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.red_button.red_button.CmdPushLidOpen.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['press', 'push', 'press button']</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdPushLidOpen.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['push', 'press button', 'press']</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdPushLidOpen.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -408,7 +408,7 @@ set in self.parse())</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.red_button.red_button.CmdPushLidOpen.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'press push press button', 'category': 'general', 'key': 'push button', 'no_prefix': ' press push press button', 'tags': '', 'text': '\n Push the red button\n\n Usage:\n push button\n\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdPushLidOpen.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'push press button press', 'category': 'general', 'key': 'push button', 'no_prefix': ' push press button press', 'tags': '', 'text': '\n Push the red button\n\n Usage:\n push button\n\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdPushLidOpen.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -506,7 +506,7 @@ be mutually exclusive.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.red_button.red_button.CmdBlindLook.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['listen', 'examine', 'l', 'ex', 'feel', 'get']</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdBlindLook.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['listen', 'l', 'get', 'examine', 'ex', 'feel']</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdBlindLook.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -532,7 +532,7 @@ be mutually exclusive.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.red_button.red_button.CmdBlindLook.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'listen examine l ex feel get', 'category': 'general', 'key': 'look', 'no_prefix': ' listen examine l ex feel get', 'tags': '', 'text': &quot;\n Looking around in darkness\n\n Usage:\n look &lt;obj&gt;\n\n ... not that there's much to see in the dark.\n\n &quot;}</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdBlindLook.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'listen l get examine ex feel', 'category': 'general', 'key': 'look', 'no_prefix': ' listen l get examine ex feel', 'tags': '', 'text': &quot;\n Looking around in darkness\n\n Usage:\n look &lt;obj&gt;\n\n ... not that there's much to see in the dark.\n\n &quot;}</em><a class="headerlink" href="#evennia.contrib.tutorials.red_button.red_button.CmdBlindLook.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

8
docs/1.0-dev/api/evennia.contrib.tutorials.tutorial_world.objects.html
View file

@ -556,7 +556,7 @@ shift green root up/down</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.tutorial_world.objects.CmdShiftRoot.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['move', 'shiftroot', 'pull', 'push']</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.objects.CmdShiftRoot.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['shiftroot', 'move', 'pull', 'push']</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.objects.CmdShiftRoot.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -592,7 +592,7 @@ yellow/green - horizontal roots</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.tutorial_world.objects.CmdShiftRoot.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'move shiftroot pull push', 'category': 'tutorialworld', 'key': 'shift', 'no_prefix': ' move shiftroot pull push', 'tags': '', 'text': '\n Shifts roots around.\n\n Usage:\n shift blue root left/right\n shift red root left/right\n shift yellow root up/down\n shift green root up/down\n\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.objects.CmdShiftRoot.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'shiftroot move pull push', 'category': 'tutorialworld', 'key': 'shift', 'no_prefix': ' shiftroot move pull push', 'tags': '', 'text': '\n Shifts roots around.\n\n Usage:\n shift blue root left/right\n shift red root left/right\n shift yellow root up/down\n shift green root up/down\n\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.objects.CmdShiftRoot.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -779,7 +779,7 @@ parry - forgoes your attack but will make you harder to hit on next</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.tutorial_world.objects.CmdAttack.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['stab', 'pierce', 'parry', 'fight', 'chop', 'defend', 'slash', 'bash', 'kill', 'thrust', 'hit']</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.objects.CmdAttack.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['hit', 'stab', 'parry', 'fight', 'bash', 'kill', 'defend', 'chop', 'thrust', 'pierce', 'slash']</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.objects.CmdAttack.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -805,7 +805,7 @@ parry - forgoes your attack but will make you harder to hit on next</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.tutorial_world.objects.CmdAttack.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'stab pierce parry fight chop defend slash bash kill thrust hit', 'category': 'tutorialworld', 'key': 'attack', 'no_prefix': ' stab pierce parry fight chop defend slash bash kill thrust hit', 'tags': '', 'text': '\n Attack the enemy. Commands:\n\n stab &lt;enemy&gt;\n slash &lt;enemy&gt;\n parry\n\n stab - (thrust) makes a lot of damage but is harder to hit with.\n slash - is easier to land, but does not make as much damage.\n parry - forgoes your attack but will make you harder to hit on next\n enemy attack.\n\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.objects.CmdAttack.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'hit stab parry fight bash kill defend chop thrust pierce slash', 'category': 'tutorialworld', 'key': 'attack', 'no_prefix': ' hit stab parry fight bash kill defend chop thrust pierce slash', 'tags': '', 'text': '\n Attack the enemy. Commands:\n\n stab &lt;enemy&gt;\n slash &lt;enemy&gt;\n parry\n\n stab - (thrust) makes a lot of damage but is harder to hit with.\n slash - is easier to land, but does not make as much damage.\n parry - forgoes your attack but will make you harder to hit on next\n enemy attack.\n\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.objects.CmdAttack.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

12
docs/1.0-dev/api/evennia.contrib.tutorials.tutorial_world.rooms.html
View file

@ -248,7 +248,7 @@ code except for adding in the details.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.tutorial_world.rooms.CmdTutorialLook.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['ls', 'l']</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdTutorialLook.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['l', 'ls']</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdTutorialLook.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -263,7 +263,7 @@ code except for adding in the details.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.tutorial_world.rooms.CmdTutorialLook.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'ls l', 'category': 'tutorialworld', 'key': 'look', 'no_prefix': ' ls l', 'tags': '', 'text': '\n looks at the room and on details\n\n Usage:\n look &lt;obj&gt;\n look &lt;room detail&gt;\n look *&lt;account&gt;\n\n Observes your location, details at your location or objects\n in your vicinity.\n\n Tutorial: This is a child of the default Look command, that also\n allows us to look at &quot;details&quot; in the room. These details are\n things to examine and offers some extra description without\n actually having to be actual database objects. It uses the\n return_detail() hook on TutorialRooms for this.\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdTutorialLook.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'l ls', 'category': 'tutorialworld', 'key': 'look', 'no_prefix': ' l ls', 'tags': '', 'text': '\n looks at the room and on details\n\n Usage:\n look &lt;obj&gt;\n look &lt;room detail&gt;\n look *&lt;account&gt;\n\n Observes your location, details at your location or objects\n in your vicinity.\n\n Tutorial: This is a child of the default Look command, that also\n allows us to look at &quot;details&quot; in the room. These details are\n things to examine and offers some extra description without\n actually having to be actual database objects. It uses the\n return_detail() hook on TutorialRooms for this.\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdTutorialLook.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -816,7 +816,7 @@ if they fall off the bridge.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.tutorial_world.rooms.CmdBridgeHelp.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['h', '?']</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdBridgeHelp.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['?', 'h']</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdBridgeHelp.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -842,7 +842,7 @@ if they fall off the bridge.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.tutorial_world.rooms.CmdBridgeHelp.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'h ?', 'category': 'tutorial world', 'key': 'help', 'no_prefix': ' h ?', 'tags': '', 'text': '\n Overwritten help command while on the bridge.\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdBridgeHelp.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': '? h', 'category': 'tutorial world', 'key': 'help', 'no_prefix': ' ? h', 'tags': '', 'text': '\n Overwritten help command while on the bridge.\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdBridgeHelp.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
@ -968,7 +968,7 @@ to find something.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.tutorial_world.rooms.CmdLookDark.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['fiddle', 'l', 'feel', 'search', 'feel around']</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdLookDark.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['search', 'l', 'feel around', 'fiddle', 'feel']</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdLookDark.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -996,7 +996,7 @@ random chance of eventually finding a light source.</p>
<dl class="py attribute">
<dt id="evennia.contrib.tutorials.tutorial_world.rooms.CmdLookDark.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'fiddle l feel search feel around', 'category': 'tutorialworld', 'key': 'look', 'no_prefix': ' fiddle l feel search feel around', 'tags': '', 'text': '\n Look around in darkness\n\n Usage:\n look\n\n Look around in the darkness, trying\n to find something.\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdLookDark.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'search l feel around fiddle feel', 'category': 'tutorialworld', 'key': 'look', 'no_prefix': ' search l feel around fiddle feel', 'tags': '', 'text': '\n Look around in darkness\n\n Usage:\n look\n\n Look around in the darkness, trying\n to find something.\n '}</em><a class="headerlink" href="#evennia.contrib.tutorials.tutorial_world.rooms.CmdLookDark.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

4
docs/1.0-dev/api/evennia.contrib.utils.git_integration.git_integration.html
View file

@ -208,7 +208,7 @@ git evennia pull - Pull the latest evennia code.</p>
<dl class="py attribute">
<dt id="evennia.contrib.utils.git_integration.git_integration.CmdGitEvennia.directory">
<code class="sig-name descname">directory</code><em class="property"> = '/tmp/tmpoztk3116/ce2d001e3510f9e8a27fa27418d49dd5bb334d6b/evennia'</em><a class="headerlink" href="#evennia.contrib.utils.git_integration.git_integration.CmdGitEvennia.directory" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">directory</code><em class="property"> = '/tmp/tmp_1kpuess/a77d568709ea6c7905c2d58d3cafa74bd7466278/evennia'</em><a class="headerlink" href="#evennia.contrib.utils.git_integration.git_integration.CmdGitEvennia.directory" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -269,7 +269,7 @@ git pull - Pull the latest code from your current branch.</p>
<dl class="py attribute">
<dt id="evennia.contrib.utils.git_integration.git_integration.CmdGit.directory">
<code class="sig-name descname">directory</code><em class="property"> = '/tmp/tmpoztk3116/ce2d001e3510f9e8a27fa27418d49dd5bb334d6b/evennia/game_template'</em><a class="headerlink" href="#evennia.contrib.utils.git_integration.git_integration.CmdGit.directory" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">directory</code><em class="property"> = '/tmp/tmp_1kpuess/a77d568709ea6c7905c2d58d3cafa74bd7466278/evennia/game_template'</em><a class="headerlink" href="#evennia.contrib.utils.git_integration.git_integration.CmdGit.directory" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">

4
docs/1.0-dev/api/evennia.utils.eveditor.html
View file

@ -336,7 +336,7 @@ indentation.</p>
<dl class="py attribute">
<dt id="evennia.utils.eveditor.CmdEditorGroup.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = [':q!', ':p', ':::', '::', ':DD', ':j', ':f', ':x', ':', ':s', ':&gt;', ':q', ':fi', ':h', ':wq', ':i', ':A', ':UU', ':y', ':!', ':r', ':echo', ':dw', ':I', ':w', ':dd', ':&lt;', ':uu', ':=', ':fd', ':S', ':u']</em><a class="headerlink" href="#evennia.utils.eveditor.CmdEditorGroup.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = [':h', ':r', ':dw', '::', ':uu', ':j', ':fi', ':S', ':dd', ':i', ':::', ':w', ':y', ':u', ':!', ':p', ':f', ':A', ':fd', ':echo', ':wq', ':I', ':=', ':s', ':&gt;', ':q!', ':x', ':DD', ':UU', ':&lt;', ':', ':q']</em><a class="headerlink" href="#evennia.utils.eveditor.CmdEditorGroup.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -364,7 +364,7 @@ efficient presentation.</p>
<dl class="py attribute">
<dt id="evennia.utils.eveditor.CmdEditorGroup.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': ':q! :p ::: :: :DD :j :f :x : :s :&gt; :q :fi :h :wq :i :A :UU :y :! :r :echo :dw :I :w :dd :&lt; :uu := :fd :S :u', 'category': 'general', 'key': ':editor_command_group', 'no_prefix': ' :q! :p ::: :: :DD :j :f :x : :s :&gt; :q :fi :h :wq :i :A :UU :y :! :r :echo :dw :I :w :dd :&lt; :uu := :fd :S :u', 'tags': '', 'text': '\n Commands for the editor\n '}</em><a class="headerlink" href="#evennia.utils.eveditor.CmdEditorGroup.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': ':h :r :dw :: :uu :j :fi :S :dd :i ::: :w :y :u :! :p :f :A :fd :echo :wq :I := :s :&gt; :q! :x :DD :UU :&lt; : :q', 'category': 'general', 'key': ':editor_command_group', 'no_prefix': ' :h :r :dw :: :uu :j :fi :S :dd :i ::: :w :y :u :! :p :f :A :fd :echo :wq :I := :s :&gt; :q! :x :DD :UU :&lt; : :q', 'tags': '', 'text': '\n Commands for the editor\n '}</em><a class="headerlink" href="#evennia.utils.eveditor.CmdEditorGroup.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

4
docs/1.0-dev/api/evennia.utils.evmenu.html
View file

@ -931,7 +931,7 @@ single question.</p>
<dl class="py attribute">
<dt id="evennia.utils.evmenu.CmdYesNoQuestion.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['abort', 'a', '__nomatch_command', 'no', 'y', 'n', 'yes']</em><a class="headerlink" href="#evennia.utils.evmenu.CmdYesNoQuestion.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['y', 'yes', 'no', '__nomatch_command', 'a', 'abort', 'n']</em><a class="headerlink" href="#evennia.utils.evmenu.CmdYesNoQuestion.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -957,7 +957,7 @@ single question.</p>
<dl class="py attribute">
<dt id="evennia.utils.evmenu.CmdYesNoQuestion.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'abort a __nomatch_command no y n yes', 'category': 'general', 'key': '__noinput_command', 'no_prefix': ' abort a __nomatch_command no y n yes', 'tags': '', 'text': '\n Handle a prompt for yes or no. Press [return] for the default choice.\n\n '}</em><a class="headerlink" href="#evennia.utils.evmenu.CmdYesNoQuestion.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'y yes no __nomatch_command a abort n', 'category': 'general', 'key': '__noinput_command', 'no_prefix': ' y yes no __nomatch_command a abort n', 'tags': '', 'text': '\n Handle a prompt for yes or no. Press [return] for the default choice.\n\n '}</em><a class="headerlink" href="#evennia.utils.evmenu.CmdYesNoQuestion.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

4
docs/1.0-dev/api/evennia.utils.evmore.html
View file

@ -137,7 +137,7 @@ the <strong>caller.msg()</strong> construct every time the page is updated.</p>
<dl class="py attribute">
<dt id="evennia.utils.evmore.CmdMore.aliases">
<code class="sig-name descname">aliases</code><em class="property"> = ['q', 'quit', 'next', 'a', 'abort', 'previous', 'top', 'e', 'end', 'p', 't', 'n']</em><a class="headerlink" href="#evennia.utils.evmore.CmdMore.aliases" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">aliases</code><em class="property"> = ['n', 'next', 'quit', 'end', 'p', 't', 'previous', 'e', 'a', 'top', 'abort', 'q']</em><a class="headerlink" href="#evennia.utils.evmore.CmdMore.aliases" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
@ -163,7 +163,7 @@ the <strong>caller.msg()</strong> construct every time the page is updated.</p>
<dl class="py attribute">
<dt id="evennia.utils.evmore.CmdMore.search_index_entry">
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'q quit next a abort previous top e end p t n', 'category': 'general', 'key': '__noinput_command', 'no_prefix': ' q quit next a abort previous top e end p t n', 'tags': '', 'text': '\n Manipulate the text paging. Catch no-input with aliases.\n '}</em><a class="headerlink" href="#evennia.utils.evmore.CmdMore.search_index_entry" title="Permalink to this definition"></a></dt>
<code class="sig-name descname">search_index_entry</code><em class="property"> = {'aliases': 'n next quit end p t previous e a top abort q', 'category': 'general', 'key': '__noinput_command', 'no_prefix': ' n next quit end p t previous e a top abort q', 'tags': '', 'text': '\n Manipulate the text paging. Catch no-input with aliases.\n '}</em><a class="headerlink" href="#evennia.utils.evmore.CmdMore.search_index_entry" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>

123
docs/1.0-dev/index.html
View file

@ -114,15 +114,16 @@ or the original github wiki. You have been warned.</p>
<p>This is the manual of <a class="reference external" href="https://www.evennia.com">Evennia</a>, the open source Python <code class="docutils literal notranslate"><span class="pre">MU*</span></code> creation system. Use the Search bar on the left to find or discover interesting articles.</p>
<ul class="simple">
<li><p><a class="reference internal" href="Evennia-Introduction.html"><span class="doc std std-doc">Introduction</span></a> - what is this Evennia thing?</p></li>
<li><p><a class="reference internal" href="Contributing.html"><span class="doc std std-doc">Getting help and Contribute</span></a> - when you get stuck or want to chip in</p></li>
<li><p><a class="reference internal" href="Contributing.html"><span class="doc std std-doc">Contributing and Getting help</span></a> - when you get stuck or want to chip in</p></li>
</ul>
<section id="setup">
<h2>Setup<a class="headerlink" href="#setup" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Setup/Setup-Overview.html#installation-and-running"><span class="std std-doc">Setup Quickstart</span></a> - installing Evennia and get going</p></li>
<li><p><a class="reference internal" href="Setup/Start-Stop-Reload.html"><span class="doc std std-doc">Starting, Stopping and Reloading</span></a> - how to manage the Evennia server</p></li>
<li><p><a class="reference internal" href="Setup/Setup-Overview.html#configuration"><span class="std std-doc">Configuration</span></a> - how to set up your server the way you like it</p></li>
<li><p><a class="reference internal" href="Setup/Setup-Overview.html#going-public"><span class="std std-doc">Going public</span></a> - taking your game online</p></li>
<li><p><a class="reference internal" href="Setup/Setup-Overview.html#installation-and-running"><span class="std std-doc">Installation</span></a> - getting started</p></li>
<li><p><a class="reference internal" href="Setup/Running-Evennia.html"><span class="doc std std-doc">Running the Game</span></a> - how to start, stop and reload Evennia</p></li>
<li><p><a class="reference internal" href="Setup/Updating-Evennia.html"><span class="doc std std-doc">Updating the Server</span></a> - how to update Evennia</p></li>
<li><p><a class="reference internal" href="Setup/Setup-Overview.html#configuration"><span class="std std-doc">Configuration</span></a> - how to set up Evennia the way you like it</p></li>
<li><p><a class="reference internal" href="Setup/Setup-Overview.html#going-online"><span class="std std-doc">Going Online</span></a> - bringing your game online</p></li>
</ul>
</section>
<section id="tutorials-and-howtos">
@ -171,6 +172,35 @@ or the original github wiki. You have been warned.</p>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Introduction.html#where-to-from-here">Where to from here?</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Setup/Running-Evennia.html">Start Stop Reload</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Setup/Running-Evennia.html#starting-evennia">Starting Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Running-Evennia.html#reloading">Reloading</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Running-Evennia.html#stopping">Stopping</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Running-Evennia.html#foreground-mode">Foreground mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Running-Evennia.html#resetting">Resetting</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Running-Evennia.html#rebooting">Rebooting</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Running-Evennia.html#status-and-info">Status and info</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Running-Evennia.html#killing-linux-mac-only">Killing (Linux/Mac only)</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Running-Evennia.html#django-options">Django options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Running-Evennia.html#advanced-handling-of-evennia-processes">Advanced handling of Evennia processes</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Setup/Running-Evennia.html#syntax-errors-during-live-development">Syntax errors during live development</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Setup/Updating-Evennia.html">Updating Evennia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Setup/Updating-Evennia.html#if-you-installed-with-pip">If you installed with <code class="docutils literal notranslate"><span class="pre">pip</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Updating-Evennia.html#if-you-installed-with-git">If you installed with <code class="docutils literal notranslate"><span class="pre">git</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Updating-Evennia.html#if-you-installed-with-docker">If you installed with <code class="docutils literal notranslate"><span class="pre">docker</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Updating-Evennia.html#resetting-your-database">Resetting your database</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Setup/Updating-Evennia.html#sqlite3-default">SQLite3 (default)</a></li>
<li class="toctree-l3"><a class="reference internal" href="Setup/Updating-Evennia.html#postgresql">PostgreSQL</a></li>
<li class="toctree-l3"><a class="reference internal" href="Setup/Updating-Evennia.html#mysql-mariadb">MySQL/MariaDB</a></li>
<li class="toctree-l3"><a class="reference internal" href="Setup/Updating-Evennia.html#what-are-database-migrations">What are database migrations?</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Setup/Setup-Overview.html">Server Setup and Life</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Setup/Setup-Overview.html#installation-and-running">Installation and running</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Setup/Installation.html">Installation</a></li>
@ -180,7 +210,8 @@ or the original github wiki. You have been warned.</p>
<li class="toctree-l3"><a class="reference internal" href="Setup/Installation-Android.html">Installing on Android</a></li>
<li class="toctree-l3"><a class="reference internal" href="Setup/Installation-Upgrade.html">Upgrading an existing installation</a></li>
<li class="toctree-l3"><a class="reference internal" href="Setup/Installation-Non-Interactive.html">Non-interactive setup</a></li>
<li class="toctree-l3"><a class="reference internal" href="Setup/Start-Stop-Reload.html">Start Stop Reload</a></li>
<li class="toctree-l3"><a class="reference internal" href="Setup/Running-Evennia.html">Start Stop Reload</a></li>
<li class="toctree-l3"><a class="reference internal" href="Setup/Updating-Evennia.html">Updating Evennia</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Setup-Overview.html#configuration">Configuration</a><ul>
@ -193,7 +224,7 @@ or the original github wiki. You have been warned.</p>
<li class="toctree-l3"><a class="reference internal" href="Setup/Channels-to-Twitter.html">Connect Evennia to Twitter</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Setup/Setup-Overview.html#going-public">Going public</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Setup/Setup-Overview.html#going-online">Going Online</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Setup/Evennia-Game-Index.html">Evennia Game Index</a></li>
<li class="toctree-l3"><a class="reference internal" href="Setup/Online-Setup.html">Online Setup</a></li>
<li class="toctree-l3"><a class="reference internal" href="Setup/Client-Support-Grid.html">Client Support Grid</a></li>
@ -360,18 +391,62 @@ or the original github wiki. You have been warned.</p>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Coding/Coding-Overview.html">Coding and development help</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Coding/Coding-Overview.html#setting-up-a-workflow">Setting up a workflow</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Coding/Version-Control.html">Version Control</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Updating-Your-Game.html">Updating Your Game</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding/Version-Control.html">Coding using Version Control</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Coding/Version-Control.html#setting-up-git">Setting up Git</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Version-Control.html#common-git-commands">Common Git commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Version-Control.html#putting-your-game-dir-under-version-control">Putting your game dir under version control</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Version-Control.html#contributing-to-evennia">Contributing to Evennia</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Version-Control.html#troubleshooting">Troubleshooting</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Coding/Coding-Overview.html#coding-away">Coding away</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-Introduction.html">Coding Introduction</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-FAQ.html">Coding FAQ</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Debugging.html">Debugging</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Unit-Testing.html">Unit Testing</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Profiling.html">Profiling</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Quirks.html">Quirks</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding/Debugging.html">Debugging</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Coding/Debugging.html#debugging-evennia">Debugging Evennia</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Debugging.html#a-simple-example-using-pdb">A simple example using pdb</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Debugging.html#cheat-sheet-of-pdb-pudb-commands">Cheat-sheet of pdb/pudb commands</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Coding/Unit-Testing.html">Unit Testing</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Coding/Unit-Testing.html#running-the-evennia-test-suite">Running the Evennia test suite</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Unit-Testing.html#running-tests-for-your-game-dir">Running tests for your game dir</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Unit-Testing.html#writing-new-tests">Writing new tests</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Unit-Testing.html#using-the-evennia-testing-classes">Using the Evennia testing classes</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Unit-Testing.html#unit-testing-contribs-with-custom-models">Unit testing contribs with custom models</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Unit-Testing.html#a-note-on-making-the-test-runner-faster">A note on making the test runner faster</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Coding/Profiling.html">Profiling</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Coding/Profiling.html#simple-timer-tests">Simple timer tests</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Profiling.html#using-cprofile">Using cProfile</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Profiling.html#the-dummyrunner">The Dummyrunner</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Coding/Evennia-Code-Style.html">Evennia Code Style</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Coding/Evennia-Code-Style.html#main-code-style-specification">Main code style specification</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Evennia-Code-Style.html#code-docstrings">Code Docstrings</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Evennia-Code-Style.html#default-command-docstrings">Default Command Docstrings</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Evennia-Code-Style.html#tools-for-auto-linting">Tools for auto-linting</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Coding/Coding-FAQ.html">Coding FAQ</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-FAQ.html#removing-default-commands">Removing default commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-FAQ.html#preventing-character-from-moving-based-on-a-condition">Preventing character from moving based on a condition</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-FAQ.html#reference-initiating-object-in-an-evmenu-command">Reference initiating object in an EvMenu command.</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-FAQ.html#selectively-turn-off-commands-in-a-room">Selectively turn off commands in a room</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-FAQ.html#select-command-based-on-a-condition">Select Command based on a condition</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-FAQ.html#automatically-updating-code-when-reloading">Automatically updating code when reloading</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-FAQ.html#changing-all-exit-messages">Changing all exit messages</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-FAQ.html#add-parsing-with-the-to-delimiter">Add parsing with the “to” delimiter</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Coding-FAQ.html#non-latin-characters-in-evtable">Non-latin characters in EvTable</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Coding/Quirks.html">Quirks</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Coding/Quirks.html#forgetting-to-use-reload-to-see-changes-to-your-typeclasses">Forgetting to use <code class="docutils literal notranslate"><span class="pre">reload</span></code> to see changes to your typeclasses</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Quirks.html#web-admin-to-create-new-account">Web admin to create new Account</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Quirks.html#mutable-attributes-and-their-connection-to-the-database">Mutable attributes and their connection to the database</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Quirks.html#commands-are-matched-by-name-or-alias">Commands are matched by name <em>or</em> alias</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Quirks.html#objects-turning-to-defaultobject">Objects turning to <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Quirks.html#overriding-of-magic-methods">Overriding of magic methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Quirks.html#things-to-remember-about-the-flat-api">Things to remember about the flat API</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Coding/Coding-Overview.html#evennia-changelog">Evennia Changelog</a><ul>
@ -381,7 +456,7 @@ or the original github wiki. You have been warned.</p>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Coding/Coding-Overview.html#third-party-integrations">Third-party integrations</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Coding/Continuous-Integration.html">Continuous Integration</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Continuous-Integration.html">Continuous Integration (CI)</a></li>
<li class="toctree-l3"><a class="reference internal" href="Coding/Setting-up-PyCharm.html">Setting up PyCharm with Evennia</a></li>
</ul>
</li>
@ -513,15 +588,13 @@ or the original github wiki. You have been warned.</p>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Contributing.html">How To Contribute And Get Help</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Contributing.html#community-and-spreading-the-word">Community and Spreading the word</a></li>
<li class="toctree-l2"><a class="reference internal" href="Contributing.html#help-with-documentation">Help with Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="Contributing.html#helping-with-code">Helping with code</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Contributing.html#using-a-forked-reposity">Using a Forked reposity</a></li>
<li class="toctree-l3"><a class="reference internal" href="Contributing.html#contributing-with-patches">Contributing with Patches</a></li>
<li class="toctree-l3"><a class="reference internal" href="Contributing.html#making-an-evennia-contrib">Making an Evennia contrib</a></li>
<li class="toctree-l2"><a class="reference internal" href="Contributing.html#getting-help">Getting Help</a></li>
<li class="toctree-l2"><a class="reference internal" href="Contributing.html#giving-help">Giving Help</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Contributing.html#help-with-documentation">Help with Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="Contributing.html#helping-with-code">Helping with code</a></li>
<li class="toctree-l3"><a class="reference internal" href="Contributing.html#helping-with-donations">Helping with Donations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Contributing.html#donations">Donations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Contributing-Docs.html">Contributing to Evennia Docs</a><ul>

BIN
docs/1.0-dev/objects.inv
View file

Binary file not shown.

2
docs/1.0-dev/searchindex.js
View file

File diff suppressed because one or more lines are too long