<spanid="evennia-prototypes-spawner"></span><h1>evennia.prototypes.spawner<aclass="headerlink"href="#module-evennia.prototypes.spawner"title="Link to this heading">¶</a></h1>
<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>
<dlclass="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>
<dlclass="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>
<dlclass="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_<name> (any): value of a nattribute (<ahref="#id1"><spanclass="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>
<spanclass="s2">"attack"</span><spanclass="p">:</span><spanclass="p">[</span><spanclass="s2">"archwizard staff"</span><spanclass="p">,</span><spanclass="s2">"eye of doom"</span><spanclass="p">]</span>
<emclass="property"><spanclass="k"><spanclass="pre">class</span></span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">evennia.prototypes.spawner.</span></span><spanclass="sig-name descname"><spanclass="pre">Unset</span></span><aclass="reference internal"href="../_modules/evennia/prototypes/spawner.html#Unset"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#evennia.prototypes.spawner.Unset"title="Link to this definition">¶</a></dt>
<spanclass="sig-prename descclassname"><spanclass="pre">evennia.prototypes.spawner.</span></span><spanclass="sig-name descname"><spanclass="pre">flatten_prototype</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">prototype</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">validate</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">False</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">no_db</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">False</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/prototypes/spawner.html#flatten_prototype"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#evennia.prototypes.spawner.flatten_prototype"title="Link to this definition">¶</a></dt>
<spanclass="sig-prename descclassname"><spanclass="pre">evennia.prototypes.spawner.</span></span><spanclass="sig-name descname"><spanclass="pre">prototype_from_object</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">obj</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/prototypes/spawner.html#prototype_from_object"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#evennia.prototypes.spawner.prototype_from_object"title="Link to this definition">¶</a></dt>
<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>
<spanclass="sig-prename descclassname"><spanclass="pre">evennia.prototypes.spawner.</span></span><spanclass="sig-name descname"><spanclass="pre">flatten_diff</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">diff</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/prototypes/spawner.html#flatten_diff"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#evennia.prototypes.spawner.flatten_diff"title="Link to this definition">¶</a></dt>
<spanclass="sig-prename descclassname"><spanclass="pre">evennia.prototypes.spawner.</span></span><spanclass="sig-name descname"><spanclass="pre">prototype_diff_from_object</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">prototype</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">obj</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">implicit_keep</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">True</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/prototypes/spawner.html#prototype_diff_from_object"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#evennia.prototypes.spawner.prototype_diff_from_object"title="Link to this definition">¶</a></dt>
<ddclass="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>
<dlclass="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>
<pclass="rubric">Notes</p>
<p>The <strong>diff</strong> is on the following form:</p>
<spanclass="sig-prename descclassname"><spanclass="pre">evennia.prototypes.spawner.</span></span><spanclass="sig-name descname"><spanclass="pre">format_diff</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">diff</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">minimal</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">True</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/prototypes/spawner.html#format_diff"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#evennia.prototypes.spawner.format_diff"title="Link to this definition">¶</a></dt>
<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.
<spanclass="sig-prename descclassname"><spanclass="pre">evennia.prototypes.spawner.</span></span><spanclass="sig-name descname"><spanclass="pre">batch_create_object</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o"><spanclass="pre">*</span></span><spanclass="n"><spanclass="pre">objparams</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/prototypes/spawner.html#batch_create_object"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#evennia.prototypes.spawner.batch_create_object"title="Link to this definition">¶</a></dt>
<ddclass="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><ulclass="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><dlclass="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><dlclass="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><dlclass="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><dlclass="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><dlclass="simple">
<dt><strong>execs</strong> (list): Code strings to execute together with the creation</dt><dd><dlclass="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
<spanclass="sig-prename descclassname"><spanclass="pre">evennia.prototypes.spawner.</span></span><spanclass="sig-name descname"><spanclass="pre">spawn</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o"><spanclass="pre">*</span></span><spanclass="n"><spanclass="pre">prototypes</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">caller</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="o"><spanclass="pre">**</span></span><spanclass="n"><spanclass="pre">kwargs</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/prototypes/spawner.html#spawn"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#evennia.prototypes.spawner.spawn"title="Link to this definition">¶</a></dt>
<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>
<ddclass="field-odd"><p><p><em>object (Object, dict or list)</em>–</p>
<dlclass="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>
