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

Updated HTML docs

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

165
docs/1.0-dev/Components/Batch-Code-Processor.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Batch Code Processor &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,12 +38,12 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="batch-code-processor">
<section id="batch-code-processor">
<h1>Batch Code Processor<a class="headerlink" href="#batch-code-processor" title="Permalink to this headline"></a></h1>
<p>For an introduction and motivation to using batch processors, see <a class="reference internal" href="Batch-Processors.html"><span class="doc">here</span></a>. This
page describes the Batch-<em>code</em> processor. The Batch-<em>command</em> one is covered [here](Batch-Command-
Processor).</p>
<div class="section" id="basic-usage">
<section id="basic-usage">
<h2>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline"></a></h2>
<p>The batch-code processor is a superuser-only function, invoked by</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">&gt;</span> <span class="nd">@batchcode</span> <span class="n">path</span><span class="o">.</span><span class="n">to</span><span class="o">.</span><span class="n">batchcodefile</span>
@ -59,8 +60,8 @@ to run the example batch file in <code class="docutils literal notranslate"><spa
<p>This will try to run through the entire batch file in one go. For more gradual, <em>interactive</em>
control you can use the <code class="docutils literal notranslate"><span class="pre">/interactive</span></code> switch. The switch <code class="docutils literal notranslate"><span class="pre">/debug</span></code> will put the processor in
<em>debug</em> mode. Read below for more info.</p>
</div>
<div class="section" id="the-batch-file">
</section>
<section id="the-batch-file">
<h2>The batch file<a class="headerlink" href="#the-batch-file" title="Permalink to this headline"></a></h2>
<p>A batch-code file is a normal Python file. The difference is that since the batch processor loads
and executes the file rather than importing it, you can reliably update the file, then call it
@ -94,44 +95,44 @@ variable in one code block won’t affect that variable in any other code block!
a separate python module.</p></li>
</ul>
<p>Below is a version of the example file found in <code class="docutils literal notranslate"><span class="pre">evennia/contrib/tutorial_examples/</span></code>.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="c1">#</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span>
<span class="normal">20</span>
<span class="normal">21</span>
<span class="normal">22</span>
<span class="normal">23</span>
<span class="normal">24</span>
<span class="normal">25</span>
<span class="normal">26</span>
<span class="normal">27</span>
<span class="normal">28</span>
<span class="normal">29</span>
<span class="normal">30</span>
<span class="normal">31</span>
<span class="normal">32</span>
<span class="normal">33</span>
<span class="normal">34</span>
<span class="normal">35</span>
<span class="normal">36</span>
<span class="normal">37</span>
<span class="normal">38</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="c1">#</span>
<span class="c1"># This is an example batch-code build file for Evennia. </span>
<span class="c1">#</span>
@ -172,8 +173,8 @@ a separate python module.</p></li>
</pre></div>
</td></tr></table></div>
<p>This uses Evennia’s Python API to create three objects in sequence.</p>
</div>
<div class="section" id="debug-mode">
</section>
<section id="debug-mode">
<h2>Debug mode<a class="headerlink" href="#debug-mode" title="Permalink to this headline"></a></h2>
<p>Try to run the example script with</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">&gt;</span> <span class="nd">@batchcode</span><span class="o">/</span><span class="n">debug</span> <span class="n">tutorial_examples</span><span class="o">.</span><span class="n">example_batch_code</span>
@ -188,8 +189,8 @@ handled this state by deleting the chair and table again.</p>
bugs in your code or try to see if things behave as they should. Running the script over and over
would then create an ever-growing stack of chairs and tables, all with the same name. You would have
to go back and painstakingly delete them later.</p>
</div>
<div class="section" id="interactive-mode">
</section>
<section id="interactive-mode">
<h2>Interactive mode<a class="headerlink" href="#interactive-mode" title="Permalink to this headline"></a></h2>
<p>Interactive mode works very similar to the [batch-command processor counterpart](Batch-Command-
Processor). It allows you more step-wise control over how the batch file is executed. This is useful
@ -206,17 +207,17 @@ for debugging or for picking and choosing only particular blocks to run. Use <c
file. Observe that the block has <em>not</em> actually been executed at this point!</p>
<p>To take a look at the full code snippet you are about to run, use <code class="docutils literal notranslate"><span class="pre">ll</span></code> (a batch-processor version of
<code class="docutils literal notranslate"><span class="pre">look</span></code>).</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11</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">create</span><span class="p">,</span> <span class="n">search</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">create</span><span class="p">,</span> <span class="n">search</span>
<span class="kn">from</span> <span class="nn">evennia.contrib.tutorial_examples</span> <span class="kn">import</span> <span class="n">red_button</span>
<span class="kn">from</span> <span class="nn">typeclasses.objects</span> <span class="kn">import</span> <span class="n">Object</span>
@ -239,12 +240,12 @@ batch file this can be very useful (don’t forget the <code class="docutils lit
<p>Use <code class="docutils literal notranslate"><span class="pre">nn</span></code> and <code class="docutils literal notranslate"><span class="pre">bb</span></code> (next and back) to step through the file; e.g. <code class="docutils literal notranslate"><span class="pre">nn</span> <span class="pre">12</span></code> will jump 12 steps forward
(without processing any blocks in between). All normal commands of Evennia should work too while
working in interactive mode.</p>
</div>
<div class="section" id="limitations-and-caveats">
</section>
<section id="limitations-and-caveats">
<h2>Limitations and Caveats<a class="headerlink" href="#limitations-and-caveats" title="Permalink to this headline"></a></h2>
<p>The batch-code processor is by far the most flexible way to build a world in Evennia. There are
however some caveats you need to keep in mind.</p>
<div class="section" id="safety">
<section id="safety">
<h3>Safety<a class="headerlink" href="#safety" title="Permalink to this headline"></a></h3>
<p>Or rather the lack of it. There is a reason only <em>superusers</em> are allowed to run the batch-code
processor by default. The code-processor runs <strong>without any Evennia security checks</strong> and allows
@ -254,8 +255,8 @@ allow other users to access the batch-code processor you should make sure to run
separate and very limited-access user on your machine (i.e. in a ‘jail’). By comparison, the batch-
command processor is much safer since the user running it is still ‘inside’ the game and can’t
really do anything outside what the game commands allow them to.</p>
</div>
<div class="section" id="no-communication-between-code-blocks">
</section>
<section id="no-communication-between-code-blocks">
<h3>No communication between code blocks<a class="headerlink" href="#no-communication-between-code-blocks" title="Permalink to this headline"></a></h3>
<p>Global variables won’t work in code batch files, each block is executed as stand-alone environments.
<code class="docutils literal notranslate"><span class="pre">#HEADER</span></code> blocks are literally pasted on top of each <code class="docutils literal notranslate"><span class="pre">#CODE</span></code> block so updating some header-variable
@ -275,18 +276,18 @@ aliases is unique to the room (like “room56”) and you will henceforth be abl
search and find it later.</p></li>
<li><p>Use the <code class="docutils literal notranslate"><span class="pre">caller</span></code> global property as an inter-block storage. For example, you could have a
dictionary of room references in an <code class="docutils literal notranslate"><span class="pre">ndb</span></code>:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1">#HEADER </span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1">#HEADER </span>
<span class="k">if</span> <span class="n">caller</span><span class="o">.</span><span class="n">ndb</span><span class="o">.</span><span class="n">all_rooms</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<span class="n">caller</span><span class="o">.</span><span class="n">ndb</span><span class="o">.</span><span class="n">all_rooms</span> <span class="o">=</span> <span class="p">{}</span>
@ -305,23 +306,23 @@ dictionary of room references in an <code class="docutils literal notranslate"><
<p>Note how we check in <code class="docutils literal notranslate"><span class="pre">#HEADER</span></code> if <code class="docutils literal notranslate"><span class="pre">caller.ndb.all_rooms</span></code> doesn’t already exist before creating the
dict. Remember that <code class="docutils literal notranslate"><span class="pre">#HEADER</span></code> is copied in front of every <code class="docutils literal notranslate"><span class="pre">#CODE</span></code> block. Without that <code class="docutils literal notranslate"><span class="pre">if</span></code> statement
we’d be wiping the dict every block!</p>
</div>
<div class="section" id="don-t-treat-a-batchcode-file-like-any-python-file">
</section>
<section id="don-t-treat-a-batchcode-file-like-any-python-file">
<h3>Don’t treat a batchcode file like any Python file<a class="headerlink" href="#don-t-treat-a-batchcode-file-like-any-python-file" title="Permalink to this headline"></a></h3>
<p>Despite being a valid Python file, a batchcode file should <em>only</em> be run by the batchcode processor.
You should not do things like define Typeclasses or Commands in them, or import them into other
code. Importing a module in Python will execute base level of the module, which in the case of your
average batchcode file could mean creating a lot of new objects every time.</p>
</div>
<div class="section" id="don-t-let-code-rely-on-the-batch-file-s-real-file-path">
</section>
<section id="don-t-let-code-rely-on-the-batch-file-s-real-file-path">
<h3>Don’t let code rely on the batch-file’s real file path<a class="headerlink" href="#don-t-let-code-rely-on-the-batch-file-s-real-file-path" title="Permalink to this headline"></a></h3>
<p>When you import things into your batchcode file, don’t use relative imports but always import with
paths starting from the root of your game directory or evennia library. Code that relies on the
batch file’s “actual” location <em>will fail</em>. Batch code files are read as text and the strings
executed. When the code runs it has no knowledge of what file those strings where once a part of.</p>
</div>
</div>
</div>
</section>
</section>
</section>
<div class="clearer"></div>