Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-17 13:26:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/3.x/Components/Batch-Command-Processor.html
Griatch a2f5d016d4 Fix 3.x legacy doc versioning
2023-12-21 00:12:31 +01:00

277 lines
No EOL
22 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Batch Command Processor &#8212; Evennia 3.x documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Batch Code Processor" href="Batch-Code-Processor.html" />
<link rel="prev" title="Batch Processors" href="Batch-Processors.html" />
</head><body>
<div class="admonition important">
<p class="first admonition-title">Note</p>
<p class="last">You are reading an old version of the Evennia documentation. <a href="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Batch-Code-Processor.html" title="Batch Code Processor"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Batch-Processors.html" title="Batch Processors"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 3.x</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Components-Overview.html" >Core Components</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Batch-Processors.html" accesskey="U">Batch Processors</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Batch Command Processor</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Batch Command Processor</a><ul>
<li><a class="reference internal" href="#the-batch-file">The batch file</a></li>
<li><a class="reference internal" href="#interactive-mode">Interactive mode</a></li>
<li><a class="reference internal" href="#limitations-and-caveats">Limitations and Caveats</a></li>
<li><a class="reference internal" href="#editor-highlighting-for-ev-files">Editor highlighting for .ev files</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Batch-Processors.html"
title="previous chapter">Batch Processors</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Batch-Code-Processor.html"
title="next chapter">Batch Code Processor</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Components/Batch-Command-Processor.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com/docs/latest/index.html">Documentation Top</a> </li>
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
<li><a href="https://github.com/evennia/evennia">Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="batch-command-processor">
<h1>Batch Command Processor<a class="headerlink" href="#batch-command-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 std std-doc">here</span></a>. This
page describes the Batch-<em>command</em> processor. The Batch-<em>code</em> one is covered [here](Batch-Code-
Processor).</p>
<p>The batch-command processor is a superuser-only function, invoked by</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> &gt; batchcommand path.to.batchcmdfile
</pre></div>
</div>
<p>Where <code class="docutils literal notranslate"><span class="pre">path.to.batchcmdfile</span></code> is the path to a <em>batch-command file</em> with the “<code class="docutils literal notranslate"><span class="pre">.ev</span></code>” file ending.
This path is given like a python path relative to a folder you define to hold your batch files, set
with <code class="docutils literal notranslate"><span class="pre">BATCH_IMPORT_PATH</span></code> in your settings. Default folder is (assuming your game is in the <code class="docutils literal notranslate"><span class="pre">mygame</span></code>
folder) <code class="docutils literal notranslate"><span class="pre">mygame/world</span></code>. So if you want to run the example batch file in
<code class="docutils literal notranslate"><span class="pre">mygame/world/batch_cmds.ev</span></code>, you could use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> &gt; batchcommand batch_cmds
</pre></div>
</div>
<p>A batch-command file contains a list of Evennia in-game commands separated by comments. The
processor will run the batch file from beginning to end. Note that <em>it will not stop if commands in
it fail</em> (there is no universal way for the processor to know what a failure looks like for all
different commands). So keep a close watch on the output, or use <em>Interactive mode</em> (see below) to
run the file in a more controlled, gradual manner.</p>
<section id="the-batch-file">
<h2>The batch file<a class="headerlink" href="#the-batch-file" title="Permalink to this headline"></a></h2>
<p>The batch file is a simple plain-text file containing Evennia commands. Just like you would write
them in-game, except you have more freedom with line breaks.</p>
<p>Here are the rules of syntax of an <code class="docutils literal notranslate"><span class="pre">*.ev</span></code> file. You’ll find it’s really, really simple:</p>
<ul class="simple">
<li><p>All lines having the <code class="docutils literal notranslate"><span class="pre">#</span></code> (hash)-symbol <em>as the first one on the line</em> are considered <em>comments</em>. All non-comment lines are treated as a command and/or their arguments.</p></li>
<li><p>Comment lines have an actual function – they mark the <em>end of the previous command definition</em>. So never put two commands directly after one another in the file - separate them with a comment, or the second of the two will be considered an argument to the first one. Besides, using plenty of comments is good practice anyway.</p></li>
<li><p>A line that starts with the word <code class="docutils literal notranslate"><span class="pre">#INSERT</span></code> is a comment line but also signifies a special instruction. The syntax is <code class="docutils literal notranslate"><span class="pre">#INSERT</span> <span class="pre">&lt;path.batchfile&gt;</span></code> and tries to import a given batch-cmd file into this one. The inserted batch file (file ending <code class="docutils literal notranslate"><span class="pre">.ev</span></code>) will run normally from the point of the <code class="docutils literal notranslate"><span class="pre">#INSERT</span></code> instruction.</p></li>
<li><p>Extra whitespace in a command definition is <em>ignored</em>. - A completely empty line translates in to a line break in texts. Two empty lines thus means a new paragraph (this is obviously only relevant for commands accepting such formatting, such as the <code class="docutils literal notranslate"><span class="pre">&#64;desc</span></code> command).</p></li>
<li><p>The very last command in the file is not required to end with a comment.</p></li>
<li><p>You <em>cannot</em> nest another <code class="docutils literal notranslate"><span class="pre">batchcommand</span></code> statement into your batch file. If you want to link many batch-files together, use the <code class="docutils literal notranslate"><span class="pre">#INSERT</span></code> batch instruction instead. You also cannot launch the <code class="docutils literal notranslate"><span class="pre">batchcode</span></code> command from your batch file, the two batch processors are not compatible.</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/batch_cmds.ev</span></code>.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="w"> </span><span class="c1">#</span>
<span class="w"> </span><span class="c1"># This is an example batch build file for Evennia. </span>
<span class="w"> </span><span class="c1">#</span>
<span class="w"> </span>
<span class="w"> </span><span class="c1"># This creates a red button</span>
<span class="w"> </span>@create<span class="w"> </span>button:tutorial_examples.red_button.RedButton
<span class="w"> </span><span class="c1"># (This comment ends input for @create)</span>
<span class="w"> </span><span class="c1"># Next command. Let&#39;s create something. </span>
<span class="w"> </span>@set<span class="w"> </span>button/desc<span class="w"> </span><span class="o">=</span><span class="w"> </span>
<span class="w"> </span>This<span class="w"> </span>is<span class="w"> </span>a<span class="w"> </span>large<span class="w"> </span>red<span class="w"> </span>button.<span class="w"> </span>Now<span class="w"> </span>and<span class="w"> </span><span class="k">then</span><span class="w"> </span>
<span class="w"> </span>it<span class="w"> </span>flashes<span class="w"> </span><span class="k">in</span><span class="w"> </span>an<span class="w"> </span>evil,<span class="w"> </span>yet<span class="w"> </span>strangely<span class="w"> </span>tantalizing<span class="w"> </span>way.<span class="w"> </span>
<span class="w"> </span>
<span class="w"> </span>A<span class="w"> </span>big<span class="w"> </span>sign<span class="w"> </span>sits<span class="w"> </span>next<span class="w"> </span>to<span class="w"> </span>it.<span class="w"> </span>It<span class="w"> </span>says:
<span class="w"> </span>
<span class="w"> </span>-----------
<span class="w"> </span>
<span class="w"> </span>Press<span class="w"> </span>me!<span class="w"> </span>
<span class="w"> </span>
<span class="w"> </span>-----------
<span class="w"> </span>
<span class="w"> </span>...<span class="w"> </span>It<span class="w"> </span>really<span class="w"> </span>begs<span class="w"> </span>to<span class="w"> </span>be<span class="w"> </span>pressed!<span class="w"> </span>You<span class="w"> </span>
<span class="w"> </span>know<span class="w"> </span>you<span class="w"> </span>want<span class="w"> </span>to!<span class="w"> </span>
<span class="w"> </span>
<span class="w"> </span><span class="c1"># This inserts the commands from another batch-cmd file named</span>
<span class="w"> </span><span class="c1"># batch_insert_file.ev.</span>
<span class="w"> </span><span class="c1">#INSERT examples.batch_insert_file</span>
<span class="w"> </span>
<span class="w"> </span>
<span class="w"> </span><span class="c1"># (This ends the @set command). Note that single line breaks </span>
<span class="w"> </span><span class="c1"># and extra whitespace in the argument are ignored. Empty lines </span>
<span class="w"> </span><span class="c1"># translate into line breaks in the output.</span>
<span class="w"> </span><span class="c1"># Now let&#39;s place the button where it belongs (let&#39;s say limbo #2 is </span>
<span class="w"> </span><span class="c1"># the evil lair in our example)</span>
<span class="w"> </span>@teleport<span class="w"> </span><span class="c1">#2</span>
<span class="w"> </span><span class="c1"># (This comments ends the @teleport command.) </span>
<span class="w"> </span><span class="c1"># Now we drop it so others can see it. </span>
<span class="w"> </span><span class="c1"># The very last command in the file needs not be ended with #.</span>
<span class="w"> </span>drop<span class="w"> </span>button
</pre></div>
</div>
<p>To test this, run <code class="docutils literal notranslate"><span class="pre">&#64;batchcommand</span></code> on the file:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; batchcommand contrib.tutorial_examples.batch_cmds
</pre></div>
</div>
<p>A button will be created, described and dropped in Limbo. All commands will be executed by the user calling the command.</p>
<blockquote>
<div><p>Note that if you interact with the button, you might find that its description changes, loosing your custom-set description above. This is just the way this particular object works.</p>
</div></blockquote>
</section>
<section id="interactive-mode">
<h2>Interactive mode<a class="headerlink" href="#interactive-mode" title="Permalink to this headline"></a></h2>
<p>Interactive mode allows you to more step-wise control over how the batch file is executed. This is useful for debugging and also if you have a large batch file and is only updating a small part of it – running the entire file again would be a waste of time (and in the case of <code class="docutils literal notranslate"><span class="pre">create</span></code>-ing objects you would to end up with multiple copies of same-named objects, for example). Use <code class="docutils literal notranslate"><span class="pre">batchcommand</span></code> with the <code class="docutils literal notranslate"><span class="pre">/interactive</span></code> flag to enter interactive mode.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> &gt; @batchcommand/interactive tutorial_examples.batch_cmds
</pre></div>
</div>
<p>You will see this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>01/04: @create button:tutorial_examples.red_button.RedButton (hh for help)
</pre></div>
</div>
<p>This shows that you are on the <code class="docutils literal notranslate"><span class="pre">&#64;create</span></code> command, the first out of only four commands in this batch file. Observe that the command <code class="docutils literal notranslate"><span class="pre">&#64;create</span></code> has <em>not</em> been actually processed at this point!</p>
<p>To take a look at the full command 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>). Use <code class="docutils literal notranslate"><span class="pre">pp</span></code> to actually process the current command (this will actually <code class="docutils literal notranslate"><span class="pre">&#64;create</span></code> the button) – and make sure it worked as planned. Use <code class="docutils literal notranslate"><span class="pre">nn</span></code> (next) to go to the next command. Use <code class="docutils literal notranslate"><span class="pre">hh</span></code> for a list of commands.</p>
<p>If there are errors, fix them in the batch file, then use <code class="docutils literal notranslate"><span class="pre">rr</span></code> to reload the file. You will still be at the same command and can rerun it easily with <code class="docutils literal notranslate"><span class="pre">pp</span></code> as needed. This makes for a simple debug cycle. It also allows you to rerun individual troublesome commands - as mentioned, in a large batch file this can be very useful. Do note that in many cases, commands depend on the previous ones (e.g. if <code class="docutils literal notranslate"><span class="pre">create</span></code> in the example above had failed, the following commands would have had nothing to operate on).</p>
<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 command in between). All normal commands of Evennia should work too while working in interactive mode.</p>
</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-command processor is great for automating smaller builds or for testing new commands and objects repeatedly without having to write so much. There are several caveats you have to be aware of when using the batch-command processor for building larger, complex worlds though.</p>
<p>The main issue is that when you run a batch-command script you (<em>you</em>, as in your superuser
character) are actually moving around in the game creating and building rooms in sequence, just as if you had been entering those commands manually, one by one. You have to take this into account when creating the file, so that you can ‘walk’ (or teleport) to the right places in order.</p>
<p>This also means there are several pitfalls when designing and adding certain types of objects. Here are some examples:</p>
<ul class="simple">
<li><p><em>Rooms that change your <a class="reference internal" href="Command-Sets.html"><span class="doc std std-doc">Command Set</span></a></em>: Imagine that you build a ‘dark’ room, which severely limits the cmdsets of those entering it (maybe you have to find the light switch to proceed). In your batch script you would create this room, then teleport to it - and promptly be shifted into the dark state where none of your normal build commands work …</p></li>
<li><p><em>Auto-teleportation</em>: Rooms that automatically teleport those that enter them to another place (like a trap room, for example). You would be teleported away too.</p></li>
<li><p><em>Mobiles</em>: If you add aggressive mobs, they might attack you, drawing you into combat. If they have AI they might even follow you around when building - or they might move away from you before you’ve had time to finish describing and equipping them!</p></li>
</ul>
<p>The solution to all these is to plan ahead. Make sure that superusers are never affected by whatever effects are in play. Add an on/off switch to objects and make sure it’s always set to <em>off</em> upon creation. It’s all doable, one just needs to keep it in mind.</p>
</section>
<section id="editor-highlighting-for-ev-files">
<h2>Editor highlighting for .ev files<a class="headerlink" href="#editor-highlighting-for-ev-files" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference external" href="https://www.gnu.org/software/emacs/">GNU Emacs</a> users might find it interesting to use emacs’ <em>evennia mode</em>. This is an Emacs major mode found in <code class="docutils literal notranslate"><span class="pre">evennia/utils/evennia-mode.el</span></code>. It offers correct syntax highlighting and indentation with <code class="docutils literal notranslate"><span class="pre">&lt;tab&gt;</span></code> when editing <code class="docutils literal notranslate"><span class="pre">.ev</span></code> files in Emacs. See the header of that file for installation instructions.</p></li>
<li><p><a class="reference external" href="https://www.vim.org/">VIM</a> users can use amfl’s <a class="reference external" href="https://github.com/amfl/vim-evennia">vim-evennia</a> mode instead, see its readme for install instructions.</p></li>
</ul>
</section>
</section>
</div>
</div>
</div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Batch-Code-Processor.html" title="Batch Code Processor"
>next</a> |</li>
<li class="right" >
<a href="Batch-Processors.html" title="Batch Processors"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 3.x</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Components-Overview.html" >Core Components</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Batch-Processors.html" >Batch Processors</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Batch Command Processor</a></li>
</ul>
</div>
<div class="admonition important">
<p class="first admonition-title">Note</p>
<p class="last">You are reading an old version of the Evennia documentation. <a href="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2023, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink