fix: combat formulas and mob attack types (mobs switch attack styles if safespotting)

3 files changed, 67 insertions, 46 deletions

diff --git a/building_guide/mobs.md b/building_guide/mobs.md
index 31ff109..7a6f0aa 100644
--- a/building_guide/mobs.md
+++ b/building_guide/mobs.md
@@ -22,15 +22,16 @@ drops:
       quantity: 10
 combat:
   kind: combat
+  aggressive: false
+  attack_types: [crush]        # list: exactly one melee (stab/slash/crush) + optional ranged/science
+  respawn_ticks: 30
   stats:
     hp: 7
     attack: 1
     strength: 1
     defense: 1
-    attack_type: crush          # stab/slash/crush/ranged/science (default: crush)
     speed: 5
-    aggressive: false
-    respawn_ticks: 30
+    max_melee_hit: 1             # max hit with melee (for melee-attacking mobs)
     bonuses:
       attack_bonus: 0
       strength_bonus: 0
@@ -51,21 +52,22 @@ combat:
 
 ### Aggressive Mobs
 
-Mobs with `combat.stats.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.
+Mobs with `combat.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
 name: goblin
 combat:
   kind: combat
+  aggressive: true              # attacks players on sight
+  attack_types: [slash]
+  respawn_ticks: 25
   stats:
-    aggressive: true              # attacks players on sight
     hp: 12
     attack: 1
     strength: 3
     defense: 3
-    attack_type: slash
     speed: 5
-    respawn_ticks: 25
+    max_melee_hit: 1            # OSRS-derived: ((strength+9)*(strength_bonus+64)+320)/640
     bonuses:
       attack_bonus: 3             # equipment-equivalent attack bonus for mob's attack roll
       strength_bonus: 2           # equipment-equivalent strength bonus for mob's max hit
@@ -94,10 +96,10 @@ All combat stats live under `combat.stats:`
 | `defense` | Defense level (base defense) |
 | `ranged` | Ranged level (for ranged/science mobs) |
 | `science` | Science level |
-| `attack_type` | Determines which player defense is used against this mob (stab/slash/crush/ranged/science) |
 | `speed` | Attack speed in ticks (default 5) |
-| `aggressive` | Auto-attacks players on sight (false if omitted) |
-| `respawn_ticks` | Ticks until respawn after death |
+| `max_melee_hit` | Maximum melee hit (for melee-attacking mobs). Computed as ((strength+9)*(strength_bonus+64)+320)/640 |
+| `max_ranged_hit` | Maximum ranged hit (for ranged-attacking mobs). Computed as ((ranged+9)*(ranged_bonus+64)+320)/640 |
+| `max_science_hit` | Maximum science hit (for science-attacking mobs). A set value — magic max hits are not level-derived in OSRS |
 
 #### Bonuses (`combat.stats.bonuses:`)
 
@@ -105,10 +107,10 @@ All combat stats live under `combat.stats:`
 |---|---|
 | `attack_bonus` | Equipment-equivalent attack bonus (added to attack roll) |
 | `strength_bonus` | Equipment-equivalent strength bonus (added to max hit) |
-| `science_bonus` | Equipment-equivalent science attack bonus |
-| `science_percent_bonus` | Percent boost to science damage |
-| `ranged_bonus` | Equipment-equivalent ranged attack bonus |
-| `ranged_strength_bonus` | Equipment-equivalent ranged strength bonus |
+| `science_bonus` | Equipment-equivalent science attack bonus (used for science-attacking mobs' accuracy) |
+| `science_percent_bonus` | Percent boost to science damage (applied to max_science_hit for science-attacking mobs) |
+| `ranged_bonus` | Equipment-equivalent ranged attack bonus (used for ranged-attacking mobs' accuracy) |
+| `ranged_strength_bonus` | Equipment-equivalent ranged strength bonus (used for max_ranged_hit derivation) |
 
 #### Defenses (`combat.stats.defenses:`)
 
@@ -119,13 +121,17 @@ All combat stats live under `combat.stats:`
 | `crush_defense` | Crush defense bonus |
 | `science_defense` | Science defense bonus |
 | `ranged_defense` | Ranged defense bonus |
-| `weakness` | Elemental weakness (solar/hydro/eco/bio/chaos) — for future Science combat |
+| `weakness` | Elemental weakness (solar/hydro/eco/bio/chaos) — matching science module element gives +accuracy% and +damage |
+| `weakness_percent` | Percent bonus per point of elemental weakness (e.g. 50 = +50% accuracy and +50% base max hit) |
 
 #### Combat-level fields (under `combat:`)
 
 | Field | Description |
 |---|---|
 | `kind` | `combat` (default) or `task` — task mobs are worksites |
+| `aggressive` | Auto-attacks players on sight (false if omitted). Only aggros if player's combat level ≤ mob level × 2 |
+| `attack_types` | List of attack types this mob can use. Must contain **exactly one** melee type (`stab`/`slash`/`crush`) and may optionally add `ranged` and/or `science`. The mob uses its melee type in normal combat; when a player is safespotted from melee it switches to its strongest ranged/science type (by max hit). Written as a YAML list, e.g. `[crush]` or `[stab, ranged]`. |
+| `respawn_ticks` | Ticks until respawn after death |
 | `size` | Mob size for safespot blocking: small/medium/large/massive (default: medium) |
 | `assassin_level` | Required assassin skill level to attack this mob |
 | `finishing_blow` | Item ID required to kill (mob stays at 1 HP until used via `use <item> on <target>`) |
@@ -215,15 +221,15 @@ steal:
   speed: 4                        # Ticks per steal attempt
 combat:
   kind: combat
+  attack_types: [slash]
+  respawn_ticks: 25
   stats:
-    hp: 15
-    attack: 3
+    hp: 12
+    attack: 1
     strength: 3
     defense: 3
-    attack_type: crush
     speed: 5
-    aggressive: false
-    respawn_ticks: 40
+    max_melee_hit: 1
     bonuses:
       attack_bonus: 0
       strength_bonus: 0
@@ -257,15 +263,16 @@ Assassin (Slayer) mobs restrict combat by assassin level and introduce finishing
 name: slug
 combat:
   kind: combat
+  aggressive: false
+  attack_types: [crush]
+  respawn_ticks: 25
   stats:
     hp: 15
     attack: 3
     strength: 3
     defense: 1
-    attack_type: crush
     speed: 6
-    aggressive: false
-    respawn_ticks: 25
+    max_melee_hit: 1
     bonuses:
       attack_bonus: 0
       strength_bonus: 0
@@ -297,15 +304,16 @@ Damage-without mobs deal 1.5x damage unless the player has the specified item eq
 name: drone
 combat:
   kind: combat
+  aggressive: true
+  attack_types: [crush]
+  respawn_ticks: 35
   stats:
     hp: 45
     attack: 15
     strength: 14
     defense: 12
-    attack_type: crush
     speed: 4
-    aggressive: true
-    respawn_ticks: 35
+    max_melee_hit: 2              # drone: strength 14, bonuses 0
     bonuses:
       attack_bonus: 0
       strength_bonus: 0
@@ -349,13 +357,14 @@ idle_descriptions:
   - "stands half-assembled, panels waiting to be fitted"
 combat:
   kind: task                     # "task" triggers the work-engine mode
+  aggressive: false              # task mobs do not fight; this is ignored
+  attack_types: [crush]
+  respawn_ticks: 40              # the worksite replenishes after this many ticks
   stats:
     hp: 40                       # units of work to complete (NOT a health bar)
     defense: 10                  # base difficulty
-    attack_type: crush
     speed: 5
-    aggressive: false            # task mobs do not fight; this is ignored
-    respawn_ticks: 40            # the worksite replenishes after this many ticks
+    max_melee_hit: 0             # task mobs do not attack; max hits are unused
     bonuses:
       attack_bonus: 0
       strength_bonus: 0
diff --git a/building_guide/objects.md b/building_guide/objects.md
index a897255..af693c4 100644
--- a/building_guide/objects.md
+++ b/building_guide/objects.md
@@ -449,9 +449,12 @@ player flags via talk node actions:
 
 ### 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.
+- A safespot blocks a mob's **melee** attacks if the mob's size is within the
+  safespot's `max_block_size`.
+- When a mob's melee is blocked, if it also has a `ranged`/`science` attack type it
+  switches to its strongest ranged/science attack (by max hit) and keeps attacking.
+  A mob with only melee is fully blocked (cannot aggro or land hits).
+- Mobs whose size exceeds `max_block_size` are never blocked and always use melee.
 - 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.
diff --git a/building_guide/quests.md b/building_guide/quests.md
index b9556dc..ff04118 100644
--- a/building_guide/quests.md
+++ b/building_guide/quests.md
@@ -41,14 +41,19 @@ talk:
                 heal: 10
             options:
                 - text: "\"Thanks!\""
-attack: 1
-strength: 1
-defense: 1
-hp: 20
-speed: 5
-aggressive: false
+combat:
+  kind: combat
+  aggressive: false
+  attack_types: [crush]
+  respawn_ticks: 30
+  stats:
+    attack: 1
+    strength: 1
+    defense: 1
+    hp: 20
+    speed: 5
 idle_descriptions:
-    - "mutters about the rat infestation"
+  - "mutters about the rat infestation"
 ```
 
 Talk configs are inline on the mob under the `talk:` key. No separate behavior file needed.
@@ -56,13 +61,17 @@ Talk configs are inline on the mob under the `talk:` key. No separate behavior f
 ### 2. Rat mobs (`data/mobs/rat.yaml`)
 ```yaml
 name: "giant rat"
-attack: 2
-strength: 1
-defense: 1
-hp: 3
-speed: 4
-aggressive: true
-respawn_ticks: 60
+combat:
+  kind: combat
+  aggressive: true
+  attack_types: [crush]
+  respawn_ticks: 60
+  stats:
+    attack: 2
+    strength: 1
+    defense: 1
+    hp: 3
+    speed: 4
 drops:
   remains: "rat bones"
 ```