<h1>Building Quickstart<aclass="headerlink"href="#building-quickstart"title="Permalink to this headline">¶</a></h1>
<p>The <aclass="reference internal"href="Default-Command-Help.html"><spanclass="doc">default command</span></a> definitions coming with Evennia
follows a style <aclass="reference internal"href="Using-MUX-as-a-Standard.html"><spanclass="doc">similar</span></a> to that of MUX, so the
commands should be familiar if you used any such code bases before.</p>
<blockquote>
<div><p>Throughout the larger documentation you may come across commands prefixed
with <codeclass="docutils literal notranslate"><spanclass="pre">@</span></code>. This is just an optional marker used in some places to make a
command stand out. Evennia defaults to ignoring the use of <codeclass="docutils literal notranslate"><spanclass="pre">@</span></code> in front of
your command (so entering <codeclass="docutils literal notranslate"><spanclass="pre">dig</span></code> is the same as entering <codeclass="docutils literal notranslate"><spanclass="pre">@dig</span></code>).</p>
</div></blockquote>
<p>The default commands have the following style (where <codeclass="docutils literal notranslate"><spanclass="pre">[...]</span></code> marks optional parts):</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>
<p>Below are some examples of commands you can try when logged in to the game. Use <codeclass="docutils literal notranslate"><spanclass="pre">help</span><spanclass="pre"><command></span></code> for learning more about each command and their detailed options.</p>
<h2>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>This will make you start using the permission of your current character’s level instead of your superuser level. If you didn’t change any settings your game Character should have an <em>Developer</em> level permission - high as can be without bypassing locks like the superuser does. This will work fine for the examples on this page. Use <codeclass="docutils literal notranslate"><spanclass="pre">unquell</span></code> to get back to superuser status again afterwards.</p>
</div>
<divclass="section"id="creating-an-object">
<h2>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>
<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>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 dropped in the room, then try this:</p>
<p>Locks represent a rather <aclass="reference internal"href="Locks.html"><spanclass="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>
<spanclass="n">You</span><spanclass="n">can</span><spanclass="s1">'t get that.</span>
</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="Attributes.html"><spanclass="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-default notranslate"><divclass="highlight"><pre><span></span><spanclass="nb">set</span><spanclass="n">box</span><spanclass="o">/</span><spanclass="n">get_err_msg</span><spanclass="o">=</span><spanclass="n">It</span><spanclass="s1">'s way too heavy for you to lift. </span>
</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. See the <aclass="reference internal"href="Adding-Command-Tutorial.html"><spanclass="doc">Adding Commands tutorial</span></a> for help with creating your first own Command.</p>
</div>
<divclass="section"id="get-a-personality">
<h2>Get a Personality<aclass="headerlink"href="#get-a-personality"title="Permalink to this headline">¶</a></h2>
<p><aclass="reference internal"href="Scripts.html"><spanclass="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/tutorial_examples/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>(note that you don’t have to give the full path as long as you are pointing to a place inside the <codeclass="docutils literal notranslate"><spanclass="pre">contrib</span></code> directory, it’s one of the places Evennia looks for Scripts). 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="Scripts.html"><spanclass="doc">Scripts</span></a> page explains more details.</p>
</div>
<divclass="section"id="pushing-your-buttons">
<h2>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 do 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="Typeclasses.html"><spanclass="doc">Typeclasses</span></a>, <aclass="reference internal"href="Scripts.html"><spanclass="doc">Scripts</span></a> and object-based <aclass="reference internal"href="Commands.html"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">RedButton</span></code> typeclass.</p>
<p>We import the RedButton python class the same way you would import it in Python except Evennia makes sure to look in<codeclass="docutils literal notranslate"><spanclass="pre">evennia/contrib/</span></code> so you don’t have to write the full path every time. 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="Typeclasses.html"><spanclass="doc">Typeclass</span></a> and <aclass="reference internal"href="Commands.html"><spanclass="doc">Commands</span></a> controlling it are inside <codeclass="docutils literal notranslate"><spanclass="pre">evennia/contrib/tutorial_examples/</span></code>.</p>
<p>If you wait for a while (make sure you dropped it!) the button will blink invitingly. Why don’t you try to push it …? Surely a big red button is meant to be pushed. You know you want to.</p>
</div>
<divclass="section"id="making-yourself-a-house">
<h2>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>
<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>
<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. You can also give its database (#dbref) number, which is unique to every object. This can be found with the <codeclass="docutils literal notranslate"><spanclass="pre">examine</span></code> command or by looking at the latest constructions with <codeclass="docutils literal notranslate"><spanclass="pre">objects</span></code>.</p>
<p>Follow the north exit to your ‘house’ or <codeclass="docutils literal notranslate"><spanclass="pre">teleport</span></code> to it:</p>
<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>
<h2>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 to our house</em>.</p>
<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>
<p>(You can usually use <codeclass="docutils literal notranslate"><spanclass="pre">here</span></code> to refer to your current location. To refer to yourself you can use <codeclass="docutils literal notranslate"><spanclass="pre">self</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code>). 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>You can destroy many objects in one go by giving a comma-separated list of objects (or their #dbrefs, if they are not in the same location) to the command.</p>
</div>
<divclass="section"id="adding-a-help-entry">
<h2>Adding a Help Entry<aclass="headerlink"href="#adding-a-help-entry"title="Permalink to this headline">¶</a></h2>
<p>An important part of building is keeping the help files updated. You can add, delete and append to existing help entries using the <codeclass="docutils literal notranslate"><spanclass="pre">sethelp</span></code> command.</p>
<h2>Adding a World<aclass="headerlink"href="#adding-a-world"title="Permalink to this headline">¶</a></h2>
<p>After this brief introduction to building you may be ready to see a more fleshed-out example. Evennia comes with a tutorial world for you to explore.</p>
<p>First you need to switch back to <em>superuser</em> by using the <codeclass="docutils literal notranslate"><spanclass="pre">unquell</span></code> command. Next, place yourself in <codeclass="docutils literal notranslate"><spanclass="pre">Limbo</span></code> and run the following command:</p>
<p>This will take a while (be patient and don’t re-run the command). You will see all the commands used to build the world scroll by as the world is built for you.</p>
<p>You will end up with a new exit from Limbo named <em>tutorial</em>. Apart from being a little solo-adventure in its own right, the tutorial world is a good source for learning Evennia building (and coding).</p>
<p>Read <aclass="reference external"href="https://github.com/evennia/evennia/blob/master/evennia/contrib/tutorial_world/build.ev">the batch file</a> to see exactly how it’s built, step by step. See also more info about the tutorial world <aclass="reference internal"href="Tutorial-World-Introduction.html"><spanclass="doc">here</span></a>.</p>
