evennia/docs/api/evennia.prototypes.spawner.html

<!DOCTYPE html>

<html lang="en" data-content_root="../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>evennia.prototypes.spawner &#8212; Evennia latest documentation</title>
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
    <link rel="stylesheet" type="text/css" href="../_static/nature.css?v=279e0f84" />
    <link rel="stylesheet" type="text/css" href="../_static/custom.css?v=e4a91a55" />
    <script src="../_static/documentation_options.js?v=c6e86fd7"></script>
    <script src="../_static/doctools.js?v=9bcbadda"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <link rel="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.scripts" href="evennia.scripts.html" />
    <link rel="prev" title="evennia.prototypes.prototypes" href="evennia.prototypes.prototypes.html" />
  </head><body>
    <div class="related" role="navigation" aria-label="Related">
      <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.scripts.html" title="evennia.scripts"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="evennia.prototypes.prototypes.html" title="evennia.prototypes.prototypes"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Evennia</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.prototypes.html" accesskey="U">evennia.prototypes</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">evennia.prototypes.spawner</a></li>
      </ul>
    </div>

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">

  <section id="module-evennia.prototypes.spawner">
<span id="evennia-prototypes-spawner"></span><h1>evennia.prototypes.spawner<a class="headerlink" href="#module-evennia.prototypes.spawner" title="Link to this heading">¶</a></h1>
<p>Spawner</p>
<p>The spawner takes input files containing object definitions in
dictionary forms. These use a prototype architecture to define
unique objects without having to make a Typeclass for each.</p>
<p>There  main function is <strong>spawn(*prototype)</strong>, where the <strong>prototype</strong>
is a dictionary like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">evennia.prototypes</span><span class="w"> </span><span class="kn">import</span> <span class="n">prototypes</span><span class="p">,</span> <span class="n">spawner</span>

<span class="n">prot</span> <span class="o">=</span> <span class="p">{</span>
 <span class="s2">&quot;prototype_key&quot;</span><span class="p">:</span> <span class="s2">&quot;goblin&quot;</span><span class="p">,</span>
 <span class="s2">&quot;typeclass&quot;</span><span class="p">:</span> <span class="s2">&quot;types.objects.Monster&quot;</span><span class="p">,</span>
 <span class="s2">&quot;key&quot;</span><span class="p">:</span> <span class="s2">&quot;goblin grunt&quot;</span><span class="p">,</span>
 <span class="s2">&quot;health&quot;</span><span class="p">:</span> <span class="k">lambda</span><span class="p">:</span> <span class="n">randint</span><span class="p">(</span><span class="mi">20</span><span class="p">,</span><span class="mi">30</span><span class="p">),</span>
 <span class="s2">&quot;resists&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;cold&quot;</span><span class="p">,</span> <span class="s2">&quot;poison&quot;</span><span class="p">],</span>
 <span class="s2">&quot;attacks&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;fists&quot;</span><span class="p">],</span>
 <span class="s2">&quot;weaknesses&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;fire&quot;</span><span class="p">,</span> <span class="s2">&quot;light&quot;</span><span class="p">]</span>
 <span class="s2">&quot;tags&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;mob&quot;</span><span class="p">,</span> <span class="s2">&quot;evil&quot;</span><span class="p">,</span> <span class="p">(</span><span class="s1">&#39;greenskin&#39;</span><span class="p">,</span><span class="s1">&#39;mob&#39;</span><span class="p">)]</span>
 <span class="s2">&quot;attrs&quot;</span><span class="p">:</span> <span class="p">[(</span><span class="s2">&quot;weapon&quot;</span><span class="p">,</span> <span class="s2">&quot;sword&quot;</span><span class="p">)]</span>
<span class="p">}</span>
<span class="c1"># spawn something with the prototype</span>
<span class="n">goblin</span> <span class="o">=</span> <span class="n">spawner</span><span class="o">.</span><span class="n">spawn</span><span class="p">(</span><span class="n">prot</span><span class="p">)</span>

<span class="c1"># make this into a db-saved prototype (optional)</span>
<span class="n">prot</span> <span class="o">=</span> <span class="n">prototypes</span><span class="o">.</span><span class="n">create_prototype</span><span class="p">(</span><span class="n">prot</span><span class="p">)</span>
</pre></div>
</div>
<dl>
<dt>Possible keywords are:</dt><dd><dl class="simple">
<dt>prototype_key (str):  name of this prototype. This is used when storing prototypes and should</dt><dd><p>be unique. This should always be defined but for prototypes defined in modules, the
variable holding the prototype dict will become the prototype_key if it’s not explicitly
given.</p>
</dd>
</dl>
<p>prototype_desc (str, optional): describes prototype in listings
prototype_locks (str, optional): locks for restricting access to this prototype. Locktypes</p>
<blockquote>
<div><p>supported are ‘edit’ and ‘use’.</p>
</div></blockquote>
<dl class="simple">
<dt>prototype_tags(list, optional): List of tags or tuples (tag, category) used to group prototype</dt><dd><p>in listings</p>
</dd>
<dt>prototype_parent (str, tuple or callable, optional): name (prototype_key) of eventual parent</dt><dd><p>prototype, or a list of parents, for multiple left-to-right inheritance.</p>
</dd>
</dl>
<p>prototype: Deprecated. Same meaning as ‘parent’.</p>
<dl class="simple">
<dt>typeclass (str or callable, optional): if not set, will use typeclass of parent prototype or use</dt><dd><p><strong>settings.BASE_OBJECT_TYPECLASS</strong></p>
</dd>
<dt>key (str or callable, optional): the name of the spawned object. If not given this will set to a</dt><dd><p>random hash</p>
</dd>
</dl>
<p>location (obj, str or callable, optional): location of the object - a valid object or #dbref
home (obj, str or callable, optional): valid object or #dbref
destination (obj, str or callable, optional): only valid for exits (object or #dbref)</p>
<p>permissions (str, list or callable, optional): which permissions for spawned object to have
locks (str or callable, optional): lock-string for the spawned object
aliases (str, list or callable, optional): Aliases for the spawned object
exec (str or callable, optional): this is a string of python code to execute or a list of such</p>
<blockquote>
<div><p>codes.  This can be used e.g. to trigger custom handlers on the object. The execution
namespace contains ‘evennia’ for the library and ‘obj’. All default spawn commands limit
this functionality to Developer/superusers. Usually it’s better to use callables or
prototypefuncs instead of this.</p>
</div></blockquote>
<dl class="simple">
<dt>tags (str, tuple, list or callable, optional): string or list of strings or tuples</dt><dd><p><strong>(tagstr, category)</strong>. Plain strings will be result in tags with no category (default tags).</p>
</dd>
<dt>attrs (tuple, list or callable, optional): tuple or list of tuples of Attributes to add. This</dt><dd><p>form allows more complex Attributes to be set. Tuples at least specify <strong>(key, value)</strong>
but can also specify up to <strong>(key, value, category, lockstring)</strong>. If you want to specify a
lockstring but not a category, set the category to <strong>None</strong>.</p>
</dd>
</dl>
<p>ndb_&lt;name&gt; (any): value of a nattribute (<a href="#id1"><span class="problematic" id="id2">ndb_</span></a> is stripped) - this is of limited use.
other (any): any other name is interpreted as the key of an Attribute with</p>
<blockquote>
<div><p>its value. Such Attributes have no categories.</p>
</div></blockquote>
</dd>
</dl>
<p>Each value can also be a callable that takes no arguments. It should
return the value to enter into the field and will be called every time
the prototype is used to spawn an object. Note, if you want to store
a callable in an Attribute, embed it in a tuple to the <strong>args</strong> keyword.</p>
<p>By specifying the “prototype_parent” key, the prototype becomes a child of
the given prototype, inheritng all prototype slots it does not explicitly
define itself, while overloading those that it does specify.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">random</span>


<span class="p">{</span>
 <span class="s2">&quot;prototype_key&quot;</span><span class="p">:</span> <span class="s2">&quot;goblin_wizard&quot;</span><span class="p">,</span>
 <span class="s2">&quot;prototype_parent&quot;</span><span class="p">:</span> <span class="s2">&quot;GOBLIN&quot;</span><span class="p">,</span>
 <span class="s2">&quot;key&quot;</span><span class="p">:</span> <span class="s2">&quot;goblin wizard&quot;</span><span class="p">,</span>
 <span class="s2">&quot;spells&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;fire ball&quot;</span><span class="p">,</span> <span class="s2">&quot;lighting bolt&quot;</span><span class="p">]</span>
 <span class="p">}</span>

<span class="n">GOBLIN_ARCHER</span> <span class="o">=</span> <span class="p">{</span>
 <span class="s2">&quot;prototype_parent&quot;</span><span class="p">:</span> <span class="s2">&quot;GOBLIN&quot;</span><span class="p">,</span>
 <span class="s2">&quot;key&quot;</span><span class="p">:</span> <span class="s2">&quot;goblin archer&quot;</span><span class="p">,</span>
 <span class="s2">&quot;attack_skill&quot;</span><span class="p">:</span> <span class="p">(</span><span class="n">random</span><span class="p">,</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">))</span><span class="s2">&quot;</span>
 <span class="s2">&quot;attacks&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;short bow&quot;</span><span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
<p>One can also have multiple prototypes. These are inherited from the
left, with the ones further to the right taking precedence.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ARCHWIZARD</span> <span class="o">=</span> <span class="p">{</span>
 <span class="s2">&quot;attack&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;archwizard staff&quot;</span><span class="p">,</span> <span class="s2">&quot;eye of doom&quot;</span><span class="p">]</span>

<span class="n">GOBLIN_ARCHWIZARD</span> <span class="o">=</span> <span class="p">{</span>
 <span class="s2">&quot;key&quot;</span> <span class="p">:</span> <span class="s2">&quot;goblin archwizard&quot;</span>
 <span class="s2">&quot;prototype_parent&quot;</span><span class="p">:</span> <span class="p">(</span><span class="s2">&quot;GOBLIN_WIZARD&quot;</span><span class="p">,</span> <span class="s2">&quot;ARCHWIZARD&quot;</span><span class="p">),</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <em>goblin archwizard</em> will have some different attacks, but will
otherwise have the same spells as a <em>goblin wizard</em> who in turn shares
many traits with a normal <em>goblin</em>.</p>
<p>Storage mechanism:</p>
<p>This sets up a central storage for prototypes. The idea is to make these
available in a repository for buildiers to use. Each prototype is stored
in a Script so that it can be tagged for quick sorting/finding and locked for limiting
access.</p>
<p>This system also takes into consideration prototypes defined and stored in modules.
Such prototypes are considered ‘read-only’ to the system and can only be modified
in code. To replace a default prototype, add the same-name prototype in a
custom module read later in the settings.PROTOTYPE_MODULES list. To remove a default
prototype, override its name with an empty dict.</p>
<dl class="py class">
<dt class="sig sig-object py" id="evennia.prototypes.spawner.Unset">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">evennia.prototypes.spawner.</span></span><span class="sig-name descname"><span class="pre">Unset</span></span><a class="reference internal" href="../_modules/evennia/prototypes/spawner.html#Unset"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.prototypes.spawner.Unset" title="Link 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>Helper class representing a non-set diff element.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="evennia.prototypes.spawner.flatten_prototype">
<span class="sig-prename descclassname"><span class="pre">evennia.prototypes.spawner.</span></span><span class="sig-name descname"><span class="pre">flatten_prototype</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prototype</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">validate</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">no_db</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/prototypes/spawner.html#flatten_prototype"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.prototypes.spawner.flatten_prototype" title="Link to this definition">¶</a></dt>
<dd><p>Produce a ‘flattened’ prototype, where all prototype parents in the inheritance tree have been
merged into a final prototype.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>prototype</strong> (<em>dict</em>) – Prototype to flatten. Its <strong>prototype_parent</strong> field will be parsed.</p></li>
<li><p><strong>validate</strong> (<em>bool</em><em>, </em><em>optional</em>) – Validate for valid keys etc.</p></li>
<li><p><strong>no_db</strong> (<em>bool</em><em>, </em><em>optional</em>) – Don’t search db-based prototypes. This can speed up
searching dramatically since module-based prototypes are static.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>flattened (dict)</em> – The final, flattened prototype.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="evennia.prototypes.spawner.prototype_from_object">
<span class="sig-prename descclassname"><span class="pre">evennia.prototypes.spawner.</span></span><span class="sig-name descname"><span class="pre">prototype_from_object</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/prototypes/spawner.html#prototype_from_object"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.prototypes.spawner.prototype_from_object" title="Link to this definition">¶</a></dt>
<dd><p>Guess a minimal prototype from an existing object.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>obj</strong> (<em>Object</em>) – An object to analyze.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>prototype (dict)</em> – A prototype estimating the current state of the object.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="evennia.prototypes.spawner.prototype_diff">
<span class="sig-prename descclassname"><span class="pre">evennia.prototypes.spawner.</span></span><span class="sig-name descname"><span class="pre">prototype_diff</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prototype1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">prototype2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">maxdepth</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">homogenize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">implicit_keep</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/prototypes/spawner.html#prototype_diff"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.prototypes.spawner.prototype_diff" title="Link to this definition">¶</a></dt>
<dd><p>A ‘detailed’ diff specifies differences down to individual sub-sections
of the prototype, like individual attributes, permissions etc. It is used
by the menu to allow a user to customize what should be kept.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>prototype1</strong> (<em>dict</em>) – Original prototype.</p></li>
<li><p><strong>prototype2</strong> (<em>dict</em>) – Comparison prototype.</p></li>
<li><p><strong>maxdepth</strong> (<em>int</em><em>, </em><em>optional</em>) – The maximum depth into the diff we go before treating the elements
of iterables as individual entities to compare. This is important since a single
attr/tag (for example) are represented by a tuple.</p></li>
<li><p><strong>homogenize</strong> (<em>bool</em><em>, </em><em>optional</em>) – Auto-homogenize both prototypes for the best comparison.
This is most useful for displaying.</p></li>
<li><p><strong>implicit_keep</strong> (<em>bool</em><em>, </em><em>optional</em>) – If set, the resulting diff will assume KEEP unless the new
prototype explicitly change them. That is, if a key exists in <strong>prototype1</strong> and
not in <strong>prototype2</strong>, it will not be REMOVEd but set to KEEP instead. This is
particularly useful for auto-generated prototypes when updating objects.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>diff (dict)</em> –</p>
<dl class="simple">
<dt>A structure detailing how to convert prototype1 to prototype2. All</dt><dd><p>nested structures are dicts with keys matching either the prototype’s matching
key or the first element in the tuple describing the prototype value (so for
a tag tuple <strong>(tagname, category)</strong> the second-level key in the diff would be tagname).
The the bottom level of the diff consist of tuples <strong>(old, new, instruction)</strong>, where
instruction can be one of “REMOVE”, “ADD”, “UPDATE” or “KEEP”.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="evennia.prototypes.spawner.flatten_diff">
<span class="sig-prename descclassname"><span class="pre">evennia.prototypes.spawner.</span></span><span class="sig-name descname"><span class="pre">flatten_diff</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">diff</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/prototypes/spawner.html#flatten_diff"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.prototypes.spawner.flatten_diff" title="Link to this definition">¶</a></dt>
<dd><p>For spawning, a ‘detailed’ diff is not necessary, rather we just want instructions on how to
handle each root key.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>diff</strong> (<em>dict</em>) – Diff produced by <strong>prototype_diff</strong> and
possibly modified by the user. Note that also a pre-flattened diff will come out
unchanged by this function.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>flattened_diff (dict)</em> –</p>
<dl class="simple">
<dt>A flat structure detailing how to operate on each</dt><dd><p>root component of the prototype.</p>
</dd>
</dl>
</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<dl class="simple">
<dt>The flattened diff has the following possible instructions:</dt><dd><p>UPDATE, REPLACE, REMOVE</p>
</dd>
</dl>
<p>Many of the detailed diff’s values can hold nested structures with their own
individual instructions. A detailed diff can have the following instructions:</p>
<blockquote>
<div><p>REMOVE, ADD, UPDATE, KEEP</p>
</div></blockquote>
<dl class="simple">
<dt>Here’s how they are translated:</dt><dd><ul class="simple">
<li><p>All REMOVE -&gt; REMOVE</p></li>
<li><p>All ADD|UPDATE -&gt; UPDATE</p></li>
<li><p>All KEEP -&gt; KEEP</p></li>
<li><p>Mix KEEP, UPDATE, ADD -&gt; UPDATE</p></li>
<li><p>Mix REMOVE, KEEP, UPDATE, ADD -&gt; REPLACE</p></li>
</ul>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="evennia.prototypes.spawner.prototype_diff_from_object">
<span class="sig-prename descclassname"><span class="pre">evennia.prototypes.spawner.</span></span><span class="sig-name descname"><span class="pre">prototype_diff_from_object</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prototype</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">implicit_keep</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/prototypes/spawner.html#prototype_diff_from_object"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.prototypes.spawner.prototype_diff_from_object" title="Link to this definition">¶</a></dt>
<dd><p>Get a simple diff for a prototype compared to an object which may or may not already have a
prototype (or has one but changed locally). For more complex migratations a manual diff may be
needed.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>prototype</strong> (<em>dict</em>) – New prototype.</p></li>
<li><p><strong>obj</strong> (<em>Object</em>) – Object to compare prototype against.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>diff (dict)</em> – Mapping for every prototype key: {“keyname”: “REMOVE|UPDATE|KEEP”, …}
obj_prototype (dict): The prototype calculated for the given object. The diff is how to</p>
<blockquote>
<div><p>convert this prototype into the new prototype.</p>
</div></blockquote>
<dl class="simple">
<dt>implicit_keep (bool, optional): This is usually what one wants for object updating. When</dt><dd><p>set, this means the prototype diff will assume KEEP on differences
between the object-generated prototype and that which is not explicitly set in the
new prototype. This means e.g. that even though the object has a location, and the
prototype does not specify the location, it will not be unset.</p>
</dd>
</dl>
</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>The <strong>diff</strong> is on the following form:</p>
<blockquote>
<div><dl>
<dt>{“key”: (old, new, “KEEP|REPLACE|UPDATE|REMOVE”),</dt><dd><dl class="simple">
<dt>“attrs”: {“attrkey”: (old, new, “KEEP|REPLACE|UPDATE|REMOVE”),</dt><dd><p>“attrkey”: (old, new, “KEEP|REPLACE|UPDATE|REMOVE”), …},</p>
</dd>
</dl>
<p>“aliases”: {“aliasname”: (old, new, “KEEP…”, …},
… }</p>
</dd>
</dl>
</div></blockquote>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="evennia.prototypes.spawner.format_diff">
<span class="sig-prename descclassname"><span class="pre">evennia.prototypes.spawner.</span></span><span class="sig-name descname"><span class="pre">format_diff</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">diff</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">minimal</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/prototypes/spawner.html#format_diff"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.prototypes.spawner.format_diff" title="Link to this definition">¶</a></dt>
<dd><p>Reformat a diff for presentation. This is a shortened version
of the olc _format_diff_text_and_options without the options.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>diff</strong> (<em>dict</em>) – A diff as produced by <strong>prototype_diff</strong>.</p></li>
<li><p><strong>minimal</strong> (<em>bool</em><em>, </em><em>optional</em>) – Only show changes (remove KEEPs)</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>texts (str)</em> – The formatted text.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="evennia.prototypes.spawner.batch_update_objects_with_prototype">
<span class="sig-prename descclassname"><span class="pre">evennia.prototypes.spawner.</span></span><span class="sig-name descname"><span class="pre">batch_update_objects_with_prototype</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prototype</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">diff</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">objects</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exact</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">caller</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">protfunc_raise_errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/prototypes/spawner.html#batch_update_objects_with_prototype"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.prototypes.spawner.batch_update_objects_with_prototype" title="Link to this definition">¶</a></dt>
<dd><p>Update existing objects with the latest version of the prototype.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>prototype</strong> (<em>str</em><em> or </em><em>dict</em>) – Either the <strong>prototype_key</strong> to use or the
prototype dict itself.</p></li>
<li><p><strong>diff</strong> (<em>dict</em><em>, </em><em>optional</em>) – This a diff structure that describes how to update the protototype.
If not given this will be constructed from the first object found.</p></li>
<li><p><strong>objects</strong> (<em>list</em><em>, </em><em>optional</em>) – List of objects to update. If not given, query for these
objects using the prototype’s <strong>prototype_key</strong>.</p></li>
<li><p><strong>exact</strong> (<em>bool</em><em>, </em><em>optional</em>) – By default (<strong>False</strong>), keys not explicitly in the prototype will
not be applied to the object, but will be retained as-is. This is usually what is
expected - for example, one usually do not want to remove the object’s location even
if it’s not set in the prototype. With <strong>exact=True</strong>, all un-specified properties of the
objects will be removed if they exist. This will lead to a more accurate 1:1 correlation
between the  object and the prototype but is usually impractical.</p></li>
<li><p><strong>caller</strong> (<em>Object</em><em> or </em><em>Account</em><em>, </em><em>optional</em>) – This may be used by protfuncs to do permission checks.</p></li>
<li><p><strong>protfunc_raise_errors</strong> (<em>bool</em>) – Have protfuncs raise explicit errors if malformed/not found.
This is highly recommended.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>changed (int)</em> – The number of objects that had changes applied to them.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="evennia.prototypes.spawner.batch_create_object">
<span class="sig-prename descclassname"><span class="pre">evennia.prototypes.spawner.</span></span><span class="sig-name descname"><span class="pre">batch_create_object</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">objparams</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/prototypes/spawner.html#batch_create_object"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.prototypes.spawner.batch_create_object" title="Link to this definition">¶</a></dt>
<dd><p>This is a cut-down version of the create_object() function,
optimized for speed. It does NOT check and convert various input
so make sure the spawned Typeclass works before using this!</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>objsparams</strong> (<em>tuple</em>) – <p>Each paremter tuple will create one object instance using the parameters
within.
The parameters should be given in the following order:</p>
<blockquote>
<div><ul class="simple">
<li><p><strong>create_kwargs</strong> (dict): For use as new_obj = <strong>ObjectDB(**create_kwargs)</strong>.</p></li>
<li><p><strong>permissions</strong> (str): Permission string used with <strong>new_obj.batch_add(permission)</strong>.</p></li>
<li><p><strong>lockstring</strong> (str): Lockstring used with <strong>new_obj.locks.add(lockstring)</strong>.</p></li>
<li><dl class="simple">
<dt><strong>aliases</strong> (list): A list of alias strings for</dt><dd><p>adding with <strong>new_object.aliases.batch_add(*aliases)</strong>.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>nattributes</strong> (list): list of tuples <strong>(key, value)</strong> to be loop-added to</dt><dd><p>add with <strong>new_obj.nattributes.add(*tuple)</strong>.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>attributes</strong> (list): list of tuples <strong>(key, value[,category[,lockstring]])</strong> for</dt><dd><p>adding with <strong>new_obj.attributes.batch_add(*attributes)</strong>.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>tags</strong> (list): list of tuples <strong>(key, category)</strong> for adding</dt><dd><p>with <strong>new_obj.tags.batch_add(*tags)</strong>.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>execs</strong> (list): Code strings to execute together with the creation</dt><dd><dl class="simple">
<dt>of each object. They will be executed with <strong>evennia</strong> and <strong>obj</strong></dt><dd><p>(the newly created object) available in the namespace. Execution
will happend after all other properties have been assigned and
is intended for calling custom handlers etc.</p>
</dd>
</dl>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>objects (list)</em> – A list of created objects</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>The <strong>exec</strong> list will execute arbitrary python code so don’t allow this to be available to
unprivileged users!</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="evennia.prototypes.spawner.spawn">
<span class="sig-prename descclassname"><span class="pre">evennia.prototypes.spawner.</span></span><span class="sig-name descname"><span class="pre">spawn</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">prototypes</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">caller</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/prototypes/spawner.html#spawn"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.prototypes.spawner.spawn" title="Link to this definition">¶</a></dt>
<dd><p>Spawn a number of prototyped objects.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>prototypes</strong> (<em>str</em><em> or </em><em>dict</em>) – Each argument should either be a
prototype_key (will be used to find the prototype) or a full prototype
dictionary. These will be batched-spawned as one object each.</p>
</dd>
<dt class="field-even">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-even"><ul class="simple">
<li><p><strong>caller</strong> (<em>Object</em><em> or </em><em>Account</em><em>, </em><em>optional</em>) – This may be used by protfuncs to do access checks.</p></li>
<li><p><strong>prototype_modules</strong> (<em>str</em><em> or </em><em>list</em>) – A python-path to a prototype
module, or a list of such paths. These will be used to build
the global protparents dictionary accessible by the input
prototypes. If not given, it will instead look for modules
defined by settings.PROTOTYPE_MODULES.</p></li>
<li><p><strong>prototype_parents</strong> (<em>dict</em>) – A dictionary holding a custom
prototype-parent dictionary. Will overload same-named
prototypes from prototype_modules.</p></li>
<li><p><strong>only_validate</strong> (<em>bool</em>) – Only run validation of prototype/parents
(no object creation) and return the create-kwargs.</p></li>
<li><p><strong>protfunc_raise_errors</strong> (<em>bool</em>) – Raise explicit exceptions on a malformed/not-found
protfunc. Defaults to True.</p></li>
</ul>
</dd>
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p><p><em>object (Object, dict or list)</em> –</p>
<dl class="simple">
<dt>Spawned object(s). If <strong>only_validate</strong> is given, return</dt><dd><p>a list of the creation kwargs to build the object(s) without actually creating it.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>

</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="../index.html">
              <img class="logo" src="../_static/evennia_logo.png" alt="Logo of Evennia"/>
            </a></p>
<search 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" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<h3><a href="../index.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">evennia.prototypes.spawner</a><ul>
<li><a class="reference internal" href="#evennia.prototypes.spawner.Unset"><code class="docutils literal notranslate"><span class="pre">Unset</span></code></a></li>
<li><a class="reference internal" href="#evennia.prototypes.spawner.flatten_prototype"><code class="docutils literal notranslate"><span class="pre">flatten_prototype()</span></code></a></li>
<li><a class="reference internal" href="#evennia.prototypes.spawner.prototype_from_object"><code class="docutils literal notranslate"><span class="pre">prototype_from_object()</span></code></a></li>
<li><a class="reference internal" href="#evennia.prototypes.spawner.prototype_diff"><code class="docutils literal notranslate"><span class="pre">prototype_diff()</span></code></a></li>
<li><a class="reference internal" href="#evennia.prototypes.spawner.flatten_diff"><code class="docutils literal notranslate"><span class="pre">flatten_diff()</span></code></a></li>
<li><a class="reference internal" href="#evennia.prototypes.spawner.prototype_diff_from_object"><code class="docutils literal notranslate"><span class="pre">prototype_diff_from_object()</span></code></a></li>
<li><a class="reference internal" href="#evennia.prototypes.spawner.format_diff"><code class="docutils literal notranslate"><span class="pre">format_diff()</span></code></a></li>
<li><a class="reference internal" href="#evennia.prototypes.spawner.batch_update_objects_with_prototype"><code class="docutils literal notranslate"><span class="pre">batch_update_objects_with_prototype()</span></code></a></li>
<li><a class="reference internal" href="#evennia.prototypes.spawner.batch_create_object"><code class="docutils literal notranslate"><span class="pre">batch_create_object()</span></code></a></li>
<li><a class="reference internal" href="#evennia.prototypes.spawner.spawn"><code class="docutils literal notranslate"><span class="pre">spawn()</span></code></a></li>
</ul>
</li>
</ul>

  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="evennia.prototypes.prototypes.html"
                          title="previous chapter">evennia.prototypes.prototypes</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="evennia.scripts.html"
                          title="next chapter">evennia.scripts</a></p>
  </div>
  <div role="note" aria-label="source link">
    <!--h3>This Page</h3-->
    <ul class="this-page-menu">
      <li><a href="../_sources/api/evennia.prototypes.spawner.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="https://www.evennia.com/docs/latest/index.html">latest (main branch)</a>
    </li>


    <li>
      <a href="https://www.evennia.com/docs/5.x/index.html">v5.0.0 branch (outdated)</a>
    </li>

    <li>
      <a href="https://www.evennia.com/docs/4.x/index.html">v4.0.0 branch (outdated)</a>
    </li>

    <li>
      <a href="https://www.evennia.com/docs/3.x/index.html">v3.0.0 branch (outdated)</a>
    </li>

    <li>
      <a href="https://www.evennia.com/docs/2.x/index.html">v2.0.0 branch (outdated)</a>
    </li>

    <li>
      <a href="https://www.evennia.com/docs/1.x/index.html">v1.0.0 branch (outdated)</a>
    </li>

    <li>
      <a href="https://www.evennia.com/docs/0.x/index.html">v0.9.5 branch (outdated)</a>
    </li>

</ul>

        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="Related">
      <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.scripts.html" title="evennia.scripts"
             >next</a> |</li>
        <li class="right" >
          <a href="evennia.prototypes.prototypes.html" title="evennia.prototypes.prototypes"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Evennia</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.prototypes.html" >evennia.prototypes</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">evennia.prototypes.spawner</a></li>
      </ul>
    </div>
    <div class="footer" role="contentinfo">
    &#169; Copyright 2024, The Evennia developer community.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
    </div>
  </body>
</html>