evennia/docs/4.x/api/evennia.utils.gametime.html
2024-03-17 14:15:56 +01:00

344 lines
No EOL
22 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>evennia.utils.gametime &#8212; Evennia latest documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="evennia.utils.logger" href="evennia.utils.logger.html" />
<link rel="prev" title="evennia.utils.funcparser" href="evennia.utils.funcparser.html" />
</head><body>
<div class="admonition important">
<p class="first admonition-title">Note</p>
<p class="last">You are reading an old version of the Evennia documentation. <a href="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="evennia.utils.logger.html" title="evennia.utils.logger"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="evennia.utils.funcparser.html" title="evennia.utils.funcparser"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia latest</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="../Evennia-API.html" >API Summary</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="evennia-api.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="evennia.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-4"><a href="evennia.utils.html" accesskey="U">evennia.utils</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.utils.gametime</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<h4>Previous topic</h4>
<p class="topless"><a href="evennia.utils.funcparser.html"
title="previous chapter">evennia.utils.funcparser</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="evennia.utils.logger.html"
title="next chapter">evennia.utils.logger</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/api/evennia.utils.gametime.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com/docs/latest/index.html">Documentation Top</a> </li>
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
<li><a href="https://github.com/evennia/evennia">Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-evennia.utils.gametime">
<span id="evennia-utils-gametime"></span><h1>evennia.utils.gametime<a class="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>
<dl class="py class">
<dt id="evennia.utils.gametime.TimeScript">
<em class="property">class </em><code class="sig-prename descclassname">evennia.utils.gametime.</code><code class="sig-name descname">TimeScript</code><span class="sig-paren">(</span><em class="sig-param"><span class="o">*</span><span class="n">args</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">kwargs</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#TimeScript"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.gametime.TimeScript" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="evennia.scripts.scripts.html#evennia.scripts.scripts.DefaultScript" title="evennia.scripts.scripts.DefaultScript"><code class="xref py py-class docutils literal notranslate"><span class="pre">evennia.scripts.scripts.DefaultScript</span></code></a></p>
<p>Gametime-sensitive script.</p>
<dl class="py method">
<dt id="evennia.utils.gametime.TimeScript.at_script_creation">
<code class="sig-name descname">at_script_creation</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#TimeScript.at_script_creation"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.gametime.TimeScript.at_script_creation" title="Permalink to this definition"></a></dt>
<dd><p>The script is created.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.utils.gametime.TimeScript.at_repeat">
<code class="sig-name descname">at_repeat</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#TimeScript.at_repeat"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.gametime.TimeScript.at_repeat" title="Permalink to this definition"></a></dt>
<dd><p>Call the callback and reset interval.</p>
</dd></dl>
<dl class="py exception">
<dt id="evennia.utils.gametime.TimeScript.DoesNotExist">
<em class="property">exception </em><code class="sig-name descname">DoesNotExist</code><a class="headerlink" href="#evennia.utils.gametime.TimeScript.DoesNotExist" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="evennia.scripts.scripts.html#evennia.scripts.scripts.DefaultScript.DoesNotExist" title="evennia.scripts.scripts.DefaultScript.DoesNotExist"><code class="xref py py-class docutils literal notranslate"><span class="pre">evennia.scripts.scripts.DefaultScript.DoesNotExist</span></code></a></p>
</dd></dl>
<dl class="py exception">
<dt id="evennia.utils.gametime.TimeScript.MultipleObjectsReturned">
<em class="property">exception </em><code class="sig-name descname">MultipleObjectsReturned</code><a class="headerlink" href="#evennia.utils.gametime.TimeScript.MultipleObjectsReturned" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="evennia.scripts.scripts.html#evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned" title="evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned"><code class="xref py py-class docutils literal notranslate"><span class="pre">evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned</span></code></a></p>
</dd></dl>
<dl class="py attribute">
<dt id="evennia.utils.gametime.TimeScript.path">
<code class="sig-name descname">path</code><em class="property"> = 'evennia.utils.gametime.TimeScript'</em><a class="headerlink" href="#evennia.utils.gametime.TimeScript.path" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt id="evennia.utils.gametime.TimeScript.typename">
<code class="sig-name descname">typename</code><em class="property"> = 'TimeScript'</em><a class="headerlink" href="#evennia.utils.gametime.TimeScript.typename" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.gametime.runtime">
<code class="sig-prename descclassname">evennia.utils.gametime.</code><code class="sig-name descname">runtime</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#runtime"><span class="viewcode-link">[source]</span></a><a class="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>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>format</strong> (<em>bool</em><em>, </em><em>optional</em>) Format into a time representation.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><p><em>time (float or tuple)</em> </p>
<dl class="simple">
<dt>The runtime or the same time split up</dt><dd><p>into time units.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.gametime.server_epoch">
<code class="sig-prename descclassname">evennia.utils.gametime.</code><code class="sig-name descname">server_epoch</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#server_epoch"><span class="viewcode-link">[source]</span></a><a class="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>
<dl class="py function">
<dt id="evennia.utils.gametime.uptime">
<code class="sig-prename descclassname">evennia.utils.gametime.</code><code class="sig-name descname">uptime</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#uptime"><span class="viewcode-link">[source]</span></a><a class="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>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>format</strong> (<em>bool</em><em>, </em><em>optional</em>) Format into time representation.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><p><em>time (float or tuple)</em> </p>
<dl class="simple">
<dt>The uptime or the same time split up</dt><dd><p>into time units.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.gametime.portal_uptime">
<code class="sig-prename descclassname">evennia.utils.gametime.</code><code class="sig-name descname">portal_uptime</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#portal_uptime"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.gametime.portal_uptime" title="Permalink to this definition"></a></dt>
<dd><p>Get the current uptime of the portal.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><em>time (float)</em> The uptime of the portal.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.gametime.game_epoch">
<code class="sig-prename descclassname">evennia.utils.gametime.</code><code class="sig-name descname">game_epoch</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#game_epoch"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.utils.gametime.game_epoch" title="Permalink to this definition"></a></dt>
<dd><p>Get the game epoch.</p>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.gametime.gametime">
<code class="sig-prename descclassname">evennia.utils.gametime.</code><code class="sig-name descname">gametime</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">absolute</span><span class="o">=</span><span class="default_value">False</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#gametime"><span class="viewcode-link">[source]</span></a><a class="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>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="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>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><em>time (float)</em> The gametime as a virtual timestamp.</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>If one is using a standard calendar, one could convert the unformatted
return to a date using Pythons standard <strong>datetime</strong> module like this:
<strong>datetime.datetime.fromtimestamp(gametime(absolute=True))</strong></p>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.gametime.real_seconds_until">
<code class="sig-prename descclassname">evennia.utils.gametime.</code><code class="sig-name descname">real_seconds_until</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">sec</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">min</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">hour</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">day</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">month</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">year</span><span class="o">=</span><span class="default_value">None</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#real_seconds_until"><span class="viewcode-link">[source]</span></a><a class="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>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="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>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>The number of real seconds before the given game time is up.</p>
</dd>
</dl>
<p class="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 its 5:10, then this function should
return 300 (5 minutes).</p>
</dd></dl>
<dl class="py function">
<dt id="evennia.utils.gametime.schedule">
<code class="sig-prename descclassname">evennia.utils.gametime.</code><code class="sig-name descname">schedule</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">callback</span></em>, <em class="sig-param"><span class="n">repeat</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">sec</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">min</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">hour</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">day</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">month</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">year</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="o">*</span><span class="n">args</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">kwargs</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#schedule"><span class="viewcode-link">[source]</span></a><a class="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>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="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>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><em>Script</em> The created Script handling the scheduling.</p>
</dd>
</dl>
<p class="rubric">Examples</p>
<dl class="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>
<dl class="py function">
<dt id="evennia.utils.gametime.reset_gametime">
<code class="sig-prename descclassname">evennia.utils.gametime.</code><code class="sig-name descname">reset_gametime</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/gametime.html#reset_gametime"><span class="viewcode-link">[source]</span></a><a class="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>
</dd></dl>
</section>
</div>
</div>
</div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="evennia.utils.logger.html" title="evennia.utils.logger"
>next</a> |</li>
<li class="right" >
<a href="evennia.utils.funcparser.html" title="evennia.utils.funcparser"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia latest</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="../Evennia-API.html" >API Summary</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="evennia-api.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="evennia.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-4"><a href="evennia.utils.html" >evennia.utils</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.utils.gametime</a></li>
</ul>
</div>
<div class="admonition important">
<p class="first admonition-title">Note</p>
<p class="last">You are reading an old version of the Evennia documentation. <a href="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2023, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>