feat: new type of non-violent 'combat': work

1 files changed, 190 insertions, 0 deletions

diff --git a/building_guide/items.md b/building_guide/items.md
new file mode 100644
index 0000000..52bfa7d
--- /dev/null
+++ b/building_guide/items.md
@@ -0,0 +1,190 @@
+## Items
+
+```yaml
+id: bronze_pickaxe
+name: bronze pickaxe
+color: "178"                   # xterm-256 color index (0-255)
+aliases: ["pick", "pickaxe"]
+description: "A sturdy bronze pickaxe."
+value: 10
+stackable: false
+equip_slot: main_hand        # optional — where it equips
+weapon_type: melee            # optional — melee, ranged, or science
+attack_type: stab             # stab/slash/crush/ranged/science — determines accuracy type
+stats:                        # optional — per-type combat bonuses
+  stab_attack: 4
+  slash_attack: -2
+  crush_attack: 2
+  strength_bonus: 3
+speed: 5                      # ticks between attacks
+tool_type: pickaxe            # used by gather behaviors that require "tool: pickaxe"
+tool_speed: 2                 # reduces gather wait time
+requirements:                 # optional — skill levels needed to equip
+  accuracy: 1
+```
+
+### Equipment Stats (ItemStats)
+
+Weapons have per-type **attack bonuses** — these determine accuracy based on the weapon's `attack_type`:
+
+| Field | Description |
+|---|---|
+| `stab_attack` | Accuracy bonus for stab attacks |
+| `slash_attack` | Accuracy bonus for slash attacks |
+| `crush_attack` | Accuracy bonus for crush attacks |
+| `science_attack` | Accuracy bonus for science attacks |
+| `ranged_attack` | Accuracy bonus for ranged attacks |
+
+Armor has per-type **defense bonuses** — the mob's `attack_type` determines which defense is used:
+
+| Field | Description |
+|---|---|
+| `stab_defense` | Defense vs stab attacks |
+| `slash_defense` | Defense vs slash attacks |
+| `crush_defense` | Defense vs crush attacks |
+| `science_defense` | Defense vs science attacks (negative on metal armor) |
+| `ranged_defense` | Defense vs ranged attacks |
+
+Other damage/utility bonuses:
+
+| Field | Description |
+|---|---|
+| `strength_bonus` | Melee max hit bonus |
+| `ranged_strength` | Ranged max hit bonus (on ammo) |
+| `science_damage` | Science max hit bonus |
+| `technology_bonus` | Reduces tech battery drain rate |
+
+### Attack Type
+
+Weapons should always set `attack_type`. Common mappings:
+
+| Category | attack_type |
+|---|---|
+| Swords | slash |
+| Daggers | stab |
+| Axes | slash |
+| Pickaxes | stab |
+| Bows | ranged |
+| Unarmed | crush (default) |
+
+### Equipment Requirements
+
+Higher-tier equipment requires skill levels to equip:
+
+```yaml
+requirements:
+  accuracy: 20      # melee weapons
+  defense: 20     # armor
+  ranged: 30      # ranged weapons/armor
+```
+
+Standard tiers: bronze/iron (none), steel (5), black (10), mithril (20), adamant (30), rune (40), dragon (60).
+
+### Ranged Ammo
+
+Arrows and bolts use `ranged_strength` for damage. Accuracy comes from the bow:
+
+```yaml
+id: iron_arrow
+name: iron arrow
+stackable: true
+equip_slot: ammo
+stats:
+  ranged_strength: 10
+```
+
+### Color
+
+The `color` field accepts xterm-256 palette indices (0-255) with optional modifiers:
+
+```yaml
+color: "178"                   # bronze/gold
+color: "75 bold"               # bold steel blue
+color: "g:196,208,226"         # gradient red → orange → gold
+```
+
+In ANSI mode, extended colors (16-255) automatically downgrade to the nearest ANSI color. Use `colortable` in-game to see all 256 colors.
+
+Key item (quest token, not equippable):
+```yaml
+id: pass_stub
+name: pass stub
+description: "A crumpled slip of paper stamped with the guard's seal."
+value: 0
+stackable: false
+```
+
+---
+
+## Firemaking
+
+```yaml
+id: logs
+name: logs
+fire_level: 1         # firemaking level required
+fire_xp: 40           # XP for burning/stoking
+burn_ticks: 24        # how long the fire burns
+```
+
+## Food / Healing
+
+```yaml
+id: bread
+name: bread
+color: "222"
+description: "A fresh loaf of bread, still warm from the oven."
+value: 5
+heal_value: 5         # positive = heal, negative = damage
+eat_message: "You eat the bread. Warm and satisfying."
+```
+
+## MadeFrom — Item Combinations
+
+Define what items combine to make this item. Used by the `use` command. Combinations run through the production system — players are prompted "How many?" and the action loops with a timer.
+
+```yaml
+id: bread_dough
+name: bread dough
+color: "222"
+ticks: 2
+made_from:
+  - items: [pot_of_flour]
+    quantity: 1
+    byproducts: [empty_pot]
+  - items: [bucket_of_water, pitcher_of_water]
+    quantity: 1
+    byproducts: [empty_bucket, empty_pitcher]
+```
+
+Each entry is an ingredient slot. Multiple `items` means any of them works. The first matching item found in inventory is consumed.
+
+`ticks` controls how many game ticks each production cycle takes (default 2).
+
+### Byproducts
+
+`byproducts` is a list matching the `items` list by index. When `bucket_of_water` (items[0]) is consumed, `empty_bucket` (byproducts[0]) is returned to inventory. When `pitcher_of_water` (items[1]) is consumed, `empty_pitcher` (byproducts[1]) is returned instead.
+
+Use `""` for items that produce no byproduct:
+
+```yaml
+made_from:
+  - items: [pot_of_flour, loose_flour]
+    quantity: 1
+    byproducts: [empty_pot, ""]   # pot returns empty_pot, loose flour returns nothing
+  - items: [bucket_of_water]
+    quantity: 1
+    byproducts: [empty_bucket]
+```
+
+Omit `byproducts` entirely if no items in that slot produce a byproduct:
+
+```yaml
+made_from:
+  - items: [pot_of_flour]
+    quantity: 1
+    byproducts: [empty_pot]       # returns empty_pot
+  - items: [salt]
+    quantity: 1                        # no byproducts field — salt is consumed entirely
+```
+
+See also `recipes.md` for station-based recipes.