FragmentWorld

< FragmentWorld - What's New Since v1.0.0 >

``` IT IS RECOMMENDED YOU DELETE YOUR OLD FRAGMENTWORLD WORLD AND THE PLUGIN FOLDER

v1.0.0 shipped the skeleton: void world generation, fragment discovery,
Cores, passive Energy, and the basic commands. This update adds the two
biggest systems from the original design doc **Guardian bosses** and
**biome decoration**  plus a handful of smaller additions and a build
target change. Nothing in v1.0.0 was removed; everything below is additive.

---

<!> 1. Guardian Bosses

The headline addition. Epic and Legendary fragments are no longer free
claims each one is now defended by a Guardian, and you have to beat it
before you can activate its Core.

<!> How it works

- Attempting `/fragment claim` on an eligible fragment now **awakens its
  Guardian** instead of claiming it outright. The Core stays locked while
  the Guardian is alive(epic and legendary fragments).
- Guardians are tracked per-fragment in SQLite, so a defeated Guardian
  stays defeated permanently  you only have to win the fight once.
- Killing a Guardian pays the killer a one-time Fragment Energy bonus on
  top of unlocking the claim.
- The whole system can be switched off server-wide with `bosses.enabled:
  false` in `config.yml` if you'd rather Epic/Legendary fragments stay
  free claims.

<!> Vanilla-only, Bedrock-safe, on purpose

Every Guardian is a **boosted vanilla mob**  no custom entity types, no
CustomModelData, nothing that needs a resource pack. Stats (health,
attack damage) are scaled up via the standard attribute system, and
abilities are built entirely out of vanilla building blocks: potion
effects, area-effect clouds, particles, sounds, boss bars, and vanilla
mob summons. The point is that a fight looks and plays exactly the same
whether you're on Java or connecting through Geyser on Bedrock.

<!> The 14 archetypes

One Guardian family per biome group, covering all 41 fragment types:

| Biome family | Guardian | Vanilla base | Signature ability |
|---|---|---|---|
| Forests (Oak/Birch/Dark Oak/Cherry/Flower) | The Bramble Colossus | Ravager | Roots a player in place with Slowness + negative Jump Boost |
| Savanna | The Savanna Warlord | Piglin Brute | War cry self-buff (Strength) |
| Desert / Badlands | The Sunscorched Husk | Husk | Sandstorm blindness + short-range "mirage" teleport |
| Snow / Igloo | The Frostbound Stray | Stray | Blizzard slow-field; summons extra Strays when enraged |
| Mountains | The Cragbound Colossus | Iron Golem | Seismic knockback slam; self-buffs Resistance when enraged |
| Swamp / Mangrove | The Bog Wretch | Witch | Its full vanilla potion-throwing/self-healing kit, boosted, plus a poison area cloud |
| Ocean / River / Ocean Monument / Shipwreck | The Void Leviathan | Elder Guardian | Native laser beam + Mining Fatigue curse, plus a tidal knockback pulse; summons extra Guardians when enraged |
| Mushroom Island | The Fungal Behemoth | Zombie | Poison spore bursts; summons zombie "spore spawn" when enraged |
| Lush Cave / Dripstone Cave | The Hollow Stalker | Enderman | Blink-strikes behind the lowest-health nearby player |
| Deep Dark / Ancient City | Warden Prime | Warden | Untouched vanilla Warden kit (sonic boom, sniff, dig, roar) — it was already a complete boss moveset |
| Village / Pillager Outpost / Woodland Mansion | The Forgotten King | Vindicator | Weakening battle cry; summons Pillager reinforcements when enraged |
| Stronghold / Trail Ruins / Trial Chamber / Mineshaft / Dungeon | The Ancient Golem | Iron Golem | Knockback slam; self-buffs Resistance when enraged |
| Nether family (Crimson/Warped Forest, Basalt Delta, Soul Sand Valley, Nether Fortress, Bastion, Ruined Portal) | The Storm Phoenix | Blaze | Native flight + fireballs; "rises from its own ashes" at 50% HP (self-heal burst + Fire Resistance + Speed) |
| End family (Outer Islands, End City, Chorus Forest, Dragon Shrine) | The Crystal Titan | Shulker | Native homing Levitation bullets; summons an extra Shulker when enraged |

<!> Fight mechanics

- **Boss bars** track health and follow anyone within 60 blocks.
- **Enrage** triggers once at 40% HP with a broadcast warning, a growl,
  and a flame burst  followed by an archetype-specific payoff (extra
  adds, a self-buff, or the Phoenix's signature rebirth moment).
- Abilities run on independent cooldowns per boss instance, so a
  Guardian's kit feels varied over the course of a fight rather than
  spamming one move.

---

<!> 2. Biome Decoration

Fragments used to be flat blocks of one or two materials. Now 23 of the
"planted" fragment types get a full decoration pass on top of their base
terrain, so they read like actual Minecraft biomes instead of colored
platforms.

Covered: all forest variants, flower forest, savanna, badlands, desert,
snow, mountains, mangrove, swamp, ocean, river, mushroom island, lush
cave, dripstone cave, and the full Nether and End families (crimson/
warped forest, basalt delta, soul sand valley, chorus forest, outer
islands). Built structures (villages, strongholds, dungeons, nether
fortresses, etc.) are deliberately left bare they're meant to read as
ruins, not overgrown biomes.

<!> What each decorated fragment can now generate:

- **Native trees** correct species per biome (oak, birch, dark oak,
  cherry, acacia, spruce, mangrove, plus crimson/warped "fungus trees"
  using real vanilla huge-fungus cap blocks, and chorus plants on End
  fragments), with a rounded, corner-clipped canopy for a less blocky
  silhouette.
- **Native foliage** short grass, ferns, seagrass, kelp, sugar cane,
  crimson/warped roots, nether sprouts matched to the biome that
  actually grows them in vanilla.
- **Correct flowers** real per-biome flower tables, not a generic
  mix. Flower Forest gets the full vanilla bouquet (dandelion, poppy,
  allium, all four tulip colors, oxeye daisy, cornflower, lily of the
  valley); Swamp gets blue orchid; Cherry Grove gets pink petals.
- **Mushrooms where appropriate** forests, dark forest, swamp, and
  lush caves get small mushrooms; Mushroom Island gets an actual giant
  mushroom "tree" built from the real vanilla mushroom-block caps.
- **Boulders and fallen logs** species-correct logs lying flat with
  real block orientation (not floating cubes), plus stone, mossy
  cobblestone, dripstone, or basalt boulder clusters depending on biome.
- **Ground detail** patchy variation instead of one flat material:
  coarse dirt and podzol in forests, gravel/andesite on mountains, moss
  in lush caves, mud in swamps and mangroves, packed ice in snow, red
  sandstone/terracotta in badlands, and so on.

**Generation order matters here**: decoration for a fragment now runs in
a second pass, strictly after that fragment's terrain is fully painted.
That guarantees a tree, fallen log, or boulder never gets silently
overwritten by a neighboring column's terrain being painted afterward
a real risk once features started spanning more than one column.

---

<!> 3. Smaller additions

- **`/fragment tp` and `/fragment leave`** jump straight into the
  fragment world for testing and back to exactly where you were, without
  needing a separate teleport plugin.
- **`bosses.enabled`** config toggle.
- **New SQLite table** (`fragment_bosses`) tracking which fragments'
  Guardians have been permanently defeated.


<!> What's still not in yet

Unchanged from the v1.0.0 roadmap: world events (Meteor Shower, Void
Storm, etc.), Bridge/Sky Rail/Airship travel tech, and the Heart Fragment
endgame. Fragment Energy still only accumulates besides the one-time
Guardian-kill bonus, there's nothing to spend it on yet. That's the next
planned pass: Energy sinks (Teleport Gates, an "awaken Guardian" cost)
paired with whatever comes after bosses.