Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-24 16:56:32 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated HTML docs

Browse source
This commit is contained in:
Griatch 2021-05-16 00:06:01 +02:00
parent 58f5ece91b
commit 1bbc93507a
1000 changed files with 39106 additions and 33861 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.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" />
@ -37,23 +38,23 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="coding-introduction">
<section 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>
<div class="section" id="start-with-the-tutorial">
<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="../Howto/Starting/Part1/Starting-Part1.html"><span class="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.</p>
</div>
<div class="section" id="python">
</section>
<section id="python">
<h2>Python<a class="headerlink" href="#python" title="Permalink to this headline"></a></h2>
<p>Evennia is developed using Python. Even if you are more of a designer than a coder, it is wise to
learn how to read and understand basic Python code. If you are new to Python, or need a refresher,
take a look at our <a class="reference internal" href="../Howto/Starting/Part1/Python-basic-introduction.html"><span class="doc">Python introduction</span></a>.</p>
</div>
<div class="section" id="explore-evennia-interactively">
</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>When new to Evennia it can be hard to find things or figure out what is available. Evennia offers a
special interactive python shell that allows you to experiment and try out things. It’s recommended
@ -74,7 +75,7 @@ are some simple commands to get started:</p>
<p>That is, enter <code class="docutils literal notranslate"><span class="pre">evennia.</span></code> and press the <code class="docutils literal notranslate"><span class="pre">&lt;TAB&gt;</span></code> key. This will show you all the resources made
available at the top level of Evennia’s “flat API”. See the <a class="reference internal" href="../Evennia-API.html"><span class="doc">flat API</span></a> page for more
info on how to explore it efficiently.</p>
<div class="section" id="jupyter-notebook-support">
<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
@ -96,22 +97,22 @@ 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"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">evennia</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><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>
</td></tr></table></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>
</div>
<div class="section" id="more-exploration">
</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">Evennia Component overview</span></a>. The <a class="reference internal" href="../Howto/Howto-Overview.html"><span class="doc">Tutorials</span></a> section also contains a growing collection
of system- or implementation-specific help.</p>
</div>
</div>
<div class="section" id="use-a-python-syntax-checker">
</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
@ -122,13 +123,13 @@ many python syntax checkers out there. A fast and easy one is
<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>
</div>
<div class="section" id="plan-before-you-code">
</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="../Howto/Starting/Part2/Game-Planning.html"><span class="doc">Game Planning</span></a>
page. It might hopefully help you avoid some common pitfalls and time sinks.</p>
</div>
<div class="section" id="code-in-your-game-folder-not-in-the-evennia-repository">
</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
@ -137,8 +138,8 @@ 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 <a class="reference external" href="https://github.com/evennia/evennia/issues/new/choose">Feature
Request</a> about it. Same goes for [bugs][bug]. If you add features or fix bugs
yourself, please consider <a class="reference internal" href="../Contributing.html"><span class="doc">Contributing</span></a> your changes upstream!</p>
</div>
<div class="section" id="learn-to-read-tracebacks">
</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
@ -156,8 +157,8 @@ module holding your custom class. Since such a module is not valid Python, Evenn
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>
</div>
<div class="section" id="docs-are-here-to-help-you">
</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
@ -165,13 +166,13 @@ and knowing what is possible can often give you a lot of new cool game ideas. Th
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="http://webchat.freenode.net/?channels=evennia">irc
chat</a> are also there for you.</p>
</div>
<div class="section" id="the-most-important-point">
</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>
<p><a class="reference external" href="https://github.com/evennia/evennia/issues/new?title=Bug%3a+%3Cdescriptive+title+here%3E&amp;body=%23%23%23%23+Steps+to+reproduce+the+issue%3a%0D%0A%0D%0A1.+%0D%0A2.+%0D%0A3.+%0D%0A%0D%0A%23%23%23%23+What+I+expect+to+see+and+what+I+actually+see+%28tracebacks%2c+error+messages+etc%29%3a%0D%0A%0D%0A%0D%0A%0D%0A%23%23%23%23+Extra+information%2c+such+as+Evennia+revision%2frepo%2fbranch%2c+operating+system+and+ideas+for+how+to+solve%3a%0D%0A%0D%0A">bug</a></p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

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

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Coding and development help &#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" />
@ -45,27 +46,27 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="coding-and-development-help">
<section id="coding-and-development-help">
<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>
<div class="section" id="find-your-way">
<section id="find-your-way">
<h2>Find your way<a class="headerlink" href="#find-your-way" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="../Howto/Starting/Part1/Gamedir-Overview.html"><span class="doc">Directory-Overview</span></a></p></li>
<li><p><a class="reference internal" href="Quirks.html"><span class="doc">Quirks of Evennia</span></a></p></li>
</ul>
</div>
<div class="section" id="setting-up-a-workflow">
</section>
<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>
<ul class="simple">
<li><p><a class="reference internal" href="Setting-up-PyCharm.html"><span class="doc">Setting up PyCharm</span></a></p></li>
<li><p><a class="reference internal" href="Version-Control.html"><span class="doc">Using Version-Control</span></a></p></li>
<li><p><a class="reference internal" href="Updating-Your-Game.html"><span class="doc">Updating Evennia sources</span></a></p></li>
</ul>
</div>
<div class="section" id="coding-away">
</section>
<section id="coding-away">
<h2>Coding away<a class="headerlink" href="#coding-away" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Coding-Introduction.html"><span class="doc">Coding Introduction</span></a></p></li>
@ -73,8 +74,8 @@ to you, but some things may still be useful.</p>
<li><p><a class="reference internal" href="Unit-Testing.html"><span class="doc">Adding unit-tests</span></a></p></li>
<li><p><a class="reference internal" href="Flat-API.html"><span class="doc">Things to remember when importing from evennia</span></a></p></li>
</ul>
</div>
<div class="section" id="advanced-concepts">
</section>
<section id="advanced-concepts">
<h2>Advanced concepts<a class="headerlink" href="#advanced-concepts" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Continuous-Integration.html"><span class="doc">Continuous Integration</span></a></p>
@ -84,8 +85,8 @@ to you, but some things may still be useful.</p>
</li>
<li><p><a class="reference internal" href="Profiling.html"><span class="doc">Profiling</span></a></p></li>
</ul>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

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

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Continuous Integration &#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" />
@ -37,13 +38,13 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="continuous-integration">
<section 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 MUSH development systems is that Evennia is
capable of integrating into enterprise level integration environments and source control. Because of
this, it can also be the subject of automation for additional convenience, allowing a more
streamlined development environment.</p>
<div class="section" id="what-is-continuous-integration">
<section id="what-is-continuous-integration">
<h2>What is Continuous Integration?<a class="headerlink" href="#what-is-continuous-integration" 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 several times a day.
@ -57,8 +58,8 @@ Each check-in is then verified by an automated build, allowing teams to detect p
<li><p>Publish those files to the server directory</p></li>
<li><p>Reload the game.</p></li>
</ul>
</div>
<div class="section" id="preparation">
</section>
<section id="preparation">
<h2>Preparation<a class="headerlink" href="#preparation" title="Permalink to this headline"></a></h2>
<p>To prepare a CI environment for your <code class="docutils literal notranslate"><span class="pre">MU*</span></code>, it will be necessary to set up some prerequisite
software for your server.</p>
@ -76,8 +77,8 @@ Guide</a></p></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="linux-teamcity-setup">
</section>
<section id="linux-teamcity-setup">
<h2>Linux TeamCity Setup<a class="headerlink" href="#linux-teamcity-setup" title="Permalink to this headline"></a></h2>
<p>For this part of the guide, an example setup will be provided for administrators running a TeamCity
build integration environment on Linux.</p>
@ -85,14 +86,14 @@ build integration environment on Linux.</p>
at <code class="docutils literal notranslate"><span class="pre">http://&lt;your</span> <span class="pre">server&gt;:8111/</span></code>.</p>
<p>Create a new project named “Evennia” and in it construct a new template called continuous-
integration.</p>
<div class="section" id="a-quick-overview">
<section id="a-quick-overview">
<h3>A Quick Overview<a class="headerlink" href="#a-quick-overview" title="Permalink to this headline"></a></h3>
<p>Templates are fancy objects in TeamCity that allow an administrator to define build steps that are
shared between one or more build projects. Assigning a VCS Root (Source Control) is unnecessary at
this stage, primarily you’ll be worrying about the build steps and your default parameters (both
visible on the tabs to the left.)</p>
</div>
<div class="section" id="template-setup">
</section>
<section id="template-setup">
<h3>Template Setup<a class="headerlink" href="#template-setup" title="Permalink to this headline"></a></h3>
<p>In this template, you’ll be outlining the steps necessary to build your specific game. (A number of
sample scripts are provided under this section below!) Click Build Steps and prepare your general
@ -112,14 +113,14 @@ from your development environment.</p></li>
<ul>
<li><p>Create a build step with the name: Transform Configuration</p></li>
<li><p>For the script add:</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3
4
5
6
7
8</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span>
<span class="normal">7</span>
<span class="normal">8</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
<span class="c1"># Replaces the game configuration with one </span>
<span class="c1"># appropriate for this deployment.</span>
@ -171,20 +172,20 @@ step to: %game.dir%</p></li>
</ul>
</li>
<li><p>In this script include:</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
<span class="c1"># Update the DB migration</span>
<span class="nv">LOGDIR</span><span class="o">=</span><span class="s2">&quot;server/logs&quot;</span>
@ -205,20 +206,20 @@ evennia makemigrations
<ul>
<li><p>If you’re using SQLLite on your game, it will be prudent to change working directory on this
step to: %game.dir%</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
<span class="c1"># Apply the database migration.</span>
<span class="nv">LOGDIR</span><span class="o">=</span><span class="s2">&quot;server/logs&quot;</span>
@ -246,19 +247,19 @@ to where our game actually exists on the local server.</p>
<ul>
<li><p>If you’re using SQLLite on your game, be sure to order this step ABOVE the Database Migration
steps. The build order will matter!</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
<span class="c1"># Publishes the build to the proper build directory.</span>
<span class="nv">DIRECTORY</span><span class="o">=</span><span class="s2">&quot;%game.dir%&quot;</span>
@ -282,25 +283,25 @@ chmod -R <span class="m">775</span> <span class="s2">&quot;</span><span class="n
<li><p>Create a new script called “Reload Game”:</p>
<ul>
<li><p>The working directory on this build step will be: %game.dir%</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
<span class="c1"># Apply the database migration.</span>
<span class="nv">LOGDIR</span><span class="o">=</span><span class="s2">&quot;server/logs&quot;</span>
@ -327,8 +328,8 @@ chmod -R <span class="m">775</span> <span class="s2">&quot;</span><span class="n
</ul>
<p>Now the template is ready for use! It would be useful this time to revisit the parameters page and
set the evenv parameter to the directory where your virtualenv exists: IE “/srv/mush/evenv”.</p>
</div>
<div class="section" id="creating-the-project">
</section>
<section id="creating-the-project">
<h3>Creating the Project<a class="headerlink" href="#creating-the-project" title="Permalink to this headline"></a></h3>
<p>Now it’s time for the last few steps to set up a CI environment.</p>
<ul class="simple">
@ -352,9 +353,9 @@ branch/version control that you are using.</p></li>
<p>And you’re done! At this point, you can return to the project overview page and queue a new build
for your game. If everything was set up correctly, the build will complete successfully. Additional
build steps could be added or removed at this point, adding some features like Unit Testing or more!</p>
</div>
</div>
</div>
</section>
</section>
</section>
<div class="clearer"></div>

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

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Debugging &#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" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="debugging">
<section 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.
@ -52,13 +53,13 @@ available out-of-the-box.</p></li>
<li><p><a class="reference external" href="https://pypi.org/project/pudb/">PuDB</a> is a third-party debugger that has a slightly more
‘graphical’, curses-based user interface than pdb. It is installed with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">pudb</span></code>.</p></li>
</ul>
<div class="section" id="debugging-evennia">
<section id="debugging-evennia">
<h2>Debugging Evennia<a class="headerlink" href="#debugging-evennia" title="Permalink to this headline"></a></h2>
<p>To run Evennia with the debugger, follow these steps:</p>
<ol>
<li><p>Find the point in the code where you want to have more insight. Add the following line at that
point.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">set_trace</span><span class="p">;</span><span class="n">set_trace</span><span class="p">()</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">set_trace</span><span class="p">;</span><span class="n">set_trace</span><span class="p">()</span>
</pre></div>
</td></tr></table></div>
</li>
@ -69,36 +70,36 @@ terminal.</p></li>
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"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="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>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><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>
</td></tr></table></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>
</div>
<div class="section" id="a-simple-example-using-pdb">
</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>
<p>The debugger is useful in different cases, but to begin with, let’s see it working in a command.
Add the following test command (which has a range of deliberate errors) and also add it to your
default cmdset. Then restart Evennia in interactive mode with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code>.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># In file commands/command.py</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># In file commands/command.py</span>
<span class="k">class</span> <span class="nc">CmdTest</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
@ -129,7 +130,7 @@ in your console, and you will find it here. Below is an example with <code class
</pre></div>
</div>
<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>
<div class="section" id="listing-surrounding-lines-of-code">
<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>
@ -153,8 +154,8 @@ yourself in lots of different files, you sometimes need to see what’s around i
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>
</div>
<div class="section" id="examining-variables">
</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
@ -181,8 +182,8 @@ executing, which can help to check that your fix is actually working when you ha
error. If you have variable names that will conflict with <code class="docutils literal notranslate"><span class="pre">pdb</span></code> commands (like a <code class="docutils literal notranslate"><span class="pre">list</span></code>
variable), you can prefix your variable with <code class="docutils literal notranslate"><span class="pre">!</span></code>, to tell <code class="docutils literal notranslate"><span class="pre">pdb</span></code> that what follows is Python code.</p>
</div></blockquote>
</div>
<div class="section" id="executing-the-current-line">
</section>
<section id="executing-the-current-line">
<h3>Executing the current line<a class="headerlink" href="#executing-the-current-line" title="Permalink to this headline"></a></h3>
<p>It’s time we asked <code class="docutils literal notranslate"><span class="pre">pdb</span></code> to execute the current line. To do so, use the <code class="docutils literal notranslate"><span class="pre">next</span></code> command. You can
shorten it by just typing <code class="docutils literal notranslate"><span class="pre">n</span></code>:</p>
@ -196,11 +197,11 @@ shorten it by just typing <code class="docutils literal notranslate"><span class
<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"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="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>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><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>
</td></tr></table></div>
</div>
<div class="section" id="letting-the-program-run">
</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
@ -273,8 +274,8 @@ experimenting!</p>
<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>
</div>
<div class="section" id="stepping-through-a-function">
</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
@ -288,9 +289,9 @@ function/method and you can then use <code class="docutils literal notranslate">
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>
</div>
</div>
<div class="section" id="cheat-sheet-of-pdb-pudb-commands">
</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>
<p>PuDB and Pdb share the same commands. The only real difference is how it’s presented. The <code class="docutils literal notranslate"><span class="pre">look</span></code>
command is not needed much in <code class="docutils literal notranslate"><span class="pre">pudb</span></code> since it displays the code directly in its user interface.</p>
@ -307,8 +308,8 @@ this directly). |
<code class="docutils literal notranslate"><span class="pre">&lt;RETURN&gt;</span></code> to repeat it). |</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>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

21
docs/1.0-dev/Coding/Flat-API.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Things to remember about the flat API &#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" />
@ -37,29 +38,29 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="things-to-remember-about-the-flat-api">
<section id="things-to-remember-about-the-flat-api">
<h1>Things to remember about the flat API<a class="headerlink" href="#things-to-remember-about-the-flat-api" title="Permalink to this headline"></a></h1>
<p>The flat API is a series of ‘shortcuts’ on the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> main library root (defined in
<code class="docutils literal notranslate"><span class="pre">evennia/__init__.py</span></code>). Its componentas are documented <a class="reference internal" href="../Evennia-API.html"><span class="doc">as part of the auto-documentation</span></a>.</p>
<div class="section" id="to-remember-when-importing-from-evennia">
<section id="to-remember-when-importing-from-evennia">
<h2>To remember when importing from <code class="docutils literal notranslate"><span class="pre">evennia</span></code><a class="headerlink" href="#to-remember-when-importing-from-evennia" title="Permalink to this headline"></a></h2>
<p>Properties on the root of the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> package are <em>not</em> modules in their own right. They are just
shortcut properties stored in the <code class="docutils literal notranslate"><span class="pre">evennia/__init__.py</span></code> module. That means that you cannot use dot-
notation to <code class="docutils literal notranslate"><span class="pre">import</span></code> nested module-names over <code class="docutils literal notranslate"><span class="pre">evennia</span></code>. The rule of thumb is that you cannot use
<code class="docutils literal notranslate"><span class="pre">import</span></code> for more than one level down. Hence you can do</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">evennia</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">evennia</span>
<span class="nb">print</span><span class="p">(</span><span class="n">evennia</span><span class="o">.</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">CmdLook</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>or import one level down</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">default_cmds</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">default_cmds</span>
<span class="nb">print</span><span class="p">(</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">CmdLook</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>but you <em>cannot</em> import two levels down</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.default_cmds</span> <span class="kn">import</span> <span class="n">CmdLook</span> <span class="c1"># error!</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.default_cmds</span> <span class="kn">import</span> <span class="n">CmdLook</span> <span class="c1"># error!</span>
</pre></div>
</td></tr></table></div>
<p>This will give you an <code class="docutils literal notranslate"><span class="pre">ImportError</span></code> telling you that the module <code class="docutils literal notranslate"><span class="pre">default_cmds</span></code> cannot be found -
@ -69,8 +70,8 @@ bypass the root package and import directly from from the real location. For exa
<code class="docutils literal notranslate"><span class="pre">evennia.DefaultObject</span></code> is a shortcut to <code class="docutils literal notranslate"><span class="pre">evennia.objects.objects.DefaultObject</span></code>. Using this full
path will have the import mechanism work normally. See <code class="docutils literal notranslate"><span class="pre">evennia/__init__.py</span></code> to see where the
package imports from.</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

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

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Profiling &#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" />
@ -37,10 +38,10 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="profiling">
<section 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>
<div class="section" id="introduction">
<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
@ -54,18 +55,18 @@ wisdom</a>:</p>
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>
</div>
<div class="section" id="simple-timer-tests">
</section>
<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 order to test if it
is faster to use a <code class="docutils literal notranslate"><span class="pre">for</span></code> loop or a list comprehension you could use the following code:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3
4
5
6
7</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">timeit</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span>
<span class="normal">7</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">timeit</span>
<span class="c1"># Time to do 1000000 for loops</span>
<span class="n">timeit</span><span class="o">.</span><span class="n">timeit</span><span class="p">(</span><span class="s2">&quot;for i in range(100):</span><span class="se">\n</span><span class="s2"> a.append(i)&quot;</span><span class="p">,</span> <span class="n">setup</span><span class="o">=</span><span class="s2">&quot;a = []&quot;</span><span class="p">)</span>
<span class="o">&lt;&lt;&lt;</span> <span class="mf">10.70982813835144</span>
@ -80,8 +81,8 @@ like <code class="docutils literal notranslate"><span class="pre">a</span> <span
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>
</div>
<div class="section" id="using-cprofile">
</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
@ -103,8 +104,8 @@ likely also mess with the profiler. Instead either use <code class="docutils lit
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>
</div>
<div class="section" id="analyzing-the-profile">
</section>
<section id="analyzing-the-profile">
<h2>Analyzing the profile<a class="headerlink" href="#analyzing-the-profile" title="Permalink to this headline"></a></h2>
<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>
@ -119,8 +120,8 @@ Python profiles you also need the wrapper script
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>
</div>
<div class="section" id="the-dummyrunner">
</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
@ -145,7 +146,7 @@ extra settings line when running a public server.</p>
settings file is <code class="docutils literal notranslate"><span class="pre">evennia/server/server/profiling/dummyrunner_settings.py</span></code> but you shouldn’t modify
this directly. Rather create/copy the default file to <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/</span></code> and modify it there. To
make sure to use your file over the default, add the following line to your settings file:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">DUMMYRUNNER_SETTINGS_MODULE</span> <span class="o">=</span> <span class="s2">&quot;server/conf/dummyrunner_settings.py&quot;</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">DUMMYRUNNER_SETTINGS_MODULE</span> <span class="o">=</span> <span class="s2">&quot;server/conf/dummyrunner_settings.py&quot;</span>
</pre></div>
</td></tr></table></div>
<blockquote>
@ -155,8 +156,8 @@ intensely than an equal number of human players. A good dummy number to start wi
<p>Once you have the dummyrunner running, stop it with <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code>.</p>
<p>Generally, the dummyrunner system makes for a decent test of general performance; but it is of
course hard to actually mimic human user behavior. For this, actual real-game testing is required.</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

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

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Quirks &#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" />
@ -37,19 +38,19 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="quirks">
<section id="quirks">
<h1>Quirks<a class="headerlink" href="#quirks" title="Permalink to this headline"></a></h1>
<p>This is a list of various quirks or common stumbling blocks that people often ask about or report
when using (or trying to use) Evennia. They are not bugs.</p>
<div class="section" id="forgetting-to-use-reload-to-see-changes-to-your-typeclasses">
<section id="forgetting-to-use-reload-to-see-changes-to-your-typeclasses">
<h2>Forgetting to use &#64;reload to see changes to your typeclasses<a class="headerlink" href="#forgetting-to-use-reload-to-see-changes-to-your-typeclasses" title="Permalink to this headline"></a></h2>
<p>Firstly: Reloading the server is a safe and usually quick operation which will <em>not</em> disconnect any
accounts.</p>
<p>New users tend to forget this step. When editing source code (such as when tweaking typeclasses and
commands or adding new commands to command sets) you need to either use the in-game <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code>
command or, from the command line do <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">evennia.py</span> <span class="pre">reload</span></code> before you see your changes.</p>
</div>
<div class="section" id="web-admin-to-create-new-account">
</section>
<section id="web-admin-to-create-new-account">
<h2>Web admin to create new Account<a class="headerlink" href="#web-admin-to-create-new-account" title="Permalink to this headline"></a></h2>
<p>If you use the default login system and are trying to use the Web admin to create a new Player
account, you need to consider which <code class="docutils literal notranslate"><span class="pre">MULTIACCOUNT_MODE</span></code> you are in. If you are in
@ -62,19 +63,19 @@ create the Account from. This should set everything up for you. Otherwise you ne
the “account” property on the Character and the “character” property on the Account to point to each
other. You must also set the lockstring of the Character to allow the Account to “puppet” this
particular character.</p>
</div>
<div class="section" id="mutable-attributes-and-their-connection-to-the-database">
</section>
<section id="mutable-attributes-and-their-connection-to-the-database">
<h2>Mutable attributes and their connection to the database<a class="headerlink" href="#mutable-attributes-and-their-connection-to-the-database" title="Permalink to this headline"></a></h2>
<p>When storing a mutable object (usually a list or a dictionary) in an Attribute</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="nb">object</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">]</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="nb">object</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">]</span>
</pre></div>
</td></tr></table></div>
<p>you should know that the connection to the database is retained also if you later extract that
Attribute into another variable (what is stored and retrieved is actually a <code class="docutils literal notranslate"><span class="pre">PackedList</span></code> or a
<code class="docutils literal notranslate"><span class="pre">PackedDict</span></code> that works just like their namesakes except they save themselves to the database when
changed). So if you do</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">alist</span> <span class="o">=</span> <span class="nb">object</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">alist</span> <span class="o">=</span> <span class="nb">object</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span>
<span class="n">alist</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
@ -82,10 +83,10 @@ changed). So if you do</p>
<code class="docutils literal notranslate"><span class="pre">[1,2,3,4]</span></code></p>
<p>If you don’t want this, Evennia provides a way to stably disconnect the mutable from the database by
use of <code class="docutils literal notranslate"><span class="pre">evennia.utils.dbserialize.deserialize</span></code>:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3
4</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.utils.dbserialize</span> <span class="kn">import</span> <span class="n">deserialize</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.utils.dbserialize</span> <span class="kn">import</span> <span class="n">deserialize</span>
<span class="n">blist</span> <span class="o">=</span> <span class="n">deserialize</span><span class="p">(</span><span class="nb">object</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">mylist</span><span class="p">)</span>
<span class="n">blist</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>
@ -93,8 +94,8 @@ use of <code class="docutils literal notranslate"><span class="pre">evennia.util
</td></tr></table></div>
<p>The property <code class="docutils literal notranslate"><span class="pre">blist</span></code> is now <code class="docutils literal notranslate"><span class="pre">[1,2,3,4]</span></code> whereas <code class="docutils literal notranslate"><span class="pre">object.db.mylist</span></code> remains unchanged. If you want to
update the database you’d need to explicitly re-assign the updated data to the <code class="docutils literal notranslate"><span class="pre">mylist</span></code> Attribute.</p>
</div>
<div class="section" id="commands-are-matched-by-name-or-alias">
</section>
<section id="commands-are-matched-by-name-or-alias">
<h2>Commands are matched by name <em>or</em> alias<a class="headerlink" href="#commands-are-matched-by-name-or-alias" title="Permalink to this headline"></a></h2>
<p>When merging <a class="reference internal" href="../Components/Commands.html"><span class="doc">command sets</span></a> it’s important to remember that command objects are identified
<em>both</em> by key <em>or</em> alias. So if you have a command with a key <code class="docutils literal notranslate"><span class="pre">look</span></code> and an alias <code class="docutils literal notranslate"><span class="pre">ls</span></code>, introducing
@ -102,8 +103,8 @@ another command with a key <code class="docutils literal notranslate"><span clas
This usually means merging cmdsets will overload one of them depending on priority. Whereas this is
logical once you know how command objects are handled, it may be confusing if you are just looking
at the command strings thinking they are parsed as-is.</p>
</div>
<div class="section" id="objects-turning-to-defaultobject">
</section>
<section id="objects-turning-to-defaultobject">
<h2>Objects turning to <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code><a class="headerlink" href="#objects-turning-to-defaultobject" title="Permalink to this headline"></a></h2>
<p>A common confusing error for new developers is finding that one or more objects in-game are suddenly
of the type <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code> rather than the typeclass you wanted it to be. This happens when you
@ -113,8 +114,8 @@ Evennia will solve this by printing the full traceback to the terminal/console a
back to the safe <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code> until you fix the problem and reload. Most errors of this kind will
be caught by any good text editors. Keep an eye on the terminal/console during a reload to catch
such errors - you may have to scroll up if your window is small.</p>
</div>
<div class="section" id="overriding-of-magic-methods">
</section>
<section id="overriding-of-magic-methods">
<h2>Overriding of magic methods<a class="headerlink" href="#overriding-of-magic-methods" title="Permalink to this headline"></a></h2>
<p>Python implements a system of <a class="reference external" href="https://docs.python.org/3/reference/datamodel.html#emulating-container-types">magic
methods</a>, usually
@ -132,8 +133,8 @@ interfere with the return values from the methods Evennia expects to be both pre
can result in very inconsistent and hard-to-diagnose errors.</p>
<p>The moral of the story– it can be dangerous to tinker with magic methods on typeclassed objects.
Try to avoid doing so.</p>
</div>
<div class="section" id="known-upstream-bugs">
</section>
<section id="known-upstream-bugs">
<h2>Known upstream bugs<a class="headerlink" href="#known-upstream-bugs" title="Permalink to this headline"></a></h2>
<ul>
<li><p>There is currently (Autumn 2017) a bug in the <code class="docutils literal notranslate"><span class="pre">zope.interface</span></code> installer on some Linux Ubuntu
@ -142,14 +143,14 @@ the server not starting with an error that <code class="docutils literal notrans
shows it’s installed. The reason is a missing empty <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file at the root of the zope
package. If the virtualenv is named “evenv” as suggested in the <a class="reference internal" href="../Setup/Setup-Quickstart.html"><span class="doc">Setup Quickstart</span></a>
instructions, use the following command to fix it:</p>
<div class="highlight-shell notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span>touch evenv/local/lib/python2.7/site-packages/zope/__init__.py
<div class="highlight-shell notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span>touch evenv/local/lib/python2.7/site-packages/zope/__init__.py
</pre></div>
</td></tr></table></div>
<p>This will create the missing file and things should henceforth work correctly.</p>
</li>
</ul>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

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

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Setting up PyCharm &#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" />
@ -37,10 +38,10 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="setting-up-pycharm">
<section id="setting-up-pycharm">
<h1>Setting up PyCharm<a class="headerlink" href="#setting-up-pycharm" title="Permalink to this headline"></a></h1>
</div>
<div class="section" id="directions-for-setting-up-pycharm-with-evennia">
</section>
<section id="directions-for-setting-up-pycharm-with-evennia">
<h1>Directions for setting up PyCharm with Evennia<a class="headerlink" href="#directions-for-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
@ -59,7 +60,7 @@ need to add them to your project too:</p>
<li><p>Select the folder (i.e. the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> root)</p></li>
<li><p>Select “Open in current window” and “Add to currently opened projects”</p></li>
</ol>
<div class="section" id="setting-up-the-project-interpreter">
<section id="setting-up-the-project-interpreter">
<h2>Setting up the project interpreter<a class="headerlink" href="#setting-up-the-project-interpreter" title="Permalink to this headline"></a></h2>
<p>It’s a good idea to do this before attempting anything further. The rest of this page assumes your
project is already configured in PyCharm.</p>
@ -69,8 +70,8 @@ project is already configured in PyCharm.</p>
<li><p>Navigate to your <code class="docutils literal notranslate"><span class="pre">evenv/scripts</span> <span class="pre">directory</span></code>, and select Python.exe</p></li>
</ol>
<p>Enjoy seeing all your imports checked properly, setting breakpoints, and live variable watching!</p>
</div>
<div class="section" id="attaching-pycharm-debugger-to-evennia">
</section>
<section id="attaching-pycharm-debugger-to-evennia">
<h2>Attaching PyCharm debugger to Evennia<a class="headerlink" href="#attaching-pycharm-debugger-to-evennia" title="Permalink to this headline"></a></h2>
<ol class="simple">
<li><p>Launch Evennia in your preferred way (usually from a console/terminal)</p></li>
@ -90,8 +91,8 @@ process in the list. To do that navigate to: <code class="docutils literal notra
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></blockquote>
</div>
<div class="section" id="setting-up-an-evennia-run-configuration">
</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
@ -114,8 +115,8 @@ parameters to: stop (and name the configuration appropriately).</p>
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>
</div>
<div class="section" id="alternative-run-configuration-utilizing-logfiles-as-source-of-data">
</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
@ -154,8 +155,8 @@ following in the bottom panel:
<img alt="Example of running alternative configuration" src="https://i.imgur.com/nTfpC04.png" />
and you can click through the tabs to check appropriate logs, or even the console output as it is
still running in interactive mode.</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

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

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Unit Testing &#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" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="unit-testing">
<section 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
@ -50,7 +51,7 @@ over the Evennia source code (called <em>test suites</em>) and runs them all in
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>
<div class="section" id="running-the-evennia-test-suite">
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">test</span> <span class="n">evennia</span>
@ -65,8 +66,8 @@ all tests by specifying a subpackage of the library:</p>
how many tests were run and how long it took. If something went wrong you will get error messages.
If you contribute to Evennia, this is a useful sanity check to see you haven’t introduced an
unexpected bug.</p>
</div>
<div class="section" id="running-tests-with-custom-settings-file">
</section>
<section id="running-tests-with-custom-settings-file">
<h2>Running tests with custom settings file<a class="headerlink" href="#running-tests-with-custom-settings-file" title="Permalink to this headline"></a></h2>
<p>If you have implemented your own tests for your game (see below) you can run them from your game dir
with</p>
@ -83,8 +84,8 @@ you must use the <code class="docutils literal notranslate"><span class="pre">--
<p>The <code class="docutils literal notranslate"><span class="pre">--settings</span></code> option of Evennia takes a file name in the <code class="docutils literal notranslate"><span class="pre">mygame/server/conf</span></code> folder. It is
normally used to swap settings files for testing and development. In combination with <code class="docutils literal notranslate"><span class="pre">test</span></code>, it
forces Evennia to use this settings file over the default one.</p>
</div>
<div class="section" id="writing-new-tests">
</section>
<section id="writing-new-tests">
<h2>Writing new tests<a class="headerlink" href="#writing-new-tests" title="Permalink to this headline"></a></h2>
<p>Evennia’s test suite makes use of Django unit test system, which in turn relies on Python’s
<em>unittest</em> module.</p>
@ -105,26 +106,26 @@ optionally do cleanup after each test.</p>
<p>To test the results, you use special methods of the <code class="docutils literal notranslate"><span class="pre">TestCase</span></code> class. Many of those start with
“<code class="docutils literal notranslate"><span class="pre">assert</span></code>”, such as <code class="docutils literal notranslate"><span class="pre">assertEqual</span></code> or <code class="docutils literal notranslate"><span class="pre">assertTrue</span></code>.</p>
<p>Example of a <code class="docutils literal notranslate"><span class="pre">TestCase</span></code> class:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">unittest</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span>
<span class="normal">20</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">unittest</span>
<span class="c1"># the function we want to test</span>
<span class="kn">from</span> <span class="nn">mypath</span> <span class="kn">import</span> <span class="n">myfunc</span>
@ -148,7 +149,7 @@ optionally do cleanup after each test.</p>
</td></tr></table></div>
<p>You might also want to read the <a class="reference external" href="http://docs.python.org/library/unittest.html">documentation for the unittest
module</a>.</p>
<div class="section" id="using-the-evenniatest-class">
<section id="using-the-evenniatest-class">
<h3>Using the EvenniaTest class<a class="headerlink" href="#using-the-evenniatest-class" title="Permalink to this headline"></a></h3>
<p>Evennia offers a custom TestCase, the <code class="docutils literal notranslate"><span class="pre">evennia.utils.test_resources.EvenniaTest</span></code> class. This class
initiates a range of useful properties on themselves for testing Evennia systems. Examples are
@ -157,16 +158,16 @@ initiates a range of useful properties on themselves for testing Evennia systems
when testing Evennia system requiring any of the default Evennia typeclasses as inputs. See the full
definition of the <code class="docutils literal notranslate"><span class="pre">EvenniaTest</span></code> class in
<a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/utils/test_resources.py">evennia/utils/test_resources.py</a>.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># in a test module</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># in a test module</span>
<span class="kn">from</span> <span class="nn">evennia.utils.test_resources</span> <span class="kn">import</span> <span class="n">EvenniaTest</span>
@ -178,8 +179,8 @@ definition of the <code class="docutils literal notranslate"><span class="pre">E
<span class="c1"># ...</span>
</pre></div>
</td></tr></table></div>
</div>
<div class="section" id="testing-in-game-commands">
</section>
<section id="testing-in-game-commands">
<h3>Testing in-game Commands<a class="headerlink" href="#testing-in-game-commands" title="Permalink to this headline"></a></h3>
<p>In-game Commands are a special case. Tests for the default commands are put in
<code class="docutils literal notranslate"><span class="pre">evennia/commands/default/tests.py</span></code>. This uses a custom <code class="docutils literal notranslate"><span class="pre">CommandTest</span></code> class that inherits from
@ -189,17 +190,17 @@ expected values. It uses Characters and Sessions generated on the <code class="d
class).</p>
<p>Each command tested should have its own <code class="docutils literal notranslate"><span class="pre">TestCase</span></code> class. Inherit this class from the <code class="docutils literal notranslate"><span class="pre">CommandTest</span></code>
class in the same module to get access to the command-specific utilities mentioned.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.commands.default.tests</span> <span class="kn">import</span> <span class="n">CommandTest</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.commands.default.tests</span> <span class="kn">import</span> <span class="n">CommandTest</span>
<span class="kn">from</span> <span class="nn">evennia.commands.default</span> <span class="kn">import</span> <span class="n">general</span>
<span class="k">class</span> <span class="nc">TestSet</span><span class="p">(</span><span class="n">CommandTest</span><span class="p">):</span>
<span class="s2">&quot;tests the look command by simple call, using Char2 as a target&quot;</span>
@ -212,8 +213,8 @@ class in the same module to get access to the command-specific utilities mention
<span class="s2">&quot;You see: Obj(#4), Obj2(#5), Char2(#7)&quot;</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<div class="section" id="unit-testing-contribs-with-custom-models">
</section>
<section id="unit-testing-contribs-with-custom-models">
<h3>Unit testing contribs with custom models<a class="headerlink" href="#unit-testing-contribs-with-custom-models" title="Permalink to this headline"></a></h3>
<p>A special case is if you were to create a contribution to go to the <code class="docutils literal notranslate"><span class="pre">evennia/contrib</span></code> folder that
uses its <a class="reference internal" href="../Concepts/New-Models.html"><span class="doc">own database models</span></a>. The problem with this is that Evennia (and Django) will
@ -230,50 +231,50 @@ test runs. here is an example of how to do it.</p>
answer](http://stackoverflow.com/questions/502916/django-how-to-create-a-model-dynamically-just-for-
testing#503435) is currently untested! Please report your findings.</p>
</div></blockquote>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># a file contrib/mycontrib/tests.py</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span>
<span class="normal">20</span>
<span class="normal">21</span>
<span class="normal">22</span>
<span class="normal">23</span>
<span class="normal">24</span>
<span class="normal">25</span>
<span class="normal">26</span>
<span class="normal">27</span>
<span class="normal">28</span>
<span class="normal">29</span>
<span class="normal">30</span>
<span class="normal">31</span>
<span class="normal">32</span>
<span class="normal">33</span>
<span class="normal">34</span>
<span class="normal">35</span>
<span class="normal">36</span>
<span class="normal">37</span>
<span class="normal">38</span>
<span class="normal">39</span>
<span class="normal">40</span>
<span class="normal">41</span>
<span class="normal">42</span>
<span class="normal">43</span>
<span class="normal">44</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># a file contrib/mycontrib/tests.py</span>
<span class="kn">from</span> <span class="nn">django.conf</span> <span class="kn">import</span> <span class="n">settings</span>
<span class="kn">import</span> <span class="nn">django</span>
@ -319,15 +320,15 @@ testing#503435) is currently untested! Please report your findings.</p>
<span class="c1"># test case here</span>
</pre></div>
</td></tr></table></div>
</div>
<div class="section" id="a-note-on-adding-new-tests">
</section>
<section id="a-note-on-adding-new-tests">
<h3>A note on adding new tests<a class="headerlink" href="#a-note-on-adding-new-tests" title="Permalink to this headline"></a></h3>
<p>Having an extensive tests suite is very important for avoiding code degradation as Evennia is
developed. Only a small fraction of the Evennia codebase is covered by test suites at this point.
Writing new tests is not hard, it’s more a matter of finding the time to do so. So adding new tests
is really an area where everyone can contribute, also with only limited Python skills.</p>
</div>
<div class="section" id="a-note-on-making-the-test-runner-faster">
</section>
<section id="a-note-on-making-the-test-runner-faster">
<h3>A note on making the test runner faster<a class="headerlink" href="#a-note-on-making-the-test-runner-faster" title="Permalink to this headline"></a></h3>
<p>If you have custom models with a large number of migrations, creating the test database can take a
very long time. If you don’t require migrations to run for your tests, you can disable them with the
@ -336,10 +337,10 @@ django-test-without-migrations package. To install it, simply:</p>
</pre></div>
</div>
<p>Then add it to your <code class="docutils literal notranslate"><span class="pre">INSTALLED_APPS</span></code> in your <code class="docutils literal notranslate"><span class="pre">server.conf.settings.py</span></code>:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3
4</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">INSTALLED_APPS</span> <span class="o">=</span> <span class="p">(</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">INSTALLED_APPS</span> <span class="o">=</span> <span class="p">(</span>
<span class="c1"># ...</span>
<span class="s1">&#39;test_without_migrations&#39;</span><span class="p">,</span>
<span class="p">)</span>
@ -349,9 +350,9 @@ django-test-without-migrations package. To install it, simply:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">test</span> <span class="o">--</span><span class="n">settings</span> <span class="n">settings</span><span class="o">.</span><span class="n">py</span> <span class="o">--</span><span class="n">nomigrations</span> <span class="o">.</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="testing-for-game-development-mini-tutorial">
</section>
</section>
<section id="testing-for-game-development-mini-tutorial">
<h2>Testing for Game development (mini-tutorial)<a class="headerlink" href="#testing-for-game-development-mini-tutorial" title="Permalink to this headline"></a></h2>
<p>Unit testing can be of paramount importance to game developers. When starting with a new game, it is
recommended to look into unit testing as soon as possible; an already huge game is much harder to
@ -361,7 +362,7 @@ there to ensure your project behaves the way it should and continue to do so.</p
<p>If you have never used unit testing (with Python or another language), you might want to check the
<a class="reference external" href="https://docs.python.org/2/library/unittest.html">official Python documentation about unit testing</a>,
particularly the first section dedicated to a basic example.</p>
<div class="section" id="basic-testing-using-evennia">
<section id="basic-testing-using-evennia">
<h3>Basic testing using Evennia<a class="headerlink" href="#basic-testing-using-evennia" title="Permalink to this headline"></a></h3>
<p>Evennia’s test runner can be used to launch tests in your game directory (let’s call it ‘mygame’).
Evennia’s test runner does a few useful things beyond the normal Python unittest module:</p>
@ -381,23 +382,23 @@ in this section) and execute the test runner:</p>
database of your choice and look into the ‘commands’ package defined in your game directory
(<code class="docutils literal notranslate"><span class="pre">mygame/commands</span></code> in this example) to find tests. The test module’s name should begin with ‘test’
and contain one or more <code class="docutils literal notranslate"><span class="pre">TestCase</span></code>. A full example can be found below.</p>
</div>
<div class="section" id="a-simple-example">
</section>
<section id="a-simple-example">
<h3>A simple example<a class="headerlink" href="#a-simple-example" title="Permalink to this headline"></a></h3>
<p>In your game directory, go to <code class="docutils literal notranslate"><span class="pre">commands</span></code> and create a new file <code class="docutils literal notranslate"><span class="pre">tests.py</span></code> inside (it could be named
anything starting with <code class="docutils literal notranslate"><span class="pre">test</span></code>). We will start by making a test that has nothing to do with Commands,
just to show how unit testing works:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="c1"># mygame/commands/tests.py</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="c1"># mygame/commands/tests.py</span>
<span class="kn">import</span> <span class="nn">unittest</span>
@ -436,8 +437,8 @@ If we have a lot of tests it may be useful to test only a single set at a time t
information text telling us we are using our custom settings file (instead of Evennia’s default
file) and then the test runs. The test passes! Change the “FOO” string to something else in the test
to see how it looks when it fails.</p>
</div>
<div class="section" id="testing-commands">
</section>
<section id="testing-commands">
<h3>Testing commands<a class="headerlink" href="#testing-commands" title="Permalink to this headline"></a></h3>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
@ -452,19 +453,19 @@ and use it properly. This class is called ‘CommandTest’ and is defined in th
need to create a class that inherits from ‘CommandTest’ and add methods.</p>
<p>We could create a new test file for this but for now we just append to the <code class="docutils literal notranslate"><span class="pre">tests.py</span></code> file we
already have in <code class="docutils literal notranslate"><span class="pre">commands</span></code> from before.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="c1"># bottom of mygame/commands/tests.py</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="c1"># bottom of mygame/commands/tests.py</span>
<span class="kn">from</span> <span class="nn">evennia.commands.default.tests</span> <span class="kn">import</span> <span class="n">CommandTest</span>
@ -481,7 +482,7 @@ already have in <code class="docutils literal notranslate"><span class="pre">com
</td></tr></table></div>
<ul class="simple">
<li><p>Line 1-4: we do some importing. ‘CommandTest’ is going to be our base class for our test, so we
need it. We also import our command (‘CmdAbilities’ in this case). Finally we import the
need it. We also import our command (’CmdAbilities’ in this case). Finally we import the
‘Character’ typeclass. We need it, since ‘CommandTest’ doesn’t use ‘Character’, but
‘DefaultCharacter’, which means the character calling the command won’t have the abilities we have
written in the ‘Character’ typeclass.</p></li>
@ -516,9 +517,9 @@ parameter).</p>
</div>
<p>Two tests were executed, since we have kept ‘TestString’ from last time. In case of failure, you
will get much more information to help you fix the bug.</p>
</div>
</div>
</div>
</section>
</section>
</section>
<div class="clearer"></div>

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

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.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" />
@ -37,11 +38,11 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="updating-your-game">
<section 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/Setup-Quickstart.html"><span class="doc">Getting Started guide</span></a> and get everything running.</p>
<div class="section" id="updating-with-the-latest-evennia-code-changes">
<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
@ -63,8 +64,8 @@ function, or use one of the menus (if applicable).</p>
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>
</div>
<div class="section" id="upgrading-evennia-dependencies">
</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
@ -92,8 +93,8 @@ currently available in your python environment after the upgrade, use</p>
</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>
</div>
<div class="section" id="migrating-the-database-schema">
</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
@ -107,8 +108,8 @@ announced on the Evennia <a class="reference external" href="https://groups.goog
<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 external" href="Glossary.html#virtualenv">virtualenv</a>.</p>
</div></blockquote>
</div>
<div class="section" id="resetting-your-database">
</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
@ -145,8 +146,8 @@ 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>
</div>
<div class="section" id="more-about-schema-migrations">
</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
@ -164,8 +165,8 @@ automatically for you. Basically, whenever the schema changes we distribute smal
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>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

31
docs/1.0-dev/Coding/Using-Travis.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Using Travis &#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" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="using-travis">
<section id="using-travis">
<h1>Using Travis<a class="headerlink" href="#using-travis" title="Permalink to this headline"></a></h1>
<p>Evennia uses <a class="reference external" href="http://travis-ci.org/">Travis CI</a> to check that it’s building successfully after every
commit to its Github repository (you can for example see the <code class="docutils literal notranslate"><span class="pre">build:</span> <span class="pre">passing</span></code> badge at the top of
@ -49,18 +50,18 @@ need to set up yourself is a Travis config file named <code class="docutils lite
This should be created in the root of your game directory. The idea with this file is that it
describes what Travis needs to import and build in order to create an instance of Evennia from
scratch and then run validation tests on it. Here is an example:</p>
<div class="highlight-yaml notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="nt">language</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">python</span>
<div class="highlight-yaml notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="nt">language</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">python</span>
<span class="nt">python</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;2.7&quot;</span>
<span class="nt">install</span><span class="p">:</span>
@ -81,7 +82,7 @@ will be able to see it.</p>
<p>For properly testing your game you of course also need to write unittests. [We have a page](Unit-
Testing) on how we set those up for Evennia, you should be able to refer to that for making tests
fitting your game.</p>
</div>
</section>
<div class="clearer"></div>

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

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>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" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="version-control">
<section 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. Even if you are not
@ -50,12 +51,12 @@ deals with commands for Linux operating systems, and the steps below may vary fo
however where possible links will be provided for alternative instructions.</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>
<div class="section" id="setting-up-git">
<section id="setting-up-git">
<h2>Setting up Git<a class="headerlink" href="#setting-up-git" title="Permalink to this headline"></a></h2>
<p>If you have gotten Evennia installed, you will have Git already and can skip to <strong>Step 2</strong> below.
Otherwise you will need to install Git on your platform. You can find expanded instructions for
installation <a class="reference external" href="http://git-scm.com/book/en/Getting-Started-Installing-Git">here</a>.</p>
<div class="section" id="step-1-install-git">
<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>
@ -73,8 +74,8 @@ installation <a class="reference external" href="http://git-scm.com/book/en/Gett
out about <a class="reference external" href="http://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>
</div>
<div class="section" id="step-2-define-user-e-mail-settings-for-git">
</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
@ -96,9 +97,9 @@ real, full name online, put a nickname here.</p>
</div>
</li>
</ol>
</div>
</div>
<div class="section" id="putting-your-game-folder-under-version-control">
</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>
@ -117,7 +118,7 @@ commit:</p>
</pre></div>
</div>
<p>Read on for help on what these commands do.</p>
<div class="section" id="tracking-files">
<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>
@ -128,8 +129,8 @@ you do you must tell Git to track them by using the add command:</p>
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>
<div class="section" id="controlling-tracking">
</section>
<section id="controlling-tracking">
<h3>Controlling tracking<a class="headerlink" href="#controlling-tracking" title="Permalink to this headline"></a></h3>
<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>.
@ -144,8 +145,8 @@ chance you’ll confuse yourself so that after a few commits and reverts don’t
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>
</div></blockquote>
</div>
<div class="section" id="committing-your-code">
</section>
<section id="committing-your-code">
<h3>Committing your Code<a class="headerlink" href="#committing-your-code" title="Permalink to this headline"></a></h3>
<blockquote>
<div><p>Committing means storing the current snapshot of your code within git. This creates a “save point”
@ -165,8 +166,8 @@ directly by using the <code class="docutils literal notranslate"><span class="pr
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">--</span><span class="nb">all</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;This fixes a bug in the combat code.&quot;</span>
</pre></div>
</div>
</div>
<div class="section" id="changing-your-mind">
</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 can do the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">&lt;</span><span class="n">file</span> <span class="n">to</span> <span class="n">revert</span><span class="o">&gt;</span>
@ -175,8 +176,8 @@ directly by using the <code class="docutils literal notranslate"><span class="pr
<p>This will revert the file to the state it was in at your last <code class="docutils literal notranslate"><span class="pre">commit</span></code>, throwing away the changes
you did to it since. It’s a good way to make wild experiments without having to remember just what
you changed. If you do <code class="docutils literal notranslate"> <span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">.</span></code> you will throw away <em>all</em> changes since the last commit.</p>
</div>
<div class="section" id="pushing-your-code-online">
</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>
@ -200,13 +201,13 @@ clone might not be what you want for all parts of your development process - you
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>
</div>
</div>
<div class="section" id="forking-evennia">
</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 Evennia so you can easily commit fixes and help with
upstream development.</p>
<div class="section" id="step-1-fork-the-evennia-master-repository">
<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
@ -217,8 +218,8 @@ Evennia.</p>
<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="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" src="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" /></p>
</div>
<div class="section" id="step-2-clone-your-fork">
</section>
<section id="step-2-clone-your-fork">
<h3>Step 2: Clone your fork<a class="headerlink" href="#step-2-clone-your-fork" 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>
@ -227,8 +228,8 @@ to develop in. From this directory run the following command:</p>
</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>
</div>
<div class="section" id="step-3-configure-remotes">
</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>A <em>remote</em> is a repository stored on another computer, in this case on GitHub’s server. When a
repository is cloned, it has a default remote called <code class="docutils literal notranslate"><span class="pre">origin</span></code>. This points to your fork on GitHub,
@ -249,9 +250,9 @@ following:</p>
</div>
<p>You should now have the upstream branch available locally. You can use this instead of <code class="docutils literal notranslate"><span class="pre">master</span></code>
below if you are contributing new features rather than bug fixes.</p>
</div>
</div>
<div class="section" id="working-with-your-fork">
</section>
</section>
<section id="working-with-your-fork">
<h2>Working with your fork<a class="headerlink" href="#working-with-your-fork" title="Permalink to this headline"></a></h2>
<blockquote>
<div><p>A <em>branch</em> is a separate instance of your code. Changes you do to code in a branch does not affect
@ -266,7 +267,7 @@ existing code.</p>
make modifications directly to your local copy of the master branch. Rather keep the master clean
and only update it by pulling our latest changes to it. Any work you do should instead happen in a
local, other branches.</p>
<div class="section" id="making-a-work-branch">
<section id="making-a-work-branch">
<h3>Making a work branch<a class="headerlink" href="#making-a-work-branch" title="Permalink to this headline"></a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">myfixes</span>
</pre></div>
@ -279,8 +280,8 @@ every bug you want to work on or feature you want to create, then create a <em>p
branch to be merged upstream (see below). Not only will this organize your work, it will also make
sure that <em>your</em> master branch version of Evennia is always exactly in sync with the upstream
version’s master branch.</p>
</div>
<div class="section" id="updating-with-upstream-changes">
</section>
<section id="updating-with-upstream-changes">
<h3>Updating with upstream changes<a class="headerlink" href="#updating-with-upstream-changes" 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>
@ -305,9 +306,9 @@ the server or run <code class="docutils literal notranslate"><span class="pre">m
commit log and on the mailing list). See the <a class="reference external" href="http://git-scm.com/documentation">Git manuals</a> for
learning more about useful day-to-day commands, and special situations such as dealing with merge
collisions.</p>
</div>
</div>
<div class="section" id="sharing-your-code-publicly">
</section>
</section>
<section id="sharing-your-code-publicly">
<h2>Sharing your Code Publicly<a class="headerlink" href="#sharing-your-code-publicly" title="Permalink to this headline"></a></h2>
<p>Up to this point your <code class="docutils literal notranslate"><span class="pre">myfixes</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
@ -326,15 +327,15 @@ we can’t see the code you want to share).</p>
<p><em>Note: 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 credentials there:</em></p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3</pre></div></td><td class="code"><div class="highlight"><pre><span></span>machine github.com
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span>machine github.com
login &lt;my_github_username&gt;
password &lt;my_github_password&gt;
</pre></div>
</td></tr></table></div>
</div>
<div class="section" id="committing-fixes-to-evennia">
</section>
<section id="committing-fixes-to-evennia">
<h2>Committing fixes to Evennia<a class="headerlink" href="#committing-fixes-to-evennia" title="Permalink to this headline"></a></h2>
<p><em>Contributing</em> can mean both bug-fixes or adding new features to Evennia. Please note that if your
change is not already listed and accepted in the <a class="reference external" href="https://github.com/evennia/evennia/issues">Issue
@ -400,8 +401,8 @@ deemed suitable.</p>
</div>
<p>to delete your work branch. Update your master branch (<code class="docutils literal notranslate"><span class="pre">checkout</span> <span class="pre">master</span></code> and then <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code>) and
you should get your fix back, now as a part of official Evennia!</p>
</div>
<div class="section" id="git-tips-and-tricks">
</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>
@ -463,8 +464,8 @@ template.</p>
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>
</div>
</section>
</section>
<div class="clearer"></div>