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

1 files changed, 221 insertions, 0 deletions

diff --git a/building_guide/mobs.md b/building_guide/mobs.md
new file mode 100644
index 0000000..c1f9332
--- /dev/null
+++ b/building_guide/mobs.md
@@ -0,0 +1,221 @@
+## Mobs
+
+Basic combat mob with per-type defense bonuses:
+```yaml
+id: "man"
+name: "man"
+description: "A shabby-looking man."
+attack: 1
+strength: 1
+defense: 1
+hp: 7
+speed: 5
+aggressive: false
+respawn_ticks: 30
+attack_type: crush            # stab/slash/crush/ranged/science (default: crush)
+stab_defense: 0               # per-type defense bonuses
+slash_defense: 0
+crush_defense: 0
+science_defense: 0
+ranged_defense: 0
+drops:
+  remains: "bones"             # always dropped on death
+  loot:
+    - item_id: "credits"
+      weight: 98
+      quantity: 10
+    - item_id: "credits"
+      weight: 2
+      quantity: 150
+idle_descriptions:
+  - "scribbles something in a small notebook"
+  - "gazes skyward at the clouds"
+combat_descriptions:
+  - "is engaged in a fight to the death with %s"
+```
+
+### Aggressive Mobs
+
+Mobs with `aggressive: true` auto-attack players entering their room (1-tick delay). Only aggros if the player's combat level is at most double the mob's combat level. Checked on room enter and login.
+
+```yaml
+id: goblin
+name: goblin
+aggressive: true              # attacks players on sight
+attack: 1
+strength: 3
+defense: 3
+hp: 12
+attack_type: slash
+attack_bonus: 3               # equipment-equivalent attack bonus for mob's attack roll
+strength_bonus: 2             # equipment-equivalent strength bonus for mob's max hit
+stab_defense: 4
+slash_defense: 3
+crush_defense: -2             # weak to crush — negative defense is valid
+science_defense: 0
+ranged_defense: 3
+```
+
+### Mob Attack/Defense Fields
+
+| Field | Description |
+|---|---|
+| `attack` | Attack level (base accuracy) |
+| `strength` | Strength level (base max hit) |
+| `defense` | Defense level (base defense) |
+| `hp` | Hit points |
+| `ranged` | Ranged level (for ranged/science mobs) |
+| `science` | Science level |
+| `attack_bonus` | Equipment-equivalent attack bonus (added to attack roll) |
+| `strength_bonus` | Equipment-equivalent strength bonus (added to max hit) |
+| `attack_type` | Determines which player defense is used against this mob |
+| `stab_defense` through `ranged_defense` | Per-type defense bonuses |
+| `weakness` | Elemental weakness (solar/hydro/eco/bio) — for future Science combat |
+| `size` | Mob size for safespot blocking: small/medium/large/massive (default: medium) |
+
+### Protected/Unique Mobs
+
+Mob with talk behavior — can be talked to via `talk:` inline config:
+```yaml
+id: "guard"
+name: "Guard"
+talk:                           # inline talk config (no separate behavior file)
+    nodes:
+        start:
+            message: "\"Halt! Who goes there?\""
+            options:
+                - text: "\"Just passing through.\""
+                  end: true
+unique: true                    # displays as "Guard" not "a guard"
+protected: true                 # cannot be attacked
+attack: 5
+strength: 5
+defense: 5
+hp: 30
+speed: 5
+aggressive: false
+respawn_ticks: 60
+attack_type: slash
+attack_bonus: 8
+strength_bonus: 6
+stab_defense: 12
+slash_defense: 15
+crush_defense: 10
+science_defense: -5
+ranged_defense: 12
+idle_descriptions:
+  - "scans the area with a watchful eye"
+  - "adjusts the grip on his weapon"
+```
+
+Note: `wander_rooms` and `wander_interval` are NOT set on the mob definition. Wander config
+is per-instance in the room YAML (see Rooms > Mobs section above).
+
+### Stealable Mobs
+
+Mobs can be stealable via the `steal` command. On failure, the mob turns hostile and attacks.
+
+```yaml
+id: farmer
+name: Farmer
+steal_table: farmer_steal       # Drop table for steal loot
+steal_level: 10                 # Required thieving level
+steal_xp: 15                    # XP per successful steal
+steal_speed: 4                  # Ticks per steal attempt
+```
+
+| Field | Description |
+|---|---|
+| `steal_table` | Drop table ID for loot when stealing |
+| `steal_level` | Required thieving level |
+| `steal_xp` | XP awarded per successful steal |
+| `steal_speed` | Ticks per steal attempt (base wait) |
+
+### Assassin Mobs
+
+Assassin (Slayer) mobs restrict combat by assassin level and introduce finishing blows and protective equipment:
+
+```yaml
+id: slug
+name: slug
+assassin_level: 1              # required assassin level to attack
+finishing_blow: salt           # item required to kill (mob stays at 1 HP otherwise)
+attack: 3
+strength: 3
+defense: 1
+hp: 15
+speed: 6
+drops:
+  remains: slug_mucus
+  loot:
+    - item_id: credits
+      weight: 100
+      quantity: 15
+```
+
+Damage-without mobs deal 1.5x damage unless the player has the specified item equipped:
+```yaml
+id: drone
+name: drone
+assassin_level: 15
+damage_without: insulated_gloves   # 1.5x damage without this item equipped
+attack: 15
+strength: 14
+defense: 12
+hp: 45
+speed: 4
+aggressive: true
+```
+
+| Field | Description |
+|---|---|
+| `assassin_level` | Required assassin skill level to attack this mob |
+| `finishing_blow` | Item ID required to kill this mob (mob stays at 1 HP until used via `use <item> on <target>`) |
+| `damage_without` | Item ID for protection — mob deals 1.5x damage if player doesn't have it equipped |
+
+Mobs without these fields work normally (assassin_level defaults to 0, finishing_blow and damage_without default to empty).
+
+### Task Mobs (Worksites)
+
+A task mob is a non-violent "worksite" — build a solar panel, survey flora, prospect a rock — that reuses the entire combat engine. Set `kind: task`. Mechanically its `hp` is a hidden work pool that drains to 0 to **complete** the work; the player sees a progress bar filling toward 100%. A task mob **never attacks back** — the danger (if any) comes from a room `hazard:` (see `hazards.md`). Use the `work` command (or `attack`) on it.
+
+```yaml
+id: solar_panel_frame
+name: solar panel frame
+kind: task                     # "" / "combat" (default) or "task"
+verb: assemble                 # flavor verb shown in messages (default: "work on")
+progress_noun: assembly        # flavor noun in the progress line (default: "work")
+complete_message: "You bolt the final panel into place and the array hums to life!"
+hp: 40                         # units of work to complete (NOT a health bar)
+defense: 10                    # base difficulty
+speed: 5
+aggressive: false              # task mobs do not fight; this is ignored
+respawn_ticks: 40              # the worksite replenishes after this many ticks
+attack_type: crush
+# Per-type defenses become METHOD EFFICIENCY: low = that approach works well.
+crush_defense: 0               # hammering panels in: efficient
+stab_defense: 40               # stabbing a frame: useless
+slash_defense: 40
+ranged_defense: 10             # a rivet gun / scanner (ranged weapon): works
+science_defense: 10            # an analysis deck (science weapon): works
+drops:                         # the "payment" for the labour — same drop system as combat
+  loot:
+    - item_id: credits
+      weight: 95
+      quantity: 40
+    - item_id: coal
+      weight: 5
+      quantity: 1
+```
+
+Key points:
+
+- **All combat styles work.** Melee, ranged (consumes ammo as "supplies") and science decks (consume junk) all apply progress. The per-type `*_defense` values steer which method is *efficient* without forbidding any — a rock might have low `crush_defense` but high `stab_defense`.
+- **XP and buffs are identical to combat** — driven by your attack style (accurate/aggressive/defensive/balanced) and split into the combat skills. This is a non-violent way to train Attack/Strength/Defense/Ranged/Science/Hitpoints.
+- **No special equipment.** Task mobs are designed around the weapons and bonuses you already have. There is no separate "tool" equipment set.
+- **Progress decays exactly like inverted mob regen.** A task you stop working on slowly loses progress over time (the same regen that heals combat mobs, displayed inverted).
+- **One worker at a time**, the same 1-v-1 lock as combat.
+
+---
+
+