<h1>Permissions<aclass="headerlink"href="#permissions"title="Permalink to this headline">¶</a></h1>
<p>A <em>permission</em> is simply a text string stored in the handler <codeclass="docutils literal notranslate"><spanclass="pre">permissions</span></code> on <codeclass="docutils literal notranslate"><spanclass="pre">Objects</span></code>
and <codeclass="docutils literal notranslate"><spanclass="pre">Accounts</span></code>. Think of it as a specialized sort of <aclass="reference internal"href="Tags.html"><spanclass="doc">Tag</span></a> - one specifically dedicated
to access checking. They are thus often tightly coupled to <aclass="reference internal"href="Locks.html"><spanclass="doc">Locks</span></a>.</p>
<p>Permissions are used as a convenient way to structure access levels and
hierarchies. It is set by the <codeclass="docutils literal notranslate"><spanclass="pre">perm</span></code> command. Permissions are especially
handled by the <codeclass="docutils literal notranslate"><spanclass="pre">perm()</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">pperm()</span></code><aclass="reference internal"href="Locks.html"><spanclass="doc">lock functions</span></a>.</p>
<p>Let’s say we have a <codeclass="docutils literal notranslate"><spanclass="pre">red_key</span></code> object. We also have red chests that we want to unlock with this key.</p>
<spanclass="normal">11</span></pre></div></td><tdclass="code"><divclass="highlight"><pre><span></span><spanclass="c1"># in some typeclass file where chest is defined</span>
<spanclass="n">who</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"The key does not fit!"</span><spanclass="p">)</span>
<spanclass="k">return</span>
</pre></div>
</td></tr></table></div>
<p>All new accounts are given a default set of permissions defined by
<p>Selected permission strings can be organized in a <em>permission hierarchy</em> by editing the tuple
<codeclass="docutils literal notranslate"><spanclass="pre">settings.PERMISSION_HIERARCHY</span></code>. Evennia’s default permission hierarchy is as follows:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="n">Developer</span><spanclass="c1"># like superuser but affected by locks</span>
<spanclass="n">Admin</span><spanclass="c1"># can administrate accounts</span>
<spanclass="n">Builder</span><spanclass="c1"># can edit the world</span>
<spanclass="n">Helper</span><spanclass="c1"># can edit help files</span>
<spanclass="n">Player</span><spanclass="c1"># can chat and send tells (default level)</span>
</pre></div>
</div>
<p>(Also the plural form works, so you could use <codeclass="docutils literal notranslate"><spanclass="pre">Developers</span></code> etc too).</p>
<blockquote>
<div><p>There is also a <codeclass="docutils literal notranslate"><spanclass="pre">Guest</span></code> level below <codeclass="docutils literal notranslate"><spanclass="pre">Player</span></code> that is only active if <codeclass="docutils literal notranslate"><spanclass="pre">settings.GUEST_ENABLED</span></code> is
set. This is never part of <codeclass="docutils literal notranslate"><spanclass="pre">settings.PERMISSION_HIERARCHY</span></code>.</p>
</div></blockquote>
<p>The main use of this is that if you use the lock function <codeclass="docutils literal notranslate"><spanclass="pre">perm()</span></code> mentioned above, a lock check for
a particular permission in the hierarchy will <em>also</em> grant access to those with <em>higher</em> hierarchy
access. So if you have the permission “Admin” you will also pass a lock defined as <codeclass="docutils literal notranslate"><spanclass="pre">perm(Builder)</span></code>
or any of those levels below “Admin”.</p>
<p>When doing an access check from an <aclass="reference internal"href="Objects.html"><spanclass="doc">Object</span></a> or Character, the <codeclass="docutils literal notranslate"><spanclass="pre">perm()</span></code> lock function will
always first use the permissions of any Account connected to that Object before checking for
permissions on the Object. In the case of hierarchical permissions (Admins, Builders etc), the
Account permission will always be used (this stops an Account from escalating their permission by
puppeting a high-level Character). If the permission looked for is not in the hierarchy, an exact
match is required, first on the Account and if not found there (or if no Account is connected), then
on the Object itself.</p>
<p>Here is how you use <codeclass="docutils literal notranslate"><spanclass="pre">perm</span></code> to give an account more permissions:</p>
<spanclass="n">perm</span><spanclass="o">/</span><spanclass="n">account</span><spanclass="o">/</span><spanclass="k">del</span><spanclass="n">Tommy</span><spanclass="o">=</span><spanclass="n">Builders</span><spanclass="c1"># remove it again</span>
</pre></div>
</div>
<p>Note the use of the <codeclass="docutils literal notranslate"><spanclass="pre">/account</span></code> switch. It means you assign the permission to the
<aclass="reference internal"href="Accounts.html"><spanclass="doc">Accounts</span></a> Tommy instead of any <aclass="reference internal"href="Objects.html"><spanclass="doc">Character</span></a> that also happens to be named
“Tommy”.</p>
<p>Putting permissions on the <em>Account</em> guarantees that they are kept, <em>regardless</em> of which Character
they are currently puppeting. This is especially important to remember when assigning permissions
from the <em>hierarchy tree</em> - as mentioned above, an Account’s permissions will overrule that of its
character. So to be sure to avoid confusion you should generally put hierarchy permissions on the
Account, not on their Characters (but see also <aclass="reference external"href="Components/Locks.html#Quelling">quelling</a>).</p>
<p>Below is an example of an object without any connected account</p>
<spanclass="n">obj2</span><spanclass="o">.</span><spanclass="n">locks</span><spanclass="o">.</span><spanclass="n">add</span><spanclass="p">(</span><spanclass="s2">"enter:perm_above(Accounts) and perm(cool_guy)"</span><spanclass="p">)</span>
<spanclass="n">obj2</span><spanclass="o">.</span><spanclass="n">access</span><spanclass="p">(</span><spanclass="n">obj1</span><spanclass="p">,</span><spanclass="s2">"enter"</span><spanclass="p">)</span><spanclass="c1"># this returns True!</span>
</pre></div>
</td></tr></table></div>
<p>And one example of a puppet with a connected account:</p>
<spanclass="n">obj2</span><spanclass="o">.</span><spanclass="n">locks</span><spanclass="o">.</span><spanclass="n">add</span><spanclass="p">(</span><spanclass="s2">"enter:perm_above(Accounts) and perm(cool_guy)"</span><spanclass="p">)</span>
<spanclass="n">obj2</span><spanclass="o">.</span><spanclass="n">access</span><spanclass="p">(</span><spanclass="n">puppet</span><spanclass="p">,</span><spanclass="s2">"enter"</span><spanclass="p">)</span><spanclass="c1"># this returns False!</span>
</pre></div>
</td></tr></table></div>
<sectionid="superusers">
<h2>Superusers<aclass="headerlink"href="#superusers"title="Permalink to this headline">¶</a></h2>
<p>There is normally only one <em>superuser</em> account and that is the one first created when starting
Evennia (User #1). This is sometimes known as the “Owner” or “God” user. A superuser has more than
full access - it completely <em>bypasses</em> all locks so no checks are even run. This allows for the
superuser to always have access to everything in an emergency. But it also hides any eventual errors
you might have made in your lock definitions. So when trying out game systems you should either use
quelling (see below) or make a second Developer-level character so your locks get tested correctly.</p>
</section>
<sectionid="quelling">
<h2>Quelling<aclass="headerlink"href="#quelling"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">quell</span></code> command can be used to enforce the <codeclass="docutils literal notranslate"><spanclass="pre">perm()</span></code> lockfunc to ignore permissions on the
Account and instead use the permissions on the Character only. This can be used e.g. by staff to
test out things with a lower permission level. Return to the normal operation with <codeclass="docutils literal notranslate"><spanclass="pre">unquell</span></code>. Note
that quelling will use the smallest of any hierarchical permission on the Account or Character, so
one cannot escalate one’s Account permission by quelling to a high-permission Character. Also the
superuser can quell their powers this way, making them affectable by locks.</p>
