<h3>Setting up game time for a standard calendar<aclass="headerlink"href="#setting-up-game-time-for-a-standard-calendar"title="Permalink to this headline">¶</a></h3>
<p>All is done through the settings. Here are the settings you should use if you want a game time with
a standard calendar:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in a file settings.py in mygame/server/conf</span>
<spanclass="c1"># The time factor dictates if the game world runs faster (timefactor>1)</span>
<spanclass="c1"># or slower (timefactor<1) than the real world.</span>
<p>By default, the game time runs twice as fast as the real time. You can set the time factor to be 1
(the game time would run exactly at the same speed than the real time) or lower (the game time will
be slower than the real time). Most games choose to have the game time spinning faster (you will
find some games that have a time factor of 60, meaning the game time runs sixty times as fast as the
real time, a minute in real time would be an hour in game time).</p>
<p>The epoch is a slightly more complex setting. It should contain a number of seconds that would
indicate the time your game started. As indicated, an epoch of 0 would mean January 1st, 1970. If
you want to set your time in the future, you just need to find the starting point in seconds. There
are several ways to do this in Python, this method will show you how to do it in local time:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># We're looking for the number of seconds representing</span>
<p>Reload the game with <codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code>, and then use the <codeclass="docutils literal notranslate"><spanclass="pre">@time</span></code> command. You should see something like
<p>The line that is most relevant here is the game time epoch. You see it shown at 2020-01-01. From
this point forward, the game time keeps increasing. If you keep typing <codeclass="docutils literal notranslate"><spanclass="pre">@time</span></code>, you’ll see the game
time updated correctly… and going (by default) twice as fast as the real time.</p>
</section>
<sectionid="time-related-events">
<h3>Time-related events<aclass="headerlink"href="#time-related-events"title="Permalink to this headline">¶</a></h3>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">gametime</span></code> utility also has a way to schedule game-related events, taking into account your game
time, and assuming a standard calendar (see below for the same feature with a custom calendar). For
instance, it can be used to have a specific message every (in-game) day at 6:00 AM showing how the
sun rises.</p>
<p>The function <codeclass="docutils literal notranslate"><spanclass="pre">schedule()</span></code> should be used here. It will create a <aclass="reference internal"href="../Components/Scripts.html"><spanclass="doc std std-doc">script</span></a> with some
additional features to make sure the script is always executed when the game time matches the given
parameters.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">schedule</span></code> function takes the following arguments:</p>
<ulclass="simple">
<li><p>The <em>callback</em>, a function to be called when time is up.</p></li>
<li><p>The keyword <codeclass="docutils literal notranslate"><spanclass="pre">repeat</span></code> (<codeclass="docutils literal notranslate"><spanclass="pre">False</span></code> by default) to indicate whether this function should be called
repeatedly.</p></li>
<li><p>Additional keyword arguments <codeclass="docutils literal notranslate"><spanclass="pre">sec</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">min</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">hour</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">day</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">month</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">year</span></code> to describe the time
to schedule. If the parameter isn’t given, it assumes the current time value of this specific unit.</p></li>
</ul>
<p>Here is a short example for making the sun rise every day:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in a file ingame_time.py in mygame/world/</span>
<spanclass="n">room</span><spanclass="o">.</span><spanclass="n">msg_contents</span><spanclass="p">(</span><spanclass="s2">"The sun rises from the eastern horizon."</span><spanclass="p">)</span>
<p>The script will be created silently. The <codeclass="docutils literal notranslate"><spanclass="pre">at_sunrise</span></code> function will now be called every in-game day
at 6 AM. You can use the <codeclass="docutils literal notranslate"><spanclass="pre">@scripts</span></code> command to see it. You could stop it using <codeclass="docutils literal notranslate"><spanclass="pre">@scripts/stop</span></code>. If
we hadn’t set <codeclass="docutils literal notranslate"><spanclass="pre">repeat</span></code> the sun would only have risen once and then never again.</p>
<p>We used the <codeclass="docutils literal notranslate"><spanclass="pre">@py</span></code> command here: nothing prevents you from adding the system into your game code.
Remember to be careful not to add each event at startup, however, otherwise there will be a lot of
overlapping events scheduled when the sun rises.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">schedule</span></code> function when using <codeclass="docutils literal notranslate"><spanclass="pre">repeat</span></code> set to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> works with the higher, non-specified unit.
In our example, we have specified hour, minute and second. The higher unit we haven’t specified is
day: <codeclass="docutils literal notranslate"><spanclass="pre">schedule</span></code> assumes we mean “run the callback every day at the specified time”. Therefore, you
can have an event that runs every hour at HH:30, or every month on the 3rd day.</p>
<blockquote>
<div><p>A word of caution for repeated scripts on a monthly or yearly basis: due to the variations in the
real-life calendar you need to be careful when scheduling events for the end of the month or year.
For example, if you set a script to run every month on the 31st it will run in January but find no
such day in February, April etc. Similarly, leap years may change the number of days in the year.</p>
</div></blockquote>
</section>
<sectionid="a-game-time-with-a-custom-calendar">
<h3>A game time with a custom calendar<aclass="headerlink"href="#a-game-time-with-a-custom-calendar"title="Permalink to this headline">¶</a></h3>
<p>Using a custom calendar to handle game time is sometimes needed if you want to place your game in a
fictional universe. For instance you may want to create the Shire calendar which Tolkien described
having 12 months, each which 30 days. That would give only 360 days per year (presumably hobbits
weren’t really fond of the hassle of following the astronomical calendar). Another example would be
creating a planet in a different solar system with, say, days 29 hours long and months of only 18
days.</p>
<p>Evennia handles custom calendars through an optional <em>contrib</em> module, called <codeclass="docutils literal notranslate"><spanclass="pre">custom_gametime</span></code>.
Contrary to the normal <codeclass="docutils literal notranslate"><spanclass="pre">gametime</span></code> module described above it is not active by default.</p>
</section>
<sectionid="setting-up-the-custom-calendar">
<h3>Setting up the custom calendar<aclass="headerlink"href="#setting-up-the-custom-calendar"title="Permalink to this headline">¶</a></h3>
<p>In our first example of the Shire calendar, used by hobbits in books by Tolkien, we don’t really
need the notion of weeks… but we need the notion of months having 30 days, not 28.</p>
<p>The custom calendar is defined by adding the <codeclass="docutils literal notranslate"><spanclass="pre">TIME_UNITS</span></code> setting to your settings file. It’s a
dictionary containing as keys the name of the units, and as value the number of seconds (the
smallest unit for us) in this unit. Its keys must be picked among the following: “sec”, “min”,
“hour”, “day”, “week”, “month” and “year” but you don’t have to include them all. Here is the
configuration for the Shire calendar:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in a file settings.py in mygame/server/conf</span>
<h4>A command to display the current game time<aclass="headerlink"href="#a-command-to-display-the-current-game-time"title="Permalink to this headline">¶</a></h4>
<p>As pointed out earlier, the <codeclass="docutils literal notranslate"><spanclass="pre">@time</span></code> command is meant to be used with a standard calendar, not a
custom one. We can easily create a new command though. We’ll call it <codeclass="docutils literal notranslate"><spanclass="pre">time</span></code>, as is often the case
on other MU*. Here’s an example of how we could write it (for the example, you can create a file
<codeclass="docutils literal notranslate"><spanclass="pre">gametime.py</span></code> in your <codeclass="docutils literal notranslate"><spanclass="pre">commands</span></code> directory and paste this code in it):</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in a file mygame/commands/gametime.py</span>
<spanclass="n">time_string</span><spanclass="o">=</span><spanclass="sa">f</span><spanclass="s2">"We are in year </span><spanclass="si">{</span><spanclass="n">year</span><spanclass="si">}</span><spanclass="s2">, day </span><spanclass="si">{</span><spanclass="n">day</span><spanclass="si">}</span><spanclass="s2">, month </span><spanclass="si">{</span><spanclass="n">month</span><spanclass="si">}</span><spanclass="s2">."</span>
<p>Reload your game with the <codeclass="docutils literal notranslate"><spanclass="pre">@reload</span></code> command. You should now see the <codeclass="docutils literal notranslate"><spanclass="pre">time</span></code> command. If you enter
it, you might see something like:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>We are in year 0, day 0, month 0.
It's 00:52:17.
</pre></div>
</div>
<p>You could display it a bit more prettily with names for months and perhaps even days, if you want.
And if “months” are called “moons” in your game, this is where you’d add that.</p>
<h2>Time-related events in custom gametime<aclass="headerlink"href="#time-related-events-in-custom-gametime"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">custom_gametime</span></code> module also has a way to schedule game-related events, taking into account
your game time (and your custom calendar). It can be used to have a specific message every day at
6:00 AM, to show the sun rises, for instance. The <codeclass="docutils literal notranslate"><spanclass="pre">custom_gametime.schedule</span></code> function works in the
same way as described for the default one above.</p>
