Phase 3: Alpha guardians, one per zone, back 5 hours after a defeat

- Companion mod (zone/Guardians.kt): each zone's guardian stands at the
  zone's sample point, appears when a player is within 96 blocks, stays
  within 24 blocks, is uncatchable and half again as big. Beating it in a
  battle gives every player in the battle its drops; it returns after 5
  hours of game time (Adrian: fixed spots, 5 hours). State lives in the
  world save; /cobblesurvival guardians lists it.
- tools/zone_spawns.py writes data/cobblesurvival/guardians/<zone>.json:
  the strongest walking (or swimming) Pokemon of the zone at band top + 5,
  with the drops from world/zones.json. Boss drops follow Adrian's rule:
  Icy Rocks before Sunscorch, Heat Rocks before Frostpeak.
- Goat Fur and Hoglin Hide recipes make 8 per rock, so one guardian's 3
  rocks pay for one full insulating set.
- Self-test guardian_appears_and_returns; hazard tests cleaned up; the
  zone generator reads Cobblemon's own entries from the field guide's
  hidden_spawns.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/balance.md

@@ -22,7 +22,10 @@ Every tunable lives in a config file or in this table. **Placeholder** means gue
 | Windswept hills temperature | 45–72 °F (Cold Sweat: 24–58 °F) | Placeholder | `config/coldsweat/world.toml` | They lie in the starter lowlands too |
 | Insulating armour | fur set (cold 10/14/12/10), hide set (heat 10/14/12/10), as Cold Sweat; leather armour none (Cold Sweat: 5/7/6/5 both) | Placeholder | `config/coldsweat/item.toml` | Frostpeak at noon: about 1 min bare, 14 min in fur; Sunscorch at noon: about 2 min bare, 25 min in hide |
 | Sewn-in insulation | goat fur 2 cold, hoglin hide 2 heat, wool 0.5 cold, leather 0.5/0.5 (Cold Sweat: wool 1.5, leather 1/1, rabbit hide 1.5 heat) | Placeholder | `config/coldsweat/item.toml` | |
-| Goat Fur / Hoglin Hide recipes | 8 wool + 1 Heat Rock → 4 Goat Fur; 8 leather + 1 Icy Rock → 4 Hoglin Hide | Placeholder | `kubejs/server_scripts/insulation.js` | Heat and Icy Rocks come from the guardians before Frostpeak and Sunscorch (archaeology finds too) |
+| Goat Fur / Hoglin Hide recipes | 8 wool + 1 Heat Rock → 8 Goat Fur; 8 leather + 1 Icy Rock → 8 Hoglin Hide (a set takes 24) | Placeholder | `kubejs/server_scripts/insulation.js` | Heat and Icy Rocks come from the guardians before Frostpeak and Sunscorch (archaeology finds too) |
+| Guardian respawn | 5 hours of game time after being beaten | Decided (Adrian, 2026-10-29) | `world/zones.json` → `guardian_respawn_hours` | Fixed spots |
+| Guardian strength | strongest Pokémon spawning in the zone, band top + 5 levels, 1.5× size, uncatchable | Placeholder | `tools/zone_spawns.py` (`GUARDIAN_*`), `world/zones.json` → `guardian.species` | |
+| Guardian drops | Button Isle 10 Poké Balls + 4 Potions; Southwold 6 Great Balls + 4 Exp. Candy S; Westmarch and Jungle 8 Pecha Berries + 2 Exp. Candy M; Mire and Highlands 3 Icy Rocks + 4 Super Potions; Sunscorch 3 Heat Rocks + 2 Exp. Candy L; Frostpeak and Deep Dark 3 Icy Rocks + 2 Exp. Candy L; Deep Sea Mystic Water + 3 Exp. Candy M | Placeholder | `world/zones.json` → `guardian.drops` | 3 rocks make one full fur or hide set |
 | Healing while sleeping | off (`healPercent` 0) | Decided (roadmap) | `config/cobblemon/main.json` | |
 | Loot container refresh | 1 hour (72,000 ticks of game time) after first opened, all containers | Decided (Adrian, 2026-10-29) | `config/lootr-common.toml` | Tiering by structure/biome later |
 | Gamerules in the template | `doMobSpawning false` | Decided (Adrian, 2026-10-28; may be reverted later) | `world/world.json` → `gamerules` | Pokémon spawning is Cobblemon's own `doPokemonSpawning` |

docs/checklists/phase-3.md

@@ -17,7 +17,9 @@ Open `build/zone-map.png` (the island coloured by zone) and read the draft in `d
 
 - **Heat and cold** (step 5, Cold Sweat). Automated: `cold_needs_fur`, `heat_needs_hide` and `lowlands_are_mild` on the island in `tools/quick_check.py`.
 
-Still to come: Alpha guardians with the boss drops that help the next zone (including the Heat and Icy Rocks), the Mire's poison, soft level pressure, flyers.
+- **Alpha guardians** (step 4). One per zone at a fixed spot, back 5 hours after being beaten; drops help with the next zone (`docs/zone-species.md` lists them). Automated: `guardian_appears_and_returns`.
+
+Still to come: the Mire's poison (and the wading gear the Westmarch and Jungle guardians should drop for it), soft level pressure, flyers.
 
 ## In-game
 
@@ -27,3 +29,4 @@ Still to come: Alpha guardians with the boss drops that help the next zone (incl
 - [ ] **Frostpeak cold:** walk onto the jagged peaks without gear: Cold Sweat's thermometer drops and after a minute or so you take damage (not during the first 5 minutes of a new world: grace period). In the fur set (Goat Fur from 8 wool + 1 Heat Rock) you last many minutes.
 - [ ] **Sunscorch heat:** the desert at noon overheats you in a couple of minutes; at night it's fine. The hide set (Hoglin Hide from 8 leather + 1 Icy Rock) or a Fire Resistance potion keeps you going.
 - [ ] **Lowlands:** a night in Southwold or on Button Isle without gear never gets dangerous.
+- [ ] **Guardians:** `/cobblesurvival guardians` (operator) lists each zone's guardian and spot. Walk there: a big Pokémon appears, can't be caught, and beating it puts its drops in your inventory with a gold message. It's gone for 5 hours of play.

docs/design.md

@@ -109,6 +109,12 @@ Order of play the bands suggest: Button Isle → Southwold → Westmarch or Jung
 - Basalt Furnace got Durant, Torkoal and Heatmor pinned to it: its own lines were all big (Charizard, Turtonator, Centiskorch, …) and Cobblemon only spawns a Pokémon where its body fits, so cramped basalt caves stayed empty.
 - Tested: `spawn_pools_are_zoned` (no Cobblemon default spawn is left; every entry has a zone and spawns within its band) and `spawn_survey` (a player at a point deep inside each zone is offered only that zone's spawns, and at least one), both in `tools/quick_check.py`.
 
+**Alpha guardians** (Phase 3, step 4; Adrian, 2026-10-29: fixed spots, back 5 hours after being beaten):
+- One per zone except the Shallows, Lush Caves and Dripstone; the Basalt Furnace gets its boss in Phase 7. Each stands at its zone's sample point (deep inside the zone; a cave floor for the Deep Dark) and only appears while a player is within 96 blocks; it wanders no further than 24 blocks.
+- The guardian is the strongest Pokémon that spawns walking (or, at sea, swimming) in its zone, five levels above the band, half again as big, and uncatchable: Pachirisu (Button Isle), Sigilyph (Southwold), Carbink (Westmarch), Tangrowth (Jungle), Arcanine (Mire), Cinderace (Highlands), Delphox (Sunscorch), Tyranitar (Frostpeak), Kingdra (Deep Sea), Dusknoir (Deep Dark). `world/zones.json` → `guardian.species` overrides the pick.
+- Beating it in a battle gives every player in that battle its drops (the chain above: Icy Rocks before Sunscorch, Heat Rocks before Frostpeak, ...). It returns after 5 hours of game time, which only passes while the server runs. Cobblemon's Habitat Blocks were the roadmap's idea, but they can't wait a set time after a defeat or carry custom drops, so the companion mod runs guardians (`zone/Guardians.kt`; state in the world save; `/cobblesurvival guardians` for operators). Definitions: `datapacks/core/data/cobblesurvival/guardians/<zone>.json`, written by `tools/zone_spawns.py`.
+- Tested: `guardian_appears_and_returns` (appears big and uncatchable at its level, beaten in a real battle, drops arrive, stays away, returns after its time).
+
 **Hazards** (Phase 3, step 5), with Cold Sweat 2.4.4:
 - Cold and heat follow the biome: Frostpeak's jagged peaks freeze an unprotected player in about a minute even at noon, Sunscorch's desert and badlands overheat one in about two minutes at noon; deserts cool off at night. Cold Sweat's insulation doesn't move the comfortable range, it slows how fast the body drifts out of it.
 - Only Cold Sweat's fur set (cold) and hide set (heat) really insulate: about 14 minutes in Frostpeak at noon and 25 in Sunscorch, longer with extra fur or hide sewn in. Their materials need boss drops (Adrian's rule): Goat Fur from wool and a Heat Rock (Sunscorch's guardian), Hoglin Hide from leather and an Icy Rock (the Mire's and the Highlands' guardians), `kubejs/server_scripts/insulation.js`. Leather armour no longer insulates by itself; sewn-in leather and wool only a little. Fire Resistance and Cold Sweat's own potions and warm/cold food still work.

docs/zone-species.md

@@ -57,3 +57,20 @@ Duskull (Dusclops, Dusknoir), Feebas (Milotic), Greavard (Houndstone), Mimikyu,
 ## Basalt Furnace (Lv 55–70, 9 lines)
 
 Charmander (Charizard), Durant, Gligar (Gliscor), Heatmor, Houndour (Houndoom), Magby (Magmortar), Sizzlipede (Centiskorch), Torkoal, Turtonator
+
+## Alpha guardians
+
+One per zone at its sample point, uncatchable, five levels above the band; it returns 5 hours after it is beaten. Its drops help with the next zone.
+
+| Zone | Guardian | Level | Drops |
+| --- | --- | --- | --- |
+| Button Isle | Pachirisu | 15 | 10× poke_ball, 4× potion |
+| Frostpeak Range | Tyranitar | 60 | 3× icy_rock, 2× exp_candy_l |
+| Sunscorch | Delphox | 50 | 3× heat_rock, 2× exp_candy_l |
+| Mangrove Mire | Arcanine | 43 | 3× icy_rock, 4× super_potion |
+| Verdant Jungle | Tangrowth | 35 | 8× pecha_berry, 2× exp_candy_m |
+| Highland Meadows | Cinderace | 40 | 3× icy_rock, 4× super_potion |
+| Westmarch | Carbink | 30 | 8× pecha_berry, 2× exp_candy_m |
+| Southwold | Sigilyph | 23 | 6× great_ball, 4× exp_candy_s |
+| Deep Sea | Kingdra | 55 | 1× mystic_water, 3× exp_candy_m |
+| Deep Dark | Dusknoir | 65 | 3× icy_rock, 2× exp_candy_l |