<spanid="evennia-contrib-game-systems-cooldowns-cooldowns"></span><h1>evennia.contrib.game_systems.cooldowns.cooldowns<aclass="headerlink"href="#module-evennia.contrib.game_systems.cooldowns.cooldowns"title="Permalink to this headline">¶</a></h1>
<p>Cooldown contrib module.</p>
<p>Evennia contrib - owllex, 2021</p>
<p>This contrib provides a simple cooldown handler that can be attached to any
typeclassed Object or Account. A cooldown is a lightweight persistent
asynchronous timer that you can query to see if it is ready.</p>
<p>Cooldowns are good for modelling rate-limited actions, like how often a
character can perform a given command.</p>
<p>Cooldowns are completely asynchronous and must be queried to know their
state. They do not fire callbacks, so are not a good fit for use cases
where something needs to happen on a specific schedule (use delay or
a TickerHandler for that instead).</p>
<p>See also the evennia documentation for command cooldowns
(<aclass="reference external"href="https://github.com/evennia/evennia/wiki/Command-Cooldown">https://github.com/evennia/evennia/wiki/Command-Cooldown</a>) for more information
about the concept.</p>
<p>Installation:</p>
<p>To use, simply add the following property to the typeclass definition of any
object type that you want to support cooldowns. It will expose a new <strong>cooldowns</strong>
property that persists data to the object’s attribute storage. You can set this
on your base <strong>Object</strong> typeclass to enable cooldown tracking on every kind of
object, or just put it on your <strong>Character</strong> typeclass.</p>
<p>By default the CooldownHandler will use the <strong>cooldowns</strong> property, but you can
customize this if desired by passing a different value for the db_attribute
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.contrib.game_systems.cooldowns.cooldowns.</code><codeclass="sig-name descname">CooldownHandler</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">obj</span></em>, <emclass="sig-param"><spanclass="n">db_attribute</span><spanclass="o">=</span><spanclass="default_value">'cooldowns'</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">__init__</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">obj</span></em>, <emclass="sig-param"><spanclass="n">db_attribute</span><spanclass="o">=</span><spanclass="default_value">'cooldowns'</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.__init__"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.__init__"title="Permalink to this definition">¶</a></dt>
<dd><p>Initialize self. See help(type(self)) for accurate signature.</p>
<codeclass="sig-name descname">data</code><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.data"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">obj</code><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.obj"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">db_attribute</code><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.db_attribute"title="Permalink to this definition">¶</a></dt>
<emclass="property">property </em><codeclass="sig-name descname">all</code><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.all"title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a list of all keys in this object.</p>
<codeclass="sig-name descname">ready</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.ready"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.ready"title="Permalink to this definition">¶</a></dt>
<dd><p>Checks whether all of the provided cooldowns are ready (expired). If a
requested cooldown does not exist, it is considered ready.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>*args</strong> (<em>str</em>) – One or more cooldown names to check.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>bool</em>– True if each cooldown has expired or does not exist.</p>
<codeclass="sig-name descname">time_left</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="n">use_int</span><spanclass="o">=</span><spanclass="default_value">False</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.time_left"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.time_left"title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the maximum amount of time left on one or more given cooldowns.
If a requested cooldown does not exist, it is considered to have 0 time
left.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>*args</strong> (<em>str</em>) – One or more cooldown names to check.</p></li>
<li><p><strong>use_int</strong> (<em>bool</em>) – True to round the return value up to an int,
False (default) to return a more precise float.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><p><em>float or int</em>–</p>
<dlclass="simple">
<dt>Number of seconds until all provided cooldowns are</dt><dd><p>ready. Returns 0 if all cooldowns are ready (or don’t exist.)</p>
<codeclass="sig-name descname">add</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cooldown</span></em>, <emclass="sig-param"><spanclass="n">seconds</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.add"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.add"title="Permalink to this definition">¶</a></dt>
<dd><p>Adds/sets a given cooldown to last for a specific amount of time.</p>
<p>If this cooldown already exits, this call replaces it.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>cooldown</strong> (<em>str</em>) – The name of the cooldown.</p></li>
<li><p><strong>seconds</strong> (<em>float</em><em> or </em><em>int</em>) – The number of seconds before this cooldown
<codeclass="sig-name descname">set</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cooldown</span></em>, <emclass="sig-param"><spanclass="n">seconds</span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.set"title="Permalink to this definition">¶</a></dt>
<dd><p>Adds/sets a given cooldown to last for a specific amount of time.</p>
<p>If this cooldown already exits, this call replaces it.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>cooldown</strong> (<em>str</em>) – The name of the cooldown.</p></li>
<li><p><strong>seconds</strong> (<em>float</em><em> or </em><em>int</em>) – The number of seconds before this cooldown
<codeclass="sig-name descname">extend</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cooldown</span></em>, <emclass="sig-param"><spanclass="n">seconds</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.extend"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.extend"title="Permalink to this definition">¶</a></dt>
<dd><p>Adds a specific amount of time to an existing cooldown.</p>
<p>If this cooldown is already ready, this is equivalent to calling set. If
the cooldown is not ready, it will be extended by the provided duration.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>cooldown</strong> (<em>str</em>) – The name of the cooldown.</p></li>
<li><p><strong>seconds</strong> (<em>float</em><em> or </em><em>int</em>) – The number of seconds to extend this cooldown.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>float</em>– The number of seconds until the cooldown will be ready again.</p>
<codeclass="sig-name descname">reset</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cooldown</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.reset"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.reset"title="Permalink to this definition">¶</a></dt>
<dd><p>Resets a given cooldown.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>cooldown</strong> (<em>str</em>) – The name of the cooldown.</p>
<codeclass="sig-name descname">clear</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.clear"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.clear"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">cleanup</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.cleanup"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.cleanup"title="Permalink to this definition">¶</a></dt>
<dd><p>Deletes all expired cooldowns. This helps keep attribute storage