<spanid="evennia-utils-gametime"></span><h1>evennia.utils.gametime<aclass="headerlink"href="#module-evennia.utils.gametime"title="Permalink to this headline">¶</a></h1>
<p>The gametime module handles the global passage of time in the mud.</p>
<p>It also supplies some useful methods to convert between
in-mud time and real-world time as well allows to get the
total runtime of the server and the current uptime.</p>
<dlclass="py class">
<dtid="evennia.utils.gametime.TimeScript">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.utils.gametime.</code><codeclass="sig-name descname">TimeScript</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#TimeScript"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.TimeScript"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">at_script_creation</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#TimeScript.at_script_creation"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.TimeScript.at_script_creation"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">at_repeat</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#TimeScript.at_repeat"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.TimeScript.at_repeat"title="Permalink to this definition">¶</a></dt>
<emclass="property">exception </em><codeclass="sig-name descname">DoesNotExist</code><aclass="headerlink"href="#evennia.utils.gametime.TimeScript.DoesNotExist"title="Permalink to this definition">¶</a></dt>
<emclass="property">exception </em><codeclass="sig-name descname">MultipleObjectsReturned</code><aclass="headerlink"href="#evennia.utils.gametime.TimeScript.MultipleObjectsReturned"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">path</code><emclass="property"> = 'evennia.utils.gametime.TimeScript'</em><aclass="headerlink"href="#evennia.utils.gametime.TimeScript.path"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">typename</code><emclass="property"> = 'TimeScript'</em><aclass="headerlink"href="#evennia.utils.gametime.TimeScript.typename"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.gametime.runtime">
<codeclass="sig-prename descclassname">evennia.utils.gametime.</code><codeclass="sig-name descname">runtime</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#runtime"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.runtime"title="Permalink to this definition">¶</a></dt>
<dd><p>Get the total runtime of the server since first start (minus
downtimes)</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>format</strong> (<em>bool</em><em>, </em><em>optional</em>) – Format into a time representation.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><p><em>time (float or tuple)</em>–</p>
<dlclass="simple">
<dt>The runtime or the same time split up</dt><dd><p>into time units.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.gametime.server_epoch">
<codeclass="sig-prename descclassname">evennia.utils.gametime.</code><codeclass="sig-name descname">server_epoch</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#server_epoch"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.server_epoch"title="Permalink to this definition">¶</a></dt>
<dd><p>Get the server epoch. We may need to calculate this on the fly.</p>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.gametime.uptime">
<codeclass="sig-prename descclassname">evennia.utils.gametime.</code><codeclass="sig-name descname">uptime</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#uptime"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.uptime"title="Permalink to this definition">¶</a></dt>
<dd><p>Get the current uptime of the server since last reload</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>format</strong> (<em>bool</em><em>, </em><em>optional</em>) – Format into time representation.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><p><em>time (float or tuple)</em>–</p>
<dlclass="simple">
<dt>The uptime or the same time split up</dt><dd><p>into time units.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.gametime.portal_uptime">
<codeclass="sig-prename descclassname">evennia.utils.gametime.</code><codeclass="sig-name descname">portal_uptime</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#portal_uptime"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.portal_uptime"title="Permalink to this definition">¶</a></dt>
<dd><p>Get the current uptime of the portal.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Returns</dt>
<ddclass="field-odd"><p><em>time (float)</em>– The uptime of the portal.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.gametime.game_epoch">
<codeclass="sig-prename descclassname">evennia.utils.gametime.</code><codeclass="sig-name descname">game_epoch</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#game_epoch"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.game_epoch"title="Permalink to this definition">¶</a></dt>
<dd><p>Get the game epoch.</p>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.gametime.gametime">
<codeclass="sig-prename descclassname">evennia.utils.gametime.</code><codeclass="sig-name descname">gametime</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">absolute</span><spanclass="o">=</span><spanclass="default_value">False</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#gametime"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.gametime"title="Permalink to this definition">¶</a></dt>
<dd><p>Get the total gametime of the server since first start (minus downtimes)</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>absolute</strong> (<em>bool</em><em>, </em><em>optional</em>) – Get the absolute game time, including
the epoch. This could be converted to an absolute in-game
date.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>time (float)</em>– The gametime as a virtual timestamp.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>If one is using a standard calendar, one could convert the unformatted
return to a date using Python’s standard <strong>datetime</strong> module like this:
<codeclass="sig-prename descclassname">evennia.utils.gametime.</code><codeclass="sig-name descname">real_seconds_until</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">sec</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">min</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">hour</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">day</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">month</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">year</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#real_seconds_until"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.real_seconds_until"title="Permalink to this definition">¶</a></dt>
<dd><p>Return the real seconds until game time.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>sec</strong> (<em>int</em><em> or </em><em>None</em>) – number of absolute seconds.</p></li>
<li><p><strong>min</strong> (<em>int</em><em> or </em><em>None</em>) – number of absolute minutes.</p></li>
<li><p><strong>hour</strong> (<em>int</em><em> or </em><em>None</em>) – number of absolute hours.</p></li>
<li><p><strong>day</strong> (<em>int</em><em> or </em><em>None</em>) – number of absolute days.</p></li>
<li><p><strong>month</strong> (<em>int</em><em> or </em><em>None</em>) – number of absolute months.</p></li>
<li><p><strong>year</strong> (<em>int</em><em> or </em><em>None</em>) – number of absolute years.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p>The number of real seconds before the given game time is up.</p>
</dd>
</dl>
<pclass="rubric">Example</p>
<p>real_seconds_until(hour=5, min=10, sec=0)</p>
<p>If the game time is 5:00, TIME_FACTOR is set to 2 and you ask
the number of seconds until it’s 5:10, then this function should
return 300 (5 minutes).</p>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.gametime.schedule">
<codeclass="sig-prename descclassname">evennia.utils.gametime.</code><codeclass="sig-name descname">schedule</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">callback</span></em>, <emclass="sig-param"><spanclass="n">repeat</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">sec</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">min</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">hour</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">day</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">month</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">year</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#schedule"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.schedule"title="Permalink to this definition">¶</a></dt>
<dd><p>Call a callback at a given in-game time.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>callback</strong> (<em>function</em>) – The callback function that will be called. Note
that the callback must be a module-level function, since the script will
be persistent. The callable should be on the form <strong>callable(*args, **kwargs)</strong>
where args/kwargs are passed into this schedule.</p></li>
<li><p><strong>repeat</strong> (<em>bool</em><em>, </em><em>optional</em>) – Defines if the callback should be called regularly
at the specified time.</p></li>
<li><p><strong>sec</strong> (<em>int</em><em> or </em><em>None</em>) – Number of absolute game seconds at which to run repeat.</p></li>
<li><p><strong>min</strong> (<em>int</em><em> or </em><em>None</em>) – Number of absolute minutes.</p></li>
<li><p><strong>hour</strong> (<em>int</em><em> or </em><em>None</em>) – Number of absolute hours.</p></li>
<li><p><strong>day</strong> (<em>int</em><em> or </em><em>None</em>) – Number of absolute days.</p></li>
<li><p><strong>month</strong> (<em>int</em><em> or </em><em>None</em>) – Number of absolute months.</p></li>
<li><p><strong>year</strong> (<em>int</em><em> or </em><em>None</em>) – Number of absolute years.</p></li>
<li><p><strong>*args</strong>– Passed into the callable. Must be possible to store in Attribute.</p></li>
<li><p><strong>**kwargs</strong>– Passed into the callable. Must be possible to store in Attribute.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>Script</em>– The created Script handling the scheduling.</p>
</dd>
</dl>
<pclass="rubric">Examples</p>
<dlclass="simple">
<dt>::</dt><dd><p>schedule(func, min=5, sec=0) # Will call 5 minutes past the next (in-game) hour.
schedule(func, hour=2, min=30, sec=0) # Will call the next (in-game) day at 02:30.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.gametime.reset_gametime">
<codeclass="sig-prename descclassname">evennia.utils.gametime.</code><codeclass="sig-name descname">reset_gametime</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/gametime.html#reset_gametime"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.gametime.reset_gametime"title="Permalink to this definition">¶</a></dt>
<dd><p>Resets the game time to make it start from the current time. Note that
the epoch set by <strong>settings.TIME_GAME_EPOCH</strong> will still apply.</p>
