<h1><spanclass="section-number">6. </span>Overview of the Evennia library<aclass="headerlink"href="#overview-of-the-evennia-library"title="Permalink to this headline">¶</a></h1>
<asideclass="sidebar">
<pclass="sidebar-title">API</p>
<p>API stands for <codeclass="docutils literal notranslate"><spanclass="pre">Application</span><spanclass="pre">Programming</span><spanclass="pre">Interface</span></code>, a description for how to access the resources of a program or library.</p>
</aside>
<p>There are several good ways to explore the Evennia library.</p>
<ulclass="simple">
<li><p>This documentation contains the <aclass="reference internal"href="../../../Evennia-API.html"><spanclass="doc std std-doc">Evennia-API docs</span></a>, generated automatically from sources. Try clicking through to a few entries - once you get deep enough you’ll see full descriptions of each component along with their documentation. You can also click <codeclass="docutils literal notranslate"><spanclass="pre">[source]</span></code> to see the full Python source code for each thing.</p></li>
<li><p>There are <aclass="reference internal"href="../../../Components/Components-Overview.html"><spanclass="doc std std-doc">separate doc pages for each component</span></a> if you want more detailed explanations.</p></li>
<li><p>You can browse <aclass="reference external"href="https://github.com/evennia/evennia">the evennia repository on github</a>. This is exactly what you can download from us.</p></li>
<li><p>Finally, you can clone the evennia repo to your own computer and read the sources. This is necessary if you want to <em>really</em> understand what’s going on, or help with Evennia’s development. See the <aclass="reference internal"href="../../../Setup/Installation-Git.html"><spanclass="doc std std-doc">extended install instructions</span></a> if you want to do this.</p></li>
</ul>
<sectionid="where-is-it">
<h2><spanclass="section-number">6.1. </span>Where is it?<aclass="headerlink"href="#where-is-it"title="Permalink to this headline">¶</a></h2>
<p>If Evennia is installed, you can import from it simply with</p>
from evennia.some_module.other_module import SomeClass
</pre></div>
</div>
<p>and so on.</p>
<p>If you installed Evennia with <codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span></code>, the library folder will be installed deep inside your Python installation; you are better off <aclass="reference external"href="https://github.com/evennia/evennia/blob/main/evennia">looking at it on github</a>. If you cloned it, you should have an <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> folder to look into.</p>
<p>You’ll find this being the outermost structure:</p>
<p>This outer layer is for Evennia’s installation and package distribution. That internal folder <codeclass="docutils literal notranslate"><spanclass="pre">evennia/evennia/</span></code> is the <em>actual</em> library, the thing covered by the API auto-docs and what you get when you do <codeclass="docutils literal notranslate"><spanclass="pre">import</span><spanclass="pre">evennia</span></code>.</p>
<blockquote>
<div><p>The <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/</span></code> folder contains the sources for this documentation. See
<aclass="reference internal"href="../../../Contributing-Docs.html"><spanclass="doc std std-doc">contributing to the docs</span></a> if you want to learn more about how this works.</p>
</div></blockquote>
<p>This is the structure of the Evennia library:</p>
<ulclass="simple">
<li><p>evennia</p>
<ul>
<li><p><aclass="reference internal"href="../../../Evennia-API.html#shortcuts"><spanclass="std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">__init__.py</span></code></span></a> - The “flat API” of Evennia resides here.</p></li>
<li><p><aclass="reference internal"href="../../../Setup/Settings.html#settings-file"><spanclass="std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">settings_default.py</span></code></span></a> - Root settings of Evennia. Copy settings from here to <codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/settings.py</span></code> file.</p></li>
<li><p><aclass="reference internal"href="../../../Components/Commands.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">commands/</span></code></span></a> - The command parser and handler.</p>
<ul>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">default/</span></code> - The <aclass="reference internal"href="../../../Components/Default-Commands.html"><spanclass="doc std std-doc">default commands</span></a> and cmdsets.</p></li>
</ul>
</li>
<li><p><aclass="reference internal"href="../../../Components/Channels.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">comms/</span></code></span></a> - Systems for communicating in-game.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">contrib/</span></code> - Optional plugins too game-specific for core Evennia.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">game_template/</span></code> - Copied to become the “game directory” when using <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">--init</span></code>.</p></li>
<li><p><aclass="reference internal"href="../../../Components/Help-System.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">help/</span></code></span></a> - Handles the storage and creation of help entries.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">locale/</span></code> - Language files (<aclass="reference internal"href="../../../Concepts/Internationalization.html"><spanclass="doc std std-doc">i18n</span></a>).</p></li>
<li><p><aclass="reference internal"href="../../../Components/Locks.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">locks/</span></code></span></a> - Lock system for restricting access to in-game entities.</p></li>
<li><p><aclass="reference internal"href="../../../Components/Objects.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">objects/</span></code></span></a> - In-game entities (all types of items and Characters).</p></li>
<li><p><aclass="reference internal"href="../../../Components/Prototypes.html"><spanclass="doc std std-doc"><codeclass="docutils literal notranslate"><spanclass="pre">prototypes/</span></code></span></a> - Object Prototype/spawning system and OLC menu</p></li>
<li><p><spanclass="xref myst"><codeclass="docutils literal notranslate"><spanclass="pre">web/</span></code></span> - Web resources and webserver. Partly copied into game directory on initialization.</p></li>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">__init__.py</span></code> file is a special Python filename used to represent a Python ‘package’. When you import <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> on its own, you import this file. When you do <codeclass="docutils literal notranslate"><spanclass="pre">evennia.foo</span></code> Python will first look for a property <codeclass="docutils literal notranslate"><spanclass="pre">.foo</span></code> in <codeclass="docutils literal notranslate"><spanclass="pre">__init__.py</span></code> and then for a module or folder of that name in the same location.</p>
</aside>
<p>While all the actual Evennia code is found in the various folders, the <codeclass="docutils literal notranslate"><spanclass="pre">__init__.py</span></code> represents the entire package <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code>. It contains “shortcuts” to code that is actually located elsewhere. Most of these shortcuts are listed if you <aclass="reference internal"href="../../../Evennia-API.html"><spanclass="doc std std-doc">scroll down a bit</span></a> on the Evennia-API page.</p>
</section>
<sectionid="an-example-of-exploring-the-library">
<h2><spanclass="section-number">6.2. </span>An example of exploring the library<aclass="headerlink"href="#an-example-of-exploring-the-library"title="Permalink to this headline">¶</a></h2>
<p>In the <aclass="reference internal"href="Beginner-Tutorial-Python-classes-and-objects.html#on-classes-and-objects"><spanclass="std std-doc">previous lesson</span></a> we took a brief look at <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/objects</span></code> as an example of a Python module. Let’s open it again.</p>
<p>We have the <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code> class, which inherits from <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>. Near the top of the module is this line:</p>
<p>We want to figure out just what this DefaultObject offers. Since this is imported directly from <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code>, we are actually importing from <codeclass="docutils literal notranslate"><spanclass="pre">evennia/__init__.py</span></code>.</p>
<p><aclass="reference external"href="https://github.com/evennia/evennia/blob/main/evennia/__init__.py#L160">Look at Line 160</a> of <codeclass="docutils literal notranslate"><spanclass="pre">evennia/__init__.py</span></code> and you’ll find this line:</p>
<pclass="sidebar-title">Relative and absolute imports</p>
<p>The first full-stop in <codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">.objects.objects</span><spanclass="pre">...</span></code> means that we are importing from the current location. This is called a <codeclass="docutils literal notranslate"><spanclass="pre">relative</span><spanclass="pre">import</span></code>. By comparison, <codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">evennia.objects.objects</span></code> is an <codeclass="docutils literal notranslate"><spanclass="pre">absolute</span><spanclass="pre">import</span></code>. In this particular case, the two would give the same result.</p>
</aside>
<blockquote>
<div><p>You can also look at <aclass="reference internal"href="../../../Evennia-API.html#typeclasses"><spanclass="std std-doc">the right section of the API frontpage</span></a> and click through to the code that way.</p>
</div></blockquote>
<p>The fact that <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code> is imported into <codeclass="docutils literal notranslate"><spanclass="pre">__init__.py</span></code> here is what makes it possible to also import it as <codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">evennia</span><spanclass="pre">import</span><spanclass="pre">DefaultObject</span></code> even though the code for the class is not actually here.</p>
<p>So to find the code for <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code> we need to look in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/objects/objects.py</span></code>. Here’s how to look it up in the docs:</p>
<olclass="simple">
<li><p>Open the <aclass="reference internal"href="../../../Evennia-API.html"><spanclass="doc std std-doc">API frontpage</span></a></p></li>
<li><p>Locate the link to <aclass="reference internal"href="../../../api/evennia.objects.objects.html"><spanclass="doc std std-doc">evennia.objects.objects</span></a> and click on it.</p></li>
<li><p>You are now in the python module. Scroll down (or search in your web browser) to find the <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code> class.</p></li>
<li><p>You can now read what this does and what methods are on it. If you want to see the full source, click the [source] link next to it.</p></li>
</ol>
</section>
<sectionid="conclusions">
<h2><spanclass="section-number">6.3. </span>Conclusions<aclass="headerlink"href="#conclusions"title="Permalink to this headline">¶</a></h2>
<p>This is an important lesson. It teaches you how to find information for yourself. Knowing how to follow the class inheritance tree and navigate to things you need is a big part in learning a new library like Evennia.</p>
<p>Next we’ll start to make use of what we have learned so far and combine it with the building blocks provided by Evennia.</p>
