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

Updated HTML docs

Browse source
This commit is contained in:
Griatch 2021-10-26 21:41:11 +02:00
parent 66d0ad0bc9
commit 7900aad365
2073 changed files with 32986 additions and 41197 deletions
Download patch file Download diff file Expand all files Collapse all files

107
docs/1.0-dev/Concepts/Async-Process.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="async-process">
<section class="tex2jax_ignore mathjax_ignore" id="async-process">
<h1>Async Process<a class="headerlink" href="#async-process" title="Permalink to this headline"></a></h1>
<p><em>This is considered an advanced topic.</em></p>
<section id="synchronous-versus-asynchronous">
@ -48,13 +50,12 @@ processed and finishes before the next can begin. This makes for easy-to-underst
a <em>requirement</em> in many cases - a subsequent piece of code often depend on something calculated or
defined in a previous statement.</p>
<p>Consider this piece of code in a traditional Python program:</p>
<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></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;before call ...&quot;</span><span class="p">)</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;before call ...&quot;</span><span class="p">)</span>
<span class="n">long_running_function</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;after call ...&quot;</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>When run, this will print <code class="docutils literal notranslate"><span class="pre">&quot;before</span> <span class="pre">call</span> <span class="pre">...&quot;</span></code>, after which the <code class="docutils literal notranslate"><span class="pre">long_running_function</span></code> gets to work
for however long time. Only once that is done, the system prints <code class="docutils literal notranslate"><span class="pre">&quot;after</span> <span class="pre">call</span> <span class="pre">...&quot;</span></code>. Easy and
logical to follow. Most of Evennia work in this way and often it’s important that commands get
@ -70,19 +71,16 @@ all commands to occur in strict sequence.</p>
<p>When delays do become noticeable and you don’t care in which order the command actually completes,
you can run it <em>asynchronously</em>. This makes use of the <code class="docutils literal notranslate"><span class="pre">run_async()</span></code> function in
<code class="docutils literal notranslate"><span class="pre">src/utils/utils.py</span></code>:</p>
<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">run_async</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">run_async</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Where <code class="docutils literal notranslate"><span class="pre">function</span></code> will be called asynchronously with <code class="docutils literal notranslate"><span class="pre">*args</span></code> and <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code>. Example:</p>
<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</span> <span class="kn">import</span> <span class="n">utils</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">utils</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;before call ...&quot;</span><span class="p">)</span>
<span class="n">utils</span><span class="o">.</span><span class="n">run_async</span><span class="p">(</span><span class="n">long_running_function</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;after call ...&quot;</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Now, when running this you will find that the program will not wait around for
<code class="docutils literal notranslate"><span class="pre">long_running_function</span></code> to finish. In fact you will see <code class="docutils literal notranslate"><span class="pre">&quot;before</span> <span class="pre">call</span> <span class="pre">...&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;after</span> <span class="pre">call</span> <span class="pre">...&quot;</span></code>
printed out right away. The long-running function will run in the background and you (and other
@ -100,11 +98,10 @@ line quite pointless for processing any data from the function. Instead one has
<li><p><code class="docutils literal notranslate"><span class="pre">at_return(r)</span></code> (the <em>callback</em>) is called when the asynchronous function (<code class="docutils literal notranslate"><span class="pre">long_running_function</span></code>
above) finishes successfully. The argument <code class="docutils literal notranslate"><span class="pre">r</span></code> will then be the return value of that function (or
<code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>
<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="k">def</span> <span class="nf">at_return</span><span class="p">(</span><span class="n">r</span><span class="p">):</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">def</span> <span class="nf">at_return</span><span class="p">(</span><span class="n">r</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="n">r</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">at_return_kwargs</span></code> - an optional dictionary that will be fed as keyword arguments to the
<code class="docutils literal notranslate"><span class="pre">at_return</span></code> callback.</p></li>
@ -113,37 +110,16 @@ This exception is passed to the errback wrapped in a <em>Failure</em> object <co
errback of your own, Evennia will automatically add one that silently writes errors to the evennia
log. An example of an errback is found below:</p></li>
</ul>
<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="k">def</span> <span class="nf">at_err</span><span class="p">(</span><span class="n">e</span><span class="p">):</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">def</span> <span class="nf">at_err</span><span class="p">(</span><span class="n">e</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;There was an error:&quot;</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">))</span>
</pre></div>
</td></tr></table></div>
</div>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">at_err_kwargs</span></code> - an optional dictionary that will be fed as keyword arguments to the <code class="docutils literal notranslate"><span class="pre">at_err</span></code>
errback.</p></li>
</ul>
<p>An example of making an asynchronous call from inside a <a class="reference internal" href="../Components/Commands.html"><span class="doc">Command</span></a> definition:</p>
<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></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">utils</span><span class="p">,</span> <span class="n">Command</span>
<p>An example of making an asynchronous call from inside a <a class="reference internal" href="../Components/Commands.html"><span class="doc std std-doc">Command</span></a> definition:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">utils</span><span class="p">,</span> <span class="n">Command</span>
<span class="k">class</span> <span class="nc">CmdAsync</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
@ -165,7 +141,7 @@ errback.</p></li>
<span class="n">utils</span><span class="o">.</span><span class="n">run_async</span><span class="p">(</span><span class="n">long_running_function</span><span class="p">,</span> <span class="n">at_return</span><span class="o">=</span><span class="n">at_return_function</span><span class="p">,</span>
<span class="n">at_err</span><span class="o">=</span><span class="n">at_err_function</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>That’s it - from here on we can forget about <code class="docutils literal notranslate"><span class="pre">long_running_function</span></code> and go on with what else need
to be done. <em>Whenever</em> it finishes, the <code class="docutils literal notranslate"><span class="pre">at_return_function</span></code> function will be called and the final
value will
@ -177,13 +153,7 @@ pop up for us to see. If not we will see an error message.</p>
execution of a command until a future time. This is equivalent to something like <code class="docutils literal notranslate"><span class="pre">time.sleep()</span></code>
except delay is asynchronous while <code class="docutils literal notranslate"><span class="pre">sleep</span></code> would lock the entire server for the duration of the
sleep.</p>
<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">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">delay</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">delay</span>
<span class="c1"># [...]</span>
<span class="c1"># e.g. inside a Command, where `self.caller` is available</span>
@ -191,35 +161,22 @@ sleep.</p>
<span class="n">obj</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Returning!&quot;</span><span class="p">)</span>
<span class="n">delay</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="n">callback</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>This will delay the execution of the callback for 10 seconds. This function is explored much more in
the <a class="reference internal" href="../Howto/Command-Duration.html"><span class="doc">Command Duration Tutorial</span></a>.</p>
the <a class="reference internal" href="../Howto/Command-Duration.html"><span class="doc std std-doc">Command Duration Tutorial</span></a>.</p>
<p>You can also try the following snippet just see how it works:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@py</span> <span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">delay</span><span class="p">;</span> <span class="n">delay</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">who</span><span class="p">:</span> <span class="n">who</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Test!&quot;</span><span class="p">),</span> <span class="bp">self</span><span class="p">)</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>@py from evennia.utils import delay; delay(10, lambda who: who.msg(&quot;Test!&quot;), self)
</pre></div>
</div>
<p>Wait 10 seconds and ‘Test!’ should be echoed back to you.</p>
</section>
<section id="the-interactive-decorator">
<h2>The &#64;interactive decorator<a class="headerlink" href="#the-interactive-decorator" title="Permalink to this headline"></a></h2>
<p>As of Evennia 0.9, the <code class="docutils literal notranslate"><span class="pre">&#64;interactive</span></code> [decorator](https://realpython.com/primer-on-python-
<p>As of Evennia 0.9, the <code class="docutils literal notranslate"><span class="pre">&#64;interactive</span></code> [decorator](<a class="reference external" href="https://realpython.com/primer-on-python-">https://realpython.com/primer-on-python-</a>
decorators/)
is available. This makes any function or method possible to ‘pause’ and/or await player input
in an interactive way.</p>
<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></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">interactive</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">interactive</span>
<span class="nd">@interactive</span>
<span class="k">def</span> <span class="nf">myfunc</span><span class="p">(</span><span class="n">caller</span><span class="p">):</span>
@ -234,7 +191,7 @@ in an interactive way.</p>
<span class="k">if</span> <span class="n">response</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="ow">not</span> <span class="ow">in</span> <span class="p">(</span><span class="s2">&quot;yes&quot;</span><span class="p">,</span> <span class="s2">&quot;y&quot;</span><span class="p">):</span>
<span class="k">break</span>
</pre></div>
</td></tr></table></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">&#64;interactive</span></code> decorator gives the function the ability to pause. The use
of <code class="docutils literal notranslate"><span class="pre">yield(seconds)</span></code> will do just that - it will asynchronously pause for the
number of seconds given before continuing. This is technically equivalent to
@ -254,16 +211,7 @@ empty <code class="docutils literal notranslate"><span class="pre">return</span>
with <code class="docutils literal notranslate"><span class="pre">&#64;interactive</span></code>, you must instead use a special Twisted function
<code class="docutils literal notranslate"><span class="pre">twisted.internet.defer.returnValue</span></code>. Evennia also makes this function
conveniently available from <code class="docutils literal notranslate"><span class="pre">evennia.utils</span></code>:</p>
<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="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">interactive</span><span class="p">,</span> <span class="n">returnValue</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">interactive</span><span class="p">,</span> <span class="n">returnValue</span>
<span class="nd">@interactive</span>
<span class="k">def</span> <span class="nf">myfunc</span><span class="p">():</span>
@ -273,8 +221,9 @@ conveniently available from <code class="docutils literal notranslate"><span cla
<span class="c1"># this must be used instead of `return result`</span>
<span class="n">returnValue</span><span class="p">(</span><span class="n">result</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
</section>
<section id="assorted-notes">
<h2>Assorted notes<a class="headerlink" href="#assorted-notes" title="Permalink to this headline"></a></h2>
@ -352,7 +301,7 @@ your own liking.</p>
<h3>Versions</h3>
<ul>
<li><a href="Async-Process.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

40
docs/1.0-dev/Concepts/Banning.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="banning">
<section class="tex2jax_ignore mathjax_ignore" id="banning">
<h1>Banning<a class="headerlink" href="#banning" title="Permalink to this headline"></a></h1>
<p>Whether due to abuse, blatant breaking of your rules, or some other reason, you will eventually find
no other recourse but to kick out a particularly troublesome player. The default command set has
@ -52,19 +54,19 @@ have tried to be nice. Now you just want this troll gone.</p>
<section id="name-ban">
<h3>Name ban<a class="headerlink" href="#name-ban" title="Permalink to this headline"></a></h3>
<p>The easiest recourse is to block the account YouSuck from ever connecting again.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">ban</span> <span class="n">YouSuck</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> ban YouSuck
</pre></div>
</div>
<p>This will lock the name YouSuck (as well as ‘yousuck’ and any other capitalization combination), and
next time they try to log in with this name the server will not let them!</p>
<p>You can also give a reason so you remember later why this was a good thing (the banned account will
never see this)</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">ban</span> <span class="n">YouSuck</span><span class="p">:</span><span class="n">This</span> <span class="ow">is</span> <span class="n">just</span> <span class="n">a</span> <span class="n">troll</span><span class="o">.</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> ban YouSuck:This is just a troll.
</pre></div>
</div>
<p>If you are sure this is just a spam account, you might even consider deleting the player account
outright:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">accounts</span><span class="o">/</span><span class="n">delete</span> <span class="n">YouSuck</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> accounts/delete YouSuck
</pre></div>
</div>
<p>Generally, banning the name is the easier and safer way to stop the use of an account – if you
@ -77,13 +79,13 @@ up. They can just create a new account YouSuckMore and be back at it. One way to
for them is to tell the server to not allow connections from their particular IP address.</p>
<p>First, when the offending account is online, check which IP address they use. This you can do with
the <code class="docutils literal notranslate"><span class="pre">who</span></code> command, which will show you something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">Account</span> <span class="n">Name</span> <span class="n">On</span> <span class="k">for</span> <span class="n">Idle</span> <span class="n">Room</span> <span class="n">Cmds</span> <span class="n">Host</span>
<span class="n">YouSuckMore</span> <span class="mi">01</span><span class="p">:</span><span class="mi">12</span> <span class="mi">2</span><span class="n">m</span> <span class="mi">22</span> <span class="mi">212</span> <span class="mf">237.333.0.223</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> Account Name On for Idle Room Cmds Host
YouSuckMore 01:12 2m 22 212 237.333.0.223
</pre></div>
</div>
<p>The “Host” bit is the IP address from which the account is connecting. Use this to define the ban
instead of the name:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">ban</span> <span class="mf">237.333.0.223</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> ban 237.333.0.223
</pre></div>
</div>
<p>This will stop YouSuckMore connecting from their computer. Note however that IP address might change
@ -92,7 +94,7 @@ changing computers. You can make a more general ban by putting asterisks <code c
groups of three digits in the address. So if you figure out that !YouSuckMore mainly connects from
237.333.0.223, 237.333.0.225, and 237.333.0.256 (only changes in their subnet), it might be an idea
to put down a ban like this to include any number in that subnet:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">ban</span> <span class="mf">237.333.0</span><span class="o">.*</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> ban 237.333.0.*
</pre></div>
</div>
<p>You should combine the IP ban with a name-ban too of course, so the account YouSuckMore is truly
@ -105,28 +107,28 @@ blocking out innocent players who just happen to connect from the same subnet as
<h2>Booting<a class="headerlink" href="#booting" title="Permalink to this headline"></a></h2>
<p>YouSuck is not really noticing all this banning yet though - and won’t until having logged out and
trying to log back in again. Let’s help the troll along.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">boot</span> <span class="n">YouSuck</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> boot YouSuck
</pre></div>
</div>
<p>Good riddance. You can give a reason for booting too (to be echoed to the player before getting
kicked out).</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">boot</span> <span class="n">YouSuck</span><span class="p">:</span><span class="n">Go</span> <span class="n">troll</span> <span class="n">somewhere</span> <span class="k">else</span><span class="o">.</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> boot YouSuck:Go troll somewhere else.
</pre></div>
</div>
<section id="lifting-a-ban">
<h3>Lifting a ban<a class="headerlink" href="#lifting-a-ban" title="Permalink to this headline"></a></h3>
<p>Use the <code class="docutils literal notranslate"><span class="pre">unban</span></code> (or <code class="docutils literal notranslate"><span class="pre">ban</span></code>) command without any arguments and you will see a list of all currently
active bans:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Active</span> <span class="n">bans</span>
<span class="nb">id</span> <span class="n">name</span><span class="o">/</span><span class="n">ip</span> <span class="n">date</span> <span class="n">reason</span>
<span class="mi">1</span> <span class="n">yousuck</span> <span class="n">Fri</span> <span class="n">Jan</span> <span class="mi">3</span> <span class="mi">23</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">22</span> <span class="mi">2020</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">just</span> <span class="n">a</span> <span class="n">Troll</span><span class="o">.</span>
<span class="mi">2</span> <span class="mf">237.333.0</span><span class="o">.*</span> <span class="n">Fri</span> <span class="n">Jan</span> <span class="mi">3</span> <span class="mi">23</span><span class="p">:</span><span class="mi">01</span><span class="p">:</span><span class="mi">03</span> <span class="mi">2020</span> <span class="n">YouSuck</span><span class="s1">&#39;s IP.</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Active bans
id name/ip date reason
1 yousuck Fri Jan 3 23:00:22 2020 This is just a Troll.
2 237.333.0.* Fri Jan 3 23:01:03 2020 YouSuck&#39;s IP.
</pre></div>
</div>
<p>Use the <code class="docutils literal notranslate"><span class="pre">id</span></code> from this list to find out which ban to lift.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">unban</span> <span class="mi">2</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> unban 2
<span class="n">Cleared</span> <span class="n">ban</span> <span class="mi">2</span><span class="p">:</span> <span class="mf">237.333.0</span><span class="o">.*</span>
Cleared ban 2: 237.333.0.*
</pre></div>
</div>
</section>
@ -150,14 +152,14 @@ is not what you want in this case.</p></li>
<li><p><strong>unban 34</strong> – Remove ban with id #34</p></li>
<li><p><strong>cboot mychannel = thomas</strong> – Boot a subscriber from a channel you control</p></li>
<li><p><strong>clock mychannel = control:perm(Admin);listen:all();send:all()</strong> – Fine control of access to
your channel using <a class="reference internal" href="../Components/Locks.html"><span class="doc">lock definitions</span></a>.</p></li>
your channel using <a class="reference internal" href="../Components/Locks.html"><span class="doc std std-doc">lock definitions</span></a>.</p></li>
</ul>
<p>Locking a specific command (like <code class="docutils literal notranslate"><span class="pre">page</span></code>) is accomplished like so:</p>
<ol class="simple">
<li><p>Examine the source of the command. <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/commands/default/comms.py#L686">The default <code class="docutils literal notranslate"><span class="pre">page</span></code> command class</a> has the lock
string <strong>“cmd:not pperm(page_banned)”</strong>. This means that unless the player has the ‘permission’
“page_banned” they can use this command. You can assign any lock string to allow finer customization
in your commands. You might look for the value of an <a class="reference internal" href="../Components/Attributes.html"><span class="doc">Attribute</span></a> or <a class="reference internal" href="../Components/Tags.html"><span class="doc">Tag</span></a>, your
in your commands. You might look for the value of an <a class="reference internal" href="../Components/Attributes.html"><span class="doc std std-doc">Attribute</span></a> or <a class="reference internal" href="../Components/Tags.html"><span class="doc std std-doc">Tag</span></a>, your
current location etc.</p></li>
<li><p><strong>perm/account thomas = page_banned</strong> – Give the account the ‘permission’ which causes (in this
case) the lock to fail.</p></li>
@ -238,7 +240,7 @@ objects on the fly. For advanced users.</p></li>
<h3>Versions</h3>
<ul>
<li><a href="Banning.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

10
docs/1.0-dev/Concepts/Bootstrap-&-Evennia.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,10 +40,10 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="bootstrap-evennia">
<section class="tex2jax_ignore mathjax_ignore" id="bootstrap-evennia">
<h1>Bootstrap &amp; Evennia<a class="headerlink" href="#bootstrap-evennia" title="Permalink to this headline"></a></h1>
</section>
<section id="what-is-bootstrap">
<section class="tex2jax_ignore mathjax_ignore" id="what-is-bootstrap">
<h1>What is Bootstrap?<a class="headerlink" href="#what-is-bootstrap" title="Permalink to this headline"></a></h1>
<p>Evennia’s new default web page uses a framework called <a class="reference external" href="https://getbootstrap.com/">Bootstrap</a>. This
framework is in use across the internet - you’ll probably start to recognize its influence once you
@ -135,7 +137,7 @@ docs</a></p>
<section id="more-bootstrap">
<h2>More Bootstrap<a class="headerlink" href="#more-bootstrap" title="Permalink to this headline"></a></h2>
<p>Bootstrap also provides a huge amount of utilities, as well as styling and content elements. To
learn more about them, please [read the Bootstrap docs](https://getbootstrap.com/docs/4.0/getting-
learn more about them, please [read the Bootstrap docs](<a class="reference external" href="https://getbootstrap.com/docs/4.0/getting-">https://getbootstrap.com/docs/4.0/getting-</a>
started/introduction/) or read one of our other web tutorials.</p>
</section>
</section>
@ -190,7 +192,7 @@ started/introduction/) or read one of our other web tutorials.</p>
<h3>Versions</h3>
<ul>
<li><a href="Bootstrap-&-Evennia.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

18
docs/1.0-dev/Concepts/Building-Permissions.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,10 +40,10 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="building-permissions">
<section class="tex2jax_ignore mathjax_ignore" id="building-permissions">
<h1>Building Permissions<a class="headerlink" href="#building-permissions" title="Permalink to this headline"></a></h1>
<p><em>OBS: This gives only a brief introduction to the access system. Locks and permissions are fully
detailed</em> <a class="reference internal" href="../Components/Locks.html"><span class="doc">here</span></a>.</p>
detailed</em> <a class="reference internal" href="../Components/Locks.html"><span class="doc std std-doc">here</span></a>.</p>
<section id="the-super-user">
<h2>The super user<a class="headerlink" href="#the-super-user" title="Permalink to this headline"></a></h2>
<p>There are strictly speaking two types of users in Evennia, the <em>super user</em> and everyone else. The
@ -55,7 +57,7 @@ but one superuser.</p>
<h2>Assigning permissions<a class="headerlink" href="#assigning-permissions" title="Permalink to this headline"></a></h2>
<p>Whereas permissions can be used for anything, those put in <code class="docutils literal notranslate"><span class="pre">settings.PERMISSION_HIERARCHY</span></code> will have
a ranking relative each other as well. We refer to these types of permissions as <em>hierarchical
permissions</em>. When building locks to check these permissions, the <code class="docutils literal notranslate"><span class="pre">perm()</span></code> <a class="reference internal" href="../Components/Locks.html"><span class="doc">lock function</span></a> is
permissions</em>. When building locks to check these permissions, the <code class="docutils literal notranslate"><span class="pre">perm()</span></code> <a class="reference internal" href="../Components/Locks.html"><span class="doc std std-doc">lock function</span></a> is
used. By default Evennia creates the following hierarchy (spelled exactly like this):</p>
<ol class="simple">
<li><p><strong>Developers</strong> basically have the same access as superusers except that they do <em>not</em> sidestep
@ -79,11 +81,11 @@ This is an <em>Developer</em>-level command, but it could in principle be made l
allows assignments equal or lower to your current level (so you cannot use it to escalate your own
permission level). So, assuming you yourself have <em>Developer</em> access (or is superuser), you assign
a new account “Tommy” to your core staff with the command</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@perm</span><span class="o">/</span><span class="n">account</span> <span class="n">Tommy</span> <span class="o">=</span> <span class="n">Developer</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>@perm/account Tommy = Developer
</pre></div>
</div>
<p>or</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@perm</span> <span class="o">*</span><span class="n">Tommy</span> <span class="o">=</span> <span class="n">Developer</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>@perm *Tommy = Developer
</pre></div>
</div>
<p>We use a switch or the <code class="docutils literal notranslate"><span class="pre">*name</span></code> format to make sure to put the permission on the <em>Account</em> and not on
@ -91,7 +93,7 @@ any eventual <em>Character</em> that may also be named “Tommy”. This is usua
Account will then remain an Developer regardless of which Character they are currently controlling.
To limit permission to a per-Character level you should instead use <em>quelling</em> (see below). Normally
permissions can be any string, but for these special hierarchical permissions you can also use
plural (”Developer” and “Developers” both grant the same powers).</p>
plural (“Developer” and “Developers” both grant the same powers).</p>
</section>
<section id="quelling-your-permissions">
<h2>Quelling your permissions<a class="headerlink" href="#quelling-your-permissions" title="Permalink to this headline"></a></h2>
@ -100,7 +102,7 @@ lower. For this you can use <em>quelling</em>. Normally, when you puppet a Char
Account-level permission. So even if your Character only has <em>Accounts</em> level permissions, your
<em>Developer</em>-level Account will take precedence. With the <code class="docutils literal notranslate"><span class="pre">&#64;quell</span></code> command you can change so that the
Character’s permission takes precedence instead:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="nd">@quell</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> @quell
</pre></div>
</div>
<p>This will allow you to test out the game using the current Character’s permission level. A developer
@ -160,7 +162,7 @@ levels. Note that you cannot escalate your permissions this way; If the Characte
<h3>Versions</h3>
<ul>
<li><a href="Building-Permissions.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

6
docs/1.0-dev/Concepts/Clickable-Links.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="clickable-links">
<section class="tex2jax_ignore mathjax_ignore" id="clickable-links">
<h1>Clickable links<a class="headerlink" href="#clickable-links" title="Permalink to this headline"></a></h1>
<p>Evennia supports clickable links for clients that supports it. This marks certain text so it can be
clicked by a mouse and either trigger a given Evennia command, or open a URL in an external web
@ -99,7 +101,7 @@ will be shown.</p>
<h3>Versions</h3>
<ul>
<li><a href="Clickable-Links.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

48
docs/1.0-dev/Concepts/Colors.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="colors">
<section class="tex2jax_ignore mathjax_ignore" id="colors">
<h1>Colors<a class="headerlink" href="#colors" title="Permalink to this headline"></a></h1>
<p><em>Note that the Documentation does not display colour the way it would look on the screen.</em></p>
<p>Color can be a very useful tool for your game. It can be used to increase readability and make your
@ -51,7 +53,7 @@ desired. Some clients don’t even support color - text games are also played wi
equipment by people who are blind or have otherwise diminished eyesight.</p>
<p>So a good rule of thumb is to use colour to enhance your game but don’t <em>rely</em> on it to display
critical information. If you are coding the game, you can add functionality to let users disable
colours as they please, as described <a class="reference internal" href="../Howto/Manually-Configuring-Color.html"><span class="doc">here</span></a>.</p>
colours as they please, as described <a class="reference internal" href="../Howto/Manually-Configuring-Color.html"><span class="doc std std-doc">here</span></a>.</p>
<p>To see which colours your client support, use the default <code class="docutils literal notranslate"><span class="pre">&#64;color</span></code> command. This will list all
available colours for ANSI and Xterm256 along with the codes you use for them. You can find a list
of all the parsed <code class="docutils literal notranslate"><span class="pre">ANSI</span></code>-colour codes in <code class="docutils literal notranslate"><span class="pre">evennia/utils/ansi.py</span></code>.</p>
@ -63,7 +65,7 @@ available in all but the most ancient mud clients. The ANSI colours are <strong>
first letter except for black which is abbreviated with the letter <strong>x</strong>. In ANSI there are “bright”
and “normal” (darker) versions of each color, adding up to a total of 16 colours to use for
foreground text. There are also 8 “background” colours. These have no bright alternative in ANSI
(but Evennia uses the <a class="reference external" href="Concepts/TextTags.html#xterm256-colours">Xterm256</a> extension behind the scenes to offer
(but Evennia uses the <a class="reference internal" href="#xterm256-colours"><span class="std std-doc">Xterm256</span></a> extension behind the scenes to offer
them anyway).</p>
<p>To colour your text you put special tags in it. Evennia will parse these and convert them to the
correct markup for the client used. If the user’s client/console/display supports ANSI colour, they
@ -71,10 +73,10 @@ will see the text in the specified colour, otherwise the tags will be stripped (
This works also for non-terminal clients, such as the webclient. For the webclient, Evennia will
translate the codes to HTML RGB colors.</p>
<p>Here is an example of the tags in action:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">|</span><span class="n">rThis</span> <span class="n">text</span> <span class="ow">is</span> <span class="n">bright</span> <span class="n">red</span><span class="o">.|</span><span class="n">n</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">normal</span> <span class="n">text</span><span class="o">.</span>
<span class="o">|</span><span class="n">RThis</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">dark</span> <span class="n">red</span> <span class="n">text</span><span class="o">.|</span><span class="n">n</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">normal</span> <span class="n">text</span><span class="o">.</span>
<span class="o">|</span><span class="p">[</span><span class="n">rThis</span> <span class="n">text</span> <span class="n">has</span> <span class="n">red</span> <span class="n">background</span><span class="o">.|</span><span class="n">n</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">normal</span> <span class="n">text</span><span class="o">.</span>
<span class="o">|</span><span class="n">b</span><span class="o">|</span><span class="p">[</span><span class="n">yThis</span> <span class="ow">is</span> <span class="n">bright</span> <span class="n">blue</span> <span class="n">text</span> <span class="n">on</span> <span class="n">yellow</span> <span class="n">background</span><span class="o">.|</span><span class="n">n</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">normal</span> <span class="n">text</span><span class="o">.</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> |rThis text is bright red.|n This is normal text.
|RThis is a dark red text.|n This is normal text.
|[rThis text has red background.|n This is normal text.
|b|[yThis is bright blue text on yellow background.|n This is normal text.
</pre></div>
</div>
<ul class="simple">
@ -101,7 +103,7 @@ set bright/normal explicitly. Technically, <code class="docutils literal notran
<blockquote>
<div><p>Note: The ANSI standard does not actually support bright backgrounds like <code class="docutils literal notranslate"><span class="pre">|[r</span></code> - the standard
only supports “normal” intensity backgrounds. To get around this Evennia instead implements these
as <a class="reference external" href="Concepts/TextTags.html#xterm256-colours">Xterm256 colours</a> behind the scenes. If the client does not support
as <a class="reference internal" href="#xterm256-colours"><span class="std std-doc">Xterm256 colours</span></a> behind the scenes. If the client does not support
Xterm256 the ANSI colors will be used instead and there will be no visible difference between using
upper- and lower-case background tags.</p>
</div></blockquote>
@ -113,7 +115,7 @@ it by preceding its <code class="docutils literal notranslate"><span class="pre"
<p>This will output the raw <code class="docutils literal notranslate"><span class="pre">|r</span></code> without any color change. This can also be necessary if you are doing
ansi art that uses <code class="docutils literal notranslate"><span class="pre">|</span></code> with a letter directly following it.</p>
<p>Use the command</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@color</span> <span class="n">ansi</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>@color ansi
</pre></div>
</div>
<p>to get a list of all supported ANSI colours and the tags used to produce them.</p>
@ -167,21 +169,20 @@ actually change the background color instead of the foreground:</p>
Tags) tutorial. But most of the time you might be better off to simply avoid <code class="docutils literal notranslate"><span class="pre">|*</span></code> and mark your text
manually instead.</p>
</section>
</section>
<section id="xterm256-colours">
<h2>Xterm256 Colours<a class="headerlink" href="#xterm256-colours" title="Permalink to this headline"></a></h2>
<h3>Xterm256 Colours<a class="headerlink" href="#xterm256-colours" title="Permalink to this headline"></a></h3>
<p>The <em>Xterm256</em> standard is a colour scheme that supports 256 colours for text and/or background.
While this offers many more possibilities than traditional ANSI colours, be wary that too many text
colors will be confusing to the eye. Also, not all clients support Xterm256 - these will instead see
the closest equivalent ANSI color. You can mix Xterm256 tags with ANSI tags as you please.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">|</span><span class="mi">555</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">pure</span> <span class="n">white</span> <span class="n">text</span><span class="o">.|</span><span class="n">n</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">normal</span> <span class="n">text</span><span class="o">.</span>
<span class="o">|</span><span class="mi">230</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">olive</span> <span class="n">green</span> <span class="n">text</span><span class="o">.</span>
<span class="o">|</span><span class="p">[</span><span class="mi">300</span> <span class="n">This</span> <span class="n">text</span> <span class="n">has</span> <span class="n">a</span> <span class="n">dark</span> <span class="n">red</span> <span class="n">background</span><span class="o">.</span>
<span class="o">|</span><span class="mi">005</span><span class="o">|</span><span class="p">[</span><span class="mi">054</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">dark</span> <span class="n">blue</span> <span class="n">text</span> <span class="n">on</span> <span class="n">a</span> <span class="n">bright</span> <span class="n">cyan</span> <span class="n">background</span><span class="o">.</span>
<span class="o">|=</span><span class="n">a</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">greyscale</span> <span class="n">value</span><span class="p">,</span> <span class="n">equal</span> <span class="n">to</span> <span class="n">black</span><span class="o">.</span>
<span class="o">|=</span><span class="n">m</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">greyscale</span> <span class="n">value</span><span class="p">,</span> <span class="n">midway</span> <span class="n">between</span> <span class="n">white</span> <span class="ow">and</span> <span class="n">black</span><span class="o">.</span>
<span class="o">|=</span><span class="n">z</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">greyscale</span> <span class="n">value</span><span class="p">,</span> <span class="n">equal</span> <span class="n">to</span> <span class="n">white</span><span class="o">.</span>
<span class="o">|</span><span class="p">[</span><span class="o">=</span><span class="n">m</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">background</span> <span class="n">greyscale</span> <span class="n">value</span><span class="o">.</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>|555 This is pure white text.|n This is normal text.
|230 This is olive green text.
|[300 This text has a dark red background.
|005|[054 This is dark blue text on a bright cyan background.
|=a This is a greyscale value, equal to black.
|=m This is a greyscale value, midway between white and black.
|=z This is a greyscale value, equal to white.
|[=m This is a background greyscale value.
</pre></div>
</div>
<ul class="simple">
@ -198,7 +199,7 @@ four gray tones between solid black and white (<code class="docutils literal not
<li><p><code class="docutils literal notranslate"><span class="pre">|[=#</span></code> - this works in the same way but produces background gray scale tones.</p></li>
</ul>
<p>If you have a client that supports Xterm256, you can use</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@color</span> <span class="n">xterm256</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>@color xterm256
</pre></div>
</div>
<p>to get a table of all the 256 colours and the codes that produce them. If the table looks broken up
@ -207,9 +208,10 @@ You can use the <code class="docutils literal notranslate"><span class="pre">&#6
client told Evennia what it supports - if not, and you know what your client supports, you may have
to activate some features manually.</p>
</section>
</section>
<section id="more-reading">
<h2>More reading<a class="headerlink" href="#more-reading" title="Permalink to this headline"></a></h2>
<p>There is an <a class="reference internal" href="../Howto/Understanding-Color-Tags.html"><span class="doc">Understanding Color Tags</span></a> tutorial which expands on the
<p>There is an <a class="reference internal" href="../Howto/Understanding-Color-Tags.html"><span class="doc std std-doc">Understanding Color Tags</span></a> tutorial which expands on the
use of ANSI color tags and the pitfalls of mixing ANSI and Xterms256 color tags in the same context.</p>
</section>
</section>
@ -239,9 +241,9 @@ use of ANSI color tags and the pitfalls of mixing ANSI and Xterms256 color tags
<li><a class="reference internal" href="#">Colors</a><ul>
<li><a class="reference internal" href="#ansi-colours">ANSI colours</a><ul>
<li><a class="reference internal" href="#caveats-of">Caveats of <code class="docutils literal notranslate"><span class="pre">|*</span></code></a></li>
<li><a class="reference internal" href="#xterm256-colours">Xterm256 Colours</a></li>
</ul>
</li>
<li><a class="reference internal" href="#xterm256-colours">Xterm256 Colours</a></li>
<li><a class="reference internal" href="#more-reading">More reading</a></li>
</ul>
</li>
@ -267,7 +269,7 @@ use of ANSI color tags and the pitfalls of mixing ANSI and Xterms256 color tags
<h3>Versions</h3>
<ul>
<li><a href="Colors.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

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

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -46,45 +48,45 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="core-concepts">
<section class="tex2jax_ignore mathjax_ignore" id="core-concepts">
<h1>Core Concepts<a class="headerlink" href="#core-concepts" title="Permalink to this headline"></a></h1>
<p>This documentation cover more over-arching concepts of Evennia, often involving many <a class="reference internal" href="../Components/Components-Overview.html"><span class="doc">Core Components</span></a> acting together.</p>
<p>This documentation cover more over-arching concepts of Evennia, often involving many <a class="reference internal" href="../Components/Components-Overview.html"><span class="doc std std-doc">Core Components</span></a> acting together.</p>
<section id="general-concepts">
<h2>General concepts<a class="headerlink" href="#general-concepts" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Async-Process.html"><span class="doc">Asynchronous processing</span></a></p></li>
<li><p><a class="reference internal" href="Soft-Code.html"><span class="doc">On Soft-Code</span></a></p></li>
<li><p><a class="reference internal" href="Using-MUX-as-a-Standard.html"><span class="doc">Using MUX as standard for default commands</span></a></p></li>
<li><p><a class="reference internal" href="Async-Process.html"><span class="doc std std-doc">Asynchronous processing</span></a></p></li>
<li><p><a class="reference internal" href="Soft-Code.html"><span class="doc std std-doc">On Soft-Code</span></a></p></li>
<li><p><a class="reference internal" href="Using-MUX-as-a-Standard.html"><span class="doc std std-doc">Using MUX as standard for default commands</span></a></p></li>
</ul>
</section>
<section id="access">
<h2>Access<a class="headerlink" href="#access" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Multisession-modes.html"><span class="doc">Multisession modes</span></a></p></li>
<li><p><a class="reference internal" href="Building-Permissions.html"><span class="doc">Permissions</span></a></p></li>
<li><p><a class="reference internal" href="Banning.html"><span class="doc">Banning</span></a></p></li>
<li><p><a class="reference internal" href="Multisession-modes.html"><span class="doc std std-doc">Multisession modes</span></a></p></li>
<li><p><a class="reference internal" href="Building-Permissions.html"><span class="doc std std-doc">Permissions</span></a></p></li>
<li><p><a class="reference internal" href="Banning.html"><span class="doc std std-doc">Banning</span></a></p></li>
</ul>
</section>
<section id="extending-the-server">
<h2>Extending the Server<a class="headerlink" href="#extending-the-server" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Custom-Protocols.html"><span class="doc">Custom Protocols</span></a></p></li>
<li><p><a class="reference internal" href="Bootstrap-%26-Evennia.html"><span class="doc">Bootstrap</span></a></p></li>
<li><p><a class="reference internal" href="New-Models.html"><span class="doc">Creating new models</span></a></p></li>
<li><p><a class="reference internal" href="Custom-Protocols.html"><span class="doc std std-doc">Custom Protocols</span></a></p></li>
<li><p><a class="reference internal" href="Bootstrap-%26-Evennia.html"><span class="doc std std-doc">Bootstrap</span></a></p></li>
<li><p><a class="reference internal" href="New-Models.html"><span class="doc std std-doc">Creating new models</span></a></p></li>
</ul>
</section>
<section id="text-processing">
<h2>Text processing<a class="headerlink" href="#text-processing" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Internationalization.html"><span class="doc">Change the language of the server</span></a></p></li>
<li><p><a class="reference internal" href="Text-Encodings.html"><span class="doc">Server text-encoding</span></a></p></li>
<li><p><a class="reference internal" href="TextTags.html"><span class="doc">Text tags</span></a></p></li>
<li><p><a class="reference internal" href="Internationalization.html"><span class="doc std std-doc">Change the language of the server</span></a></p></li>
<li><p><a class="reference internal" href="Text-Encodings.html"><span class="doc std std-doc">Server text-encoding</span></a></p></li>
<li><p><a class="reference internal" href="TextTags.html"><span class="doc std std-doc">Text tags</span></a></p></li>
</ul>
</section>
<section id="web-features">
<h2>Web features<a class="headerlink" href="#web-features" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Web-Features.html"><span class="doc">Web features</span></a></p></li>
<li><p><a class="reference internal" href="Web-Features.html"><span class="doc std std-doc">Web features</span></a></p></li>
</ul>
</section>
</section>
@ -147,7 +149,7 @@
<h3>Versions</h3>
<ul>
<li><a href="Concepts-Overview.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

150
docs/1.0-dev/Concepts/Custom-Protocols.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,13 +40,13 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="custom-protocols">
<section class="tex2jax_ignore mathjax_ignore" id="custom-protocols">
<h1>Custom Protocols<a class="headerlink" href="#custom-protocols" title="Permalink to this headline"></a></h1>
<p><em>Note: This is considered an advanced topic and is mostly of interest to users planning to implement
their own custom client protocol.</em></p>
<p>A <a class="reference external" href="Components/Sessions.html#Portal-and-Server-Sessions">PortalSession</a> is the basic data object representing an
<p>A <a class="reference internal" href="../Components/Sessions.html#portal-and-server-sessions"><span class="std std-doc">PortalSession</span></a> is the basic data object representing an
external
connection to the Evennia <a class="reference internal" href="../Components/Portal-And-Server.html"><span class="doc">Portal</span></a> – usually a human player running a mud client
connection to the Evennia <a class="reference internal" href="../Components/Portal-And-Server.html"><span class="doc std std-doc">Portal</span></a> – usually a human player running a mud client
of some kind. The way they connect (the language the player’s client and Evennia use to talk to
each other) is called the connection <em>Protocol</em>. The most common such protocol for MUD:s is the
<em>Telnet</em> protocol. All Portal Sessions are stored and managed by the Portal’s <em>sessionhandler</em>.</p>
@ -61,7 +63,7 @@ data flows through this part of the system, this is how it goes</p>
<span class="n">InputFunc</span>
</pre></div>
</div>
<p>(See the <a class="reference internal" href="Messagepath.html"><span class="doc">Message Path</span></a> for the bigger picture of how data flows through Evennia). The
<p>(See the <a class="reference internal" href="Messagepath.html"><span class="doc std std-doc">Message Path</span></a> for the bigger picture of how data flows through Evennia). The
parts that needs to be customized to make your own custom protocol is the <code class="docutils literal notranslate"><span class="pre">Protocol</span> <span class="pre">+</span> <span class="pre">PortalSession</span></code>
(which translates between data coming in/out over the wire to/from Evennia internal representation)
as well as the <code class="docutils literal notranslate"><span class="pre">InputFunc</span></code> (which handles incoming data).</p>
@ -75,15 +77,12 @@ Portal (there is an equivalent but shorter list in <code class="docutils literal
Server, look at <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/server_services_plugins</span></code> and <code class="docutils literal notranslate"><span class="pre">portal_services_plugins</span></code>. By
default Evennia will look into these modules to find plugins. If you wanted to have it look for more
modules, you could do the following:</p>
<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="c1"># add to the Server</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="c1"># add to the Server</span>
<span class="n">SERVER_SERVICES_PLUGIN_MODULES</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;server.conf.my_server_plugins&#39;</span><span class="p">)</span>
<span class="c1"># or, if you want to add to the Portal</span>
<span class="n">PORTAL_SERVICES_PLUGIN_MODULES</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;server.conf.my_portal_plugins&#39;</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>When adding a new connection you’ll most likely only need to add new things to the
<code class="docutils literal notranslate"><span class="pre">PORTAL_SERVICES_PLUGIN_MODULES</span></code>.</p>
<p>This module can contain whatever you need to define your protocol, but it <em>must</em> contain a function
@ -92,30 +91,7 @@ modules, you could do the following:</p>
reference to the Portal/Server application itself so the custom service can be added to it. The
function should not return anything.</p>
<p>This is how it looks:</p>
<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></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="c1"># mygame/server/conf/portal_services_plugins.py</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="c1"># mygame/server/conf/portal_services_plugins.py</span>
<span class="c1"># here the new Portal Twisted protocol is defined</span>
<span class="k">class</span> <span class="nc">MyOwnFactory</span><span class="p">(</span> <span class="o">...</span> <span class="p">):</span>
@ -140,7 +116,7 @@ function should not return anything.</p>
<span class="c1"># add to the main portal application</span>
<span class="n">portal</span><span class="o">.</span><span class="n">services</span><span class="o">.</span><span class="n">addService</span><span class="p">(</span><span class="n">my_service</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Once the module is defined and targeted in settings, just reload the server and your new
protocol/services should start with the others.</p>
</section>
@ -154,98 +130,7 @@ already existing Twisted protocol class and from <code class="docutils literal n
inheritance), then overloading the methods that particular protocol uses to link them to the
Evennia-specific inputs.</p>
<p>Here’s a example to show the concept:</p>
<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>
<span class="normal">45</span>
<span class="normal">46</span>
<span class="normal">47</span>
<span class="normal">48</span>
<span class="normal">49</span>
<span class="normal">50</span>
<span class="normal">51</span>
<span class="normal">52</span>
<span class="normal">53</span>
<span class="normal">54</span>
<span class="normal">55</span>
<span class="normal">56</span>
<span class="normal">57</span>
<span class="normal">58</span>
<span class="normal">59</span>
<span class="normal">60</span>
<span class="normal">61</span>
<span class="normal">62</span>
<span class="normal">63</span>
<span class="normal">64</span>
<span class="normal">65</span>
<span class="normal">66</span>
<span class="normal">67</span>
<span class="normal">68</span>
<span class="normal">69</span>
<span class="normal">70</span>
<span class="normal">71</span>
<span class="normal">72</span>
<span class="normal">73</span>
<span class="normal">74</span>
<span class="normal">75</span>
<span class="normal">76</span>
<span class="normal">77</span>
<span class="normal">78</span>
<span class="normal">79</span>
<span class="normal">80</span>
<span class="normal">81</span>
<span class="normal">82</span>
<span class="normal">83</span>
<span class="normal">84</span>
<span class="normal">85</span>
<span class="normal">86</span>
<span class="normal">87</span>
<span class="normal">88</span>
<span class="normal">89</span>
<span class="normal">90</span>
<span class="normal">91</span>
<span class="normal">92</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># In module that we&#39;ll later add to the system through PORTAL_SERVICE_PLUGIN_MODULES</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># In module that we&#39;ll later add to the system through PORTAL_SERVICE_PLUGIN_MODULES</span>
<span class="c1"># pseudo code </span>
<span class="kn">from</span> <span class="nn">twisted.something</span> <span class="kn">import</span> <span class="n">TwistedClient</span>
@ -337,16 +222,17 @@ Evennia-specific inputs.</p>
<span class="sd"> Handles all outputfuncs without an explicit `send_*` method to handle them.</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="bp">self</span><span class="o">.</span><span class="n">data_out</span><span class="p">(</span><span class="o">**</span><span class="p">{</span><span class="n">cmdname</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">args</span><span class="p">)})</span>
</pre></div>
</td></tr></table></div>
</div>
<p>The principle here is that the Twisted-specific methods are overridden to redirect inputs/outputs to
the Evennia-specific methods.</p>
<section id="sending-data-out">
<h3>Sending data out<a class="headerlink" href="#sending-data-out" title="Permalink to this headline"></a></h3>
<p>To send data out through this protocol, you’d need to get its Session and then you could e.g.</p>
<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">session</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="s2">&quot;foo&quot;</span><span class="p">)</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">session</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="s2">&quot;foo&quot;</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>The message will pass through the system such that the sessionhandler will dig out the session and
check if it has a <code class="docutils literal notranslate"><span class="pre">send_text</span></code> method (it has). It will then pass the “foo” into that method, which
in our case means sending “foo” across the network.</p>
@ -354,11 +240,11 @@ in our case means sending “foo” across the network.</p>
<section id="receiving-data">
<h3>Receiving data<a class="headerlink" href="#receiving-data" title="Permalink to this headline"></a></h3>
<p>Just because the protocol is there, does not mean Evennia knows what to do with it. An
<a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc">Inputfunc</span></a> must exist to receive it. In the case of the <code class="docutils literal notranslate"><span class="pre">text</span></code> input exemplified above,
<a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc std std-doc">Inputfunc</span></a> must exist to receive it. In the case of the <code class="docutils literal notranslate"><span class="pre">text</span></code> input exemplified above,
Evennia alredy handles this input - it will parse it as a Command name followed by its inputs. So
handle that you need to simply add a cmdset with commands on your receiving Session (and/or the
Object/Character it is puppeting). If not you may need to add your own Inputfunc (see the
<a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc">Inputfunc</span></a> page for how to do this.</p>
<a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc std std-doc">Inputfunc</span></a> page for how to do this.</p>
<p>These might not be as clear-cut in all protocols, but the principle is there. These four basic
components - however they are accessed - links to the <em>Portal Session</em>, which is the actual common
interface between the different low-level protocols and Evennia.</p>
@ -429,7 +315,7 @@ ways.</p>
<h3>Versions</h3>
<ul>
<li><a href="Custom-Protocols.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

14
docs/1.0-dev/Concepts/Guest-Logins.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,25 +40,25 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="guest-logins">
<section class="tex2jax_ignore mathjax_ignore" id="guest-logins">
<h1>Guest Logins<a class="headerlink" href="#guest-logins" title="Permalink to this headline"></a></h1>
<p>Evennia supports <em>guest logins</em> out of the box. A guest login is an anonymous, low-access account
and can be useful if you want users to have a chance to try out your game without committing to
creating a real account.</p>
<p>Guest accounts are turned off by default. To activate, add this to your <code class="docutils literal notranslate"><span class="pre">game/settings.py</span></code> file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">GUEST_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>GUEST_ENABLED = True
</pre></div>
</div>
<p>Henceforth users can use <code class="docutils literal notranslate"><span class="pre">connect</span> <span class="pre">guest</span></code> (in the default command set) to login with a guest account.
You may need to change your <a class="reference internal" href="../Components/Connection-Screen.html"><span class="doc">Connection Screen</span></a> to inform them of this
You may need to change your <a class="reference internal" href="../Components/Connection-Screen.html"><span class="doc std std-doc">Connection Screen</span></a> to inform them of this
possibility. Guest accounts work differently from normal accounts - they are automatically <em>deleted</em>
whenever the user logs off or the server resets (but not during a reload). They are literally re-
usable throw-away accounts.</p>
<p>You can add a few more variables to your <code class="docutils literal notranslate"><span class="pre">settings.py</span></code> file to customize your guests:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">BASE_GUEST_TYPECLASS</span></code> - the python-path to the default <a class="reference internal" href="../Components/Typeclasses.html"><span class="doc">typeclass</span></a> for guests.
<li><p><code class="docutils literal notranslate"><span class="pre">BASE_GUEST_TYPECLASS</span></code> - the python-path to the default <a class="reference internal" href="../Components/Typeclasses.html"><span class="doc std std-doc">typeclass</span></a> for guests.
Defaults to <code class="docutils literal notranslate"><span class="pre">&quot;typeclasses.accounts.Guest&quot;</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">PERMISSION_GUEST_DEFAULT</span></code> - <a class="reference internal" href="../Components/Locks.html"><span class="doc">permission level</span></a> for guest accounts. Defaults to <code class="docutils literal notranslate"><span class="pre">&quot;Guests&quot;</span></code>,
<li><p><code class="docutils literal notranslate"><span class="pre">PERMISSION_GUEST_DEFAULT</span></code> - <a class="reference internal" href="../Components/Locks.html"><span class="doc std std-doc">permission level</span></a> for guest accounts. Defaults to <code class="docutils literal notranslate"><span class="pre">&quot;Guests&quot;</span></code>,
which is the lowest permission level in the hierarchy.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">GUEST_START_LOCATION</span></code> - the <code class="docutils literal notranslate"><span class="pre">#dbref</span></code> to the starting location newly logged-in guests should
appear at. Defaults to <code class="docutils literal notranslate"><span class="pre">&quot;#2</span></code> (Limbo).</p></li>
@ -107,7 +109,7 @@ of nine names from <code class="docutils literal notranslate"><span class="pre">
<h3>Versions</h3>
<ul>
<li><a href="Guest-Logins.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

60
docs/1.0-dev/Concepts/Internationalization.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="internationalization">
<section class="tex2jax_ignore mathjax_ignore" id="internationalization">
<h1>Internationalization<a class="headerlink" href="#internationalization" title="Permalink to this headline"></a></h1>
<p><em>Internationalization</em> (often abbreviated <em>i18n</em> since there are 18 characters
between the first “i” and the last “n” in that word) allows Evennia’s core
@ -103,36 +105,40 @@ updated after May 2021 will be missing some translations.</p>
</tr>
</tbody>
</table>
<p>Language translations are found in the <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/locale">evennia/locale</a>
<p>Language translations are found in the <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/locale/">evennia/locale</a>
folder. Read below if you want to help improve an existing translation of
contribute a new one.</p>
<section id="changing-server-language">
<h2>Changing server language<a class="headerlink" href="#changing-server-language" title="Permalink to this headline"></a></h2>
<p>Change language by adding the following to your <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code>
file:</p>
<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">USE_I18N</span> <span class="o">=</span> <span class="kc">True</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">USE_I18N</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">LANGUAGE_CODE</span> <span class="o">=</span> <span class="s1">&#39;en&#39;</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Here <code class="docutils literal notranslate"><span class="pre">'en'</span></code> (the default English) should be changed to the abbreviation for one
of the supported languages found in <code class="docutils literal notranslate"><span class="pre">locale/</span></code> (and in the list above). Restart
the server to activate i18n.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Even for a ‘fully translated’ language you will still see English text
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Even for a &#39;fully translated&#39; language you will still see English text
in many places when you start Evennia. This is because we expect you (the
developer) to know English (you are reading this manual after all). So we
translate <em>hard-coded strings that the end player may see</em> - things you
can’t easily change from your mygame/ folder. Outputs from Commands and
Typeclasses are generally <em>not</em> translated, nor are console/log outputs.</p>
translate *hard-coded strings that the end player may see* - things you
can&#39;t easily change from your mygame/ folder. Outputs from Commands and
Typeclasses are generally *not* translated, nor are console/log outputs.
</pre></div>
</div>
</div>
<aside class="sidebar">
<p class="sidebar-title">Windows users</p>
<p>If you get errors concerning <cite>gettext</cite> or <cite>xgettext</cite> on Windows,
see the <a class="reference external" href="https://docs.djangoproject.com/en/3.2/topics/i18n/translation/#gettext-on-windows">Django documentation</a>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>If you get errors concerning `gettext` or `xgettext` on Windows,
see the `Django documentation &lt;https://docs.djangoproject.com/en/3.2/topics/i18n/translation/#gettext-on-windows&gt;`_
A self-installing and up-to-date version of gettext for Windows (32/64-bit) is
available on <a class="reference external" href="https://github.com/mlocati/gettext-iconv-windows">Github</a></p>
available on `Github &lt;https://github.com/mlocati/gettext-iconv-windows&gt;`_
</pre></div>
</div>
</aside>
</section>
<section id="translating-evennia">
@ -145,18 +151,18 @@ has translated it yet. Alternatively you might have the language but find the
translation bad … You are welcome to help improve the situation!</p>
<p>To start a new translation you need to first have cloned the Evennia repositry
with GIT and activated a python virtualenv as described on the
<a class="reference internal" href="../Setup/Setup-Quickstart.html"><span class="doc">Setup Quickstart</span></a> page.</p>
<a class="reference internal" href="../Setup/Setup-Quickstart.html"><span class="doc std std-doc">Setup Quickstart</span></a> page.</p>
<p>Go to <code class="docutils literal notranslate"><span class="pre">evennia/evennia/</span></code> - that is, not your game dir, but inside the <code class="docutils literal notranslate"><span class="pre">evennia/</span></code>
repo itself. If you see the <code class="docutils literal notranslate"><span class="pre">locale/</span></code> folder you are in the right place. Make
sure your <code class="docutils literal notranslate"><span class="pre">virtualenv</span></code> is active so the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command is available. Then run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">evennia</span> <span class="n">makemessages</span> <span class="o">--</span><span class="n">locale</span> <span class="o">&lt;</span><span class="n">language</span><span class="o">-</span><span class="n">code</span><span class="o">&gt;</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> evennia makemessages --locale &lt;language-code&gt;
</pre></div>
</div>
<p>where <code class="docutils literal notranslate"><span class="pre">&lt;language-code&gt;</span></code> is the <a class="reference external" href="http://www.science.co.il/Language/Codes.asp">two-letter locale code</a>
for the language you want to translate, like ‘sv’ for Swedish or ‘es’ for
Spanish. After a moment it will tell you the language has been processed. For
instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">evennia</span> <span class="n">makemessages</span> <span class="o">--</span><span class="n">locale</span> <span class="n">sv</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> evennia makemessages --locale sv
</pre></div>
</div>
<p>If you started a new language, a new folder for that language will have emerged
@ -168,14 +174,14 @@ want.</p>
find there. You can edit this with a normal text editor but it is easiest if
you use a special po-file editor from the web (search the web for “po editor”
for many free alternatives), for example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span> <span class="p">[</span><span class="n">gtranslator</span><span class="p">](</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">wiki</span><span class="o">.</span><span class="n">gnome</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">Apps</span><span class="o">/</span><span class="n">Gtranslator</span><span class="p">)</span>
<span class="o">-</span> <span class="p">[</span><span class="n">poeditor</span><span class="p">](</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">poeditor</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="p">)</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>- [gtranslator](https://wiki.gnome.org/Apps/Gtranslator)
- [poeditor](https://poeditor.com/)
</pre></div>
</div>
<p>The concept of translating is simple, it’s just a matter of taking the english
strings you find in the <code class="docutils literal notranslate"><span class="pre">**.po</span></code> file and add your language’s translation best
you can. Once you are done, run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>`evennia compilemessages`
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>`evennia compilemessages`
</pre></div>
</div>
<p>This will compile all languages. Check your language and also check back to your
@ -190,15 +196,15 @@ not your thing) you can also attach it to a new post in our forums.</p>
are to be used in <code class="docutils literal notranslate"><span class="pre">.format()</span></code> python operations. While you can change the
<em>order</em> of these if it makes more sense in your language, you must <em>not</em>
translate the variables in these formatting tags - Python will look for them!</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Original</span><span class="p">:</span> <span class="s2">&quot;|G</span><span class="si">{key}</span><span class="s2"> connected|n&quot;</span>
<span class="n">Swedish</span><span class="p">:</span> <span class="s2">&quot;|G</span><span class="si">{key}</span><span class="s2"> anslöt|n&quot;</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Original: &quot;|G{key} connected|n&quot;
Swedish: &quot;|G{key} anslöt|n&quot;
</pre></div>
</div>
<p>You must also retain line breaks <em>at the start and end</em> of a message, if any
(your po-editor should stop you if you don’t). Try to also end with the same
sentence delimiter (if that makes sense in your language).</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Original</span><span class="p">:</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">(Unsuccessfull tried &#39;</span><span class="si">{path}</span><span class="s2">&#39;).&quot;</span>
<span class="n">Swedish</span><span class="p">:</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">Misslyckades med att nå &#39;</span><span class="si">{path}</span><span class="s2">&#39;).&quot;</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Original: &quot;\n(Unsuccessfull tried &#39;{path}&#39;).&quot;
Swedish: &quot;\nMisslyckades med att nå &#39;{path}&#39;).&quot;
</pre></div>
</div>
<p>Finally, try to get a feel for who a string is for. If a special technical term
@ -207,10 +213,10 @@ outside of a <code class="docutils literal notranslate"><span class="pre">{...}<
English, clarity is more important. Many languages may also use the English term
normally and reaching for a translation may make the result sound awkward
instead.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Original</span><span class="p">:</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">Error loading cmdset: No cmdset class &#39;</span><span class="si">{classname}</span><span class="s2">&#39; in &#39;</span><span class="si">{path}</span><span class="s2">&#39;.</span>
\<span class="n">n</span><span class="p">(</span><span class="n">Traceback</span> <span class="n">was</span> <span class="n">logged</span> <span class="p">{</span><span class="n">timestamp</span><span class="p">})</span><span class="s2">&quot;</span>
<span class="n">Swedish</span><span class="p">:</span> <span class="s2">&quot;Fel medan cmdset laddades: Ingen cmdset-klass med namn &#39;</span><span class="si">{classname}</span><span class="s2">&#39; i </span><span class="si">{path}</span><span class="s2">.</span>
\<span class="n">n</span><span class="p">(</span><span class="n">Traceback</span> <span class="n">loggades</span> <span class="p">{</span><span class="n">timestamp</span><span class="p">})</span><span class="s2">&quot;</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Original: &quot;\nError loading cmdset: No cmdset class &#39;{classname}&#39; in &#39;{path}&#39;.
\n(Traceback was logged {timestamp})&quot;
Swedish: &quot;Fel medan cmdset laddades: Ingen cmdset-klass med namn &#39;{classname}&#39; i {path}.
\n(Traceback loggades {timestamp})&quot;
</pre></div>
</div>
</section>
@ -269,7 +275,7 @@ instead.</p>
<h3>Versions</h3>
<ul>
<li><a href="Internationalization.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

67
docs/1.0-dev/Concepts/Messagepath.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="messagepath">
<section class="tex2jax_ignore mathjax_ignore" id="messagepath">
<h1>Messagepath<a class="headerlink" href="#messagepath" title="Permalink to this headline"></a></h1>
<p>The main functionality of Evennia is to communicate with clients connected to it; a player enters
commands or their client queries for a gui update (ingoing data). The server responds or sends data
@ -47,13 +49,13 @@ information works in Evennia.</p>
<section id="the-ingoing-message-path">
<h2>The ingoing message path<a class="headerlink" href="#the-ingoing-message-path" title="Permalink to this headline"></a></h2>
<p>We’ll start by tracing data from the client to the server. Here it is in short:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Client</span> <span class="o">-&gt;</span>
<span class="n">PortalSession</span> <span class="o">-&gt;</span>
<span class="n">PortalSessionhandler</span> <span class="o">-&gt;</span>
<span class="p">(</span><span class="n">AMP</span><span class="p">)</span> <span class="o">-&gt;</span>
<span class="n">ServerSessionHandler</span> <span class="o">-&gt;</span>
<span class="n">ServerSession</span> <span class="o">-&gt;</span>
<span class="n">Inputfunc</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Client -&gt;
PortalSession -&gt;
PortalSessionhandler -&gt;
(AMP) -&gt;
ServerSessionHandler -&gt;
ServerSession -&gt;
Inputfunc
</pre></div>
</div>
<section id="client-ingoing">
@ -63,7 +65,7 @@ information works in Evennia.</p>
<li><p>When first connecting, the client can send data to the server about its
capabilities. This is things like “I support xterm256 but not unicode” and is
mainly used when a Telnet client connects. This is called a “handshake” and
will generally set some flags on the <a class="reference internal" href="../Components/Portal-And-Server.html"><span class="doc">Portal Session</span></a> that
will generally set some flags on the <a class="reference internal" href="../Components/Portal-And-Server.html"><span class="doc std std-doc">Portal Session</span></a> that
are later synced to the Server Session. Since this is not something the player
controls, we’ll not explore this further here.</p></li>
<li><p>The client can send an <em>inputcommand</em> to the server. Traditionally this only
@ -72,7 +74,7 @@ client GUI, a command could also come from the pressing of a button. Finally
the client may send commands based on a timer or some trigger.</p></li>
</ul>
<p>Exactly how the inputcommand looks when it travels from the client to Evennia
depends on the <a class="reference internal" href="Custom-Protocols.html"><span class="doc">Protocol</span></a> used:</p>
depends on the <a class="reference internal" href="Custom-Protocols.html"><span class="doc std std-doc">Protocol</span></a> used:</p>
<ul class="simple">
<li><p>Telnet: A string. If GMCP or MSDP OOB protocols are used, this string will
be formatted in a special way, but it’s still a raw string. If Telnet SSL is
@ -94,22 +96,22 @@ that anything arriving normally over the wire should be passed on as a “text
<p>The <em>PortalSessionhandler</em> manages all connected Sessions in the Portal. Its <code class="docutils literal notranslate"><span class="pre">data_in</span></code> method
(called by each Portal Session) will parse the command names and arguments from the protocols and
convert them to a standardized form we call the <em>inputcommand</em>:</p>
<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="p">(</span><span class="n">commandname</span><span class="p">,</span> <span class="p">(</span><span class="n">args</span><span class="p">),</span> <span class="p">{</span><span class="n">kwargs</span><span class="p">})</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="p">(</span><span class="n">commandname</span><span class="p">,</span> <span class="p">(</span><span class="n">args</span><span class="p">),</span> <span class="p">{</span><span class="n">kwargs</span><span class="p">})</span>
</pre></div>
</td></tr></table></div>
</div>
<p>All inputcommands must have a name, but they may or may not have arguments and keyword arguments -
in fact no default inputcommands use kwargs at all. The most common inputcommand is “text”, which
has the argument the player input on the command line:</p>
<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="p">(</span><span class="s2">&quot;text&quot;</span><span class="p">,</span> <span class="p">(</span><span class="s2">&quot;look&quot;</span><span class="p">,),</span> <span class="p">{})</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="p">(</span><span class="s2">&quot;text&quot;</span><span class="p">,</span> <span class="p">(</span><span class="s2">&quot;look&quot;</span><span class="p">,),</span> <span class="p">{})</span>
</pre></div>
</td></tr></table></div>
</div>
<p>This inputcommand-structure is pickled together with the unique session-id of the Session to which
it belongs. This is then sent over the AMP connection.</p>
</section>
<section id="serversessionhandler-ingoing">
<h3>ServerSessionHandler (ingoing)<a class="headerlink" href="#serversessionhandler-ingoing" title="Permalink to this headline"></a></h3>
<p>On the Server side, the AMP unpickles the data and associates the session id with the server-side
<a class="reference internal" href="../Components/Sessions.html"><span class="doc">Session</span></a>. Data and Session are passed to the server-side <code class="docutils literal notranslate"><span class="pre">SessionHandler.data_in</span></code>. This
<a class="reference internal" href="../Components/Sessions.html"><span class="doc std std-doc">Session</span></a>. Data and Session are passed to the server-side <code class="docutils literal notranslate"><span class="pre">SessionHandler.data_in</span></code>. This
in turn calls <code class="docutils literal notranslate"><span class="pre">ServerSession.data_in()</span></code></p>
</section>
<section id="serversession-ingoing">
@ -125,15 +127,15 @@ just normal functions and one can plugin new ones by simply putting them in a mo
looks for such functions.</p>
<p>If a matching inputfunc is found, it will be called with the Session and the inputcommand’s
arguments:</p>
<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">text</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="o">*</span><span class="p">(</span><span class="s2">&quot;look&quot;</span><span class="p">,),</span> <span class="o">**</span><span class="p">{})</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">text</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="o">*</span><span class="p">(</span><span class="s2">&quot;look&quot;</span><span class="p">,),</span> <span class="o">**</span><span class="p">{})</span>
</pre></div>
</td></tr></table></div>
</div>
<p>If no matching inputfunc is found, an inputfunc named “default” will be tried and if that is also
not found, an error will be raised.</p>
</section>
<section id="inputfunc">
<h3>Inputfunc<a class="headerlink" href="#inputfunc" title="Permalink to this headline"></a></h3>
<p>The <a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc">Inputfunc</span></a> must be on the form <code class="docutils literal notranslate"><span class="pre">func(session,</span> <span class="pre">*args,</span> <span class="pre">**kwargs)</span></code>. An exception is
<p>The <a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc std std-doc">Inputfunc</span></a> must be on the form <code class="docutils literal notranslate"><span class="pre">func(session,</span> <span class="pre">*args,</span> <span class="pre">**kwargs)</span></code>. An exception is
the <code class="docutils literal notranslate"><span class="pre">default</span></code> inputfunc which has form <code class="docutils literal notranslate"><span class="pre">default(session,</span> <span class="pre">cmdname,</span> <span class="pre">*args,</span> <span class="pre">**kwargs)</span></code>, where <code class="docutils literal notranslate"><span class="pre">cmdname</span></code>
is the un-matched inputcommand string.</p>
<p>This is where the message’s path diverges, since just what happens next depends on the type of
@ -145,13 +147,13 @@ executed.</p>
<section id="the-outgoing-message-path">
<h2>The outgoing message path<a class="headerlink" href="#the-outgoing-message-path" title="Permalink to this headline"></a></h2>
<p>Next let’s trace the passage from server to client.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">msg</span> <span class="o">-&gt;</span>
<span class="n">ServerSession</span> <span class="o">-&gt;</span>
<span class="n">ServerSessionHandler</span> <span class="o">-&gt;</span>
<span class="p">(</span><span class="n">AMP</span><span class="p">)</span> <span class="o">-&gt;</span>
<span class="n">PortalSessionHandler</span> <span class="o">-&gt;</span>
<span class="n">PortalSession</span> <span class="o">-&gt;</span>
<span class="n">Client</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>msg -&gt;
ServerSession -&gt;
ServerSessionHandler -&gt;
(AMP) -&gt;
PortalSessionHandler -&gt;
PortalSession -&gt;
Client
</pre></div>
</div>
<section id="msg">
@ -163,21 +165,20 @@ executed.</p>
<li><p><code class="docutils literal notranslate"><span class="pre">Session.msg</span></code></p></li>
</ul>
<p>The call sign of the <code class="docutils literal notranslate"><span class="pre">msg</span></code> method looks like this:</p>
<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">msg</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">from_obj</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">session</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">msg</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">from_obj</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">session</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>For our purposes, what is important to know is that with the exception of <code class="docutils literal notranslate"><span class="pre">from_obj</span></code>, <code class="docutils literal notranslate"><span class="pre">session</span></code> and
<code class="docutils literal notranslate"><span class="pre">options</span></code>, all keywords given to the <code class="docutils literal notranslate"><span class="pre">msg</span></code> method is the name of an <em>outputcommand</em> and its
arguments. So <code class="docutils literal notranslate"><span class="pre">text</span></code> is actually such a command, taking a string as its argument. The reason <code class="docutils literal notranslate"><span class="pre">text</span></code>
sits as the first keyword argument is that it’s so commonly used (<code class="docutils literal notranslate"><span class="pre">caller.msg(&quot;Text&quot;)</span></code> for example).
Here are some examples</p>
<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></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Hello!&quot;</span><span class="p">)</span> <span class="c1"># using the &#39;text&#39; outputfunc</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Hello!&quot;</span><span class="p">)</span> <span class="c1"># using the &#39;text&#39; outputfunc</span>
<span class="n">msg</span><span class="p">(</span><span class="n">prompt</span><span class="o">=</span><span class="sa">f</span><span class="s2">&quot;HP: </span><span class="si">{</span><span class="n">HP</span><span class="si">}</span><span class="s2">, SP: </span><span class="si">{</span><span class="n">SP</span><span class="si">}</span><span class="s2">, MP: </span><span class="si">{</span><span class="n">MP</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
<span class="n">msg</span><span class="p">(</span><span class="n">mycommand</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><span class="mi">4</span><span class="p">),</span> <span class="p">{</span><span class="s2">&quot;foo&quot;</span><span class="p">:</span> <span class="s2">&quot;bar&quot;</span><span class="p">})</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Note the form of the <code class="docutils literal notranslate"><span class="pre">mycommand</span></code> outputfunction. This explicitly defines the arguments and keyword
arguments for the function. In the case of the <code class="docutils literal notranslate"><span class="pre">text</span></code> and <code class="docutils literal notranslate"><span class="pre">prompt</span></code> calls we just specify a string -
this works too: The system will convert this into a single argument for us later in the message
@ -202,7 +203,7 @@ It immediately passes the data on to …</p>
</div>
<p>This will intelligently convert different input to the same form. So <code class="docutils literal notranslate"><span class="pre">msg(&quot;Hello&quot;)</span></code> will end up as
an outputcommand <code class="docutils literal notranslate"><span class="pre">(&quot;text&quot;,</span> <span class="pre">(&quot;Hello&quot;,),</span> <span class="pre">{})</span></code>.</p>
<p>This is also the point where <a class="reference external" href="Concepts/TextTags.html#inline-functions">Inlinefuncs</a> are parsed, depending on the
<p>This is also the point where the <a class="reference internal" href="../Components/FuncParser.html"><span class="doc std std-doc">FuncParser</span></a>) is applied, depending on the
session to receive the data. Said data is pickled together with the Session id then sent over the
AMP bridge.</p>
</section>
@ -303,7 +304,7 @@ may trigger changes in the GUI or play a sound etc.</p>
<h3>Versions</h3>
<ul>
<li><a href="Messagepath.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

6
docs/1.0-dev/Concepts/Multisession-modes.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="multisession-modes">
<section class="tex2jax_ignore mathjax_ignore" id="multisession-modes">
<h1>Multisession modes<a class="headerlink" href="#multisession-modes" title="Permalink to this headline"></a></h1>
<p>TODO: This is covered in various places before.</p>
</section>
@ -83,7 +85,7 @@
<h3>Versions</h3>
<ul>
<li><a href="Multisession-modes.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

107
docs/1.0-dev/Concepts/New-Models.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="new-models">
<section class="tex2jax_ignore mathjax_ignore" id="new-models">
<h1>New Models<a class="headerlink" href="#new-models" title="Permalink to this headline"></a></h1>
<p><em>Note: This is considered an advanced topic.</em></p>
<p>Evennia offers many convenient ways to store object data, such as via Attributes or Scripts. This is
@ -46,7 +48,7 @@ sufficient for most use cases. But if you aim to build a large stand-alone syste
your storage requirements into those may be more complex than you bargain for. Examples may be to
store guild data for guild members to be able to change, tracking the flow of money across a game-
wide economic system or implement other custom game systems that requires the storage of custom data
in a quickly accessible way. Whereas <a class="reference internal" href="../Components/Tags.html"><span class="doc">Tags</span></a> or <a class="reference internal" href="../Components/Scripts.html"><span class="doc">Scripts</span></a> can handle many situations,
in a quickly accessible way. Whereas <a class="reference internal" href="../Components/Tags.html"><span class="doc std std-doc">Tags</span></a> or <a class="reference internal" href="../Components/Scripts.html"><span class="doc std std-doc">Scripts</span></a> can handle many situations,
sometimes things may be easier to handle by adding your own database model.</p>
<section id="overview-of-database-tables">
<h2>Overview of database tables<a class="headerlink" href="#overview-of-database-tables" title="Permalink to this headline"></a></h2>
@ -61,21 +63,21 @@ retrieving text stored in tables. A table may look like this</p>
<p>Each line is considerably longer in your database. Each column is referred to as a “field” and every
row is a separate object. You can check this out for yourself. If you use the default sqlite3
database, go to your game folder and run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">evennia</span> <span class="n">dbshell</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> evennia dbshell
</pre></div>
</div>
<p>You will drop into the database shell. While there, try:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">sqlite</span><span class="o">&gt;</span> <span class="o">.</span><span class="n">help</span> <span class="c1"># view help</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> sqlite&gt; .help # view help
<span class="n">sqlite</span><span class="o">&gt;</span> <span class="o">.</span><span class="n">tables</span> <span class="c1"># view all tables</span>
sqlite&gt; .tables # view all tables
<span class="c1"># show the table field names for objects_objectdb</span>
<span class="n">sqlite</span><span class="o">&gt;</span> <span class="o">.</span><span class="n">schema</span> <span class="n">objects_objectdb</span>
# show the table field names for objects_objectdb
sqlite&gt; .schema objects_objectdb
<span class="c1"># show the first row from the objects_objectdb table</span>
<span class="n">sqlite</span><span class="o">&gt;</span> <span class="n">select</span> <span class="o">*</span> <span class="kn">from</span> <span class="nn">objects_objectdb</span> <span class="n">limit</span> <span class="mi">1</span><span class="p">;</span>
# show the first row from the objects_objectdb table
sqlite&gt; select * from objects_objectdb limit 1;
<span class="n">sqlite</span><span class="o">&gt;</span> <span class="o">.</span><span class="n">exit</span>
sqlite&gt; .exit
</pre></div>
</div>
<p>Evennia uses <a class="reference external" href="https://docs.djangoproject.com">Django</a>, which abstracts away the database SQL
@ -92,8 +94,8 @@ extend and build on.</p>
For this example we’ll call it “myapp”. Run the following (you need to have a working Evennia
running before you do this, so make sure you have run the steps in [Setup Quickstart](Getting-
Started) first):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">cd</span> <span class="n">mygame</span><span class="o">/</span><span class="n">world</span>
<span class="n">evennia</span> <span class="n">startapp</span> <span class="n">myapp</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> cd mygame/world
evennia startapp myapp
</pre></div>
</div>
</li>
@ -112,14 +114,14 @@ you put <code class="docutils literal notranslate"><span class="pre">myapp</span
</div>
</li>
<li><p>From <code class="docutils literal notranslate"><span class="pre">mygame/</span></code>, run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">evennia</span> <span class="n">makemigrations</span> <span class="n">myapp</span>
<span class="n">evennia</span> <span class="n">migrate</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> evennia makemigrations myapp
evennia migrate
</pre></div>
</div>
</li>
</ol>
<p>This will add your new database table to the database. If you have put your game under version
control (if not, <a class="reference internal" href="../Coding/Version-Control.html"><span class="doc">you should</span></a>), don’t forget to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span> <span class="pre">myapp/*</span></code> to add all items
control (if not, <a class="reference internal" href="../Coding/Version-Control.html"><span class="doc std std-doc">you should</span></a>), don’t forget to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span> <span class="pre">myapp/*</span></code> to add all items
to version control.</p>
</section>
<section id="defining-your-models">
@ -131,17 +133,7 @@ database.</p>
<p>We won’t describe all aspects of Django models here, for that we refer to the vast <a class="reference external" href="https://docs.djangoproject.com/en/2.2/topics/db/models/">Django
documentation</a> on the subject. Here is a
(very) brief example:</p>
<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">django.db</span> <span class="kn">import</span> <span class="n">models</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">models</span>
<span class="k">class</span> <span class="nc">MyDataStore</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
<span class="s2">&quot;A simple model for storing some data&quot;</span>
@ -153,12 +145,12 @@ documentation</a> on the subject. Here is a
<span class="n">db_date_created</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">DateTimeField</span><span class="p">(</span><span class="s1">&#39;date created&#39;</span><span class="p">,</span> <span class="n">editable</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
<span class="n">auto_now_add</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">db_index</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>We create four fields: two character fields of limited length and one text field which has no
maximum length. Finally we create a field containing the current time of us creating this object.</p>
<blockquote>
<div><p>The <code class="docutils literal notranslate"><span class="pre">db_date_created</span></code> field, with exactly this name, is <em>required</em> if you want to be able to store
instances of your custom model in an Evennia <a class="reference internal" href="../Components/Attributes.html"><span class="doc">Attribute</span></a>. It will automatically be set
instances of your custom model in an Evennia <a class="reference internal" href="../Components/Attributes.html"><span class="doc std std-doc">Attribute</span></a>. It will automatically be set
upon creation and can after that not be changed. Having this field will allow you to do e.g.
<code class="docutils literal notranslate"><span class="pre">obj.db.myinstance</span> <span class="pre">=</span> <span class="pre">mydatastore</span></code>. If you know you’ll never store your model instances in Attributes
the <code class="docutils literal notranslate"><span class="pre">db_date_created</span></code> field is optional.</p>
@ -180,31 +172,25 @@ point for your models.</p>
<section id="creating-a-new-model-instance">
<h2>Creating a new model instance<a class="headerlink" href="#creating-a-new-model-instance" title="Permalink to this headline"></a></h2>
<p>To create a new row in your table, you instantiate the model and then call its <code class="docutils literal notranslate"><span class="pre">save()</span></code> method:</p>
<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">from</span> <span class="nn">evennia.myapp</span> <span class="kn">import</span> <span class="n">MyDataStore</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.myapp</span> <span class="kn">import</span> <span class="n">MyDataStore</span>
<span class="n">new_datastore</span> <span class="o">=</span> <span class="n">MyDataStore</span><span class="p">(</span><span class="n">db_key</span><span class="o">=</span><span class="s2">&quot;LargeSword&quot;</span><span class="p">,</span>
<span class="n">db_category</span><span class="o">=</span><span class="s2">&quot;weapons&quot;</span><span class="p">,</span>
<span class="n">db_text</span><span class="o">=</span><span class="s2">&quot;This is a huge weapon!&quot;</span><span class="p">)</span>
<span class="c1"># this is required to actually create the row in the database!</span>
<span class="n">new_datastore</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Note that the <code class="docutils literal notranslate"><span class="pre">db_date_created</span></code> field of the model is not specified. Its flag <code class="docutils literal notranslate"><span class="pre">at_now_add=True</span></code>
makes sure to set it to the current date when the object is created (it can also not be changed
further after creation).</p>
<p>When you update an existing object with some new field value, remember that you have to save the
object afterwards, otherwise the database will not update:</p>
<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">my_datastore</span><span class="o">.</span><span class="n">db_key</span> <span class="o">=</span> <span class="s2">&quot;Larger Sword&quot;</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">my_datastore</span><span class="o">.</span><span class="n">db_key</span> <span class="o">=</span> <span class="s2">&quot;Larger Sword&quot;</span>
<span class="n">my_datastore</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Evennia’s normal models don’t need to explicitly save, since they are based on <code class="docutils literal notranslate"><span class="pre">SharedMemoryModel</span></code>
rather than the raw django model. This is covered in the next section.</p>
</section>
@ -221,26 +207,24 @@ will automatically create field wrappers for them. This happens in the model’s
<a class="reference external" href="http://en.wikibooks.org/wiki/Python_Programming/Metaclasses">Metaclass</a> so there is no speed
penalty for this. The name of the wrapper will be the same name as the field, minus the <code class="docutils literal notranslate"><span class="pre">db_</span></code>
prefix. So the <code class="docutils literal notranslate"><span class="pre">db_key</span></code> field will have a wrapper property named <code class="docutils literal notranslate"><span class="pre">key</span></code>. You can then do:</p>
<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">my_datastore</span><span class="o">.</span><span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;Larger Sword&quot;</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">my_datastore</span><span class="o">.</span><span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;Larger Sword&quot;</span>
</pre></div>
</td></tr></table></div>
</div>
<p>and don’t have to explicitly call <code class="docutils literal notranslate"><span class="pre">save()</span></code> afterwards. The saving also happens in a more efficient
way under the hood, updating only the field rather than the entire model using django optimizations.
Note that if you were to manually add the property or method <code class="docutils literal notranslate"><span class="pre">key</span></code> to your model, this will be used
instead of the automatic wrapper and allows you to fully customize access as needed.</p>
<p>To explain the second and more important point, consider the following example using the default
Django model parent:</p>
<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">shield</span> <span class="o">=</span> <span class="n">MyDataStore</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">db_key</span><span class="o">=</span><span class="s2">&quot;SmallShield&quot;</span><span class="p">)</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">shield</span> <span class="o">=</span> <span class="n">MyDataStore</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">db_key</span><span class="o">=</span><span class="s2">&quot;SmallShield&quot;</span><span class="p">)</span>
<span class="n">shield</span><span class="o">.</span><span class="n">cracked</span> <span class="o">=</span> <span class="kc">True</span> <span class="c1"># where cracked is not a database field</span>
</pre></div>
</td></tr></table></div>
</div>
<p>And then later:</p>
<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">shield</span> <span class="o">=</span> <span class="n">MyDataStore</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">db_key</span><span class="o">=</span><span class="s2">&quot;SmallShield&quot;</span><span class="p">)</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">shield</span> <span class="o">=</span> <span class="n">MyDataStore</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">db_key</span><span class="o">=</span><span class="s2">&quot;SmallShield&quot;</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">shield</span><span class="o">.</span><span class="n">cracked</span><span class="p">)</span> <span class="c1"># error!</span>
</pre></div>
</td></tr></table></div>
</div>
<p>The outcome of that last print statement is <em>undefined</em>! It could <em>maybe</em> randomly work but most
likely you will get an <code class="docutils literal notranslate"><span class="pre">AttributeError</span></code> for not finding the <code class="docutils literal notranslate"><span class="pre">cracked</span></code> property. The reason is that
<code class="docutils literal notranslate"><span class="pre">cracked</span></code> doesn’t represent an actual field in the database. It was just added at run-time and thus
@ -262,16 +246,7 @@ idmapper.</p>
<p>To use the idmapper and the field-wrapper functionality you just have to have your model classes
inherit from <code class="docutils literal notranslate"><span class="pre">evennia.utils.idmapper.models.SharedMemoryModel</span></code> instead of from the default
<code class="docutils literal notranslate"><span class="pre">django.db.models.Model</span></code>:</p>
<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="kn">from</span> <span class="nn">evennia.utils.idmapper.models</span> <span class="kn">import</span> <span class="n">SharedMemoryModel</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia.utils.idmapper.models</span> <span class="kn">import</span> <span class="n">SharedMemoryModel</span>
<span class="k">class</span> <span class="nc">MyDataStore</span><span class="p">(</span><span class="n">SharedMemoryModel</span><span class="p">):</span>
<span class="c1"># the rest is the same as before, but db_* is important; these will</span>
@ -282,24 +257,14 @@ inherit from <code class="docutils literal notranslate"><span class="pre">evenni
<span class="n">db_date_created</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">DateTimeField</span><span class="p">(</span><span class="s1">&#39;date created&#39;</span><span class="p">,</span> <span class="n">editable</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
<span class="n">auto_now_add</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">db_index</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
</section>
<section id="searching-for-your-models">
<h2>Searching for your models<a class="headerlink" href="#searching-for-your-models" title="Permalink to this headline"></a></h2>
<p>To search your new custom database table you need to use its database <em>manager</em> to build a <em>query</em>.
Note that even if you use <code class="docutils literal notranslate"><span class="pre">SharedMemoryModel</span></code> as described in the previous section, you have to use
the actual <em>field names</em> in the query, not the wrapper name (so <code class="docutils literal notranslate"><span class="pre">db_key</span></code> and not just <code class="docutils literal notranslate"><span class="pre">key</span></code>).</p>
<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">world.myapp</span> <span class="kn">import</span> <span class="n">MyDataStore</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">world.myapp</span> <span class="kn">import</span> <span class="n">MyDataStore</span>
<span class="c1"># get all datastore objects exactly matching a given key</span>
<span class="n">matches</span> <span class="o">=</span> <span class="n">MyDataStore</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">db_key</span><span class="o">=</span><span class="s2">&quot;Larger Sword&quot;</span><span class="p">)</span>
@ -311,7 +276,7 @@ the actual <em>field names</em> in the query, not the wrapper name (so <code cla
<span class="k">for</span> <span class="n">match</span> <span class="ow">in</span> <span class="n">matches2</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="n">match</span><span class="o">.</span><span class="n">db_text</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>See the <a class="reference external" href="https://docs.djangoproject.com/en/2.2/topics/db/queries/">Django query documentation</a> for a
lot more information about querying the database.</p>
</section>
@ -370,7 +335,7 @@ lot more information about querying the database.</p>
<h3>Versions</h3>
<ul>
<li><a href="New-Models.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

72
docs/1.0-dev/Concepts/OOB.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="oob">
<section class="tex2jax_ignore mathjax_ignore" id="oob">
<h1>OOB<a class="headerlink" href="#oob" title="Permalink to this headline"></a></h1>
<p>OOB, or Out-Of-Band, means sending data between Evennia and the user’s client without the user
prompting it or necessarily being aware that it’s being passed. Common uses would be to update
@ -47,39 +49,38 @@ window pane.</p>
<section id="briefly-on-input-outputcommands">
<h2>Briefly on input/outputcommands<a class="headerlink" href="#briefly-on-input-outputcommands" title="Permalink to this headline"></a></h2>
<p>Inside Evennia, all server-client communication happens in the same way (so plain text is also an
‘OOB message’ as far as Evennia is concerned). The message follows the <a class="reference internal" href="Messagepath.html"><span class="doc">Message Path</span></a>.
‘OOB message’ as far as Evennia is concerned). The message follows the <a class="reference internal" href="Messagepath.html"><span class="doc std std-doc">Message Path</span></a>.
You should read up on that if you are unfamiliar with it. As the message travels along the path it
has a standardized internal form: a tuple with a string, a tuple and a dict:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="s2">&quot;cmdname&quot;</span><span class="p">,</span> <span class="p">(</span><span class="n">args</span><span class="p">),</span> <span class="p">{</span><span class="n">kwargs</span><span class="p">})</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>(&quot;cmdname&quot;, (args), {kwargs})
</pre></div>
</div>
<p>This is often referred to as an <em>inputcommand</em> or <em>outputcommand</em>, depending on the direction it’s
traveling. The end point for an inputcommand, (the ‘Evennia-end’ of the message path) is a matching
<a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc">Inputfunc</span></a>. This function is called as <code class="docutils literal notranslate"><span class="pre">cmdname(session,</span> <span class="pre">*args,</span> <span class="pre">**kwargs)</span></code> where
<a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc std std-doc">Inputfunc</span></a>. This function is called as <code class="docutils literal notranslate"><span class="pre">cmdname(session,</span> <span class="pre">*args,</span> <span class="pre">**kwargs)</span></code> where
<code class="docutils literal notranslate"><span class="pre">session</span></code> is the Session-source of the command. Inputfuncs can easily be added by the developer to
support/map client commands to actions inside Evennia (see the <a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc">inputfunc</span></a> page for more
support/map client commands to actions inside Evennia (see the <a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc std std-doc">inputfunc</span></a> page for more
details).</p>
<p>When a message is outgoing (at the ‘Client-end’ of the message path) the outputcommand is handled by
a matching <em>Outputfunc</em>. This is responsible for converting the internal Evennia representation to a
form suitable to send over the wire to the Client. Outputfuncs are hard-coded. Which is chosen and
how it processes the outgoing data depends on the nature of the client it’s connected to. The only
time one would want to add new outputfuncs is as part of developing support for a new Evennia
<a class="reference internal" href="Custom-Protocols.html"><span class="doc">Protocol</span></a>.</p>
<a class="reference internal" href="Custom-Protocols.html"><span class="doc std std-doc">Protocol</span></a>.</p>
</section>
<section id="sending-and-receiving-an-oob-message">
<h2>Sending and receiving an OOB message<a class="headerlink" href="#sending-and-receiving-an-oob-message" title="Permalink to this headline"></a></h2>
<p>Sending is simple. You just use the normal <code class="docutils literal notranslate"><span class="pre">msg</span></code> method of the object whose session you want to send
to. For example in a Command:</p>
<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">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="n">cmdname</span><span class="o">=</span><span class="p">((</span><span class="n">args</span><span class="p">,</span> <span class="o">...</span><span class="p">),</span> <span class="p">{</span><span class="n">key</span><span class="p">:</span><span class="n">value</span><span class="p">,</span> <span class="o">...</span><span class="p">}))</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="n">cmdname</span><span class="o">=</span><span class="p">((</span><span class="n">args</span><span class="p">,</span> <span class="o">...</span><span class="p">),</span> <span class="p">{</span><span class="n">key</span><span class="p">:</span><span class="n">value</span><span class="p">,</span> <span class="o">...</span><span class="p">}))</span>
</pre></div>
</td></tr></table></div>
</div>
<p>A special case is the <code class="docutils literal notranslate"><span class="pre">text</span></code> input/outputfunc. It’s so common that it’s the default of the <code class="docutils literal notranslate"><span class="pre">msg</span></code>
method. So these are equivalent:</p>
<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">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Hello&quot;</span><span class="p">)</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Hello&quot;</span><span class="p">)</span>
<span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="s2">&quot;Hello&quot;</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>You don’t have to specify the full output/input definition. So for example, if your particular
command only needs kwargs, you can skip the <code class="docutils literal notranslate"><span class="pre">(args)</span></code> part. Like in the <code class="docutils literal notranslate"><span class="pre">text</span></code> case you can skip
writing the tuple if there is only one arg … and so on - the input is pretty flexible. If there
@ -93,7 +94,7 @@ drop any other types of outputfuncs.</p>
you turn off telnet completely and only rely on the webclient, you should never rely on non-<code class="docutils literal notranslate"><span class="pre">text</span></code>
OOB messages always reaching all targets.</p>
</div></blockquote>
<p><a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc">Inputfuncs</span></a> lists the default inputfuncs available to handle incoming OOB messages. To
<p><a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc std std-doc">Inputfuncs</span></a> lists the default inputfuncs available to handle incoming OOB messages. To
accept more you need to add more inputfuncs (see that page for more info).</p>
</section>
<section id="supported-oob-protocols">
@ -129,35 +130,30 @@ come <code class="docutils literal notranslate"><span class="pre">foo_bar</span>
underscore, use the <code class="docutils literal notranslate"><span class="pre">Core</span></code> package. So <code class="docutils literal notranslate"><span class="pre">Core.Cmdname</span></code> becomes just <code class="docutils literal notranslate"><span class="pre">cmdname</span></code> in Evennia and vice
versa.</p>
<p>On the wire, a GMCP instruction for <code class="docutils literal notranslate"><span class="pre">(&quot;cmdname&quot;,</span> <span class="pre">(&quot;arg&quot;,),</span> <span class="pre">{})</span></code> will look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">IAC</span> <span class="n">SB</span> <span class="n">GMCP</span> <span class="s2">&quot;cmdname&quot;</span> <span class="s2">&quot;arg&quot;</span> <span class="n">IAC</span> <span class="n">SE</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>IAC SB GMCP &quot;cmdname&quot; &quot;arg&quot; IAC SE
</pre></div>
</div>
<p>where all the capitalized words are telnet character constants specified in
<code class="docutils literal notranslate"><span class="pre">evennia/server/portal/telnet_oob.py</span></code>. These are parsed/added by the protocol and we don’t include
these in the listings below.</p>
</section>
</section>
</section>
<section id="input-outputfunc-gmcp-command">
<h2>Input/Outputfunc | GMCP-Command<a class="headerlink" href="#input-outputfunc-gmcp-command" title="Permalink to this headline"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">[cmd_name,</span> <span class="pre">[],</span> <span class="pre">{}]</span></code> | Cmd.Name
<code class="docutils literal notranslate"><span class="pre">[cmd_name,</span> <span class="pre">[arg],</span> <span class="pre">{}]</span></code> | Cmd.Name arg
<code class="docutils literal notranslate"><span class="pre">[cmd_na_me,</span> <span class="pre">[args],{}]</span></code> | Cmd.Na.Me [args]
<code class="docutils literal notranslate"><span class="pre">[cmd_name,</span> <span class="pre">[],</span> <span class="pre">{kwargs}]</span></code> | Cmd.Name {kwargs}
<p>Input/Outputfunc | GMCP-Command
<code class="docutils literal notranslate"><span class="pre">[cmd_name,</span> <span class="pre">[],</span> <span class="pre">{}]</span></code> | <a class="reference external" href="http://Cmd.Name">Cmd.Name</a>
<code class="docutils literal notranslate"><span class="pre">[cmd_name,</span> <span class="pre">[arg],</span> <span class="pre">{}]</span></code> | <a class="reference external" href="http://Cmd.Name">Cmd.Name</a> arg
<code class="docutils literal notranslate"><span class="pre">[cmd_na_me,</span> <span class="pre">[args],{}]</span></code> | <a class="reference external" href="http://Cmd.Na.Me">Cmd.Na.Me</a> [args]
<code class="docutils literal notranslate"><span class="pre">[cmd_name,</span> <span class="pre">[],</span> <span class="pre">{kwargs}]</span></code> | <a class="reference external" href="http://Cmd.Name">Cmd.Name</a> {kwargs}
<code class="docutils literal notranslate"><span class="pre">[cmdname,</span> <span class="pre">[args,</span> <span class="pre">{kwargs}]</span></code> | Core.Cmdname [[args],{kwargs}]</p>
<p>Since Evennia already supplies default inputfuncs that don’t match the names expected by the most
common GMCP implementations we have a few hard-coded mappings for those:</p>
</section>
<section id="gmcp-command-name-input-outputfunc-name">
<h2>GMCP command name | Input/Outputfunc name<a class="headerlink" href="#gmcp-command-name-input-outputfunc-name" title="Permalink to this headline"></a></h2>
<p>“Core.Hello” | “client_options”
<p>GMCP command name | Input/Outputfunc name
“Core.Hello” | “client_options”
“Core.Supports.Get” | “client_options”
“Core.Commands.Get” | “get_inputfuncs”
“Char.Value.Get” | “get_value”
“Char.Repeat.Update” | “repeat”
“Char.Monitor.Update” | “monitor”</p>
</section>
<section id="telnet-msdp">
<h3>Telnet + MSDP<a class="headerlink" href="#telnet-msdp" title="Permalink to this headline"></a></h3>
<h4>Telnet + MSDP<a class="headerlink" href="#telnet-msdp" title="Permalink to this headline"></a></h4>
<p><a class="reference external" href="http://tintin.sourceforge.net/msdp/">MSDP</a>, the <em>Mud Server Data Protocol</em>, is a competing standard
to GMCP. The MSDP protocol page specifies a range of “recommended” available MSDP command names.
Evennia does <em>not</em> support those - since MSDP doesn’t specify a special format for its command names
@ -167,16 +163,13 @@ name.</p>
strings, arrays (lists) and tables (dicts). These are used to define the cmdname, args and kwargs
needed. When sending MSDP for <code class="docutils literal notranslate"><span class="pre">(&quot;cmdname&quot;,</span> <span class="pre">(&quot;arg&quot;,),</span> <span class="pre">{})</span></code> the resulting MSDP instruction will look
like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">IAC</span> <span class="n">SB</span> <span class="n">MSDP</span> <span class="n">VAR</span> <span class="n">cmdname</span> <span class="n">VAL</span> <span class="n">arg</span> <span class="n">IAC</span> <span class="n">SE</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>IAC SB MSDP VAR cmdname VAL arg IAC SE
</pre></div>
</div>
<p>The various available MSDP constants like <code class="docutils literal notranslate"><span class="pre">VAR</span></code> (variable), <code class="docutils literal notranslate"><span class="pre">VAL</span></code> (value), <code class="docutils literal notranslate"><span class="pre">ARRAYOPEN</span></code>/<code class="docutils literal notranslate"><span class="pre">ARRAYCLOSE</span></code>
and <code class="docutils literal notranslate"><span class="pre">TABLEOPEN</span></code>/<code class="docutils literal notranslate"><span class="pre">TABLECLOSE</span></code> are specified in <code class="docutils literal notranslate"><span class="pre">evennia/server/portal/telnet_oob</span></code>.</p>
</section>
</section>
<section id="outputfunc-inputfunc-msdp-instruction">
<h2>Outputfunc/Inputfunc | MSDP instruction<a class="headerlink" href="#outputfunc-inputfunc-msdp-instruction" title="Permalink to this headline"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">[cmdname,</span> <span class="pre">[],</span> <span class="pre">{}]</span></code> | VAR cmdname VAL
<p>Outputfunc/Inputfunc | MSDP instruction
<code class="docutils literal notranslate"><span class="pre">[cmdname,</span> <span class="pre">[],</span> <span class="pre">{}]</span></code> | VAR cmdname VAL
<code class="docutils literal notranslate"><span class="pre">[cmdname,</span> <span class="pre">[arg],</span> <span class="pre">{}]</span></code> | VAR cmdname VAL arg
<code class="docutils literal notranslate"><span class="pre">[cmdname,</span> <span class="pre">[args],{}]</span></code> | VAR cmdname VAL ARRAYOPEN VAL arg VAL arg … ARRAYCLOSE
<code class="docutils literal notranslate"><span class="pre">[cmdname,</span> <span class="pre">[],</span> <span class="pre">{kwargs}]</span></code> | VAR cmdname VAL TABLEOPEN VAR key VAL val … TABLECLOSE
@ -185,6 +178,8 @@ VAL TABLEOPEN VAR key VAL val … TABLECLOSE</p>
<p>Observe that <code class="docutils literal notranslate"><span class="pre">VAR</span> <span class="pre">...</span> <span class="pre">VAL</span></code> always identifies cmdnames, so if there are multiple arrays/dicts tagged
with the same cmdname they will be appended to the args, kwargs of that inputfunc. Vice-versa, a
different <code class="docutils literal notranslate"><span class="pre">VAR</span> <span class="pre">...</span> <span class="pre">VAL</span></code> (outside a table) will come out as a second, different command input.</p>
</section>
</section>
<section id="ssh">
<h3>SSH<a class="headerlink" href="#ssh" title="Permalink to this headline"></a></h3>
<p>SSH only supports the <code class="docutils literal notranslate"><span class="pre">text</span></code> input/outputcommand.</p>
@ -194,7 +189,7 @@ different <code class="docutils literal notranslate"><span class="pre">VAR</span
<p>Our web client uses pure JSON structures for all its communication, including <code class="docutils literal notranslate"><span class="pre">text</span></code>. This maps
directly to the Evennia internal output/inputcommand, including eventual empty args/kwargs. So the
same example <code class="docutils literal notranslate"><span class="pre">(&quot;cmdname&quot;,</span> <span class="pre">(&quot;arg&quot;,),</span> <span class="pre">{})</span></code> will be sent/received as a valid JSON structure</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="s2">&quot;cmdname, [&quot;</span><span class="n">arg</span><span class="s2">&quot;], </span><span class="si">{}</span><span class="s2">]</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[&quot;cmdname, [&quot;arg&quot;], {}]
</pre></div>
</div>
<p>Since JSON is native to Javascript, this becomes very easy for the webclient to handle.</p>
@ -230,16 +225,9 @@ same example <code class="docutils literal notranslate"><span class="pre">(&quot
<li><a class="reference internal" href="#supported-oob-protocols">Supported OOB protocols</a><ul>
<li><a class="reference internal" href="#telnet">Telnet</a><ul>
<li><a class="reference internal" href="#telnet-gmcp">Telnet + GMCP</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#input-outputfunc-gmcp-command">Input/Outputfunc | GMCP-Command</a></li>
<li><a class="reference internal" href="#gmcp-command-name-input-outputfunc-name">GMCP command name | Input/Outputfunc name</a><ul>
<li><a class="reference internal" href="#telnet-msdp">Telnet + MSDP</a></li>
</ul>
</li>
<li><a class="reference internal" href="#outputfunc-inputfunc-msdp-instruction">Outputfunc/Inputfunc | MSDP instruction</a><ul>
<li><a class="reference internal" href="#ssh">SSH</a></li>
<li><a class="reference internal" href="#web-client">Web client</a></li>
</ul>
@ -268,7 +256,7 @@ same example <code class="docutils literal notranslate"><span class="pre">(&quot
<h3>Versions</h3>
<ul>
<li><a href="OOB.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

25
docs/1.0-dev/Concepts/Soft-Code.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="soft-code">
<section class="tex2jax_ignore mathjax_ignore" id="soft-code">
<h1>Soft Code<a class="headerlink" href="#soft-code" title="Permalink to this headline"></a></h1>
<p>Softcode is a very simple programming language that was created for in-game development on TinyMUD
derivatives such as MUX, PennMUSH, TinyMUSH, and RhostMUSH. The idea is that by providing a stripped
@ -52,28 +54,27 @@ or more which is obviously not very readable nor (easily) maintainable over time
<section id="examples-of-softcode">
<h2>Examples of Softcode<a class="headerlink" href="#examples-of-softcode" title="Permalink to this headline"></a></h2>
<p>Here is a simple ‘Hello World!’ command:</p>
<div class="highlight-bash 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> @set <span class="nv">me</span><span class="o">=</span>HELLO_WORLD.C:<span class="nv">$hello</span>:@pemit %#<span class="o">=</span>Hello World!
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> @set <span class="nv">me</span><span class="o">=</span>HELLO_WORLD.C:<span class="nv">$hello</span>:@pemit %#<span class="o">=</span>Hello World!
</pre></div>
</td></tr></table></div>
</div>
<p>Pasting this into a MUX/MUSH and typing ‘hello’ will theoretically yield ‘Hello World!’, assuming
certain flags are not set on your account object.</p>
<p>Setting attributes is done via <code class="docutils literal notranslate"><span class="pre">&#64;set</span></code>. Softcode also allows the use of the ampersand (<code class="docutils literal notranslate"><span class="pre">&amp;</span></code>) symbol.
This shorter version looks like this:</p>
<div class="highlight-bash 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="p">&amp;</span>HELLO_WORLD.C <span class="nv">me</span><span class="o">=</span><span class="nv">$hello</span>:@pemit %#<span class="o">=</span>Hello World!
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="p">&amp;</span>HELLO_WORLD.C <span class="nv">me</span><span class="o">=</span><span class="nv">$hello</span>:@pemit %#<span class="o">=</span>Hello World!
</pre></div>
</td></tr></table></div>
</div>
<p>Perhaps I want to break the Hello World into an attribute which is retrieved when emitting:</p>
<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></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="p">&amp;</span>HELLO_VALUE.D <span class="nv">me</span><span class="o">=</span>Hello World
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="p">&amp;</span>HELLO_VALUE.D <span class="nv">me</span><span class="o">=</span>Hello World
<span class="p">&amp;</span>HELLO_WORLD.C <span class="nv">me</span><span class="o">=</span><span class="nv">$hello</span>:@pemit %#<span class="o">=[</span>v<span class="o">(</span>HELLO_VALUE.D<span class="o">)]</span>
</pre></div>
</td></tr></table></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">v()</span></code> function returns the <code class="docutils literal notranslate"><span class="pre">HELLO_VALUE.D</span></code> attribute on the object that the command resides
(<code class="docutils literal notranslate"><span class="pre">me</span></code>, which is yourself in this case). This should yield the same output as the first example.</p>
<p>If you are still curious about how Softcode works, take a look at some external resources:</p>
<ul class="simple">
<li><p>https://wiki.tinymux.org/index.php/Softcode</p></li>
<li><p>https://www.duh.com/discordia/mushman/man2x1</p></li>
<li><p><a class="reference external" href="https://wiki.tinymux.org/index.php/Softcode">https://wiki.tinymux.org/index.php/Softcode</a></p></li>
<li><p><a class="reference external" href="https://www.duh.com/discordia/mushman/man2x1">https://www.duh.com/discordia/mushman/man2x1</a></p></li>
</ul>
</section>
<section id="problems-with-softcode">
@ -118,7 +119,7 @@ professional source-control system (svn, git, bazaar, mercurial etc) anyway.</p>
satisfy most creative builders. However, if you really, <em>really</em> want to offer online coding, there
is of course nothing stopping you from adding that to Evennia, no matter our recommendations. You
could even re-implement MUX’ softcode in Python should you be very ambitious. The
<a class="reference internal" href="../Contribs/Dialogues-in-events.html"><span class="doc">in-game-python</span></a> is an optional
<a class="reference internal" href="../Contribs/Dialogues-in-events.html"><span class="doc std std-doc">in-game-python</span></a> is an optional
pseudo-softcode plugin aimed at developers wanting to script their game from inside it.</p>
</section>
</section>
@ -175,7 +176,7 @@ pseudo-softcode plugin aimed at developers wanting to script their game from ins
<h3>Versions</h3>
<ul>
<li><a href="Soft-Code.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

6
docs/1.0-dev/Concepts/Text-Encodings.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="text-encodings">
<section class="tex2jax_ignore mathjax_ignore" id="text-encodings">
<h1>Text Encodings<a class="headerlink" href="#text-encodings" title="Permalink to this headline"></a></h1>
<p>Evennia is a text-based game server. This makes it important to understand how
it actually deals with data in the form of text.</p>
@ -147,7 +149,7 @@ the Wikipedia article <a class="reference external" href="https://en.wikipedia.o
<h3>Versions</h3>
<ul>
<li><a href="Text-Encodings.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

42
docs/1.0-dev/Concepts/TextTags.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,49 +40,19 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="in-text-tags-parsed-by-evennia">
<section class="tex2jax_ignore mathjax_ignore" id="in-text-tags-parsed-by-evennia">
<h1>In-text tags parsed by Evennia<a class="headerlink" href="#in-text-tags-parsed-by-evennia" title="Permalink to this headline"></a></h1>
<p>Evennia understands various extra information embedded in text:</p>
<ul class="simple">
<li><p><a class="reference internal" href="Colors.html"><span class="doc">Colors</span></a> - Using <code class="docutils literal notranslate"><span class="pre">|r</span></code>, <code class="docutils literal notranslate"><span class="pre">|n</span></code> etc can be used to mark parts of text with a color. The color will
<li><p><a class="reference internal" href="Colors.html"><span class="doc std std-doc">Colors</span></a> - Using <code class="docutils literal notranslate"><span class="pre">|r</span></code>, <code class="docutils literal notranslate"><span class="pre">|n</span></code> etc can be used to mark parts of text with a color. The color will
become ANSI/XTerm256 color tags for Telnet connections and CSS information for the webclient.</p></li>
<li><p><a class="reference internal" href="Clickable-Links.html"><span class="doc">Clickable links</span></a> - This allows you to provide a text the user can click to execute an
<li><p><a class="reference internal" href="Clickable-Links.html"><span class="doc std std-doc">Clickable links</span></a> - This allows you to provide a text the user can click to execute an
in-game command. This is on the form <code class="docutils literal notranslate"><span class="pre">|lc</span> <span class="pre">command</span> <span class="pre">|lt</span> <span class="pre">text</span> <span class="pre">|le</span></code>.</p></li>
<li><p><a class="reference internal" href="../Components/FuncParser.html"><span class="doc">FuncParser callables</span></a> - These are full-fledged function calls on the form <code class="docutils literal notranslate"><span class="pre">$funcname(args,</span> <span class="pre">kwargs)</span></code>
<li><p><a class="reference internal" href="../Components/FuncParser.html"><span class="doc std std-doc">FuncParser callables</span></a> - These are full-fledged function calls on the form <code class="docutils literal notranslate"><span class="pre">$funcname(args,</span> <span class="pre">kwargs)</span></code>
that lead to calls to Python functions. The parser can be run with different available callables in different
circumstances. The parser is run on all outgoing messages if <code class="docutils literal notranslate"><span class="pre">settings.FUNCPARSER_PARSE_OUTGOING_MESSAGES_ENABLED=True</span></code>
(disabled by default).</p></li>
</ul>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Colors.html">Colors</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Colors.html#ansi-colours">ANSI colours</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Colors.html#caveats-of">Caveats of <code class="docutils literal notranslate"><span class="pre">|*</span></code></a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Colors.html#xterm256-colours">Xterm256 Colours</a></li>
<li class="toctree-l2"><a class="reference internal" href="Colors.html#more-reading">More reading</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Clickable-Links.html">Clickable links</a></li>
<li class="toctree-l1"><a class="reference internal" href="../Components/FuncParser.html">The Inline Function Parser</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../Components/FuncParser.html#uses-in-default-evennia">Uses in default Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="../Components/FuncParser.html#using-the-funcparser">Using the FuncParser</a></li>
<li class="toctree-l2"><a class="reference internal" href="../Components/FuncParser.html#defining-custom-callables">Defining custom callables</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../Components/FuncParser.html#safe-convertion-of-inputs">Safe convertion of inputs</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../Components/FuncParser.html#default-callables">Default callables</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../Components/FuncParser.html#evennia-utils-funcparser-funcparser-callables"><code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser.FUNCPARSER_CALLABLES</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="../Components/FuncParser.html#evennia-utils-funcparser-searching-callables"><code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser.SEARCHING_CALLABLES</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="../Components/FuncParser.html#evennia-utils-funcparser-actor-stance-callables"><code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser.ACTOR_STANCE_CALLABLES</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="../Components/FuncParser.html#example">Example</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</section>
@ -123,7 +95,7 @@ circumstances. The parser is run on all outgoing messages if <code class="docuti
<h3>Versions</h3>
<ul>
<li><a href="TextTags.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

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

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="using-mux-as-a-standard">
<section class="tex2jax_ignore mathjax_ignore" id="using-mux-as-a-standard">
<h1>Using MUX as a Standard<a class="headerlink" href="#using-mux-as-a-standard" title="Permalink to this headline"></a></h1>
<p>Evennia allows for any command syntax. If you like the way DikuMUDs, LPMuds or MOOs handle things,
you could emulate that with Evennia. If you are ambitious you could even design a whole new style,
@ -49,7 +51,7 @@ perfectly fitting your own dreams of the ideal game.</p>
While the reason for this similarity is partly historical, these codebases offer very mature feature
sets for administration and building.</p>
<p>Evennia is <em>not</em> a MUX system though. It works very differently in many ways. For example, Evennia
deliberately lacks an online softcode language (a policy explained on our <a class="reference internal" href="Soft-Code.html"><span class="doc">softcode policy
deliberately lacks an online softcode language (a policy explained on our <a class="reference internal" href="Soft-Code.html"><span class="doc std std-doc">softcode policy
page</span></a>). Evennia also does not shy from using its own syntax when deemed appropriate: the
MUX syntax has grown organically over a long time and is, frankly, rather arcane in places. All in
all the default command syntax should at most be referred to as “MUX-like” or “MUX-inspired”.</p>
@ -57,22 +59,7 @@ all the default command syntax should at most be referred to as “MUX-like” o
<h2>Documentation policy<a class="headerlink" href="#documentation-policy" title="Permalink to this headline"></a></h2>
<p>All the commands in the default command sets should have their doc-strings formatted on a similar
form:</p>
<div class="highlight-python notranslate"><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></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Short header</span>
<span class="sd"> </span>
<span class="sd"> Usage:</span>
@ -89,37 +76,18 @@ form:</p>
<span class="sd"> </span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</td></tr></table></div>
</div>
<ul class="simple">
<li><p>Two spaces are used for <em>indentation</em> in all default commands.</p></li>
<li><p>Square brackets <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">]</span></code> surround <em>optional, skippable arguments</em>.</p></li>
<li><p>Angled brackets <code class="docutils literal notranslate"><span class="pre">&lt;</span> <span class="pre">&gt;</span></code> surround a <em>description</em> of what to write rather than the exact syntax.</p></li>
<li><p>*Explicit choices are separated by <code class="docutils literal notranslate"><span class="pre">|</span></code>. To avoid this being parsed as a color code, use <code class="docutils literal notranslate"><span class="pre">||</span></code> (this
will come out as a single <code class="docutils literal notranslate"><span class="pre">|</span></code>) or put spaces around the character (”<code class="docutils literal notranslate"><span class="pre">|</span></code>”) if there’s plenty of
will come out as a single <code class="docutils literal notranslate"><span class="pre">|</span></code>) or put spaces around the character (“<code class="docutils literal notranslate"><span class="pre">|</span></code>”) if there’s plenty of
room.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">Switches</span></code> and <code class="docutils literal notranslate"><span class="pre">Examples</span></code> blocks are optional based on the Command.</p></li>
</ul>
<p>Here is the <code class="docutils literal notranslate"><span class="pre">nick</span></code> command as an example:</p>
<div class="highlight-python notranslate"><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="sd">&quot;&quot;&quot;</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Define a personal alias/nick</span>
<span class="sd"> </span>
<span class="sd"> Usage:</span>
@ -140,17 +108,15 @@ room.</p></li>
<span class="sd"> </span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</td></tr></table></div>
</div>
<p>For commands that <em>require arguments</em>, the policy is for it to return a <code class="docutils literal notranslate"><span class="pre">Usage:</span></code> string if the
command is entered without any arguments. So for such commands, the Command body should contain
something to the effect of</p>
<div class="highlight-python notranslate"><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> <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">:</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Usage: nick[/switches] &lt;nickname&gt; = [&lt;string&gt;]&quot;</span><span class="p">)</span>
<span class="k">return</span>
</pre></div>
</td></tr></table></div>
</div>
</section>
</section>
@ -202,7 +168,7 @@ something to the effect of</p>
<h3>Versions</h3>
<ul>
<li><a href="Using-MUX-as-a-Standard.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

34
docs/1.0-dev/Concepts/Web-Features.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="web-features">
<section class="tex2jax_ignore mathjax_ignore" id="web-features">
<h1>Web Features<a class="headerlink" href="#web-features" title="Permalink to this headline"></a></h1>
<p>Evennia is its own webserver and hosts a default website and browser webclient.</p>
<section id="web-site">
@ -75,7 +77,7 @@ change from the <code class="docutils literal notranslate"><span class="pre">web
<p>Example: To override or modify <code class="docutils literal notranslate"><span class="pre">evennia/web/website/template/website/index.html</span></code> you need to
add/modify <code class="docutils literal notranslate"><span class="pre">mygame/web/template_overrides/website/index.html</span></code>.</p>
<p>The detailed description on how to customize the website is best described in tutorial form. See the
<a class="reference internal" href="../Howto/Starting/Part5/Web-Tutorial.html"><span class="doc">Web Tutorial</span></a> for more information.</p>
<a class="reference internal" href="../Howto/Starting/Part5/Web-Tutorial.html"><span class="doc std std-doc">Web Tutorial</span></a> for more information.</p>
</section>
<section id="overloading-django-views">
<h3>Overloading Django views<a class="headerlink" href="#overloading-django-views" title="Permalink to this headline"></a></h3>
@ -90,22 +92,7 @@ field of your web browser to get to the page in question. If you put your own UR
the default ones, your own view will be used instead. The file <code class="docutils literal notranslate"><span class="pre">urls.py</span></code> even marks where you should
put your change.</p>
<p>Here’s an example:</p>
<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></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># mygame/web/urls.py</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># mygame/web/urls.py</span>
<span class="kn">from</span> <span class="nn">django.conf.urls</span> <span class="kn">import</span> <span class="n">url</span><span class="p">,</span> <span class="n">include</span>
<span class="c1"># default patterns</span>
@ -121,8 +108,9 @@ put your change.</p>
<span class="p">]</span>
<span class="n">urlpatterns</span> <span class="o">=</span> <span class="n">patterns</span> <span class="o">+</span> <span class="n">urlpatterns</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Django will always look for a list named <code class="docutils literal notranslate"><span class="pre">urlpatterns</span></code> which consists of the results of <code class="docutils literal notranslate"><span class="pre">url()</span></code>
calls. It will use the <em>first</em> match it finds in this list. Above, we add a new URL redirect from
the root of the website. It will now our own function <code class="docutils literal notranslate"><span class="pre">myview</span></code> from a new module
@ -145,7 +133,7 @@ you will also log all requests in <code class="docutils literal notranslate"><sp
<h2>Web client<a class="headerlink" href="#web-client" title="Permalink to this headline"></a></h2>
<p>Evennia comes with a MUD client accessible from a normal web browser. During
development you can try it at <code class="docutils literal notranslate"><span class="pre">http://localhost:4001/webclient</span></code>.
<a class="reference internal" href="../Components/Webclient.html"><span class="doc">See the Webclient page</span></a> for more details.</p>
<a class="reference internal" href="../Components/Webclient.html"><span class="doc std std-doc">See the Webclient page</span></a> for more details.</p>
</section>
<section id="the-django-admin-page">
<h2>The Django ‘Admin’ Page<a class="headerlink" href="#the-django-admin-page" title="Permalink to this headline"></a></h2>
@ -156,11 +144,11 @@ in your database from a graphical interface.</p>
<p>The behavior of default Evennia models are controlled by files <code class="docutils literal notranslate"><span class="pre">admin.py</span></code> in the Evennia package.
New database models you choose to add yourself (such as in the Web Character View Tutorial) can/will
also have <code class="docutils literal notranslate"><span class="pre">admin.py</span></code> files. New models are registered to the admin website by a call of
<code class="docutils literal notranslate"><span class="pre">admin.site.register(model</span> <span class="pre">class,</span> <span class="pre">admin</span> <span class="pre">class)</span></code> inside an admin.py file. It is an error to attempt
<code class="docutils literal notranslate"><span class="pre">admin.site.register(model</span> <span class="pre">class,</span> <span class="pre">admin</span> <span class="pre">class)</span></code> inside an <a class="reference external" href="http://admin.py">admin.py</a> file. It is an error to attempt
to register a model that has already been registered.</p>
<p>To overload Evennia’s admin files you don’t need to modify Evennia itself. To customize you can call
<code class="docutils literal notranslate"><span class="pre">admin.site.unregister(model</span> <span class="pre">class)</span></code>, then follow that with <code class="docutils literal notranslate"><span class="pre">admin.site.register</span></code> in one of your own
admin.py files in a new app that you add.</p>
<a class="reference external" href="http://admin.py">admin.py</a> files in a new app that you add.</p>
</section>
<section id="more-reading">
<h2>More reading<a class="headerlink" href="#more-reading" title="Permalink to this headline"></a></h2>
@ -228,7 +216,7 @@ implementation, the relevant django “applications” in default Evennia are <c
<h3>Versions</h3>
<ul>
<li><a href="Web-Features.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>

21
docs/1.0-dev/Concepts/Zones.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@ -38,7 +40,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="zones">
<section class="tex2jax_ignore mathjax_ignore" id="zones">
<h1>Zones<a class="headerlink" href="#zones" title="Permalink to this headline"></a></h1>
<p>Say you create a room named <em>Meadow</em> in your nice big forest MUD. That’s all nice and dandy, but
what if you, in the other end of that forest want another <em>Meadow</em>? As a game creator, this can
@ -58,29 +60,28 @@ part should be easy to retrieve.</p>
<p>Many MUD codebases hardcode zones as part of the engine and database. Evennia does no such
distinction due to the fact that rooms themselves are meant to be customized to any level anyway.
Below is a suggestion for how to implement zones in Evennia.</p>
<p>All objects in Evennia can hold any number of <a class="reference internal" href="../Components/Tags.html"><span class="doc">Tags</span></a>. Tags are short labels that you attach to
<p>All objects in Evennia can hold any number of <a class="reference internal" href="../Components/Tags.html"><span class="doc std std-doc">Tags</span></a>. Tags are short labels that you attach to
objects. They make it very easy to retrieve groups of objects. An object can have any number of
different tags. So let’s attach the relevant tag to our forest:</p>
<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">forestobj</span><span class="o">.</span><span class="n">tags</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;magicalforest&quot;</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">&quot;zone&quot;</span><span class="p">)</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">forestobj</span><span class="o">.</span><span class="n">tags</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;magicalforest&quot;</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">&quot;zone&quot;</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>You could add this manually, or automatically during creation somehow (you’d need to modify your
&#64;dig command for this, most likely). You can also use the default <code class="docutils literal notranslate"><span class="pre">&#64;tag</span></code> command during building:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="nd">@tag</span> <span class="n">forestobj</span> <span class="o">=</span> <span class="n">magicalforest</span> <span class="p">:</span> <span class="n">zone</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> @tag forestobj = magicalforest : zone
</pre></div>
</div>
<p>Henceforth you can then easily retrieve only objects with a given tag:</p>
<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>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">evennia</span>
<span class="n">rooms</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_tag</span><span class="p">(</span><span class="s2">&quot;magicalforest&quot;</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">&quot;zone&quot;</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
</section>
<section id="using-typeclasses-and-inheritance-for-zoning">
<h2>Using typeclasses and inheritance for zoning<a class="headerlink" href="#using-typeclasses-and-inheritance-for-zoning" title="Permalink to this headline"></a></h2>
<p>The tagging or aliasing systems above don’t instill any sort of functional difference between a
magical forest room and a normal one - they are just arbitrary ways to mark objects for quick
retrieval later. Any functional differences must be expressed using <a class="reference internal" href="../Components/Typeclasses.html"><span class="doc">Typeclasses</span></a>.</p>
retrieval later. Any functional differences must be expressed using <a class="reference internal" href="../Components/Typeclasses.html"><span class="doc std std-doc">Typeclasses</span></a>.</p>
<p>Of course, an alternative way to implement zones themselves is to have all rooms/objects in a zone
inherit from a given typeclass parent - and then limit your searches to objects inheriting from that
given parent. The effect would be similar but you’d need to expand the search functionality to
@ -137,7 +138,7 @@ properly search the inheritance tree.</p>
<h3>Versions</h3>
<ul>
<li><a href="Zones.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>