<p>For an introduction and motivation to using batch processors, see <aclass="reference internal"href="Batch-Processors.html"><spanclass="doc std std-doc">here</span></a>. This
<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 std std-doc">Command Set</span></a></em>: Imagine that you build a ‘dark’ room, which
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 std std-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>
