====================
crafting and recipes
====================

the crafting system lets players combine materials to create new items. recipes
are defined in TOML files, loaded at startup, and executed via the ``craft``
command.

recipe structure
================

recipes live in ``content/recipes/`` as TOML files. each defines:

- ``name`` - unique identifier (lowercase, underscores)
- ``description`` - what you're making (shown in recipe listings)
- ``ingredients`` - list of thing template names (duplicates = need multiples)
- ``result`` - thing template name to spawn

example::

    name = "wooden_table"
    description = "Craft a sturdy table from planks and nails"
    ingredients = ["plank", "plank", "plank", "nail", "nail"]
    result = "table"

all ingredient and result names must match existing thing templates in the
``thing_templates`` registry.

loading
=======

``load_recipe(path)`` parses a single TOML file into a Recipe dataclass.
``load_recipes(dir)`` walks the directory and loads all ``.toml`` files.

the global ``recipes`` dict (keyed by name) is updated at server startup in
``server.py``. recipes are immutable after load.

crafting
========

``cmd_craft(player, args)`` executes the crafting flow:

1. parse recipe name from args (case-insensitive, prefix matching)
2. find matching recipe (error if ambiguous or not found)
3. count required ingredients via ``Counter()``
4. count available items in player inventory
5. check all ingredients present (list missing if not)
6. verify result template exists in ``thing_templates``
7. consume ingredients (remove from world)
8. spawn result via ``spawn_thing``, add to inventory
9. send success message

ingredient counting uses python's ``Counter`` to handle duplicates. "2x plank"
means the ingredients list contains ``"plank"`` twice.

browsing recipes
================

``cmd_recipes()`` shows available recipes:

- no args: lists all recipes with descriptions
- with args: shows detailed recipe for a specific name (prefix matching)

detail view shows ingredients with counts ("2x plank, 2x nail") and the result
item. ambiguous prefixes are detected and reported.

materials
=========

existing thing templates usable as materials:

- ``plank`` - wooden plank
- ``nail`` - iron nail
- ``table`` - wooden table
- ``chair`` - wooden chair

new materials require adding thing templates to ``things.py`` and
creating recipes that reference them.

code
====

- ``src/mudlib/crafting.py`` - Recipe dataclass, loading, registry
- ``src/mudlib/commands/crafting.py`` - craft and recipes commands
- ``content/recipes/`` - TOML recipe definitions
- ``src/mudlib/things.py`` - thing template registry