<h1>TickerHandler<aclass="headerlink"href="#tickerhandler"title="Permalink to this headline">¶</a></h1>
<p>One way to implement a dynamic MUD is by using “tickers”, also known as “heartbeats”. A ticker is a
timer that fires (“ticks”) at a given interval. The tick triggers updates in various game systems.</p>
<sectionid="about-tickers">
<h2>About Tickers<aclass="headerlink"href="#about-tickers"title="Permalink to this headline">¶</a></h2>
<p>Tickers are very common or even unavoidable in other mud code bases. Certain code bases are even
hard-coded to rely on the concept of the global ‘tick’. Evennia has no such notion - the decision to
use tickers is very much up to the need of your game and which requirements you have. The “ticker
recipe” is just one way of cranking the wheels.</p>
<p>The most fine-grained way to manage the flow of time is of course to use <aclass="reference internal"href="Scripts.html"><spanclass="doc std std-doc">Scripts</span></a>. Many
types of operations (weather being the classic example) are however done on multiple objects in the
same way at regular intervals, and for this, storing separate Scripts on each object is inefficient.
The way to do this is to use a ticker with a “subscription model” - let objects sign up to be
triggered at the same interval, unsubscribing when the updating is no longer desired.</p>
<p>Evennia offers an optimized implementation of the subscription model - the <em>TickerHandler</em>. This is
a singleton global handler reachable from <codeclass="docutils literal notranslate"><spanclass="pre">evennia.TICKER_HANDLER</span></code>. You can assign any <em>callable</em> (a
function or, more commonly, a method on a database object) to this handler. The TickerHandler will
then call this callable at an interval you specify, and with the arguments you supply when adding
it. This continues until the callable un-subscribes from the ticker. The handler survives a reboot
and is highly optimized in resource usage.</p>
<p>Here is an example of importing <codeclass="docutils literal notranslate"><spanclass="pre">TICKER_HANDLER</span></code> and using it:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># we assume that obj has a hook "at_tick" defined on itself</span>
<p>That’s it - from now on, <codeclass="docutils literal notranslate"><spanclass="pre">obj.at_tick()</span></code> will be called every 20 seconds.</p>
<p>You can also import function and tick that:</p>
<p>Note that you have to also supply <codeclass="docutils literal notranslate"><spanclass="pre">interval</span></code> to identify which subscription to remove. This is
because the TickerHandler maintains a pool of tickers and a given callable can subscribe to be
ticked at any number of different intervals.</p>
<p>The full definition of the <codeclass="docutils literal notranslate"><spanclass="pre">tickerhandler.add</span></code> method is</p>
<p>Here <codeclass="docutils literal notranslate"><spanclass="pre">*args</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code> will be passed to <codeclass="docutils literal notranslate"><spanclass="pre">callback</span></code> every <codeclass="docutils literal notranslate"><spanclass="pre">interval</span></code> seconds. If <codeclass="docutils literal notranslate"><spanclass="pre">persistent</span></code>
is <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code>, this subscription will not survive a server reload.</p>
<p>Tickers are identified and stored by making a key of the callable itself, the ticker-interval, the
<codeclass="docutils literal notranslate"><spanclass="pre">persistent</span></code> flag and the <codeclass="docutils literal notranslate"><spanclass="pre">idstring</span></code> (the latter being an empty string when not given explicitly).</p>
<p>Since the arguments are not included in the ticker’s identification, the <codeclass="docutils literal notranslate"><spanclass="pre">idstring</span></code> must be used to
have a specific callback triggered multiple times on the same interval but with different arguments:</p>
<div><p>Note that, when we want to send arguments to our callback within a ticker handler, we need to
specify <codeclass="docutils literal notranslate"><spanclass="pre">idstring</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">persistent</span></code> before, unless we call our arguments as keywords, which would
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">callable</span></code> can be on any form as long as it accepts the arguments you give to send to it in
<div><p>Note that everything you supply to the TickerHandler will need to be pickled at some point to be
saved into the database. Most of the time the handler will correctly store things like database
objects, but the same restrictions as for <aclass="reference internal"href="Attributes.html"><spanclass="doc std std-doc">Attributes</span></a> apply to what the TickerHandler
may store.</p>
</div></blockquote>
<p>When testing, you can stop all tickers in the entire game with <codeclass="docutils literal notranslate"><spanclass="pre">tickerhandler.clear()</span></code>. You can also
view the currently subscribed objects with <codeclass="docutils literal notranslate"><spanclass="pre">tickerhandler.all()</span></code>.</p>
<p>See the <aclass="reference internal"href="../Howtos/Tutorial-Weather-Effects.html"><spanclass="doc std std-doc">Weather Tutorial</span></a> for an example of using the TickerHandler.</p>
