<p>All in-game objects in Evennia, be it characters, chairs, monsters, rooms or hand grenades are jointly referred to as an Evennia <em>Object</em>. An Object is generally something you can look and interact with in the game world. When a message travels from the client, the Object-level is the last stop.</p>
<p>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>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code> - the base in-game entity. Found in <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/objects.py</span></code>. Inherits directly from <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>.</p></li>
<li><p><aclass="reference internal"href="Characters.html"><spanclass="doc std std-doc">Characters</span></a> - the normal in-game Character, controlled by a player. Found in <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/characters.py</span></code>. Inherits from <codeclass="docutils literal notranslate"><spanclass="pre">DefaultCharacter</span></code>, which is turn a child of <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>.</p></li>
<li><p><aclass="reference internal"href="Rooms.html"><spanclass="doc std std-doc">Rooms</span></a> - a location in the game world. Found in <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/rooms.py</span></code>. Inherits from <codeclass="docutils literal notranslate"><spanclass="pre">DefaultRoom</span></code>, which is in turn a child of <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>).</p></li>
<li><p><aclass="reference internal"href="Exits.html"><spanclass="doc std std-doc">Exits</span></a> - represents a one-way connection to another location. Found in <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/exits.py</span></code> (inherits from <codeclass="docutils literal notranslate"><spanclass="pre">DefaultExit</span></code>, which is in turn a child of <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>).</p></li>
</ul>
<sectionid="object">
<h2>Object<aclass="headerlink"href="#object"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code> class is meant to be used as the basis for creating things that are neither characters, rooms or exits - anything from weapons and armour, equipment and houses can be represented by extending the Object class. Depending on your game, this also goes for NPCs and monsters (in some games you may want to treat NPCs as just an un-puppeted <aclass="reference internal"href="Characters.html"><spanclass="doc std std-doc">Character</span></a> instead).</p>
<p>You should not use Objects for game <em>systems</em>. Don’t use an ‘invisible’ Object for tracking weather, combat, economy or guild memberships - that’s what <aclass="reference internal"href="Scripts.html"><spanclass="doc std std-doc">Scripts</span></a> are for.</p>
<h2>ObjectParent - Adding common functionality<aclass="headerlink"href="#objectparent-adding-common-functionality"title="Permalink to this headline">¶</a></h2>
<p><codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code>, as well as <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> classes all additionally inherit from <codeclass="docutils literal notranslate"><spanclass="pre">mygame.typeclasses.objects.ObjectParent</span></code>.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">ObjectParent</span></code> is an empty ‘mixin’ class. You can add stuff to this class that you want <em>all</em> in-game entities to have.</p>
<p>Here is an example:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in mygame/typeclasses/objects.py</span>
<p>Now all of <codeclass="docutils literal notranslate"><spanclass="pre">Object</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">Exit</span></code>. <codeclass="docutils literal notranslate"><spanclass="pre">Room</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">Character</span></code> default to not being able to be picked up using the <codeclass="docutils literal notranslate"><spanclass="pre">get</span></code> command.</p>
<h2>Working with children of DefaultObject<aclass="headerlink"href="#working-with-children-of-defaultobject"title="Permalink to this headline">¶</a></h2>
<p>This functionality is shared by all sub-classes of <codeclass="docutils literal notranslate"><spanclass="pre">DefaultObject</span></code>. You can easily add your own in-game behavior by either modifying one of the typeclasses in your game dir or by inheriting further from them.</p>
<p>You can put your new typeclass directly in the relevant module, or you could organize your code in some other way. Here we assume we make a new module <codeclass="docutils literal notranslate"><spanclass="pre">mygame/typeclasses/flowers.py</span></code>:</p>
<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 to make a new rose:</p>
<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 <aclass="reference internal"href="Prototypes.html"><spanclass="doc std std-doc">Spawner</span></a>).</p>
<h3>Properties and functions on Objects<aclass="headerlink"href="#properties-and-functions-on-objects"title="Permalink to this headline">¶</a></h3>
<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.html"><spanclass="doc 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 <codeclass="docutils literal notranslate"><spanclass="pre">destination</span></code> property set.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">appearance_template</span></code> - this helps formatting the look of the Object when someone looks at it (see next section).l</p></li>
<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.html"><spanclass="doc 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 <codeclass="docutils literal notranslate"><spanclass="pre">clear_contents()</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">return_appearance</span></code> is the main hook letting the object visually describe itself.</p></li>
<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>
<h2>Changing an Object’s appearance<aclass="headerlink"href="#changing-an-objects-appearance"title="Permalink to this headline">¶</a></h2>
<p>When you type <codeclass="docutils literal notranslate"><spanclass="pre">look</span><spanclass="pre"><obj></span></code>, this is the sequence of events that happen:</p>
<ol>
<li><p>The command checks if the <codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> of the command (the ‘looker’) passes the <codeclass="docutils literal notranslate"><spanclass="pre">view</span></code><aclass="reference internal"href="Locks.html"><spanclass="doc std std-doc">lock</span></a> of the target <codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code>. If not, they will not find anything to look at (this is how you make objects invisible).</p></li>
<li><p>The <codeclass="docutils literal notranslate"><spanclass="pre">look</span></code> command calls <codeclass="docutils literal notranslate"><spanclass="pre">caller.at_look(obj)</span></code> - that is, the <codeclass="docutils literal notranslate"><spanclass="pre">at_look</span></code> hook on the ‘looker’ (the caller of the command) is called to perform the look on the target object. The command will echo whatever this hook returns.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">caller.at_look</span></code> calls and returns the outcome of <codeclass="docutils literal notranslate"><spanclass="pre">obj.return_apperance(looker,</span><spanclass="pre">**kwargs)</span></code>. Here <codeclass="docutils literal notranslate"><spanclass="pre">looker</span></code> is the <codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> of the command. In other words, we ask the <codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code> to descibe itself to <codeclass="docutils literal notranslate"><spanclass="pre">looker</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">obj.return_appearance</span></code> makes use of its <codeclass="docutils literal notranslate"><spanclass="pre">.appearance_template</span></code> property and calls a slew of helper-hooks to populate this template. This is how the template looks by default:</p>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">header</span></code> -><codeclass="docutils literal notranslate"><spanclass="pre">obj.get_display_header(looker,</span><spanclass="pre">**kwargs)</span></code> - empty by default.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">footer</span></code> -><codeclass="docutils literal notranslate"><spanclass="pre">obj.get_display_footer(looker,</span><spanclass="pre">**kwargs)</span></code> - empty by default.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">exits</span></code> -><codeclass="docutils literal notranslate"><spanclass="pre">obj.get_display_exits(looker,</span><spanclass="pre">**kwargs)</span></code> - a list of <codeclass="docutils literal notranslate"><spanclass="pre">DefaultExit</span></code>-inheriting objects found inside this object (usually only present if <codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code> is a <codeclass="docutils literal notranslate"><spanclass="pre">Room</span></code>).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">characters</span></code> -><codeclass="docutils literal notranslate"><spanclass="pre">obj.get_display_characters(looker,</span><spanclass="pre">**kwargs)</span></code> - a list of <codeclass="docutils literal notranslate"><spanclass="pre">DefaultCharacter</span></code>-inheriting entities inside this object.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">things</span></code> -><codeclass="docutils literal notranslate"><spanclass="pre">obj.get_display_things(looker,</span><spanclass="pre">**kwargs)</span></code> - a list of all other Objects inside <codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code>.</p></li>
</ul>
</li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">obj.format_appearance(string,</span><spanclass="pre">looker,</span><spanclass="pre">**kwargs)</span></code> is the last step the populated template string goes through. This can be used for final adjustments, such as stripping whitespace. The return from this method is what the user will see.</p></li>
<p>As each of these hooks (and the template itself) can be overridden in your child class, you can customize your look extensively. You can also have objects look different depending on who is looking at them. The extra <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code> are not used by default, but are there to allow you to pass extra data into the system if you need it (like light conditions etc.)</p>
