Add documentation for new crafting contrib

docs/source/Components/Components-Overview.md

@@ -15,7 +15,7 @@ than, the doc-strings of each component in the [API](../Evennia-API).
 - [Attributes](./Attributes)
 - [Nicks](./Nicks)
 - [Tags](./Tags)
-- [Spawner and prototypes](./Spawner-and-Prototypes)
+- [Spawner and prototypes](./Prototypes)
 - [Help entries](./Help-System)
 
 ## Commands 

docs/source/Components/Objects.md

@@ -53,7 +53,7 @@ like [Scripts](./Scripts)).
 This particular Rose class doesn't really do much, all it does it make sure the attribute
 `desc`(which is what the `look` command looks for) is pre-set, which is pretty pointless since you
 will usually want to change this at build time (using the `@desc` command or using the
-[Spawner](./Spawner-and-Prototypes)). The `Object` typeclass offers many more hooks that is available
+[Spawner](./Prototypes)). The `Object` typeclass offers many more hooks that is available
 to use though - see next section.
 
 ## Properties and functions on Objects

docs/source/Components/Prototypes.md

@@ -119,7 +119,7 @@ Deprecated as of Evennia 0.8:
  - `ndb_<name>` - sets the value of a non-persistent attribute (`"ndb_"` is stripped from the name).
    This is simply not useful in a prototype and is deprecated.
  - `exec` - This accepts a code snippet or a list of code snippets to run. This should not be used -
-   use callables or [$protfuncs](./Spawner-and-Prototypes#protfuncs) instead (see below).
+   use callables or [$protfuncs](./Prototypes#protfuncs) instead (see below).
 
 ### Prototype values
 

docs/source/Contribs/Contrib-Overview.md

@@ -3,20 +3,52 @@
 The [evennia/contrib/](api:evennia.contrib) folder holds Game-specific tools, systems and utilities created by the community. This gathers 
 longer-form documentation associated with particular contribs. 
 
+## Crafting
+A full, extendable crafting system.
+
+- [Crafting overview](./Crafting)
+- [Crafting API documentation](api:evennia.contrib.crafting.crafting)
+- [Example of a sword crafting tree](api:evennia.contrib.crafting.example_recipes)
+
 ## In-Game-Python
 
+Allow Builders to add Python-scripted events to their objects (OBS-not for untrusted users!)
+
 - [A voice-operated elevator using events](./A-voice-operated-elevator-using-events)
 - [Dialogues using events](./Dialogues-in-events)
 
 ## Maps
 
+Solutions for generating and displaying maps in-game.
+
 - [Dynamic in-game map](./Dynamic-In-Game-Map)
 - [Static in-game map](./Static-In-Game-Map)
 
 ## The tutorial-world
 
+The Evennia single-player sole quest. Made to be analyzed to learn.
+
 - [The tutorial world introduction](../Howto/Starting/Part1/Tutorial-World-Introduction)
 
 ## Menu-builder
 
+A tool for building using an in-game menu instead of the normal build commands. Meant to 
+be expanded for the needs of your game.
+
 - [Building Menus](./Building-menus)
+
+
+```toctree::
+    :hidden:
+
+    ./Crafting
+    ../api/evennia.contrib.crafting.crafting 
+    ../api/evennia.contrib.crafting.example_recipes
+    ./A-voice-operated-elevator-using-events
+    ./Dialogues-in-events
+    ./Dynamic-In-Game-Map
+    ./Static-In-Game-Map
+    ../Howto/Starting/Part1/Tutorial-World-Introduction
+    ./Building-menus
+
+```

docs/source/Contribs/Crafting.md

@@ -0,0 +1,214 @@
+# Crafting system contrib 
+
+_Contrib by Griatch 2020_
+```versionadded:: 1.0
+```
+
+This contrib implements a full Crafting system that can be expanded and modified to fit your game. 
+
+- See the [evennia/contrib/crafting/crafting.py API](api:evennia.contrib.crafting.crafting) for installation 
+  instructrions.
+- See the [sword example](api:evennia.contrib.crafting.example_recipes) for an example of how to design 
+  a crafting tree for crafting a sword from base elements.
+
+From in-game it uses the new `craft` command: 
+
+```bash
+> craft bread from flour, eggs, salt, water, yeast using oven, roller
+> craft bandage from cloth using scissors
+```
+
+The syntax is `craft <recipe> [from <ingredient>,...][ using <tool>,...]`. 
+
+The above example uses the `bread` *recipe* and requires `flour`, `eggs`, `salt`, `water` and `yeast` objects 
+to be in your inventory. These will be consumed as part of crafting (baking) the bread. 
+
+The `oven` and `roller` are "tools" that can be either in your inventory or in your current location (you are not carrying an oven 
+around with you after all). Tools are *not* consumed in the crafting. If the added ingredients/tools matches 
+the requirements of the recipe, a new `bread` object will appear in the crafter's inventory.
+
+If you wanted, you could also picture recipes without any consumables: 
+
+```
+> craft fireball using wand, spellbook
+```
+
+With a little creativity, the 'recipe' concept could be adopted to all sorts of things, like puzzles or 
+magic systems.
+
+In code, you can craft using the `evennia.contrib.crafting.crafting.craft` function:
+
+```python
+from evennia.contrib.crafting.crafting import craft
+
+result = craft(caller, *inputs)
+
+```
+Here, `caller` is the one doing the crafting and `*inputs` is any combination of consumables and/or tool
+Objects. The system will identify which is which by the [Tags](../Components/Tags) on them (see below)
+The `result` is always a list. 
+
+## Adding new recipes
+
+A *recipe* is a class inheriting from `evennia.contrib.crafting.crafting.CraftingRecipe`. 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. 
+
+For the `craft` command to find your custom recipes, you need to tell Evennia where they are. Add a new 
+line to your `mygame/server/conf/settings.py` file, with a list to any new modules with recipe classes.
+
+```python
+CRAFT_RECIPE_MODULES = ["world.myrecipes"]
+```
+
+(You need to reload after adding this). All global-level classes in these modules (whose names don't start 
+with underscore) are considered by the system as viable recipes.
+
+Here we assume you created `mygame/world/myrecipes.py` to match the above example setting:
+
+```python
+# in mygame/world/myrecipes.py
+
+from evennia.contrib.crafting.crafting import CraftingRecipe
+
+class WoodenPuppetRecipe(CraftingRecipe):
+    """A puppet""""
+    name = "wooden puppet"  # name to refer to this recipe as
+    tool_tags = ["knife"]
+    consumable_tags = ["wood"]
+    output_prototypes = [
+        {"key": "A carved wooden doll",
+         "typeclass": "typeclasses.objects.decorations.Toys",
+         "desc": "A small carved doll",
+    ]   
+
+```
+
+This specifies what tags to look for in the inputs and a [Prototype](../Components/Prototypes) 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 `prototype_key`s to existing 
+prototypes you have.
+
+After reloading the server, this recipe would now be available to use. To try it we should 
+create materials and tools the recipe understands. 
+
+The recipe looks only for the [Tag](../Components/Tags) of the ingredients. The tag-category used 
+can be set per-recipe using the (`.consumable_tag_category` and 
+`.tool_tag_category` respectively). The defaults are `crafting_material` and `crafting_tool`. For 
+the puppet we need one object with the `wood` tag and another with the `knife` tag: 
+
+```python
+from evennia import create_object
+
+knife = create_object(key="Hobby knife", tags=[("knife", "crafting_tool")])
+wood = create_object(key="Piece of wood", tags[("wood", "crafting_material")])
+```
+
+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.
+
+Assuming these objects were put in our inventory, we could now craft using the in-game command: 
+
+```bash
+> craft wooden puppet from wood using hobby knife
+```
+In code we would do 
+
+```python
+from evennia.contrub.crafting.crafting import craft
+puppet = craft(crafter, "wooden puppet", knife, wood)
+
+```
+In the call to `craft`, the order of `knife` and `wood` doesn't matter - the recipe will sort out which
+is which based on their tags. 
+
+## Deeper customization of recipes
+
+To understand how to customize recipes further, it helps to understand how they are used directly: 
+
+```python
+class MyRecipe(CraftingRecipe):
+    ...
+
+# convenient helper to get dummy objects with the right tags
+tools, consumables = MyRecipe.seed()
+
+recipe = MyRecipe(crafter, *(tools + consumables))
+result = recipe.craft()
+
+```
+This is useful for testing and allows you to use the class directly without adding it to a module 
+in `settings.CRAFTING_RECIPE_MODULES`. The `seed` class method is useful e.g. for making unit tests.
+
+Even without modifying more than the class properties, there are a lot of options to set on 
+the `CraftingRecipe` class. Easiest is to refer to the 
+[CraftingRecipe api documentation](evennia.contrib.crafting.crafting.html#evennia.contrib.crafting.crafting.CraftingRecipe).
+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.
+
+For even more control you can override hooks in your own class:
+
+- `pre_craft` - this should handle input validation and store its data in `.validated_consumables` and 
+  `validated_tools` respectively. On error, this reports the error to the crafter and raises the
+  `CraftingValidationError`.
+- `do_craft` - this will only be called if `pre_craft` 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. 
+- `post_craft` - this receives the result from `do_craft` and handles error messages and also deletes
+  any consumables as needed. It may also modify the result before returning it.
+- `msg` - this is a wrapper for `self.crafter.msg` 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.
+
+The class constructor (and the `craft` access function) takes optional `**kwargs`. These are passed 
+into each crafting hook. These are unused by default but could be used to customize things per-call.
+
+### Skilled crafters
+
+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.
+
+
+```python
+from random import randint
+from evennia.contrib.crafting.crafting import CraftingRecipe
+
+class SkillRecipe(CraftingRecipe):
+   """A recipe that considers skill"""
+
+    difficulty = 20
+
+    def do_craft(self, **kwargs):
+        """The input is ok. Determine if crafting succeeds"""
+
+        # this is set at initialization
+        crafter = self.crafte
+
+        # let's assume the skill is stored directly on the crafter
+        # - the skill is 0..100.
+        crafting_skill = crafter.db.skill_crafting
+        # roll for success:
+        if randint(1, 100) <= (crafting_skill - self.difficulty):
+            # all is good, craft away
+            return super().do_craft()
+        else:
+            self.msg("You are not good enough to craft this. Better luck next time!")
+            return []
+```
+In this example we introduce a `.difficulty` 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. 
+
+The [sword recipe example module](api:evennia.contrib.crafting.example_recipes) also shows an example
+of a random skill-check being implemented in a parent and then inherited for multiple use.
+
+## Even more customization
+
+The base class `evennia.contrib.crafting.crafting.CraftingRecipeBase` implements just the minimum 
+needed to be a recipe. It doesn't know about Objects or tags. If you want to adopt the crafting system
+for something entirely different (maybe using different input or validation logic), starting from this 
+may be cleaner than overriding things in the more opinionated `CraftingRecipe`.

docs/source/Evennia-API.md

@@ -70,7 +70,7 @@ The flat API is defined in `__init__.py` [viewable here](github:evennia/__init__
 - [evennia.gametime](api:evennia.utils.gametime) - server run- and game time ([docs](Components/Coding-Utils#gametime))
 - [evennia.logger](api:evennia.utils.logger) - logging tools
 - [evennia.ansi](api:evennia.utils.ansi) - ansi coloring tools
-- [evennia.spawn](api:evennia.prototypes.spawner#evennia.prototypes.spawner.Spawn) - spawn/prototype system ([docs](Components/Spawner-and-Prototypes))
+- [evennia.spawn](api:evennia.prototypes.spawner#evennia.prototypes.spawner.Spawn) - spawn/prototype system ([docs](Components/Prototypes))
 - [evennia.lockfuncs](api:evennia.locks.lockfuncs) - default lock functions for access control ([docs](Components/Locks))
 - [evennia.EvMenu](api:evennia.utils.evmenu#evennia.utils.evmenu.EvMenu) - menu system ([docs](Components/EvMenu))
 - [evennia.EvTable](api:evennia.utils.evtable#evennia.utils.evtable.EvTable) - text table creater

docs/source/Howto/Starting/Part1/Evennia-Library-Overview.md

@@ -62,7 +62,7 @@ from here to `mygame/server/settings.py` file.
    - `locale/` - Language files ([i18n](../../../Concepts/Internationalization)).
    - [`locks/`](../../../Components/Locks) - Lock system for restricting access to in-game entities.
    - [`objects/`](../../../Components/Objects) - In-game entities (all types of items and Characters).
-   - [`prototypes/`](../../../Components/Spawner-and-Prototypes) - Object Prototype/spawning system and OLC menu
+   - [`prototypes/`](../../../Components/Prototypes) - Object Prototype/spawning system and OLC menu
    - [`accounts/`](../../../Components/Accounts) - Out-of-game Session-controlled entities (accounts, bots etc)
    - [`scripts/`](../../../Components/Scripts) - Out-of-game entities equivalence to Objects, also with timer support. 
    - [`server/`](../../../Components/Portal-And-Server) - Core server code and Session handling. 

docs/source/Howto/Starting/Part1/Gamedir-Overview.md

@@ -201,7 +201,7 @@ people change and re-structure this in various ways to better fit their ideas.
 - [batch_cmds.ev](github:evennia/game_template/world/batch_cmds.ev) - This is an `.ev` file, which is essentially
     just a list of Evennia commands to execute in sequence. This one is empty and ready to expand on. The 
     [Tutorial World](./Tutorial-World-Introduction) was built with such a batch-file.
-- [prototypes.py](github:evennia/game_template/world/prototypes.py) - A [prototype](../../../Components/Spawner-and-Prototypes) is a way
+- [prototypes.py](github:evennia/game_template/world/prototypes.py) - A [prototype](../../../Components/Prototypes) is a way
     to easily vary objects without changing their base typeclass. For example, one could use prototypes to 
     tell that Two goblins, while both of the class 'Goblin' (so they follow the same code logic), should have different 
     equipment, stats and looks.

docs/source/api/evennia.contrib.crafting.crafting.rst

@@ -0,0 +1,7 @@
+evennia.contrib.crafting.crafting 
+========================================
+
+.. automodule:: evennia.contrib.crafting.crafting
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.crafting.example_recipes.rst

@@ -0,0 +1,7 @@
+evennia.contrib.crafting.example\_recipes 
+================================================
+
+.. automodule:: evennia.contrib.crafting.example_recipes
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.crafting.rst

@@ -0,0 +1,16 @@
+evennia.contrib.crafting 
+================================
+
+.. automodule:: evennia.contrib.crafting
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+
+.. toctree::
+   :maxdepth: 6
+
+   evennia.contrib.crafting.crafting
+   evennia.contrib.crafting.example_recipes
+   evennia.contrib.crafting.tests

docs/source/api/evennia.contrib.crafting.tests.rst

@@ -0,0 +1,7 @@
+evennia.contrib.crafting.tests 
+=====================================
+
+.. automodule:: evennia.contrib.crafting.tests
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.evscaperoom.commands.rst

@@ -0,0 +1,7 @@
+evennia.contrib.evscaperoom.commands 
+===========================================
+
+.. automodule:: evennia.contrib.evscaperoom.commands
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.evscaperoom.menu.rst

@@ -0,0 +1,7 @@
+evennia.contrib.evscaperoom.menu 
+=======================================
+
+.. automodule:: evennia.contrib.evscaperoom.menu
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.evscaperoom.objects.rst

@@ -0,0 +1,7 @@
+evennia.contrib.evscaperoom.objects 
+==========================================
+
+.. automodule:: evennia.contrib.evscaperoom.objects
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.evscaperoom.room.rst

@@ -0,0 +1,7 @@
+evennia.contrib.evscaperoom.room 
+=======================================
+
+.. automodule:: evennia.contrib.evscaperoom.room
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.evscaperoom.rst

@@ -0,0 +1,21 @@
+evennia.contrib.evscaperoom 
+===================================
+
+.. automodule:: evennia.contrib.evscaperoom
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+
+.. toctree::
+   :maxdepth: 6
+
+   evennia.contrib.evscaperoom.commands
+   evennia.contrib.evscaperoom.menu
+   evennia.contrib.evscaperoom.objects
+   evennia.contrib.evscaperoom.room
+   evennia.contrib.evscaperoom.scripts
+   evennia.contrib.evscaperoom.state
+   evennia.contrib.evscaperoom.tests
+   evennia.contrib.evscaperoom.utils

docs/source/api/evennia.contrib.evscaperoom.scripts.rst

@@ -0,0 +1,7 @@
+evennia.contrib.evscaperoom.scripts 
+==========================================
+
+.. automodule:: evennia.contrib.evscaperoom.scripts
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.evscaperoom.state.rst

@@ -0,0 +1,7 @@
+evennia.contrib.evscaperoom.state 
+========================================
+
+.. automodule:: evennia.contrib.evscaperoom.state
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.evscaperoom.tests.rst

@@ -0,0 +1,7 @@
+evennia.contrib.evscaperoom.tests 
+========================================
+
+.. automodule:: evennia.contrib.evscaperoom.tests
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.evscaperoom.utils.rst

@@ -0,0 +1,7 @@
+evennia.contrib.evscaperoom.utils 
+========================================
+
+.. automodule:: evennia.contrib.evscaperoom.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/evennia.contrib.rst

@@ -45,6 +45,8 @@ evennia.contrib
    :maxdepth: 6
 
    evennia.contrib.awsstorage
+   evennia.contrib.crafting
+   evennia.contrib.evscaperoom
    evennia.contrib.ingame_python
    evennia.contrib.security
    evennia.contrib.turnbattle

docs/source/toc.md

@@ -37,12 +37,12 @@
 - [Components/Objects](Components/Objects)
 - [Components/Outputfuncs](Components/Outputfuncs)
 - [Components/Portal And Server](Components/Portal-And-Server)
+- [Components/Prototypes](Components/Prototypes)
 - [Components/Scripts](Components/Scripts)
 - [Components/Server](Components/Server)
 - [Components/Server Conf](Components/Server-Conf)
 - [Components/Sessions](Components/Sessions)
 - [Components/Signals](Components/Signals)
-- [Components/Spawner and Prototypes](Components/Spawner-and-Prototypes)
 - [Components/Tags](Components/Tags)
 - [Components/TickerHandler](Components/TickerHandler)
 - [Components/Typeclasses](Components/Typeclasses)
@@ -70,6 +70,7 @@
 - [Contribs/Arxcode installing help](Contribs/Arxcode-installing-help)
 - [Contribs/Building menus](Contribs/Building-menus)
 - [Contribs/Contrib Overview](Contribs/Contrib-Overview)
+- [Contribs/Crafting](Contribs/Crafting)
 - [Contribs/Dialogues in events](Contribs/Dialogues-in-events)
 - [Contribs/Dynamic In Game Map](Contribs/Dynamic-In-Game-Map)
 - [Contribs/Static In Game Map](Contribs/Static-In-Game-Map)