<p>See the <aclass="reference internal"href="../api/evennia.contrib.game_systems.crafting.example_recipes.html#evennia-contrib-game-systems-crafting-example-recipes"><spanclass="std std-ref">sword example</span></a> for an example
of how to design a recipe tree for crafting a sword from base elements.</p>
<p>Here, <codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> is the one doing the crafting and <codeclass="docutils literal notranslate"><spanclass="pre">*inputs</span></code> is any combination of
consumables and/or tool Objects. The system will identify which is which by the
<aclass="reference internal"href="../Components/Tags.html"><spanclass="doc std std-doc">Tags</span></a> on them (see below) The <codeclass="docutils literal notranslate"><spanclass="pre">result</span></code> is always a list.</p>
<p>To use crafting you need recipes. Add a new variable to
<p>All top-level classes in these modules (whose name does not start with <codeclass="docutils literal notranslate"><spanclass="pre">_</span></code>) will
be parsed by Evennia as recipes to make available to the crafting system. Using
the above example, create <codeclass="docutils literal notranslate"><spanclass="pre">mygame/world/recipes.py</span></code> and add your recipies in
there:</p>
<p>A quick example (read on for more details):</p>
<spanclass="sd"> Bread is good for making sandwitches!</span>
<spanclass="sd">"""</span>
<spanclass="n">name</span><spanclass="o">=</span><spanclass="s2">"bread"</span><spanclass="c1"># used to identify this recipe in 'craft' command</span>
<spanclass="p">{</span><spanclass="s2">"key"</span><spanclass="p">:</span><spanclass="s2">"Loaf of Bread"</span><spanclass="p">,</span>
<spanclass="s2">"desc"</span><spanclass="p">:</span><spanclass="s2">"A nice load of bread."</span><spanclass="p">,</span>
<spanclass="s2">"typeclass"</span><spanclass="p">:</span><spanclass="s2">"typeclasses.objects.Food"</span><spanclass="p">,</span><spanclass="c1"># assuming this exists</span>
<spanclass="s2">"tags"</span><spanclass="p">:</span><spanclass="p">[(</span><spanclass="s2">"bread"</span><spanclass="p">,</span><spanclass="s2">"crafting_material"</span><spanclass="p">)]</span><spanclass="c1"># this makes it usable in other recipes ...</span>
<codeclass="docutils literal notranslate"><spanclass="pre">evennia.contrib.game_systems.crafting.CraftingRecipe</span></code>. This class implements the
most common form of crafting - that using in-game objects. Each recipe is a
separate class which gets initialized with the consumables/tools you provide.</p>
<p>For the <codeclass="docutils literal notranslate"><spanclass="pre">craft</span></code> command to find your custom recipes, you need to tell Evennia
where they are. Add a new line to your <codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/conf/settings.py</span></code> file,
with a list to any new modules with recipe classes.</p>
<spanclass="n">name</span><spanclass="o">=</span><spanclass="s2">"wooden puppet"</span><spanclass="c1"># name to refer to this recipe as</span>
<spanclass="s2">"desc"</span><spanclass="p">:</span><spanclass="s2">"A small carved doll"</span><spanclass="p">}</span>
<spanclass="p">]</span>
</pre></div>
</div>
<p>This specifies which tags to look for in the inputs. It defines a
<aclass="reference internal"href="../Components/Prototypes.html"><spanclass="doc std std-doc">Prototype</span></a> for the recipe to use to spawn the
result on the fly (a recipe could spawn more than one result if needed).
Instead of specifying the full prototype-dict, you could also just provide a
list of <codeclass="docutils literal notranslate"><spanclass="pre">prototype_key</span></code>s to existing prototypes you have.</p>
<p>After reloading the server, this recipe would now be available to use. To try it
we should create materials and tools to insert into the recipe.</p>
<p>The recipe analyzes inputs, looking for <aclass="reference internal"href="../Components/Tags.html"><spanclass="doc std std-doc">Tags</span></a> with
specific tag-categories. The tag-category used can be set per-recipe using the
(<codeclass="docutils literal notranslate"><spanclass="pre">.consumable_tag_category</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">.tool_tag_category</span></code> respectively). The defaults
are <codeclass="docutils literal notranslate"><spanclass="pre">crafting_material</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">crafting_tool</span></code>. For
the puppet we need one object with the <codeclass="docutils literal notranslate"><spanclass="pre">wood</span></code> tag and another with the <codeclass="docutils literal notranslate"><spanclass="pre">knife</span></code>
<spanclass="n">wood</span><spanclass="o">=</span><spanclass="n">create_object</span><spanclass="p">(</span><spanclass="n">key</span><spanclass="o">=</span><spanclass="s2">"Piece of wood"</span><spanclass="p">,</span><spanclass="n">tags</span><spanclass="p">[(</span><spanclass="s2">"wood"</span><spanclass="p">,</span><spanclass="s2">"crafting_material"</span><spanclass="p">)])</span>
</pre></div>
</div>
<p>Note that the objects can have any name, all that matters is the
tag/tag-category. This means if a “bayonet” also had the “knife” crafting tag,
it could also be used to carve a puppet. This is also potentially interesting
for use in puzzles and to allow users to experiment and find alternatives to
know ingredients.</p>
<p>By the way, there is also a simple shortcut for doing this:</p>
<p>In the call to <codeclass="docutils literal notranslate"><spanclass="pre">craft</span></code>, the order of <codeclass="docutils literal notranslate"><spanclass="pre">knife</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">wood</span></code> doesn’t matter - the
recipe will sort out which is which based on their tags.</p>
</section>
<sectionid="deeper-customization-of-recipes">
<h2>Deeper customization of recipes<aclass="headerlink"href="#deeper-customization-of-recipes"title="Permalink to this headline">¶</a></h2>
<p>For customizing recipes further, it helps to understand how to use the
<p>This is useful for testing and allows you to use the class directly without
adding it to a module in <codeclass="docutils literal notranslate"><spanclass="pre">settings.CRAFTING_RECIPE_MODULES</span></code>.</p>
<p>Even without modifying more than the class properties, there are a lot of
options to set on the <codeclass="docutils literal notranslate"><spanclass="pre">CraftingRecipe</span></code> class. Easiest is to refer to the
<aclass="reference internal"href="../api/evennia.contrib.game_systems.crafting.crafting.html#evennia.contrib.game_systems.crafting.crafting.CraftingRecipe"title="evennia.contrib.game_systems.crafting.crafting.CraftingRecipe"><spanclass="xref myst py py-class">CraftingRecipe api
documentation</span></a>. For example,
you can customize the validation-error messages, decide if the ingredients have
to be exactly right, if a failure still consumes the ingredients or not, and
much more.</p>
<p>For even more control you can override hooks in your own class:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">pre_craft</span></code> - this should handle input validation and store its data in <codeclass="docutils literal notranslate"><spanclass="pre">.validated_consumables</span></code> and
<codeclass="docutils literal notranslate"><spanclass="pre">validated_tools</span></code> respectively. On error, this reports the error to the crafter and raises the
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">craft</span></code> - this will only be called if <codeclass="docutils literal notranslate"><spanclass="pre">pre_craft</span></code> finished without an exception. This should
return the result of the crafting, by spawnging the prototypes. Or the empty list if crafting
fails for some reason. This is the place to add skill-checks or random chance if you need it
for your game.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">post_craft</span></code> - this receives the result from <codeclass="docutils literal notranslate"><spanclass="pre">craft</span></code> and handles error messages and also deletes
any consumables as needed. It may also modify the result before returning it.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code> - this is a wrapper for <codeclass="docutils literal notranslate"><spanclass="pre">self.crafter.msg</span></code> and should be used to send messages to the
crafter. Centralizing this means you can also easily modify the sending style in one place later.</p></li>
</ul>
<p>The class constructor (and the <codeclass="docutils literal notranslate"><spanclass="pre">craft</span></code> access function) takes optional <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code>. These are passed
into each crafting hook. These are unused by default but could be used to customize things per-call.</p>
<sectionid="skilled-crafters">
<h3>Skilled crafters<aclass="headerlink"href="#skilled-crafters"title="Permalink to this headline">¶</a></h3>
<p>What the crafting system does not have out of the box is a ‘skill’ system - the
notion of being able to fail the craft if you are not skilled enough. Just how
skills work is game-dependent, so to add this you need to make your own recipe
parent class and have your recipes inherit from this.</p>
<spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"You are not good enough to craft this. Better luck next time!"</span><spanclass="p">)</span>
<p>In this example we introduce a <codeclass="docutils literal notranslate"><spanclass="pre">.difficulty</span></code> for the recipe and makes a ‘dice roll’ to see
if we succed. We would of course make this a lot more immersive and detailed in a full game. In
principle you could customize each recipe just the way you want it, but you could also inherit from
a central parent like this to cut down on work.</p>
<p>The <aclass="reference internal"href="../api/evennia.contrib.game_systems.crafting.example_recipes.html#evennia-contrib-game-systems-crafting-example-recipes"><spanclass="std std-ref">sword recipe example module</span></a> also shows an example
of a random skill-check being implemented in a parent and then inherited for multiple use.</p>
</section>
</section>
<sectionid="even-more-customization">
<h2>Even more customization<aclass="headerlink"href="#even-more-customization"title="Permalink to this headline">¶</a></h2>
<p>If you want to build something even more custom (maybe using different input types of validation logic)
you could also look at the <codeclass="docutils literal notranslate"><spanclass="pre">CraftingRecipe</span></code> parent class <codeclass="docutils literal notranslate"><spanclass="pre">CraftingRecipeBase</span></code>.
It implements just the minimum needed to be a recipe and for big changes you may be better off starting
from this rather than the more opinionated <codeclass="docutils literal notranslate"><spanclass="pre">CraftingRecipe</span></code>.</p>
<hrclass="docutils"/>
<p><small>This document page is generated from <codeclass="docutils literal notranslate"><spanclass="pre">evennia/contrib/game_systems/crafting/README.md</span></code>. Changes to this
file will be overwritten, so edit that file rather than this one.</small></p>
