<p>The <em>spawner</em> is a system for defining and creating individual objects from a base template called a <em>prototype</em>. It is only designed for use with in-game <aclass="reference internal"href="Objects.html"><spanclass="std std-doc">Objects</span></a>, not any other type of entity.</p>
<p>The normal way to create a custom object in Evennia is to make a <aclass="reference internal"href="Typeclasses.html"><spanclass="std std-doc">Typeclass</span></a>. If you haven’t read up on Typeclasses yet, think of them as normal Python classes that save to the database behind the scenes. Say you wanted to create a “Goblin” enemy. A common way to do this would be to first create a <codeclass="docutils literal notranslate"><spanclass="pre">Mobile</span></code> typeclass that holds everything common to mobiles in the game, like generic AI, combat code and various movement methods. A <codeclass="docutils literal notranslate"><spanclass="pre">Goblin</span></code> subclass is then made to inherit from <codeclass="docutils literal notranslate"><spanclass="pre">Mobile</span></code>. The <codeclass="docutils literal notranslate"><spanclass="pre">Goblin</span></code> class adds stuff unique to goblins, like group-based AI (because goblins are smarter in a group), the ability to panic, dig for gold etc.</p>
<p>But now it’s time to actually start to create some goblins and put them in the world. What if we wanted those goblins to not all look the same? Maybe we want grey-skinned and green-skinned goblins or some goblins that can cast spells or which wield different weapons? We <em>could</em> make subclasses of <codeclass="docutils literal notranslate"><spanclass="pre">Goblin</span></code>, like <codeclass="docutils literal notranslate"><spanclass="pre">GreySkinnedGoblin</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">GoblinWieldingClub</span></code>. But that seems a bit excessive (and a lot of Python code for every little thing). Using classes can also become impractical when wanting to combine them - what if we want a grey-skinned goblin shaman wielding a spear - setting up a web of classes inheriting each other with multiple inheritance can be tricky.</p>
<p>This is what the <em>prototype</em> is for. It is a Python dictionary that describes these per-instance changes to an object. The prototype also has the advantage of allowing an in-game builder to customize an object without access to the Python backend. Evennia also allows for saving and searching prototypes so other builders can find and use (and tweak) them later. Having a library of interesting prototypes is a good reasource for builders. The OLC system allows for creating, saving, loading and manipulating prototypes using a menu system.</p>
<p>The <em>spawner</em> takes a prototype and uses it to create (spawn) new, custom objects.</p>
<p>Enter the <codeclass="docutils literal notranslate"><spanclass="pre">olc</span></code> command or <codeclass="docutils literal notranslate"><spanclass="pre">spawn/olc</span></code> to enter the prototype wizard. This is a menu system for creating, loading, saving and manipulating prototypes. It’s intended to be used by in-game builders and will give a better understanding of prototypes in general. Use <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> on each node of the menu for more information. Below are further details about how prototypes work and how they are used.</p>
<p>The prototype dictionary can either be created for you by the OLC (see above), be written manually in a Python module (and then referenced by the <codeclass="docutils literal notranslate"><spanclass="pre">spawn</span></code> command/OLC), or created on-the-fly and manually loaded into the spawner function or <codeclass="docutils literal notranslate"><spanclass="pre">spawn</span></code> command.</p>
<p>The dictionary defines all possible database-properties of an Object. It has a fixed set of allowed keys. When preparing to store the prototype in the database (or when using the OLC), some of these keys are mandatory. When just passing a one-time prototype-dict to the spawner the system is more lenient and will use defaults for keys not explicitly provided.</p>
<p>In dictionary form, a prototype can look something like this:</p>
<div><p>Note that the prototype dict as given on the command line must be a valid Python structure - so you need to put quotes around strings etc. For security reasons, a dict inserted from-in game cannot have any other advanced Python functionality, such as executable code, <codeclass="docutils literal notranslate"><spanclass="pre">lambda</span></code> etc. If builders are supposed to be able to use such features, you need to offer them through [$protfuncs](Spawner-and- Prototypes#protfuncs), embedded runnable functions that you have full control to check and vet before running.</p>
<p>All keys starting with <codeclass="docutils literal notranslate"><spanclass="pre">prototype_</span></code> are for book keeping.</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">prototype_key</span></code> - the ‘name’ of the prototype, used for referencing the prototype
when spawning and inheritance. If defining a prototype in a module and this
not set, it will be auto-set to the name of the prototype’s variable in the module.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">prototype_parent</span></code> - If given, this should be the <codeclass="docutils literal notranslate"><spanclass="pre">prototype_key</span></code> of another prototype stored in the system or available in a module. This makes this prototype <em>inherit</em> the keys from the
parent and only override what is needed. Give a tuple <codeclass="docutils literal notranslate"><spanclass="pre">(parent1,</span><spanclass="pre">parent2,</span><spanclass="pre">...)</span></code> for multiple left-right inheritance. If this is not given, a <codeclass="docutils literal notranslate"><spanclass="pre">typeclass</span></code> should usually be defined (below).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">prototype_desc</span></code> - this is optional and used when listing the prototype in in-game listings.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">protototype_tags</span></code> - this is optional and allows for tagging the prototype in order to find it
easier later.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">prototype_locks</span></code> - two lock types are supported: <codeclass="docutils literal notranslate"><spanclass="pre">edit</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">spawn</span></code>. The first lock restricts the copying and editing of the prototype when loaded through the OLC. The second determines who may use the prototype to create new objects.</p></li>
</ul>
<p>The remaining keys determine actual aspects of the objects to spawn from this prototype:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> - the main object identifier. Defaults to “Spawned Object <em>X</em>”, where <em>X</em> is a random integer.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">typeclass</span></code> - A full python-path (from your gamedir) to the typeclass you want to use. If not set, the <codeclass="docutils literal notranslate"><spanclass="pre">prototype_parent</span></code> should be defined, with <codeclass="docutils literal notranslate"><spanclass="pre">typeclass</span></code> defined somewhere in the parent chain. When creating a one-time prototype dict just for spawning, one could omit this - <codeclass="docutils literal notranslate"><spanclass="pre">settings.BASE_OBJECT_TYPECLASS</span></code> will be used instead.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">location</span></code> - this should be a <codeclass="docutils literal notranslate"><spanclass="pre">#dbref</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">home</span></code> - a valid <codeclass="docutils literal notranslate"><spanclass="pre">#dbref</span></code>. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">location</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">settings.DEFAULT_HOME</span></code> if location does not exist.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">destination</span></code> - a valid <codeclass="docutils literal notranslate"><spanclass="pre">#dbref</span></code>. Only used by exits.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">permissions</span></code> - list of permission strings, like <codeclass="docutils literal notranslate"><spanclass="pre">["Accounts",</span><spanclass="pre">"may_use_red_door"]</span></code></p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">tags</span></code> - list <aclass="reference internal"href="Tags.html"><spanclass="std std-doc">Tags</span></a>. These are given as tuples <codeclass="docutils literal notranslate"><spanclass="pre">(tag,</span><spanclass="pre">category,</span><spanclass="pre">data)</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">attrs</span></code> - list of <aclass="reference internal"href="Attributes.html"><spanclass="std std-doc">Attributes</span></a>. These are given as tuples <codeclass="docutils literal notranslate"><spanclass="pre">(attrname,</span><spanclass="pre">value,</span><spanclass="pre">category,</span><spanclass="pre">lockstring)</span></code></p></li>
<li><p>Any other keywords are interpreted as non-category <aclass="reference internal"href="Attributes.html"><spanclass="std std-doc">Attributes</span></a> and their values. This is convenient for simple Attributes - use <codeclass="docutils literal notranslate"><spanclass="pre">attrs</span></code> for full control of Attributes.</p></li>
<li><p>A prototype can inherit by defining a <codeclass="docutils literal notranslate"><spanclass="pre">prototype_parent</span></code> pointing to the name (<codeclass="docutils literal notranslate"><spanclass="pre">prototype_key</span></code> of another prototype). If a list of <codeclass="docutils literal notranslate"><spanclass="pre">prototype_keys</span></code>, this will be stepped through from left to right, giving priority to the first in the list over those appearing later. That is, if your inheritance is <codeclass="docutils literal notranslate"><spanclass="pre">prototype_parent</span><spanclass="pre">=</span><spanclass="pre">('A',</span><spanclass="pre">'B,'</span><spanclass="pre">'C')</span></code>, and all parents contain colliding keys, then the one from <codeclass="docutils literal notranslate"><spanclass="pre">A</span></code> will apply.</p></li>
<li><p>The prototype keys that start with <codeclass="docutils literal notranslate"><spanclass="pre">prototype_*</span></code> are all unique to each prototype. They are <em>never</em> inherited from parent to child.</p></li>
<li><p>The prototype fields <codeclass="docutils literal notranslate"><spanclass="pre">'attr':</span><spanclass="pre">[(key,</span><spanclass="pre">value,</span><spanclass="pre">category,</span><spanclass="pre">lockstring),...]</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">'tags':</span><spanclass="pre">[(key,</span><spanclass="pre">category,</span><spanclass="pre">data),</span><spanclass="pre">...]</span></code> are inherited in a <em>complementary</em> fashion. That means that only colliding key+category matches will be replaced, not the entire list. Remember that the category <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> is also considered a valid category!</p></li>
<li><p>Adding an Attribute as a simple <codeclass="docutils literal notranslate"><spanclass="pre">key:value</span></code> will under the hood be translated into an Attribute tuple <codeclass="docutils literal notranslate"><spanclass="pre">(key,</span><spanclass="pre">value,</span><spanclass="pre">None,</span><spanclass="pre">'')</span></code> and may replace an Attribute in the parent if it the same key and a <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> category.</p></li>
<li><p>All other keys (<codeclass="docutils literal notranslate"><spanclass="pre">permissions</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">destination</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">aliases</span></code> etc) are completely <em>replaced</em> by the child’s value if given. For the parent’s value to be retained, the child must not define these keys at all.</p></li>
<p>By use of Python <codeclass="docutils literal notranslate"><spanclass="pre">lambda</span></code> one can wrap the callable so as to make immediate settings in the prototype:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="p">{</span><spanclass="s2">"key"</span><spanclass="p">:</span><spanclass="k">lambda</span><spanclass="p">:</span><spanclass="n">random</span><spanclass="o">.</span><spanclass="n">choice</span><spanclass="p">((</span><spanclass="s2">"Urfgar"</span><spanclass="p">,</span><spanclass="s2">"Rick the smelly"</span><spanclass="p">,</span><spanclass="s2">"Blargh the foul"</span><spanclass="p">,</span><spanclass="o">...</span><spanclass="p">)),</span><spanclass="o">...</span><spanclass="p">}</span>
<p>Finally, the value can be a <em>prototype function</em> (<em>Protfunc</em>). These look like simple function calls that you embed in strings and that has a <codeclass="docutils literal notranslate"><spanclass="pre">$</span></code> in front, like</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="p">{</span><spanclass="s2">"key"</span><spanclass="p">:</span><spanclass="s2">"$choice(Urfgar, Rick the smelly, Blargh the foul)"</span><spanclass="p">,</span>
<spanclass="s2">"attrs"</span><spanclass="p">:</span><spanclass="p">{</span><spanclass="s2">"desc"</span><spanclass="p">:</span><spanclass="s2">"This is a large $red(and very red) demon. "</span>
<spanclass="s2">"He has $randint(2,5) skulls in a chain around his neck."</span><spanclass="p">}</span>
</pre></div>
</div>
<blockquote>
<div><p>If you want to escape a protfunc and have it appear verbatim, use <codeclass="docutils literal notranslate"><spanclass="pre">$$funcname()</span></code>.</p>
<p>At spawn time, the place of the protfunc will be replaced with the result of that protfunc being called (this is always a string). A protfunc is a <aclass="reference internal"href="FuncParser.html"><spanclass="std std-doc">FuncParser function</span></a> run every time the prototype is used to spawn a new object. See the FuncParse for a lot more information.</p>
<p>Here is how a protfunc is defined (same as other funcparser functions).</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># this is a silly example, you can just color the text red with |r directly!</span>
<spanclass="k">raise</span><spanclass="ne">ValueError</span><spanclass="p">(</span><spanclass="s2">"Must have one argument, the text to color red!"</span><spanclass="p">)</span>
<div><p>Note that we must make sure to validate input and raise <codeclass="docutils literal notranslate"><spanclass="pre">ValueError</span></code> on failure.</p>
</div></blockquote>
<p>The parser will always include the following reserved <codeclass="docutils literal notranslate"><spanclass="pre">kwargs</span></code>:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">session</span></code> - the current <aclass="reference internal"href="../api/evennia.server.serversession.html#evennia-server-serversession"><spanclass="std std-ref">Session</span></a> performing the spawning.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">prototype</span></code> - The Prototype-dict this function is a part of. This is intended to be used <em>read-only</em>. Be careful to modify a mutable structure like this from inside the function - you can cause really hard-to-find bugs this way.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">current_key</span></code> - The current key of the <codeclass="docutils literal notranslate"><spanclass="pre">prototype</span></code> dict under which this protfunc is executed.</p></li>
</ul>
<p>To make this protfunc available to builders in-game, add it to a new module and add the path to that module to <codeclass="docutils literal notranslate"><spanclass="pre">settings.PROT_FUNC_MODULES</span></code>:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in mygame/server/conf/settings.py</span>
<p>All <em>global callables</em> in your added module will be considered a new protfunc. To avoid this (e.g. to have helper functions that are not protfuncs on their own), name your function something starting with <codeclass="docutils literal notranslate"><spanclass="pre">_</span></code>.</p>
<p>The default protfuncs available out of the box are defined in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/prototypes/profuncs.py</span></code>. To override the ones available, just add the same-named function in your own protfunc module.</p>
<td><p>Returns result of <aclass="reference external"href="https://docs.python.org/2/library/ast.html#ast.literal_eval">literal-eval</a> of code string. Only simple python expressions.</p></td>
<td><p>Like <codeclass="docutils literal notranslate"><spanclass="pre">$obj</span></code>, except always returns a list of zero, one or more results.</p></td>
<td><p>Returns argument if it is formed as a #dbref (e.g. #1234), otherwise error.</p></td>
</tr>
</tbody>
</table>
<p>For developers with access to Python, using protfuncs in prototypes is generally not useful. Passing real Python functions is a lot more powerful and flexible. Their main use is to allow in-game builders to do limited coding/scripting for their prototypes without giving them direct access to raw Python.</p>
<h2>Database prototypes<aclass="headerlink"href="#database-prototypes"title="Link to this heading">¶</a></h2>
<p>Stored as <aclass="reference internal"href="Scripts.html"><spanclass="std std-doc">Scripts</span></a> in the database. These are sometimes referred to as <em>database- prototypes</em> This is the only way for in-game builders to modify and add prototypes. They have the advantage of being easily modifiable and sharable between builders but you need to work with them using in-game tools.</p>
<p>These prototypes are defined as dictionaries assigned to global variables in one of the modules defined in <codeclass="docutils literal notranslate"><spanclass="pre">settings.PROTOTYPE_MODULES</span></code>. They can only be modified from outside the game so they are are necessarily “read-only” from in-game and cannot be modified (but copies of them could be made into database-prototypes). These were the only prototypes available before Evennia 0.8. Module based prototypes can be useful in order for developers to provide read-only “starting” or “base” prototypes to build from or if they just prefer to work offline in an external code editor.</p>
<p>By default <codeclass="docutils literal notranslate"><spanclass="pre">mygame/world/prototypes.py</span></code> is set up for you to add your own prototypes. <em>All global
dicts</em> in this module will be considered by Evennia to be a prototype. You could also tell Evennia
to look for prototypes in more modules if you want:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in mygame/server/conf.py</span>
<div><p>Note that in the example above, <codeclass="docutils literal notranslate"><spanclass="pre">"ORC_SHAMAN"</span></code> will become the <codeclass="docutils literal notranslate"><spanclass="pre">prototype_key</span></code> of this prototype. It’s the only case when <codeclass="docutils literal notranslate"><spanclass="pre">prototype_key</span></code> can be skipped in a prototype. However, if <codeclass="docutils literal notranslate"><spanclass="pre">prototype_key</span></code>was given explicitly, that would take precedence. This is a legacy behavior and it’s recommended > that you always add <codeclass="docutils literal notranslate"><spanclass="pre">prototype_key</span></code> to be consistent.</p>
<p>The spawner can be used from inside the game through the Builder-only <codeclass="docutils literal notranslate"><spanclass="pre">@spawn</span></code> command. Assuming the “goblin” typeclass is available to the system (either as a database-prototype or read from module), you can spawn a new goblin with</p>
<div><p>Note: The <codeclass="docutils literal notranslate"><spanclass="pre">spawn</span></code> command is more lenient about the prototype dictionary than shown here. So you can for example skip the <codeclass="docutils literal notranslate"><spanclass="pre">prototype_key</span></code> if you are just testing a throw-away prototype. A random hash will be used to please the validation. You could also skip <codeclass="docutils literal notranslate"><spanclass="pre">prototype_parent/typeclass</span></code> - then the typeclass given by <codeclass="docutils literal notranslate"><spanclass="pre">settings.BASE_OBJECT_TYPECLASS</span></code> will be used.</p>
<div><p>Hint: Same as when using <codeclass="docutils literal notranslate"><spanclass="pre">spawn</span></code>, when spawning from a one-time prototype dict like this, you can skip otherwise required keys, like <codeclass="docutils literal notranslate"><spanclass="pre">prototype_key</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">typeclass</span></code>/<codeclass="docutils literal notranslate"><spanclass="pre">prototype_parent</span></code>. Defaults will be used.</p>
</div></blockquote>
<p>Note that no <codeclass="docutils literal notranslate"><spanclass="pre">location</span></code> will be set automatically when using <codeclass="docutils literal notranslate"><spanclass="pre">evennia.prototypes.spawner.spawn()</span></code>, you have to specify <codeclass="docutils literal notranslate"><spanclass="pre">location</span></code> explicitly in the prototype dict. If the prototypes you supply are using <codeclass="docutils literal notranslate"><spanclass="pre">prototype_parent</span></code> keywords, the spawner will read prototypes from modules in <codeclass="docutils literal notranslate"><spanclass="pre">settings.PROTOTYPE_MODULES</span></code> as well as those saved to the database to determine the body of available parents. The <codeclass="docutils literal notranslate"><spanclass="pre">spawn</span></code> command takes many optional keywords, you can find its definition <aclass="reference external"href="https://www.evennia.com/docs/latest/api/evennia.prototypes.spawner.html#evennia.prototypes.spawner.spawn">in the api docs</a></p>
