<h1>Objects<aclass="headerlink"href="#objects"title="Permalink to this headline">¶</a></h1>
<p>All in-game objects in Evennia, be it characters, chairs, monsters, rooms or hand grenades are
represented by an Evennia <em>Object</em>. Objects form the core of Evennia and is probably what you’ll
spend most time working with. Objects are <aclass="reference internal"href="Typeclasses.html"><spanclass="doc std std-doc">Typeclassed</span></a> entities.</p>
<p>An Evennia Object is, by definition, a Python class that includes
<aclass="reference internal"href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject"title="evennia.objects.objects.DefaultObject"><spanclass="xref myst py py-class">evennia.objects.objects.DefaultObject</span></a> among its
parents. Evennia defines several subclasses of <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>:</p>
the normal in-game Character, controlled by a player.</p></li>
<li><p><aclass="reference internal"href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultRoom"title="evennia.objects.objects.DefaultRoom"><spanclass="xref myst py py-class">evennia.objects.objects.DefaultRoom</span></a> - a location in the game world.</p></li>
<li><p><aclass="reference internal"href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultExit"title="evennia.objects.objects.DefaultExit"><spanclass="xref myst py py-class">evennia.objects.objects.DefaultExit</span></a> - an entity that (usually) sits
in a room and represents a one-way connection to another location.</p></li>
</ul>
<p>You will usually not use the <codeclass="docutils literal notranslate"><spanclass="pre">Default*</span></code> parents themselves. In <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/</span></code> there are
convenient subclasses to use. They are empty, and thus identical to
the defaults. Tweaking them is one of the main ways to customize you game!</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">mygame.typeclasses.objects.Object</span></code> (inherits from <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>)</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">mygame.typeclasses.characters.Character</span></code> (inherits from <codeclass="docutils literal notranslate"><spanclass="pre">DefaultCharacter</span></code>)</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">mygame.typeclasses.rooms.Room</span></code> (inherits from <codeclass="docutils literal notranslate"><spanclass="pre">DefaultRoom</span></code>)</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">mygame.typeclasses.exits.Exit</span></code> (inherits from <codeclass="docutils literal notranslate"><spanclass="pre">DefaultExit</span></code>)</p></li>
</ul>
<sectionid="how-to-create-your-own-object-types">
<h2>How to create your own object types<aclass="headerlink"href="#how-to-create-your-own-object-types"title="Permalink to this headline">¶</a></h2>
<p>You can easily add your own in-game behavior by either modifying one of the typeclasses in
your game dir or by inheriting from them.</p>
<p>You can put your new typeclass directly in the relevant parent
module, or you could organize your code in some other way. Here we assume we make a new module
<spanclass="s2">"this is called only once, when object is first created"</span>
<spanclass="c1"># add a persistent attribute 'desc'</span>
<spanclass="c1"># to object (silly example).</span>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">db</span><spanclass="o">.</span><spanclass="n">desc</span><spanclass="o">=</span><spanclass="s2">"This is a pretty rose with thorns."</span>
</pre></div>
</div>
<p>Now you just need to point to the class <em>Rose</em> with the <codeclass="docutils literal notranslate"><spanclass="pre">create</span></code> command
<p>What the <codeclass="docutils literal notranslate"><spanclass="pre">create</span></code> command actually <em>does</em> is to use the <aclass="reference internal"href="../api/evennia.utils.create.html#evennia.utils.create.create_object"title="evennia.utils.create.create_object"><spanclass="xref myst py py-func">evennia.create_object</span></a>
function. You can do the same thing yourself in code:</p>
<p>(The <codeclass="docutils literal notranslate"><spanclass="pre">create</span></code> command will auto-append the most likely path to your typeclass, if you enter the
call manually you have to give the full path to the class. The <codeclass="docutils literal notranslate"><spanclass="pre">create.create_object</span></code> function is
powerful and should be used for all coded object creating (so this is what you use when defining
your own building commands).</p>
<p>This particular Rose class doesn’t really do much, all it does it make sure the attribute
<codeclass="docutils literal notranslate"><spanclass="pre">desc</span></code>(which is what the <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code> command looks for) is pre-set, which is pretty pointless since you
will usually want to change this at build time (using the <codeclass="docutils literal notranslate"><spanclass="pre">desc</span></code> command or using the
<h2>Adding common functionality<aclass="headerlink"href="#adding-common-functionality"title="Permalink to this headline">¶</a></h2>
<p><codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">Character</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">Room</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">Exit</span></code> also inherit from <codeclass="docutils literal notranslate"><spanclass="pre">mygame.typeclasses.objects.ObjectParent</span></code>.
This is an empty ‘mixin’ class. Optionally, you can modify this class if you want to easily add some <em>common</em> functionality to all
your Objects, Characters, Rooms and Exits at once. You can still customize each subclass separately (see the Python
docs on <aclass="reference external"href="https://docs.python.org/3/tutorial/classes.html#multiple-inheritance">multiple inheritance</a> for details).</p>
<p>For example:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in mygame/typeclasses/objects.py</span>
<h2>Properties and functions on Objects<aclass="headerlink"href="#properties-and-functions-on-objects"title="Permalink to this headline">¶</a></h2>
<p>Beyond the properties assigned to all <aclass="reference internal"href="Typeclasses.html"><spanclass="doc std std-doc">typeclassed</span></a> objects (see that page for a list
of those), the Object also has the following custom properties:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">aliases</span></code> - a handler that allows you to add and remove aliases from this object. Use
<codeclass="docutils literal notranslate"><spanclass="pre">aliases.add()</span></code> to add a new alias and <codeclass="docutils literal notranslate"><spanclass="pre">aliases.remove()</span></code> to remove one.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">location</span></code> - a reference to the object currently containing this object.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">home</span></code> is a backup location. The main motivation is to have a safe place to move the object to if
its <codeclass="docutils literal notranslate"><spanclass="pre">location</span></code> is destroyed. All objects should usually have a home location for safety.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">destination</span></code> - this holds a reference to another object this object links to in some way. Its
main use is for <aclass="reference internal"href="#exits"><spanclass="std std-doc">Exits</span></a>, it’s otherwise usually unset.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">nicks</span></code> - as opposed to aliases, a <aclass="reference internal"href="Nicks.html"><spanclass="doc std std-doc">Nick</span></a> holds a convenient nickname replacement for a
real name, word or sequence, only valid for this object. This mainly makes sense if the Object is
used as a game character - it can then store briefer shorts, example so as to quickly reference game
commands or other characters. Use nicks.add(alias, realname) to add a new one.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">account</span></code> - this holds a reference to a connected <aclass="reference internal"href="Accounts.html"><spanclass="doc std std-doc">Account</span></a> controlling this object (if
any). Note that this is set also if the controlling account is <em>not</em> currently online - to test if
an account is online, use the <codeclass="docutils literal notranslate"><spanclass="pre">has_account</span></code> property instead.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">sessions</span></code> - if <codeclass="docutils literal notranslate"><spanclass="pre">account</span></code> field is set <em>and the account is online</em>, this is a list of all active
sessions (server connections) to contact them through (it may be more than one if multiple
connections are allowed in settings).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">has_account</span></code> - a shorthand for checking if an <em>online</em> account is currently connected to this
object.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">contents</span></code> - this returns a list referencing all objects ‘inside’ this object (i,e. which has this
object set as their <codeclass="docutils literal notranslate"><spanclass="pre">location</span></code>).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">exits</span></code> - this returns all objects inside this object that are <em>Exits</em>, that is, has the
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">cmdset</span></code> - this is a handler that stores all <aclass="reference internal"href="Command-Sets.html"><spanclass="doc std std-doc">command sets</span></a> defined on the
object (if any).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">scripts</span></code> - this is a handler that manages <aclass="reference internal"href="Scripts.html"><spanclass="doc std std-doc">Scripts</span></a> attached to the object (if any).</p></li>
</ul>
<p>The Object also has a host of useful utility functions. See the function headers in
<codeclass="docutils literal notranslate"><spanclass="pre">src/objects/objects.py</span></code> for their arguments and more details.</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">msg()</span></code> - this function is used to send messages from the server to an account connected to this
object.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">msg_contents()</span></code> - calls <codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code> on all objects inside this object.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">search()</span></code> - this is a convenient shorthand to search for a specific object, at a given location
or globally. It’s mainly useful when defining commands (in which case the object executing the
command is named <codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> and one can do <codeclass="docutils literal notranslate"><spanclass="pre">caller.search()</span></code> to find objects in the room to operate
on).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">execute_cmd()</span></code> - Lets the object execute the given string as if it was given on the command line.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">move_to</span></code> - perform a full move of this object to a new location. This is the main move method
and will call all relevant hooks, do all checks etc.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">clear_exits()</span></code> - will delete all <aclass="reference internal"href="#exits"><spanclass="std std-doc">Exits</span></a> to <em>and</em> from this object.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">clear_contents()</span></code> - this will not delete anything, but rather move all contents (except Exits) to
their designated <codeclass="docutils literal notranslate"><spanclass="pre">Home</span></code> locations.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">delete()</span></code> - deletes this object, first calling <codeclass="docutils literal notranslate"><spanclass="pre">clear_exits()</span></code> and
<p>The Object Typeclass defines many more <em>hook methods</em> beyond <codeclass="docutils literal notranslate"><spanclass="pre">at_object_creation</span></code>. Evennia calls
these hooks at various points. When implementing your custom objects, you will inherit from the
base parent and overload these hooks with your own custom code. See <codeclass="docutils literal notranslate"><spanclass="pre">evennia.objects.objects</span></code> for an
updated list of all the available hooks or the <aclass="reference internal"href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject"title="evennia.objects.objects.DefaultObject"><spanclass="xref myst py py-class">API for DefaultObject here</span></a>.</p>
</section>
<sectionid="subclasses-of-object">
<h2>Subclasses of <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code><aclass="headerlink"href="#subclasses-of-object"title="Permalink to this headline">¶</a></h2>
<p>There are three special subclasses of <em>Object</em> in default Evennia - <em>Characters</em>, <em>Rooms</em> and
<em>Exits</em>. The reason they are separated is because these particular object types are fundamental,
something you will always need and in some cases requires some extra attention in order to be
recognized by the game engine (there is nothing stopping you from redefining them though). In
practice they are all pretty similar to the base Object.</p>
<sectionid="characters">
<h3>Characters<aclass="headerlink"href="#characters"title="Permalink to this headline">¶</a></h3>
<p>Characters are objects controlled by <aclass="reference internal"href="Accounts.html"><spanclass="doc std std-doc">Accounts</span></a>. When a new Account
logs in to Evennia for the first time, a new <codeclass="docutils literal notranslate"><spanclass="pre">Character</span></code> object is created and
the Account object is assigned to the <codeclass="docutils literal notranslate"><spanclass="pre">account</span></code> attribute. A <codeclass="docutils literal notranslate"><spanclass="pre">Character</span></code> object
must have a <aclass="reference internal"href="Command-Sets.html"><spanclass="doc std std-doc">Default Commandset</span></a> set on itself at
creation, or the account will not be able to issue any commands! If you just
inherit your own class from <codeclass="docutils literal notranslate"><spanclass="pre">evennia.DefaultCharacter</span></code> and make sure to use
<codeclass="docutils literal notranslate"><spanclass="pre">super()</span></code> to call the parent methods you should be fine. In
<codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/characters.py</span></code> is an empty <codeclass="docutils literal notranslate"><spanclass="pre">Character</span></code> class ready for you
to modify.</p>
</section>
<sectionid="rooms">
<h3>Rooms<aclass="headerlink"href="#rooms"title="Permalink to this headline">¶</a></h3>
<p><em>Rooms</em> are the root containers of all other objects. The only thing really separating a room from
any other object is that they have no <codeclass="docutils literal notranslate"><spanclass="pre">location</span></code> of their own and that default commands like <codeclass="docutils literal notranslate"><spanclass="pre">@dig</span></code>
creates objects of this class - so if you want to expand your rooms with more functionality, just
inherit from <codeclass="docutils literal notranslate"><spanclass="pre">ev.DefaultRoom</span></code>. In <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/rooms.py</span></code> is an empty <codeclass="docutils literal notranslate"><spanclass="pre">Room</span></code> class ready for
you to modify.</p>
</section>
<sectionid="exits">
<h3>Exits<aclass="headerlink"href="#exits"title="Permalink to this headline">¶</a></h3>
<p><em>Exits</em> are objects connecting other objects (usually <em>Rooms</em>) together. An object named <em>North</em> or
<em>in</em> might be an exit, as well as <em>door</em>, <em>portal</em> or <em>jump out the window</em>. An exit has two things
that separate them from other objects. Firstly, their <em>destination</em> property is set and points to a
valid object. This fact makes it easy and fast to locate exits in the database. Secondly, exits
define a special <aclass="reference internal"href="Commands.html"><spanclass="doc std std-doc">Transit Command</span></a> on themselves when they are created. This command is
named the same as the exit object and will, when called, handle the practicalities of moving the
character to the Exits’s <em>destination</em> - this allows you to just enter the name of the exit on its
own to move around, just as you would expect.</p>
<p>The exit functionality is all defined on the Exit typeclass, so you could in principle completely
change how exits work in your game (it’s not recommended though, unless you really know what you are
doing). Exits are <aclass="reference internal"href="Locks.html"><spanclass="doc std std-doc">locked</span></a> using an access_type called <em>traverse</em> and also make use of a few
hook methods for giving feedback if the traversal fails. See <codeclass="docutils literal notranslate"><spanclass="pre">evennia.DefaultExit</span></code> for more info.
In <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/exits.py</span></code> there is an empty <codeclass="docutils literal notranslate"><spanclass="pre">Exit</span></code> class for you to modify.</p>
<p>The process of traversing an exit is as follows:</p>
<olclass="simple">
<li><p>The traversing <codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code> sends a command that matches the Exit-command name on the Exit object. The
<aclass="reference internal"href="Commands.html"><spanclass="doc std std-doc">cmdhandler</span></a> detects this and triggers the command defined on the Exit. Traversal always
involves the “source” (the current location) and the <codeclass="docutils literal notranslate"><spanclass="pre">destination</span></code> (this is stored on the Exit
object).</p></li>
<li><p>The Exit command checks the <codeclass="docutils literal notranslate"><spanclass="pre">traverse</span></code> lock on the Exit object</p></li>
<li><p>The Exit command triggers <codeclass="docutils literal notranslate"><spanclass="pre">at_traverse(obj,</span><spanclass="pre">destination)</span></code> on the Exit object.</p></li>
<li><p>In <codeclass="docutils literal notranslate"><spanclass="pre">at_traverse</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">object.move_to(destination)</span></code> is triggered. This triggers the following hooks,
in order:</p>
<olclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">obj.at_pre_move(destination)</span></code> - if this returns False, move is aborted.</p></li>
<li><p>Move is performed by changing <codeclass="docutils literal notranslate"><spanclass="pre">obj.location</span></code> from source location to <codeclass="docutils literal notranslate"><spanclass="pre">destination</span></code>.</p></li>
<li><p>On the Exit object, <codeclass="docutils literal notranslate"><spanclass="pre">at_post_traverse(obj,</span><spanclass="pre">source)</span></code> is triggered.</p></li>
</ol>
<p>If the move fails for whatever reason, the Exit will look for an Attribute <codeclass="docutils literal notranslate"><spanclass="pre">err_traverse</span></code> on itself
and display this as an error message. If this is not found, the Exit will instead call
<codeclass="docutils literal notranslate"><spanclass="pre">at_failed_traverse(obj)</span></code> on itself.</p>
