AOE – EPOCHEN-WANDEL / AGE OF ELEMENTS

Was AOE wirklich macht
AOE ist kein reines Mob-Pack, sondern ein konfigurationsgetriebenes Survival-Framework fuer Spigot/Paper (API 26.1): Epochen, Spielerphysiologie, Weltveraenderung, monumentale Strukturen, Dungeons mit Wellen und Traps, Legendary-Endgame, Setup-Wizard, Live-Feedback und vollstaendige Lokalisierung. Fast alles laesst sich ueber YAML justieren, sodass du Druck, Tempo und Risiko pro Server, Profil oder Event anpassen kannst, ohne neu zu kompilieren.

Epochen-Zyklus und Zeitlogik

• Vier Epochen: DROUGHT (Hitze/Trockenheit), FLOOD (Wasser/Regenlogik), ICE_AGE (Kaelte/Isolation), OVERGROWTH (Vegetation/Besiedlung). Jede Epoche hat eigene Spieler-Stat-Deltas in configs/stats.yml (Hydration/Temperatur pro Situation: Sonne, Wasser, Basiswerte usw.).
• Zykluslaenge, Warnfenster und Uebergaenge steuern ueber configs/epochs.yml und zentrale Services: Epochenwechsel mit Broadcasts, Persistenz und konsistentem State, damit Restarts und Reloads keine "haengenden" Welten erzeugen.
• /aoe status, /aoe next, /aoe set, /aoe advance geben Admins kontrolliertes Steuerungswerkzeug; Spieler sehen den Lauf gleichzeitig im Epochenmonitor-GUI und optional in der Actionbar/Bossbar je nach Feedback-Konfiguration.

Spielmodi und Konfliktprofil

• ALLIANCE: kooperativer Fokus, weniger harter PvP-Zwang, staerkeres Umwelt- und Ressourcenmanagement als Konfliktquelle.
• RESOURCE_WAR: PvPvE mit aktivem Ressourcenwettbewerb; Strukturen und Begegnungen wirken insgesamt riskanter.
• HYBRID: gemischte Regeln, die sich an die Epoche anbinden (siehe configs/modes.yml fuer feine Schalter wie PvP-Fenster je Saison).
• Der Modus beeinflusst nicht nur Text, sondern Gewichtung von Events, Risikoempfinden und typischer Rundenlaenge – alles serverseitig nachjustierbar.

Spielerstatus: Hydration, Temperatur, Live-HUD

• Permanenter Lauf: Hydration und Temperatur werden im Tick-Service aktualisiert und sind kein Einmal-Command-Feature. configs/stats.yml enthaelt globale Multiplikatoren und epochenspezifische Tabellen, damit Drain/Gain tick-normalisiert bleibt (unterschiedliche stats-interval-ticks aus dem Profil skalieren Werte automatisch).
• Live-HUD: Layouts compact, detailed, minimal ueber configs/stats.yml -> hud.layout; Bossbar-basierte Anzeige folgt der Spielersprache und aktualisiert sich mit Saison und Werten.
• Trinken: Konsum einer Wasserflasche gibt einen klar definierten Hydration-Schub (Plugin-intern balanciert) – wichtig fuer Duerre- und Hitze-Szenarien ohne extra Commands.
• Waermequellen: Lagerfeuer (inkl. Seelen-Lagerfeuer), Ofen, Hochofen, Raeucherofen, Lava und Lava-Kessel erhoehen die Temperatur situativ. Dazu gibt es Distanz-basierte Waerme: linear interpoliert zwischen Nah- und Fernradius (heat-linear-near-distance-blocks / heat-linear-far-distance-blocks mit Multiplikatoren), plus einen harten max-heat-gain-per-tick-Cap gegen Mikro-Stapel-Mikro-Exploits.
• Isolation: Leder-Ruestung und der Isolations-Mantel (Custom Item) reduzieren bzw. modifizieren Temperaturstress – Eis-Epoche kann Mantel-Bonus separat verstaerken (temperature-insulation-bonus in ICE_AGE).
• Konsequenzen: Grenzwerte loesen negative Effekte aus (Debuff-Logik); beim Verlassen von Struktur-Radien oder Dungeon-Reset werden Tags und Effekte hart bereinigt, damit keine "klebenden" Stat-Debuffs von Legendary/Dungeon-Zonen bleiben.
• Run-Start: resetForRunStart setzt faire Startwerte; Tutorial kann Hydration/Temperatur kurz neutralisieren (prepareForTutorial).

Permadeath-Lockout

• Permadeath fuehrt nicht in einen leeren Spectator-Modus: betroffene Spieler landen in einem geschuetzten Sky-Warteraum (Adventure-Regeln: kein Schaden, kein Hunger, kein PvP, kein Blocksetzen).
• Parkour-Segment und Hologramm zeigen die verbleibende Zeit bis zum naechsten Epochenwechsel; danach erfolgt automatische Rueckfuehrung in den Survival-Run.

Welt-Effekte (epochales Map-Design)

• configs/world-effects.yml steuert ein samples-per-tick-basiertes System: wie viele Bloecke pro Tick in welchem chunk-radius um Spieler herum mutiert werden duerfen (0 = nur Spielerchunk, 1 = 3x3-Feld – spuerbarer "lebende Karte"-Effekt).
• Pro Epoche eigene Wahrscheinlichkeiten: z. B. Duerre mit Versteppung, Holz-Zuendung, Rissbildung, Blattfall; Flut mit Wasser-Anstieg bis konfigurierbarem Y, Fackel-Ausloeschung, Ton-/Schlamm-Flips; Eis mit Schnee, Lavagefrieren, Kessel-Freeze; Overgrowth mit Ranken, Moos, Bluemchen, Creeper-Blutmond-Spawns – alles fein skalierbar.
• Globale Mini-Events in Spielernaehe (global-event-chance, Radius, Aktionsbudget) erzeugen zusaetzliche dramatische Momentchen ohne die ganze Map gleichzeitig zu flashen.

Strukturen, Loot, Silhouetten

• Hauptfamilien (Oasis, Scorched, Flood, Ice, Spore, Legendary Monolith) sind als Monumente lesbar: groessere Footprints, erweiterte Hoehen-/Neigungs-Checks, seltener aber hochwertiger Spawn.
• Biome-Styles wechseln Materialpalette (Default/Desert/Swamp/Snow); Bonus-Loot pro Stil ist voll datengetrieben (material, chance, amount, min/max, bonus-scale, amount-rounding).
• Loot-Sicherheit: mehrstufige Befuellung mit Backfill und Container-Repair, damit Truhen nicht leer bleiben, wenn andere Plugins oder Edge-Cases eingreifen.
• Silhouette-Lighting: nachts aktive Konturlichter (Redstone-Lampen + invertierte Daylight-Detector) machen Landmarken aus der Ferne lesbar; tagsueber dezenter – Schalter structures.silhouette-lighting.enabled.

Dungeon-System (Tunnel, Himmel, Wasser)

• Zusaetzlich zu normalen Strukturen: eigenes Dungeon-Subsystem mit drei Linien DUNGEON_TUNNEL, DUNGEON_SKY, DUNGEON_WATER (eigene Y-Bereiche, Gewichte, min/max Hoehen in configs/structures.yml).
• 20+ Archetypen (eigene Keys, Gewichte, Elite- und Wellen-Mobs, Trap-Typ). Jeder Archetyp ist einzeln aktivierbar und ueber Gewichtung mischbar.
• Wellen + Elites: konfigurierbare Wellenanzahl und Intervall; Elite mit HP-Bonus; elite-area-multiplier skaliert Elites getrennt nach Tunnel/Himmel/Wasser – feine Balance pro Dungeon-Linie ohne globales Nerven.
• Traps: Radius und Basisschaden konfigurierbar; Schaden skaliert mit Dungeon-Tier (siehe progression).
• Progression: tiers-by-season mappt jede Epoche auf Dungeon-Tier I–III. Pro Tier: wave-bonus (mehr Wellen), trap-damage-multiplier, elite-health-multiplier. Ergebnis: dieselbe Archetyp-Begegnung fuehlt sich in spaeteren Epochen deutlich bedrohlicher an.
• Cluster-Preset balanced | depth | sky | water | chaos: beeinflusst Archetyp-Gewichte (z. B. depth bevorzugt Tunnel-Dungeons); im Preset chaos wirken zusaetzlich Zufallseffekte auf die Meta.
• Eskalations-Warnung vor schwereren Wellen (Tier II ab Welle 2, Tier III ab Welle 3): Actionbar-Text, temporaere BossBar, Radius und Dauer konfigurierbar. Sounds und Partikel sind pro Cluster waehlbar: depth/sky/water folgt der physischen Dungeon-Linie; bei cluster-preset: chaos nutzt die Warnung das Chaos-Set (Tier-II-Sound zufaellig aus kurzer Liste). YAML: structures.dungeons.warning.sounds.* und particles.* mit Spigot-Enum-Namen; Partikelanzahl weiterhin ueber tier-2-particle-count / tier-3-particle-count.
• Belohnung: Crate-Placement nach letzter Welle; Integration mit Struktur-Loot-Philosophie (siehe oben).

Legendary-Monolithen

• 10+ Archetypen mit eigenen Faehigkeiten, Namen, Stat-Profilen, Drops; force-aggro und retarget-interval-ticks fuer aktives Boss-Feeling.
• Tier I/II/III pro Epoche konfigurierbar; skaliert HP, Strength, Resistance, Faehigkeits-Cooldowns, Drops, XP.
• Exklusive Drops ueber by-tier und by-tier-and-archetype mit max-exclusive-items-per-kill gegen Highroll-Explosionen.
• Aura-Hygiene: Effekte werden beim Verlassen des Radius hart entfernt – kein permanentes "Aura-Drift".

Mutatoren, Finale, Epochenmonitor-GUI

• configs/mutators.yml: saisonale Zufalls-Modifikatoren (z. B. saurer Regen, Blutmond) mit eigenen Regeln und Laufzeiten – fuer kurzfristige Meta-Brueche neben der Epoche.
• configs/finale.yml: Steuerung von Saison-Endevents inklusive Hall-of-Fame-Fluss (/aoe finale Subcommands).
• configs/gui.yml: Titel und Sichtbarkeit von Modus-, Mutator- und Stat-Sektionen im Epochenmonitor; schaltet Informationsdichte fuer Casual vs. Hardcore Server.

Setup-Wizard (drei Seiten)

• Seite 1: Spielmodus, Schwierigkeit, Pre-Game-Lock, Lock-Radius, Legendary-Retarget, Force-Aggro – alles mit Live-Tooltips und Druck-Indikator (Niedrig/Mittel/Hoch/Extrem) aus Aggro + Retarget + Schwierigkeit; explizite Warnung bei extremen Kombinationen.
• Seite 2: Weltname-Presets (zyklisch), Struktur-/Spawnschalter inkl. Dungeon-Spawns, Loot-Boost-Presets (farbige Chancen-Vorschau), Countdown-Optionen, Starter-Kit Toggle; Live-Vorschau-Karte fasst alle gewaehlten Werte zusammen.
• Seite 3 – Dungeon-Feintuning: Trap-Intensitaets-Preset, Elite-HP-Bonus-Preset, Wellenzahl-Preset (soweit vom Setup angeboten), Archetype-Cluster-Preset (balanced/depth/sky/water/chaos), plus getrennte Elite-Multiplikatoren fuer Tunnel-, Himmel- und Wasser-Dungeons – direkt an die Struktur-Service-Werte angebunden und persistent in first-start-setup.yml.
• Rundenstart: gemeinsame Teleport-Sync, Inventar-Clear, optionales Starter-Kit aus configs/setup.yml (map-basierte Items inkl. Namen/Lore-Keys, Verzauberungen), Countdown-Sidebar, Feuerwerk, sauberer Uebergang in den Live-Run.
• Festungs-Spawn: mehrstufiger Aufbau mit Beacon-Zentrum, Thronsaal mit modus-farbigen Bannern, Toranlagen, Innenhof-Set, kleiner Parkour an der Mauer – technisch und inszenatorisch als "Lobby-Festung" gedacht.

Custom Items (Design + Technik)

• Persistente Item-IDs ueber NamespacedKeys, Rezepte optional pro Item aktivierbar in configs/items.yml.
• Astrolabium: Sofort-Feedback zu Stats/Saison, oeffnet den Epochenmonitor per Rechtsklick; Mainhand-only und 200ms Debounce gegen Doppeltrigger.
• Isolations-Mantel, Regensammler, Klimablock, Machete, Legendary-Kompass (Ladungen, Cooldown, Refill) – alle an Epochen- und Stat-Logik angebunden, wo sinnvoll.

Tutorial, Lokalisierung, Betrieb

• /aoe tutorial: Schrittfolge inkl. Status, GUI, Astrolabium-Ziel, Profile, Spielweisen, Rezeptuebersicht; Bossbar-Fortschritt optional; eigenes Tutorial-GUI mit Kacheln fuer Show/Next/Restart/Stop.
• Neu: reclaim-loaned-astrolabium in configs/tutorial.yml – wenn das Tutorial ein Astrolabium nur zum Testen ins Inventar legt (weil noch keins vorhanden war), wird es beim Abschluss, bei stop/reset und bei start force wieder entfernt; Spieler mit eigenem Astrolabium bleiben unangetastet.
• Lokalisierung: vollstaendige de_DE und en_US YAMLs; /aoe langcheck fuehrt den Localization-Guard aus (fehlende/leere/extra Keys, Platzhalter-Inkonsistenzen).
• /aoe config get|set und /aoe reload fuer schnelle Live-Anpassungen ohne Neustart (soweit die jeweilige Datei reload-tauglich ist).

Technik, Persistenz, Balance-Profile

• Profile-System: configs/profiles.yml buendelt Tick-Intervalle, Stats, Struktur-Chancen, GUI-Flags, Tutorial-Schalter usw. Der aktive Profilname steht in config.yml; so kannst du Casual-, Event- oder Hardcore-Presets parallel pflegen.
• Persistente State-Dateien (z. B. Struktur-Chunk-Listen, Tutorial-Fortschritt, First-Start-Setup) verhindern Doppel-Spawns und erhalten Admin-Entscheidungen ueber Restarts – unter plugins/AOE/ nachvollziehbar benannt.
• Performance-Denken: Struktur- und Dungeon-Spawns arbeiten spieler- und chunkzentriert mit konfigurierbaren Intervallen/Chancen; World-Effekte skalieren ueber samples-per-tick und chunk-radius, damit du visuelle Intensitaet gegen TPS abwaegen kannst.
• Design-Philosophie: Situationsstaerke vor globalem Chaos – Epoche + Modus + Profil + optional Mutator bilden den Kontext; Dungeons und Legendaries reagieren darueber hinaus mit eigenen Tier- und Cluster-Schichten.

/aoe <status|next|set|advance|gui|mode|finale|profile|tutorial|config|reload|langcheck|info|setup>

• /aoe status -> zeigt Epochenstatus, Stats, Modus, Mutatoren
• /aoe next -> nächste Epoche anzeigen
• /aoe set <DROUGHT|FLOOD|ICE_AGE|OVERGROWTH> -> Epoche setzen
• /aoe advance -> Epoche manuell weiterschalten
• /aoe gui -> Monitor-GUI öffnen
• /aoe mode <ALLIANCE|RESOURCE_WAR|HYBRID> -> Modus wechseln
• /aoe finale <start|stop|hof> -> Endspiel kontrollieren
• /aoe profile | /aoe profile list | /aoe profile <name> -> Balanceprofile
• /aoe tutorial <start|next|show|stop|reset> -> Ingame-Tutorial
• /aoe config <get|set> <datei> <pfad> [wert] -> Runtime-Configzugriff
• /aoe reload -> Konfig neu laden
• /aoe langcheck -> Localization-Guard ausführen
• /aoe info -> Copyright-Hinweis
• /aoe setup -> Setup-GUI öffnen
• /aoe setup reset -> Erststart-Status zurücksetzen

Kern

• aoe.admin
• aoe.tutorial
• aoe.setup
• aoe.langcheck

Profile

• aoe.profile.view
• aoe.profile.change
• aoe.profile.lock.bypass
• aoe.profile.easy
• aoe.profile.normal
• aoe.profile.hardcore
• aoe.profile.hardcore_full
• aoe.profile.casual
• aoe.profile.pvp_tournament
• aoe.profile.builder_creative_survival
• aoe.profile.extreme
• aoe.profile.custom

Permission-Vorschlag (Rollen)

• Owner: aoe.admin, aoe.setup, aoe.langcheck, aoe.profile.lock.bypass + gewünschte Profilrechte
• Moderator: aoe.profile.view, aoe.profile.change + ausgewählte Profilrechte
• Spieler: aoe.tutorial, optional aoe.profile.view

• 1) /aoe tutorial start (optional force) – Einstieg, Bossbar, Schritt-Titel im Chat
• 2) /aoe status – Hydration, Temperatur, Epoche, Modus lesen (Tutorial-Ziel)
• 3) /aoe gui oder Astrolabium-Rechtsklick – Epochenmonitor, Mutatoren, Zyklus
• 4) Astrolabium-Schritt: nur bei Bedarf Leih-Item; bei reclaim-loaned-astrolabium: true wird es nach Ende/Stop/Reset wieder eingezogen
• 5) /aoe profile – Balanceprofile und Risikoanpassung
• 6) Spielweisen-Text + Rezeptuebersicht (Crafting-Pfade)
• 7) /aoe tutorial show – jeden Schritt erneut anzeigen; tutorial gui-menu-enabled optional fuer Klick-Navigation

Crafting (detailliert erklärt)

• Legende für Pattern-Rezepte: C = Kupfer, G = Glas, R = Redstone, W = Wolle, L = Leder.
• Astrolabium (Frühspiel-Navigation): CGC / GRG / CGC. Zweck: schneller Saison-/Status-Check und Einstieg in AOE-Mechaniken.
• Isolations-Mantel (Klima-Schutz): WLW / L L / WLW. Zweck: bessere Stabilität bei harten Temperaturphasen (z. B. ICE_AGE).
• Regensammler (Wasserlogistik): Kernzutaten Eisen + Kessel + Trichter. Zweck: verlässliche Wasserquelle in Dürre-/Stressphasen.
• Klimablock (Zonen-Kontrolle): Kernzutaten Glas + Glowstone + Redstone. Zweck: lokale Klima-Entschärfung rund um Basis oder Außenposten.
• Machete (Utility-Tool): Eisen + Stock. Zweck: schnelles Arbeiten in Overgrowth-/Vegetations-Situationen.
• Legendary-Kompass (Endgame-Tracking): Kernzutaten Echo-Scherbe + Netherit + Kompass + Netherstern. Zweck: Monolith-Signale tracken; arbeitet mit Ladungen, Cooldown und Refill.
• Wichtig: Werte/Balance (Cooldowns, Ladungen, Effekte) sind serverseitig konfigurierbar, das Rezept liefert den Einstieg ins System.

Epochenmonitor, Titel, Bossbars

• Das Haupt-GUI bündelt Modus, Mutatoren, Zyklus und – je nach configs/gui.yml – Live-Spielerstats; farbige Titel und Lore folgen den Sprachdateien, damit du das Layout ohne Code umbiegen kannst.
• Astrolabium kann die gleiche GUI öffnen und liefert zusätzlich eine kompakte Textzeile zu Hydration/Temperatur/Saison – ideal, wenn du Spielern kein extra Command zumuten willst.
• Dungeon-Warnungen kombinieren Actionbar (sofort lesbar) mit einer temporären BossBar (Restdauer konfigurierbar), damit Eskalationen auch in lauten Teamsituationen nicht übersehen werden.
• Tutorial optional mit eigener Bossbar und Kachel-GUI; Schritttexte komplett aus lang/*.yml und/oder configs/tutorial.yml überschreibbar.

Dungeon-Ablauf (ein Durchlauf)

• Spawn eines Dungeon-Typs (Tunnel/Himmel/Wasser) + Zufalls-Archetyp aus dem gewichteten Pool; cluster-preset verschiebt die Gewichte (z. B. mehr Himmel in „sky“).
• Elite erscheint mit skaliertem Leben (elite-health-bonus-hearts, Epochen-Tier, elite-area-multiplier für die aktuelle Linie).
• Erste Welle + erste Trap-Phase; nach konfigurierbarem Intervall folgen weitere Wellen. Vor der nächsten harten Welle feuert die Warning-Pipeline (Radius, Sounds/Partikel nach Cluster, BossBar).
• Nach der letzten Welle: Belohnungskiste; Spieler verlassen den Radius – Trap-/Aura-Reste werden bereinigt, damit keine Zustände mitgeschleppt werden.

Konfig-Schalter für Admins (Auszug)

• commands.yml: einzelne Command-Familien (z. B. Tutorial) abschaltbar; Permissions bleiben dokumentiert in PERMISSIONS.md / LuckPerms-Vorlage.
• configs/stats.yml: HUD-Layout, globale Hydrations-/Hitzemultiplikatoren, Distanz-Heat-Kurve, Cap pro Tick.
• configs/world-effects.yml: Intensität der Map-Mutation pro Epoche, Chunk-Radius, globale Mini-Events.
• configs/structures.yml: normale Strukturen, Dungeons inkl. Warnungs-Sounds/Partikeln, Progression, Archetyp-Tabelle, Biome-Loot.
• configs/setup.yml + first-start-setup.yml: Wizard-Auswahl und Persistenz der gewählten Feinwerte (inkl. Seite 3).

Wichtige Dateien: config.yml, configs/*.yml, lang/de_DE.yml, lang/en_US.yml



What AOE Actually Delivers
AOE is a configuration-first survival framework for Spigot/Paper ( API 26.1). It is not "just more mobs": epochs reshape the world, player physiology reacts every tick, dungeons escalate by season tier, legendary sites scale with archetypes, and the first-start wizard configures pressure, loot, dungeons, and fair launches. Nearly every tuning knob lives in YAML so you can adapt pacing, risk, and spectacle per server or profile without recompiling.

Epoch Cycle and Scheduling

• Four epochs: DROUGHT, FLOOD, ICE_AGE, OVERGROWTH. Each epoch owns its own hydration/temperature rules in configs/stats.yml (sun, water, baseline, insulation bonuses, etc.).
• Cycle length, warnings, and transitions are driven from configs/epochs.yml with persistent state so reloads and restarts do not desync the season machine.
• /aoe status, /aoe next, /aoe set, /aoe advance give operators precise control while players read the same truth in the Epoch Monitor GUI and optional HUD feedback.

Modes and Conflict Profile

• ALLIANCE: cooperative resilience, softer PvP pressure, more emphasis on surviving the environment together.
• RESOURCE_WAR: PvPvE with explicit resource contest; structures and encounters skew more dangerous.
• HYBRID: mixed rules with season-aware PvP windows (see configs/modes.yml for detailed switches).
• Modes change how encounters feel—not just chat prefixes—through server-side weighting and configurable rules.

Player Stats: Hydration, Temperature, Live HUD

• Always-on simulation: hydration and temperature tick continuously; they are not gated behind commands. Global multipliers and per-epoch tables in configs/stats.yml keep deltas tick-normalized against profile stats-interval-ticks.
• HUD layouts: compact, detailed, minimal via stats.yml -> hud.layout; boss bars track the live values with localized formatting.
• Drinking water bottles applies a strong hydration bump (fixed plugin balance) so drought gameplay has a natural loop without admin commands.
• Heat sources: campfires (including soul campfires), furnaces, blast furnaces, smokers, lava, and lava cauldrons warm the player contextually. Distance-linear heat interpolates between near/far radii and multipliers; max-heat-gain-per-tick caps burst stacking.
• Insulation: leather armor plus the Insulation Mantle custom item mitigate cold spikes; ICE_AGE can grant an extra temperature-insulation-bonus multiplier for mantle logic.
• Consequences + cleanup: crossing thresholds applies negative effects; leaving structure radii or resetting dungeon runs performs hard debuff/tag cleanup so legendary or dungeon auras never stick as ghost states.
• Run start: resetForRunStart restores fair baselines; prepareForTutorial can temporarily normalize stats for onboarding.

Permadeath Lockout

• Permadeath does not dump players into empty spectator: they enter a protected sky lobby (adventure rules—no damage, hunger, PvP, or block placement).
• Parkour plus hologram timers show remaining wait until the next epoch transition, then the plugin automatically returns them to survival.

World Effects (Living Map Layer)

• configs/world-effects.yml controls sampling throughput, per-player chunk-radius (0 = player chunk only, 1 = 3x3 field for stronger visible churn), and clear-weather/event chances.
• Each epoch defines its own mutation palette: drought desiccation and ignition risks; flood water rise up to configurable Y, torch snuffing, clay/mud shifts; ice snowing, lava freezing, cauldron freeze; overgrowth vines, moss, flower spread, blood-moon creeper spawns—all probability-driven and tunable.
• Localized global micro-events near players (global-event-chance, radius, action budget) add cinematic spikes without rewriting the entire map at once.

Structures, Loot, Silhouettes

• Major families (Oasis, Scorched, Flood, Ice, Spore, Legendary Monolith) are built as monuments: larger footprints, stricter slope/height checks, rarer but higher-impact spawns.
• Biome styles swap palettes (default/desert/swamp/snow); bonus loot tables are fully data-driven with material, chance, amount, min/max, bonus-scale, and amount-rounding.
• Loot reliability: staged filling, backfill, and container repair to fight empty reward chests when other plugins or edge cases interfere.
• Silhouette lighting: inverted daylight sensors + lamps outline builds at night for landmark readability; toggle with structures.silhouette-lighting.enabled.

Dungeon System (Tunnel / Sky / Water)

• Dedicated dungeon pipeline beside normal structures: DUNGEON_TUNNEL, DUNGEON_SKY, DUNGEON_WATER with independent Y bands, weights, and placement rules in configs/structures.yml.
• 20+ archetypes, each with elite/minion pairings, trap motif, weights, and enable flags for curated variety.
• Waves + elites: configurable wave count/interval, elite HP bonus, and per-line elite-area multipliers (tunnel vs sky vs water) so you can tune aerial or aquatic bosses separately.
• Traps: radius + base damage with tier-scaled damage multipliers from progression tables.
• Season-tier progression: tiers-by-season maps each epoch to dungeon tier I–III. Each tier defines extra waves, trap damage multiplier, and elite health multiplier so late seasons feel intentionally brutal—not random.
• Cluster presets balanced | depth | sky | water | chaos skew archetype weights; chaos layers additional randomness into the meta.
• Escalation warnings before harder waves: localized action bar, temporary boss bar, configurable radius/duration. Sounds and particles are themed by depth/sky/water based on the physical dungeon line; when the server preset is chaos, warnings use the chaos audio/particle kits (tier-II chaos sound picks a random cue). Configure enums under structures.dungeons.warning.sounds.* and structures.dungeons.warning.particles.*; intensities still honor tier-2-particle-count / tier-3-particle-count.
• Rewards: final-wave reward crate placement integrated with the structure loot philosophy.

Legendary Monoliths

• 10+ archetypes with bespoke abilities, naming, stats, and drops; force-aggro + retarget-interval-ticks for aggressive boss pacing.
• Tier I/II/III per epoch scales health, strength, resistance, ability cooldowns, drops, and XP.
• Exclusive drops via by-tier and by-tier-and-archetype with max-exclusive-items-per-kill to prevent loot jackpots.
• Aura hygiene: hard cleanup when players exit the aura radius—no lingering debuff haze.

Mutators, Finale, GUI

• configs/mutators.yml: seasonal random mutators (acid rain, blood moon, etc.) with their own timing and rules for short-lived meta twists.
• configs/finale.yml: finale orchestration plus Hall-of-Fame flow through /aoe finale subcommands.
• configs/gui.yml: controls epoch monitor title and which panels (modes, mutators, player stats) appear for casual vs hardcore presentations.

Setup Wizard (Three Pages)

• Page 1: game mode, difficulty, pre-game lock, lock radius, legendary retarget interval, force-aggro—with live tooltips, pressure meter (Low/Medium/High/Extreme), and explicit warnings for extreme combos.
• Page 2: world-name presets, structure/dungeon spawn toggles, loot boost presets (color-coded chance preview), countdown granularity, starter kit toggle, and a consolidated live preview card.
• Page 3 – Dungeon fine tuning: trap intensity preset, elite HP bonus preset, wave-count preset (where exposed), archetype cluster preset (balanced/depth/sky/water/chaos), and separate elite multipliers for tunnel, sky, and water dungeons—persisted into first-start-setup.yml and wired directly into runtime structure logic.
• Fair launch: synchronized teleports, inventory wipe, optional starter kit from configs/setup.yml (map-driven items with localized names/lore keys and enchant lists), countdown sidebar, fireworks, clean handoff into survival.
• Fortress spawn hub: beacon-centered citadel, throne hall with mode-colored banners, gatehouses, courtyard props, wall-crown parkour—serves as both technical staging area and in-world spectacle.

Custom Items (Design + Tech)

• Persistent IDs via namespaced keys; recipes individually toggleable inside configs/items.yml.
• Astrolabe: instant stat/season readout and GUI shortcut; main-hand only with 200ms debounce to stop double activation.
• Insulation Mantle, Rain Collector, Climate Block, Machete, Legendary Compass (charges, cooldown, refill) tie into epoch and survival loops where applicable.

Tutorial, Localization, Operations

• /aoe tutorial: guided steps (status, GUI, astrolabe objective, profiles, playstyles, recipe overview) plus optional boss bar and clickable tutorial GUI tiles.
• New: reclaim-loaned-astrolabium in configs/tutorial.yml—if the tutorial grants an astrolabe only because the player had none, it is removed again on completion, stop, reset, or start force; players who already owned one are untouched.
• Localization: full de_DE + en_US; /aoe langcheck runs the localization guard (missing/empty/extra keys, placeholder mismatches).
• /aoe config get|set plus /aoe reload for rapid iteration where supported.

Engineering, Persistence, Profiles

• profiles.yml bundles tick intervals, stats tuning, structure odds, GUI switches, tutorial flags, and more; config.yml selects the active profile so you can maintain casual, event, and hardcore bundles side by side.
• Persistent state files (structure chunk registries, tutorial completion, first-start setup snapshots) prevent duplicate spawns and preserve admin intent across restarts—each lives under the plugin data folder with clear YAML naming.
• Performance levers: structure/dungeon triggers are player/chunk scoped with configurable cadence; world effects scale via samples-per-tick and chunk-radius so you can trade spectacle for TPS headroom.
• Design philosophy: contextual pressure beats flat global difficulty—epoch + mode + profile + optional mutators define the baseline, while dungeons and legendaries add tier and cluster layers that react to season and dungeon line.

/aoe <status|next|set|advance|gui|mode|finale|profile|tutorial|config|reload|langcheck|info|setup>

• /aoe status -> current epoch, stats, mode, mutators
• /aoe next -> next epoch preview
• /aoe set <DROUGHT|FLOOD|ICE_AGE|OVERGROWTH> -> set epoch
• /aoe advance -> advance epoch manually
• /aoe gui -> open monitor GUI
• /aoe mode <ALLIANCE|RESOURCE_WAR|HYBRID> -> set mode
• /aoe finale <start|stop|hof> -> finale controls
• /aoe profile | /aoe profile list | /aoe profile <name> -> profile controls
• /aoe tutorial <start|next|show|stop|reset> -> tutorial controls
• /aoe config <get|set> <file> <path> [value] -> runtime config access
• /aoe reload -> reload configuration
• /aoe langcheck -> run localization guard
• /aoe info -> copyright info
• /aoe setup -> open setup GUI
• /aoe setup reset -> reset first-start state

Core

• aoe.admin
• aoe.tutorial
• aoe.setup
• aoe.langcheck

Profiles

• aoe.profile.view
• aoe.profile.change
• aoe.profile.lock.bypass
• aoe.profile.easy
• aoe.profile.normal
• aoe.profile.hardcore
• aoe.profile.hardcore_full
• aoe.profile.casual
• aoe.profile.pvp_tournament
• aoe.profile.builder_creative_survival
• aoe.profile.extreme
• aoe.profile.custom

Suggested Role Setup

• Owner: aoe.admin, aoe.setup, aoe.langcheck, aoe.profile.lock.bypass + selected profile rights
• Moderator: aoe.profile.view, aoe.profile.change + selected profile rights
• Player: aoe.tutorial, optional aoe.profile.view

• 1) /aoe tutorial start (optional force) – onboarding, boss bar, chat titles
• 2) /aoe status – read hydration, temperature, epoch, mode (tutorial objective)
• 3) /aoe gui or astrolabe right-click – epoch monitor, mutators, cycle context
• 4) Astrolabe step – loan item only if needed; with reclaim-loaned-astrolabium: true it is removed after finish/stop/reset/start-force
• 5) /aoe profile – balance profiles and risk tuning
• 6) Playstyle copy + crafting overview step
• 7) /aoe tutorial show – revisit any step; optional click GUI when tutorial gui-menu-enabled is true

Crafting (explained in detail)

• Pattern legend: C = copper, G = glass, R = redstone, W = wool, L = leather.
• Astrolabe (early navigation): CGC / GRG / CGC. Purpose: fast season/status reading and smooth onboarding.
• Insulation Mantle (climate defense): WLW / L L / WLW. Purpose: better survival stability in harsh temperature phases (especially ICE_AGE).
• Rain Collector (water logistics): core ingredients iron + cauldron + hopper. Purpose: reliable water recovery under drought/resource pressure.
• Climate Block (local control): core ingredients glass + glowstone + redstone. Purpose: stabilize local climate pressure near bases/outposts.
• Machete (utility tool): iron + stick. Purpose: fast utility in vegetation-heavy phases like Overgrowth.
• Legendary Compass (endgame tracking): core ingredients echo shard + netherite + compass + nether star. Purpose: track monolith signals with charges, cooldown and recharge.
• Important: recipe unlocks the item; operational tuning (cooldowns, charges, effect strength) stays configurable server-side.

Epoch Monitor, Titles, Boss Bars

• The main GUI aggregates mode, mutators, cycle data, and—per configs/gui.yml—live player stats; titles and lore pull from language files so you can reskin text without rebuilding.
• Astrolabe can open the same GUI and prints a compact stats/season line for players who should not memorize slash commands.
• Dungeon warnings pair an action bar ping with a temporary boss bar (duration configurable) so wave escalation is noticeable even in noisy voice groups.
• Tutorial optionally mirrors progress on its own boss bar plus click menu; step copy can be overridden in lang/*.yml and/or configs/tutorial.yml.

Dungeon Run Flow (one pass)

• Dungeon line (tunnel/sky/water) + weighted archetype roll; cluster-preset biases the pool (e.g., favor sky arenas when preset is sky).
• Elite spawns with stacked health (elite-health-bonus-hearts, seasonal tier, line-specific elite-area-multiplier).
• Wave zero plus trap pulse, then timed follow-up waves; before the next spike the warning pipeline fires (radius, cluster-themed particles/sounds, boss bar).
• After the final wave: reward crate; leaving the encounter radius triggers hard cleanup of trap/aura residue so no phantom debuffs follow players home.

Admin-Facing Config Highlights

• commands.yml: toggle whole command families (e.g., tutorial) for lobby servers; permissions remain documented in PERMISSIONS.md and the LuckPerms template.
• configs/stats.yml: HUD layout, global hydration/heat multipliers, distance heat curve, per-tick heat cap.
• configs/world-effects.yml: per-epoch mutation intensity, chunk sampling radius, localized micro-events.
• configs/structures.yml: surface structures, dungeon engine, warning SFX/VFX tables, seasonal dungeon tiers, archetype matrix, biome loot.
• configs/setup.yml + first-start-setup.yml: wizard defaults and persisted fine tuning (including dungeon page 3 knobs).

Important Files: config.yml, configs/*.yml, lang/de_DE.yml, lang/en_US.yml