L-Dungeons

L-Dungeons is a next-generation dungeon and realm-travel plugin built from the ground up for modern Minecraft server networks (Paper, Purpur, and Folia). It features procedural labyrinth dungeons, a tag-resonant runic portal network, 100% lossless cross-server NBT inventory synchronization, zero-lag asynchronous player auditing, and comprehensive BungeeCord/Velocity clustering.

---

Key Features

1. Resonant Runic Portal Network

• Tag-Based Resonance: Portals sharing the identical tag automatically discover each other and form a seamless two-way planar link.
• Dynamic Particles & Ambient Resonance: Swirling runic vortex particle rings, ancient whispering soundscapes, and entrance activation animations.
• Metal & Raw Ore Transit Restrictions: Prevents players from teleporting raw ores (RAW_IRON, RAW_GOLD, ANCIENT_DEBRIS, etc.) and ingots through portals, preserving survival economy balance (can be bypassed with ldungeons.bypass.ore).
• Interactive Management GUI: Name portals, browse active gateways across dimensions, teleport instantly, or remotely deconstruct portals via /portal list.

2. Ancient Procedural Dungeons & Tiered Gates

• Procedural Labyrinth Generation: Corridors and interconnecting chambers generated on a dynamic grid—rooms never open into the void, with automatic fallback and schematic support.
• Per-Player Dynamic Holograms: The entrance gate adapts dynamically to each individual player. A player who unlocked the gate sees [Unlocked - Right-Click to Enter], while other players still see [Locked - Requires Tier X Key].
• Tiered Ancient Keys: Tier-based ancient keys (/ldungeons key give) consumed upon unlocking entrance gates and interior vault barriers.
• In-Dungeon Interactive Mechanics:
  • Muddy Scrap Piles: Mineable scrap block clusters that drop scrap metal upon taking pickaxe hits.
  • Evil Piles: Ancient dark spawner structures with dynamic boss-health bars that spawn dungeon sentinels until shattered.
  • Indestructible Dungeon Fortification: Dungeon blocks and corridors are completely immune to unauthorized block breaking and placing.
• Automatic Lifecycle Reset: When the last explorer departs, an automated countdown initiates (reset-timeout-seconds: 300), after which mobs and loot respawn, and gates re-lock for all players.

3. Proxy & Lossless Cross-Server Clustering

• 3 Operating Modes:
  • STANDALONE: Single server running instances in a local dungeons_world. Does not require a proxy.
  • SURVIVAL: Overworld node hosting entrance gates; forwards players smoothly to dedicated dungeon nodes.
  • DUNGEON_NODE: Dedicated worker server executing dungeon instances in complete isolation.
• Native Lossless NBT Synchronization: 36 inventory slots, 4 armor slots, offhand, ender chest, health, food level, experience points/levels, and active potion effects are transferred with zero external plugin dependencies using cryptographic single-use transfer tickets.
• Database Engine: High-performance HikariCP connection pooling supporting both local SQLite and centralized MySQL / MariaDB.
• Live Admin Proxy GUI: Real-time cluster monitoring dashboard (/ldungeons proxy) displaying node TPS, active dungeon sessions, player counts, and heartbeat statuses. Automatically updates every 5 minutes with on-demand manual refresh.

4. Zero-Lag Asynchronous Player Action Logging

• Non-Blocking In-Memory Queue: Player actions are captured into a concurrent lock-free buffer and acknowledged in $O(1)$ time, guaranteeing zero main-thread lag spikes.
• Dual-File Logging Strategy: Every action is written simultaneously to both a global daily log (logs/YYYY-MM-DD.log) and an individual per-player log file (logs/players/PlayerName.log).
• Exhaustive Audit Scope: Tracks portal travels, ore restriction rejections, key unlocks, dungeon entries/exits, reward claims, scrap/evil pile destructions, and proxy network transfers.
• In-Game Audit GUI: Staff can review a player's complete chronological history through an interactive, color-coded, paginated menu (/ldungeons logs <player>).
• Automated Retention Purge: Background task automatically cleans up log files older than 15 days (retention-days: 15).

5. Custom 3D Model & Plugin Hooks

• ItemsAdder & Oraxen: Native custom model hooks for runic portals, ancient keys, scrap piles, and evil spawner structures.
• MythicMobs: Seamlessly spawn custom MythicMobs bosses and mobs inside procedural dungeon rooms.
• WorldEdit & FastAsyncWorldEdit (FAWE): High-speed schematic pasting and room assembly.
• bStats Metrics: Fully integrated anonymous statistics collection (Service ID: 34880), toggleable in config.yml.

---

System Requirements

Component	Requirement
Java	Java 21 or higher
Server Software	Paper, Purpur, or Folia (1.21.x+)
Database	SQLite (Single server) or MySQL / MariaDB (Proxy networks)
Optional Hooks	ItemsAdder, Oraxen, MythicMobs, FastAsyncWorldEdit

---

Quick Start

1. Installation

1. Place L-Dungeons-1.0.0-SNAPSHOT.jar into your server's plugins/ folder.
2. Start the server to generate default configurations and language files.

2. Standalone Mode Configuration

If you run a single Minecraft server without BungeeCord/Velocity:

database:
  type: "SQLITE"
proxy:
  enabled: false
  server-mode: "STANDALONE"

3. Multi-Server Proxy Setup

To establish a high-performance cross-server dungeon cluster:

1. Set up a central MariaDB / MySQL database.
2. Configure config.yml across your cluster:

database:
  type: "MYSQL"
  mysql:
    host: "127.0.0.1"
    port: 3306
    database: "ldungeons"
    username: "root"
    password: "YOUR_PASSWORD"

proxy:
  enabled: true
  server-mode: "SURVIVAL" # Set to "DUNGEON_NODE" on worker instances
  server-id: "survival-1"
  dungeon-servers:
    - "dungeon-1"
    - "dungeon-2"
  fallback-server: "survival-1"
  data-sync:
    provider: "NATIVE"

---

Commands & Permissions

Command	Arguments	Description	Default Permission
/ldungeons help	-	Lists all available commands	Everyone
/ldungeons reload	-	Reloads configuration, languages, and portals	ldungeons.admin
/ldungeons portal give	<player> [amount]	Gives a Runic Portal item	ldungeons.admin
/ldungeons portal list	-	Opens the interactive portal management GUI	ldungeons.admin
/ldungeons dungeon spawn-entrance	<tier>	Spawns an ancient dungeon entrance gate	ldungeons.admin
/ldungeons dungeon enter	[tier] [variant]	Teleports directly into a dungeon instance	ldungeons.admin
/ldungeons dungeon leave	-	Safely exits the current dungeon session	Everyone
/ldungeons key give	<player> [tier] [amount]	Grants tiered ancient dungeon keys	ldungeons.admin
/ldungeons proxy	[status/gui/list]	Displays the proxy cluster monitoring GUI	ldungeons.admin
/ldungeons logs	<player>	Opens the player action audit GUI	ldungeons.admin
/portal give	<player> [amount]	Shortcut to grant a runic portal item	ldungeons.portal.admin
/portal list	-	Opens the player's personal portal list GUI	ldungeons.portal.use

Permission Nodes

• ldungeons.admin: Full administrative access to all commands and features.
• ldungeons.portal.use: Permission to place, name, and travel through runic portals.
• ldungeons.portal.admin: Administrative authority to edit or delete any portal remotely.
• ldungeons.bypass.ore: Bypasses portal raw ore and metal transit restrictions.
• ldungeons.bypass.build: Bypasses block-break and block-place protections inside dungeons.

---

Localization & Multi-Language

L-Dungeons features dual-language parity with full support for Adventure MiniMessage formatting:

• English (en): plugins/L-Dungeons/lang/messages_en.yml
• Turkish (tr): plugins/L-Dungeons/lang/messages_tr.yml

Switch languages dynamically in config.yml:

language: "en" # or "tr"

---

Comprehensive Wiki

Looking for detailed architectural diagrams, NBT synchronization workflows, hook configurations, or troubleshooting advice? 👉 Check out the WIKI!

---

Author & License

• Author: squezsaz
• License: ARR