HimDungeons 4.1 发布说明 / Release Notes

版本 / Version: 4.1.0 基线 / Base: 4.0.0 类型 / Type: 功能更新 + 修复 / Feature Update + Bug Fix

---

概述 / Overview

中文： 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.

---

一、国际化 / Internationalization

中文：

• 新增 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 LanguageManager with plugins/HimDungeons/lang/<code>.yml support
• Full zh_CN / en_US bilingual support, roughly 420 language keys
• Fallback chain: current language → en_US → zh_CN → raw key (with console WARN)
• New language.useClientLocale: true for per-player client-locale switching
• New /dg lang <code> command for live global language switching
• msgPrefix is now active: instance msgPrefix takes priority inside that dungeon world, falling back to global
• Fixed a bug where lang/*.yml was not released on upgrade for existing users (extractDefaultResources now handles lang files independently)
• All player-facing text, GUI titles, item lore, and console logs are key-based
• DebugUtil.debug output intentionally kept unchanged for troubleshooting

---

二、软依赖兼容性修复 / Soft Dependency Fixes

中文：

• 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 日志

English:

• MythicMobs: Reflection layer rewritten to support both v4 (io.lumine.xikage) and v5 (io.lumine.mythic) with auto-detection. Failures now log clearly instead of silently no-oping
• PlayerPoints: Tries String signatures (look/give/take(String, int)) first, then falls back to UUID overloads. take now uses its return value
• Vault: Null-check added for getRegistration(Economy.class) to avoid NPE when no economy plugin is present
• Parties: No longer a stub that "just sends a message"; uses Parties.getApi() to fetch online party members and notify each one. handlePartyConfirm now validates membership
• Slimefun: Emits a clear Debug log when the class is missing

---

三、新增配置项 / New Configuration Options

中文： 本次一次性落地了完整的 P0–P3 便民配置体系。

P0（可用性）

• respawnMode：死亡后 lobby / checkpoint / spectator
• deathCooldown：死亡复活冷却秒数
• playerCooldown：玩家再次进入冷却
• friendlyFire：友伤开关
• autoPickup：自动拾取
• teleportInvulnerable：传送后无敌秒数
• countdownWarn：限时倒计时提示点
• bossBar：Boss 顶部血条
• partyGlow：队友发光

P1（体验 / 难度 / 奖励）

• enterTitle / leaveTitle
• roomProgress / bossDirection / soundVolume / allowSpectatorAfterDeath
• scaleByPartySize / bossHealthMultiplierPerPlayer / mobSpawnRate / maxMobsPerRoom / timeoutAction
• rewards.firstClearBonus.* / rewards.shareMode / rewards.permissionMultiplier
• failurePenalty.* / 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 / spectator
• deathCooldown: respawn delay in seconds
• playerCooldown: re-entry cooldown
• friendlyFire: friendly fire toggle
• autoPickup: auto item pickup
• teleportInvulnerable: invulnerability seconds after teleport
• countdownWarn: time-limit warning checkpoints
• bossBar: top-of-screen boss health bar
• partyGlow: party member glow

P1 (Experience / Difficulty / Rewards)

• enterTitle / leaveTitle
• roomProgress / bossDirection / soundVolume / allowSpectatorAfterDeath
• scaleByPartySize / bossHealthMultiplierPerPlayer / mobSpawnRate / maxMobsPerRoom / timeoutAction
• rewards.firstClearBonus.* / rewards.shareMode / rewards.permissionMultiplier
• failurePenalty.* / stats.trackFastestTime

P2 (Operations)

• Global: configVersion / keepTestWorld / pasteSpeed / entityCleanupInterval / debugLogToFile / metrics / updateCheck

P3 (Advanced)

• roomFog: dynamic view distance by room size
• leaderboard: clear-time leaderboard
• bossPhase.*: HP-threshold boss phases
• lootTable.*: named loot tables
• minimap: config key reserved only (runtime not implemented)

---

四、新增命令与 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
• Fixed compile failure caused by non-existent Material.STRING

---

六、修复列表 / Bug Fixes

中文：

1. 老用户升级后 lang/*.yml 不再释放
2. Vault 未注册 Economy 时 NPE
3. PlayerPoints 仅使用 UUID 签名导致静默失效
4. MythicMobs v5 下 isMythicMob / spawnMythicMob 静默失效
5. Parties 模式只给自己发消息，队员收不到通知
6. DungeonStartGUI 用标题分发事件，i18n 后失效（改为 StartGuiHolder）
7. EditorGuiManager 使用不存在的 Material.STRING
8. DungeonBossListener 结束后未清理 BossBar / BossPhase 状态

English:

1. lang/*.yml no longer released on upgrade for existing users
2. NPE when Vault has no registered Economy provider
3. PlayerPoints silently failed with only UUID signatures
4. isMythicMob / spawnMythicMob silently failed on MythicMobs v5
5. Party mode only notified the initiator, not other members
6. DungeonStartGUI dispatched events by title, broken after i18n (now uses StartGuiHolder)
7. EditorGuiManager referenced non-existent Material.STRING
8. DungeonBossListener did not clean up BossBar / BossPhase state

---

七、配置迁移 / Config Migration

中文：

• 首次启动 4.1 时，ConfigMigrator 会：
  1. 在 config.yml 写入 configVersion: 1 及所有新增全局键
  2. 遍历所有 dungeonInstance 配置，补齐缺失键
• 不会覆盖已有值
• 迁移仅在 configVersion 低于目标版本时执行
• 升级日志会输出 Config upgraded from version X to Y
• 建议升级前备份整个 plugins/HimDungeons/

English:

• On first launch of 4.1, ConfigMigrator will:
  1. Write configVersion: 1 and all new global keys to config.yml
  2. Walk every dungeonInstance config and add missing keys
• Existing values are never overwritten
• Migration only runs when configVersion is below the target version
• Upgrade log prints Config upgraded from version X to Y
• Back up the entire plugins/HimDungeons/ before upgrading

---

八、升级指南 / Upgrade Guide

中文：

1. 停止服务器
2. 备份 plugins/HimDungeons/
3. 删除旧版 HimDungeons-4.0.jar，放入 HimDungeons-4.1.jar
4. 启动服务器
5. 检查控制台无 WARN / ERROR
6. 执行 /dg reload 让语言与配置生效
7. 执行 /dg validate <地牢名> 校验已有房间
8. 若原 config.yml 中 lang 为 zh_CN，无需改动

English:

1. Stop the server
2. Back up plugins/HimDungeons/
3. Remove old HimDungeons-4.0.jar, drop in HimDungeons-4.1.jar
4. Start the server
5. Check the console for WARN / ERROR
6. Run /dg reload to apply language and config
7. Run /dg validate <dungeon> to check existing rooms
8. If config.yml has lang: 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
• 服务端未安装上述软依赖时，对应功能自动降级

English:

• Paper / Spigot 1.20+ (Paper 1.21.3+ recommended)
• Java 17+
• No WorldEdit required
• 4.0 configs are fully compatible
• Soft deps: Vault / PlayerPoints / Parties / MythicMobs (v4+v5) / Slimefun / PlaceholderAPI
• Features gracefully degrade when soft deps are absent

---

十、已知限制 / Known Limitations

中文：

• minimap 仅保留配置键，运行时未实现（需要第三方地图插件或客户端资源包）
• lootTable 的 tables 和 bossPhase.phases 在 GUI 中只提示手动编辑 YAML，不提供完整可视化编辑
• roomFog 使用客户端视距，不依赖资源包，因此视觉上是"视距收缩"而非真正的雾效
• 控制台日志不做玩家侧语言切换，永远使用全局语言

English:

• minimap config key reserved only; runtime not implemented (requires third-party map plugin or client resource pack)
• lootTable.tables and bossPhase.phases show a hint to edit YAML manually in the GUI; no full visual editor
• roomFog uses client view distance, not a resource-pack fog effect; visually it's view-distance shrinking
• Console logs always use the global language, not the player's locale

---

十一、文档 / Documentation

中文： 随 4.1 一并发布完整 Wiki（中英双语），包含：

• 全部命令与权限
• 房间模板、门锚点、宝箱、出生点设置详解
• 全局配置与实例配置逐项说明
• 编辑器 GUI 使用指南
• 钩子系统与外部插件集成
• 多语言、软依赖、战利品表、Boss 分阶段、排行榜、房间迷雾
• 常见问题 FAQ

English: 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 的很多配置项直接来自你们的建议。

English: 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