Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-04-01 13:37:17 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated HTML docs.

Browse source
This commit is contained in:
Evennia docbuilder action 2022-11-21 23:18:31 +00:00
parent 370a11cf2f
commit 88477386fe
64 changed files with 2209 additions and 2458 deletions
Download patch file Download diff file Expand all files Collapse all files

99
docs/1.0-dev/Howtos/Howto-Command-Cooldown.html
View file

@ -6,7 +6,7 @@
<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>Command Cooldown &#8212; Evennia 1.0-dev documentation</title>
<title>Adding Command Cooldowns &#8212; Evennia 1.0-dev 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>
@ -17,8 +17,8 @@
<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="Command Duration" href="Howto-Command-Duration.html" />
<link rel="prev" title="Command Prompt" href="Howto-Command-Prompt.html" />
<link rel="next" title="Commands that take time to finish" href="Howto-Command-Duration.html" />
<link rel="prev" title="Adding a Command Prompt" href="Howto-Command-Prompt.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -30,14 +30,14 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Howto-Command-Duration.html" title="Command Duration"
<a href="Howto-Command-Duration.html" title="Commands that take time to finish"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Howto-Command-Prompt.html" title="Command Prompt"
<a href="Howto-Command-Prompt.html" title="Adding a Command Prompt"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Howtos-Overview.html" accesskey="U">Tutorials and Howto’s</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Command Cooldown</a></li>
<li class="nav-item nav-item-this"><a href="">Adding Command Cooldowns</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
@ -62,10 +62,11 @@
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Command Cooldown</a><ul>
<li><a class="reference internal" href="#the-cooldown-contrib">The Cooldown Contrib</a></li>
<li><a class="reference internal" href="#non-persistent-cooldown">Non-persistent cooldown</a></li>
<li><a class="reference internal" href="#persistent-cooldown">Persistent cooldown</a></li>
<li><a class="reference internal" href="#">Adding Command Cooldowns</a><ul>
<li><a class="reference internal" href="#an-efficient-cooldown">An efficient cooldown</a><ul>
<li><a class="reference internal" href="#non-persistent-cooldown">Non-Persistent cooldown</a></li>
</ul>
</li>
<li><a class="reference internal" href="#make-a-cooldown-aware-command-parent">Make a cooldown-aware command parent</a><ul>
<li><a class="reference internal" href="#command-crossover">Command crossover</a></li>
</ul>
@ -76,10 +77,10 @@
<h4>Previous topic</h4>
<p class="topless"><a href="Howto-Command-Prompt.html"
title="previous chapter">Command Prompt</a></p>
title="previous chapter">Adding a Command Prompt</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Howto-Command-Duration.html"
title="next chapter">Command Duration</a></p>
title="next chapter">Commands that take time to finish</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -110,31 +111,28 @@
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="command-cooldown">
<h1>Command Cooldown<a class="headerlink" href="#command-cooldown" title="Permalink to this headline"></a></h1>
<section class="tex2jax_ignore mathjax_ignore" id="adding-command-cooldowns">
<h1>Adding Command Cooldowns<a class="headerlink" href="#adding-command-cooldowns" title="Permalink to this headline"></a></h1>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; hit goblin with sword
You strike goblin with the sword. It dodges!
&gt; hit goblin with sword
You are off-balance and can&#39;t attack again yet.
</pre></div>
</div>
<p>Some types of games want to limit how often a command can be run. If a
character casts the spell <em>Firestorm</em>, you might not want them to spam that
command over and over. Or in an advanced combat system, a massive swing may
command over and over. In an advanced combat system, a massive swing may
offer a chance of lots of damage at the cost of not being able to re-do it for
a while. Such effects are called <em>cooldowns</em>.</p>
<p>This page exemplifies a very resource-efficient way to do cooldowns. A more
‘active’ way is to use asynchronous delays as in the <a class="reference internal" href="Howto-Command-Duration.html#blocking-commands"><span class="std std-doc">Blocking commands</span></a>, the two might be useful to
combine if you want to echo some message to the user after the cooldown ends.</p>
<section id="the-cooldown-contrib">
<h2>The Cooldown Contrib<a class="headerlink" href="#the-cooldown-contrib" title="Permalink to this headline"></a></h2>
<p>The <a class="reference internal" href="../Contribs/Contrib-Cooldowns.html"><span class="doc std std-doc">Cooldown contrib</span></a> is a ready-made solution for
command cooldowns you can use. It implements a <em>handler</em> on the object to
conveniently manage and store the cooldowns in a similar manner exemplified in
this tutorial.</p>
</section>
<section id="non-persistent-cooldown">
<h2>Non-persistent cooldown<a class="headerlink" href="#non-persistent-cooldown" title="Permalink to this headline"></a></h2>
<p>This little recipe will limit how often a particular command can be run. Since
Commands are class instances, and those are cached in memory, a command
instance will remember things you store on it. So just store the current time
of execution! Next time the command is run, it just needs to check if it has
that time stored, and compare it with the current time to see if a desired
delay has passed.</p>
a while.</p>
<p>Such effects are called <em>command cooldowns</em>.</p>
<aside class="sidebar">
<p>The <a class="reference internal" href="../Contribs/Contrib-Cooldowns.html"><span class="doc std std-doc">Cooldown contrib</span></a> is a ready-made solution for command cooldowns. It is based on this howto and implements a <span class="xref myst">handler</span> on the object to conveniently manage and store the cooldowns.</p>
</aside>
<p>This howto exemplifies a very resource-efficient way to do cooldowns. A more
‘active’ way is to use asynchronous delays as in the <span class="xref myst">Command-Duration howto</span> suggests. The two howto’s might be useful to combine if you want to echo some message to the user after the cooldown ends.</p>
<section id="an-efficient-cooldown">
<h2>An efficient cooldown<a class="headerlink" href="#an-efficient-cooldown" title="Permalink to this headline"></a></h2>
<p>The idea is that when a <a class="reference internal" href="../Components/Commands.html"><span class="doc std std-doc">Command</span></a> runs, we store the time it runs. When it next runs, we check again the current time. The command is only allowed to run if enough time passed since now and the previous run. This is a <em>very</em> efficient implementation that only checks on-demand.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in, say, mygame/commands/spells.py</span>
<span class="kn">import</span> <span class="nn">time</span>
@ -157,7 +155,7 @@ delay has passed.</p>
<span class="s2">&quot;Implement the spell&quot;</span>
<span class="n">now</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span>
<span class="n">last_cast</span> <span class="o">=</span> <span class="n">caller</span><span class="o">.</span><span class="n">ndb</span><span class="o">.</span><span class="n">firestorm_last_cast</span> <span class="c1"># could be None</span>
<span class="n">last_cast</span> <span class="o">=</span> <span class="n">caller</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">firestorm_last_cast</span> <span class="c1"># could be None</span>
<span class="k">if</span> <span class="n">last_cast</span> <span class="ow">and</span> <span class="p">(</span><span class="n">now</span> <span class="o">-</span> <span class="n">last_cast</span> <span class="o">&lt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">rate_of_fire</span><span class="p">):</span>
<span class="n">message</span> <span class="o">=</span> <span class="s2">&quot;You cannot cast this spell again yet.&quot;</span>
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
@ -166,21 +164,20 @@ delay has passed.</p>
<span class="c1"># [the spell effect is implemented]</span>
<span class="c1"># if the spell was successfully cast, store the casting time</span>
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">ndb</span><span class="o">.</span><span class="n">firestorm_last_cast</span> <span class="o">=</span> <span class="n">now</span>
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">firestorm_last_cast</span> <span class="o">=</span> <span class="n">now</span>
</pre></div>
</div>
<p>We specify <code class="docutils literal notranslate"><span class="pre">rate_of_fire</span></code> and then just check for a NAtrribute
<code class="docutils literal notranslate"><span class="pre">firestorm_last_cast</span></code> and update it if everything works out.</p>
<p>Simple and very effective since everything is just stored in memory. The
drawback of this simple scheme is that it’s non-persistent. If you do
<code class="docutils literal notranslate"><span class="pre">reload</span></code>, the cache is cleaned and all such ongoing cooldowns will be
forgotten.</p>
<p>We specify <code class="docutils literal notranslate"><span class="pre">rate_of_fire</span></code> and then just check for an <a class="reference internal" href="../Components/Attributes.html"><span class="doc std std-doc">Attribute</span></a> <code class="docutils literal notranslate"><span class="pre">firestorm_last_cast</span></code> on the <code class="docutils literal notranslate"><span class="pre">caller.</span></code> It is either <code class="docutils literal notranslate"><span class="pre">None</span></code> (because the spell was never cast before) or an timestamp representing the last time the spell was cast.</p>
<section id="non-persistent-cooldown">
<h3>Non-Persistent cooldown<a class="headerlink" href="#non-persistent-cooldown" title="Permalink to this headline"></a></h3>
<p>The above implementation will survive a reload. If you don’t want that, you can just switch to let <code class="docutils literal notranslate"><span class="pre">firestorm_last_cast</span></code> be a <a class="reference internal" href="../Components/Attributes.html#in-memory-attributes-nattributes"><span class="std std-doc">NAtrribute</span></a> instead. For example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">last_cast</span> <span class="o">=</span> <span class="n">caller</span><span class="o">.</span><span class="n">ndb</span><span class="o">.</span><span class="n">firestorm_last_cast</span>
<span class="c1"># ... </span>
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">ndb</span><span class="o">.</span><span class="n">firestorm_last_cast</span> <span class="o">=</span> <span class="n">now</span>
</pre></div>
</div>
<p>That is, use <code class="docutils literal notranslate"><span class="pre">.ndb</span></code> instead of <code class="docutils literal notranslate"><span class="pre">.db</span></code>. Since a <code class="docutils literal notranslate"><span class="pre">NAttribute</span></code>s are purely in-memory, they can be faster to read and write to than an <code class="docutils literal notranslate"><span class="pre">Attribute</span></code>. So this can be more optimal if your intervals are short and need to change often. The drawback is that they’ll reset if the server reloads.</p>
</section>
<section id="persistent-cooldown">
<h2>Persistent cooldown<a class="headerlink" href="#persistent-cooldown" title="Permalink to this headline"></a></h2>
<p>To make a cooldown <em>persistent</em> (so it survives a server reload), just
use the same technique, but use <a class="reference internal" href="../Components/Attributes.html"><span class="doc std std-doc">Attributes</span></a> (that is, <code class="docutils literal notranslate"><span class="pre">.db</span></code> instead
of <code class="docutils literal notranslate"><span class="pre">.ndb</span></code> storage to save the last-cast time.</p>
</section>
<section id="make-a-cooldown-aware-command-parent">
<h2>Make a cooldown-aware command parent<a class="headerlink" href="#make-a-cooldown-aware-command-parent" title="Permalink to this headline"></a></h2>
@ -253,7 +250,7 @@ reuse this mixin for all your cooldowns.</p>
you can have all fire-related spells store the cooldown with the same
<code class="docutils literal notranslate"><span class="pre">cooldown_storage_key</span></code> (like <code class="docutils literal notranslate"><span class="pre">fire_spell_last_used</span></code>). That would mean casting
of <em>Firestorm</em> would block all other fire-related spells for a while.</p>
<p>Similarly, when you take that that big sword swing, other types of attacks could
<p>Similarly, when you take that big sword swing, other types of attacks could
be blocked before you can recover your balance.</p>
</section>
</section>
@ -275,14 +272,14 @@ be blocked before you can recover your balance.</p>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Howto-Command-Duration.html" title="Command Duration"
<a href="Howto-Command-Duration.html" title="Commands that take time to finish"
>next</a> |</li>
<li class="right" >
<a href="Howto-Command-Prompt.html" title="Command Prompt"
<a href="Howto-Command-Prompt.html" title="Adding a Command Prompt"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Howtos-Overview.html" >Tutorials and Howto’s</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Command Cooldown</a></li>
<li class="nav-item nav-item-this"><a href="">Adding Command Cooldowns</a></li>
</ul>
<div class="develop">develop branch</div>
</div>