<h1>Adding Command Tutorial<aclass="headerlink"href="#adding-command-tutorial"title="Permalink to this headline">¶</a></h1>
<p>This is a quick first-time tutorial expanding on the <aclass="reference internal"href="Commands.html"><spanclass="doc">Commands</span></a> documentation.</p>
<p>Let’s assume you have just downloaded Evennia, installed it and created your game folder (let’s call
it just <codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code> here). Now you want to try to add a new command. This is the fastest way to do it.</p>
<h2>Step 1: Creating a custom command<aclass="headerlink"href="#step-1-creating-a-custom-command"title="Permalink to this headline">¶</a></h2>
<olclass="simple">
<li><p>Open <codeclass="docutils literal notranslate"><spanclass="pre">mygame/commands/command.py</span></code> in a text editor. This is just one place commands could be placed but you get it setup from the onset as an easy place to start. It also already contains some example code.</p></li>
<li><p>Create a new class in <codeclass="docutils literal notranslate"><spanclass="pre">command.py</span></code> inheriting from <codeclass="docutils literal notranslate"><spanclass="pre">default_cmds.MuxCommand</span></code>. Let’s call it
<codeclass="docutils literal notranslate"><spanclass="pre">CmdEcho</span></code> in this example.</p></li>
<li><p>Set the class variable <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> to a good command name, like <codeclass="docutils literal notranslate"><spanclass="pre">echo</span></code>.</p></li>
<li><p>Give your class a useful <em>docstring</em>. A docstring is the string at the very top of a class or function/method. The docstring at the top of the command class is read by Evennia to become the help entry for the Command (see
<li><p>Define a class method <codeclass="docutils literal notranslate"><spanclass="pre">func(self)</span></code> that echoes your input back to you.</p></li>
</ol>
<p>Below is an example how this all could look for the echo command:</p>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"You didn't enter anything!"</span><spanclass="p">)</span>
<spanclass="k">else</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="s2">"You gave the string: '</span><spanclass="si">%s</span><spanclass="s2">'"</span><spanclass="o">%</span><spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">args</span><spanclass="p">)</span>
<h2>Step 2: Adding the Command to a default Cmdset<aclass="headerlink"href="#step-2-adding-the-command-to-a-default-cmdset"title="Permalink to this headline">¶</a></h2>
<p>The command is not available to use until it is part of a <aclass="reference internal"href="Command-Sets.html"><spanclass="doc">Command Set</span></a>. In this
example we will go the easiest route and add it to the default Character commandset that already
<li><p>Import your new command with <codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">commands.command</span><spanclass="pre">import</span><spanclass="pre">CmdEcho</span></code>.</p></li>
<li><p>Add a line <codeclass="docutils literal notranslate"><spanclass="pre">self.add(CmdEcho())</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">CharacterCmdSet</span></code>, in the <codeclass="docutils literal notranslate"><spanclass="pre">at_cmdset_creation</span></code> method (the
template tells you where).</p></li>
</ol>
<p>This is approximately how it should look at this point:</p>
<p>Next, run the <codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code> command. You should now be able to use your new <codeclass="docutils literal notranslate"><spanclass="pre">echo</span></code> command from inside
the game. Use <codeclass="docutils literal notranslate"><spanclass="pre">help</span><spanclass="pre">echo</span></code> to see the documentation for the command.</p>
<p>If you have trouble, make sure to check the log for error messages (probably due to syntax errors in
your command definition).</p>
<blockquote>
<div><p>Note: Typing <codeclass="docutils literal notranslate"><spanclass="pre">echotest</span></code> will also work. It will be handled as the command <codeclass="docutils literal notranslate"><spanclass="pre">echo</span></code> directly followed by
its argument <codeclass="docutils literal notranslate"><spanclass="pre">test</span></code> (which will end up in <codeclass="docutils literal notranslate"><spanclass="pre">self.args).</span><spanclass="pre">To</span><spanclass="pre">change</span><spanclass="pre">this</span><spanclass="pre">behavior,</span><spanclass="pre">you</span><spanclass="pre">can</span><spanclass="pre">add</span><spanclass="pre">the</span></code>arg_regex<codeclass="docutils literal notranslate"><spanclass="pre">property</span><spanclass="pre">alongside</span></code>key<codeclass="docutils literal notranslate"><spanclass="pre">,</span></code>help_category` etc. <aclass="reference external"href="/Commands.html#on-arg_regex">See the arg_regex documentation</a> for more info.</p>
</div></blockquote>
<p>If you want to overload existing default commands (such as <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">get</span></code>), just add your new
command with the same key as the old one - it will then replace it. Just remember that you must use
<codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code> to see any changes.</p>
<p>See <aclass="reference internal"href="Commands.html"><spanclass="doc">Commands</span></a> for many more details and possibilities when defining Commands and using
<h2>Adding the command to specific object types<aclass="headerlink"href="#adding-the-command-to-specific-object-types"title="Permalink to this headline">¶</a></h2>
<p>Adding your Command to the <codeclass="docutils literal notranslate"><spanclass="pre">CharacterCmdSet</span></code> is just one easy exapmple. The cmdset system is very
generic. You can create your own cmdsets (let’s say in a module <codeclass="docutils literal notranslate"><spanclass="pre">mycmdsets.py</span></code>) and add them to
objects as you please (how to control their merging is described in detail in the <aclass="reference internal"href="Command-Sets.html"><spanclass="doc">Command Set
<p>This will add this cmdset (along with its echo command) to yourself so you can test it. Note that
you cannot add a single Command to an object on its own, it must be part of a CommandSet in order to
do so.</p>
<p>The Command you added is not there permanently at this point. If you do a <codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code> the merger will
be gone. You <em>could</em> add the <codeclass="docutils literal notranslate"><spanclass="pre">permanent=True</span></code> keyword to the <codeclass="docutils literal notranslate"><spanclass="pre">cmdset.add</span></code> call. This will however
only make the new merged cmdset permanent on that <em>single</em> object. Often you want <em>all</em> objects of
this particular class to have this cmdset.</p>
<p>To make sure all new created objects get your new merged set, put the <codeclass="docutils literal notranslate"><spanclass="pre">cmdset.add</span></code> call in your
<p>All new objects of this typeclass will now start with this cmdset and it will survive a <codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code>.</p>
<p><em>Note:</em> An important caveat with this is that <codeclass="docutils literal notranslate"><spanclass="pre">at_object_creation</span></code> is only called <em>once</em>, when the
object is first created. This means that if you already have existing objects in your databases
using that typeclass, they will not have been initiated the same way. There are many ways to update
them; since it’s a one-time update you can usually just simply loop through them. As superuser, try
<p>This goes through all objects in your database having the right typeclass, adding the new cmdset to
each. The good news is that you only have to do this if you want to post-add <em>cmdsets</em>. If you just
want to add a new <em>command</em>, you can simply add that command to the cmdset’s <codeclass="docutils literal notranslate"><spanclass="pre">at_cmdset_creation</span></code>
and <codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code> to make the Command immediately available.</p>
<h2>Change where Evennia looks for command sets<aclass="headerlink"href="#change-where-evennia-looks-for-command-sets"title="Permalink to this headline">¶</a></h2>
<p>Evennia uses settings variables to know where to look for its default command sets. These are
normally not changed unless you want to re-organize your game folder in some way. For example, the
default character cmdset defaults to being defined as</p>
