WIP: Earth Labyrinth dungeon and Earth Guardian

ASSET_CREDITS.md

@@ -63,4 +63,8 @@ Asset License. Minecraft and the Wildfire texture are copyright Mojang Studios/M
 
 The Aender portal references the installed `minecraft:block/nether_portal` texture and creates a green sprite at resource-load time. Retold does not package a copied or modified Minecraft portal texture.
 
+The provisional Earth Guardian renderer references Minecraft's installed Iron Golem model and
+texture at runtime, and its spawn-egg definition references the installed Iron Golem Spawn Egg
+model. Retold packages no copied or modified pixels for this placeholder presentation.
+
 If an asset's authorship, source, license, or status is unclear, do not redistribute or reuse it separately. Contact the developer first.

README.md

@@ -19,7 +19,7 @@ Retold is independently developed and is not an official Minecraft product or so
 ## What Retold Changes
 
 - **Connected progression:** defeating the Ender Dragon changes the world instead of ending the game.
-- **Element paths:** Water and Air lead through the ocean monument and Air Temple, while boss-tier Stage 2 Wildfires provide the Nether Reactor Core for Fire. Earth remains planned.
+- **Element paths:** Water and Air lead through the ocean monument and Air Temple, boss-tier Stage 2 Wildfires provide the Nether Reactor Core for Fire, and newly generated Jungle Pyramids contain the initial Earth Labyrinth and a blind Earth Guardian that permanently reshapes terrain and turns remembered vibration locations into ceiling collapses, real lava pools, or collapsing floors. The guardian drops Lodestone for the six-sacrifice egg ritual, while dark side branches contain traps and occasional treasure.
 - **The Aender:** a bright, unstable late-game dimension that replaces normal survival End progression after the dragon egg ritual.
 - **Living mobs:** hunger, homes, ranges, factions, territory, hunting, fleeing, warnings, and group behavior.
 - **Discovery-first crafting:** recipe knowledge and villager teaching replace a recipe-book-first experience.
@@ -56,7 +56,7 @@ Only the locations linked above are official downloads. Version settings are def
 The current build includes the survival spine, Water and Air progression, staged world changes, Aender foundations, recipe discovery, and the Retold mob-behavior framework. Major unfinished areas include:
 
 - wider seed, upgraded-world, server, and multiplayer verification of the cartographer Air Temple map, plus further Gale Core tuning
-- the Earth element path and natural-world Wildfire presentation/balance verification
+- Earth Labyrinth trap/treasure room tuning, guardian final presentation, and natural-world maze/vibration/combat/terrain-shaping and six-sacrifice progression verification, plus Wildfire presentation/balance verification
 - original replacements for provisional Aender assets and naming
 - Aender travel networks and late-game rewards
 - broader progression, combat, village, and world-generation work

ROADMAP.md

@@ -13,8 +13,10 @@ This concise public roadmap may change as features are designed and tested. Deta
 
 ## Next
 
-- Design and implement the Earth path around a custom terrain-building guardian and the current working Lodestone sacrifice.
-- Complete the intended six-sacrifice Dragon Egg ritual in any order once the Earth path is survival-obtainable.
+- Build on the generated Earth Labyrinth and its vibration-investigating, terrain-relocating
+  persisted Earth Guardian: verify and tune the initial trap/treasure side rooms, natural dark-area
+  spawns, environmental hazards, and Lodestone reward.
+- Verify the six-sacrifice Dragon Egg ritual in any order, including upgraded worlds and multiplayer.
 - Verify and tune the implemented Life path around Evokers and Totems of Undying and the Death path around the Wither and Nether Star.
 - Add Aender in-dimension transportation and meaningful late-game building or travel rewards.
 - Audit survival removal or replacement of incompatible modern structures and progression.
@@ -30,8 +32,8 @@ See [`docs/element-ritual.md`](docs/element-ritual.md) for the current ritual, a
 ## Open Decisions
 
 - Whether Stage 1 should require the Wither or a Nether Star before End access, given the Nether Star's intended Stage 2 Death-sacrifice role.
-- Whether Lodestone remains the final Earth sacrifice.
 - The final roles of Nether and Aender dragons.
-- Whether pyramid boss tombs, a world ending, or New Game+ belong in Retold.
+- Whether Desert Pyramids or additional structures should receive boss tombs beyond the confirmed
+  Jungle Pyramid Earth Labyrinth, and whether a world ending or New Game+ belongs in Retold.
 
 Focused proposals are welcome through the [suggestion form](https://github.com/xefensor/Retold/issues/new?template=suggestion.yml). Explain the player-facing problem and how the proposal supports Retold's design pillars.

docs/design-overview.md

@@ -36,7 +36,11 @@ The Aender is the dimension of change: an unstable, bright, strange, and dangero
 2. **Stage 2:** defeating the dragon makes the world more dangerous and begins the Dragon Egg ritual built around four classical elements plus Life and Death.
 3. **Stage 3:** completing the ritual hatches the egg, redirects normal End access to the Aender, and begins returning the Nether toward balance.
 
-The intended ritual uses six consumed artifacts: Heavy Core (Air), Heart of the Sea (Water), Nether Reactor Core (Fire), Lodestone (Earth), Nether Star (Death), and Totem of Undying (Life). Air, Water, Life, and Death currently control hatching; the implemented Fire offering is recorded but remains outside that threshold until the unfinished Earth path makes all six obtainable. See [`element-ritual.md`](element-ritual.md) for the current guardian and encounter direction.
+The intended ritual uses six consumed artifacts: Heavy Core (Air), Heart of the Sea (Water), Nether
+Reactor Core (Fire), Lodestone (Earth), Nether Star (Death), and Totem of Undying (Life).
+All six now control hatching. The Earth Guardian supplies Lodestone, while side branches contain
+initial arrow traps and treasure with no added lights or spawners. See [`element-ritual.md`](element-ritual.md) for the generated Jungle Pyramid labyrinth,
+persisted guardian lifecycle, blind terrain relocation, and implemented environmental combat direction.
 
 ## The Aender
 

docs/element-ritual.md

@@ -1,6 +1,6 @@
 # Dragon Egg Ritual And Sacrifices
 
-> Current design direction as of 2026-08-19. This document records the intended player-facing design; several parts are not implemented yet.
+> Current design direction as of 2026-09-07. This document records the intended player-facing design; several parts are not implemented yet.
 
 ## Role In Progression
 
@@ -13,11 +13,14 @@ The ritual uses **six artifact sacrifices**. Four represent the classical elemen
 | Air | **Heavy Core** | **Gale Core** | Air Temple / Gale Core path exists and now rewards the Heavy Core. |
 | Water | **Heart of the Sea** | **Elder Guardian** | Ocean Monument / Elder Guardian path exists and now rewards the Heart of the Sea. |
 | Fire | **Nether Reactor Core** | **Wildfire** | Initial path implemented: a rare Stage 2+ Nether guardian roams, attacks undead, and guarantees the core. |
-| Earth | **Lodestone** | **Custom Earth Guardian** | Working item choice. The guardian's defining mechanic is terrain construction: it places/builds blocks between itself and the player, forcing the player to mine through its defenses. |
+| Earth | **Lodestone** | **Custom Earth Guardian** | Confirmed Jungle Pyramid labyrinth path. The blind guardian permanently excavates and relocates any loaded block while following players inside or outside the structure. |
 | Death | **Nether Star** | **Wither** | The Wither is the Death-associated challenge and the Nether Star is its sacrifice. |
 | Life | **Totem of Undying** | **Evoker** | The Evoker/Totem connection matches Retold's existing illager lore around avoiding death. |
 
-The **Nether Reactor Core** is the confirmed Fire artifact. The **Lodestone** remains a working Earth choice and may still change.
+The **Nether Reactor Core** is the Fire artifact, and **Lodestone** is the confirmed Earth artifact.
+The Earth Guardian drops one Lodestone through its entity loot table (subject to normal mob-loot
+rules). The ordinary Lodestone recipe and new Ruined Portal/Bastion Bridge chest Lodestones are
+removed. Existing stacks remain valid; datapacks can deliberately override these acquisition rules.
 
 ## Ritual Rules
 
@@ -65,9 +68,96 @@ need in-game verification.
 
 Earth uses a new Retold mob rather than repurposing an existing Minecraft boss.
 
-Its defining combat behavior is **building with the terrain**. The guardian creates block barriers and defenses between itself and the player. Reaching it requires the player to mine through those defenses, making mining itself a central part of the encounter rather than using an ordinary combat boss with an Earth visual theme.
-
-The current Earth sacrifice is the **Lodestone**. The guardian's final name, appearance, location, exact block-placement rules, and acquisition flow are still to be designed.
+Every newly generated Jungle Pyramid contains a deterministic, seed-randomized **Earth
+Labyrinth** beneath it. Solving the pyramid's existing lever puzzle reveals the staircase into the
+maze. Already-generated Jungle Pyramids remain untouched; upgraded worlds must explore newly
+generated terrain to find the enhanced structure. The implemented footprint is 77 or 101 blocks
+wide across two connected levels. The upper maze floor lies 64 blocks below the pyramid
+base, and the lower floor lies another fourteen blocks down. A long walkable switchback staircase
+connects the secret room to the fixed entrance; the maze has a fixed central guardian chamber,
+multiple stairs, loops, alternate routes, and randomized trap/treasure side branches. Additional
+puzzle or combat-room systems are not part of the confirmed room direction.
+
+The labyrinth should read as an ancient cave network that was cut, reinforced, and occupied rather
+than as a regular block-built grid. Its implemented base geometry offsets junctions from their
+logical cells, bends connecting tunnels through deterministic intermediate points, and uses
+separated rough tunnels, irregular junction caverns, and a depth-aware Stone, Deepslate, Andesite,
+and Tuff palette. Cobblestone and Mossy Cobblestone are limited to ruined structural accents and
+the access stairs.
+
+Before Stage 2, the guardian is an immovable, indestructible ancient jungle stone statue in the
+central chamber. It has no AI, boss bar, damage, knockback, pushing, or portal movement. Reaching
+Stage 2 makes it eligible to awaken, but it remains dormant until a player returns to the chamber.
+Its persisted encounter lifecycle is `DORMANT → AWAKENING → ROAMING/COMBAT → DEFEATED`. A defeated
+labyrinth remains permanently cleared and its guardian does not respawn.
+
+The guardian is blind. It patrols and navigates through its knowledge of the labyrinth while mining,
+movement, block placement, containers, projectiles, explosions, direct damage, and very close
+ground contact provide differently weighted vibration clues. Sneaking reduces movement noise, and
+the guardian investigates a remembered vibration position instead of receiving perfect awareness
+through walls. In multiplayer it chooses among actual vibration sources rather than automatically
+knowing every player's position.
+
+Its defining combat behavior is **permanently reshaping the world around it**. The guardian can
+excavate any non-air block in a loaded chunk to create paths for itself, retains the removed block
+state as a bounded reserve, and relocates that material into persistent barriers elsewhere. There
+is no labyrinth boundary or block whitelist: player builds, containers, puzzle mechanisms, block
+entities, fluids, and normally indestructible blocks such as Bedrock are all valid. Every edit still
+obeys `mobGriefing`, NeoForge's entity-griefing hook, and `RetoldWorldProtection`, allowing server
+administrators and claim integrations to disable it. Relocation rather than unlimited creation
+avoids an infinite block farm while leaving a permanent physical record of the encounter.
+
+The guardian's final model and palette still need design approval. Side branches now receive up to
+six content rooms per floor: pressure-plate arrow traps and occasional treasure chests. Rooms add
+no lighting or spawners; normal darkness, biome, difficulty, distance, and mob-cap rules govern
+natural mobs. Loot and finite dispenser ammunition use Retold-owned loot tables. Content version 1
+is saved on new starts; older starts retain empty rooms, including their not-yet-generated chunks.
+The initial implementation replaces new Jungle Pyramid starts
+with a compatible composite structure under the same registry id, attaches a serialized labyrinth
+piece, and places the deterministic two-level maze, safe secret-room staircase, carved cave
+tunnels, irregular junction caverns, and ladder connections using a provisional natural-stone
+palette. It now registers `retold:earth_guardian`, spawns exactly one structure-owned guardian at
+the fixed chamber, and persists `DORMANT`, `AWAKENING`, `ROAMING`, and `DEFEATED` encounter state.
+The guardian is an immovable, indestructible Stage 1 statue; a Survival player entering its chamber
+in Stage 2 starts a three-second awakening and reveals its boss bar. The current Iron Golem model
+and texture are code-level placeholders. After awakening, it uses Minecraft's vibration system to
+patrol and investigate weighted remembered player clues without acquiring a sight target; the clue
+and listener state survive reloads. Vibration clues may originate outside the maze. While pursuing
+one, its terrain controller batches permanent changes: it excavates any loaded
+non-air block into a persisted 128-state reserve and later spends that exact material on an
+entity-clear barrier behind it. When ordinary navigation stops, a short route builder clears
+three-wide body passages and constructs one-block ramp steps with longer landings, using only
+solid full-block states from its reserve for support. It retains its 3.2-block height and physically
+walks the carved route. Uphill/downhill heading persists across reloads; short work segments are
+recomputed from the actual position, and player edits can invalidate and rebuild them. Excavation
+and backfill share a budget of up to 12 changes every ten ticks (half a second). Once a segment
+is walkable, spare budget can build a supported 3×3 wall three to six blocks behind the guardian,
+at most once every forty ticks. Walls require at least 18 stored states and consume only solid
+full-block states, leaving material for subsequent traversal; occupied and protected cells stay empty.
+There is no block-type, ownership, or labyrinth-bound restriction on excavation;
+only `mobGriefing`, NeoForge's entity-griefing hook, and Retold world protection can deny an edit.
+Once roaming, it becomes damageable and aggressively closes on heard positions. At contact range
+it can strike the heard Survival player with its Iron Golem attack, at most once every 30 ticks.
+A fresh obstruction check prevents wall hits, and Creative/Spectator players remain excluded.
+Pursuit is one-third faster than the initial investigation pass and continues during environmental
+warnings; reaching a clue no longer discards it before contact combat. No live sight target is acquired.
+A remembered vibration within 24 blocks marks the floor for a
+30-tick environmental warning. The guardian cycles through pulling up to five real blocks out
+of a valid ceiling as damaging falling debris, turning a 3×3 layer of ground beneath the marked
+position into real lava sources, and opening a 3×3 pit up to four blocks deep. The pit remains in the
+world and causes ordinary falling and landing damage; protected blocks stop excavation in their
+column. Creatures left above the lava patch fall into lava and take normal
+Minecraft contact damage; the attack adds no scripted damage or launch. Ceiling dust identifies the actual blocks
+being loosened, and every selected block must have an empty vertical fall path to the marked area.
+If no protected-safe, unobstructed ceiling block exists, the collapse falls back to the eruption.
+The location does not follow the player after the warning
+begins, so dodging remains possible without giving the blind guardian sight-like tracking. The
+cooldown, selected hazard, target, and pending warning persist across save/load. Ceiling removal
+uses the normal entity-griefing and Retold world-protection policy; lava conversion checks both break
+and place permission. Lava sources persist and can flow, burn surroundings, and affect any creature
+according to ordinary Minecraft rules. The initial trap/treasure rooms, Lodestone reward, and
+six-offering ritual are implemented; natural-world generation, balance, reward retrieval around
+lava, multiplayer progression, and final presentation still require verification.
 
 ### Death — Wither
 
@@ -85,19 +175,19 @@ connection. The Dragon Egg now accepts and consumes the Totem as the Life offeri
 The broader Life-path encounter presentation remains open design work; the accepted artifact and
 its Evoker source are now implemented.
 
-## Implementation Gap
+## Implementation Status
 
-The current implementation is intentionally behind this design:
+The initial acquisition paths and six-sacrifice gate are wired:
 
 - `RetoldRitualOffering` reserves stable saved-state bits for all six sacrifices.
-- The Dragon Egg accepts Heavy Core, Heart of the Sea, Nether Reactor Core, Totem of Undying, and
-  Nether Star, consumes successful offerings, and rejects duplicates without consuming them.
+- The Dragon Egg accepts Heavy Core, Heart of the Sea, Nether Reactor Core, Lodestone, Totem of
+  Undying, and Nether Star, consumes successful offerings, and rejects duplicates without consumption.
 - The legacy `WATER_ELEMENT` and `AIR_ELEMENT` items remain accepted but are no longer encounter
   rewards or Creative-tab progression entries.
-- The temporary hatch threshold is Water, Air, Life, and Death so Stage 3 remains
-  survival-obtainable while the other acquisition paths are unfinished.
-- Fire is accepted and persisted but is not yet required for hatching. Earth is represented in
-  saved ritual state but is not yet accepted or required.
-
-Implementation should turn on the complete six-sacrifice hatch requirement only when Earth is
-survival-obtainable.
+- All six are now required, in any order. Old offering bits retain their meanings; unfinished
+  Stage 2 worlds must supply their missing Fire/Earth artifacts. Worlds already in Stage 3 stay there.
+- Existing generated vanilla pyramids gain no labyrinth; existing Retold labyrinth guardians can
+  drop the newly wired reward, while new room content requires a newly generated structure start.
+  Previously defeated guardians stay defeated; those worlds need another encounter for Lodestone.
+- Natural encounter balance, multi-seed/chunk-border generation, and dedicated multiplayer and
+  upgraded-world end-to-end progression still need verification.