<h1>Coding Utils<aclass="headerlink"href="#coding-utils"title="Permalink to this headline">¶</a></h1>
<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>
<div><p>This is just a small selection of the tools in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/utils</span></code>. It’s worth to browse <aclass="reference internal"href="../api/evennia.utils.html#evennia-utils"><spanclass="std std-ref">the directory</span></a> and in particular the content of <aclass="reference internal"href="../api/evennia.utils.utils.html#evennia-utils-utils"><spanclass="std std-ref">evennia/utils/utils.py</span></a> directly to find more useful stuff.</p>
<h2>Searching<aclass="headerlink"href="#searching"title="Permalink to this headline">¶</a></h2>
<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 zero entries.</p>
<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>Each of these create-functions have a host of arguments to further customize the created entity. See <codeclass="docutils literal notranslate"><spanclass="pre">evennia/utils/create.py</span></code> for more information.</p>
<h2>Logging<aclass="headerlink"href="#logging"title="Permalink to this headline">¶</a></h2>
<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>See also the <aclass="reference internal"href="../Coding/Debugging.html"><spanclass="doc std std-doc">Debugging</span></a> documentation for help with finding elusive bugs.</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> shortcut:</p>
<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.
You can also <em>schedule</em> things to happen at specific in-game times using the <aclass="reference internal"href="../api/evennia.utils.gametime.html#evennia.utils.gametime.schedule"title="evennia.utils.gametime.schedule"><spanclass="xref myst py py-func">gametime.schedule</span></a> function:</p>
<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>
</ul>
</section>
<sectionid="utils-delay">
<h3>utils.delay()<aclass="headerlink"href="#utils-delay"title="Permalink to this headline">¶</a></h3>
<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
<p>Note that Python code should usually work with <aclass="reference external"href="https://en.wikipedia.org/wiki/Duck_typing">duck typing</a>. But in Evennia’s case it can sometimes be useful 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 for example that we have a typeclass <em>Animal</em>. This has a subclass <em>Felines</em> which in turn has a subclass <em>HouseCat</em>. Maybe there are a bunch of other animal types too, like horses and dogs. Using <codeclass="docutils literal notranslate"><spanclass="pre">inherits_from</span></code> will allow you to check for all animals in one go:</p>
<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>
</pre></div>
</div>
</section>
</section>
<sectionid="text-utilities">
<h2>Text utilities<aclass="headerlink"href="#text-utilities"title="Permalink to this headline">¶</a></h2>
<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>
<sectionid="utils-fill">
<h3>utils.fill()<aclass="headerlink"href="#utils-fill"title="Permalink to this headline">¶</a></h3>
<h3>utils.crop()<aclass="headerlink"href="#utils-crop"title="Permalink to this headline">¶</a></h3>
<p>This function will crop a very long line, adding a suffix to show the line actually continues. This
can be useful in listings when showing multiple lines would mess up things.</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>
<p>This solves what may at first glance appear to be a trivial problem with text - removing indentations. It is used to shift entire paragraphs to the left, without disturbing any further formatting they may have. A common case for this is when using Python triple-quoted strings in code - they will retain whichever indentation they have in the code, and to make easily-readable source code one usually don’t want to shift the string to the left edge.</p>
<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 <aclass="reference internal"href="../Concepts/Text-Encodings.html"><spanclass="doc std std-doc">here</span></a> for more info.</p>
