feat: web client, get/drop updates and fixes

1 files changed, 182 insertions, 14 deletions

diff --git a/WORLDBUILDING.md b/WORLDBUILDING.md
index a0ca168..9585c32 100644
--- a/WORLDBUILDING.md
+++ b/WORLDBUILDING.md
@@ -92,13 +92,28 @@ spawns:
 
 ### Mobs — NPCs placed in the room
 
+Simple string (no wandering):
 ```yaml
 mobs:
-  - "man"           # spawns a "man" mob
-  - "man"           # second "man" — duplicate IDs create multiple instances
-  - "guard"         # unique named mob
+  - "newbie_trainer"
+  - "man"
 ```
 
+With wander config per-instance:
+```yaml
+mobs:
+  - id: man
+    wander_interval: 10      # attempts to wander every 10 ticks
+  - id: man
+    wander_interval: 15
+    wander_rooms: [1, 4, 5]  # optional — only exit to these rooms
+```
+
+Mob wander config lives in the room YAML, not in the mob definition. This keeps mobs generic
+so the same `man` can wander differently depending on where it's placed. Mobs wander through
+legal (unconditioned) room exits. If no legal exits exist, the mob stays still. Mobs with
+no `wander_interval` never wander.
+
 ### Objects — interactive fixtures
 
 ```yaml
@@ -106,7 +121,7 @@ objects:
   - id: copper_rock                                    # simple placement
   - id: copper_rock                                    # second instance
   - id: fishing_spot
-    wander_rooms: [7, 8, 9]                            # moves between these rooms
+    wander_rooms: [7, 8, 9]                            # teleports between these rooms
     wander_interval: 12                                # every 12 ticks
   - id: iron_gate                                      # hidden object (see below)
 ```
@@ -143,7 +158,6 @@ stats:                        # optional — combat bonuses
   attack_bonus: 2
   strength_bonus: 1
 speed: 5                      # ticks between attacks
-toolbelt: true                # usable from toolbelt (doesn't need to be in inventory)
 tool_type: pickaxe            # used by gather behaviors that require "tool: pickaxe"
 tool_speed: 2                 # reduces gather wait time
 ```
@@ -173,8 +187,6 @@ hp: 7
 speed: 5
 aggressive: false
 respawn_ticks: 30
-wander_rooms: [1, 2, 3]
-wander_interval: 10
 drops:
   remains: "bones"             # always dropped on death
   loot:
@@ -210,6 +222,9 @@ idle_descriptions:
   - "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).
+
 ---
 
 ## Objects
@@ -221,6 +236,13 @@ name: copper rock
 behavior: mine_copper
 ```
 
+Tree object:
+```yaml
+id: oak_tree
+name: oak tree
+behavior: chop_oak
+```
+
 Hidden object — doesn't appear in room's object list, only discoverable via description or experimentation:
 ```yaml
 id: iron_gate
@@ -246,11 +268,13 @@ props:
 
 ### 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:
@@ -279,6 +303,7 @@ id: fish_trout
 type: gather
 skill: fishing
 level: 1
+xp: 10
 base_wait: 4
 tool: fishing_rod
 success:
@@ -294,6 +319,80 @@ drops:
     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 (shared_deplete)
+    message: "You get some oak logs."
+deplete_delay: 14              # ticks until tree respawns after being cut down
+shared_deplete: 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."
+deplete_delay: 80
+respawn_message: "A new tree grows in its place."
+respawn_broadcast: "A {name} grows back."
+```
+
+#### Shared depletion explained
+
+When `shared_deplete > 0`, the tree has a shared despawn timer:
+- The timer starts at `shared_deplete` 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 `shared_deplete` 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:
@@ -424,6 +523,7 @@ success:
   cap: 0.95
 skill: smithing
 level: 1
+xp: 15                           # XP awarded per successful craft
 ```
 
 ---
@@ -511,6 +611,28 @@ drops:
     weight: 1
 ```
 
+Bird's nest drop table:
+```yaml
+# data/drops/birds_nest_drop.yaml
+id: birds_nest_drop
+drops:
+  - item_id: credits
+    weight: 50
+    quantity: 200
+  - item_id: credits
+    weight: 30
+    quantity: 500
+  - item_id: credits
+    weight: 15
+    quantity: 1000
+  - item_id: credits
+    weight: 4
+    quantity: 3000
+  - item_id: credits
+    weight: 1
+    quantity: 10000
+```
+
 Referenced from a gather behavior:
 ```yaml
 drops:
@@ -744,26 +866,68 @@ behavior: fish_trout
 ```
 
 ```yaml
-# In rooms 7, 8, and 9:
+# In a room:
 objects:
   - id: fishing_spot
     wander_rooms: [7, 8, 9]
     wander_interval: 12
 ```
 
-Players gathering from a wandering object are silently interrupted when it moves.
+Objects teleport between rooms in their `wander_rooms` list. Players gathering from a
+wandering object are silently interrupted when it moves.
 
 ---
 
 ## Wandering Mobs
 
+Mob wandering is configured per-instance in the room YAML, not on the mob definition:
 ```yaml
-# mobs that roam between rooms:
-wander_rooms: [1, 2, 3, 4]
-wander_interval: 10     # moves every 10 ticks
+# In a room:
+mobs:
+  - id: man
+    wander_interval: 10       # attempt to wander every 10 ticks
+  - id: man
+    wander_interval: 15
+    wander_rooms: [5, 6, 7]   # optional — restrict which rooms via exits
 ```
 
-Mobs stop wandering while in combat. Dead mobs respawn at their home room after `respawn_ticks`.
+Mobs wander through legal (unconditioned) room exits. When the wander interval expires,
+the mob picks a random exit with no conditions and moves through it. If `wander_rooms`
+is set, only exits leading to those room IDs are legal. Mobs without `wander_interval`
+never wander. Mobs stop wandering while in combat. Dead mobs respawn at their home room.
+
+---
+
+## Player Toggles
+
+Players can toggle personal settings with the `toggle` command:
+
+| Toggle | Effect |
+|---|---|
+| `description` | Show full room description when moving |
+| `tinymap` | Mini-map display (not yet implemented) |
+| `xpdrops` | Show XP gained in gather/craft/combat messages |
+| `exits` | Show exit destinations inline in look output |
+| `mobenter` | Notify when a mob enters the room |
+| `mobleave` | Notify when a mob leaves the room |
+| `mobspawn` | Notify when a mob spawns in the area |
+| `reserve` | Show full reserved item details in look |
+| `depletion` | Show depletion and despawn timers on objects |
+
+---
+
+## The `search` Command
+
+Used to open searchable items in your inventory (bird's nests, etc.):
+```
+Usage: search <item>
+
+Example: search nest
+         search birds nest
+```
+
+Searches your inventory for the named item. If found, removes it and rolls on a drop table.
+Currently only bird's nests are searchable.
 
 ---
 
@@ -802,6 +966,10 @@ description: "A dusty corridor. One of the wall stones looks slightly out of pla
 
 6. **The `behavior` field on mobs** lets you talk to them directly — `talk guard` finds the guard mob, no duplicate object entry needed.
 
-7. **Exits accept both `int` and `map` formats.** `north: 2` is shorthand for `north: {room: 2}`. Add `condition` and `blocked_message` only when needed.
+7. **Exits accept both `int` and `map` formats.** `north: 2` is shorthand for `north: {room: 2}`. Add `condition` and `blocked_message` only when needed. Mob room entries accept both `"man"` and `{id: man, ...}`.
 
 8. **Live editing works.** Room, item, mob, object, and behavior YAML files are read from disk on each access. Change a room description or dialog and it takes effect immediately — no restart needed.
+
+9. **Shared depletion vs per-drop depletion.** Use `shared_deplete` for trees — the timer counts down while being chopped and regens when left alone. Use `depletes: true` on individual drops for rocks — they deplete on first successful gather.
+
+10. **Mob wander config goes in the room YAML**, not the mob definition. This lets the same `man` wander differently in different rooms.