Guardian boss bars; Phase 7 approved

Adrian, 2026-11-03: guardians get a boss health bar like the Wither's, which
also leads players to them. Every player within 128 blocks of a living
guardian sees a red bar of their own (GuardianBars): name, zone, how many
blocks away, and HP. The End boss keeps the dragon's bar.
guardian_appears_and_returns checks the bar appears and goes once beaten.
Self-tests and the island check pass.

Phase 7 approved ("Then begin with the next phase"); README status updated.

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

docs/balance.md

@@ -42,6 +42,7 @@ Every tunable lives in a config file or in this table. **Placeholder** means gue
 | End spawns | the End is a zone, Lv 50–70; Cobblemon's End lines spawn there (Beheeyem, Reuniclus, Metagross; Gothitelle and Sigilyph in End cities; Malamar and Unown with a Poké Snack), all in the common bucket, each line's heaviest entry weight 10, Metagross 2 | Placeholder | `world/zones.json` → `dimensions` (`levels`, `bucket`, `line_weight`, `rare_factor`), then `tools/zone_layout.py` and `tools/zone_spawns.py` | Adrian, 2026-11-02: the End was barren; Lv 50–70 his pick |
 | Boss size | guardians about 8 blocks tall (Morpeko 4.9 at the 12× cap, Moltres 8, Regigigas 9.8 at the 1.5× floor); Eternatus 15 blocks; a cave guardian's spot needs that much air above it, else the roomiest floor within 24 blocks | Placeholder | `tools/zone_spawns.py` (`GUARDIAN_HEIGHT`, `GUARDIAN_SCALE_MIN`, `GUARDIAN_SCALE_MAX`), `tools/zone_bosses.py` (`END_HEIGHT`) | Adrian, 2026-11-02: way bigger. Area attacks that start at the boss reach half its width further |
 | Boss toughness | perfect IVs and 170 EVs each in HP, Defense and Sp. Def (510, the games' limit), nothing in Attack, Sp. Atk or Speed; in battle the Guardian's Ward: Defense and Sp. Def ×2 while defending, and one attack (all hits of a multi-hit move together) takes at most 25 % of max HP | Placeholder | `BossToughness.EVS`; `datapacks/core/data/cobblesurvival/held_items/guardiansward.js` (`DEF_FACTOR`, `SPD_FACTOR`, `HP_SHARE`) | Adrian, 2026-11-02: tougher, not stronger; the 25 % cap is his number. Applies to guardians, the End boss and practice copies |
+| Guardian boss bar | shown to each player within 128 blocks of a living guardian, updated every half second: name, zone, distance in blocks, HP | Placeholder | `GuardianBars.RANGE` | Adrian, 2026-11-03: like the Wither's, and it leads players to the guardian |
 | Machine look | a working core glows (light 10), its front animates (8 frames, 3 ticks each) and particles show; it keeps looking busy 2 s after the work stops; the Pokémon inside flinches (red flash, hit sound, no damage) about every 15 s while it works | Placeholder | `MachineBlock.ACTIVE_LIGHT`, `tools/machine_assets.py` (`FRAMES`, `FRAME_TICKS`), `MachineEffects` (particle and sound chances), `MachineBlockEntity` (`ACTIVE_LINGER`, `FLINCH_ONE_IN`) | Adrian, 2026-11-02. Working means: a heated furnace has something to cook, the generator isn't full, the synthesizer gets energy, a rebirth runs, the altar holds a Pokémon |
 | Level pressure | full experience up to 5 levels above the zone's band, then 10 % less per level, at least 10 % (Exp. Candy and commands exempt) | Decided (Adrian, 2026-10-30) | `world/zones.json` → `level_pressure` | E.g. on Button Isle (up to Lv 10): Lv 15 full, Lv 20 half, Lv 24+ a tenth |
 | Strong flyer | ridable through the air with top speed ≥ 60 or top stamina ≥ 85 (Cobblemon ride stats) | Decided (Adrian, 2026-10-30) | `tools/zone_spawns.py` (`STRONG_FLYER_*`) | 29 species |

docs/checklists/phase-7.md

@@ -11,6 +11,7 @@
 - **Arena:** leaving it (24 blocks; Basalt 32; End 40) or dying ends the battle as lost; the boss heals and stays. Automated: `boss_arena_leaving_loses`.
 - **The End:** the Ender Dragon is gone; Eternatus appears on the main island, with the dragon's boss bar; beating it opens the exit portal and gateway, leaves the egg the first time and gives experience. Automated: `end_boss_replaces_the_dragon`.
 - **Big and tough bosses** (Adrian, 2026-11-02): guardians stand about 8 blocks tall, Eternatus 15. Only HP, Defense and Sp. Def are raised (training, and the Guardian's Ward in battle doubles Defense and Sp. Def); no single attack takes more than a quarter of their HP. Guardians already in your world grow on the next check. Automated: `practice_bosses_spawn`, `boss_takes_a_quarter_per_attack`.
+- **Guardian boss bars** (Adrian, 2026-11-03): within 128 blocks of a guardian you see a red bar like the Wither's: its name, its zone, how many blocks away it is (which leads you to it) and its HP. Automated in `guardian_appears_and_returns`.
 - **End spawns:** the End is a zone (Lv 50–70) with Cobblemon's End lines: Beheeyem, Reuniclus, Metagross; Gothitelle and Sigilyph in End cities; Malamar and Unown with a Poké Snack. Automated: `end_has_spawns`.
 
 ## In game (Prism instance)
@@ -25,9 +26,12 @@ On the island save (or a new one), in creative or survival:
 - [ ] Find Regigigas in a Deep Dark cave and Moltres in the Basalt Furnace.
 - [ ] Go to the End: Eternatus is huge now (15 blocks). Fight it: no attack takes more than a quarter of its HP bar, even a super-effective one; it needs at least four hits. Its attacks are as strong as before.
 - [ ] Visit a guardian (`/cobblesurvival boss <zone>` spawns a practice copy next to you): about 8 blocks tall; Regigigas and Moltres stand in caves with room above them.
+- [ ] Walk towards a guardian's zone: within 128 blocks a red bar appears at the top ("Pinsir, guardian of Southwold (84 blocks away)"); the number drops as you get closer. In the fight the bar shows its HP; once it's beaten the bar goes.
 - [ ] Walk around the End's islands for a minute: Beheeyem, Reuniclus and now and then Metagross appear, Lv 50–70 (`/cobblesurvival zone` shows "The End").
 
 ## Ask Adrian
 
+**Phase 7 approved 2026-11-03** ("guardians should have a boss healthbar, like a wither … Then begin with the next phase"; the bar was built first).
+
 - Do the attacks feel dodgeable but dangerous? All numbers are placeholders (`docs/balance.md`).
 - Swap Moltres → Groudon, Eternatus → Giratina, Regigigas → Meloetta when Cobblemon adds their models? (one word each in `world/zones.json` / `tools/zone_bosses.py`)

docs/design.md

@@ -294,6 +294,8 @@ Self-tests (`BossTests`): every guardian has a fight and a Cobblemon model; each
 
 **Bosses are big and tough, not strong** (Adrian, 2026-11-02: Eternatus was too small and too easy; guardians should be way bigger and tougher; only defensive stats go up, never Attack or Speed; no single attack may take more than a quarter of a boss's HP). Every boss (guardian, End boss, practice copy) is scaled to stand about 8 blocks tall (Eternatus 15; `tools/zone_spawns.py`, `tools/zone_bosses.py`) and gets perfect IVs and 170 EVs each in HP, Defense and Sp. Def, nothing offensive (`BossToughness`). In battle it brings the **Guardian's Ward**, a held item that exists only inside Cobblemon's battle engine (Showdown): Cobblemon loads it from `datapacks/core/data/cobblesurvival/held_items/guardiansward.js`, and the companion mod hands it to every boss ahead of whatever it holds, so it can't be stolen, knocked off or suppressed. It starts a lasting condition that doubles Defense and Sp. Def while the boss defends (not for Body Press) and caps one attack, all hits of a multi-hit move together, at a quarter of the boss's max HP. Guardians and an Eternatus already standing in a world grow and get their training on the next check outside battle; a cave guardian moves to a spot it fits in. Area attacks that start at the boss (rings, lines, cones) reach half its width further, so a big boss's ring starts at its edge. Self-tests: `practice_bosses_spawn` (size, training, full health) and `boss_takes_a_quarter_per_attack` (a real battle: a Lv 100 Garchomp's Bullet Seed, every hit enough to knock out the Lv 15 boss, takes exactly a quarter per use).
 
+**Guardian boss bars** (Adrian, 2026-11-03: a boss health bar like the Wither's, which also leads players to the guardian). Every player within 128 blocks of a living guardian sees a red bar of their own (`GuardianBars`): the guardian's name, its zone and how many blocks away it is, and its HP, which falls in battle. Walking around, the number tells players whether they're getting closer; no other hint (Adrian, 2026-11-02). The End boss keeps the dragon's bar.
+
 **The End has Pokémon** (Adrian, 2026-11-02: it looked barren). The End is a zone of its own, "The End", Lv 50–70 (`world/zones.json` → `dimensions`; `Zones.at` returns it anywhere in the End). Every line Cobblemon spawns in End biomes spawns there too, on top of its home on the island: Beheeyem, Reuniclus and Metagross anywhere; Gothitelle and Sigilyph in End cities; Malamar and Unown with a Poké Snack. Gothita had no island home (it only spawns in the End), so it's new. Cobblemon has all of these uncommon or rare, and it rolls the bucket before the Pokémon, so in the End they move to the common bucket or the End would stay nearly empty; each line weighs the same, Metagross a fifth. Being a zone, the End also has level pressure (full experience up to Lv 75, like the Basalt Furnace) and the wild-Pokémon cleanup above Lv 80; Eternatus is exempt as an uncatchable boss. Self-test `end_has_spawns`.
 
 ## Open decisions for Adrian (proceeding with the default, flagged)