<h1><spanclass="section-number">1. </span>Using commands and building stuff<aclass="headerlink"href="#using-commands-and-building-stuff"title="Permalink to this headline">¶</a></h1>
<p>In this lesson we will test out what we can do in-game out-of-the-box. Evennia ships with
<aclass="reference internal"href="../../../Components/Default-Commands.html"><spanclass="doc std std-doc">around 90 default commands</span></a>, and while you can override those as you please,
they can be quite useful.</p>
<p>Connect and log into your new game and you will end up in the “Limbo” location. This
is the only room in the game at this point. Let’s explore the commands a little.</p>
<p>The default commands has syntax <aclass="reference internal"href="../../../Concepts/Using-MUX-as-a-Standard.html"><spanclass="doc std std-doc">similar to MUX</span></a>:</p>
<p>A <em>/switch</em> is a special, optional flag to the command to make it behave differently. It is always
put directly after the command name, and begins with a forward slash (<codeclass="docutils literal notranslate"><spanclass="pre">/</span></code>). The <em>arguments</em> are one
or more inputs to the commands. It’s common to use an equal sign (<codeclass="docutils literal notranslate"><spanclass="pre">=</span></code>) when assigning something to
an object.</p>
<blockquote>
<div><p>Are you used to commands starting with @, like @create? That will work too. Evennia simply ignores
the preceeding @.</p>
</div></blockquote>
<sectionid="getting-help">
<h2><spanclass="section-number">1.1. </span>Getting help<aclass="headerlink"href="#getting-help"title="Permalink to this headline">¶</a></h2>
<p>This will show you the description of the current location. <codeclass="docutils literal notranslate"><spanclass="pre">l</span></code> is an alias.</p>
<p>When targeting objects in commands you have two special labels you can use, <codeclass="docutils literal notranslate"><spanclass="pre">here</span></code> for the current
room or <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code>/<codeclass="docutils literal notranslate"><spanclass="pre">self</span></code> to point back to yourself. So</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>look me
</pre></div>
</div>
<p>will give you your own description. <codeclass="docutils literal notranslate"><spanclass="pre">look</span><spanclass="pre">here</span></code> is, in this case, the same as plain <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code>.</p>
</section>
<sectionid="stepping-down-from-godhood">
<h2><spanclass="section-number">1.3. </span>Stepping Down From Godhood<aclass="headerlink"href="#stepping-down-from-godhood"title="Permalink to this headline">¶</a></h2>
<p>If you just installed Evennia, your very first player account is called user #1, also known as the
<em>superuser</em> or <em>god user</em>. This user is very powerful, so powerful that it will override many game
restrictions such as locks. This can be useful, but it also hides some functionality that you might
want to test.</p>
<p>To temporarily step down from your superuser position you can use the <codeclass="docutils literal notranslate"><spanclass="pre">quell</span></code> command in-game:</p>
<p>to get superuser status again when you are done.</p>
</section>
<sectionid="creating-an-object">
<h2><spanclass="section-number">1.4. </span>Creating an Object<aclass="headerlink"href="#creating-an-object"title="Permalink to this headline">¶</a></h2>
<p>Basic objects can be anything – swords, flowers and non-player characters. They are created using
the <codeclass="docutils literal notranslate"><spanclass="pre">create</span></code> command:</p>
<p>This created a new ‘box’ (of the default object type) in your inventory. Use the command <codeclass="docutils literal notranslate"><spanclass="pre">inventory</span></code>
(or <codeclass="docutils literal notranslate"><spanclass="pre">i</span></code>) to see it. Now, ‘box’ is a rather short name, let’s rename it and tack on a few aliases.</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>name box = very large box;box;very;crate
</pre></div>
</div>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>MUD clients and semi-colon
Some traditional MUD clients use the semi-colon <codeclass="docutils literal notranslate"><spanclass="pre">;</span></code> to separate client inputs. If so,
the above line will give an error. You need to change your client to use another command-separator
or to put it in ‘verbatim’ mode. If you still have trouble, use the Evennia web client instead.</p>
</div>
<p>We now renamed the box to <em>very large box</em> (and this is what we will see when looking at it), but we
will also recognize it by any of the other names we give - like <em>crate</em> or simply <em>box</em> as before.
We could have given these aliases directly after the name in the <codeclass="docutils literal notranslate"><spanclass="pre">create</span></code> command, this is true for
all creation commands - you can always tag on a list of <codeclass="docutils literal notranslate"><spanclass="pre">;</span></code>-separated aliases to the name of your
new object. If you had wanted to not change the name itself, but to only add aliases, you could have
used the <codeclass="docutils literal notranslate"><spanclass="pre">alias</span></code> command.</p>
<p>We are currently carrying the box. Let’s drop it (there is also a short cut to create and drop in
one go by using the <codeclass="docutils literal notranslate"><spanclass="pre">/drop</span></code> switch, for example <codeclass="docutils literal notranslate"><spanclass="pre">create/drop</span><spanclass="pre">box</span></code>).</p>
<p>The description you get is not very exciting. Let’s add some flavor.</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>desc box = This is a large and very heavy box.
</pre></div>
</div>
<p>If you try the <codeclass="docutils literal notranslate"><spanclass="pre">get</span></code> command we will pick up the box. So far so good, but if we really want this to
be a large and heavy box, people should <em>not</em> be able to run off with it that easily. To prevent
this we need to lock it down. This is done by assigning a <em>Lock</em> to it. Make sure the box was
<p>Locks represent a rather <aclass="reference internal"href="../../../Components/Locks.html"><spanclass="doc std std-doc">big topic</span></a>, but for now that will do what we want. This will lock
the box so noone can lift it. The exception is superusers, they override all locks and will pick it
up anyway. Make sure you are quelling your superuser powers and try to get the box now:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>> get box
You can't get that.
</pre></div>
</div>
<p>Think thís default error message looks dull? The <codeclass="docutils literal notranslate"><spanclass="pre">get</span></code> command looks for an <aclass="reference internal"href="../../../Components/Attributes.html"><spanclass="doc std std-doc">Attribute</span></a>
named <codeclass="docutils literal notranslate"><spanclass="pre">get_err_msg</span></code> for returning a nicer error message (we just happen to know this, you would need
to peek into the
<aclass="reference external"href="https://github.com/evennia/evennia/blob/master/evennia/commands/default/general.py#L235">code</a> for
the <codeclass="docutils literal notranslate"><spanclass="pre">get</span></code> command to find out.). You set attributes using the <codeclass="docutils literal notranslate"><spanclass="pre">set</span></code> command:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>set box/get_err_msg = It's way too heavy for you to lift.
</pre></div>
</div>
<p>Try to get it now and you should see a nicer error message echoed back to you. To see what this
message string is in the future, you can use ‘examine.’</p>
<p>Examine will return the value of attributes, including color codes. <codeclass="docutils literal notranslate"><spanclass="pre">examine</span><spanclass="pre">here/desc</span></code> would return
the raw description of your current room (including color codes), so that you can copy-and-paste to
set its description to something else.</p>
<p>You create new Commands (or modify existing ones) in Python outside the game. We will get to that
later, in the <aclass="reference internal"href="Beginner-Tutorial-Adding-Commands.html"><spanclass="doc std std-doc">Commands tutorial</span></a>.</p>
</section>
<sectionid="get-a-personality">
<h2><spanclass="section-number">1.5. </span>Get a Personality<aclass="headerlink"href="#get-a-personality"title="Permalink to this headline">¶</a></h2>
<p><aclass="reference internal"href="../../../Components/Scripts.html"><spanclass="doc std std-doc">Scripts</span></a> are powerful out-of-character objects useful for many “under the hood” things.
One of their optional abilities is to do things on a timer. To try out a first script, let’s put one
on ourselves. There is an example script in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/contrib/tutorials/bodyfunctions/bodyfunctions.py</span></code>
that is called <codeclass="docutils literal notranslate"><spanclass="pre">BodyFunctions</span></code>. To add this to us we will use the <codeclass="docutils literal notranslate"><spanclass="pre">script</span></code> command:</p>
<p>This string will tell Evennia to dig up the Python code at the place we indicate. It already knows
to look in the <codeclass="docutils literal notranslate"><spanclass="pre">contrib/</span></code> folder, so we don’t have to give the full path.</p>
<blockquote>
<div><p>Note also how we use <codeclass="docutils literal notranslate"><spanclass="pre">.</span></code> instead of <codeclass="docutils literal notranslate"><spanclass="pre">/</span></code> (or <codeclass="docutils literal notranslate"><spanclass="pre">\</span></code> on Windows). This is a so-called “Python path”. In a Python-path,
you separate the parts of the path with <codeclass="docutils literal notranslate"><spanclass="pre">.</span></code> and skip the <codeclass="docutils literal notranslate"><spanclass="pre">.py</span></code> file-ending. Importantly, it also allows you to point to
Python code <em>inside</em> files, like the <codeclass="docutils literal notranslate"><spanclass="pre">BodyFunctions</span></code> class inside <codeclass="docutils literal notranslate"><spanclass="pre">bodyfunctions.py</span></code> (we’ll get to classes later).
These “Python-paths” are used extensively throughout Evennia.</p>
</div></blockquote>
<p>Wait a while and you will notice yourself starting making random observations …</p>
<p>This will show details about scripts on yourself (also <codeclass="docutils literal notranslate"><spanclass="pre">examine</span></code> works). You will see how long it is
until it “fires” next. Don’t be alarmed if nothing happens when the countdown reaches zero - this
particular script has a randomizer to determine if it will say something or not. So you will not see
output every time it fires.</p>
<p>When you are tired of your character’s “insights”, kill the script with</p>
<p>You create your own scripts in Python, outside the game; the path you give to <codeclass="docutils literal notranslate"><spanclass="pre">script</span></code> is literally
the Python path to your script file. The <aclass="reference internal"href="../../../Components/Scripts.html"><spanclass="doc std std-doc">Scripts</span></a> page explains more details.</p>
</section>
<sectionid="pushing-your-buttons">
<h2><spanclass="section-number">1.6. </span>Pushing Your Buttons<aclass="headerlink"href="#pushing-your-buttons"title="Permalink to this headline">¶</a></h2>
<p>If we get back to the box we made, there is only so much fun you can have with it at this point. It’s
just a dumb generic object. If you renamed it to <codeclass="docutils literal notranslate"><spanclass="pre">stone</span></code> and changed its description, noone would be
the wiser. However, with the combined use of custom <aclass="reference internal"href="../../../Components/Typeclasses.html"><spanclass="doc std std-doc">Typeclasses</span></a>, <aclass="reference internal"href="../../../Components/Scripts.html"><spanclass="doc std std-doc">Scripts</span></a>
and object-based <aclass="reference internal"href="../../../Components/Commands.html"><spanclass="doc std std-doc">Commands</span></a>, you could expand it and other items to be as unique, complex
and interactive as you want.</p>
<p>Let’s take an example. So far we have only created objects that use the default object typeclass
named simply <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code>. Let’s create an object that is a little more interesting. Under
<codeclass="docutils literal notranslate"><spanclass="pre">evennia/contrib/tutorial_examples</span></code> there is a module <codeclass="docutils literal notranslate"><spanclass="pre">red_button.py</span></code>. It contains the enigmatic
<p>The same way we did with the Script Earler, we specify a “Python-path” to the Python code we want Evennia
to use for creating the object. There you go - one red button.</p>
<p>The RedButton is an example object intended to show off a few of Evennia’s features. You will find
that the <aclass="reference internal"href="../../../Components/Typeclasses.html"><spanclass="doc std std-doc">Typeclass</span></a> and <aclass="reference internal"href="../../../Components/Commands.html"><spanclass="doc std std-doc">Commands</span></a> controlling it are
<p>If you wait for a while (make sure you dropped it!) the button will blink invitingly.</p>
<p>Why don’t you try to push it …?</p>
<p>Surely a big red button is meant to be pushed.</p>
<p>You know you want to.</p>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>Don’t press the invitingly blinking red button.</p>
</div>
</section>
<sectionid="making-yourself-a-house">
<h2><spanclass="section-number">1.7. </span>Making Yourself a House<aclass="headerlink"href="#making-yourself-a-house"title="Permalink to this headline">¶</a></h2>
<p>The main command for shaping the game world is <codeclass="docutils literal notranslate"><spanclass="pre">dig</span></code>. For example, if you are standing in Limbo you
can dig a route to your new house location like this:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>dig house = large red door;door;in,to the outside;out
</pre></div>
</div>
<p>This will create a new room named ‘house’. Spaces at the start/end of names and aliases are ignored
so you could put more air if you wanted. This call will directly create an exit from your current
location named ‘large red door’ and a corresponding exit named ‘to the outside’ in the house room
leading back to Limbo. We also define a few aliases to those exits, so people don’t have to write
the full thing all the time.</p>
<p>If you wanted to use normal compass directions (north, west, southwest etc), you could do that with
<codeclass="docutils literal notranslate"><spanclass="pre">dig</span></code> too. But Evennia also has a limited version of <codeclass="docutils literal notranslate"><spanclass="pre">dig</span></code> that helps for compass directions (and
also up/down and in/out). It’s called <codeclass="docutils literal notranslate"><spanclass="pre">tunnel</span></code>:</p>
<p>This will create a new room “cliff” with an exit “southwest” leading there and a path “northeast”
leading back from the cliff to your current location.</p>
<p>You can create new exits from where you are, using the <codeclass="docutils literal notranslate"><spanclass="pre">open</span></code> command:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>open north;n = house
</pre></div>
</div>
<p>This opens an exit <codeclass="docutils literal notranslate"><spanclass="pre">north</span></code> (with an alias <codeclass="docutils literal notranslate"><spanclass="pre">n</span></code>) to the previously created room <codeclass="docutils literal notranslate"><spanclass="pre">house</span></code>.</p>
<p>If you have many rooms named <codeclass="docutils literal notranslate"><spanclass="pre">house</span></code> you will get a list of matches and have to select which one you
want to link to.</p>
<p>Follow the north exit to your ‘house’ or <codeclass="docutils literal notranslate"><spanclass="pre">teleport</span></code> to it:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>teleport house
</pre></div>
</div>
<p>To manually open an exit back to Limbo (if you didn’t do so with the <codeclass="docutils literal notranslate"><spanclass="pre">dig</span></code> command):</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>open door = limbo
</pre></div>
</div>
<p>(You can also us the #dbref of limbo, which you can find by using <codeclass="docutils literal notranslate"><spanclass="pre">examine</span><spanclass="pre">here</span></code> when in limbo).</p>
</section>
<sectionid="reshuffling-the-world">
<h2><spanclass="section-number">1.8. </span>Reshuffling the World<aclass="headerlink"href="#reshuffling-the-world"title="Permalink to this headline">¶</a></h2>
<p>You can find things using the <codeclass="docutils literal notranslate"><spanclass="pre">find</span></code> command. Assuming you are back at <codeclass="docutils literal notranslate"><spanclass="pre">Limbo</span></code>, let’s teleport the
<em>large box</em> to our house.</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>teleport box = house
very large box is leaving Limbo, heading for house.
<p>Knowing the <codeclass="docutils literal notranslate"><spanclass="pre">#dbref</span></code> of the box (#8 in this example), you can grab the box and get it back here
without actually yourself going to <codeclass="docutils literal notranslate"><spanclass="pre">house</span></code> first:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>teleport #8 = here
</pre></div>
</div>
<p>As mentioned, <codeclass="docutils literal notranslate"><spanclass="pre">here</span></code> is an alias for ‘your current location’. The box should now be back in Limbo with you.</p>
<p>We are getting tired of the box. Let’s destroy it.</p>
<p>It will ask you for confirmation. Once you give it, the box will be gone.</p>
<p>You can destroy many objects in one go by giving a comma-separated list of objects (or a range
of #dbrefs, if they are not in the same location) to the command.</p>
</section>
<sectionid="adding-a-help-entry">
<h2><spanclass="section-number">1.9. </span>Adding a Help Entry<aclass="headerlink"href="#adding-a-help-entry"title="Permalink to this headline">¶</a></h2>
<p>The Command-help is something you modify in Python code. We’ll get to that when we get to how to
add Commands. But you can also add regular help entries, for example to explain something about
the history of your game world:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>sethelp History = At the dawn of time ...
</pre></div>
</div>
<p>You will now find your new <codeclass="docutils literal notranslate"><spanclass="pre">History</span></code> entry in the <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> list and read your help-text with <codeclass="docutils literal notranslate"><spanclass="pre">help</span><spanclass="pre">History</span></code>.</p>
</section>
<sectionid="adding-a-world">
<h2><spanclass="section-number">1.10. </span>Adding a World<aclass="headerlink"href="#adding-a-world"title="Permalink to this headline">¶</a></h2>
<p>After this brief introduction to building and using in-game commands you may be ready to see a more fleshed-out
example. Evennia comes with a tutorial world for you to explore. We will try that out in the next lesson.</p>
