<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>
<divclass="section"id="searching">
<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>
</div>
<divclass="section"id="create">
<h2>Create<aclass="headerlink"href="#create"title="Permalink to this headline">¶</a></h2>
<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>
</div>
<divclass="section"id="logging">
<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>
</pre></div>
</td></tr></table></div>
<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 kill the server.</p>
<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>
</pre></div>
</td></tr></table></div>
<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>
</div>
<divclass="section"id="time-utilities">
<h2>Time Utilities<aclass="headerlink"href="#time-utilities"title="Permalink to this headline">¶</a></h2>
<divclass="section"id="game-time">
<h3>Game time<aclass="headerlink"href="#game-time"title="Permalink to this headline">¶</a></h3>
<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.</p>
<p>You can also <em>schedule</em> things to happen at specific in-game times using the <aclass="reference external"href="https://github.com/evennia/evennia/blob/master/evennia.utils.gametime#schedule">gametime.schedule</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>
<h3>utils.time_format()<aclass="headerlink"href="#utils-time-format"title="Permalink to this headline">¶</a></h3>
<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>
</div>
<divclass="section"id="utils-delay">
<h3>utils.delay()<aclass="headerlink"href="#utils-delay"title="Permalink to this headline">¶</a></h3>
<spanclass="c1"># code here will run immediately, not waiting for the delay to fire!</span>
</pre></div>
</td></tr></table></div>
<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 limitations incurred when saving to an <aclass="reference internal"href="Attributes.html"><spanclass="doc">Attribute</span></a>.</p>
<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">TickerHandler</span></a> and <aclass="reference internal"href="Scripts.html"><spanclass="doc">Scripts</span></a>.</p>
<blockquote>
<div><p>Note that many delayed effects can be achieved without any need for an active timer. For example if you have a trait that should recover a point every 5 seconds you might just need its value when it’s needed, but checking the current time and calculating on the fly what value it should have.</p>
</div></blockquote>
</div>
</div>
<divclass="section"id="object-classes">
<h2>Object Classes<aclass="headerlink"href="#object-classes"title="Permalink to this headline">¶</a></h2>
<divclass="section"id="utils-inherits-from">
<h3>utils.inherits_from()<aclass="headerlink"href="#utils-inherits-from"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 will only catch immediate dependence). This function also accepts as input any combination of classes, instances or python-paths-to-classes.</p>
<p>Note that Python code should usually work with <aclass="reference external"href="http://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">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>
</td></tr></table></div>
</div>
</div>
<divclass="section"id="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>
<divclass="section"id="utils-fill">
<h3>utils.fill()<aclass="headerlink"href="#utils-fill"title="Permalink to this headline">¶</a></h3>
<p>This flood-fills a text to a given width (shuffles the words to make each line evenly wide). It also indents as needed.</p>
<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>
3</pre></div></td><tdclass="code"><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>
<spanclass="c1"># outtxt is now "This is a long text[...]"</span>
</pre></div>
</td></tr></table></div>
</div>
<divclass="section"id="utils-dedent">
<h3>utils.dedent()<aclass="headerlink"href="#utils-dedent"title="Permalink to this headline">¶</a></h3>
<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>
<spanclass="c1"># outtxt will now retain all internal indentation</span>
<spanclass="c1"># but be shifted all the way to the left.</span>
</pre></div>
</td></tr></table></div>
<p>Normally you do the dedent in the display code (this is for example how the help system homogenizes help entries).</p>
</div>
<divclass="section"id="to-str-and-to-bytes">
<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
<aclass="reference internal"href="Text-Encodings.html"><spanclass="doc">here</span></a> for more info.</p>
</div>
<divclass="section"id="ansi-coloring-tools">
<h3>Ansi Coloring Tools<aclass="headerlink"href="#ansi-coloring-tools"title="Permalink to this headline">¶</a></h3>
<h2>Display utilities<aclass="headerlink"href="#display-utilities"title="Permalink to this headline">¶</a></h2>
<divclass="section"id="making-ascii-tables">
<h3>Making ascii tables<aclass="headerlink"href="#making-ascii-tables"title="Permalink to this headline">¶</a></h3>
<p>The <aclass="reference external"href="https://github.com/evennia/evennia/blob/master/evennia.utils.evtable#evtable">EvTable</a> class (<codeclass="docutils literal notranslate"><spanclass="pre">evennia/utils/evtable.py</span></code>) can be used to create correctly formatted text tables. There is also <aclass="reference external"href="https://github.com/evennia/evennia/blob/master/evennia.utils.evform#evform">EvForm</a> (<codeclass="docutils literal notranslate"><spanclass="pre">evennia/utils/evform.py</span></code>). This reads a fixed-format 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 instructions.</p>
</div>
<divclass="section"id="menus">
<h3>Menus<aclass="headerlink"href="#menus"title="Permalink to this headline">¶</a></h3>
