# The House of Icarus - World Building Guide

## Recipes

Recipes define how items are processed on stations to produce new items. They are the foundation for cooking, smithing, crafting, and fletching.

Recipe files live in `data/recipes/<id>.yaml`.

### Recipe vs MadeFrom

- **Recipes** (`data/recipes/`) use a station (fire, range, furnace, anvil, etc.). The player must be near the station object.
- **MadeFrom** (on the item YAML directly) is for item-on-item combinations that need no station. The player combines ingredients from their inventory.

### Recipe YAML Reference

| Field          | Type           | Description                                     |
| -------------- | -------------- | ----------------------------------------------- |
| `id`           | string         | Unique recipe identifier                        |
| `type`         | string         | Recipe type (cooking, smithing, crafting, etc.) |
| `skill`        | string         | Skill checked for success                       |
| `level`        | int            | Required skill level                            |
| `xp`           | int            | XP awarded on success                           |
| `wait`         | float64        | Ticks per craft cycle (default 6)               |
| `station`      | []string       | Station object IDs required                     |
| `consume`      | []ConsumeEntry | Ingredients consumed (see below)                |
| `output`       | string         | ItemID produced on success                      |
| `output_qty`   | int            | Quantity produced (default 1, for stackables)   |
| `fail`         | string         | ItemID produced on failure (optional)           |
| `message`      | string         | Success message                                 |
| `fail_message` | string         | Failure message                                 |
| `success`      | SuccessFormula | Optional skill check formula (see Behaviors)    |

The recipe's name in menus comes from the output item's `name` field, colored using the output item's `color`.

### ConsumeEntry — Multi-Item Ingredient Slots

Each consume entry defines an ingredient slot with multiple valid items. The first matching item found in the player's inventory is consumed.

```yaml
consume:
  - items: [item_id, alternative_id, ...]
    qty: 1
    byproducts: [byproduct_for_item, byproduct_for_alt, ...]
```

`byproducts` is optional. When present, it matches the `items` list by index — consuming `items[0]` returns `byproducts[0]` to inventory. Use `""` for items with no byproduct:

```yaml
consume:
  - items: [bucket_of_water, vial_of_water]
    qty: 1
    byproducts: [empty_bucket, ""]   # bucket returns empty, vial is consumed entirely
  - items: [herb]
    qty: 1                           # no byproducts — herb is consumed entirely
```

### Station-based recipe (cooking on a fire)

```yaml
id: cook_trout
type: cooking
skill: cooking
level: 15
xp: 70
wait: 6
station: [fire, cooking_range]
consume:
  - items: [raw_trout]
    qty: 1
output: trout
fail: burnt_fish
message: "Cooked to perfection. It looks great!"
fail_message: "You accidentally burn the trout."
```

### Station-specific recipe (range only, not fire)

```yaml
id: cook_bread
type: cooking
skill: cooking
level: 1
xp: 40
wait: 6
station: [cooking_range]
consume:
  - items: [bread_dough]
    qty: 1
output: bread
fail: burnt_meat
message: "You bake the dough into a fresh loaf of bread."
fail_message: "You burn the bread to a crisp."
```

### Smelting recipe (ore to bar at a furnace)

Smelting recipes use `type: smelting` and `station: [furnace]`. The `smelt` command or `use <ore> on furnace` triggers them. Multi-ore recipes use `qty` on consume entries.

```yaml
id: smelt_steel
type: smelting
skill: smithing
level: 40
xp: 17
wait: 4
station: [furnace]
consume:
  - items: [iron_ore]
    qty: 1
  - items: [coal]
    qty: 2
output: steel_bar
message: "You remove a white hot steel bar!"
fail_message: "You fail to smelt a usable bar."
```

Iron smelting uses a `success` formula for its 50% failure rate:

```yaml
success:
  base: 0.5
  per_level: 0
  cap: 0.5
```

### Smithing recipe (bar to item at an anvil)

Smithing recipes use `type: smithing` and `station: [anvil]`. The `smith` command or `use <bar> on anvil` triggers them. Requires a hammer (`tool_type: hammer`) in inventory.

```yaml
id: smith_steel_platebody
type: smithing
skill: smithing
level: 48
xp: 187
wait: 4
station: [anvil]
consume:
  - items: [steel_bar]
    qty: 5
output: steel_platebody
message: "You hammer out a steel platebody."
```

For stackable outputs, use `output_qty`:

```yaml
id: smith_iron_nails
type: smithing
skill: smithing
level: 24
xp: 25
wait: 4
station: [anvil]
consume:
  - items: [iron_bar]
    qty: 1
output: iron_nails
output_qty: 15
message: "You hammer out some iron nails."
```

### MadeFrom — Item-on-item combinations

Item-on-item combinations are defined directly on the output item via the `made_from` field. No recipe file needed.

```yaml
# data/items/bread_dough.yaml
id: bread_dough
name: bread dough
color: "222"
made_from:
  - items: [pot_of_flour]
    qty: 1
  - items: [bucket_of_water, pitcher_of_water, vial_of_water]
    qty: 1
```

The player uses `use flour on water` to combine them. The system finds that `bread_dough` can be made from these ingredients and produces it.

### Food/Healing Items

Items with `heal_value` and `eat_message` can be consumed via the `eat` command.

```yaml
id: bread
name: bread
color: "222"
description: "A fresh loaf of bread, still warm from the oven."
value: 5
heal_value: 5
eat_message: "You eat the bread. Warm and satisfying."
```