<h1>Glossary<aclass="headerlink"href="#glossary"title="Permalink to this headline">¶</a></h1>
<p>This explains common recurring terms used in the Evennia docs. It will be expanded as needed.</p>
<ulclass="simple">
<li><p><em><aclass="reference internal"href="#account"><spanclass="std std-doc">account</span></a></em> - the player’s account on the game</p></li>
<li><p><em><aclass="reference internal"href="#admin-site"><spanclass="std std-doc">admin-site</span></a></em> - the Django web page for manipulating the database</p></li>
<li><p><em><aclass="reference internal"href="#attribute"><spanclass="std std-doc">attribute</span></a></em> - persistent, custom data stored on typeclasses</p></li>
<li><p><em><aclass="reference internal"href="#channel"><spanclass="std std-doc">channel</span></a></em> - game communication channels</p></li>
<li><p><em><aclass="reference internal"href="#character"><spanclass="std std-doc">character</span></a></em> - the player’s avatar in the game, controlled from
<li><p><em><aclass="reference internal"href="#contrib"><spanclass="std std-doc">contrib</span></a></em> - a term used for optional code contributed by the community.</p></li>
<li><p><em><aclass="reference internal"href="#core"><spanclass="std std-doc">core</span></a></em> - a term used for the code distributed with Evennia proper</p></li>
<li><p><em><aclass="reference internal"href="#django"><spanclass="std std-doc">django</span></a></em> - web framework Evennia uses for database access and web integration</p></li>
<li><p><em><aclass="reference internal"href="#field"><spanclass="std std-doc">field</span></a></em> - a <em><aclass="reference internal"href="#typeclass"><spanclass="std std-doc">typeclass</span></a></em> property representing a database
column</p></li>
<li><p><em><aclass="reference internal"href="#git"><spanclass="std std-doc">git</span></a></em> - the version-control system we use</p></li>
<li><p><em><aclass="reference internal"href="#github"><spanclass="std std-doc">github</span></a></em> - the online hosting of our source code</p></li>
<li><p><em><aclass="reference internal"href="#migrate"><spanclass="std std-doc">migrate</span></a></em> - updating the database schema</p></li>
<li><p><em><aclass="reference internal"href="#multisession-mode"><spanclass="std std-doc">multisession mode`</span></a></em> - a setting defining how users connect to Evennia</p></li>
<li><p><em><aclass="reference internal"href="#object"><spanclass="std std-doc">object</span></a></em> - Python instance, general term or in-game
<li><p><em><aclass="reference internal"href="#pip"><spanclass="std std-doc">pip</span></a></em> - the Python installer</p></li>
<li><p><em>player</em> - the human connecting to the game with their client</p></li>
<li><p><em><aclass="reference internal"href="#puppet"><spanclass="std std-doc">puppet</span></a></em> - when an <aclass="reference internal"href="#account"><spanclass="std std-doc">account</span></a> controls an in-game
<li><p><em><aclass="reference internal"href="#property"><spanclass="std std-doc">property</span></a></em> - a python property</p></li>
<li><p><em>evenv</em> - see <em><aclass="reference internal"href="#virtualenv"><spanclass="std std-doc">virtualenv</span></a></em></p></li>
<li><p><em><aclass="reference internal"href="#repository"><spanclass="std std-doc">repository</span></a></em> - a store of source code + source history</p></li>
<li><p><em><aclass="reference internal"href="#script"><spanclass="std std-doc">script</span></a></em> - a building block for custom storage, systems and time-keepint</p></li>
<li><p><em><aclass="reference internal"href="#session"><spanclass="std std-doc">session</span></a></em> - represents one client connection</p></li>
<li><p><em><aclass="reference internal"href="#ticker"><spanclass="std std-doc">ticker</span></a></em> - Allows to run events on a steady ‘tick’</p></li>
<li><p><em><aclass="reference internal"href="#twisted"><spanclass="std std-doc">twisted</span></a></em> - networking engine responsible for Evennia’s event loop and
<li><p><em>upstream</em> - see <em><aclass="reference internal"href="#github"><spanclass="std std-doc">github</span></a></em></p></li>
<li><p><em><aclass="reference internal"href="#virtualenv"><spanclass="std std-doc">virtualenv</span></a></em> - a Python program and way to make an isolated Python install</p></li>
</ul>
<hrclass="docutils"/>
<sectionid="account">
<h2><em>account</em><aclass="headerlink"href="#account"title="Permalink to this headline">¶</a></h2>
<p>The term ‘account’ refers to the <aclass="reference internal"href="#account"><spanclass="std std-doc">player’s</span></a> unique account on the game. It is
represented by the <codeclass="docutils literal notranslate"><spanclass="pre">Account</span></code><aclass="reference internal"href="#typeclass"><spanclass="std std-doc">typeclass</span></a> and holds things like email, password,
configuration etc.</p>
<p>When a player connects to the game, they connect to their account. The account has <em>no</em>
representation in the game world. Through their Account they can instead choose to
<aclass="reference internal"href="#puppet"><spanclass="std std-doc">puppet</span></a> one (or more, depending on game mode) <aclass="reference internal"href="#character"><spanclass="std std-doc">Characters</span></a> in
the game.</p>
<p>In the default <aclass="reference internal"href="Components/Sessions.html#multisession-mode"><spanclass="std std-doc">multisession mode</span></a> of Evennia, you immediately start
puppeting a Character with the same name as your Account when you log in - mimicking how older
servers used to work.</p>
</section>
<sectionid="admin-site">
<h2><em>admin-site</em><aclass="headerlink"href="#admin-site"title="Permalink to this headline">¶</a></h2>
<p>This usually refers to <aclass="reference internal"href="#django"><spanclass="std std-doc">Django’s</span></a><em>Admin site</em> or database-administration web page
(<aclass="reference external"href="https://docs.djangoproject.com/en/2.1/ref/contrib/admin/">link to Django docs</a>). The admin site is
an automatically generated web interface to the database (it can be customized extensively). It’s
reachable from the <codeclass="docutils literal notranslate"><spanclass="pre">admin</span></code> link on the default Evennia website you get with your server.</p>
</section>
<sectionid="attribute">
<h2><em>attribute</em><aclass="headerlink"href="#attribute"title="Permalink to this headline">¶</a></h2>
<p>The term <em>Attribute</em> should not be confused with (<aclass="reference internal"href="#property"><spanclass="std std-doc">properties</span></a> or
<aclass="reference internal"href="#field"><spanclass="std std-doc">fields</span></a>. The <codeclass="docutils literal notranslate"><spanclass="pre">Attribute</span></code> represents arbitrary pieces of data that can be attached
to any <aclass="reference internal"href="#typeclass"><spanclass="std std-doc">typeclassed</span></a> entity in Evennia. Attributes allows storing new persistent
data on typeclasses without changing their underlying database schemas.
<aclass="reference internal"href="Components/Attributes.html"><spanclass="doc std std-doc">Read more about Attributes here</span></a>.</p>
</section>
<sectionid="channel">
<h2><em>channel</em><aclass="headerlink"href="#channel"title="Permalink to this headline">¶</a></h2>
<p>A <em>Channel</em> refers to an in-game communication channel. It’s an entity that people subscribe to and
which re-distributes messages between all subscribers. Such subscribers default to being
<aclass="reference internal"href="#account"><spanclass="std std-doc">Accounts</span></a>, for out-of-game communication but could also be <aclass="reference internal"href="#character"><spanclass="std std-doc">Objects (usually
Characters)</span></a> if one wanted to adopt Channels for things like in-game walkie-
talkies or phone systems. It is represented by the <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code> typeclass. <aclass="reference internal"href="Components/Channels.html"><spanclass="doc std std-doc">You can read more about the
comm system here</span></a>.</p>
</section>
<sectionid="character">
<h2><em>character</em><aclass="headerlink"href="#character"title="Permalink to this headline">¶</a></h2>
<p>The <em>Character</em> is the term we use for the default avatar being <aclass="reference internal"href="#puppet"><spanclass="std std-doc">puppeted</span></a> by the
<aclass="reference internal"href="#account"><spanclass="std std-doc">account</span></a> in the game world. It is represented by the <codeclass="docutils literal notranslate"><spanclass="pre">Character</span></code> typeclass (which
is a child of <aclass="reference internal"href="#object"><spanclass="std std-doc">Object</span></a>). Many developers use children of this class to represent
monsters and other NPCs. You can <aclass="reference internal"href="Components/Objects.html#subclasses-of-object"><spanclass="std std-doc">read more about it here</span></a>.</p>
</section>
<sectionid="django">
<h2><em>django</em><aclass="headerlink"href="#django"title="Permalink to this headline">¶</a></h2>
<p><aclass="reference external"href="https://www.djangoproject.com/">Django</a> is a professional and very popular Python web framework,
similar to Rails for the Ruby language. It is one of Evennia’s central library dependencies (the
other one is <aclass="reference internal"href="#twisted"><spanclass="std std-doc">Twisted</span></a>). Evennia uses Django for two main things - to map all
database operations to Python and for structuring our web site.</p>
<p>Through Django, we can work with any supported database (SQlite3, Postgres, MySQL …) using generic
Python instead of database-specific SQL: A database table is represented in Django as a Python class
(called a <em>model</em>). An Python instance of such a class represents a row in that table.</p>
<p>There is usually no need to know the details of Django’s database handling in order to use Evennia -
it will handle most of the complexity for you under the hood using what we call
<aclass="reference internal"href="#typeclass"><spanclass="std std-doc">typeclasses</span></a>. But should you need the power of Django you can always get it.
Most commonly people want to use “raw” Django when doing more advanced/custom database queries than
offered by Evennia’s <aclass="reference internal"href="Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Searching-Things.html"><spanclass="doc std std-doc">default search functions</span></a>. One will then need
to read about Django’s <em>querysets</em>. Querysets are Python method calls on a special form that lets
you build complex queries. They get converted into optimized SQL queries under the hood, suitable
for your current database. [Here is our tutorial/explanation of Django queries](Tutorial-Searching-
For-Objects#queries-in-django).</p>
<blockquote>
<div><p>By the way, Django (and Evennia) does allow you to fall through and send raw SQL if you really
want to. It’s highly unlikely to be needed though; the Django database abstraction is very, very
powerful.</p>
</div></blockquote>
<p>The other aspect where Evennia uses Django is for web integration. On one end Django gives an
infrastructure for wiring Python functions (called <em>views</em>) to URLs: the view/function is called
when a user goes that URL in their browser, enters data into a form etc. The return is the web page
to show. Django also offers templating with features such as being able to add special markers in
HTML where it will insert the values of Python variables on the fly (like showing the current player
count on the web page). [Here is one of our tutorials on wiring up such a web page](Add-a-simple-
new-web-page). Django also comes with the <aclass="reference internal"href="#admin-site"><spanclass="std std-doc">admin site</span></a>, which automatically
maps the database into a form accessible from a web browser.</p>
</section>
<sectionid="core">
<h2><em>core</em><aclass="headerlink"href="#core"title="Permalink to this headline">¶</a></h2>
<p>This term is sometimes used to represent the main Evennia library code suite, <em>excluding</em> its
<aclass="reference internal"href="#contrib"><spanclass="std std-doc">contribs</span></a> directory. It can sometimes come up in code reviews, such as</p>
<blockquote>
<div><p>Evennia is game-agnostic but this feature is for a particular game genre. So it does not belong in
core. Better make it a contrib.</p>
</div></blockquote>
</section>
<sectionid="contrib">
<h2><em>contrib</em><aclass="headerlink"href="#contrib"title="Permalink to this headline">¶</a></h2>
<p>Game-specific code and examples are distributed in evennia’s <aclass="reference internal"href="Contribs/Contribs-Overview.html"><spanclass="doc std std-doc">contribs/</span></a> folder.
This is game-specific, optional code created by the Evennia community.</p>
</section>
<sectionid="field">
<h2><em>field</em><aclass="headerlink"href="#field"title="Permalink to this headline">¶</a></h2>
<p>A <em>field</em> or <em>database field</em> in Evennia refers to a <aclass="reference internal"href="#property"><spanclass="std std-doc">property</span></a> on a
<aclass="reference internal"href="#typeclass"><spanclass="std std-doc">typeclass</span></a> directly linked to an underlying database column. Only a few fixed
properties per typeclass are database fields but they are often tied to the core functionality of
that base typeclass (for example <aclass="reference internal"href="#object"><spanclass="std std-doc">Objects</span></a> store its location as a field). In all
other cases, <aclass="reference internal"href="#attribute"><spanclass="std std-doc">attributes</span></a> are used to add new persistent data to the typeclass.
<aclass="reference internal"href="Components/Typeclasses.html#about-typeclass-properties"><spanclass="std std-doc">Read more about typeclass properties here</span></a>.</p>
</section>
<sectionid="git">
<h2><em>git</em><aclass="headerlink"href="#git"title="Permalink to this headline">¶</a></h2>
<p><aclass="reference external"href="https://git-scm.com/">Git</a> is a <aclass="reference external"href="https://en.wikipedia.org/wiki/Version_control">version control</a>
tool. It allows us to track the development of the Evennia code by dividing it into units called
<em>commits</em>. A ‘commit’ is sort of a save-spot - you save the current state of your code and can then
come back to it later if later changes caused problems. By tracking commits we know what ‘version’
of the code we are currently using.</p>
<p>Evennia’s source code + its source history is jointly called a <aclass="reference internal"href="#repository"><spanclass="std std-doc">repository</span></a>.
This is centrally stored at our online home on <aclass="reference internal"href="#github"><spanclass="std std-doc">GitHub</span></a>. Everyone using or
developing Evennia makes a ‘clone’ of this repository to their own computer - everyone
automatically gets everything that is online, including all the code history.</p>
<blockquote>
<div><p>Don’t confuse Git and <aclass="reference internal"href="#github"><spanclass="std std-doc">GitHub</span></a>. The former is the version control system. The
latter is a website (run by a company) that allows you to upload source code controlled by Git for
others to see (among other things).</p>
</div></blockquote>
<p>Git allows multiple users from around the world to efficiently collaborate on Evennia’s code: People
can make local commits on their cloned code. The commits they do can then be uploaded to GitHub and
reviewed by the Evennia lead devs - and if the changes look ok they can be safely <em>merged</em> into the
central Evennia code - and everyone can <em>pull</em> those changes to update their local copies.</p>
<p>Developers using Evennia often uses Git on their own games in the same way - to track their changes
and to help collaboration with team mates. This is done completely independently of Evennia’s Git
usage.</p>
<p>Common usage (for non-Evennia developers):</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">clone</span><spanclass="pre"><github-url></span></code> - clone an online repository to your computer. This is what you do when
you ‘download’ Evennia. You only need to do this once.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">pull</span></code> (inside local copy of repository) - sync your local repository with what is online.</p></li>
</ul>
<blockquote>
<div><p>Full usage of Git is way beyond the scope of this glossary. See
<aclass="reference internal"href="Coding/Version-Control.html"><spanclass="doc std std-doc">Tutorial - version control</span></a> for more info and links to the Git documentation.</p>
</div></blockquote>
</section>
<sectionid="migrate">
<h2><em>migrate</em><aclass="headerlink"href="#migrate"title="Permalink to this headline">¶</a></h2>
<p>This term is used for upgrading the database structure (it’s <em>schema</em> )to a new version. Most often
this is due to Evennia’s <aclass="reference internal"href="#github"><spanclass="std std-doc">upstream</span></a> schema changing. When that happens you need to
migrate that schema to the new version as well. Once you have used <aclass="reference internal"href="#git"><spanclass="std std-doc">git</span></a> to pull the
latest changes, just <codeclass="docutils literal notranslate"><spanclass="pre">cd</span></code> into your game dir and run</p>
<p>That should be it (see <aclass="reference internal"href="#virtualenv"><spanclass="std std-doc">virtualenv</span></a> if you get a warning that the <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code>
command is not available). See also <aclass="reference internal"href="Coding/Updating-Your-Game.html"><spanclass="doc std std-doc">Updating your game</span></a> for more details.</p>
<blockquote>
<div><p>Technically, migrations are shipped as little Python snippets of code that explains which database
actions must be taken to upgrade from one version of the schema to the next. When you run the
command above, those snippets are run in sequence.</p>
</div></blockquote>
</section>
<sectionid="multisession-mode">
<h2><em>multisession mode</em><aclass="headerlink"href="#multisession-mode"title="Permalink to this headline">¶</a></h2>
<p>This term refers to the <codeclass="docutils literal notranslate"><spanclass="pre">MULTISESSION_MODE</span></code> setting, which has a value of 0 to 3. The mode alters
how players can connect to the game, such as how many Sessions a player can start with one account
and how many Characters they can control at the same time. It is <aclass="reference internal"href="Components/Sessions.html#multisession-mode"><spanclass="std std-doc">described in detail
here</span></a>.</p>
</section>
<sectionid="github">
<h2><em>github</em><aclass="headerlink"href="#github"title="Permalink to this headline">¶</a></h2>
<p><aclass="reference external"href="https://github.com/evennia">Github</a> is where Evennia’s source code and documentation is hosted.
This online <aclass="reference internal"href="#repository"><spanclass="std std-doc">repository</span></a> of code we also sometimes refer to as <em>upstream</em>.</p>
<p>GitHub is a business, offering free hosting to Open-source projects like Evennia. Despite the
similarity in name, don’t confuse GitHub the website with <aclass="reference internal"href="#git"><spanclass="std std-doc">Git</span></a>, the versioning
system. Github hosts Git <aclass="reference internal"href="#repository"><spanclass="std std-doc">repositories</span></a> online and helps with collaboration and
infrastructure. Git itself is a separate project.</p>
</section>
<sectionid="object">
<h2><em>object</em><aclass="headerlink"href="#object"title="Permalink to this headline">¶</a></h2>
<p>In general Python (and other [object-oriented languages](<aclass="reference external"href="https://en.wikipedia.org/wiki/Object-">https://en.wikipedia.org/wiki/Object-</a>
oriented_programming)), an <codeclass="docutils literal notranslate"><spanclass="pre">object</span></code> is what we call the instance of a <em>class</em>. But one of Evennia’s
core <aclass="reference internal"href="#typeclass"><spanclass="std std-doc">typeclasses</span></a> is also called “Object”. To separate these in the docs we
try to use <codeclass="docutils literal notranslate"><spanclass="pre">object</span></code> to refer to the general term and capitalized <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code> when we refer to the
typeclass.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code> is a typeclass that represents all <em>in-game</em> entities, including
<aclass="reference internal"href="#character"><spanclass="std std-doc">Characters</span></a>, rooms, trees, weapons etc. <aclass="reference internal"href="Components/Objects.html"><spanclass="doc std std-doc">Read more about Objects here</span></a>.</p>
</section>
<sectionid="pip">
<h2><em>pip</em><aclass="headerlink"href="#pip"title="Permalink to this headline">¶</a></h2>
<p><em><aclass="reference external"href="https://pypi.org/project/pip/">pip</a></em> comes with Python and is the main tool for installing third-
party Python packages from the web. Once a python package is installed you can do <codeclass="docutils literal notranslate"><spanclass="pre">import</span><spanclass="pre"><packagename></span></code> in your Python code.</p>
<p>Common usage:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre"><package-name></span></code> - install the given package along with all its dependencies.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">search</span><spanclass="pre"><name></span></code> - search Python’s central package repository <aclass="reference external"href="https://pypi.org/">PyPi</a> for a
package of that name.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre">--upgrade</span><spanclass="pre"><package_name></span></code> - upgrade a package you already have to the latest version.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre"><packagename>==1.5</span></code> - install exactly a specific package version.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre"><folder></span></code> - install a Python package you have downloaded earlier (or cloned using
git).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre">-e</span><spanclass="pre"><folder></span></code> - install a local package by just making a soft link to the folder. This
means that if the code in <codeclass="docutils literal notranslate"><spanclass="pre"><folder></span></code> changes, the installed Python package is immediately updated.
If not using <codeclass="docutils literal notranslate"><spanclass="pre">-e</span></code>, one would need to run <codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre">--upgrade</span><spanclass="pre"><folder></span></code> every time to make the
changes available when you import this package into your code. Evennia is installed this way.</p></li>
</ul>
<p>For development, <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> is usually used together with a <aclass="reference internal"href="#virtualenv"><spanclass="std std-doc">virtualenv</span></a> to install
all packages and dependencies needed for a project in one, isolated location on the hard drive.</p>
</section>
<sectionid="puppet">
<h2><em>puppet</em><aclass="headerlink"href="#puppet"title="Permalink to this headline">¶</a></h2>
<p>An <aclass="reference internal"href="#account"><spanclass="std std-doc">account</span></a> can take control and “play as” any <aclass="reference internal"href="#object"><spanclass="std std-doc">Object</span></a>. When
doing so, we call this <em>puppeting</em>, (like <aclass="reference external"href="https://en.wikipedia.org/wiki/Puppeteer">puppeteering</a>).
Normally the entity being puppeted is of the <aclass="reference internal"href="#character"><spanclass="std std-doc">Character</span></a> subclass but it does
not have to be.</p>
</section>
<sectionid="property">
<h2><em>property</em><aclass="headerlink"href="#property"title="Permalink to this headline">¶</a></h2>
<p>A <em>property</em> is a general term used for properties on any Python object. The term also sometimes
refers to the <codeclass="docutils literal notranslate"><spanclass="pre">property</span></code> built-in function of Python ([read more here](https://www.python-
<aclass="reference external"href="http://course.eu/python3_properties.php">course.eu/python3_properties.php</a>)). Note the distinction between properties,
<aclass="reference internal"href="#field"><spanclass="std std-doc">fields</span></a> and <aclass="reference internal"href="#attribute"><spanclass="std std-doc">Attributes</span></a>.</p>
</section>
<sectionid="repository">
<h2><em>repository</em><aclass="headerlink"href="#repository"title="Permalink to this headline">¶</a></h2>
<p>A <em>repository</em> is a version control/<aclass="reference internal"href="#git"><spanclass="std std-doc">git</span></a> term. It represents a folder containing
source code plus its versioning history.</p>
<blockquote>
<div><p>In Git’s case, that history is stored in a hidden folder <codeclass="docutils literal notranslate"><spanclass="pre">.git</span></code>. If you ever feel the need to look
into this folder you probably already know enough Git to know why.</p>
</div></blockquote>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> folder you download from us with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">clone</span></code> is a repository. The code on
<aclass="reference internal"href="#github"><spanclass="std std-doc">GitHub</span></a> is often referred to as the ‘online repository’ (or the <em>upstream</em>
repository). If you put your game dir under version control, that of course becomes a repository as
well.</p>
</section>
<sectionid="script">
<h2><em>script</em><aclass="headerlink"href="#script"title="Permalink to this headline">¶</a></h2>
<p>When we refer to <em>Scripts</em>, we generally refer to the <codeclass="docutils literal notranslate"><spanclass="pre">Script</span></code><aclass="reference internal"href="Components/Typeclasses.html"><spanclass="doc std std-doc">typeclass</span></a>. Scripts are
the mavericks of Evennia - they are like <aclass="reference internal"href="#object"><spanclass="std std-doc">Objects</span></a> but without any in-game
existence. They are useful as custom places to store data but also as building blocks in persistent
game systems. Since the can be initialized with timing capabilities they can also be used for long-
time persistent time keeping (for fast updates other types of timers may be better though).
<aclass="reference internal"href="Components/Scripts.html"><spanclass="doc std std-doc">Read more about Scripts here</span></a></p>
</section>
<sectionid="session">
<h2><em>session</em><aclass="headerlink"href="#session"title="Permalink to this headline">¶</a></h2>
<p>A <aclass="reference internal"href="Components/Sessions.html"><spanclass="doc std std-doc">Session</span></a> is a Python object representing a single client connection to the server. A
given human player could connect to the game from different clients and each would get a Session
(even if you did not allow them to actually log in and get access to an
<p>Sessions are <em>not</em><aclass="reference internal"href="#typeclass"><spanclass="std std-doc">typeclassed</span></a> and has no database persistence. But since they
always exist (also when not logged in), they share some common functionality with typeclasses that
can be useful for certain game states.</p>
</section>
<sectionid="tag">
<h2><em>tag</em><aclass="headerlink"href="#tag"title="Permalink to this headline">¶</a></h2>
<p>A <aclass="reference internal"href="Components/Tags.html"><spanclass="doc std std-doc">Tag</span></a> is used to group and categorize other database entitiess together in an efficient way
so they can be efficiently searched later.</p>
</section>
<sectionid="ticker">
<h2><em>ticker</em><aclass="headerlink"href="#ticker"title="Permalink to this headline">¶</a></h2>
<p>The <aclass="reference internal"href="Components/TickerHandler.html"><spanclass="doc std std-doc">Ticker handler</span></a> runs Evennia’s optional ‘ticker’ system. In other engines, such
as <aclass="reference external"href="https://en.wikipedia.org/wiki/DikuMUD">DIKU</a>, all game events are processed only at specific
intervals called ‘ticks’. Evennia has no such technical limitation (events are processed whenever
needed) but using a fixed tick can still be useful for certain types of game systems, like combat.
Ticker Handler allows you to emulate any number of tick rates (not just one) and subscribe actions
to be called when those ticks come around.</p>
</section>
<sectionid="typeclass">
<h2><em>typeclass</em><aclass="headerlink"href="#typeclass"title="Permalink to this headline">¶</a></h2>
<p>The <aclass="reference internal"href="Components/Typeclasses.html"><spanclass="doc std std-doc">typeclass</span></a> is an Evennia-specific term. A typeclass allows developers to work with
database-persistent objects as if they were normal Python objects. It makes use of specific
<aclass="reference internal"href="#django"><spanclass="std std-doc">Django</span></a> features to link a Python class to a database table. Sometimes we refer to
such code entities as <em>being typeclassed</em>.</p>
<p>Evennia’s main typeclasses are <aclass="reference internal"href="#account"><spanclass="std std-doc">Account</span></a>, <aclass="reference internal"href="#object"><spanclass="std std-doc">Object</span></a>,
<aclass="reference internal"href="#script"><spanclass="std std-doc">Script</span></a> and <aclass="reference internal"href="#channel"><spanclass="std std-doc">Channel</span></a>. Children of the base class (such as
<aclass="reference internal"href="#character"><spanclass="std std-doc">Character</span></a>) will use the same database table as the parent, but can have vastly
different Python capabilities (and persistent features through <aclass="reference internal"href="#attribute"><spanclass="std std-doc">Attributes</span></a> and
<aclass="reference internal"href="#tag"><spanclass="std std-doc">Tags</span></a>. A typeclass can be coded and treated pretty much like any other Python class
except it must inherit (at any distance) from one of the base typeclasses. Also, creating a new
instance of a typeclass will add a new row to the database table to which it is linked.</p>
<p>The <aclass="reference internal"href="#core"><spanclass="std std-doc">core</span></a> typeclasses in the Evennia library are all named <codeclass="docutils literal notranslate"><spanclass="pre">DefaultAccount</span></code>,
<codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code> etc. When you initialize your [game dir] you automatically get empty children of
these, called <codeclass="docutils literal notranslate"><spanclass="pre">Account</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code> etc that you can start working with.</p>
</section>
<sectionid="twisted">
<h2><em>twisted</em><aclass="headerlink"href="#twisted"title="Permalink to this headline">¶</a></h2>
<p><aclass="reference external"href="https://twistedmatrix.com/trac/">Twisted</a> is a heavy-duty asynchronous networking engine. It is one
of Evennia’s two major library dependencies (the other one is <aclass="reference internal"href="#django"><spanclass="std std-doc">Django</span></a>). Twisted is
what “runs” Evennia - it handles Evennia’s event loop. Twisted also has the building blocks we need
to construct network protocols and communicate with the outside world; such as our MUD-custom
version of Telnet, Telnet+SSL, SSH, webclient-websockets etc. Twisted also runs our integrated web
server, serving the Django-based website for your game.</p>
</section>
<sectionid="virtualenv">
<h2><em>virtualenv</em><aclass="headerlink"href="#virtualenv"title="Permalink to this headline">¶</a></h2>
<p>The standard <aclass="reference external"href="https://virtualenv.pypa.io/en/stable/">virtualenv</a> program comes with Python. It is
used to isolate all Python packages needed by a given Python project into one folder (we call that
folder <codeclass="docutils literal notranslate"><spanclass="pre">evenv</span></code> but it could be called anything). A package environment created this way is usually
referred to as “a virtualenv”. If you ever try to run the <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> program and get an error saying
something like “the command ‘evennia’ is not available” - it’s probably because your virtualenv is
not ‘active’ yet (see below).</p>
<p>Usage:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">python3.10</span><spanclass="pre">-m</span><spanclass="pre">venv</span><spanclass="pre">evenv</span></code> - initialize a new virtualenv-folder <codeclass="docutils literal notranslate"><spanclass="pre">evenv</span></code> in the current
location. You can call this whatever you like. The Python-version you use for this call will be the one used
for everything inside the virtualenv.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">source</span><spanclass="pre">evenv/bin/activate</span></code> (linux/mac) or <codeclass="docutils literal notranslate"><spanclass="pre">evenv\Scripts\activate</span></code>(windows) - this activates the
virtualenv.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">deactivate</span></code> - turn off the currently activated virtualenv.</p></li>
</ul>
<p>A virtualenv is ‘activated’ only for the console/terminal it was started in, but it’s safe to
activate the same virtualenv many times in different windows if you want. Once activated, all Python
packages now installed with <aclass="reference internal"href="#pip"><spanclass="std std-doc">pip</span></a> will install to <codeclass="docutils literal notranslate"><spanclass="pre">evenv</span></code> rather than to a global
location like <codeclass="docutils literal notranslate"><spanclass="pre">/usr/local/bin</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">C:\Program</span><spanclass="pre">Files</span></code>.</p>
<blockquote>
<div><p>Note that if you have root/admin access you <em>could</em> install Evennia globally just fine, without
using a virtualenv. It’s strongly discouraged and considered bad practice though. Experienced Python
developers tend to rather create one new virtualenv per project they are working on, to keep the
varying installs cleanly separated from one another.</p>
</div></blockquote>
<p>When you execute Python code within this activated virtualenv, <em>only</em> those packages installed
within will be possible to <codeclass="docutils literal notranslate"><spanclass="pre">import</span></code> into your code. So if you installed a Python package globally on
your computer, you’ll need to install it again in your virtualenv.</p>
<blockquote>
<div><p>Virtualenvs <em>only</em> deal with Python programs/packages. Other programs on your computer couldn’t
care less if your virtualenv is active or not. So you could use <codeclass="docutils literal notranslate"><spanclass="pre">git</span></code> without the virtualenv being
active, for example.</p>
</div></blockquote>
<p>When your virtualenv is active you should see your console/terminal prompt change to</p>
<p>… or whatever name you gave the virtualenv when you initialized it.</p>
<blockquote>
<div><p>We sometimes say that we are “in” the virtualenv when it’s active. But just to be clear - you
never have to actually <codeclass="docutils literal notranslate"><spanclass="pre">cd</span></code> into the <codeclass="docutils literal notranslate"><spanclass="pre">evenv</span></code> folder. You can activate it from anywhere and will
still be considered “in” the virtualenv wherever you go until you <codeclass="docutils literal notranslate"><spanclass="pre">deactivate</span></code> or close the
console/terminal.</p>
</div></blockquote>
<p>So, when do you <em>need</em> to activate my virtualenv? If the virtualenv is not active, none of the Python
packages/programs you installed in it will be available to you. So at a minimum, <em>it needs to be
activated whenever you want to use the <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> command</em> for any reason.</p>
