<p>Commands are intimately linked to <aclass="reference internal"href="Command-Sets.html"><spanclass="doc">Command Sets</span></a> and you need to read that page too to
be familiar with how the command system works. The two pages were split for easy reading.</p>
<p>The basic way for users to communicate with the game is through <em>Commands</em>. These can be commands
directly related to the game world such as <em>look</em>, <em>get</em>, <em>drop</em> and so on, or administrative
commands such as <em>examine</em> or <em>@dig</em>.</p>
<p>The <aclass="reference external"href="../api/evennia.commands.default.html#modules">default commands</a> coming with Evennia are ‘MUX-like’ in that they use @
for admin commands, support things like switches, syntax with the ‘=’ symbol etc, but there is
nothing that prevents you from implementing a completely different command scheme for your game. You
can find the default commands in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/commands/default</span></code>. You should not edit these directly -
they will be updated by the Evennia team as new features are added. Rather you should look to them
for inspiration and inherit your own designs from them.</p>
<p>There are two components to having a command running - the <em>Command</em> class and the
<aclass="reference internal"href="Command-Sets.html"><spanclass="doc">Command Set</span></a> (command sets were split into a separate wiki page for ease of reading).</p>
page detailing <aclass="reference internal"href="Command-Sets.html"><spanclass="doc">Command Sets</span></a>. There is also a step-by-step
<aclass="reference internal"href="../Howto/Starting/Part1/Adding-Commands.html"><spanclass="doc">Adding Command Tutorial</span></a> that will get you started quickly without the
<p>All commands are implemented as normal Python classes inheriting from the base class <codeclass="docutils literal notranslate"><spanclass="pre">Command</span></code>
(<codeclass="docutils literal notranslate"><spanclass="pre">evennia.Command</span></code>). You will find that this base class is very “bare”. The default commands of
Evennia actually inherit from a child of <codeclass="docutils literal notranslate"><spanclass="pre">Command</span></code> called <codeclass="docutils literal notranslate"><spanclass="pre">MuxCommand</span></code> - this is the class that
knows all the mux-like syntax like <codeclass="docutils literal notranslate"><spanclass="pre">/switches</span></code>, splitting by “=” etc. Below we’ll avoid mux-
specifics and use the base <codeclass="docutils literal notranslate"><spanclass="pre">Command</span></code> class directly.</p>
<p>In Evennia there are three types of objects that may call the command. It is important to be aware
of this since this will also assign appropriate <codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">session</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">sessid</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">account</span></code>
properties on the command body at runtime. Most often the calling type is <codeclass="docutils literal notranslate"><spanclass="pre">Session</span></code>.</p>
<li><p>A <aclass="reference internal"href="Sessions.html"><spanclass="doc">Session</span></a>. This is by far the most common case when a user is entering a command in
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> - this is set to the puppeted <aclass="reference internal"href="Objects.html"><spanclass="doc">Object</span></a> if such an object exists. If no
puppet is found, <codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> is set equal to <codeclass="docutils literal notranslate"><spanclass="pre">account</span></code>. Only if an Account is not found either (such as
before being logged in) will this be set to the Session object itself.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">session</span></code> - a reference to the <aclass="reference internal"href="Sessions.html"><spanclass="doc">Session</span></a> object itself.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">sessid</span></code> - <codeclass="docutils literal notranslate"><spanclass="pre">sessid.id</span></code>, a unique integer identifier of the session.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">account</span></code> - the <aclass="reference internal"href="Accounts.html"><spanclass="doc">Account</span></a> object connected to this Session. None if not logged in.</p></li>
<li><p>An <aclass="reference internal"href="Accounts.html"><spanclass="doc">Account</span></a>. This only happens if <codeclass="docutils literal notranslate"><spanclass="pre">account.execute_cmd()</span></code> was used. No Session
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> - this is set to the puppeted Object if such an object can be determined (without
Session info this can only be determined in <codeclass="docutils literal notranslate"><spanclass="pre">MULTISESSION_MODE=0</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">1</span></code>). If no puppet is found,
this is equal to <codeclass="docutils literal notranslate"><spanclass="pre">account</span></code>.</p></li>
<li><p>An <aclass="reference internal"href="Objects.html"><spanclass="doc">Object</span></a>. This only happens if <codeclass="docutils literal notranslate"><spanclass="pre">object.execute_cmd()</span></code> was used (for example by an
<div><p><codeclass="docutils literal notranslate"><spanclass="pre">*)</span></code>: There is a way to make the Session available also inside tests run directly on Accounts and
Objects, and that is to pass it to <codeclass="docutils literal notranslate"><spanclass="pre">execute_cmd</span></code> like so: <codeclass="docutils literal notranslate"><spanclass="pre">account.execute_cmd("...",</span><spanclass="pre">session=<Session>)</span></code>. Doing so <em>will</em> make the <codeclass="docutils literal notranslate"><spanclass="pre">.session</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">.sessid</span></code> properties available in the
<h3>Properties assigned to the command instance at run-time<aclass="headerlink"href="#properties-assigned-to-the-command-instance-at-run-time"title="Permalink to this headline">¶</a></h3>
<p>Let’s say account <em>Bob</em> with a character <em>BigGuy</em> enters the command <em>look at sword</em>. After the
system having successfully identified this as the “look” command and determined that BigGuy really
has access to a command named <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code>, it chugs the <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code> command class out of storage and either
loads an existing Command instance from cache or creates one. After some more checks it then assigns
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> - The character BigGuy, in this example. This is a reference to the object executing the
command. The value of this depends on what type of object is calling the command; see the previous
section.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">session</span></code> - the <aclass="reference internal"href="Sessions.html"><spanclass="doc">Session</span></a> Bob uses to connect to the game and control BigGuy (see also
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">sessid</span></code> - the unique id of <codeclass="docutils literal notranslate"><spanclass="pre">self.session</span></code>, for quick lookup.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">account</span></code> - the <aclass="reference internal"href="Accounts.html"><spanclass="doc">Account</span></a> Bob (see previous section).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">cmdstring</span></code> - the matched key for the command. This would be <em>look</em> in our example.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> - this is the rest of the string, except the command name. So if the string entered was
<em>look at sword</em>, <codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> would be “ <em>at sword</em>”. Note the space kept - Evennia would correctly
interpret <codeclass="docutils literal notranslate"><spanclass="pre">lookat</span><spanclass="pre">sword</span></code> too. This is useful for things like <codeclass="docutils literal notranslate"><spanclass="pre">/switches</span></code> that should not use space.
In the <codeclass="docutils literal notranslate"><spanclass="pre">MuxCommand</span></code> class used for default commands, this space is stripped. Also see the
<codeclass="docutils literal notranslate"><spanclass="pre">arg_regex</span></code> property if you want to enforce a space to make <codeclass="docutils literal notranslate"><spanclass="pre">lookat</span><spanclass="pre">sword</span></code> give a command-not-found
error.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code> - the game <aclass="reference internal"href="Objects.html"><spanclass="doc">Object</span></a> on which this command is defined. This need not be the caller,
but since <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code> is a common (default) command, this is probably defined directly on <em>BigGuy</em> - so
<codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code> will point to BigGuy. Otherwise <codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code> could be an Account or any interactive object with
commands defined on it, like in the example of the “check time” command defined on a “Clock” object.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">cmdset</span></code> - this is a reference to the merged CmdSet (see below) from which this command was
matched. This variable is rarely used, it’s main use is for the [auto-help system](Help-
System#command-auto-help-system) (<em>Advanced note: the merged cmdset need NOT be the same as
<codeclass="docutils literal notranslate"><spanclass="pre">BigGuy.cmdset</span></code>. The merged set can be a combination of the cmdsets from other objects in the room,
for example</em>).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">raw_string</span></code> - this is the raw input coming from the user, without stripping any surrounding
whitespace. The only thing that is stripped is the ending newline marker.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.get_help(caller,</span><spanclass="pre">cmdset)</span></code> - Get the help entry for this command. By default the arguments are
used, but they could be used to implement alternate help-display systems.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.client_width()</span></code> - Shortcut for getting the client’s screen-width. Note that not all clients will
truthfully report this value - that case the <codeclass="docutils literal notranslate"><spanclass="pre">settings.DEFAULT_SCREEN_WIDTH</span></code> will be returned.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.styled_table(*args,</span><spanclass="pre">**kwargs)</span></code> - This returns an [EvTable](api:evennia.utils#module-
evennia.utils.evtable) styled based on the
session calling this command. The args/kwargs are the same as for EvTable, except styling defaults
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.styled_header</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">_footer</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">separator</span></code> - These will produce styled decorations for
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> (string) - the identifier for the command, like <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code>. This should (ideally) be unique. A
key can consist of more than one word, like “press button” or “pull left lever”. Note that <em>both</em>
<codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">aliases</span></code> below determine the identity of a command. So two commands are considered if
either matches. This is important for merging cmdsets described below.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">aliases</span></code> (optional list) - a list of alternate names for the command (<codeclass="docutils literal notranslate"><spanclass="pre">["glance",</span><spanclass="pre">"see",</span><spanclass="pre">"l"]</span></code>).
Same name rules as for <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> applies.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">locks</span></code> (string) - a <aclass="reference internal"href="Locks.html"><spanclass="doc">lock definition</span></a>, usually on the form <codeclass="docutils literal notranslate"><spanclass="pre">cmd:<lockfuncs></span></code>. Locks is a
rather big topic, so until you learn more about locks, stick to giving the lockstring <codeclass="docutils literal notranslate"><spanclass="pre">"cmd:all()"</span></code>
to make the command available to everyone (if you don’t provide a lock string, this will be assigned
for you).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">help_category</span></code> (optional string) - setting this helps to structure the auto-help into categories.
If none is set, this will be set to <em>General</em>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">save_for_next</span></code> (optional boolean). This defaults to <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code>. If <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code>, a copy of this command
object (along with any changes you have done to it) will be stored by the system and can be accessed
by the next command by retrieving <codeclass="docutils literal notranslate"><spanclass="pre">self.caller.ndb.last_cmd</span></code>. The next run command will either clear
or replace the storage.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">arg_regex</span></code> (optional raw string): Used to force the parser to limit itself and tell it when the
command-name ends and arguments begin (such as requiring this to be a space or a /switch). This is
done with a regular expression. <aclass="reference external"href="Components/Commands.html#on-arg_regex">See the arg_regex section</a> for the details.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">auto_help</span></code> (optional boolean). Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code>. This allows for turning off the
<aclass="reference external"href="Components/Help-System.html#command-auto-help-system">auto-help system</a> on a per-command basis. This could be useful if you
either want to write your help entries manually or hide the existence of a command from <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code>’s
generated list.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">is_exit</span></code> (bool) - this marks the command as being used for an in-game exit. This is, by default,
set by all Exit objects and you should not need to set it manually unless you make your own Exit
system. It is used for optimization and allows the cmdhandler to easily disregard this command when
the cmdset has its <codeclass="docutils literal notranslate"><spanclass="pre">no_exits</span></code> flag set.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">is_channel</span></code> (bool)- this marks the command as being used for an in-game channel. This is, by
default, set by all Channel objects and you should not need to set it manually unless you make your
own Channel system. is used for optimization and allows the cmdhandler to easily disregard this
command when its cmdset has its <codeclass="docutils literal notranslate"><spanclass="pre">no_channels</span></code> flag set.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">msg_all_sessions</span></code> (bool): This affects the behavior of the <codeclass="docutils literal notranslate"><spanclass="pre">Command.msg</span></code> method. If unset
(default), calling <codeclass="docutils literal notranslate"><spanclass="pre">self.msg(text)</span></code> from the Command will always only send text to the Session that
actually triggered this Command. If set however, <codeclass="docutils literal notranslate"><spanclass="pre">self.msg(text)</span></code> will send to all Sessions relevant
to the object this Command sits on. Just which Sessions receives the text depends on the object and
the server’s <codeclass="docutils literal notranslate"><spanclass="pre">MULTISESSION_MODE</span></code>.</p></li>
<p>You should also implement at least two methods, <codeclass="docutils literal notranslate"><spanclass="pre">parse()</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">func()</span></code> (You could also implement
<codeclass="docutils literal notranslate"><spanclass="pre">perm()</span></code>, but that’s not needed unless you want to fundamentally change how access checks work).</p>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_pre_cmd()</span></code> is called very first on the command. If this function returns anything that
evaluates to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> the command execution is aborted at this point.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">parse()</span></code> is intended to parse the arguments (<codeclass="docutils literal notranslate"><spanclass="pre">self.args</span></code>) of the function. You can do this in any
way you like, then store the result(s) in variable(s) on the command object itself (i.e. on <codeclass="docutils literal notranslate"><spanclass="pre">self</span></code>).
To take an example, the default mux-like system uses this method to detect “command switches” and
store them as a list in <codeclass="docutils literal notranslate"><spanclass="pre">self.switches</span></code>. Since the parsing is usually quite similar inside a command
scheme you should make <codeclass="docutils literal notranslate"><spanclass="pre">parse()</span></code> as generic as possible and then inherit from it rather than re-
implementing it over and over. In this way, the default <codeclass="docutils literal notranslate"><spanclass="pre">MuxCommand</span></code> class implements a <codeclass="docutils literal notranslate"><spanclass="pre">parse()</span></code>
for all child commands to use.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">func()</span></code> is called right after <codeclass="docutils literal notranslate"><spanclass="pre">parse()</span></code> and should make use of the pre-parsed input to actually
do whatever the command is supposed to do. This is the main body of the command. The return value
from this method will be returned from the execution as a Twisted Deferred.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">at_post_cmd()</span></code> is called after <codeclass="docutils literal notranslate"><spanclass="pre">func()</span></code> to handle eventual cleanup.</p></li>
<p>Finally, you should always make an informative <aclass="reference external"href="http://www.python.org/dev/peps/pep-0257/#what-is-a-docstring">doc
string</a> (<codeclass="docutils literal notranslate"><spanclass="pre">__doc__</span></code>) at the top of your
class. This string is dynamically read by the <aclass="reference internal"href="Help-System.html"><spanclass="doc">Help System</span></a> to create the help entry
for this command. You should decide on a way to format your help and stick to that.</p>
<p>The power of having commands as classes and to separate <codeclass="docutils literal notranslate"><spanclass="pre">parse()</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">func()</span></code>
lies in the ability to inherit functionality without having to parse every
command individually. For example, as mentioned the default commands all
inherit from <codeclass="docutils literal notranslate"><spanclass="pre">MuxCommand</span></code>. <codeclass="docutils literal notranslate"><spanclass="pre">MuxCommand</span></code> implements its own version of <codeclass="docutils literal notranslate"><spanclass="pre">parse()</span></code>
that understands all the specifics of MUX-like commands. Almost none of the
default commands thus need to implement <codeclass="docutils literal notranslate"><spanclass="pre">parse()</span></code> at all, but can assume the
incoming string is already split up and parsed in suitable ways by its parent.</p>
<p>Before you can actually use the command in your game, you must now store it
within a <em>command set</em>. See the <aclass="reference internal"href="Command-Sets.html"><spanclass="doc">Command Sets</span></a> page.</p>
</div>
<divclass="section"id="on-arg-regex">
<h3>On arg_regex<aclass="headerlink"href="#on-arg-regex"title="Permalink to this headline">¶</a></h3>
<p>The command parser is very general and does not require a space to end your command name. This means
that the alias <codeclass="docutils literal notranslate"><spanclass="pre">:</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">emote</span></code> can be used like <codeclass="docutils literal notranslate"><spanclass="pre">:smiles</span></code> without modification. It also means
<codeclass="docutils literal notranslate"><spanclass="pre">getstone</span></code> will get you the stone (unless there is a command specifically named <codeclass="docutils literal notranslate"><spanclass="pre">getstone</span></code>, then
that will be used). If you want to tell the parser to require a certain separator between the
command name and its arguments (so that <codeclass="docutils literal notranslate"><spanclass="pre">get</span><spanclass="pre">stone</span></code> works but <codeclass="docutils literal notranslate"><spanclass="pre">getstone</span></code> gives you a ‘command not
found’ error) you can do so with the <codeclass="docutils literal notranslate"><spanclass="pre">arg_regex</span></code> property.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">arg_regex</span></code> is a <aclass="reference external"href="http://docs.python.org/library/re.html">raw regular expression string</a>. The
regex will be compiled by the system at runtime. This allows you to customize how the part
<em>immediately following</em> the command name (or alias) must look in order for the parser to match for
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">commandname</span><spanclass="pre">argument</span></code> (<codeclass="docutils literal notranslate"><spanclass="pre">arg_regex</span><spanclass="pre">=</span><spanclass="pre">r"\s.+"</span></code>): This forces the parser to require the command name
to be followed by one or more spaces. Whatever is entered after the space will be treated as an
argument. However, if you’d forget the space (like a command having no arguments), this would <em>not</em>
match <codeclass="docutils literal notranslate"><spanclass="pre">commandname</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">commandname</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">commandname</span><spanclass="pre">argument</span></code> (<codeclass="docutils literal notranslate"><spanclass="pre">arg_regex</span><spanclass="pre">=</span><spanclass="pre">r"\s.+|$"</span></code>): This makes both <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code> and
<codeclass="docutils literal notranslate"><spanclass="pre">look</span><spanclass="pre">me</span></code> work but <codeclass="docutils literal notranslate"><spanclass="pre">lookme</span></code> will not.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">commandname/switches</span><spanclass="pre">arguments</span></code> (<codeclass="docutils literal notranslate"><spanclass="pre">arg_regex</span><spanclass="pre">=</span><spanclass="pre">r"(?:^(?:\s+|\/).*$)|^$"</span></code>. If you are using
Evennia’s <codeclass="docutils literal notranslate"><spanclass="pre">MuxCommand</span></code> Command parent, you may wish to use this since it will allow <codeclass="docutils literal notranslate"><spanclass="pre">/switche</span></code>s to
work as well as having or not having a space.</p></li>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">arg_regex</span></code> allows you to customize the behavior of your commands. You can put it in the parent
class of your command to customize all children of your Commands. However, you can also change the
base default behavior for all Commands by modifying <codeclass="docutils literal notranslate"><spanclass="pre">settings.COMMAND_DEFAULT_ARG_REGEX</span></code>.</p>
<p>Normally you just use <codeclass="docutils literal notranslate"><spanclass="pre">return</span></code> in one of your Command class’ hook methods to exit that method. That
will however still fire the other hook methods of the Command in sequence. That’s usually what you
want but sometimes it may be useful to just abort the command, for example if you find some
unacceptable input in your parse method. To exit the command this way you can raise
<p>Sometimes you want to pause the execution of your command for a little while before continuing -
maybe you want to simulate a heavy swing taking some time to finish, maybe you want the echo of your
voice to return to you with an ever-longer delay. Since Evennia is running asynchronously, you
cannot use <codeclass="docutils literal notranslate"><spanclass="pre">time.sleep()</span></code> in your commands (or anywhere, really). If you do, the <em>entire game</em> will
be frozen for everyone! So don’t do that. Fortunately, Evennia offers a really quick syntax for
making pauses in commands.</p>
<p>In your <codeclass="docutils literal notranslate"><spanclass="pre">func()</span></code> method, you can use the <codeclass="docutils literal notranslate"><spanclass="pre">yield</span></code> keyword. This is a Python keyword that will freeze
the current execution of your command and wait for more before processing.</p>
<div><p>Note that you <em>cannot</em> just drop <codeclass="docutils literal notranslate"><spanclass="pre">yield</span></code> into any code and expect it to pause. Evennia will only
pause for you if you <codeclass="docutils literal notranslate"><spanclass="pre">yield</span></code> inside the Command’s <codeclass="docutils literal notranslate"><spanclass="pre">func()</span></code> method. Don’t expect it to work anywhere
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"Starting to wait ..."</span><spanclass="p">)</span>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"... This shows after 5 seconds. Waiting ..."</span><spanclass="p">)</span>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"... And now another 2 seconds have passed."</span><spanclass="p">)</span>
<p>The important line is the <codeclass="docutils literal notranslate"><spanclass="pre">yield</span><spanclass="pre">5</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">yield</span><spanclass="pre">2</span></code> lines. It will tell Evennia to pause execution
here and not continue until the number of seconds given has passed.</p>
<p>There are two things to remember when using <codeclass="docutils literal notranslate"><spanclass="pre">yield</span></code> in your Command’s <codeclass="docutils literal notranslate"><spanclass="pre">func</span></code> method:</p>
<li><p>The paused state produced by the <codeclass="docutils literal notranslate"><spanclass="pre">yield</span></code> is not saved anywhere. So if the server reloads in the
middle of your command pausing, it will <em>not</em> resume when the server comes back up - the remainder
of the command will never fire. So be careful that you are not freezing the character or account in
a way that will not be cleared on reload.</p></li>
<li><p>If you use <codeclass="docutils literal notranslate"><spanclass="pre">yield</span></code> you may not also use <codeclass="docutils literal notranslate"><spanclass="pre">return</span><spanclass="pre"><values></span></code> in your <codeclass="docutils literal notranslate"><spanclass="pre">func</span></code> method. You’ll get an
error explaining this. This is due to how Python generators work. You can however use a “naked”
<codeclass="docutils literal notranslate"><spanclass="pre">return</span></code> just fine. Usually there is no need for <codeclass="docutils literal notranslate"><spanclass="pre">func</span></code> to return a value, but if you ever do need
to mix <codeclass="docutils literal notranslate"><spanclass="pre">yield</span></code> with a final return value in the same <codeclass="docutils literal notranslate"><spanclass="pre">func</span></code>, look at
<spanclass="n">answer</span><spanclass="o">=</span><spanclass="k">yield</span><spanclass="p">(</span><spanclass="s2">"Are you sure you want to go on?"</span><spanclass="p">)</span>
<div><p>Note again that the <codeclass="docutils literal notranslate"><spanclass="pre">yield</span></code> keyword does not store state. If the game reloads while waiting for
the user to answer, the user will have to start over. It is not a good idea to use <codeclass="docutils literal notranslate"><spanclass="pre">yield</span></code> for
important or complex choices, a persistent <aclass="reference internal"href="EvMenu.html"><spanclass="doc">EvMenu</span></a> might be more appropriate in this case.</p>
<p>There are several command-situations that are exceptional in the eyes of the server. What happens if
the account enters an empty string? What if the ‘command’ given is infact the name of a channel the
user wants to send a message to? Or if there are multiple command possibilities?</p>
<p>Such ‘special cases’ are handled by what’s called <em>system commands</em>. A system command is defined
in the same way as other commands, except that their name (key) must be set to one reserved by the
engine (the names are defined at the top of <codeclass="docutils literal notranslate"><spanclass="pre">evennia/commands/cmdhandler.py</span></code>). You can find (unused)
implementations of the system commands in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/commands/default/system_commands.py</span></code>. Since these
are not (by default) included in any <codeclass="docutils literal notranslate"><spanclass="pre">CmdSet</span></code> they are not actually used, they are just there for
show. When the special situation occurs, Evennia will look through all valid <codeclass="docutils literal notranslate"><spanclass="pre">CmdSet</span></code>s for your
custom system command. Only after that will it resort to its own, hard-coded implementation.</p>
<p>Here are the exceptional situations that triggers system commands. You can find the command keys
they use as properties on <codeclass="docutils literal notranslate"><spanclass="pre">evennia.syscmdkeys</span></code>:</p>
<li><p>No input (<codeclass="docutils literal notranslate"><spanclass="pre">syscmdkeys.CMD_NOINPUT</span></code>) - the account just pressed return without any input. Default
is to do nothing, but it can be useful to do something here for certain implementations such as line
editors that interpret non-commands as text input (an empty line in the editing buffer).</p></li>
<li><p>Command not found (<codeclass="docutils literal notranslate"><spanclass="pre">syscmdkeys.CMD_NOMATCH</span></code>) - No matching command was found. Default is to
display the “Huh?” error message.</p></li>
<li><p>Several matching commands where found (<codeclass="docutils literal notranslate"><spanclass="pre">syscmdkeys.CMD_MULTIMATCH</span></code>) - Default is to show a list of
matches.</p></li>
<li><p>User is not allowed to execute the command (<codeclass="docutils literal notranslate"><spanclass="pre">syscmdkeys.CMD_NOPERM</span></code>) - Default is to display the
“Huh?” error message.</p></li>
<li><p>Channel (<codeclass="docutils literal notranslate"><spanclass="pre">syscmdkeys.CMD_CHANNEL</span></code>) - This is a <aclass="reference internal"href="Communications.html"><spanclass="doc">Channel</span></a> name of a channel you are
subscribing to - Default is to relay the command’s argument to that channel. Such commands are
created by the Comm system on the fly depending on your subscriptions.</p></li>
<li><p>New session connection (<codeclass="docutils literal notranslate"><spanclass="pre">syscmdkeys.CMD_LOGINSTART</span></code>). This command name should be put in the
<codeclass="docutils literal notranslate"><spanclass="pre">settings.CMDSET_UNLOGGEDIN</span></code>. Whenever a new connection is established, this command is always
called on the server (default is to show the login screen).</p></li>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"Don't just press return like that, talk to me!"</span><spanclass="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
<divclass="section"id="dynamic-commands">
<h2>Dynamic Commands<aclass="headerlink"href="#dynamic-commands"title="Permalink to this headline">¶</a></h2>
<p>To create a command with a dynamic call signature, first define the command body normally in a class
(set your <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">aliases</span></code> to default values), then use the following call (assuming the command
class you created is named <codeclass="docutils literal notranslate"><spanclass="pre">MyCommand</span></code>):</p>
<p><em>All</em> keyword arguments you give to the Command constructor will be stored as a property on the
command object. This will overload existing properties defined on the parent class.</p>
<p>Normally you would define your class and only overload things like <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">aliases</span></code> at run-time.
But you could in principle also send method objects (like <codeclass="docutils literal notranslate"><spanclass="pre">func</span></code>) as keyword arguments in order to
make your command completely customized at run-time.</p>
<p>The functionality of <aclass="reference internal"href="Objects.html"><spanclass="doc">Exit</span></a> objects in Evennia is not hard-coded in the engine. Instead
Exits are normal <aclass="reference internal"href="Typeclasses.html"><spanclass="doc">typeclassed</span></a> objects that auto-create a <aclass="reference external"href="Components/Commands.html#CmdSets">CmdSet</a> on
themselves when they load. This cmdset has a single dynamically created Command with the same
properties (key, aliases and locks) as the Exit object itself. When entering the name of the exit,
this dynamic exit-command is triggered and (after access checks) moves the Character to the exit’s
destination.
Whereas you could customize the Exit object and its command to achieve completely different
behaviour, you will usually be fine just using the appropriate <codeclass="docutils literal notranslate"><spanclass="pre">traverse_*</span></code> hooks on the Exit
object. But if you are interested in really changing how things work under the hood, check out
<codeclass="docutils literal notranslate"><spanclass="pre">evennia/objects/objects.py</span></code> for how the <codeclass="docutils literal notranslate"><spanclass="pre">Exit</span></code> typeclass is set up.</p>
<p>Note how the in-memory address of the <codeclass="docutils literal notranslate"><spanclass="pre">testid</span></code> command never changes, but <codeclass="docutils literal notranslate"><spanclass="pre">xval</span></code> keeps ticking up.</p>
<p>This will start the <codeclass="docutils literal notranslate"><spanclass="pre">MyCommand</span></code> with <codeclass="docutils literal notranslate"><spanclass="pre">myvar</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">foo</span></code> set as properties (accessable as <codeclass="docutils literal notranslate"><spanclass="pre">self.myvar</span></code>
and <codeclass="docutils literal notranslate"><spanclass="pre">self.foo</span></code>). How they are used is up to the Command. Remember however the discussion from the
previous section - since the Command instance is re-used, those properties will <em>remain</em> on the
command as long as this cmdset and the object it sits is in memory (i.e. until the next reload).
Unless <codeclass="docutils literal notranslate"><spanclass="pre">myvar</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">foo</span></code> are somehow reset when the command runs, they can be modified and that
change will be remembered for subsequent uses of the command.</p>
<li><p>The user’s Session determines the text is not some protocol-specific control sequence or OOB
command, but sends it on to the command handler.</p></li>
<li><p>Evennia’s <em>command handler</em> analyzes the Session and grabs eventual references to Account and
eventual puppeted Characters (these will be stored on the command object later). The <em>caller</em>
property is set appropriately.</p></li>
<li><p>If input is an empty string, resend command as <codeclass="docutils literal notranslate"><spanclass="pre">CMD_NOINPUT</span></code>. If no such command is found in
<li><p>If multiple matches were returned, resend as <codeclass="docutils literal notranslate"><spanclass="pre">CMD_MULTIMATCH</span></code>. If no such command is found in
cmdset, return hard-coded list of matches.</p></li>
<li><p>If no match was found, resend as <codeclass="docutils literal notranslate"><spanclass="pre">CMD_NOMATCH</span></code>. If no such command is found in cmdset, give
<li><p>If a single command was found by the parser, the correct command object is plucked out of
storage. This usually doesn’t mean a re-initialization.</p></li>
<li><p>It is checked that the caller actually has access to the command by validating the <em>lockstring</em>
of the command. If not, it is not considered as a suitable match and <codeclass="docutils literal notranslate"><spanclass="pre">CMD_NOMATCH</span></code> is triggered.</p></li>
<li><p>If the new command is tagged as a channel-command, resend as <codeclass="docutils literal notranslate"><spanclass="pre">CMD_CHANNEL</span></code>. If no such command
is found in cmdset, use hard-coded implementation.</p></li>
<li><p>Call <codeclass="docutils literal notranslate"><spanclass="pre">parse()</span></code> on the command instance. This is fed the remainder of the string, after the name
of the command. It’s intended to pre-parse the string into a form useful for the <codeclass="docutils literal notranslate"><spanclass="pre">func()</span></code> method.</p></li>
<li><p>Call <codeclass="docutils literal notranslate"><spanclass="pre">func()</span></code> on the command instance. This is the functional body of the command, actually
<spanclass="n">caller</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"Returned is </span><spanclass="si">%s</span><spanclass="s2">"</span><spanclass="o">%</span><spanclass="n">ret</span><spanclass="p">)</span>
<p>This is probably not relevant to any but the most advanced/exotic designs (one might use it to
create a “nested” command structure for example).</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">save_for_next</span></code> class variable can be used to implement state-persistent commands. For example
it can make a command operate on “it”, where it is determined by what the previous command operated
<li><aclass="reference internal"href="#who-is-calling-the-command">Who is calling the command?</a></li>
<li><aclass="reference internal"href="#properties-assigned-to-the-command-instance-at-run-time">Properties assigned to the command instance at run-time</a><ul>
