Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-19 22:36:31 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/2.x/api/evennia.contrib.rpg.traits.traits.html
Evennia docbuilder action e535f5782a Updated HTML docs.
2023-10-19 20:22:27 +00:00

1153 lines
No EOL
91 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.rpg.traits.traits &#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.tutorials" href="evennia.contrib.tutorials.html" />
<link rel="prev" title="evennia.contrib.rpg.traits.tests" href="evennia.contrib.rpg.traits.tests.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.tutorials.html" title="evennia.contrib.tutorials"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="evennia.contrib.rpg.traits.tests.html" title="evennia.contrib.rpg.traits.tests"
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.rpg.html" >evennia.contrib.rpg</a> &#187;</li>
<li class="nav-item nav-item-6"><a href="evennia.contrib.rpg.traits.html" accesskey="U">evennia.contrib.rpg.traits</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.contrib.rpg.traits.traits</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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">evennia.contrib.rpg.traits.traits</a><ul>
<li><a class="reference internal" href="#installation">Installation</a><ul>
<li><a class="reference internal" href="#traits-with-traithandler">Traits with TraitHandler</a></li>
<li><a class="reference internal" href="#traitproperties">TraitProperties</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-traits">Using traits</a></li>
<li><a class="reference internal" href="#trait-types">Trait types</a></li>
<li><a class="reference internal" href="#static-trait">Static trait</a><ul>
<li><a class="reference internal" href="#counter">Counter</a><ul>
<li><a class="reference internal" href="#descs">.descs</a></li>
<li><a class="reference internal" href="#rate">.rate</a></li>
<li><a class="reference internal" href="#percent">.percent()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#gauge">Gauge</a></li>
<li><a class="reference internal" href="#trait">Trait</a></li>
</ul>
</li>
<li><a class="reference internal" href="#expanding-with-your-own-traits">Expanding with your own Traits</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="evennia.contrib.rpg.traits.tests.html"
title="previous chapter">evennia.contrib.rpg.traits.tests</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="evennia.contrib.tutorials.html"
title="next chapter">evennia.contrib.tutorials</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.rpg.traits.traits.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.rpg.traits.traits.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.rpg.traits.traits">
<span id="evennia-contrib-rpg-traits-traits"></span><h1>evennia.contrib.rpg.traits.traits<a class="headerlink" href="#module-evennia.contrib.rpg.traits.traits" title="Permalink to this headline"></a></h1>
<p>Traits</p>
<p>Whitenoise 2014, Ainneve contributors,
Griatch 2020</p>
<p>A <strong>Trait</strong> represents a modifiable property on (usually) a Character. They can
be used to represent everything from attributes (str, agi etc) to skills
(hunting 10, swords 14 etc) and dynamically changing things like HP, XP etc.</p>
<p>Traits use Evennia Attributes under the hood, making them persistent (they survive
a server reload/reboot).</p>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline"></a></h2>
<p>Traits are always added to a typeclass, such as the Character class.</p>
<p>There are two ways to set up Traits on a typeclass. The first sets up the <strong>TraitHandler</strong>
as a property <strong>.traits</strong> on your class and you then access traits as e.g. <strong>.traits.strength</strong>.
The other alternative uses a <strong>TraitProperty</strong>, which makes the trait available directly
as e.g. <strong>.strength</strong>. This solution also uses the <strong>TraitHandler</strong>, but you don’t need to
define it explicitly. You can combine both styles if you like.</p>
<section id="traits-with-traithandler">
<h3>Traits with TraitHandler<a class="headerlink" href="#traits-with-traithandler" title="Permalink to this headline"></a></h3>
<p>Here’s an example for adding the TraitHandler to the Character class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># mygame/typeclasses/objects.py</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultCharacter</span>
<span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">lazy_property</span>
<span class="kn">from</span> <span class="nn">evennia.contrib.rpg.traits</span> <span class="kn">import</span> <span class="n">TraitHandler</span>
<span class="c1"># ...</span>
<span class="k">class</span> <span class="nc">Character</span><span class="p">(</span><span class="n">DefaultCharacter</span><span class="p">):</span>
<span class="o">...</span>
<span class="nd">@lazy_property</span>
<span class="k">def</span> <span class="nf">traits</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># this adds the handler as .traits</span>
<span class="k">return</span> <span class="n">TraitHandler</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">at_object_creation</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># (or wherever you want)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;str&quot;</span><span class="p">,</span> <span class="s2">&quot;Strength&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;static&quot;</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">mod</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">mult</span><span class="o">=</span><span class="mf">2.0</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;hp&quot;</span><span class="p">,</span> <span class="s2">&quot;Health&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;gauge&quot;</span><span class="p">,</span> <span class="nb">min</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="nb">max</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;hunting&quot;</span><span class="p">,</span> <span class="s2">&quot;Hunting Skill&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;counter&quot;</span><span class="p">,</span>
<span class="n">base</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">mod</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="nb">min</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="nb">max</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
</pre></div>
</div>
<p>When adding the trait, you supply the name of the property (<strong>hunting</strong>) along
with a more human-friendly name (“Hunting Skill”). The latter will show if you
print the trait etc. The <strong>trait_type</strong> is important, this specifies which type
of trait this is (see below).</p>
</section>
<section id="traitproperties">
<h3>TraitProperties<a class="headerlink" href="#traitproperties" title="Permalink to this headline"></a></h3>
<p>Using <strong>TraitProperties</strong> makes the trait available directly on the class, much like Django model
fields. The drawback is that you must make sure that the name of your Traits don’t collide with any
other properties/methods on your class.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># mygame/typeclasses/objects.py</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">DefaultObject</span>
<span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">lazy_property</span>
<span class="kn">from</span> <span class="nn">evennia.contrib.rpg.traits</span> <span class="kn">import</span> <span class="n">TraitProperty</span>
<span class="c1"># ...</span>
<span class="k">class</span> <span class="nc">Object</span><span class="p">(</span><span class="n">DefaultObject</span><span class="p">):</span>
<span class="o">...</span>
<span class="n">strength</span> <span class="o">=</span> <span class="n">TraitProperty</span><span class="p">(</span><span class="s2">&quot;Strength&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;static&quot;</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">mod</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">mult</span><span class="o">=</span><span class="mf">1.5</span><span class="p">)</span>
<span class="n">health</span> <span class="o">=</span> <span class="n">TraitProperty</span><span class="p">(</span><span class="s2">&quot;Health&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;gauge&quot;</span><span class="p">,</span> <span class="nb">min</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">mod</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="n">hunting</span> <span class="o">=</span> <span class="n">TraitProperty</span><span class="p">(</span><span class="s2">&quot;Hunting Skill&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;counter&quot;</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">mod</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">mult</span><span class="o">=</span><span class="mf">2.0</span><span class="p">,</span> <span class="nb">min</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="nb">max</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
</pre></div>
</div>
<p>&gt; Note that the property-name will become the name of the trait and you don’t supply <strong>trait_key</strong>
&gt; separately.</p>
<p>&gt; The <strong>.traits</strong> TraitHandler will still be created (it’s used under the
&gt; hood. But it will only be created when the TraitProperty has been accessed at least once,
&gt; so be careful if mixing the two styles. If you want to make sure <strong>.traits</strong> is always available,
&gt; add the <strong>TraitHandler</strong> manually like shown earlier - the <strong>TraitProperty</strong> will by default use
&gt; the same handler (<strong>.traits</strong>).</p>
</section>
</section>
<section id="using-traits">
<h2>Using traits<a class="headerlink" href="#using-traits" title="Permalink to this headline"></a></h2>
<p>A trait is added to the traithandler (if you use <strong>TraitProperty</strong> the handler is just created under
the hood) after which one can access it as a property on the handler (similarly to how you can do
.db.attrname for Attributes in Evennia).</p>
<p>All traits have a _read-<a href="#id7"><span class="problematic" id="id8">only_</span></a> field <strong>.value</strong>. This is only used to read out results, you never
manipulate it directly (if you try, it will just remain unchanged). The <strong>.value</strong> is calculated based
on combining fields, like <strong>.base</strong> and <strong>.mod</strong> - which fields are available and how they relate to
each other depends on the trait type.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">strength</span><span class="o">.</span><span class="n">value</span>
<span class="mi">18</span> <span class="c1"># (base + mod) * mult</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">strength</span><span class="o">.</span><span class="n">base</span> <span class="o">+=</span> <span class="mi">6</span>
<span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">strength</span><span class="o">.</span><span class="n">value</span>
<span class="mi">27</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">value</span>
<span class="mi">102</span> <span class="c1"># (base + mod) * mult</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">base</span> <span class="o">-=</span> <span class="mi">200</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">value</span>
<span class="mi">0</span> <span class="c1"># min of 0</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">reset</span><span class="p">()</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">value</span>
<span class="mi">100</span>
<span class="c1"># you can also access properties like a dict</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="p">[</span><span class="s2">&quot;value&quot;</span><span class="p">]</span>
<span class="mi">100</span>
<span class="c1"># you can store arbitrary data persistently for easy reference</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">effect</span> <span class="o">=</span> <span class="s2">&quot;poisoned!&quot;</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">effect</span>
<span class="s2">&quot;poisoned!&quot;</span>
<span class="c1"># with TraitProperties:</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">22</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">strength</span><span class="o">.</span><span class="n">value</span> <span class="o">+=</span> <span class="mi">5</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">strength</span><span class="o">.</span><span class="n">value</span>
<span class="mi">32</span>
</pre></div>
</div>
</section>
<section id="trait-types">
<h2>Trait types<a class="headerlink" href="#trait-types" title="Permalink to this headline"></a></h2>
<p>All default traits have a read-only <strong>.value</strong> property that shows the relevant or
‘current’ value of the trait. Exactly what this means depends on the type of trait.</p>
<p>Traits can also be combined to do arithmetic with their .value, if both have a
compatible type.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="n">trait1</span> <span class="o">+</span> <span class="n">trait2</span>
<span class="mi">54</span>
<span class="o">&gt;</span> <span class="n">trait1</span><span class="o">.</span><span class="n">value</span>
<span class="mi">3</span>
<span class="o">&gt;</span> <span class="n">trait1</span> <span class="o">+</span> <span class="mi">2</span>
<span class="o">&gt;</span> <span class="n">trait1</span><span class="o">.</span><span class="n">value</span>
<span class="mi">5</span>
</pre></div>
</div>
<p>Two numerical traits can also be compared (bigger-than etc), which is useful in
all sorts of rule-resolution.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">trait1</span> <span class="o">&gt;</span> <span class="n">trait2</span><span class="p">:</span>
<span class="c1"># do stuff</span>
</pre></div>
</div>
</section>
<section id="static-trait">
<h2>Static trait<a class="headerlink" href="#static-trait" title="Permalink to this headline"></a></h2>
<p><strong>value = (base + mod) * mult</strong></p>
<p>The static trait has a <strong>base</strong> value and an optional <strong>mod</strong>-ifier and ‘mult’-iplier.
The modifier defaults to 0, and the multiplier to 1.0, for no change in value.
A typical use of a static trait would be a Strength stat or Skill value. That is,
somethingthat varies slowly or not at all, and which may be modified in-place.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;str&quot;</span><span class="p">,</span> <span class="s2">&quot;Strength&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;static&quot;</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">mod</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mytrait</span><span class="o">.</span><span class="n">value</span>
<span class="mi">12</span> <span class="c1"># base + mod</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mytrait</span><span class="o">.</span><span class="n">base</span> <span class="o">+=</span> <span class="mi">2</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mytrait</span><span class="o">.</span><span class="n">mod</span> <span class="o">+=</span> <span class="mi">1</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mytrait</span><span class="o">.</span><span class="n">value</span>
<span class="mi">15</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mytrait</span><span class="o">.</span><span class="n">mod</span> <span class="o">=</span> <span class="mi">0</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mytrait</span><span class="o">.</span><span class="n">mult</span> <span class="o">=</span> <span class="mf">2.0</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mytrait</span><span class="o">.</span><span class="n">value</span>
<span class="mi">20</span>
</pre></div>
</div>
<section id="counter">
<h3>Counter<a class="headerlink" href="#counter" title="Permalink to this headline"></a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">min</span><span class="o">/</span><span class="n">unset</span> <span class="n">base</span> <span class="n">base</span><span class="o">+</span><span class="n">mod</span> <span class="nb">max</span><span class="o">/</span><span class="n">unset</span>
<span class="o">|--------------|--------|---------</span><span class="n">X</span><span class="o">--------</span><span class="n">X</span><span class="o">------------|</span>
<span class="n">current</span> <span class="n">value</span>
<span class="o">=</span> <span class="p">(</span><span class="n">current</span>
<span class="o">+</span> <span class="n">mod</span><span class="p">)</span>
<span class="o">*</span> <span class="n">mult</span>
</pre></div>
</div>
<p>A counter describes a value that can move from a base. The <strong>.current</strong> property
is the thing usually modified. It starts at the <strong>.base</strong>. One can also add a
modifier, which is added to both the base and to current. ‘.value’ is then formed
by multiplying by the multiplier, which defaults to 1.0 for no change. The min/max
of the range are optional, a boundary set to None will remove it. A suggested use
for a Counter Trait would be to track skill values.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;hunting&quot;</span><span class="p">,</span> <span class="s2">&quot;Hunting Skill&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;counter&quot;</span><span class="p">,</span>
<span class="n">base</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">mod</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">mult</span><span class="o">=</span><span class="mf">1.0</span><span class="p">,</span> <span class="nb">min</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="nb">max</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">11</span> <span class="c1"># current starts at base + mod</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">current</span> <span class="o">+=</span> <span class="mi">10</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">21</span>
<span class="c1"># reset back to base+mod by deleting current</span>
<span class="o">&gt;</span> <span class="k">del</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">current</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">11</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">max</span> <span class="o">=</span> <span class="kc">None</span> <span class="c1"># removing upper bound</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">mult</span> <span class="o">=</span> <span class="mf">100.0</span>
<span class="mi">1100</span>
<span class="c1"># for TraitProperties, pass the args/kwargs of traits.add() to the</span>
<span class="c1"># TraitProperty constructor instead.</span>
</pre></div>
</div>
<p>Counters have some extra properties:</p>
<section id="descs">
<h4>.descs<a class="headerlink" href="#descs" title="Permalink to this headline"></a></h4>
<p>The <strong>descs</strong> property is a dict {upper_bound:text_description}. This allows for easily
storing a more human-friendly description of the current value in the
interval. Here is an example for skill values between 0 and 10:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="mi">0</span><span class="p">:</span> <span class="s2">&quot;unskilled&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">:</span> <span class="s2">&quot;neophyte&quot;</span><span class="p">,</span> <span class="mi">5</span><span class="p">:</span> <span class="s2">&quot;trained&quot;</span><span class="p">,</span> <span class="mi">7</span><span class="p">:</span> <span class="s2">&quot;expert&quot;</span><span class="p">,</span> <span class="mi">9</span><span class="p">:</span> <span class="s2">&quot;master&quot;</span><span class="p">}</span>
</pre></div>
</div>
<p>The keys must be supplied from smallest to largest. Any values below the lowest and above the
highest description will be considered to be included in the closest description slot.
By calling <strong>.desc()</strong> on the Counter, you will get the text matching the current <strong>value</strong>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># (could also have passed descs= to traits.add())</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">descs</span> <span class="o">=</span> <span class="p">{</span>
<span class="mi">0</span><span class="p">:</span> <span class="s2">&quot;unskilled&quot;</span><span class="p">,</span> <span class="mi">10</span><span class="p">:</span> <span class="s2">&quot;neophyte&quot;</span><span class="p">,</span> <span class="mi">50</span><span class="p">:</span> <span class="s2">&quot;trained&quot;</span><span class="p">,</span> <span class="mi">70</span><span class="p">:</span> <span class="s2">&quot;expert&quot;</span><span class="p">,</span> <span class="mi">90</span><span class="p">:</span> <span class="s2">&quot;master&quot;</span><span class="p">}</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">11</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">desc</span><span class="p">()</span>
<span class="s2">&quot;neophyte&quot;</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">current</span> <span class="o">+=</span> <span class="mi">60</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">71</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">desc</span><span class="p">()</span>
<span class="s2">&quot;expert&quot;</span>
</pre></div>
</div>
</section>
<section id="rate">
<h4>.rate<a class="headerlink" href="#rate" title="Permalink to this headline"></a></h4>
<p>The <strong>rate</strong> property defaults to 0. If set to a value different from 0, it
allows the trait to change value dynamically. This could be used for example
for an attribute that was temporarily lowered but will gradually (or abruptly)
recover after a certain time. The rate is given as change of the current
<strong>.value</strong> per-second, and this will still be restrained by min/max boundaries,
if those are set.</p>
<p>It is also possible to set a <strong>.ratetarget</strong>, for the auto-change to stop at
(rather than at the min/max boundaries). This allows the value to return to
a previous value.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">71</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">ratetarget</span> <span class="o">=</span> <span class="mi">71</span>
<span class="c1"># debuff hunting for some reason</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">current</span> <span class="o">-=</span> <span class="mi">30</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">41</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">rate</span> <span class="o">=</span> <span class="mi">1</span> <span class="c1"># 1/s increase</span>
<span class="c1"># Waiting 5s</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">46</span>
<span class="c1"># Waiting 8s</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">54</span>
<span class="c1"># Waiting 100s</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">value</span>
<span class="mi">71</span> <span class="c1"># we have stopped at the ratetarget</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">rate</span> <span class="o">=</span> <span class="mi">0</span> <span class="c1"># disable auto-change</span>
</pre></div>
</div>
<p>Note that when retrieving the <strong>current</strong>, the result will always be of the same
type as the <strong>.base</strong> even <strong>rate</strong> is a non-integer value. So if <strong>base</strong> is an <strong>int</strong>
(default)**, the <strong>current</strong> value will also be rounded the closest full integer.
If you want to see the exact <strong>current</strong> value, set <strong>base</strong> to a float - you
will then need to use <strong>round()</strong> yourself on the result if you want integers.</p>
</section>
<section id="percent">
<h4>.percent()<a class="headerlink" href="#percent" title="Permalink to this headline"></a></h4>
<p>If both min and max are defined, the <strong>.percent()</strong> method of the trait will
return the value as a percentage.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">percent</span><span class="p">()</span>
<span class="s2">&quot;71.0%&quot;</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hunting</span><span class="o">.</span><span class="n">percent</span><span class="p">(</span><span class="n">formatting</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
<span class="mf">71.0</span>
</pre></div>
</div>
</section>
</section>
<section id="gauge">
<h3>Gauge<a class="headerlink" href="#gauge" title="Permalink to this headline"></a></h3>
<p>This emulates a [fuel-] gauge that empties from a base+mod value.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">min</span><span class="o">/</span><span class="mi">0</span> <span class="nb">max</span><span class="o">=</span><span class="n">base</span><span class="o">+</span><span class="n">mod</span>
<span class="o">|-----------------------</span><span class="n">X</span><span class="o">---------------------------|</span>
<span class="n">value</span>
<span class="o">=</span> <span class="n">current</span>
</pre></div>
</div>
<p>The <strong>.current</strong> value will start from a full gauge. The .max property is
read-only and is set by <strong>.base</strong> + <strong>.mod</strong>. So contrary to a <strong>Counter</strong>, the
<strong>.mod</strong> modifier only applies to the max value of the gauge and not the current
value. The minimum bound defaults to 0 if not set explicitly.</p>
<p>This trait is useful for showing commonly depletable resources like health,
stamina and the like.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;hp&quot;</span><span class="p">,</span> <span class="s2">&quot;Health&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;gauge&quot;</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">value</span> <span class="c1"># (or .current)</span>
<span class="mi">100</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">mod</span> <span class="o">=</span> <span class="mi">10</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">value</span>
<span class="mi">110</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">current</span> <span class="o">-=</span> <span class="mi">30</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">value</span>
<span class="mi">80</span>
</pre></div>
</div>
<p>The Gauge trait is subclass of the Counter, so you have access to the same
methods and properties where they make sense. So gauges can also have a
<strong>.descs</strong> dict to describe the intervals in text, and can use <strong>.percent()</strong> to
get how filled it is as a percentage etc.</p>
<p>The <strong>.rate</strong> is particularly relevant for gauges - useful for everything
from poison slowly draining your health, to resting gradually increasing it.</p>
</section>
<section id="trait">
<h3>Trait<a class="headerlink" href="#trait" title="Permalink to this headline"></a></h3>
<p>A single value of any type.</p>
<p>This is the ‘base’ Trait, meant to inherit from if you want to invent
trait-types from scratch (most of the time you’ll probably inherit from some of
the more advanced trait-type classes though).</p>
<p>Unlike other Trait-types, the single <strong>.value</strong> property of the base <strong>Trait</strong> can
be editied. The value can hold any data that can be stored in an Attribute. If
it’s an integer/float you can do arithmetic with it, but otherwise this acts just
like a glorified Attribute.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;mytrait&quot;</span><span class="p">,</span> <span class="s2">&quot;My Trait&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;trait&quot;</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="mi">30</span><span class="p">)</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mytrait</span><span class="o">.</span><span class="n">value</span>
<span class="mi">30</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mytrait</span><span class="o">.</span><span class="n">value</span> <span class="o">=</span> <span class="s2">&quot;stringvalue&quot;</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mytrait</span><span class="o">.</span><span class="n">value</span>
<span class="s2">&quot;stringvalue&quot;</span>
</pre></div>
</div>
</section>
</section>
<section id="expanding-with-your-own-traits">
<h2>Expanding with your own Traits<a class="headerlink" href="#expanding-with-your-own-traits" title="Permalink to this headline"></a></h2>
<p>A Trait is a class inhering from <strong>evennia.contrib.rpg.traits.Trait</strong> (or from one of
the existing Trait classes).</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># in a file, say, &#39;mygame/world/traits.py&#39;</span>
<span class="kn">from</span> <span class="nn">evennia.contrib.rpg.traits</span> <span class="kn">import</span> <span class="n">StaticTrait</span>
<span class="k">class</span> <span class="nc">RageTrait</span><span class="p">(</span><span class="n">StaticTrait</span><span class="p">):</span>
<span class="n">trait_type</span> <span class="o">=</span> <span class="s2">&quot;rage&quot;</span>
<span class="n">default_keys</span> <span class="o">=</span> <span class="p">{</span>
<span class="s2">&quot;rage&quot;</span><span class="p">:</span> <span class="mi">0</span>
<span class="p">}</span>
<span class="k">def</span> <span class="nf">berserk</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">mod</span> <span class="o">=</span> <span class="mi">100</span>
<span class="k">def</span> <span class="nf">sedate</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">mod</span> <span class="o">=</span> <span class="mi">0</span>
</pre></div>
</div>
<p>Above is an example custom-trait-class “rage” that stores a property “rage” on
itself, with a default value of 0. This has all the functionality of a Trait -
for example, if you do del on the <strong>rage</strong> property, it will be set back to its
default (0). Above we also added some helper methods.</p>
<p>To add your custom RageTrait to Evennia, add the following to your settings file
(assuming your class is in mygame/world/traits.py):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TRAIT_CLASS_PATHS</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;world.traits.RageTrait&quot;</span><span class="p">]</span>
</pre></div>
</div>
<p>Reload the server and you should now be able to use your trait:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;mood&quot;</span><span class="p">,</span> <span class="s2">&quot;A dark mood&quot;</span><span class="p">,</span> <span class="n">rage</span><span class="o">=</span><span class="mi">30</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s1">&#39;rage&#39;</span><span class="p">)</span>
<span class="o">&gt;</span> <span class="n">obj</span><span class="o">.</span><span class="n">traits</span><span class="o">.</span><span class="n">mood</span><span class="o">.</span><span class="n">rage</span>
<span class="mi">30</span>
<span class="c1"># as TraitProperty</span>
<span class="k">class</span> <span class="nc">Character</span><span class="p">(</span><span class="n">DefaultCharacter</span><span class="p">):</span>
<span class="n">rage</span> <span class="o">=</span> <span class="n">TraitProperty</span><span class="p">(</span><span class="s2">&quot;A dark mood&quot;</span><span class="p">,</span> <span class="n">rage</span><span class="o">=</span><span class="mi">30</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s1">&#39;rage&#39;</span><span class="p">)</span>
</pre></div>
</div>
<hr class="docutils" />
<dl class="py exception">
<dt id="evennia.contrib.rpg.traits.traits.TraitException">
<em class="property">exception </em><code class="sig-prename descclassname">evennia.contrib.rpg.traits.traits.</code><code class="sig-name descname">TraitException</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">msg</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#TraitException"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitException" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">RuntimeError</span></code></p>
<p>Base exception class raised by <strong>Trait</strong> objects.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>msg</strong> (<em>str</em>) – informative error message</p>
</dd>
</dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.TraitException.__init__">
<code class="sig-name descname">__init__</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">msg</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#TraitException.__init__"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitException.__init__" title="Permalink to this definition"></a></dt>
<dd><p>Initialize self. See help(type(self)) for accurate signature.</p>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt id="evennia.contrib.rpg.traits.traits.MandatoryTraitKey">
<em class="property">class </em><code class="sig-prename descclassname">evennia.contrib.rpg.traits.traits.</code><code class="sig-name descname">MandatoryTraitKey</code><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#MandatoryTraitKey"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.MandatoryTraitKey" 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>This represents a required key that must be
supplied when a Trait is initialized. It’s used
by Trait classes when defining their required keys.</p>
</dd></dl>
<dl class="py class">
<dt id="evennia.contrib.rpg.traits.traits.TraitHandler">
<em class="property">class </em><code class="sig-prename descclassname">evennia.contrib.rpg.traits.traits.</code><code class="sig-name descname">TraitHandler</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_key</span><span class="o">=</span><span class="default_value">'traits'</span></em>, <em class="sig-param"><span class="n">db_attribute_category</span><span class="o">=</span><span class="default_value">'traits'</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#TraitHandler"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitHandler" 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>Factory class that instantiates Trait objects. Must be assigned as a property
on the class, usually with <strong>lazy_property</strong>.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Object</span><span class="p">(</span><span class="n">DefaultObject</span><span class="p">):</span>
<span class="o">...</span>
<span class="nd">@lazy_property</span>
<span class="k">def</span> <span class="nf">traits</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># this adds the handler as .traits</span>
<span class="k">return</span> <span class="n">TraitHandler</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
</pre></div>
</div>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.TraitHandler.__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_key</span><span class="o">=</span><span class="default_value">'traits'</span></em>, <em class="sig-param"><span class="n">db_attribute_category</span><span class="o">=</span><span class="default_value">'traits'</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#TraitHandler.__init__"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitHandler.__init__" title="Permalink to this definition"></a></dt>
<dd><p>Initialize the handler and set up its internal Attribute-based storage.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>obj</strong> (<em>Object</em>) – Parent Object typeclass for this TraitHandler</p></li>
<li><p><strong>db_attribute_key</strong> (<em>str</em>) – Name of the DB attribute for trait data storage.</p></li>
<li><p><strong>db_attribute_category</strong> (<em>str</em>) – Name of DB attribute’s category to trait data storage.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.TraitHandler.all">
<code class="sig-name descname">all</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#TraitHandler.all"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitHandler.all" title="Permalink to this definition"></a></dt>
<dd><p>Get all trait keys in this handler.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><em>list</em> – All Trait keys.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.TraitHandler.get">
<code class="sig-name descname">get</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">trait_key</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#TraitHandler.get"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitHandler.get" title="Permalink to this definition"></a></dt>
<dd><dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>trait_key</strong> (<em>str</em>) – key from the traits dict containing config data.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>(<strong>Trait</strong> or <strong>None</strong>) – named Trait class or None if trait key
is not found in traits collection.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.TraitHandler.add">
<code class="sig-name descname">add</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">trait_key</span></em>, <em class="sig-param"><span class="n">name</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">trait_type</span><span class="o">=</span><span class="default_value">'static'</span></em>, <em class="sig-param"><span class="n">force</span><span class="o">=</span><span class="default_value">True</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">trait_properties</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#TraitHandler.add"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitHandler.add" title="Permalink to this definition"></a></dt>
<dd><p>Create a new Trait and add it to the handler.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>trait_key</strong> (<em>str</em>) – This is the name of the property that will be made
available on this handler (example ‘hp’).</p></li>
<li><p><strong>name</strong> (<em>str</em><em>, </em><em>optional</em>) – Name of the Trait, like “Health”. If
not given, will use <strong>trait_key</strong> starting with a capital letter.</p></li>
<li><p><strong>trait_type</strong> (<em>str</em><em>, </em><em>optional</em>) – One of ‘static’, ‘counter’ or ‘gauge’.</p></li>
<li><p><strong>force</strong> (<em>bool</em>) – If set, create a new Trait even if a Trait with
the same <strong>trait_key</strong> already exists.</p></li>
<li><p><strong>trait_properties</strong> (<em>dict</em>) – These will all be use to initialize
the new trait. See the <strong>properties</strong> class variable on each
Trait class to see which are required.</p></li>
</ul>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><p><a class="reference internal" href="#evennia.contrib.rpg.traits.traits.TraitException" title="evennia.contrib.rpg.traits.traits.TraitException"><strong>TraitException</strong></a> – If specifying invalid values for the given Trait,
the <strong>trait_type</strong> is not recognized, or an existing trait
already exists (and <strong>force</strong> is unset).</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.TraitHandler.remove">
<code class="sig-name descname">remove</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">trait_key</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#TraitHandler.remove"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitHandler.remove" title="Permalink to this definition"></a></dt>
<dd><p>Remove a Trait from the handler’s parent object.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>trait_key</strong> (<em>str</em>) – The name of the trait to remove.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.TraitHandler.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/rpg/traits/traits.html#TraitHandler.clear"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitHandler.clear" title="Permalink to this definition"></a></dt>
<dd><p>Remove all Traits from the handler’s parent object.</p>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt id="evennia.contrib.rpg.traits.traits.TraitProperty">
<em class="property">class </em><code class="sig-prename descclassname">evennia.contrib.rpg.traits.traits.</code><code class="sig-name descname">TraitProperty</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">name</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">trait_type</span><span class="o">=</span><span class="default_value">'static'</span></em>, <em class="sig-param"><span class="n">force</span><span class="o">=</span><span class="default_value">True</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">trait_properties</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#TraitProperty"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitProperty" 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>Optional extra: Allows for applying traits as individual properties directly on the parent class
instead for properties on the <strong>.traits</strong> handler. So with this you could access data e.g. as
<strong>character.hp.value</strong> instead of <strong>character.traits.hp.value</strong>. This still uses the traitshandler
under the hood.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">lazy_property</span>
<span class="kn">from</span> <span class="nn">evennia.contrib.rpg.traits</span> <span class="kn">import</span> <span class="n">TraitProperty</span>
<span class="k">class</span> <span class="nc">Character</span><span class="p">(</span><span class="n">DefaultCharacter</span><span class="p">):</span>
<span class="n">strength</span> <span class="o">=</span> <span class="n">TraitProperty</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;STR&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;static&quot;</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">mod</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="n">hunting</span> <span class="o">=</span> <span class="n">TraitProperty</span><span class="p">(</span><span class="s2">&quot;Hunting Skill&quot;</span><span class="p">,</span> <span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;counter&quot;</span><span class="p">,</span>
<span class="n">base</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">mod</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="nb">max</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
<span class="n">health</span> <span class="o">=</span> <span class="n">TraitProperty</span><span class="p">(</span><span class="n">trait_type</span><span class="o">=</span><span class="s2">&quot;gauge&quot;</span><span class="p">,</span> <span class="nb">min</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
</pre></div>
</div>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.TraitProperty.__init__">
<code class="sig-name descname">__init__</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">name</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">trait_type</span><span class="o">=</span><span class="default_value">'static'</span></em>, <em class="sig-param"><span class="n">force</span><span class="o">=</span><span class="default_value">True</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">trait_properties</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#TraitProperty.__init__"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.TraitProperty.__init__" title="Permalink to this definition"></a></dt>
<dd><p>Initialize a TraitField. Mimics TraitHandler.add input except no <strong>trait_key</strong>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>name</strong> (<em>str</em><em>, </em><em>optional</em>) – Name of the Trait, like “Health”. If
not given, will use <strong>trait_key</strong> starting with a capital letter.</p></li>
<li><p><strong>trait_type</strong> (<em>str</em><em>, </em><em>optional</em>) – One of ‘static’, ‘counter’ or ‘gauge’.</p></li>
<li><p><strong>force</strong> (<em>bool</em>) – If set, create a new Trait even if a Trait with
the same <strong>trait_key</strong> already exists.</p></li>
</ul>
</dd>
</dl>
<dl class="simple">
<dt>Kwargs:</dt><dd><dl class="simple">
<dt>traithandler_name (str): If given, this is used as the name of the TraitHandler created</dt><dd><p>behind the scenes. If not set, this will be a property <strong>traits</strong> on the class.</p>
</dd>
<dt>any: All other trait_properties are the same as for adding a new trait of the given type</dt><dd><p>using the normal TraitHandler.</p>
</dd>
</dl>
</dd>
</dl>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt id="evennia.contrib.rpg.traits.traits.Trait">
<em class="property">class </em><code class="sig-prename descclassname">evennia.contrib.rpg.traits.traits.</code><code class="sig-name descname">Trait</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">trait_data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#Trait"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.Trait" 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>Represents an object or Character trait. This simple base is just
storing anything in it’s ‘value’ property, so it’s pretty much just a
different wrapper to an Attribute. It does no type-checking of what is
stored.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>See module docstring for configuration details.</p>
</div>
<p>value</p>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.traits.traits.Trait.trait_type">
<code class="sig-name descname">trait_type</code><em class="property"> = 'trait'</em><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.Trait.trait_type" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.traits.traits.Trait.default_keys">
<code class="sig-name descname">default_keys</code><em class="property"> = {'value': None}</em><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.Trait.default_keys" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.traits.traits.Trait.allow_extra_properties">
<code class="sig-name descname">allow_extra_properties</code><em class="property"> = True</em><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.Trait.allow_extra_properties" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.Trait.__init__">
<code class="sig-name descname">__init__</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">trait_data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#Trait.__init__"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.Trait.__init__" title="Permalink to this definition"></a></dt>
<dd><p>This both initializes and validates the Trait on creation. It must
raise exception if validation fails. The TraitHandler will call this
when the trait is furst added, to make sure it validates before
storing.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>trait_data</strong> (<em>any</em>) – Any pickle-able values to store with this trait.
This must contain any cls.default_keys that do not have a default
value in cls.data_default_values. Any extra kwargs will be made
available as extra properties on the Trait, assuming the class
variable <strong>allow_extra_properties</strong> is set.</p>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><p><a class="reference internal" href="#evennia.contrib.rpg.traits.traits.TraitException" title="evennia.contrib.rpg.traits.traits.TraitException"><strong>TraitException</strong></a> – If input-validation failed.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.Trait.validate_input">
<em class="property">static </em><code class="sig-name descname">validate_input</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">cls</span></em>, <em class="sig-param"><span class="n">trait_data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#Trait.validate_input"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.Trait.validate_input" title="Permalink to this definition"></a></dt>
<dd><p>Validate input</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>trait_data</strong> (<em>dict</em><em> or </em><em>_SaverDict</em>) – Data to be used for
initialization of this trait.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><p><em>dict</em> –</p>
<dl class="simple">
<dt>Validated data, possibly complemented with default</dt><dd><p>values from default_keys.</p>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><p><a class="reference internal" href="#evennia.contrib.rpg.traits.traits.TraitException" title="evennia.contrib.rpg.traits.traits.TraitException"><strong>TraitException</strong></a> – If finding unset keys without a default.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.Trait.name">
<em class="property">property </em><code class="sig-name descname">name</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.Trait.name" title="Permalink to this definition"></a></dt>
<dd><p>Display name for the trait.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.Trait.key">
<em class="property">property </em><code class="sig-name descname">key</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.Trait.key" title="Permalink to this definition"></a></dt>
<dd><p>Display name for the trait.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.Trait.value">
<em class="property">property </em><code class="sig-name descname">value</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.Trait.value" title="Permalink to this definition"></a></dt>
<dd><p>Store a value</p>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt id="evennia.contrib.rpg.traits.traits.StaticTrait">
<em class="property">class </em><code class="sig-prename descclassname">evennia.contrib.rpg.traits.traits.</code><code class="sig-name descname">StaticTrait</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">trait_data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#StaticTrait"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.StaticTrait" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="#evennia.contrib.rpg.traits.traits.Trait" title="evennia.contrib.rpg.traits.traits.Trait"><code class="xref py py-class docutils literal notranslate"><span class="pre">evennia.contrib.rpg.traits.traits.Trait</span></code></a></p>
<p>Static Trait. This is a single value with a modifier,
multiplier, and no concept of a ‘current’ value or min/max etc.</p>
<p>value = (base + mod) * mult</p>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.traits.traits.StaticTrait.trait_type">
<code class="sig-name descname">trait_type</code><em class="property"> = 'static'</em><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.StaticTrait.trait_type" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.traits.traits.StaticTrait.default_keys">
<code class="sig-name descname">default_keys</code><em class="property"> = {'base': 0, 'mod': 0, 'mult': 1.0}</em><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.StaticTrait.default_keys" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.StaticTrait.base">
<em class="property">property </em><code class="sig-name descname">base</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.StaticTrait.base" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.StaticTrait.mod">
<em class="property">property </em><code class="sig-name descname">mod</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.StaticTrait.mod" title="Permalink to this definition"></a></dt>
<dd><p>The trait’s modifier.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.StaticTrait.mult">
<em class="property">property </em><code class="sig-name descname">mult</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.StaticTrait.mult" title="Permalink to this definition"></a></dt>
<dd><p>The trait’s multiplier.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.StaticTrait.value">
<em class="property">property </em><code class="sig-name descname">value</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.StaticTrait.value" title="Permalink to this definition"></a></dt>
<dd><p>The value of the Trait.</p>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait">
<em class="property">class </em><code class="sig-prename descclassname">evennia.contrib.rpg.traits.traits.</code><code class="sig-name descname">CounterTrait</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">trait_data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#CounterTrait"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="#evennia.contrib.rpg.traits.traits.Trait" title="evennia.contrib.rpg.traits.traits.Trait"><code class="xref py py-class docutils literal notranslate"><span class="pre">evennia.contrib.rpg.traits.traits.Trait</span></code></a></p>
<p>Counter Trait.</p>
<p>This includes modifications and min/max limits as well as the notion of a
current value. The value can also be reset to the base value.</p>
<dl class="simple">
<dt>min/unset base (base+mod)*mult max/unset</dt><dd><dl class="simple">
<dt><a href="#id1"><span class="problematic" id="id2">|--------------|</span></a>——–<a href="#id3"><span class="problematic" id="id4">|---------X--------X------------|</span></a></dt><dd><dl class="simple">
<dt>current value</dt><dd><p>= (current
+ mod)
* mult</p>
</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
<ul>
<li><p>value = (current + mod) * mult, starts at (base + mod) * mult</p></li>
<li><p>if min or max is None, there is no upper/lower bound (default)</p></li>
<li><p>if max is set to “base”, max will be equal ot base+mod</p></li>
<li><p>descs are used to optionally describe each value interval.
The desc of the current <strong>value</strong> value can then be retrieved
with .desc(). The property is set as {lower_bound_inclusive:desc}
and should be given smallest-to-biggest. For example, for
a skill rating between 0 and 10:</p>
<blockquote>
<div><dl class="simple">
<dt>{0: “unskilled”,</dt><dd><p>1: “neophyte”,
5: “traited”,
7: “expert”,
9: “master”}</p>
</dd>
</dl>
</div></blockquote>
</li>
<li><p>rate/ratetarget are optional settings to include a rate-of-change
of the current value. This is calculated on-demand and allows for
describing a value that is gradually growing smaller/bigger. The
increase will stop when either reaching a boundary (if set) or
ratetarget. Setting the rate to 0 (default) stops any change.</p></li>
</ul>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.trait_type">
<code class="sig-name descname">trait_type</code><em class="property"> = 'counter'</em><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.trait_type" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.default_keys">
<code class="sig-name descname">default_keys</code><em class="property"> = {'base': 0, 'descs': None, 'max': None, 'min': None, 'mod': 0, 'mult': 1.0, 'rate': 0, 'ratetarget': None}</em><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.default_keys" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.validate_input">
<em class="property">static </em><code class="sig-name descname">validate_input</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">cls</span></em>, <em class="sig-param"><span class="n">trait_data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#CounterTrait.validate_input"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.validate_input" title="Permalink to this definition"></a></dt>
<dd><p>Add extra validation for descs</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.base">
<em class="property">property </em><code class="sig-name descname">base</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.base" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.mod">
<em class="property">property </em><code class="sig-name descname">mod</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.mod" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.mult">
<em class="property">property </em><code class="sig-name descname">mult</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.mult" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.min">
<em class="property">property </em><code class="sig-name descname">min</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.min" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.max">
<em class="property">property </em><code class="sig-name descname">max</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.max" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.current">
<em class="property">property </em><code class="sig-name descname">current</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.current" title="Permalink to this definition"></a></dt>
<dd><p>The <strong>current</strong> value of the <strong>Trait</strong>. This does not have .mod added and is not .mult-iplied.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.value">
<em class="property">property </em><code class="sig-name descname">value</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.value" title="Permalink to this definition"></a></dt>
<dd><p>The value of the Trait. (current + mod) * mult</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.ratetarget">
<em class="property">property </em><code class="sig-name descname">ratetarget</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.ratetarget" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.percent">
<code class="sig-name descname">percent</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">formatting</span><span class="o">=</span><span class="default_value">'{:3.1f}%'</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#CounterTrait.percent"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.percent" title="Permalink to this definition"></a></dt>
<dd><p>Return the current value as a percentage.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>formatting</strong> (<em>str</em><em>, </em><em>optional</em>) – Should contain a
format-tag which will receive the value. If
this is set to None, the raw float will be
returned.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><p><em>float or str</em> –</p>
<dl class="simple">
<dt>Depending of if a <strong>formatting</strong> string</dt><dd><p>is supplied or not.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.reset">
<code class="sig-name descname">reset</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#CounterTrait.reset"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.reset" title="Permalink to this definition"></a></dt>
<dd><p>Resets <strong>current</strong> property equal to <strong>base</strong> value.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.CounterTrait.desc">
<code class="sig-name descname">desc</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#CounterTrait.desc"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.CounterTrait.desc" title="Permalink to this definition"></a></dt>
<dd><p>Retrieve descriptions of the current value, if available.</p>
<p>This must be a mapping {upper_bound_inclusive: text},
ordered from small to big. Any value above the highest
upper bound will be included as being in the highest bound.
rely on Python3.7+ dicts retaining ordering to let this
describe the interval.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><p><em>str</em> –</p>
<dl class="simple">
<dt>The description describing the <strong>value</strong> value.</dt><dd><p>If not found, returns the empty string.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait">
<em class="property">class </em><code class="sig-prename descclassname">evennia.contrib.rpg.traits.traits.</code><code class="sig-name descname">GaugeTrait</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">trait_data</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#GaugeTrait"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="#evennia.contrib.rpg.traits.traits.CounterTrait" title="evennia.contrib.rpg.traits.traits.CounterTrait"><code class="xref py py-class docutils literal notranslate"><span class="pre">evennia.contrib.rpg.traits.traits.CounterTrait</span></code></a></p>
<p>Gauge Trait.</p>
<p>This emulates a gauge-meter that empties from a (base+mod) * mult value.</p>
<dl>
<dt>min/0 max=(base+mod)*mult</dt><dd><dl>
<dt><a href="#id5"><span class="problematic" id="id6">|-----------------------X---------------------------|</span></a></dt><dd><blockquote>
<div><p>value</p>
</div></blockquote>
<p>= current</p>
</dd>
</dl>
</dd>
</dl>
<ul>
<li><p>min defaults to 0</p></li>
<li><p>max value is always (base + mod) * mult</p></li>
<li><p>.max is an alias of .base</p></li>
<li><p>value = current and varies from min to max.</p></li>
<li><dl>
<dt>descs is a mapping {upper_bound_inclusive: desc}. These</dt><dd><p>are checked with .desc() and can be retrieve a text
description for a given current value.</p>
<p>For example, this could be used to describe health
values between 0 and 100:</p>
<blockquote>
<div><dl class="simple">
<dt>{0: “Dead”</dt><dd><p>10: “Badly hurt”,
30: “Bleeding”,
50: “Hurting”,
90: “Healthy”}</p>
</dd>
</dl>
</div></blockquote>
</dd>
</dl>
</li>
</ul>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.trait_type">
<code class="sig-name descname">trait_type</code><em class="property"> = 'gauge'</em><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.trait_type" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.default_keys">
<code class="sig-name descname">default_keys</code><em class="property"> = {'base': 0, 'descs': None, 'min': 0, 'mod': 0, 'mult': 1.0, 'rate': 0, 'ratetarget': None}</em><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.default_keys" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.base">
<em class="property">property </em><code class="sig-name descname">base</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.base" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.mod">
<em class="property">property </em><code class="sig-name descname">mod</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.mod" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.mult">
<em class="property">property </em><code class="sig-name descname">mult</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.mult" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.min">
<em class="property">property </em><code class="sig-name descname">min</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.min" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.max">
<em class="property">property </em><code class="sig-name descname">max</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.max" title="Permalink to this definition"></a></dt>
<dd><p>The max is always (base + mod) * mult.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.current">
<em class="property">property </em><code class="sig-name descname">current</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.current" title="Permalink to this definition"></a></dt>
<dd><p>The <strong>current</strong> value of the gauge.</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.value">
<em class="property">property </em><code class="sig-name descname">value</code><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.value" title="Permalink to this definition"></a></dt>
<dd><p>The value of the trait</p>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.percent">
<code class="sig-name descname">percent</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">formatting</span><span class="o">=</span><span class="default_value">'{:3.1f}%'</span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#GaugeTrait.percent"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.percent" title="Permalink to this definition"></a></dt>
<dd><p>Return the current value as a percentage.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>formatting</strong> (<em>str</em><em>, </em><em>optional</em>) – Should contain a
format-tag which will receive the value. If
this is set to None, the raw float will be
returned.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><p><em>float or str</em> –</p>
<dl class="simple">
<dt>Depending of if a <strong>formatting</strong> string</dt><dd><p>is supplied or not.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="evennia.contrib.rpg.traits.traits.GaugeTrait.reset">
<code class="sig-name descname">reset</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/contrib/rpg/traits/traits.html#GaugeTrait.reset"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#evennia.contrib.rpg.traits.traits.GaugeTrait.reset" title="Permalink to this definition"></a></dt>
<dd><p>Fills the gauge to its maximum allowed by base + mod</p>
</dd></dl>
</dd></dl>
</section>
</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.tutorials.html" title="evennia.contrib.tutorials"
>next</a> |</li>
<li class="right" >
<a href="evennia.contrib.rpg.traits.tests.html" title="evennia.contrib.rpg.traits.tests"
>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.rpg.html" >evennia.contrib.rpg</a> &#187;</li>
<li class="nav-item nav-item-6"><a href="evennia.contrib.rpg.traits.html" >evennia.contrib.rpg.traits</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.contrib.rpg.traits.traits</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>
Reference in a new issue View git blame Copy permalink