feat: recipe system, combining items, cooking skill

1 files changed, 264 insertions, 0 deletions

diff --git a/worldbuilding_guide/behaviors.md b/worldbuilding_guide/behaviors.md
new file mode 100644
index 0000000..a275c60
--- /dev/null
+++ b/worldbuilding_guide/behaviors.md
@@ -0,0 +1,264 @@
+## Behaviors
+
+### Gather (mining, fishing, woodcutting)
+
+Mining — per-drop depletion:
+```yaml
+id: mine_copper
+type: gather
+skill: mining
+level: 1
+xp: 17                        # XP awarded per successful gather
+base_wait: 8                   # ticks between attempts
+tool: pickaxe                  # requires item with tool_type: pickaxe
+success:
+  base: 0.40                   # 40% base chance
+  per_level: 0.01              # +1% per level above requirement
+  cap: 0.95                    # 95% max
+gather_message: "You swing your pickaxe at the rock..."
+fail_message: "You chip away but get nothing useful."
+drops:
+  - item_id: copper_ore
+    weight: 90                 # 90% chance when roll succeeds
+    depletes: true             # rock becomes depleted after this drop
+    message: "You manage to mine some copper ore."
+  - table: gem_table           # reference a shared drop table
+    weight: 10
+    depletes: false            # gem drops don't deplete the rock
+    message: "You spot a glint of something valuable!"
+respawn_timer: 50              # ticks until rock respawns
+respawn_message: "You see more ore in the rock."
+respawn_broadcast: "A glint of copper catches your eye from some {name}."
+```
+
+Non-depleting gather (fishing):
+```yaml
+id: fish_trout
+type: gather
+skill: fishing
+level: 1
+xp: 10
+base_wait: 4
+tool: fishing_rod
+success:
+  base: 0.30
+  per_level: 0.01
+  cap: 0.90
+gather_message: "You cast your line into the water..."
+fail_message: "Nothing seems to bite."
+drops:
+  - item_id: raw_trout
+    weight: 100
+    depletes: false            # never depletes
+    message: "You catch a trout!"
+```
+
+Woodcutting with shared depletion and bird's nests:
+```yaml
+id: chop_oak
+type: gather
+skill: woodcutting
+level: 15
+xp: 37
+base_wait: 6
+tool: axe
+success:
+  base: 0.40
+  per_level: 0.01
+  cap: 0.90
+gather_message: "You swing your axe at the oak tree..."
+fail_message: "You swing but get no logs."
+drops:
+  - item_id: oak_logs
+    weight: 100
+    depletes: false            # depletion is timer-based (deplete_timer)
+    message: "You get some oak logs."
+respawn_timer: 14              # ticks until tree respawns after being cut down
+deplete_timer: 45             # max ticks before next gather depletes (counts down while chopping)
+nest_chance: 256               # 1/256 chance for a bird's nest on each successful gather
+respawn_message: "A new oak sapling grows in its place."
+respawn_broadcast: "An {name} grows back."
+```
+
+Regular tree — always depletes on first gather, no shared timer, no nests:
+```yaml
+id: chop_tree
+type: gather
+skill: woodcutting
+level: 1
+xp: 25
+base_wait: 4
+tool: axe
+success:
+  base: 0.50
+  per_level: 0.01
+  cap: 0.95
+gather_message: "You swing your axe at the tree..."
+fail_message: "You swing but get no logs."
+drops:
+  - item_id: logs
+    weight: 100
+    depletes: true             # regular tree depletes on first successful gather
+    message: "You get some logs."
+respawn_timer: 80
+respawn_message: "A new tree grows in its place."
+respawn_broadcast: "A {name} grows back."
+```
+
+#### Shared depletion explained
+
+When `deplete_timer > 0`, the tree has a shared despawn timer:
+- The timer starts at `deplete_timer` max when the first player begins chopping.
+- Each tick, if anyone is chopping, the timer counts down.
+- When the timer reaches 0, the NEXT successful gather depletes the tree.
+- If no one is chopping and the tree isn't depleted, the timer ticks back UP.
+- All players chopping the same tree are interrupted when it depletes.
+
+Use `deplete_timer` for trees. Use `depletes: true` on individual drops for rocks.
+
+#### Bird's nests
+
+When `nest_chance > 0`, each successful gather has a 1/N independent chance to also drop
+a bird's nest. The nest goes to inventory (or to the ground if inventory is full).
+Use the `search` command to open nests — they roll on the `birds_nest_drop` table.
+
+#### XP drops
+
+When `xp > 0`, the gather awards XP on each successful drop. If the player's `xpdrops`
+toggle is on, the output includes the XP gain: `(+37xp wct)`.
+
+### Talk (dialog trees)
+
+Full conversation with conditions, actions, and player flag tracking:
+```yaml
+id: guard_talk
+type: talk
+nodes:
+  start:
+    message: "\"Halt! This area is restricted.\""
+    options:
+      - text: "\"What's behind that gate?\""
+        goto: about_gate
+      - text: "\"I have copper ore.\""            # only shows if player has ore
+        goto: trade_ore
+        condition:
+          has_item: copper_ore
+      - text: "\"I have a pass.\""                # only shows if player earned a pass
+        goto: has_pass
+        condition:
+          player_flag: got_pass
+          value: true
+      - text: "\"Goodbye.\""
+        end: true
+
+  about_gate:
+    message: "\"Bring me some copper ore and I'll stamp you a pass.\""
+    action:
+      set_player_flags:                           # player-local: only this player
+        talked_to_guard: true
+    options:
+      - text: "\"I'll be back.\""
+        end: true
+      - text: "\"I have some right here.\""
+        goto: trade_ore
+        condition:
+          has_item: copper_ore
+
+  trade_ore:
+    message: "\"Good quality ore.\" He stamps a pass and hands it to you."
+    action:
+      take_item: copper_ore                       # removes 1 copper ore
+      give_item: pass_stub                        # gives pass stub
+      set_player_flags:
+        got_pass: true                            # player now "has a pass"
+    options:
+      - text: "\"Thanks.\""
+        end: true
+
+  has_pass:
+    message: "\"Alright, I'll open the gate for you.\""
+    action:
+      set_flags:                                  # WORLD flag: gate opens for everyone
+        gate_open: true
+    options:
+      - text: "\"Thanks.\""
+        end: true
+```
+
+#### Node action reference
+
+| Field | Effect |
+|---|---|
+| `set_flags` | Sets world flags (global, shared by all players) |
+| `set_player_flags` | Sets player-local flags (per-character, quest progress) |
+| `give_item` | Gives an item to the player's inventory |
+| `take_item` | Removes an item from the player's inventory |
+| `teleport` | Moves the player to a room ID |
+| `heal` | Restores that many hitpoints |
+
+All fields in a single action are processed together — you can give an item, take an item, set flags, and heal all in one node.
+
+Example — quest completion:
+```yaml
+action:
+  take_item: dragon_head
+  give_item: dragon_slayer_medal
+  set_player_flags:
+    dragon_quest: complete
+    dragon_slain: true
+  heal: 99
+  teleport: 1                                     # return to town
+```
+
+### Toggle (levers, switches, gates)
+
+Simple toggle that sets a world flag:
+```yaml
+id: iron_gate_toggle
+type: toggle
+message: "You push the heavy iron gate open."
+set_flags:
+  gate_open: true
+check:                                            # only works when gate is closed
+  flag: gate_open
+  value: true
+  not: true
+```
+
+Lever that toggles between two states:
+```yaml
+id: bridge_lever
+type: toggle
+message: "You pull the lever. Mechanisms groan somewhere in the distance."
+set_flags:
+  bridge_extended: true
+check:
+  flag: bridge_extended
+  value: true
+  not: true
+```
+
+### Use (crafting stations)
+
+```yaml
+id: smelt_copper
+type: use
+message: "You place the ore in the furnace..."
+wait: 4                          # ticks between crafts
+consume:                         # items consumed per craft
+  copper_ore: 1
+reward:                          # item produced
+  item_id: copper_bar
+  quantity: 1
+fail_message: "The ore crumbles to dust."
+success:
+  base: 0.60
+  per_level: 0.01
+  cap: 0.95
+skill: smithing
+level: 1
+xp: 15                           # XP awarded per successful craft
+```
+
+---
+