HimDungeons

Let the rooms decide how they connect.

HimDungeons is a procedural dungeon generator for Paper / Spigot / Bukkit servers that does not require WorldEdit. It builds dungeon worlds at runtime and stitches prefabricated room schematics together using a bidirectional door-anchor algorithm. Rooms of any size, any shape, and any door position can connect — as long as their doors meet face-to-face.

---

Why HimDungeons?

Most dungeon plugins force your rooms into a grid: uniform sizes, doors on fixed walls, every room facing the same direction. You spend hours building an L-shaped room, then discover the door must sit on the north wall’s midpoint — and the blueprint is dead.

HimDungeons takes a different approach. Each room declares where its doors are and which way they face. The generator finds the correct rotation and offset to connect any two rooms. You build what you want; the algorithm handles the rest.

Capability	Typical dungeon plugins	HimDungeons
Room size	Must be uniform	Any size
Room shape	Mostly rectangular	Any shape (L, T, cross, irregular)
Door position	Fixed wall positions	Any coordinate
Door size	1×1 or fixed	Any size (1×1, 3×3, 5×5 arches)
Vertical connections	Rarely supported	Native 3D (y+ / y-)
Room folder layout	Flat, forced prefixes	Any subdirectory depth
WorldEdit	Hard dependency	No dependency
Async loading	Often blocks main thread	Tick-batched, TPS-safe

---

Core Algorithm: Bidirectional Door Anchoring

Every room declares its doors in a _door.yml file:

doors:
  - {x: 0, y: 1, z: 5, facing: "z-", type: "default", weight: 10}
  - {x: 12, y: 1, z: 3, facing: "x+", type: "default", weight: 10}
  - {x: 5, y: 0, z: 5, facing: "y-", type: "stairs", weight: 5}

During generation, the algorithm takes an available door A from the current room (world position P1, facing D1). It then tries to place each door (P2, D2) of a candidate room B, testing all four rotations. A pair connects if and only if:

P1 + D1 == P2   AND   P2 + D2 == P1

Walking one block out from door A lands exactly on door B, and walking one block out from door B lands exactly on door A. The two doors face each other, touch, and point in opposite directions.

What this unlocks:

• Any room size — a 3×3 storage closet can sit directly beside a 50×50 boss hall, as long as their doors line up.
• Any room shape — L-shaped, cross-shaped, ring-shaped, irregular polygons all work. The algorithm only cares about door coordinates and facings, not the room’s silhouette.
• Any door position — doors do not need to be centered on a wall. A corner door is perfectly valid.
• Any door size — a 1×1 door and a 3×3 arch can connect, because the algorithm matches coordinates and directions, not the geometric opening.
• Automatic 4-way rotation — candidate rooms are rotated 0°, 90°, 180°, and 270° until doors match. You never need to prepare four schematic variants for four directions.
• AABB collision detection — rotation-aware bounding boxes guarantee that newly placed rooms never overlap existing ones.

Door type gating

Doors support a type field. Stair doors only connect to stair doors, grand arches only to grand arches, fallback doors only to fallback doors. This lets you enforce semantic constraints such as “stairs must lead downward” or “a grand arch always leads to a boss hall.”

---

Native 3D Stitching

Most dungeon plugins are 2D: rooms stitch only on the XZ plane, and vertical movement means switching worlds. HimDungeons supports y+ (up) and y- (down) door facings. When a y- door connects to a y+ door, the new room is placed below the current one, forming a genuine vertical stack.

What you can build:

• Multi-layer dungeons — surface entrance → underground crypt → deep lair, using one schematic set.
• Towers — spiral upward, one y+ door per floor.
• Vertical difficulty gradients — the deeper the player goes, the stronger the boss, controlled by structureChoose weights.

Vertical doors are invariant under Y-axis rotation, so you only need one schematic for up/down connections.

---

Free File Organization

Room folders are scanned recursively. Rooms can live at any depth, and the path itself is the unique room identifier:

plugins/HimDungeons/my_dungeon/rooms/
├── chapter1/
│   ├── start_entrance.schem
│   ├── combat/
│   │   ├── sword_fight.schem
│   │   └── ambush.schem
│   └── boss_chapter1.schem
├── chapter2/
│   └── ...
└── fallback/
    └── sealed_wall.schem

chapter1/combat/sword_fight is the room’s name in configuration. Organize by chapter, difficulty, theme, or author — your choice. Large dungeons stay clean, and version control stays reviewable.

---

No WorldEdit Required

HimDungeons ships with its own SpongeSchematicReader and SpongeSchematicWriter (built on the Querz NBT library) for Sponge Schematic v2 and v3. Block rotation uses Bukkit’s native BlockData.rotate(StructureRotation). Region selection uses a wooden pickaxe in creative mode as an operator — no external plugin needed.

Why this matters:

• The plugin jar is roughly 3.5 MB (NBT and SQLite native libraries shaded in), far smaller than the WorldEdit stack.
• Server upgrades do not wait on WorldEdit compatibility.
• WorldEdit and HimDungeons cannot drag each other down.
• Schematic format is configurable globally (schematic.readFormat: auto | sponge_v2 | sponge_v3).

Migrating from WorldEdit? Drop your existing .schem files into rooms/ — they read directly, because WorldEdit saves in Sponge v2 or v3 by default.

---

Async IO and Tick-Batched Pasting

WorldEdit pasting is synchronous. A 30×20×30 room can stall a low-end server for 100–500 ms. HimDungeons splits the work into three stages:

1. Async — read and parse the .schem file.
2. Async — precompute every block position and rotated BlockData.
3. Main thread, tick-batched — place a configurable batch of blocks per tick, then yield.

// Tunable in AsyncPaster.java
private static final int BLOCKS_PER_TICK = 2000;

The server keeps running normally while a large room is pasted. Saving is asynchronous too: the main thread reads block data, and the async thread writes the file.

---

Complete Lifecycle and Crash Safety

Player transitions are handled by a single DungeonSessionService state machine:

[Overworld] ──enter──► [In Dungeon] ──finish──► [Overworld] (restore inventory + rewards + wins++)
                          │
                          ├── death ──► [In Dungeon] (respawn at checkpoint or spawn, no inventory op)
                          ├── /dg leave ──► [Overworld] (restore inventory + 5-min cleanup timer)
                          ├── quit ──► [Offline] (restore inventory immediately, 5-min rejoin window)
                          └── join ──► < 5 min: re-enter | ≥ 5 min: stay in overworld

Data storage is split into two independent systems:

Data	Location	Format
Win counts	plugins/HimDungeons/<dungeon>/stats.yml	YAML (human-readable, editable)
Inventory backups	plugins/HimDungeons/backup.db	SQLite (WAL, synchronous=NORMAL)

Restoring an inventory can never affect win statistics, because the two live in separate files.

Crash recovery: on server startup, every ACTIVE backup row is marked PENDING_RESTORE. On player join, the fallback restore runs and deletes the row. A kill -9 or hard power loss never loses committed backups.

Death behavior: keepInventory decides whether items drop on death (vanilla gamerule). The plugin only picks the respawn location: checkpoint first, then dungeon spawn. Death never triggers an inventory restore.

---

In-Game Admin GUI

Rooms, doors, chests, spawn points, checkpoints, and configuration values are all editable through an in-game GUI. No hand-editing YAML required. Batch config editing lets you modify a key across every dungeon at once.

---

Commands

Command	Permission	Description
/dg start [dungeon] [mode]	himdungeons.start	Start a dungeon. Modes: single, multi, party
/dg leave	himdungeons.leave	Leave the current dungeon
/dg edit [dungeon]	himdungeons.admin	Open the admin GUI
/dg create <dungeon>	himdungeons.admin	Create a dungeon folder structure
/dg reload	himdungeons.admin	Reload global configuration

multi mode adds nearby sneaking players within 3 blocks. party mode requires the Parties plugin.

---

Configuration Sample

dungeonInstance:
  minRoomAmount: 5
  maxRoomAmount: 12
  dfsMaxDeep: 8
  startToBossRoomAmmount: "10 10"
  allowRoomReuse: false
  allowDoorReuse: false
  useAabb: true
  useBfsCheck: false
  disconnectedRoomDistance: 0
  keepInventory: false
  deepCloneInventory: false
  time: 0
  dungeonTime: 1200
  weather: clear
  difficulty: normal
  lobby: "world,0,64,0,0,0"
  bossType: ["zombie"]
  bossNbt: ["{Health:100.0f}"]
  rewards:
    vault: {}
    playerPoints: {}
    consoleCommands: []

keepInventory and deepCloneInventory are independent. Enable only keepInventory for “no drops in dungeon.” Enable only deepCloneInventory for “inventory isolation on enter/exit.” Both can coexist.

---

Compatibility

• Server: Bukkit 1.18+ (1.21.3+ recommended), Spigot, Bukkit, Paper Purpur.
• Java: 25+ (The newest version allows 17+)
• Soft dependencies (all optional): Vault (entry fees, reward money), PlaceholderAPI (placeholders), Parties (party mode), Slimefun (item usage gating), MythicMobs (custom bosses)

All soft dependencies degrade gracefully when absent.

---

Known Limitations

• Only Sponge Schematic v2 and v3 are supported. Legacy MCEdit .schematic files are not supported.
• Dungeon worlds use a void generator — no natural terrain or mobs.
• Bundled SQLite native libraries cover Linux x86_64 and Windows x86_64 only. ARM and macOS users must adjust the shade exclusions in pom.xml.
• After a hard crash, world folders (dungeon_<name>_<timestamp>) remain on disk and must be cleaned manually. Auto-scan cleanup is planned.

---