Updated HTML docs

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

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="tutorial-vehicles">
<section class="tex2jax_ignore mathjax_ignore" id="tutorial-vehicles">
<h1>Tutorial Vehicles<a class="headerlink" href="#tutorial-vehicles" title="Permalink to this headline"></a></h1>
<p>This tutorial explains how you can create vehicles that can move around in your world. The tutorial
will explain how to create a train, but this can be equally applied to create other kind of vehicles
@ -55,15 +57,7 @@ move the Train, which brings along everyone inside it.</p>
<h2>Creating our train object<a class="headerlink" href="#creating-our-train-object" title="Permalink to this headline"></a></h2>
<p>The first step we need to do is create our train object, including a new typeclass. To do this,
create a new file, for instance in <code class="docutils literal notranslate"><span class="pre">mygame/typeclasses/train.py</span></code> with the following content:</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></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># file mygame/typeclasses/train.py</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># file mygame/typeclasses/train.py</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultObject</span>
@ -72,8 +66,9 @@ create a new file, for instance in <code class="docutils literal notranslate"><s
<span class="k">def</span> <span class="nf">at_object_creation</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># We&#39;ll add in code here later.</span>
<span class="k">pass</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Now we can create our train in our game:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@create</span><span class="o">/</span><span class="n">drop</span> <span class="n">train</span><span class="p">:</span><span class="n">train</span><span class="o">.</span><span class="n">TrainObject</span>
</pre></div>
@ -89,67 +84,18 @@ and back (assuming we created it in limbo).</p>
<h2>Entering and leaving the train<a class="headerlink" href="#entering-and-leaving-the-train" title="Permalink to this headline"></a></h2>
<p>Using the <code class="docutils literal notranslate"><span class="pre">&#64;tel</span></code>command like shown above is obviously not what we want. <code class="docutils literal notranslate"><span class="pre">&#64;tel</span></code> is an admin command
and normal players will thus never be able to enter the train! It is also not really a good idea to
use <a class="reference external" href="Components/Objects.html#exits">Exits</a> to get in and out of the train - Exits are (at least by default) objects
use <a class="reference internal" href="../Components/Objects.html#exits"><span class="std std-doc">Exits</span></a> to get in and out of the train - Exits are (at least by default) objects
too. They point to a specific destination. If we put an Exit in this room leading inside the train
it would stay here when the train moved away (still leading into the train like a magic portal!). In
the same way, if we put an Exit object inside the train, it would always point back to this room,
regardless of where the Train has moved. Now, one <em>could</em> define custom Exit types that move with
the train or change their destination in the right way - but this seems to be a pretty cumbersome
solution.</p>
<p>What we will do instead is to create some new <a class="reference internal" href="../Components/Commands.html"><span class="doc">commands</span></a>: one for entering the train and
<p>What we will do instead is to create some new <a class="reference internal" href="../Components/Commands.html"><span class="doc std std-doc">commands</span></a>: one for entering the train and
another for leaving it again. These will be stored <em>on the train object</em> and will thus be made
available to whomever is either inside it or in the same room as the train.</p>
<p>Lets create a new command module as <code class="docutils literal notranslate"><span class="pre">mygame/commands/train.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>
<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></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># mygame/commands/train.py</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># mygame/commands/train.py</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">Command</span><span class="p">,</span> <span class="n">CmdSet</span>
@ -200,23 +146,15 @@ available to whomever is either inside it or in the same room as the train.</p>
<span class="bp">self</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">CmdEnterTrain</span><span class="p">())</span>
<span class="bp">self</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">CmdLeaveTrain</span><span class="p">())</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Note that while this seems like a lot of text, the majority of lines here are taken up by
documentation.</p>
<p>These commands are work in a pretty straightforward way: <code class="docutils literal notranslate"><span class="pre">CmdEnterTrain</span></code> moves the location of the
player to inside the train and <code class="docutils literal notranslate"><span class="pre">CmdLeaveTrain</span></code> does the opposite: it moves the player back to the
current location of the train (back outside to its current location). We stacked them in a
<a class="reference internal" href="../Components/Command-Sets.html"><span class="doc">cmdset</span></a> <code class="docutils literal notranslate"><span class="pre">CmdSetTrain</span></code> so they can be used.</p>
<a class="reference internal" href="../Components/Command-Sets.html"><span class="doc std std-doc">cmdset</span></a> <code class="docutils literal notranslate"><span class="pre">CmdSetTrain</span></code> so they can be used.</p>
<p>To make the commands work we need to add this cmdset to our train typeclass:</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></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># file mygame/typeclasses/train.py</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># file mygame/typeclasses/train.py</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultObject</span>
<span class="kn">from</span> <span class="nn">commands.train</span> <span class="kn">import</span> <span class="n">CmdSetTrain</span>
@ -225,8 +163,9 @@ current location of the train (back outside to its current location). We stacked
<span class="k">def</span> <span class="nf">at_object_creation</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">cmdset</span><span class="o">.</span><span class="n">add_default</span><span class="p">(</span><span class="n">CmdSetTrain</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>If we now <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code> our game and reset our train, those commands should work and we can now enter
and leave the train:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@reload</span>
@ -245,7 +184,7 @@ As seen above, when this hook is called on our train, our new cmdset will be loa
<p>If you have played around a bit, youve probably figured out that you can use <code class="docutils literal notranslate"><span class="pre">leave</span> <span class="pre">train</span></code> when
outside the train and <code class="docutils literal notranslate"><span class="pre">enter</span> <span class="pre">train</span></code> when inside. This doesnt make any sense … so lets go ahead
and fix that. We need to tell Evennia that you can not enter the train when youre already inside
or leave the train when youre outside. One solution to this is <a class="reference internal" href="../Components/Locks.html"><span class="doc">locks</span></a>: we will lock down
or leave the train when youre outside. One solution to this is <a class="reference internal" href="../Components/Locks.html"><span class="doc std std-doc">locks</span></a>: we will lock down
the commands so that they can only be called if the player is at the correct location.</p>
<p>Right now commands defaults to the lock <code class="docutils literal notranslate"><span class="pre">cmd:all()</span></code>. The <code class="docutils literal notranslate"><span class="pre">cmd</span></code> lock type in combination with the
<code class="docutils literal notranslate"><span class="pre">all()</span></code> lock function means that everyone can run those commands as long as they are in the same
@ -254,16 +193,7 @@ player and <em>only</em> allow access if they are inside the train.</p>
<p>First of all we need to create a new lock function. Evennia comes with many lock functions built-in
already, but none that we can use for locking a command in this particular case. Create a new entry
in <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/lockfuncs.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>
<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>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span>
<span class="c1"># file mygame/server/conf/lockfuncs.py</span>
<span class="k">def</span> <span class="nf">cmdinside</span><span class="p">(</span><span class="n">accessing_obj</span><span class="p">,</span> <span class="n">accessed_obj</span><span class="p">,</span> <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>
@ -273,8 +203,9 @@ in <code class="docutils literal notranslate"><span class="pre">mygame/server/co
<span class="sd"> is defined on an object which accessing_obj is inside of. </span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="k">return</span> <span class="n">accessed_obj</span><span class="o">.</span><span class="n">obj</span> <span class="o">==</span> <span class="n">accessing_obj</span><span class="o">.</span><span class="n">location</span>
</pre></div>
</td></tr></table></div>
</div>
<p>If you didnt know, Evennia is by default set up to use all functions in this module as lock
functions (there is a setting variable that points to it).</p>
<p>Our new lock function, <code class="docutils literal notranslate"><span class="pre">cmdinside</span></code>, is to be used by Commands. The <code class="docutils literal notranslate"><span class="pre">accessed_obj</span></code> is the Command
@ -287,17 +218,7 @@ train.</p>
it is, it means the player is inside the train. Otherwise it means the player is somewhere else and
the check will fail.</p>
<p>The next step is to actually use this new lock function to create a lock of type <code class="docutils literal notranslate"><span class="pre">cmd</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="c1"># file commands/train.py</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># file commands/train.py</span>
<span class="o">...</span>
<span class="k">class</span> <span class="nc">CmdEnterTrain</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
<span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;enter train&quot;</span>
@ -309,7 +230,7 @@ the check will fail.</p>
<span class="n">locks</span> <span class="o">=</span> <span class="s2">&quot;cmd:cmdinside()&quot;</span>
<span class="c1"># ...</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Notice how we use the <code class="docutils literal notranslate"><span class="pre">not</span></code> here so that we can use the same <code class="docutils literal notranslate"><span class="pre">cmdinside</span></code> to check if we are inside
and outside, without having to create two separate lock functions. After a <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code> our commands
should be locked down appropriately and you should only be able to use them at the right places.</p>
@ -348,42 +269,7 @@ and leave it.</p>
</pre></div>
</div>
<p>Next we will tell the train how to move and which route to take.</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></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># file typeclasses/train.py</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># file typeclasses/train.py</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultObject</span><span class="p">,</span> <span class="n">search_object</span>
@ -420,7 +306,7 @@ and leave it.</p>
<span class="bp">self</span><span class="o">.</span><span class="n">move_to</span><span class="p">(</span><span class="n">room</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">msg_contents</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;The train is moving forward to </span><span class="si">{</span><span class="n">room</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">.&quot;</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>We added a lot of code here. Since we changed the <code class="docutils literal notranslate"><span class="pre">at_object_creation</span></code> to add in variables we will
have to reset our train object like earlier (using the <code class="docutils literal notranslate"><span class="pre">&#64;typeclass/force/reset</span></code> command).</p>
<p>We are keeping track of a few different things now: whether the train is moving or standing still,
@ -441,48 +327,11 @@ moves the train to the next room in the list. Or makes it stop driving if it rea
<p>If we wanted full control of the train we could now just add a command to step it along the track
when desired. We want the train to move on its own though, without us having to force it by manually
calling the <code class="docutils literal notranslate"><span class="pre">goto_next_room</span></code> method.</p>
<p>To do this we will create two <a class="reference internal" href="../Components/Scripts.html"><span class="doc">scripts</span></a>: one script that runs when the train has stopped at
<p>To do this we will create two <a class="reference internal" href="../Components/Scripts.html"><span class="doc std std-doc">scripts</span></a>: one script that runs when the train has stopped at
a station and is responsible for starting the train again after a while. The other script will take
care of the driving.</p>
<p>Lets make a new file in <code class="docutils literal notranslate"><span class="pre">mygame/typeclasses/trainscript.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>
<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></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># file mygame/typeclasses/trainscript.py</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># file mygame/typeclasses/trainscript.py</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultScript</span>
@ -521,21 +370,13 @@ care of the driving.</p>
<span class="k">def</span> <span class="nf">at_stop</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">obj</span><span class="o">.</span><span class="n">scripts</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">TrainStoppedScript</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Those scripts work as a state system: when the train is stopped, it waits for 30 seconds and then
starts again. When the train is driving, it moves to the next room every second. The train is always
in one of those two states - both scripts take care of adding the other one once they are done.</p>
<p>As a last step we need to link the stopped-state script to our train, reload the game and reset our
train again., and were ready to ride it around!</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></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># file typeclasses/train.py</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># file typeclasses/train.py</span>
<span class="kn">from</span> <span class="nn">typeclasses.trainscript</span> <span class="kn">import</span> <span class="n">TrainStoppedScript</span>
@ -545,7 +386,7 @@ train again., and were ready to ride it around!</p>
<span class="c1"># ...</span>
<span class="bp">self</span><span class="o">.</span><span class="n">scripts</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">TrainStoppedScript</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@reload</span>
<span class="nd">@typeclass</span><span class="o">/</span><span class="n">force</span><span class="o">/</span><span class="n">reset</span> <span class="n">train</span> <span class="o">=</span> <span class="n">train</span><span class="o">.</span><span class="n">TrainObject</span>
<span class="n">enter</span> <span class="n">train</span>
@ -573,7 +414,7 @@ enter/exit commands check so the train is not moving before allowing the caller
<li><p>Have train conductor commands that can override the automatic start/stop.</p></li>
<li><p>Allow for in-between stops between the start- and end station</p></li>
<li><p>Have a rail road track instead of hard-coding the rooms in the train object. This could for
example be a custom <a class="reference external" href="Components/Objects.html#exits">Exit</a> only traversable by trains. The train will follow the
example be a custom <a class="reference internal" href="../Components/Objects.html#exits"><span class="std std-doc">Exit</span></a> only traversable by trains. The train will follow the
track. Some track segments can split to lead to two different rooms and a player can switch the
direction to which room it goes.</p></li>
<li><p>Create another kind of vehicle!</p></li>
@ -635,7 +476,7 @@ direction to which room it goes.</p></li>
<h3>Versions</h3>
<ul>
<li><a href="Tutorial-Vehicles.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>