?
Host a serverModrinth App
Sign in
ModsResource PacksData PacksShadersModpacksPluginsServers
Settings
HimDungeons

HimDungeons

WorldEdit-free procedural dungeon generator. Any room size, shape, and door position. Native 3D stitching. Async tick-batched pasting. Crash-safe inventory backups via SQLite. No forced grid. No fixed door rules.

22downloads
0followers
22downloads
0followers

Links

Report issues View source

Tags

Creators

Details

Licensed GPL-3.0-only
Published yesterday
Updated 17 hours ago
All versions

4.0.0

Release
4.0.017 hours ago 6
Download

Compatibility

Minecraft: Java Edition
26.3
26.2
26.1.x
1.21.x
1.20.x
1.19.x
1.18.x
Platforms
Bukkit
Paper
Purpur

Changes

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你无权进入此地牢");
    }
});