Skip to content

WIKI

Jump to bottom
squezsaz edited this page Oct 22, 2026 · 1 revision

L-Dungeons Official Wiki Guide

Welcome to the comprehensive technical documentation and operator handbook for L-Dungeons. This guide provides an in-depth reference for configuration options, architectural designs, server clustering, and administrative workflows.

Table of Contents

  1. Overview & Core Architecture
  2. Installation & Requirements
  3. Runic Portal Network
  4. Ancient Dungeons & Gameplay Mechanics
  5. Proxy & Multi-Server Architecture
  6. Zero-Lag Asynchronous Logging System
  7. Custom 3D Models & Plugin Hooks
  8. Anonymous Metrics (bStats)
  9. Commands & Permissions Reference
  10. Configuration Guide (config.yml)
  11. Frequently Asked Questions & Troubleshooting

1. Overview & Core Architecture

L-Dungeons is engineered for high-performance production Minecraft networks, targeting Paper, Purpur, and Folia (1.21.x+).

Platform Support & Folia Compatibility

  • Regional Threading Abstraction: L-Dungeons does not rely on legacy Bukkit schedulers. It utilizes a unified SchedulerManager abstraction that detects Folia at runtime and delegates tasks to RegionScheduler, GlobalRegionScheduler, or AsyncScheduler.
  • Asynchronous Teleportation: All portal transits and dungeon entries invoke player.teleportAsync(). Chunk loading never blocks the server main thread.
  • Dual-Language Parity: Native support for English (en) and Turkish (tr). All user-facing strings are formatted using Adventure MiniMessage with RGB color gradients and click/hover events.

2. Installation & Requirements

Minimum Specifications

  • Java: Java 21 LTS or newer.
  • Server Platform: Paper, Purpur, or Folia 1.21.x+.
  • Database:
    • SQLite: Recommended for single-server (Standalone) environments (automatically generated).
    • MySQL / MariaDB: Recommended for multi-server proxy networks (requires HikariCP pooling).

Step-by-Step Installation

  1. Download L-Dungeons-1.0.0-SNAPSHOT.jar and place it into your server's plugins/ directory.
  2. Start and stop the server once to generate default configuration files and language templates.
  3. Open plugins/L-Dungeons/config.yml to specify your operational server mode (STANDALONE or SURVIVAL).
  4. Restart your server.

3. Runic Portal Network

Runic Portals are resonant physical gateways that link two locations across identical or separate worlds.

flowchart LR
    A["Runic Portal (Tag: 'MiningOutpost')"] <--->|Bidirectional Resonance| B["Runic Portal (Tag: 'MiningOutpost')"]
Loading

3.1. Resonance Logic & Tagging

  • When a portal structure is placed, the owner designates a Tag (default: default).
  • When exactly two portals in the network share an identical tag, an energetic resonance is established, triggering purple/cyan vortex particles and ambient audio.
  • If three or more portals share the same tag, the network flags a CONFLICT state and locks all linked gates to prevent teleport loops.

3.2. Metal & Raw Ore Transit Restrictions

To maintain healthy survival economies and prevent players from instantly teleporting raw mined wealth directly into base vaults:

  • Restricted Materials: RAW_IRON, RAW_COPPER, RAW_GOLD, ANCIENT_DEBRIS, IRON_INGOT, GOLD_INGOT, COPPER_INGOT, NETHERITE_INGOT, NETHERITE_SCRAP.
  • When an explorer attempts to cross a portal while carrying restricted materials, passage is rejected: the player is pushed back with velocity, and a warning title appears on screen.
  • Bypass Permission: Players or VIPs with ldungeons.bypass.ore can carry ores freely.

3.3. Interactive Portal GUIs

  • Portal Settings GUI: Right-clicking an owned portal opens a control pane allowing the owner to modify tags via chat prompt or safely dismantle the portal.
  • Portal Directory GUI (/portal list): A paginated administrative directory displaying portal owners, coordinates, tags, and status (CONNECTED, WAITING, CONFLICT). Offers one-click teleportation, tag inspection, and remote deletion (Shift + Right-Click).

4. Ancient Dungeons & Gameplay Mechanics

Ancient Dungeons are instanced, procedural challenge chambers where players unlock entrance gates, fight hostile sentinels, mine scrap piles, and collect rewards.

4.1. Procedural Labyrinth Generation

  • L-Dungeons constructs procedural dungeons using a grid layout.
  • The ProceduralDungeonBuilder algorithm ensures rooms are systematically connected by enclosed corridors, guaranteeing no doorway opens into the void.
  • The default layout generates 16 interconnected chambers (rooms-count: 16), supporting both procedural layouts and schematic files (generation-mode: AUTO).

4.2. Dungeon Entrance Gates & Dynamic Holograms

  • Administrators can place permanent dungeon entrance gates in survival worlds using /ldungeons dungeon spawn-entrance <tier>.
  • Per-Player Dynamic Hologram:
    • A player who has not unlocked the gate sees: [Locked - Requires Tier X Key].
    • Right-clicking the gate while holding an Ancient Key of matching tier unlocks the passage and consumes the key.
    • The hologram dynamically transforms into [Unlocked - Right-Click to Enter] solely for that player. Other players continue to see the gate as locked.

4.3. In-Dungeon Gameplay Elements

  1. Evil Piles (Spawner Monuments):
    • Dark spawner structures that continually summon dungeon sentinels.
    • Display a dynamic boss bar reflecting remaining health. Once damaged and destroyed by players, mob spawning terminates.
  2. Muddy Scrap Piles:
    • Ancient mineral blocks embedded in dungeon corridors.
    • Requires pickaxe hits to break down, dropping valuable scrap metal upon total destruction.
  3. Anti-Grief Structure Fortification:
    • All ancient stone walls and floors inside dungeons are protected against breaking and building (ldungeons.bypass.build can bypass).
  4. Automated Lifecycle Reset:
    • Once all explorers exit the dungeon, an automatic countdown initiates (reset-timeout-seconds: 300).
    • After timeout expiry, the dungeon resets: mobs and loot are regenerated, and the overworld entrance gate returns to Locked for all players.

5. Proxy & Multi-Server Architecture

For large networks where dungeon instances must not impact overworld tick rates, L-Dungeons provides native BungeeCord and Velocity clustering.

flowchart TD
    subgraph Proxy Network
        Proxy[BungeeCord / Velocity]
    end
    subgraph Survival Node
        Surv["Survival Server (SURVIVAL Mode)"]
        Gate["Dungeon Entrance Gate"]
    end
    subgraph Central Database
        DB[("MariaDB / MySQL (HikariCP)")]
    end
    subgraph Dedicated Dungeon Nodes
        Node1["Dungeon Node 1 (DUNGEON_NODE)"]
        Node2["Dungeon Node 2 (DUNGEON_NODE)"]
    end

    Surv -->|Generate NBT Ticket & Nonce| DB
    Surv -->|Forward Player| Proxy
    Proxy -->|Route Player| Node1
    Node1 -->|Validate & Consume Single-Use Ticket| DB
    Node1 -->|Restore 100% Lossless Inventory & Stats| Node1
Loading

5.1. Operating Server Modes

Mode Purpose
STANDALONE Operates an instanced dungeons_world locally on a single server. No proxy required.
SURVIVAL Hosts survival worlds and entrance gates. Forwards players to dedicated dungeon nodes.
DUNGEON_NODE Dedicated worker server hosting and executing dungeon instances in isolation.

5.2. Lossless Native NBT Synchronization

L-Dungeons delivers built-in cross-server player synchronization without external dependencies:

  1. When a player steps into an entrance gate on the SURVIVAL server, the plugin serializes:
    • 36 Inventory slots
    • 4 Armor slots
    • Offhand slot
    • Ender chest inventory
    • Health and maximum health
    • Food and saturation levels
    • Total experience points and levels
    • Active potion effects with durations and amplifiers
  2. The payload is encoded into Base64 and stored in the central database alongside a single-use cryptographic ticket (TransferTicket) and sync_nonce.
  3. The player is transferred via proxy plugin messaging. Upon arrival at the target dungeon node, the ticket is verified and consumed, restoring player state with zero item loss or duplication.

5.3. Admin Proxy Dashboard (/ldungeons proxy)

A live graphical administration menu displaying the health and load of the proxy cluster:

  • Cluster Beacon: Displays active/offline node counts, total cluster player counts, and active dungeon session metrics.
  • Node Cards: Individual server items showing server ID, operating mode, online players, active dungeon sessions, live TPS, and heartbeat timestamps.
  • Cache Lifecycle: Node statuses update every 5 minutes (status-refresh-interval-minutes: 5) to prevent database strain.
  • Instant Refresh: Administrators can click the Nether Star button to trigger an immediate live database query.

6. Zero-Lag Asynchronous Logging System

L-Dungeons features an asynchronous file auditing engine engineered to never block the main thread.

flowchart LR
    A["Player Action Event"] -->|O(1) Enqueue| B["ConcurrentLinkedQueue (Memory)"]
    B -->|Async Background Task (Every 2s)| C["Disk Writer Thread"]
    C -->|Batch Write| D["Daily Log (YYYY-MM-DD.log)"]
    C -->|Batch Write| E["Player Log (players/Player.log)"]
Loading

6.1. Zero-Lag Architecture

  • In-Memory Buffering: Player events are pushed into a thread-safe ConcurrentLinkedQueue in $O(1)$ time.
  • Batched Disk Flushing: A background task flushes pending events in batches every 2 seconds (flush-interval-seconds: 2).
  • Shutdown Persistence: On plugin disable (onDisable), any remaining queue items are synchronously flushed to ensure zero record loss.

6.2. Dual-Target Logging Strategy

Every event is written to two destinations simultaneously:

  1. Daily Network Log: plugins/L-Dungeons/logs/YYYY-MM-DD.log (Chronological record across the entire server).
  2. Per-Player Log: plugins/L-Dungeons/logs/players/PlayerName.log (Consolidated player audit trail).

6.3. Recorded Event Categories

  • Portal Events: Portal placement, tag changes, deletions, and planar crossings.
  • Security & Restriction Rejections: Raw ore and metal transit blocks with item types and coordinates.
  • Dungeon Entrance & Keys: Ancient key consumptions, gate unlocks, and interior door interactions.
  • In-Dungeon Actions: Dungeon entries, safe departures, scrap pile mining, evil spawner destructions, and dungeon clears.
  • Security Violations: Unauthorized attempts to place or destroy blocks inside dungeons.
  • Rewards: Vault chest openings and loot claimed.
  • Proxy Network Transfers: Transfer tickets issued and target verification arrivals.

6.4. Automated Retention Purge

To prevent disk exhaustion, log files older than 15 days are automatically removed during server startup and daily background cycles (retention-days: 15).

6.5. In-Game Audit GUI (/ldungeons logs <player>)

Staff members can review a player's history through an interactive in-game menu:

  • Displays player skull, total logged events, and active retention policy.
  • Thematic icons for each event type (Barrier for restrictions, Iron Door for dungeon entries, Tripwire Hook for key unlocks, etc.).
  • Exact timestamps, world coordinates, and detailed event payloads.
  • Refresh button to load newly flushed events from disk instantly.

7. Custom 3D Models & Plugin Hooks

L-Dungeons integrates with leading Spigot and Paper ecosystem plugins:

ItemsAdder & Oraxen

Assign custom 3D models and textures to portals, keys, and dungeon blocks:

hooks:
  itemsadder:
    enabled: true
    items:
      runic-portal: "ldungeons:runic_portal"
      swamp-key: "ldungeons:swamp_key"
      scrap-iron: "ldungeons:scrap_iron"
      surtling-core: "ldungeons:surtling_core"
    blocks:
      muddy-scrap-pile: "ldungeons:muddy_scrap_pile"
    entities:
      evil-pile: "ldungeons:evil_pile"

MythicMobs

Bind custom MythicMobs identifiers to dungeon room spawn points to feature specialized minibosses and guards.

WorldEdit & FastAsyncWorldEdit (FAWE)

Leverage FAWE for asynchronous pasting of custom .schem dungeon room templates.

8. Anonymous Metrics (bStats)

L-Dungeons integrates anonymous usage metrics via bStats (Plugin ID: 34880).

Custom Metrics Tracked

  • Server Operating Mode: Distribution of STANDALONE, SURVIVAL, and DUNGEON_NODE servers.
  • Database Engine: Distribution of SQLITE vs MYSQL configurations.
  • Language Selection: Active localization (tr vs en).
  • Folia Adoption: Percentage of servers utilizing Folia's regional threading.

Toggling bStats

bStats can be enabled or disabled at any time in config.yml:

bstats:
  enabled: true # Set to false to disable all metrics collection

9. Commands & Permissions Reference

Full Command Reference

Command Arguments Description Default Permission
/ldungeons help - Displays command help index Everyone
/ldungeons reload - Reloads configuration, languages, and portals ldungeons.admin
/ldungeons portal give <player> [amount] Grants a Runic Portal item ldungeons.admin
/ldungeons portal list - Opens the portal directory GUI ldungeons.admin
/ldungeons dungeon spawn-entrance <tier> Places a permanent dungeon entrance gate ldungeons.admin
/ldungeons dungeon enter [tier] [variant] Teleports directly into a dungeon session ldungeons.admin
/ldungeons dungeon leave - Safely departs an active dungeon Everyone
/ldungeons key give <player> [tier] [amount] Grants tiered ancient dungeon keys ldungeons.admin
/ldungeons proxy [status/gui/list] Opens the proxy network monitoring dashboard ldungeons.admin
/ldungeons logs <player> Opens the player action audit GUI ldungeons.admin
/portal give <player> [amount] Shortcut to grant a runic portal ldungeons.portal.admin
/portal list - Opens personal portal management GUI ldungeons.portal.use

Permissions Index

  • ldungeons.admin: Complete access to all administrative commands and GUIs (Default: OP).
  • ldungeons.portal.use: Ability to place, tune, and travel through runic portals (Default: Everyone).
  • ldungeons.portal.admin: Administrative power to modify or delete any player's portal (Default: OP).
  • ldungeons.bypass.ore: Bypasses portal ore transit restrictions (Default: OP).
  • ldungeons.bypass.build: Bypasses block-breaking and placing restrictions inside dungeons (Default: OP).

10. Configuration Guide (config.yml)

Annotated reference of the core configuration file:

# ========================================================
#                  L-DUNGEONS CONFIGURATION
# ========================================================

# Language selection: "tr" (Turkish) or "en" (English)
language: "en"

# Database settings (SQLite or MySQL/MariaDB with HikariCP)
database:
  type: "SQLITE" # "SQLITE" for single servers, "MYSQL" for proxy networks
  file: "data.db"
  pool-size: 10
  mysql:
    host: "127.0.0.1"
    port: 3306
    database: "ldungeons"
    username: "root"
    password: ""
    use-ssl: false

# Proxy and Multi-Server Network Settings (BungeeCord / Velocity)
proxy:
  enabled: false
  server-mode: "STANDALONE" # STANDALONE, SURVIVAL, or DUNGEON_NODE
  server-id: "survival-1"
  dungeon-servers:
    - "dungeon-1"
  fallback-server: "survival-1"
  data-sync:
    provider: "NATIVE" # Zero-dependency lossless NBT sync
    sync-main-inventory: true
    sync-armor: true
    sync-offhand: true
    sync-enderchest: true
    sync-experience: true
    sync-health: true
    sync-food: true
    sync-potion-effects: true
  status-refresh-interval-minutes: 5
  heartbeat-interval-seconds: 30

# Asynchronous Zero-Lag Player Action Logging
logging:
  enabled: true
  retention-days: 15
  flush-interval-seconds: 2
  log-portal: true
  log-dungeon: true
  log-reward: true
  log-proxy: true
  log-restrictions: true

# Runic Portal Settings
portal:
  particle-effects: true
  ambient-sound: true
  cooldown-seconds: 3
  push-back-force: 0.7
  metal-restriction:
    enabled: true
    blocked-materials:
      - RAW_IRON
      - RAW_COPPER
      - RAW_GOLD
      - ANCIENT_DEBRIS
      - IRON_INGOT
      - GOLD_INGOT
      - COPPER_INGOT
      - NETHERITE_INGOT
      - NETHERITE_SCRAP

# Dungeon World Settings
dungeons:
  world-name: "dungeons_world"
  grid-offset: 5000
  reset-timeout-seconds: 300
  generation-mode: "AUTO" # PROCEDURAL, SCHEMATIC, or AUTO
  rooms-count: 16

# bStats Anonymous Metrics (Service ID: 34880)
bstats:
  enabled: true

11. Frequently Asked Questions & Troubleshooting

Q1: The game says "Transferring to dungeon server..." but nothing happens?

  • Cause: You are running in SURVIVAL proxy mode without a connected BungeeCord or Velocity proxy routing the player.
  • Solution: For single-server testing, set proxy.enabled: false and proxy.server-mode: "STANDALONE" in config.yml, then execute /ldungeons reload. The dungeon instance will generate locally.

Q2: Why does the portal push me back with an "Access Denied" notice?

  • Cause: Your inventory contains blocked raw ores (RAW_IRON, RAW_GOLD, etc.) or ingots.
  • Solution: Deposit raw ores into a chest before traversing, or grant yourself the ldungeons.bypass.ore permission.

Q3: Why does the dungeon entrance gate hologram still say "Locked"?

  • Cause: You need an Ancient Key matching the gate's tier.
  • Solution: Use /ldungeons key give <player> 1 to obtain a Tier 1 Ancient Key, then right-click the gate. Once unlocked, the hologram will dynamically update to "Unlocked" for your player.

Q4: Does L-Dungeons cause region threading issues on Folia servers?

  • Solution: No. L-Dungeons is designed with Folia architecture in mind. All scheduling operations run through specialized Folia region schedulers, and world teleportations are performed asynchronously via player.teleportAsync().

Clone this wiki locally