<p>For an introduction and motivation to using batch processors, see <aclass="reference internal"href="Batch-Processors.html"><spanclass="doc">here</span></a>. This
page describes the Batch-<em>command</em> processor. The Batch-<em>code</em> one is covered [here](Batch-Code-
<p>Where <codeclass="docutils literal notranslate"><spanclass="pre">path.to.batchcmdfile</span></code> is the path to a <em>batch-command file</em> with the “<codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">BATCH_IMPORT_PATH</span></code> in your settings. Default folder is (assuming your game is in the <codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code>
folder) <codeclass="docutils literal notranslate"><spanclass="pre">mygame/world</span></code>. So if you want to run the example batch file in
<codeclass="docutils literal notranslate"><spanclass="pre">mygame/world/batch_cmds.ev</span></code>, you could use</p>
<p>Here are the rules of syntax of an <codeclass="docutils literal notranslate"><spanclass="pre">*.ev</span></code> file. You’ll find it’s really, really simple:</p>
<li><p>All lines having the <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">#INSERT</span></code> is a comment line but also signifies a special
instruction. The syntax is <codeclass="docutils literal notranslate"><spanclass="pre">#INSERT</span><spanclass="pre"><path.batchfile></span></code> and tries to import a given batch-cmd file
into this one. The inserted batch file (file ending <codeclass="docutils literal notranslate"><spanclass="pre">.ev</span></code>) will run normally from the point of the
<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 <codeclass="docutils literal notranslate"><spanclass="pre">@desc</span></code> command).</p></li>
<li><p>You <em>cannot</em> nest another <codeclass="docutils literal notranslate"><spanclass="pre">@batchcommand</span></code> statement into your batch file. If you want to link many
batch-files together, use the <codeclass="docutils literal notranslate"><spanclass="pre">#INSERT</span></code> batch instruction instead. You also cannot launch the
<codeclass="docutils literal notranslate"><spanclass="pre">@batchcode</span></code> command from your batch file, the two batch processors are not compatible.</p></li>
<p>Below is a version of the example file found in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/contrib/tutorial_examples/batch_cmds.ev</span></code>.</p>
<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 <codeclass="docutils literal notranslate"><spanclass="pre">@create</span></code>-ing objects
you would to end up with multiple copies of same-named objects, for example). Use <codeclass="docutils literal notranslate"><spanclass="pre">@batchcommand</span></code>
with the <codeclass="docutils literal notranslate"><spanclass="pre">/interactive</span></code> flag to enter interactive mode.</p>
<p>This shows that you are on the <codeclass="docutils literal notranslate"><spanclass="pre">@create</span></code> command, the first out of only four commands in this batch
file. Observe that the command <codeclass="docutils literal notranslate"><spanclass="pre">@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 <codeclass="docutils literal notranslate"><spanclass="pre">ll</span></code> (a batch-processor version of
<codeclass="docutils literal notranslate"><spanclass="pre">look</span></code>). Use <codeclass="docutils literal notranslate"><spanclass="pre">pp</span></code> to actually process the current command (this will actually <codeclass="docutils literal notranslate"><spanclass="pre">@create</span></code> the button)
– and make sure it worked as planned. Use <codeclass="docutils literal notranslate"><spanclass="pre">nn</span></code> (next) to go to the next command. Use <codeclass="docutils literal notranslate"><spanclass="pre">hh</span></code> for a
list of commands.</p>
<p>If there are errors, fix them in the batch file, then use <codeclass="docutils literal notranslate"><spanclass="pre">rr</span></code> to reload the file. You will still be
at the same command and can rerun it easily with <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">@create</span></code> in the example above had failed, the following commands would have had nothing to
operate on).</p>
<p>Use <codeclass="docutils literal notranslate"><spanclass="pre">nn</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">bb</span></code> (next and back) to step through the file; e.g. <codeclass="docutils literal notranslate"><spanclass="pre">nn</span><spanclass="pre">12</span></code> will jump 12 steps forward
(without processing any command in between). All normal commands of Evennia should work too while
<li><p><em>Rooms that change your <aclass="reference internal"href="Command-Sets.html"><spanclass="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>
<p>The fact that you build as ‘yourself’ can also be considered an advantage however, should you ever
decide to change the default command to allow others than superusers to call the processor. Since
normal access-checks are still performed, a malevolent builder with access to the processor should
not be able to do all that much damage (this is the main drawback of the <aclass="reference internal"href="Batch-Code-Processor.html"><spanclass="doc">Batch Code
<li><p><aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">evennia/utils/evennia-mode.el</span></code>. It offers
correct syntax highlighting and indentation with <codeclass="docutils literal notranslate"><spanclass="pre"><tab></span></code> when editing <codeclass="docutils literal notranslate"><spanclass="pre">.ev</span></code> files in Emacs. See the
header of that file for installation instructions.</p></li>
<li><p><aclass="reference external"href="http://www.vim.org/">VIM</a> users can use amfl’s <aclass="reference external"href="https://github.com/amfl/vim-evennia">vim-evennia</a>
mode instead, see its readme for install instructions.</p></li>
