HimDungeons
让房间决定它们如何连接。
HimDungeons 是一个适用于 Paper / Spigot / Bukkit 服务器的程序化地牢生成器,无需 WorldEdit。它在运行时构建地牢世界,并使用双向门锚算法将预制房间结构体拼接在一起。任何大小、任何形状、任何门位置的房间都可以连接——只要它们的门面对面相接即可。
为什么选择 HimDungeons?
大多数地牢插件强制你的房间遵循网格布局:统一的大小、固定在墙壁上的门、每个房间朝向相同的方向。你花几个小时建造一个 L 形房间,却发现门必须位于北墙的中点——蓝图就此报废。
HimDungeons 采取了不同的方法。每个房间声明其门的位置和朝向。生成器会找到正确的旋转和偏移量来连接任意两个房间。你建造你想要的;算法处理其余部分。
| 功能 | 典型的地牢插件 | HimDungeons |
|---|---|---|
| 房间大小 | 必须统一 | 任意大小 |
| 房间形状 | 多为矩形 | 任意形状(L 形、T 形、十字形、不规则) |
| 门位置 | 固定的墙壁位置 | 任意坐标 |
| 门大小 | 1×1 或固定 | 任意大小(1×1、3×3、5×5 拱门) |
| 垂直连接 | 很少支持 | 原生 3D (y+ / y-) |
| 房间文件夹布局 | 扁平,强制前缀 | 任意子目录深度 |
| WorldEdit | 硬性依赖 | 无依赖 |
| 异步加载 | 经常阻塞主线程 | Tick 批量处理,TPS 安全 |
核心算法:双向门锚定
每个房间在 _door.yml 文件中声明其门:
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}
在生成过程中,算法从当前房间获取一个可用的门 A(世界位置 P1,朝向 D1)。然后尝试放置候选房间 B 的每个门 (P2, D2),并测试所有四种旋转。当且仅当满足以下条件时,一对门连接成功:
P1 + D1 == P2 AND P2 + D2 == P1
从门 A 向外走一格正好落在门 B 上,从门 B 向外走一格正好落在门 A 上。两扇门相对而立,相互接触,且指向相反的方向。
这解锁了:
- 任意房间大小 —— 一个 3×3 的储藏室可以直接紧邻一个 50×50 的首领大厅,只要它们的门对齐即可。
- 任意房间形状 —— L 形、十字形、环形、不规则多边形均有效。算法只关心门的坐标和朝向,而不关心房间的轮廓。
- 任意门位置 —— 门不需要位于墙壁中心。角落的门完全合法。
- 任意门大小 —— 1×1 的门和 3×3 的拱门可以连接,因为算法匹配的是坐标和方向,而不是几何开口。
- 自动四向旋转 —— 候选房间会被旋转 0°、90°、180° 和 270° 直到门匹配。你无需为四个方向准备四种结构体变体。
- AABB 碰撞检测 —— 感知旋转的边界框确保新放置的房间永远不会与现有房间重叠。
门类型门控
门支持 type 字段。楼梯门只能连接到楼梯门,宏伟拱门只能连接到宏伟拱门,备用门只能连接到备用门。这允许你强制执行语义约束,例如“楼梯必须向下”或“宏伟拱门总是通向首领大厅”。
原生 3D 拼接
大多数地牢插件是 2D 的:房间仅在 XZ 平面上拼接,垂直移动意味着切换世界。HimDungeons 支持 y+(向上)和 y-(向下)的门朝向。当 y- 门连接到 y+ 门时,新房间被放置在当前房间下方,形成真正的垂直堆叠。
你可以建造:
- 多层地牢 —— 地面入口 → 地下墓穴 → 深层巢穴,使用一套结构体。
- 塔楼 —— 螺旋上升,每层一个
y+门。 - 垂直难度梯度 —— 玩家深入得越深,首领越强,由
structureChoose权重控制。
垂直门在 Y 轴旋转下是不变的,因此你只需要一个结构体用于上下连接。
自由文件组织
房间文件夹会被递归扫描。房间可以位于任何深度,路径本身即为唯一的房间标识符:
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 是配置中的房间名称。按章节、难度、主题或作者组织——由你决定。大型地牢保持整洁,版本控制易于审查。
无需 WorldEdit
HimDungeons 自带 SpongeSchematicReader 和 SpongeSchematicWriter(基于 Querz NBT 库),用于支持 Sponge Schematic v2 和 v3。方块旋转使用 Bukkit 原生的 BlockData.rotate(StructureRotation)。区域选择使用创造模式下的木镐作为操作员——无需外部插件。
这很重要:
- 插件 jar 包大约为 3.5 MB(NBT 和 SQLite 原生库已阴影打包),远小于 WorldEdit 堆栈。
- 服务器升级无需等待 WorldEdit 兼容性。
- WorldEdit 和 HimDungeons 不会互相拖累。
- 结构体格式可全局配置(
schematic.readFormat: auto | sponge_v2 | sponge_v3)。
从 WorldEdit 迁移?将现有的 .schem 文件放入 rooms/ 中——它们可以直接读取,因为 WorldEdit 默认以 Sponge v2 或 v3 格式保存。
异步 IO 和 Tick 批量粘贴
WorldEdit 粘贴是同步的。一个 30×20×30 的房间可能会使低端服务器停滞 100–500 毫秒。HimDungeons 将工作分为三个阶段:
- Async — 读取并解析
.schem文件。 - Async — 预计算每个方块位置及旋转后的
BlockData。 - 主线程,按刻批处理 — 每刻放置一批可配置的方块数,然后让出控制权。
// Tunable in AsyncPaster.java
private static final int BLOCKS_PER_TICK = 2000;
在粘贴大型房间时,服务器仍可正常运行。保存也是异步的:主线程读取方块数据,异步线程写入文件。
完整生命周期与崩溃安全性
玩家状态转换由单一的 DungeonSessionService 状态机处理:
[Overworld] ──enter──► [In Dungeon] ──finish──► [Overworld] (恢复物品栏 + 奖励 + 胜利次数++)
│
├── death ──► [In Dungeon] (在检查点或出生点重生,不操作物品栏)
├── /dg leave ──► [Overworld] (恢复物品栏 + 5分钟清理计时器)
├── quit ──► [Offline] (立即恢复物品栏,5分钟重新加入窗口)
└── join ──► < 5分钟: 重新进入 | ≥ 5分钟: 留在主世界
数据存储分为两个独立的系统:
| 数据 | 位置 | 格式 |
|---|---|---|
| 胜利计数 | plugins/HimDungeons/<dungeon>/stats.yml |
YAML(人类可读,可编辑) |
| 物品栏备份 | plugins/HimDungeons/backup.db |
SQLite(WAL 模式,synchronous=NORMAL) |
恢复物品栏绝不会影响胜利统计,因为两者存储在不同的文件中。
崩溃恢复: 服务器启动时,每个 ACTIVE 状态的备份行会被标记为 PENDING_RESTORE。玩家加入时,备用恢复机制会运行并删除该行。kill -9 或硬断电不会丢失已提交的备份。
死亡行为: keepInventory 决定是否在死亡时掉落物品(原版游戏规则)。插件仅选择重生位置:优先检查点,其次是地牢出生点。死亡永远不会触发物品栏恢复。
游戏内管理 GUI
房间、门、箱子、出生点和检查点以及配置值均可通过游戏内 GUI 进行编辑。无需手动编辑 YAML。批量配置编辑功能允许您一次性修改所有地牢中的某个键值。
命令
| 命令 | 权限 | 描述 |
|---|---|---|
/dg start [dungeon] [mode] |
himdungeons.start |
开始一个地牢。模式:single、multi、party |
/dg leave |
himdungeons.leave |
离开当前地牢 |
/dg edit [dungeon] |
himdungeons.admin |
打开管理 GUI |
/dg create <dungeon> |
himdungeons.admin |
创建地牢文件夹结构 |
/dg reload |
himdungeons.admin |
重新加载全局配置 |
以及更多...
multi 模式会将 3 格范围内潜行的附近玩家纳入其中。party 模式需要 Parties 插件支持。
配置示例
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 和 deepCloneInventory 是独立的。启用 keepInventory 可实现“地牢内不掉落物品”。启用 deepCloneInventory 可实现“进入/退出时的物品栏隔离”。两者可以同时存在。
兼容性
- 服务器: Bukkit 1.18+(推荐 1.21.3+),Spigot、Bukkit、Paper Purpur。
- Java: 25+(最新版本支持 21+)
- 软依赖(均为可选): Vault(入场费、奖励金钱)、PlaceholderAPI(占位符)、Parties(组队模式)、Slimefun(物品使用限制)、MythicMobs(自定义 Boss)
当缺少这些软依赖时,插件会优雅降级。
已知限制
- 仅支持 Sponge Schematic v2 和 v3。不支持传统的 MCEdit
.schematic文件。 - 地牢世界使用虚空生成器——没有自然地形或生物。
- 捆绑的 SQLite 原生库仅覆盖 Linux x86_64 和 Windows x86_64。ARM 和 macOS 用户必须在
pom.xml中调整 shade 排除项。 - 发生硬崩溃后,世界文件夹(
dungeon_<name>_<timestamp>)会保留在磁盘上,必须手动清理。计划添加自动扫描清理功能。
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
structureChooseweights.
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:
- Async — read and parse the
.schemfile. - Async — precompute every block position and rotated
BlockData. - 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 |
and more...
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 21+)
- 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
.schematicfiles 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.
下载 HimDungeons
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 HimDungeons
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 HimDungeons
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 HimDungeons
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 HimDungeons
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 HimDungeons
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
🚀 HimDungeons v5.0.0 史诗级更新:底层重构、生态开放与运维体验全面进化
这是一次具有里程碑意义的重大版本更新(v5.0.0)。我们不仅补全了历史更新中备受期待的 NMS 极致性能优化,还推翻了原有的房间生成与数据存储架构,全面走向“单文件配置化”、“数据持久化”与“生态开放化”。
✨ 重磅新特性 (New Features)
🚀 1. NMS 底层性能优化(历史更新补录)
- LevelChunkSection 直写粘贴:新增
NmsFastPaster快速粘贴技术,通过反射直接写入LevelChunkSection,绕过 Bukkit 繁琐的高度图与逐方块光源更新。将大型地牢的生成/粘贴耗时从数秒压缩至百毫秒级。 - Heightmap 强制重建:彻底修复快速粘贴导致的高度图失效问题(使用
Heightmap.primeHeightmaps)。修复后,地牢内的亡灵生物在白天不再异常燃烧,且恢复正常刷怪判定。 - 光照引擎精准刷新:通过反射调用
ThreadedLevelLightEngine的relight接口强制重算光照队列,解决了快速粘贴带来的“光照滞后”问题,无需频繁重载世界来修复光照。 - 固定出生点优化:
VoidChunkGenerator直接返回固定出生坐标0,64,0,跳过原版漫长的“安全出生点搜索”,将虚空世界创建时间从 5 秒降至约 100ms。
🧩 2. 生态开放:对外 API 与 PAPI 支持
-
全面接入 Bukkit Event:新增
com.him.dungeons.api.event包,对外暴露 14 个核心生命周期事件。外部插件或脚本现在可以监听玩家进出、Boss 生成/死亡、方块交互等,并支持通过setCancelled(true)直接否决玩家行为。Boss 生成时甚至支持替换实体。 -
PlaceholderAPI 扩展:完美支持计分板与 TAB。提供
in_dungeon、remaining_seconds、room_progress、boss_hp_percent等状态变量,以及wins_<dungeon>、rank_fastest_<dungeon>等统计变量。内置双重缓存机制,零延迟、不卡服。 -
PlaceholderAPI Expansion: Perfect support for scoreboards and TAB. Provides state variables like
in_dungeon,remaining_seconds,room_progress,boss_hp_percent, and stat variables likewins_<dungeon>,rank_fastest_<dungeon>. Built-in dual caching mechanism ensures zero latency and no server lag. -
脚本 API 补充:
DungeonAPI新增addDamageDealt、addMobsKilled等方法,方便外部战斗系统或脚本汇报数据。 -
Script API 新增内容:为
DungeonAPI添加了如addDamageDealt、addMobsKilled等方法,方便外部战斗系统或脚本上报数据。
🏗️ 3. Room Architecture Revolution: Single-File & Free Connection
- 配置归一化 (
<baseName>.yml):废弃了过往散落的_door.yml、_chest.yml。现在每个房间只有一份<baseName>.yml,将doors、chests、spawn等集中管理,清晰直观。 - Configuration Normalization (
<baseName>.yml): Deprecated scattered_door.ymland_chest.yml. Each room now has a single<baseName>.ymlmanagingdoors,chests,spawn, etc., clearly and intuitively. - 精确门配对约束 (
Connect Rules):支持通过allow/deny规则,精准规定某扇门只能与特定type(类型)、特定baseName(房间)或特定id(门编号)相连。支持单向 allow 与双向 deny 拦截。 - Precise Door Pairing Constraints (
Connect Rules): Supportsallow/denyrules to precisely specify that a door can only connect to a specifictype,baseName, or doorid. Supports unidirectional allow and bidirectional deny interception. - 多维用途标签 (
use):废弃硬编码前缀。可在 YAML 中自由设定房间属性(inStart/inBoss/inMainPath/inBranch/inFallback),同一个房间可以既做支线,又做普通房。 - Multi-dimensional Usage Tags (
use): Deprecated hardcoded prefixes. Room properties (inStart,inBoss,inMainPath,inBranch,inFallback) can be freely set in YAML. The same room can be used for both side paths and normal rooms. - 无感自动迁移:服务器启动时会自动扫描旧版碎片文件并打包迁移为新版单文件,服主无需手动干预。
- Seamless Auto-Migration: Automatically scans legacy fragmented files on startup and packages them into new single files. No manual intervention required from server owners.
📊 4. Leaderboard & Stats: SQLite Persistence
- 底层存储升级:通关记录改用 SQLite(WAL 模式)异步批量写入。不仅记录胜负,还完整记录耗时、队伍规模、总伤害、总承伤、击杀数、死亡数、综合得分等详尽数据。
- Storage Upgrade: Run records now use SQLite (WAL mode) with async batch writing. Records not just win/loss, but full details like duration, team size, total damage, damage taken, kills, deaths, and overall score.
- 三维排行榜 GUI:
/dg leaderboard焕新升级!支持 模式(最快/次数/得分) × 队伍规模(单人/双人/四人等) × 时间范围(总榜/周榜/月榜) 随心切换,点击即可查看“我的排名”。 - 3D Leaderboard GUI:
/dg leaderboardis completely upgraded! Supports switching between Mode (Fastest/Wins/Score) × Team Size (Solo/Duo/Quad, etc.) × Time Period (All/Weekly/Monthly). Click to view "My Rank." - 多维统计命令:
/dg stats me查看个人胜率与极速,/dg stats admin查看全服汇总,/dg stats export一键导出 CSV 供 Excel 分析。 - Multi-dimensional Stats Commands:
/dg stats mefor personal win rates and speed,/dg stats adminfor server-wide summary, and/dg stats exportto export CSV for Excel analysis.
🛠️ 5. Ops & Debugging Tools
- 实例管理 GUI (
/dg instances):服主专属面板。三层视图(总览 -> 详情 -> 踢人),可直观查看当前运行的地牢、玩家队伍、Boss 血量、房间进度,支持一键强制结束或踢出玩家。 - Instance Manager GUI (
/dg instances): Admin panel. 3-tier view (Overview -> Detail -> Kick), intuitively view running dungeons, player teams, Boss HP, room progress. Supports one-click force-end or kick. - 可视化调试框 (Display Entities):使用木镐选区时,自动生成单一拉伸的白色染色玻璃包围盒,内部透视完美辅助圈地。打开房间配置时,自动用高亮实体标记门(淡蓝+ID)、箱子(棕色)、出生点(金色)、存档点(蓝色)。
- Visual Debug Box (Display Entities): When selecting with a wooden pickaxe, a single stretched white stained glass bounding box is generated. Internal perspective perfectly assists in area selection. When opening room config, highlights doors (light blue + ID), chests (brown), spawn points (gold), and checkpoints (blue) using display entities.
🐛 Bug Fixes
- 修复强制结束导致脱管漏洞:彻底修复了在 GUI 中强制结束自己所在的地牢后,GUI 未同步关闭导致玩家能在无约束状态下操作界面的问题。现在传送前会强制关闭 GUI。
- Fixed Force-End Desync Bug: Completely fixed the issue where force-ending your own dungeon via the GUI left it open, allowing unconstrained interface operations. Now GUI is closed before teleporting.
- 修复单文件迁移连带问题:修复了出生点失效(总是跑到固定坐标)、箱子战利品不自动填充,以及编辑器内读写文件错乱的问题。现在全部精准指向
<baseName>.yml。 - Fixed Single-File Migration Issues: Fixed broken spawns (always teleporting to fixed coordinates), chest loot not auto-filling, and file read/write confusion in the editor. All now point precisely to
<baseName>.yml. - 修复 PAPI 未安装导致崩溃:当服务器未安装 PlaceholderAPI 时,主类不再报
NoClassDefFoundError崩溃,而是安全跳过注册。 - Fixed PAPI Missing Crash: No longer throws
NoClassDefFoundErrorif PlaceholderAPI is missing; safely skips registration instead.
⚠️ Upgrade & Migration Guide
- 配置备份 (Backup):升级前强烈建议完整备份
plugins/HimDungeons目录。 Highly recommend fully backing up theplugins/HimDungeonsdirectory before upgrading. - 自动迁移 (Auto-Migration):重启服务器后,控制台会打印
[自动迁移] 完成...,老房间会自动生成<baseName>.yml(旧文件保留防翻车)。 After restart, the console prints[Auto-Migration] Complete.... Old rooms will generate<baseName>.yml(old files are kept as a fallback). - 确认与清理 (Confirm & Clean):测试生成无误后,可手动删除旧的
_door.yml、_chest.yml等冗余文件。 After confirming generation works, you can manually delete old redundant files like_door.yml,_chest.yml. - 语言文件 (Language Files):请删除旧的
lang/zh_CN.yml与en_US.yml,让插件重新释放,或手动补全新增的统计、GUI 等相关文本。 Delete oldlang/zh_CN.ymlanden_US.ymlto let the plugin release new ones, or manually add the new stats/GUI texts.
📌 Compatibility & Dependencies
- 服务端版本 (Server Version):Spigot / Paper 1.20.5 ~ 1.21.3+
- 推荐软依赖 (Recommended Soft-Dependencies):Vault, PlayerPoints, PlaceholderAPI, MythicMobs
HimDungeons 4.1 发布说明
版本: 4.1.0 基线: 4.0.0 类型: 功能更新 + 修复
概述
中文:
4.1 是 HimDungeons 自 4.0 以来最大的一次更新,涵盖四大方向:完整国际化、软依赖兼容性修复、P0–P3 便民配置项落地、以及配套的 Wiki 文档。本次更新不破坏现有 4.0 配置,升级时由 ConfigMigrator 自动补齐所有新增键,旧地牢可直接运行。
English:
4.1 is the largest update to HimDungeons since 4.0, covering four major areas: full internationalization, soft-dependency compatibility fixes, implementation of P0–P3 quality-of-life configs, and accompanying Wiki documentation. Existing 4.0 configs remain compatible; ConfigMigrator automatically fills in all new keys on upgrade, so existing dungeons keep working out of the box.
一、国际化
中文:
- 新增
LanguageManager,支持plugins/HimDungeons/lang/<code>.yml多语言文件 - 完整支持
zh_CN/en_US双语,约 420 条语言 key - 语言回退链:当前语言 →
en_US→zh_CN→ key 原文(并在控制台 WARN) - 支持
language.useClientLocale: true,按玩家客户端语言自动切换 - 新增
/dg lang <code>命令,管理员可热切换全局语言 msgPrefix正式启用:优先使用玩家所在地牢实例的msgPrefix,回退全局- 修复老用户升级时
lang/*.yml不释放的 Bug(extractDefaultResources独立处理语言文件) - 所有玩家可见文本、GUI 标题、物品 lore、控制台日志全部 key 化
DebugUtil.debug调试输出保留原样,便于排查
English:
- New
LanguageManagerwithplugins/HimDungeons/lang/<code>.ymlsupport - Full
zh_CN/en_USbilingual support, roughly 420 language keys - Fallback chain: current language →
en_US→zh_CN→ raw key (with console WARN) - New
language.useClientLocale: truefor per-player client-locale switching - New
/dg lang <code>command for live global language switching msgPrefixis now active: instancemsgPrefixtakes priority inside that dungeon world, falling back to global- Fixed a bug where
lang/*.ymlwas not released on upgrade for existing users (extractDefaultResourcesnow handles lang files independently) - All player-facing text, GUI titles, item lore, and console logs are key-based
DebugUtil.debugoutput intentionally kept unchanged for troubleshooting
二、软依赖兼容性修复
中文:
- MythicMobs:重写反射层,同时兼容 v4(
io.lumine.xikage)与 v5(io.lumine.mythic),自动识别版本;生成失败时有明确 Debug 日志,不再静默失效 - PlayerPoints:优先尝试
String签名(look/give/take(String, int)),不存在时回退UUID重载;take使用返回值判断是否成功 - Vault:
getRegistration(Economy.class)增加判空,避免未装经济插件时的 NPE - Parties:不再是"只发消息"的半成品,通过
Parties.getApi()获取队伍在线成员,逐人推送确认提示;handlePartyConfirm增加校验 - Slimefun:类名缺失时输出明确的 Debug 日志
中文:
- MythicMobs:重写反射层以支持 v4 (
io.lumine.xikage) 和 v5 (io.lumine.mythic),并具备自动检测功能。失败时现在会清晰记录日志,而不是静默忽略 - PlayerPoints:优先尝试
String签名(look/give/take(String, int)),然后回退到UUID重载方法。take现在使用其返回值 - Vault:为
getRegistration(Economy.class)添加了空值检查,以避免在没有经济插件时出现 NPE(空指针异常) - Parties:不再是一个“仅发送消息”的存根;改用
Parties.getApi()获取在线小队成员并通知每一位成员。handlePartyConfirm现在会验证成员资格 - Slimefun:当类缺失时会输出清晰的调试日志
三、新增配置项 / New Configuration Options
中文: 本次一次性落地了完整的 P0–P3 便民配置体系。
P0(可用性)
respawnMode:死亡后lobby/checkpoint/spectatordeathCooldown:死亡复活冷却秒数playerCooldown:玩家再次进入冷却friendlyFire:友伤开关autoPickup:自动拾取teleportInvulnerable:传送后无敌秒数countdownWarn:限时倒计时提示点bossBar:Boss 顶部血条partyGlow:队友发光
P1(体验 / 难度 / 奖励)
enterTitle/leaveTitleroomProgress/bossDirection/soundVolume/allowSpectatorAfterDeathscaleByPartySize/bossHealthMultiplierPerPlayer/mobSpawnRate/maxMobsPerRoom/timeoutActionrewards.firstClearBonus.*/rewards.shareMode/rewards.permissionMultiplierfailurePenalty.*/stats.trackFastestTime
P2(运维)
- 全局:
configVersion/keepTestWorld/pasteSpeed/entityCleanupInterval/debugLogToFile/metrics/updateCheck
P3(进阶)
roomFog:房间迷雾(动态视距)leaderboard:通关排行榜bossPhase.*:Boss 血量分阶段lootTable.*:命名战利品表minimap:仅保留配置键(暂未实现运行时)
English: This release delivers the full P0–P3 quality-of-life config system in one pass.
P0 (Availability)
respawnMode:lobby/checkpoint/spectatordeathCooldown: respawn delay in secondsplayerCooldown: re-entry cooldownfriendlyFire: friendly fire toggleautoPickup: auto item pickupteleportInvulnerable: invulnerability seconds after teleportcountdownWarn: time-limit warning checkpointsbossBar: top-of-screen boss health barpartyGlow: party member glow
P1 (Experience / Difficulty / Rewards)
enterTitle/leaveTitleroomProgress/bossDirection/soundVolume/allowSpectatorAfterDeathscaleByPartySize/bossHealthMultiplierPerPlayer/mobSpawnRate/maxMobsPerRoom/timeoutActionrewards.firstClearBonus.*/rewards.shareMode/rewards.permissionMultiplierfailurePenalty.*/stats.trackFastestTime
P2(操作)
- 全局:
configVersion/keepTestWorld/pasteSpeed/entityCleanupInterval/debugLogToFile/metrics/updateCheck
P3(高级)
roomFog: 根据房间大小动态调整视距leaderboard: 通关时间排行榜bossPhase.*: 基于生命值阈值的 Boss 阶段lootTable.*: 命名的战利品表minimap: 仅保留配置键(运行时未实现)
四、新增命令与 API / New Commands & APIs
中文: 新增命令:
| 命令 | 权限 | 说明 |
|---|---|---|
/dg list |
himdungeons.admin |
列出运行中的地牢实例 |
/dg kick <玩家> |
himdungeons.admin |
强制踢出玩家 |
/dg forceend <世界> |
himdungeons.admin.world |
强制结束实例 |
/dg reload <地牢> |
himdungeons.admin |
单实例热重载 |
/dg validate <地牢> |
himdungeons.admin |
校验房间文件完整性 |
/dg lang <code> |
himdungeons.admin |
热切换语言 |
/dg setlobby <地牢> |
himdungeons.admin |
用当前位置设置大厅 |
/dg leaderboard [地牢] |
himdungeons.start |
排行榜 GUI |
新增内部管理器:
LanguageManager/PlayerCooldownManager/BossBarManager/EntityCleanupTask/ConfigMigrator/RoomValidator/RoomFogManager/BossPhaseManager/LeaderboardGui
English: New commands:
| Command | Permission | Description |
|---|---|---|
/dg list |
himdungeons.admin |
List running instances |
/dg kick <player> |
himdungeons.admin |
Force-kick a player |
/dg forceend <world> |
himdungeons.admin.world |
Force-end an instance |
/dg reload <dungeon> |
himdungeons.admin |
Hot-reload one instance |
/dg validate <dungeon> |
himdungeons.admin |
Validate room files |
/dg lang <code> |
himdungeons.admin |
Hot-switch language |
/dg setlobby <dungeon> |
himdungeons.admin |
Set lobby to current position |
/dg leaderboard [dungeon] |
himdungeons.start |
Leaderboard GUI |
New internal managers:
LanguageManager/PlayerCooldownManager/BossBarManager/EntityCleanupTask/ConfigMigrator/RoomValidator/RoomFogManager/BossPhaseManager/LeaderboardGui
五、编辑器 GUI 扩展 / Editor GUI Expansion
中文:
- 实例配置 GUI 从 27 格扩展到 54 格,容纳全部新增字段
- 新增交互类型:
- 枚举循环(重生模式 / 超时处理 / 分配模式 / 白黑名单)
- 浮点数输入(
mobSpawnRate/bossHealthMultiplierPerPlayer) - 嵌套结构提示(
bossPhase.phases/lootTable.tables)
- 新增字段已在各分类页就位:
- 生成算法:
scaleByPartySize/mobSpawnRate/maxMobsPerRoom - 世界规则:重生 / 冷却 / 无敌 / 倒计时 / 超时 / Title / 进度 / 音效 / 迷雾
- 玩家配置:
bossBar/partyGlow - Boss 配置:血量倍率 / 分阶段
- 经济与奖励:首通 / 分配 / 权限倍率 / 失败惩罚 / 排行榜 / 战利品表
- 生成算法:
- 顺带修复
Material.STRING不存在导致编译失败的问题
English:
- Instance config GUI expanded from 27 to 54 slots to hold all new fields
- New interaction types:
- Enum cycling (respawn mode / timeout action / share mode / whitelist-blacklist)
- Float input (
mobSpawnRate/bossHealthMultiplierPerPlayer) - Nested structure hints (
bossPhase.phases/lootTable.tables)
- All new fields placed in their category pages:
- Generation:
scaleByPartySize/mobSpawnRate/maxMobsPerRoom - World: respawn / cooldown / invulnerability / countdown / timeout / titles / progress / sound / fog
- Player:
bossBar/partyGlow - Boss: HP multiplier / phases
- Economy: first clear / share mode / permission multiplier / failure penalty / leaderboard / loot tables
- Generation:
- Fixed compile failure caused by non-existent
Material.STRING
六、修复列表 / Bug Fixes
中文:
- 老用户升级后
lang/*.yml不再释放 - Vault 未注册 Economy 时 NPE
- PlayerPoints 仅使用
UUID签名导致静默失效 - MythicMobs v5 下
isMythicMob/spawnMythicMob静默失效 - Parties 模式只给自己发消息,队员收不到通知
DungeonStartGUI用标题分发事件,i18n 后失效(改为StartGuiHolder)EditorGuiManager使用不存在的Material.STRINGDungeonBossListener结束后未清理 BossBar / BossPhase 状态
English:
lang/*.ymlno longer released on upgrade for existing users- NPE when Vault has no registered Economy provider
- PlayerPoints silently failed with only
UUIDsignatures isMythicMob/spawnMythicMobsilently failed on MythicMobs v5- Party mode only notified the initiator, not other members
DungeonStartGUIdispatched events by title, broken after i18n (now usesStartGuiHolder)EditorGuiManagerreferenced non-existentMaterial.STRINGDungeonBossListenerdid not clean up BossBar / BossPhase state
七、配置迁移 / Config Migration
中文:
- 首次启动 4.1 时,
ConfigMigrator会:- 在
config.yml写入configVersion: 1及所有新增全局键 - 遍历所有
dungeonInstance配置,补齐缺失键
- 在
- 不会覆盖已有值
- 迁移仅在
configVersion低于目标版本时执行 - 升级日志会输出
Config upgraded from version X to Y - 建议升级前备份整个
plugins/HimDungeons/
English:
- 首次启动 4.1 时,
ConfigMigrator将执行以下操作:- 向
config.yml写入configVersion: 1以及所有新的全局键值 - 遍历每个
dungeonInstance配置并补全缺失的键值
- 向
- 现有值永远不会被覆盖
- 仅当
configVersion低于目标版本时才执行迁移 - 升级日志会打印
Config upgraded from version X to Y(配置已从版本 X 升级至 Y) - 升级前请备份整个
plugins/HimDungeons/目录
八、升级指南 / Upgrade Guide
中文:
- 停止服务器
- 备份
plugins/HimDungeons/ - 删除旧版
HimDungeons-4.0.jar,放入HimDungeons-4.1.jar - 启动服务器
- 检查控制台是否有 WARN / ERROR 警告或错误
- 执行
/dg reload使语言与配置生效 - 执行
/dg validate <地牢名>校验已有房间 - 若原
config.yml中lang为zh_CN,无需改动
English:
- Stop the server
- Back up
plugins/HimDungeons/ - Remove old
HimDungeons-4.0.jar, drop inHimDungeons-4.1.jar - Start the server
- Check the console for WARN / ERROR
- Run
/dg reloadto apply language and config - Run
/dg validate <dungeon>to check existing rooms - If
config.ymlhaslang: zh_CN, no change needed
九、兼容性 / Compatibility
中文:
-
Paper / Spigot 1.20+(推荐 Paper 1.21.3+)
-
Java 17+
-
不依赖 WorldEdit
-
4.0 配置完全兼容
-
软依赖:Vault / PlayerPoints / Parties / MythicMobs (v4+v5) / Slimefun / PlaceholderAPI
-
服务端未安装上述软依赖时,对应功能自动降级
-
Paper / Spigot 1.20+(推荐使用 Paper 1.21.3+)
-
Java 17+
-
无需 WorldEdit
-
4.0 配置文件完全兼容
-
软依赖:Vault / PlayerPoints / Parties / MythicMobs (v4+v5) / Slimefun / PlaceholderAPI
-
当缺少软依赖时,功能会优雅降级
十、已知限制 / Known Limitations
Chinese:
minimap仅保留配置键,运行时未实现(需要第三方地图插件或客户端资源包)lootTable的tables和bossPhase.phases在 GUI 中只提示手动编辑 YAML,不提供完整可视化编辑roomFog使用客户端视距,不依赖资源包,因此视觉上是"视距收缩"而非真正的雾效- 控制台日志不做玩家侧语言切换,永远使用全局语言
英文:
minimap配置项仅保留;运行时未实现(需第三方地图插件或客户端资源包)lootTable.tables和bossPhase.phases在 GUI 中提示手动编辑 YAML;无完整可视化编辑器roomFog使用客户端视距,而非资源包雾效;视觉上表现为视距缩小- 控制台日志始终使用全局语言,而非玩家的语言环境
十一、文档 / Documentation
中文: 随 4.1 一并发布完整 Wiki(中英双语),包含:
- 全部命令与权限
- 房间模板、门锚点、宝箱、出生点设置详解
- 全局配置与实例配置逐项说明
- 编辑器 GUI 使用指南
- 钩子系统与外部插件集成
- 多语言、软依赖、战利品表、Boss 分阶段、排行榜、房间迷雾
- 常见问题 FAQ
英文: A complete bilingual Wiki ships with 4.1, covering:
- All commands and permissions
- Room templates, door anchors, chests, spawn points in detail
- Full global and instance config reference
- Editor GUI usage guide
- Hook system and plugin integration
- i18n, soft dependencies, loot tables, boss phases, leaderboards, room fog
- FAQ
十二、致谢 / Credits
中文: 感谢所有在 4.0 期间反馈 Issue、测试生成的服主与开发者。4.1 的很多配置项直接来自你们的建议。
英文: Thanks to every server owner and developer who filed issues and tested generation during 4.0. Many of 4.1's configs came directly from your feedback.
下载 / Download: HimDungeons-4.1.jar
完整变更 / Full Changelog: 见 Wiki 与 Git 提交历史 / See Wiki and git history
HimDungeons v4.0 发布说明
发布日期 / Release Date: 2026-10-24
概览 / Overview
v4.0 引入了一套运行时可插拔的钩子系统,允许外部插件在不修改本插件源码的前提下,在地牢生命周期的各个阶段注入自定义逻辑。同时新增了方块爆炸/TNT/实体爆炸三档管控、GUI 钩子管理器,并将编译目标降至 Java 17 以覆盖更多服务端环境。
v4.0 introduces a runtime-pluggable hook system, allowing external plugins to inject custom logic at every stage of a dungeon's lifecycle without modifying this plugin's source code. It also adds three-tier explosion control (TNT / entity / block), a GUI hook manager, and lowers the compilation target to Java 17 for broader server compatibility.
新增功能 / New Features
1. 钩子系统 / Hook System
-
新增
com.him.dungeons.api.hook包,共 22 个强类型函数式接口,覆盖实例级、房间级、玩家级、Boss 级四个层级。 -
Added the
com.him.dungeons.api.hookpackage containing 22 strongly-typed functional interfaces spanning four levels: instance, room, player, and boss. -
所有钩子通过
HimDungeons.getInstance().getHookRegistry()获取注册中心,支持onXxx()/offXxx()增量管理。 -
All hooks are managed through
HimDungeons.getInstance().getHookRegistry(), supporting incremental registration viaonXxx()/offXxx(). -
触发点遵循注册顺序依次调用,单个钩子抛异常会被隔离,不影响其他钩子与地牢主流程。
-
Hooks fire in registration order; exceptions from a single hook are isolated and never affect other hooks or the main dungeon flow.
-
上下文对象提供
attrs(线程安全 Map),供跨钩子之间共享状态(例如从AfterGenerate向RoomPasted传递主题信息)。 -
Every hook receives a context object with a thread-safe
attrsmap, enabling cross-hook state sharing (e.g., passing theme info fromAfterGeneratetoRoomPasted).
钩子清单 / Hook List
| 分组 / Group | 钩子 / Hook | 触发时机 / Timing |
|---|---|---|
| L1 实例级 / Instance | BeforeCreateWorld |
世界创建前 / Before world creation |
| L1 | AfterCreateWorld |
世界创建并应用设置后 / After world creation + settings applied |
| L1 | BeforeGenerate |
异步生成任务开始 / Async generation starts |
| L1 | AfterGenerate |
全部房间放置完成、未粘贴 / All rooms placed, not yet pasted |
| L1 | BeforePaste |
即将开始粘贴 / Paste about to start |
| L1 | AfterPaste |
粘贴全部完成 / All pasting done |
| L1 | DungeonReady |
实例就绪、玩家传送前 / Instance ready, before player teleport |
| L1 | BeforeDestroy |
世界销毁前 / Before world destruction |
| L1 | AfterDestroy |
世界销毁并清理完毕 / After world destruction + cleanup |
| L2 房间级 / Room | RoomSelect |
选中房间模板时(可否决 / 重定向)/ When selecting a room template (veto / redirect) |
| L2 | RoomPlaced |
房间加入已放置列表 / Room added to placed list |
| L2 | RoomPasted |
单房间粘贴完成 / Single room paste complete |
| L2 | ChestFill |
单条战利品填充前(可改物品/数量/概率)/ Before each loot item fills (item/amount/chance editable) |
| L3 玩家级 / Player | BeforeEnter |
进入前(可否决)/ Before entering (cancellable) |
| L3 | AfterEnter |
进入后 / After entering |
| L3 | BeforeLeave |
离开前(可否决)/ Before leaving (cancellable) |
| L3 | AfterLeave |
离开后 / After leaving |
| L3 | Finish |
通关结算完成 / After completion rewards are granted |
| L3 | Offline |
玩家离线 / Player went offline |
| L3 | Online |
玩家重新上线并重入成功 / Player rejoined and re-entered |
| L4 Boss 级 / Boss | BossSpawn |
Boss 生成后、注册前(可替换实体)/ After boss spawns, before registration (replaceable) |
| L4 | BossDefeat |
Boss 击杀时(可否决结算)/ When boss dies (settlement cancellable) |
2. GUI 钩子管理器 / GUI Hook Manager
-
主编辑页面新增"钩子管理"入口,按 L1–L4 分组展示 22 类钩子的实时注册数量。
-
Added a "Hook Manager" entry to the main editor GUI, showing live registration counts for all 22 hook types grouped by L1–L4.
-
点击任一类型进入详情页,可查看该类下每条钩子的来源类名、序号,并支持逐条删除。
-
Clicking a hook type opens a detail page showing the source class name and index of each hook, with per-hook deletion.
-
支持
Shift + 左键清空单类,或清空全部钩子(用于调试与热重载场景)。 -
Shift + Left Clickclears a single type, or clears all hooks (useful for debugging and hot-reload scenarios). -
操作在主线程完成,
CopyOnWriteArrayList保证与异步生成线程并发安全。 -
All operations run on the main thread;
CopyOnWriteArrayListguarantees concurrency safety with the async generation thread.
3. 爆炸管控 / Explosion Control
新增三项独立的地牢级爆炸配置,每项可选择三档之一:
Added three independent per-dungeon explosion settings, each with a three-way mode:
| 配置键 / Key | 管控对象 / Target | 默认 / Default |
|---|---|---|
dungeonInstance.tntExplosion |
TNT、TNT 矿车 / TNT, TNT Minecart | deny |
dungeonInstance.entityExplosion |
苦力怕、恶魂火球、凋灵、末影水晶等 / Creeper, Ghast fireball, Wither, End Crystal, etc. | deny |
dungeonInstance.blockExplosion |
床、重生锚等方块爆炸 / Bed, Respawn Anchor, other block explosions | deny |
三种模式 / Three Modes:
-
allow—— 完全允许,方块破坏与实体伤害均保留。 -
allow— Fully allowed: block destruction and entity damage both apply. -
damage_only—— 仅造成伤害,方块不被破坏(blockList().clear())。 -
damage_only— Damage only: blocks are not destroyed (blockList().clear()). -
deny—— 完全禁止(setCancelled(true));TNT/实体爆炸在引信阶段即被拦截,方块爆炸在事件发生时拦截。 -
deny— Fully forbidden (setCancelled(true)); TNT/entity explosions are intercepted at prime time, block explosions at event time.
GUI 中三项均以点击循环切换方式操作,Lore 实时显示当前模式的中文描述(完全允许 / 仅造成伤害 / 完全禁止)。
In the GUI, all three entries cycle through modes on click, with Lore showing the current mode's localized label.
改进 / Improvements
-
DungeonGenerator.spawnBossEntity合并 MythicMobs 与原版生成路径,统一在注册前触发BossSpawn钩子,外部可替换任意LivingEntity。 -
DungeonGenerator.spawnBossEntitynow merges the MythicMobs and vanilla spawn paths; theBossSpawnhook fires before registration regardless of source, allowing arbitraryLivingEntitysubstitution. -
fillChests改用实例级chestRandom,避免每条战利品new Random()的开销。 -
fillChestsnow uses a class-levelchestRandomto avoid per-lootnew Random()allocation. -
DungeonSessionService.enter(...)返回值改为boolean,被BeforeEnter否决时调用方(DungeonGenerator/HimDungeons.startDungeonAsync)可以正确处理。 -
DungeonSessionService.enter(...)now returnsboolean; callers (DungeonGenerator/HimDungeons.startDungeonAsync) can react properly whenBeforeEntervetoes. -
所有
fireXxx方法在列表为空时直接返回,热路径无额外开销。 -
All
fireXxxmethods return immediately when their list is empty, adding zero overhead on hot paths.
修复 / Bug Fixes
-
修复
forceFinishDungeon中世界删除与清理逻辑被错误地写在players循环体内,导致多次执行的问题。 -
Fixed an issue where world deletion and cleanup logic in
forceFinishDungeonwas placed inside theplayersloop, causing redundant execution. -
修复
DungeonGenerator.generate()未创建DungeonContext,导致generateAsync()内访问hookContext.placedRooms抛出NullPointerException的问题。 -
Fixed a
NullPointerExceptioningenerateAsync()caused bygenerate()failing to initializeDungeonContext, resulting in null access onhookContext.placedRooms. -
修复
DungeonInstance缺乏hookContext引用,导致玩家级、Boss 级钩子无上下文可用的隐患。 -
Fixed a latent issue where
DungeonInstancelacked ahookContextreference, leaving player-level and boss-level hooks without context.
技术变更 / Technical Changes
-
编译目标 / Compilation target:由 Java 25 调整为 Java 17,兼容主流 LTS 服务端(Paper 1.20.x / 1.21.x 均默认运行在 Java 17+)。
-
Compilation target: lowered from Java 25 to Java 17 for compatibility with mainstream LTS server runtimes (Paper 1.20.x / 1.21.x all run on Java 17+).
-
pom.xml中maven.compiler.source、maven.compiler.target与maven-compiler-plugin的source/target同步变更。 -
Updated
maven.compiler.source,maven.compiler.targetinpom.xmlalong with thesource/targetofmaven-compiler-plugin. -
无新增依赖,无 shade 配置变更,二进制体积与 v3.0 持平。
-
No new dependencies, no shade-configuration changes, binary size remains on par with v3.0.
升级说明 / Upgrade Notes
-
旧地牢的
config.yml无需手动修改:缺失的tntExplosion/entityExplosion/blockExplosion三项会在读取时按默认值deny处理(保守策略,与 v3.0 的默认体验一致)。 -
Existing dungeons'
config.ymlrequires no manual edits: missingtntExplosion/entityExplosion/blockExplosionentries are read asdenyby default (conservative, matching v3.0 behavior). -
如需在 GUI 中看到并修改这三项,请打开
/dg edit <地牢> config world页面,或在config.yml中手动补充。 -
To view and edit these three settings in the GUI, open
/dg edit <dungeon> config world, or add the entries manually inconfig.yml. -
新增地牢通过
/dg create会自动写入全部默认项。 -
New dungeons created via
/dg createwill automatically include all default entries. -
依赖 HimDungeons 的第三方插件可在
onEnable中注册钩子;本插件onDisable时会清空所有已注册钩子,重启后需重新注册。 -
Third-party plugins depending on HimDungeons can register hooks in
onEnable; all registered hooks are cleared on this plugin'sonDisableand must be re-registered after restart.
兼容性 / Compatibility
-
服务端 / Server:Paper 1.21.3(API),理论兼容 Spigot/Paper 1.20.6+。
-
Server: Paper 1.21.3 (API); theoretically compatible with Spigot/Paper 1.20.6+.
-
Java:17 及以上。
-
Java: 17 or higher.
-
软依赖 / Soft Dependencies:Vault、PlayerPoints、Slimefun、MythicMobs、Parties、PlaceholderAPI —— 全部可选,未安装时自动降级。
-
Soft Dependencies: Vault, PlayerPoints, Slimefun, MythicMobs, Parties, PlaceholderAPI — all optional, gracefully degrade when absent.
-
不再依赖 WorldEdit(自 v3.0 起改用 Querz NBT 直接读写 Sponge 原理图)。
-
WorldEdit is no longer required (since v3.0, Sponge schematics are read/written directly via Querz NBT).
致谢 / Credits
感谢所有在 v4.0 开发过程中提供反馈与测试的社区成员。
Thanks to all community members who provided feedback and testing during v4.0 development.
附录:钩子最小示例 / Appendix: Minimal Hook Example
DungeonHookRegistry hooks = HimDungeons.getInstance().getHookRegistry();
// 进入地牢后发标题 / Show title after entering
hooks.onAfterEnter(ctx -> {
var p = ctx.player;
p.sendTitle("§c§l" + ctx.dungeon.dungeonName, "§7活下去", 10, 60, 20);
});
// 20% 概率把普通房间替换成高危版本 / 20% chance to swap normal rooms
hooks.onRoomSelect(ctx -> {
if ("normal".equals(ctx.poolType) && Math.random() < 0.2) {
ctx.baseName = "combat/hardVariant";
}
});
// 拦截无权限玩家进入 / Block unauthorized entry
hooks.onBeforeEnter(ctx -> {
if (!ctx.player.hasPermission("dungeon.enter")) {
ctx.cancelled = true;
ctx.player.sendMessage("§c你无权进入此地牢");
}
});
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
插件
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
插件
SkyBlock、OneBlock、Boxed、SkyGrid、AcidIsland、CaveBlock、Poseidon、StrangerRealms——以及更多!这些只是由 BentoBox 支持的基于岛屿的游戏模式之一。来自原版 ASkyBlock 的作者。
插件
一个高度兼容、功能完善且稳定的 TPA 模组
插件
在 Minecraft 中加入“最后一击”、“第二次机会”和“最后喘息”机制!从高处坠落时,你将拥有 0.5 HP 而不是直接死亡;当生命值较低时,增强你的能力。
插件
更快速的直线轨道矿车、链式连接列车、熔炉机车,以及原版红石信号!
插件
城镇现在可以要求建造具有特定功能的建筑
评论 0
登录后参与评分
还没有评论,来抢沙发吧