<h1><spanclass="section-number">8. </span>Adding custom commands<aclass="headerlink"href="#adding-custom-commands"title="Permalink to this headline">¶</a></h1>
<p>In this lesson we’ll learn how to create our own Evennia <em>Commands</em>. If you are new to Python you’ll also learn some more basics about how to manipulate strings and get information out of Evennia.</p>
<p>A Command is something that handles the input from a user and causes a result to happen.
An example is <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code>, which examines your current location and tells how it looks like and
what is in it.</p>
<asideclass="sidebar">
<pclass="sidebar-title">Commands are not typeclassed</p>
<p>If you just came from the previous lesson, you might want to know that Commands and
CommandSets are not <codeclass="docutils literal notranslate"><spanclass="pre">typeclassed</span></code>. That is, instances of them are not saved to the
database. They are “just” normal Python classes.</p>
</aside>
<p>In Evennia, a Command is a Python <em>class</em>. If you are unsure about what a class is, review the
previous lessons! A Command inherits from <codeclass="docutils literal notranslate"><spanclass="pre">evennia.Command</span></code> or from one of the alternative command-
classes, such as <codeclass="docutils literal notranslate"><spanclass="pre">MuxCommand</span></code> which is what most default commands use.</p>
<p>All Commands are in turn grouped in another class called a <em>Command Set</em>. Think of a Command Set
as a bag holding many different commands. One CmdSet could for example hold all commands for
combat, another for building etc. By default, Evennia groups all character-commands into one
big cmdset.</p>
<p>Command-Sets are then associated with objects, for example with your Character. Doing so makes the
commands in that cmdset available to the object. So, to summarize:</p>
<ulclass="simple">
<li><p>Commands are classes</p></li>
<li><p>A group of Commands is stored in a CmdSet</p></li>
<li><p>CmdSets are stored on objects - this defines which commands are available to that object.</p></li>
</ul>
<sectionid="creating-a-custom-command">
<h2><spanclass="section-number">8.1. </span>Creating a custom command<aclass="headerlink"href="#creating-a-custom-command"title="Permalink to this headline">¶</a></h2>
<spanclass="c1"># (lots of commented-out stuff)</span>
<spanclass="c1"># ...</span>
</pre></div>
</div>
<p>Ignoring the docstrings (which you can read if you want), this is the only really active code in the module.</p>
<p>We can see that we import <codeclass="docutils literal notranslate"><spanclass="pre">Command</span></code> from <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> and use the <codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">...</span><spanclass="pre">import</span><spanclass="pre">...</span><spanclass="pre">as</span><spanclass="pre">...</span></code> form to rename it
to <codeclass="docutils literal notranslate"><spanclass="pre">BaseCommand</span></code>. This is so we can let our child class also be named <codeclass="docutils literal notranslate"><spanclass="pre">Command</span></code> for reference. The class
itself doesn’t do anything, it just has <codeclass="docutils literal notranslate"><spanclass="pre">pass</span></code>. So in the same way as <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code> in the previous lesson, this
class is identical to its parent.</p>
<blockquote>
<div><p>The commented out <codeclass="docutils literal notranslate"><spanclass="pre">default_cmds</span></code> gives us access to Evennia’s default commands for easy overriding. We’ll try
that a little later.</p>
</div></blockquote>
<p>We could modify this module directly, but to train imports we’ll work in a separate module. Open a new file
<codeclass="docutils literal notranslate"><spanclass="pre">mygame/commands/mycommands.py</span></code> and add the following code:</p>
<p>Our <codeclass="docutils literal notranslate"><spanclass="pre">EchoCmdSet</span></code> class must have an <codeclass="docutils literal notranslate"><spanclass="pre">at_cmdset_creation</span></code> method, named exactly
like this - this is what Evennia will be looking for when setting up the cmdset later, so
if you didn’t set it up, it will use the parent’s version, which is empty. Inside we add the
command class to the cmdset by <codeclass="docutils literal notranslate"><spanclass="pre">self.add()</span></code>. If you wanted to add more commands to this CmdSet you
could just add more lines of <codeclass="docutils literal notranslate"><spanclass="pre">self.add</span></code> after this.</p>
<p>Finally, let’s add this command to ourselves so we can try it out. In-game you can experiment with <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> again:</p>
Command echo has no defined `func()` - showing on-command variables:
...
...
</pre></div>
</div>
<p>You should be getting a long list of outputs. The reason for this is that your <codeclass="docutils literal notranslate"><spanclass="pre">echo</span></code> function is not really
“doing” anything yet and the default function is then to show all useful resources available to you when you
use your Command. Let’s look at some of those listed:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>Command echo has no defined `func()` - showing on-command variables:
<p>These are all properties you can access with <codeclass="docutils literal notranslate"><spanclass="pre">.</span></code> on the Command instance, such as <codeclass="docutils literal notranslate"><spanclass="pre">.key</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">.args</span></code> and so on.
Evennia makes these available to you and they will be different every time a command is run. The most
important ones we will make use of now are:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> - this is ‘you’, the person calling the command.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> - this is all arguments to the command. Now it’s empty, but if you tried <codeclass="docutils literal notranslate"><spanclass="pre">echo</span><spanclass="pre">foo</span><spanclass="pre">bar</span></code> you’d find
that this would be <codeclass="docutils literal notranslate"><spanclass="pre">"</span><spanclass="pre">foo</span><spanclass="pre">bar"</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code> - this is object on which this Command (and CmdSet) “sits”. So you, in this case.</p></li>
</ul>
<p>The reason our command doesn’t do anything yet is because it’s missing a <codeclass="docutils literal notranslate"><spanclass="pre">func</span></code> method. This is what Evennia
looks for to figure out what a Command actually does. Modify your <codeclass="docutils literal notranslate"><spanclass="pre">CmdEcho</span></code> class:</p>
<p>First we added a docstring. This is always a good thing to do in general, but for a Command class, it will also
automatically become the in-game help entry! Next we add the <codeclass="docutils literal notranslate"><spanclass="pre">func</span></code> method. It has one active line where it
makes use of some of those variables we found the Command offers to us. If you did the
<aclass="reference internal"href="Beginner-Tutorial-Python-basic-introduction.html"><spanclass="doc std std-doc">basic Python tutorial</span></a>, you will recognize <codeclass="docutils literal notranslate"><spanclass="pre">.msg</span></code> - this will send a message
to the object it is attached to us - in this case <codeclass="docutils literal notranslate"><spanclass="pre">self.caller</span></code>, that is, us. We grab <codeclass="docutils literal notranslate"><spanclass="pre">self.args</span></code> and includes
that in the message.</p>
<p>Since we haven’t changed <codeclass="docutils literal notranslate"><spanclass="pre">MyCmdSet</span></code>, that will work as before. Reload and re-add this command to ourselves to
<p>Note that there is an extra space before <codeclass="docutils literal notranslate"><spanclass="pre">Woo!</span></code>. That is because self.args contains the <em>everything</em> after
the command name, including spaces. Evennia will happily understand if you skip that space too:</p>
<p>The only difference is that we called <codeclass="docutils literal notranslate"><spanclass="pre">.strip()</span></code> on <codeclass="docutils literal notranslate"><spanclass="pre">self.args</span></code>. This is a helper method available on all
strings - it strips out all whitespace before and after the string. Now the Command-argument will no longer
<p>Don’t forget to look at the help for the echo command:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>> help echo
</pre></div>
</div>
<p>You will get the docstring you put in your Command-class.</p>
<sectionid="making-our-cmdset-persistent">
<h3><spanclass="section-number">8.1.1. </span>Making our cmdset persistent<aclass="headerlink"href="#making-our-cmdset-persistent"title="Permalink to this headline">¶</a></h3>
<p>It’s getting a little annoying to have to re-add our cmdset every time we reload, right? It’s simple
enough to make <codeclass="docutils literal notranslate"><spanclass="pre">echo</span></code> a <em>persistent</em> change though:</p>
<p>Now you can <codeclass="docutils literal notranslate"><spanclass="pre">reload</span></code> as much as you want and your code changes will be available directly without
needing to re-add the MyCmdSet again. To remove the cmdset again, do</p>
<p>But for now, keep it around, we’ll expand it with some more examples.</p>
</section>
<sectionid="figuring-out-who-to-hit">
<h3><spanclass="section-number">8.1.2. </span>Figuring out who to hit<aclass="headerlink"href="#figuring-out-who-to-hit"title="Permalink to this headline">¶</a></h3>
<p>Let’s try something a little more exciting than just echo. Let’s make a <codeclass="docutils literal notranslate"><spanclass="pre">hit</span></code> command, for punching
someone in the face! This is how we want it to work:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>> hit <target>
You hit <target> with full force!
</pre></div>
</div>
<p>Not only that, we want the <target> to see</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>You got hit by <hitter> with full force!
</pre></div>
</div>
<p>Here, <codeclass="docutils literal notranslate"><spanclass="pre"><hitter></span></code> would be the one using the <codeclass="docutils literal notranslate"><spanclass="pre">hit</span></code> command and <codeclass="docutils literal notranslate"><spanclass="pre"><target></span></code> is the one doing the punching.</p>
<p>Still in <codeclass="docutils literal notranslate"><spanclass="pre">mygame/commands/mycommands.py</span></code>, add a new class, between <codeclass="docutils literal notranslate"><spanclass="pre">CmdEcho</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">MyCmdSet</span></code>.</p>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"Who do you want to hit?"</span><spanclass="p">)</span>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="sa">f</span><spanclass="s2">"You hit </span><spanclass="si">{</span><spanclass="n">target</span><spanclass="o">.</span><spanclass="n">key</span><spanclass="si">}</span><spanclass="s2"> with full force!"</span><spanclass="p">)</span>
<spanclass="n">target</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="sa">f</span><spanclass="s2">"You got hit by </span><spanclass="si">{</span><spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">key</span><spanclass="si">}</span><spanclass="s2"> with full force!"</span><spanclass="p">)</span>
<spanclass="c1"># ...</span>
</pre></div></td></tr></table></div>
</div>
<p>A lot of things to dissect here:</p>
<ulclass="simple">
<li><p><strong>Line 3</strong>: The normal <codeclass="docutils literal notranslate"><spanclass="pre">class</span></code> header. We inherit from <codeclass="docutils literal notranslate"><spanclass="pre">Command</span></code> which we imported at the top of this file.</p></li>
<li><p><strong>Lines 4-10</strong>: The docstring and help-entry for the command. You could expand on this as much as you wanted.</p></li>
<li><p><strong>Line 11</strong>: We want to write <codeclass="docutils literal notranslate"><spanclass="pre">hit</span></code> to use this command.</p></li>
<li><p><strong>Line 14</strong>: We strip the whitespace from the argument like before. Since we don’t want to have to do
<codeclass="docutils literal notranslate"><spanclass="pre">self.args.strip()</span></code> over and over, we store the stripped version
in a <em>local variable</em><codeclass="docutils literal notranslate"><spanclass="pre">args</span></code>. Note that we don’t modify <codeclass="docutils literal notranslate"><spanclass="pre">self.args</span></code> by doing this, <codeclass="docutils literal notranslate"><spanclass="pre">self.args</span></code> will still
have the whitespace and is not the same as <codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> in this example.</p></li>
<p>There can be any number of <codeclass="docutils literal notranslate"><spanclass="pre">elifs</span></code> to mark when different branches of the code should run. If
the <codeclass="docutils literal notranslate"><spanclass="pre">else</span></code> condition is given, it will run if none of the other conditions was truthy. In Python
the <codeclass="docutils literal notranslate"><spanclass="pre">if..elif..else</span></code> structure also serves the same function as <codeclass="docutils literal notranslate"><spanclass="pre">case</span></code> in some other languages.</p>
</aside>
<ul>
<li><p><strong>Line 15</strong> has our first <em>conditional</em>, an <codeclass="docutils literal notranslate"><spanclass="pre">if</span></code> statement. This is written on the form <codeclass="docutils literal notranslate"><spanclass="pre">if</span><spanclass="pre"><condition>:</span></code> and only
if that condition is ‘truthy’ will the indented code block under the <codeclass="docutils literal notranslate"><spanclass="pre">if</span></code> statement run. To learn what is truthy in
Python it’s usually easier to learn what is “falsy”:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">False</span></code> - this is a reserved boolean word in Python. The opposite is <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> - another reserved word. This represents nothing, a null-result or value.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">0</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">0.0</span></code></p></li>
<li><p>The empty string <codeclass="docutils literal notranslate"><spanclass="pre">""</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">''</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">""""""</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">''''''</span></code></p></li>
<li><p>Empty <em>iterables</em> we haven’t seen yet, like empty lists <codeclass="docutils literal notranslate"><spanclass="pre">[]</span></code>, empty tuples <codeclass="docutils literal notranslate"><spanclass="pre">()</span></code> and empty dicts <codeclass="docutils literal notranslate"><spanclass="pre">{}</span></code>.</p></li>
<li><p>Everything else is “truthy”.</p></li>
</ul>
<p>Line 16’s condition is <codeclass="docutils literal notranslate"><spanclass="pre">not</span><spanclass="pre">args</span></code>. The <codeclass="docutils literal notranslate"><spanclass="pre">not</span></code><em>inverses</em> the result, so if <codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> is the empty string (falsy), the
whole conditional becomes truthy. Let’s continue in the code:</p>
</li>
<li><p><strong>Lines 16-17</strong>: This code will only run if the <codeclass="docutils literal notranslate"><spanclass="pre">if</span></code> statement is truthy, in this case if <codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> is the empty string.</p></li>
<li><p><strong>Line 17</strong>: <codeclass="docutils literal notranslate"><spanclass="pre">return</span></code> is a reserved Python word that exits <codeclass="docutils literal notranslate"><spanclass="pre">func</span></code> immediately.</p></li>
<li><p><strong>Line 18</strong>: We use <codeclass="docutils literal notranslate"><spanclass="pre">self.caller.search</span></code> to look for the target in the current location.</p></li>
<li><p><strong>Lines 19-20</strong>: A feature of <codeclass="docutils literal notranslate"><spanclass="pre">.search</span></code> is that it will already inform <codeclass="docutils literal notranslate"><spanclass="pre">self.caller</span></code> if it couldn’t find the target.
In that case, <codeclass="docutils literal notranslate"><spanclass="pre">target</span></code> will be <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> and we should just directly <codeclass="docutils literal notranslate"><spanclass="pre">return</span></code>.</p></li>
<li><p><strong>Lines 21-22</strong>: At this point we have a suitable target and can send our punching strings to each.</p></li>
</ul>
<p>Finally we must also add this to a CmdSet. Let’s add it to <codeclass="docutils literal notranslate"><spanclass="pre">MyCmdSet</span></code> which we made persistent earlier.</p>
<p>With longer code snippets to try, it gets more and more likely you’ll
make an error and get a <codeclass="docutils literal notranslate"><spanclass="pre">traceback</span></code> when you reload. This will either appear
directly in-game or in your log (view it with <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">-l</span></code> in a terminal).
Don’t panic; tracebacks are your friends - they are to be read bottom-up and usually describe
exactly where your problem is. Refer to <codeclass="docutils literal notranslate"><spanclass="pre">The</span><spanclass="pre">Python</span><spanclass="pre">intro</span><spanclass="pre"><Python-basic-introduction.html></span></code>_ for
more hints. If you get stuck, reach out to the Evennia community for help.</p>
</aside>
<p>Next we reload to let Evennia know of these code changes and try it out:</p>
