<p>This quickstart assumes you have <aclass="reference internal"href="Getting-Started.html"><spanclass="doc">gotten Evennia started</span></a>. You should make sure
that you are able to see the output from the server in the console from which you started it. Log
into the game either with a mud client on <codeclass="docutils literal notranslate"><spanclass="pre">localhost:4000</span></code> or by pointing a web browser to
<codeclass="docutils literal notranslate"><spanclass="pre">localhost:4001/webclient</span></code>. Log in as your superuser (the user you created during install).</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> (or <codeclass="docutils literal notranslate"><spanclass="pre">!</span></code> which is an alias) command allows you as a superuser to run raw Python from in-
game. From the game’s input line, enter the following:</p>
<p>To understand what is going on: some extra info: The <codeclass="docutils literal notranslate"><spanclass="pre">print(...)</span></code><em>function</em> is the basic, in-built
way to output text in Python. The quotes <codeclass="docutils literal notranslate"><spanclass="pre">"..."</span></code> means you are inputing a <em>string</em> (i.e. text). You
could also have used single-quotes <codeclass="docutils literal notranslate"><spanclass="pre">'...'</span></code>, Python accepts both.</p>
<p>The first return line (with <codeclass="docutils literal notranslate"><spanclass="pre">>>></span></code>) is just <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> echoing what you input (we won’t include that in the
<div><p>Note: You may sometimes see people/docs refer to <codeclass="docutils literal notranslate"><spanclass="pre">@py</span></code> or other commands starting with <codeclass="docutils literal notranslate"><spanclass="pre">@</span></code>.
Evennia ignores <codeclass="docutils literal notranslate"><spanclass="pre">@</span></code> by default, so <codeclass="docutils literal notranslate"><spanclass="pre">@py</span></code> is the exact same thing as <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code>.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">print</span></code> command is a standard Python structure. We can use that here in the <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> command, and
it’s great for debugging and quick testing. But if you need to send a text to an actual player,
<codeclass="docutils literal notranslate"><spanclass="pre">print</span></code> won’t do, because it doesn’t know <em>who</em> to send to. Try this:</p>
<p>This looks the same as the <codeclass="docutils literal notranslate"><spanclass="pre">print</span></code> result, but we are now actually messaging a specific <em>object</em>,
<codeclass="docutils literal notranslate"><spanclass="pre">me</span></code>. The <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> is something uniquely available in the <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> command (we could also use <codeclass="docutils literal notranslate"><spanclass="pre">self</span></code>, it’s
an alias). It represents “us”, the ones calling the <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> command. The <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> is an example of an
<em>Object instance</em>. Objects are fundamental in Python and Evennia. The <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> object not only
represents the character we play in the game, it also contains a lot of useful resources for doing
things with that Object. One such resource is <codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code>. <codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code> works like <codeclass="docutils literal notranslate"><spanclass="pre">print</span></code> except it sends the
text to the object it is attached to. So if we, for example, had an object <codeclass="docutils literal notranslate"><spanclass="pre">you</span></code>, doing
<codeclass="docutils literal notranslate"><spanclass="pre">you.msg(...)</span></code> would send a message to the object <codeclass="docutils literal notranslate"><spanclass="pre">you</span></code>.</p>
<p>You access an Object’s resources by using the full-stop character <codeclass="docutils literal notranslate"><spanclass="pre">.</span></code>. So <codeclass="docutils literal notranslate"><spanclass="pre">self.msg</span></code> accesses the
<codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code> resource and then we call it like we did print, with our “Hello World!” greeting in
<div><p>Important: something like <codeclass="docutils literal notranslate"><spanclass="pre">print(...)</span></code> we refer to as a <em>function</em>, while <codeclass="docutils literal notranslate"><spanclass="pre">msg(...)</span></code> which sits on
<p>For now, <codeclass="docutils literal notranslate"><spanclass="pre">print</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">me.msg</span></code> behaves the same, just remember that you’re going to mostly be using
the latter in the future. Try printing other things. Also try to include <codeclass="docutils literal notranslate"><spanclass="pre">|r</span></code> at the start of your
string to make the output red in-game. Use <codeclass="docutils literal notranslate"><spanclass="pre">color</span></code> to learn more color tags.</p>
<p>Keep your game running, then open a text editor of your choice. If your game folder is called
<codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code>, create a new text file <codeclass="docutils literal notranslate"><spanclass="pre">test.py</span></code> in the subfolder <codeclass="docutils literal notranslate"><spanclass="pre">mygame/world</span></code>. This is how the file
<p>Don’t forget to save the file. A file with the ending <codeclass="docutils literal notranslate"><spanclass="pre">.py</span></code> is referred to as a Python <em>module</em>. To
use this in-game we have to <em>import</em> it. Try this:</p>
<p>If you make some error (we’ll cover how to handle errors below) you may need to run the <codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code>
command for your changes to take effect.</p>
<p>So importing <codeclass="docutils literal notranslate"><spanclass="pre">world.test</span></code> actually means importing <codeclass="docutils literal notranslate"><spanclass="pre">world/test.py</span></code>. Think of the period <codeclass="docutils literal notranslate"><spanclass="pre">.</span></code> as
replacing <codeclass="docutils literal notranslate"><spanclass="pre">/</span></code> (or <codeclass="docutils literal notranslate"><spanclass="pre">\</span></code> for Windows) in your path. The <codeclass="docutils literal notranslate"><spanclass="pre">.py</span></code> ending of <codeclass="docutils literal notranslate"><spanclass="pre">test.py</span></code> is also never
included in this “Python-path”, but <em>only</em> files with that ending can be imported this way. Where is
<codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code> in that Python-path? The answer is that Evennia has already told Python that your <codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code>
folder is a good place to look for imports. So we don’t include <codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code> in the path - Evennia
handles this for us.</p>
<p>When you import the module, the top “level” of it will execute. In this case, it will immediately
<div><p>If you look in the folder you’ll also often find new files ending with <codeclass="docutils literal notranslate"><spanclass="pre">.pyc</span></code>. These are compiled
Python binaries that Python auto-creates when running code. Just ignore them, you should never edit
<p>You will <em>not</em> see any output this second time or any subsequent times! This is not a bug. Rather
it is because Python is being clever - it stores all imported modules and to be efficient it will
avoid importing them more than once. So your <codeclass="docutils literal notranslate"><spanclass="pre">print</span></code> will only run the first time, when the module
is first imported. To see it again you need to <codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code> first, so Python forgets about the module
<h2>Parsing Python errors<aclass="headerlink"href="#parsing-python-errors"title="Permalink to this headline">¶</a></h2>
<p>Next, erase the single <codeclass="docutils literal notranslate"><spanclass="pre">print</span></code> statement you had in <codeclass="docutils literal notranslate"><spanclass="pre">test.py</span></code> and replace it with this instead:</p>
<p>As you recall we used this from <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> earlier - it echoed “Hello World!” in-game.
Save your file and <codeclass="docutils literal notranslate"><spanclass="pre">reload</span></code> your server - this makes sure Evennia sees the new version of your code.
Try to import it from <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> in the same way as earlier:</p>
<li><p>An error of type <codeclass="docutils literal notranslate"><spanclass="pre">NameError</span></code> is the problem …</p></li>
<li><p>… more specifically it is due to the variable <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> not being defined.</p></li>
<li><p>This happened on the line <codeclass="docutils literal notranslate"><spanclass="pre">me.msg("Hello</span><spanclass="pre">world!")</span></code> …</p></li>
<li><p>… which is on line <codeclass="docutils literal notranslate"><spanclass="pre">1</span></code> of the file <codeclass="docutils literal notranslate"><spanclass="pre">./world/test.py</span></code>.</p></li>
<p>In our case the traceback is short. There may be many more lines above it, tracking just how
different modules called each other until it got to the faulty line. That can sometimes be useful
information, but reading from the bottom is always a good start.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">NameError</span></code> we see here is due to a module being its own isolated thing. It knows nothing about
the environment into which it is imported. It knew what <codeclass="docutils literal notranslate"><spanclass="pre">print</span></code> is because that is a special
<aclass="reference external"href="https://docs.python.org/2.5/ref/keywords.html">reserved Python keyword</a>. But <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> is <em>not</em> such a
reserved word. As far as the module is concerned <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> is just there out of nowhere. Hence the
<p>Let’s see if we can resolve that <codeclass="docutils literal notranslate"><spanclass="pre">NameError</span></code> from the previous section. We know that <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> is defined
at the time we use the <codeclass="docutils literal notranslate"><spanclass="pre">@py</span></code> command because if we do <codeclass="docutils literal notranslate"><spanclass="pre">py</span><spanclass="pre">me.msg("Hello</span><spanclass="pre">World!")</span></code> directly in-game
it works fine. What if we could <em>send</em> that <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> to the <codeclass="docutils literal notranslate"><spanclass="pre">test.py</span></code> module so it knows what it is? One
<li><p>Capitalization matters in Python. It must be <codeclass="docutils literal notranslate"><spanclass="pre">def</span></code> and not <codeclass="docutils literal notranslate"><spanclass="pre">DEF</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">who</span></code> is not the same as <codeclass="docutils literal notranslate"><spanclass="pre">Who</span></code>
etc.</p></li>
<li><p>Indentation matters in Python. The second line must be indented or it’s not valid code. You should
also use a consistent indentation length. We <em>strongly</em> recommend that you set up your editor to
always indent <em>4 spaces</em> (<strong>not</strong> a single tab-character) when you press the TAB key - it will make
your life a lot easier.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">def</span></code> is short for “define” and defines a <em>function</em> (or a <em>method</em>, if sitting on an object).
This is a <aclass="reference external"href="https://docs.python.org/2.5/ref/keywords.html">reserved Python keyword</a>; try not to use
these words anywhere else.</p></li>
<li><p>A function name can not have spaces but otherwise we could have called it almost anything. We call
it <codeclass="docutils literal notranslate"><spanclass="pre">hello_world</span></code>. Evennia follows [Python’s standard naming style](https://github.com/evennia/evennia/blob/master/CODING_STYLE.md#a-quick-list-of-code-style-
points) with lowercase letters and underscores. Use this style for now.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">who</span></code> is what we call the <em>argument</em> to our function. Arguments are variables we pass to the
function. We could have named it anything and we could also have multiple arguments separated by
commas. What <codeclass="docutils literal notranslate"><spanclass="pre">who</span></code> is depends on what we pass to this function when we <em>call</em> it later (hint: we’ll
pass <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> to it).</p></li>
<li><p>The colon (<codeclass="docutils literal notranslate"><spanclass="pre">:</span></code>) at the end of the first line indicates that the header of the function is
complete.</p></li>
<li><p>The indentation marks the beginning of the actual operating code of the function (the function’s
<em>body</em>). If we wanted more lines to belong to this function those lines would all have to have to
start at this indentation level.</p></li>
<li><p>In the function body we take the <codeclass="docutils literal notranslate"><spanclass="pre">who</span></code> argument and treat it as we would have treated <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> earlier</p></li>
<li><p>we expect it to have a <codeclass="docutils literal notranslate"><spanclass="pre">.msg</span></code> method we can use to send “Hello World” to.</p></li>
<p>First, <codeclass="docutils literal notranslate"><spanclass="pre">reload</span></code> your game to make it aware of the updated Python module. Now we have defined our
<p>There is our “Hello World”! The <codeclass="docutils literal notranslate"><spanclass="pre">;</span></code> is the way to put multiple Python-statements on one line.</p>
<div><p>Some MUD clients use <codeclass="docutils literal notranslate"><spanclass="pre">;</span></code> for their own purposes to separate client-inputs. If so you’ll get a
<codeclass="docutils literal notranslate"><spanclass="pre">NameError</span></code> stating that <codeclass="docutils literal notranslate"><spanclass="pre">world</span></code> is not defined. Check so you understand why this is! Change the use
of <codeclass="docutils literal notranslate"><spanclass="pre">;</span></code> in your client or use the Evennia web client if this is a problem.</p>
<p>In the second statement we access the module path we imported (<codeclass="docutils literal notranslate"><spanclass="pre">world.test</span></code>) and reach for the
<codeclass="docutils literal notranslate"><spanclass="pre">hello_world</span></code> function within. We <em>call</em> the function with <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code>, which becomes the <codeclass="docutils literal notranslate"><spanclass="pre">who</span></code> variable we
use inside the <codeclass="docutils literal notranslate"><spanclass="pre">hello_function</span></code>.</p>
<div><p>As an exercise, try to pass something else into <codeclass="docutils literal notranslate"><spanclass="pre">hello_world</span></code>. Try for example to pass <em>who</em> as
the number <codeclass="docutils literal notranslate"><spanclass="pre">5</span></code> or the simple string <codeclass="docutils literal notranslate"><spanclass="pre">"foo"</span></code>. You’ll get errors that they don’t have the attribute
<codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code>. As we’ve seen, <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code><em>does</em> make <codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code> available which is why it works (you’ll learn more
about Objects like <codeclass="docutils literal notranslate"><spanclass="pre">me</span></code> in the next part of this tutorial). If you are familiar with other
programming languages you may be tempted to start <em>validating</em><codeclass="docutils literal notranslate"><spanclass="pre">who</span></code> to make sure it works as
expected. This is usually not recommended in Python which suggests it’s better to
<aclass="reference external"href="https://docs.python.org/2/tutorial/errors.html">handle</a> the error if it happens rather than to make
a lot of code to prevent it from happening. See also <aclass="reference external"href="https://en.wikipedia.org/wiki/Duck_typing">duck
<p>As you start to explore Evennia, it’s important that you know where to look when things go wrong.
While using the friendly <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> command you’ll see errors directly in-game. But if something goes
wrong in your code while the game runs, you must know where to find the <em>log</em>.</p>
<p>Open a terminal (or go back to the terminal you started Evennia in), make sure your <codeclass="docutils literal notranslate"><spanclass="pre">virtualenv</span></code> is
active and that you are standing in your game directory (the one created with <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">--init</span></code>
<p>This will show the log. New entries will show up in real time. Whenever you want to leave the log,
enter <codeclass="docutils literal notranslate"><spanclass="pre">Ctrl-C</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">Cmd-C</span></code> depending on your system. As a game dev it is important to look at the
log output when working in Evennia - many errors will only appear with full details here. You may
sometimes have to scroll up in the history if you miss it.</p>
<p>This tutorial is continued in <aclass="reference internal"href="Python-basic-tutorial-part-two.html"><spanclass="doc">Part 2</span></a>, where we’ll start learning
about objects and to explore the Evennia library.</p>
