<p>Evennia comes with many utilities to help with common coding tasks. Most are accessible directly
from the flat API, otherwise you can find them in the <codeclass="docutils literal notranslate"><spanclass="pre">evennia/utils/</span></code> folder.</p>
<p>A common thing to do is to search for objects. There it’s easiest to use the <codeclass="docutils literal notranslate"><spanclass="pre">search</span></code> method defined
on all objects. This will search for objects in the same location and inside the self object:</p>
<p>The most common time one needs to do this is inside a command body. <codeclass="docutils literal notranslate"><spanclass="pre">obj</span><spanclass="pre">=</span><spanclass="pre">self.caller.search(objname)</span></code> will search inside the caller’s (typically, the character that typed
the command) <codeclass="docutils literal notranslate"><spanclass="pre">.contents</span></code> (their “inventory”) and <codeclass="docutils literal notranslate"><spanclass="pre">.location</span></code> (their “room”).</p>
<p>Give the keyword <codeclass="docutils literal notranslate"><spanclass="pre">global_search=True</span></code> to extend search to encompass entire database. Aliases will
also be matched by this search. You will find multiple examples of this functionality in the default
command set.</p>
<p>If you need to search for objects in a code module you can use the functions in
<codeclass="docutils literal notranslate"><spanclass="pre">evennia.utils.search</span></code>. You can access these as shortcuts <codeclass="docutils literal notranslate"><spanclass="pre">evennia.search_*</span></code>.</p>
<p>Note that these latter methods will always return a <codeclass="docutils literal notranslate"><spanclass="pre">list</span></code> of results, even if the list has one or
<p>Apart from the in-game build commands (<codeclass="docutils literal notranslate"><spanclass="pre">@create</span></code> etc), you can also build all of Evennia’s game
entities directly in code (for example when defining new create commands).</p>
<p>Normally you can use Python <codeclass="docutils literal notranslate"><spanclass="pre">print</span></code> statements to see output to the terminal/log. The <codeclass="docutils literal notranslate"><spanclass="pre">print</span></code>
statement should only be used for debugging though. For producion output, use the <codeclass="docutils literal notranslate"><spanclass="pre">logger</span></code> which
will create proper logs either to terminal or to file.</p>
<spanclass="n">logger</span><spanclass="o">.</span><spanclass="n">log_err</span><spanclass="p">(</span><spanclass="s2">"This is an Error!"</span><spanclass="p">)</span>
<spanclass="n">logger</span><spanclass="o">.</span><spanclass="n">log_warn</span><spanclass="p">(</span><spanclass="s2">"This is a Warning!"</span><spanclass="p">)</span>
<spanclass="n">logger</span><spanclass="o">.</span><spanclass="n">log_info</span><spanclass="p">(</span><spanclass="s2">"This is normal information"</span><spanclass="p">)</span>
<spanclass="n">logger</span><spanclass="o">.</span><spanclass="n">log_dep</span><spanclass="p">(</span><spanclass="s2">"This feature is deprecated"</span><spanclass="p">)</span>
<p>There is a special log-message type, <codeclass="docutils literal notranslate"><spanclass="pre">log_trace()</span></code> that is intended to be called from inside a
traceback - this can be very useful for relaying the traceback message back to log without having it
<spanclass="n">logger</span><spanclass="o">.</span><spanclass="n">log_trace</span><spanclass="p">(</span><spanclass="s2">"This text will show beneath the traceback itself."</span><spanclass="p">)</span>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">log_file</span></code> logger, finally, is a very useful logger for outputting arbitrary log messages. This
is a heavily optimized asynchronous log mechanism using
<aclass="reference external"href="https://en.wikipedia.org/wiki/Thread_%28computing%29">threads</a> to avoid overhead. You should be
able to use it for very heavy custom logging without fearing disk-write delays.</p>
<p>If not an absolute path is given, the log file will appear in the <codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/logs/</span></code> directory.
If the file already exists, it will be appended to. Timestamps on the same format as the normal
Evennia logs will be automatically added to each entry. If a filename is not specified, output will
be written to a file <codeclass="docutils literal notranslate"><spanclass="pre">game/logs/game.log</span></code>.</p>
<p>Evennia tracks the current server time. You can access this time via the <codeclass="docutils literal notranslate"><spanclass="pre">evennia.gametime</span></code>
<p>The setting <codeclass="docutils literal notranslate"><spanclass="pre">TIME_FACTOR</span></code> determines how fast/slow in-game time runs compared to the real world. The
setting <codeclass="docutils literal notranslate"><spanclass="pre">TIME_GAME_EPOCH</span></code> sets the starting game epoch (in seconds). The functions from the
<codeclass="docutils literal notranslate"><spanclass="pre">gametime</span></code> module all return their times in seconds. You can convert this to whatever units of time
you desire for your game. You can use the <codeclass="docutils literal notranslate"><spanclass="pre">@time</span></code> command to view the server time info.</p>
<p>You can also <em>schedule</em> things to happen at specific in-game times using the
<spanclass="n">limbo</span><spanclass="o">.</span><spanclass="n">msg_contents</span><spanclass="p">(</span><spanclass="s2">"The church clock chimes two."</span><spanclass="p">)</span>
<p>This function takes a number of seconds as input (e.g. from the <codeclass="docutils literal notranslate"><spanclass="pre">gametime</span></code> module above) and
converts it to a nice text output in days, hours etc. It’s useful when you want to show how old
something is. It converts to four different styles of output using the <em>style</em> keyword:</p>
<li><p>style 1 - <codeclass="docutils literal notranslate"><spanclass="pre">5d</span></code> (shows only the longest time unit)</p></li>
<li><p>style 2 - <codeclass="docutils literal notranslate"><spanclass="pre">5</span><spanclass="pre">days,</span><spanclass="pre">45</span><spanclass="pre">minutes</span></code> (full format, ignores seconds)</p></li>
<li><p>style 3 - <codeclass="docutils literal notranslate"><spanclass="pre">5</span><spanclass="pre">days,</span><spanclass="pre">45</span><spanclass="pre">minutes,</span><spanclass="pre">12</span><spanclass="pre">seconds</span></code> (full format, with seconds)</p></li>
<p>This creates an asynchronous delayed call. It will fire the given callback function after the given
number of seconds. This is a very light wrapper over a Twisted
<aclass="reference external"href="https://twistedmatrix.com/documents/current/core/howto/defer.html">Deferred</a>. Normally this is run
non-persistently, which means that if the server is <codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code>ed before the delay is over, the
callback will never run (the server forgets it). If setting <codeclass="docutils literal notranslate"><spanclass="pre">persistent</span></code> to True, the delay will be
stored in the database and survive a <codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code> - but for this to work it is susceptible to the same
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">deferred</span></code> return object can usually be ignored, but calling its <codeclass="docutils literal notranslate"><spanclass="pre">.cancel()</span></code> method will abort
the delay prematurely.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">utils.delay</span></code> is the lightest form of delayed call in Evennia. For other way to create time-bound
tasks, see the <aclass="reference internal"href="TickerHandler.html"><spanclass="doc std std-doc">TickerHandler</span></a> and <aclass="reference internal"href="Scripts.html"><spanclass="doc std std-doc">Scripts</span></a>.</p>
<p>This useful function takes two arguments - an object to check and a parent. It returns <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> if
object inherits from parent <em>at any distance</em> (as opposed to Python’s in-built <codeclass="docutils literal notranslate"><spanclass="pre">is_instance()</span></code> that
will only catch immediate dependence). This function also accepts as input any combination of
classes, instances or python-paths-to-classes.</p>
to check if an object inherits from a given <aclass="reference internal"href="Typeclasses.html"><spanclass="doc std std-doc">Typeclass</span></a> as a way of identification. Say
<spanclass="n">obj</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"The bouncer stops you in the door. He says: 'No talking animals allowed.'"</span><spanclass="p">)</span>
<p>In a text game, you are naturally doing a lot of work shuffling text back and forth. Here is a <em>non-
complete</em> selection of text utilities found in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/utils/utils.py</span></code> (shortcut <codeclass="docutils literal notranslate"><spanclass="pre">evennia.utils</span></code>).
If nothing else it can be good to look here before starting to develop a solution of your own.</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="n">intxt</span><spanclass="o">=</span><spanclass="s2">"This is a long text that we want to crop."</span>
<h3>to_str() and to_bytes()<aclass="headerlink"href="#to-str-and-to-bytes"title="Permalink to this headline">¶</a></h3>
<p>Evennia supplies two utility functions for converting text to the correct
encodings. <codeclass="docutils literal notranslate"><spanclass="pre">to_str()</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">to_bytes()</span></code>. Unless you are adding a custom protocol and
need to send byte-data over the wire, <codeclass="docutils literal notranslate"><spanclass="pre">to_str</span></code> is the only one you’ll need.</p>
<p>The difference from Python’s in-built <codeclass="docutils literal notranslate"><spanclass="pre">str()</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">bytes()</span></code> operators are that
the Evennia ones makes use of the <codeclass="docutils literal notranslate"><spanclass="pre">ENCODINGS</span></code> setting and will try very hard to
never raise a traceback but instead echo errors through logging. See
<p>The <aclass="reference internal"href="../api/evennia.utils.evtable.html#evennia.utils.evtable.EvTable"title="evennia.utils.evtable.EvTable"><spanclass="xref myst py py-class">EvTable</span></a> class (<codeclass="docutils literal notranslate"><spanclass="pre">evennia/utils/evtable.py</span></code>) can be used
text template from a file in order to create any level of sophisticated ascii layout. Both evtable
and evform have lots of options and inputs so see the header of each module for help.</p>
<p>The third-party <aclass="reference external"href="https://code.google.com/p/prettytable/">PrettyTable</a> module is also included in
Evennia. PrettyTable is considered deprecated in favor of EvTable since PrettyTable cannot handle
ANSI colour. PrettyTable can be found in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/utils/prettytable/</span></code>. See its homepage above for
