HimDungeons v4.0 Release Notes

发布日期 / 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.hook package 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 via onXxx() / 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 attrs map, enabling cross-hook state sharing (e.g., passing theme info from AfterGenerate to RoomPasted).

钩子清单 / 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 Click clears a single type, or clears all hooks (useful for debugging and hot-reload scenarios).
操作在主线程完成，CopyOnWriteArrayList 保证与异步生成线程并发安全。
All operations run on the main thread; CopyOnWriteArrayList guarantees 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.spawnBossEntity now merges the MythicMobs and vanilla spawn paths; the BossSpawn hook fires before registration regardless of source, allowing arbitrary LivingEntity substitution.
fillChests 改用实例级 chestRandom，避免每条战利品 new Random() 的开销。
fillChests now uses a class-level chestRandom to avoid per-loot new Random() allocation.
DungeonSessionService.enter(...) 返回值改为 boolean，被 BeforeEnter 否决时调用方（DungeonGenerator / HimDungeons.startDungeonAsync）可以正确处理。
DungeonSessionService.enter(...) now returns boolean; callers (DungeonGenerator / HimDungeons.startDungeonAsync) can react properly when BeforeEnter vetoes.
所有 fireXxx 方法在列表为空时直接返回，热路径无额外开销。
All fireXxx methods 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 forceFinishDungeon was placed inside the players loop, causing redundant execution.
修复 DungeonGenerator.generate() 未创建 DungeonContext，导致 generateAsync() 内访问 hookContext.placedRooms 抛出 NullPointerException 的问题。
Fixed a NullPointerException in generateAsync() caused by generate() failing to initialize DungeonContext, resulting in null access on hookContext.placedRooms.
修复 DungeonInstance 缺乏 hookContext 引用，导致玩家级、Boss 级钩子无上下文可用的隐患。
Fixed a latent issue where DungeonInstance lacked a hookContext reference, 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.target in pom.xml along with the source/target of maven-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.yml requires no manual edits: missing tntExplosion / entityExplosion / blockExplosion entries are read as deny by 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 in config.yml.
新增地牢通过 /dg create 会自动写入全部默认项。
New dungeons created via /dg create will 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's onDisable and 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你无权进入此地牢");
    }
});

HimDungeons

4.0.0

Список изменений

HimDungeons v4.0 Release Notes

概览 / Overview

新增功能 / New Features

1. 钩子系统 / Hook System

钩子清单 / Hook List

2. GUI 钩子管理器 / GUI Hook Manager

3. 爆炸管控 / Explosion Control

改进 / Improvements

修复 / Bug Fixes

技术变更 / Technical Changes

升级说明 / Upgrade Notes

兼容性 / Compatibility

致谢 / Credits

附录：钩子最小示例 / Appendix: Minimal Hook Example

Файлы

Метаданные

Канал релиза

Номер версии

Загрузчики

Версии игры

Загрузок

Дата публикации

Загрузил

ID версии