feat: safespot system implemented

4 files changed, 123 insertions, 1 deletions

diff --git a/worldbuilding_guide/behaviors.md b/worldbuilding_guide/behaviors.md
index 08dc2d1..22e97fe 100644
--- a/worldbuilding_guide/behaviors.md
+++ b/worldbuilding_guide/behaviors.md
@@ -1,7 +1,7 @@
 ## Behaviors
 
 Behaviors are **inline configs** placed directly inside object YAML (`gather:`, `talk:`,
-`use:`) or mob YAML (`talk:`). Each section below shows the keys you can use under each behavior type.
+`use:`, `safespot:`) or mob YAML (`talk:`). Each section below shows the keys you can use under each behavior type.
 
 ### Gather (mining, fishing, woodcutting)
 
diff --git a/worldbuilding_guide/hidden_objects.md b/worldbuilding_guide/hidden_objects.md
index 39030d8..24fd6bc 100644
--- a/worldbuilding_guide/hidden_objects.md
+++ b/worldbuilding_guide/hidden_objects.md
@@ -24,5 +24,17 @@ Room description hints at it:
 description: "A dusty corridor. One of the wall stones looks slightly out of place."
 ```
 
+### Safespot Objects
+
+Safespot objects should always be `hidden: true`. They only become visible in `look` when the player's effective safespot tier meets the object's `safespot.tier` requirement. This creates a natural discovery mechanic: completing quests and achievements reveals new coverage opportunities.
+
+Players can discover safespots by:
+- Reading room descriptions for hints
+- Trying `hide <object_name>` (name matching works even for hidden objects)
+- Using `look <object>` once they know the name
+- Gaining tier through progression, which reveals safespots in `look`
+
+See [Safespots](objects.md#safespots) for the full YAML format.
+
 ---
 
diff --git a/worldbuilding_guide/mobs.md b/worldbuilding_guide/mobs.md
index 70afa6a..c19efff 100644
--- a/worldbuilding_guide/mobs.md
+++ b/worldbuilding_guide/mobs.md
@@ -71,6 +71,7 @@ ranged_defense: 3
 | `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
 
diff --git a/worldbuilding_guide/objects.md b/worldbuilding_guide/objects.md
index 38eaeeb..65ab430 100644
--- a/worldbuilding_guide/objects.md
+++ b/worldbuilding_guide/objects.md
@@ -227,3 +227,112 @@ Use the `sneak` command to see guard watch state changes in real time.
 
 ---
 
+## Safespots
+
+Safespot objects provide cover that blocks melee attacks. Players use `hide <object>` to
+crouch behind them and attack with ranged or science weapons. Melee attacks force the player
+out of cover.
+
+```yaml
+id: rock_outcrop
+name: rock outcrop
+color: "248"
+hidden: true
+inroom_description: "A jagged rock outcrop juts from the floor."
+description: "A large, jagged rock formation providing natural cover."
+safespot:
+  tier: 2
+  max_block_size: large
+  max_occupants: 3
+  unsafe_chance: 0.008
+  decay_ticks: 500
+  decay_chance: 0.01
+  respawn_on_hide: false
+  respawn_ticks: 300
+  levels:
+    - message: "The rock formation stands solid."
+      degrade_message: "The rock structure begins crumbling!"
+    - message: "The rock outcrop is cracked and worn."
+      degrade_message: "A few jagged bits are all that's left of the rock outcrop!"
+    - message: "Only a few jagged rocks remain."
+      degrade_message: "The rock outcrop crumbles to nothing!"
+```
+
+Safespot objects should be `hidden: true` so they only appear in `look` when the player's
+effective safespot tier meets or exceeds the object's required tier. This creates a natural
+discovery mechanic: as players complete quests and achievements, they begin to notice cover
+they couldn't use before.
+
+### SafespotConfig Fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `tier` | int | 0 | Required safespot tier to use this object |
+| `max_block_size` | string | `""` (all) | Largest mob size blocked: small/medium/large/massive |
+| `max_occupants` | int | 0 | Max players that can hide behind this object (0 = unlimited) |
+| `unsafe_chance` | float64 | 0 | Per-tick chance (0.0-1.0) to be forced out of cover |
+| `decay_ticks` | float64 | 0 | Guaranteed ticks before object degrades one level |
+| `decay_chance` | float64 | 0 | Per-tick random chance (0.0-1.0) to degrade one level |
+| `respawn_on_hide` | bool | false | If true, re-hiding resets the safespot to max level |
+| `respawn_ticks` | float64 | 0 | Ticks until a destroyed safespot respawns (0 = never) |
+| `levels` | []SafespotLevel | required | At least one level entry |
+
+### SafespotLevel Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `message` | string | Shown to the player when the safespot is at this level |
+| `degrade_message` | string | Broadcast to the room when the safespot degrades FROM this level |
+
+Levels are ordered from highest to lowest. The first entry is the safespot's best state;
+the last entry is its weakest state before destruction. When the last level degrades,
+the safespot is destroyed.
+
+### Mob Size
+
+Mobs must have a `size` field for safespot blocking to work:
+
+```yaml
+# data/mobs/cow.yaml
+size: small
+
+# data/mobs/moss_giant.yaml
+size: large
+```
+
+Size ordering: `small` < `medium` < `large` < `massive`. Defaults to `medium` when absent.
+A safespot with `max_block_size: large` blocks mobs of size small, medium, and large,
+but not massive.
+
+### Progression
+
+Players gain safespot tier by completing quests and combat achievements, which set
+player flags via talk node actions:
+
+| Flag | Source | Tier bonus |
+|---|---|---|
+| `quest_animal_magnetism` | Quest completion | +1 |
+| `quest_dragon_slayer` | Quest completion | +1 |
+| `achieve_medium_combat` | Combat achievement | +1 |
+| `achieve_hard_combat` | Combat achievement | +2 |
+
+### Combat Integration
+
+- Melee mobs (attack_type: stab/slash/crush) cannot initiate aggro or land hits on
+  safespotted players if the mob's size is within the safespot's `max_block_size`.
+- Ranged and science mobs (attack_type: ranged/science) ignore safespots entirely.
+- If a safespotted player attacks with melee, they automatically leave cover.
+- Hiding in combat takes 4 ticks; if the mob hits during this time, the hide fails.
+- Hiding out of combat takes 1 tick.
+
+### Option: safespot_alert
+
+Players can customize the message shown when forced out of a safespot:
+
+    option safespot_alert "{196 bold}** DANGER **{/} Cover blown!"
+    option safespot_alert none
+
+Default: `"{196 bold}** Your safespot has been compromised! **{/}"`
+
+---
+