evennia/docs/2.x/api/evennia.contrib.game_systems.cooldowns.cooldowns.html
Evennia docbuilder action e535f5782a Updated HTML docs.
2023-10-19 20:22:27 +00:00

389 lines
No EOL
23 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.contrib.game_systems.cooldowns.cooldowns &#8212; Evennia 2.x 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.contrib.game_systems.cooldowns.tests" href="evennia.contrib.game_systems.cooldowns.tests.html" />
<link rel="prev" title="evennia.contrib.game_systems.cooldowns" href="evennia.contrib.game_systems.cooldowns.html" />
</head><body>
<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.contrib.game_systems.cooldowns.tests.html" title="evennia.contrib.game_systems.cooldowns.tests"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="evennia.contrib.game_systems.cooldowns.html" title="evennia.contrib.game_systems.cooldowns"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 2.x</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.contrib.html" >evennia.contrib</a> &#187;</li>
<li class="nav-item nav-item-5"><a href="evennia.contrib.game_systems.html" >evennia.contrib.game_systems</a> &#187;</li>
<li class="nav-item nav-item-6"><a href="evennia.contrib.game_systems.cooldowns.html" accesskey="U">evennia.contrib.game_systems.cooldowns</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.contrib.game_systems.cooldowns.cooldowns</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.contrib.game_systems.cooldowns.html"
title="previous chapter">evennia.contrib.game_systems.cooldowns</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="evennia.contrib.game_systems.cooldowns.tests.html"
title="next chapter">evennia.contrib.game_systems.cooldowns.tests</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/api/evennia.contrib.game_systems.cooldowns.cooldowns.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>
<h3>Doc Versions</h3>
<ul>
<li><a href="evennia.contrib.game_systems.cooldowns.cooldowns.html">2.x (main branch)</a></li>
<ul>
<li><a href="../1.3.0/index.html">1.3.0 (v1.3.0 branch)</a></li>
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-evennia.contrib.game_systems.cooldowns.cooldowns">
<span id="evennia-contrib-game-systems-cooldowns-cooldowns"></span><h1>evennia.contrib.game_systems.cooldowns.cooldowns<a class="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
(<a class="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 objects 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
parameter.</p>
<blockquote>
<div><p>from evennia.contrib.game_systems.cooldowns import Cooldownhandler
from evennia.utils.utils import lazy_property</p>
<p>&#64;lazy_property
def cooldowns(self):</p>
<blockquote>
<div><p>return CooldownHandler(self, db_attribute=”cooldowns”)</p>
</div></blockquote>
</div></blockquote>
<p>Example:</p>
<p>Assuming youve installed cooldowns on your Character typeclasses, you can use a
cooldown to limit how often you can perform a command. The following code
snippet will limit the use of a Power Attack command to once every 10 seconds
per character.</p>
<dl class="simple">
<dt>class PowerAttack(Command):</dt><dd><dl class="simple">
<dt>def func(self):</dt><dd><dl class="simple">
<dt>if self.caller.cooldowns.ready(“power attack”):</dt><dd><p>self.do_power_attack()
self.caller.cooldowns.add(“power attack”, 10)</p>
</dd>
<dt>else:</dt><dd><p>self.caller.msg(“Thats not ready yet!”)</p>
</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
<dl class="py class">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler">
<em class="property">class </em><code class="sig-prename descclassname">evennia.contrib.game_systems.cooldowns.cooldowns.</code><code class="sig-name descname">CooldownHandler</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">obj</span></em>, <em class="sig-param"><span class="n">db_attribute</span><span class="o">=</span><span class="default_value">'cooldowns'</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
<p>Handler for cooldowns. This can be attached to any object that supports DB
attributes (like a Character or Account).</p>
<p>A cooldown is a timer that is usually used to limit how often some action
can be performed or some effect can trigger. When a cooldown is first added,
it counts down from the amount of time provided back to zero, at which point
it is considered ready again.</p>
<p>Cooldowns are named with an arbitrary string, and that string is used to
check on the progression of the cooldown. Each cooldown is tracked
separately and independently from other cooldowns on that same object. A
cooldown is unique per-object.</p>
<p>Cooldowns are saved persistently, so they survive reboots. This module does
not register or provide callback functionality for when a cooldown becomes
ready again. Users of cooldowns are expected to query the state of any
cooldowns they are interested in.</p>
<p>Methods:
- ready(name): Checks whether a given cooldown name is ready.
- time_left(name): Returns how much time is left on a cooldown.
- add(name, seconds): Sets a given cooldown to last for a certain</p>
<blockquote>
<div><p>amount of time. Until then, ready() will return False for that
cooldown name. set() is an alias.</p>
</div></blockquote>
<ul class="simple">
<li><dl class="simple">
<dt>extend(name, seconds): Like add(), but adds more time to the given</dt><dd><p>cooldown if it already exists. If it doesnt exist yet, calling
this is equivalent to calling add().</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>reset(cooldown): Resets a given cooldown, causing ready() to return</dt><dd><p>True for that cooldown immediately.</p>
</dd>
</dl>
</li>
<li><p>clear(): Resets all cooldowns.</p></li>
</ul>
<dl class="py method">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.__init__">
<code class="sig-name descname">__init__</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">obj</span></em>, <em class="sig-param"><span class="n">db_attribute</span><span class="o">=</span><span class="default_value">'cooldowns'</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.__init__"><span class="viewcode-link">[source]</span></a><a class="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>
</dd></dl>
<dl class="py attribute">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.data">
<code class="sig-name descname">data</code><a class="headerlink" href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.data" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.obj">
<code class="sig-name descname">obj</code><a class="headerlink" href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.obj" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.db_attribute">
<code class="sig-name descname">db_attribute</code><a class="headerlink" href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.db_attribute" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.all">
<em class="property">property </em><code class="sig-name descname">all</code><a class="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>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.ready">
<code class="sig-name descname">ready</code><span class="sig-paren">(</span><em class="sig-param"><span class="o">*</span><span class="n">args</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.ready"><span class="viewcode-link">[source]</span></a><a class="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>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>*args</strong> (<em>str</em>) One or more cooldown names to check.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><em>bool</em> True if each cooldown has expired or does not exist.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.time_left">
<code class="sig-name descname">time_left</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="n">use_int</span><span class="o">=</span><span class="default_value">False</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.time_left"><span class="viewcode-link">[source]</span></a><a class="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>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="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>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><p><em>float or int</em> </p>
<dl class="simple">
<dt>Number of seconds until all provided cooldowns are</dt><dd><p>ready. Returns 0 if all cooldowns are ready (or dont exist.)</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.add">
<code class="sig-name descname">add</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">cooldown</span></em>, <em class="sig-param"><span class="n">seconds</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.add"><span class="viewcode-link">[source]</span></a><a class="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>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="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
is ready again.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.set">
<code class="sig-name descname">set</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">cooldown</span></em>, <em class="sig-param"><span class="n">seconds</span></em><span class="sig-paren">)</span><a class="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>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="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
is ready again.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.extend">
<code class="sig-name descname">extend</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">cooldown</span></em>, <em class="sig-param"><span class="n">seconds</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.extend"><span class="viewcode-link">[source]</span></a><a class="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>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="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>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><em>float</em> The number of seconds until the cooldown will be ready again.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.reset">
<code class="sig-name descname">reset</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">cooldown</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.reset"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.reset" title="Permalink to this definition"></a></dt>
<dd><p>Resets a given cooldown.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>cooldown</strong> (<em>str</em>) The name of the cooldown.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.clear">
<code class="sig-name descname">clear</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.clear"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.clear" title="Permalink to this definition"></a></dt>
<dd><p>Resets all cooldowns.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.game_systems.cooldowns.cooldowns.CooldownHandler.cleanup">
<code class="sig-name descname">cleanup</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/game_systems/cooldowns/cooldowns.html#CooldownHandler.cleanup"><span class="viewcode-link">[source]</span></a><a class="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
requirements small.</p>
</dd></dl>
</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.contrib.game_systems.cooldowns.tests.html" title="evennia.contrib.game_systems.cooldowns.tests"
>next</a> |</li>
<li class="right" >
<a href="evennia.contrib.game_systems.cooldowns.html" title="evennia.contrib.game_systems.cooldowns"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 2.x</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.contrib.html" >evennia.contrib</a> &#187;</li>
<li class="nav-item nav-item-5"><a href="evennia.contrib.game_systems.html" >evennia.contrib.game_systems</a> &#187;</li>
<li class="nav-item nav-item-6"><a href="evennia.contrib.game_systems.cooldowns.html" >evennia.contrib.game_systems.cooldowns</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.contrib.game_systems.cooldowns.cooldowns</a></li>
</ul>
</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>