Skip to content

Home

Jump to bottom
Himxh edited this page Oct 30, 2026 · 1 revision

HimDungeons 插件 Wiki / Plugin Wiki

程序化地牢生成器 Procedural Dungeon Generator

目录 / Table of Contents

  1. 插件简介 / Introduction
  2. 安装 / Installation
  3. 目录结构 / Directory Structure
  4. 命令 / Commands
  5. 权限 / Permissions
  6. 快速开始 / Quick Start
  7. 房间设置 / Room Setup
  8. 全局配置 / Global Config
  9. 实例配置 / Instance Config
  10. 编辑器 GUI / Editor GUI
  11. 钩子 / Hooks
  12. 多语言 / i18n
  13. 软依赖 / Soft Dependencies
  14. 高级功能 / Advanced
  15. 常见问题 / FAQ

1. 插件简介 / Introduction

中文： HimDungeons 是一个程序化地牢生成器。你准备一堆房间模板（.schem + _door.yml），插件运行时用深度优先 + 广度优先算法随机拼接房间，生成从 start 到 boss 的主路径和分支，未连通的门用 fallback 封堵，最终在独立虚空世界里粘贴出完整地牢并传送玩家进入。

English: HimDungeons is a procedural dungeon generator. You prepare room templates (.schem + _door.yml), and the plugin randomly stitches them together at runtime using DFS + BFS algorithms to build a main path from start to boss plus branches. Unconnected doors are sealed with fallback rooms. The final dungeon is pasted into an isolated void world and players are teleported in.

核心特性 / Key Features：

  • 自动房间拼接，每次不同 / Automatic room stitching, unique every run
  • Sponge v2/v3 原理图，不依赖 WorldEdit / Sponge v2/v3 schematics, no WorldEdit dependency
  • 每实例独立配置 / Per-instance config
  • 23 个生命周期钩子 / 23 lifecycle hooks
  • SQLite 背包备份 / SQLite inventory backup
  • 中英双语 + 客户端语言自动切换 / Bilingual + client-locale switching
  • 完整 GUI 编辑器 / Full GUI editor

2. 安装 / Installation

中文：

要求：Paper/Spigot 1.20+，Java 21+。 把 HimDungeons-4.0.jar 放进 plugins/，启动服务器即可。首次启动会自动生成 config.yml、lang/、example_dungeon/、backup.db。

English:

Requirements: Paper/Spigot 1.20+, Java 21+. Drop HimDungeons-4.0.jar into plugins/ and start the server. On first launch it generates config.yml, lang/, example_dungeon/, and backup.db.

验证 / Verify:

/dg help

3. 目录结构 / Directory Structure

中文：

plugins/HimDungeons/
├── config.yml              全局配置 / Global config
├── backup.db               背包备份 / Inventory backup
├── lang/
│   ├── zh_CN.yml
│   └── en_US.yml
└── <地牢名>/
    ├── config.yml          实例配置 / Instance config
    ├── stats.yml           通关统计 / Stats
    ├── code/               脚本 / Scripts
    └── rooms/              房间 / Rooms
        ├── start/*.schem
        ├── boss/*.schem
        ├── fallback/*.schem
        └── 其他普通房间 / normal rooms

English:

Room files per room / 每个房间的文件：

  • xxx.schem / xxx.schematic — 原理图本体 / schematic body
  • xxx_door.yml — 门锚点 / door anchors
  • xxx_chest.yml — 宝箱 / chest loot
  • xxx_spawn.yml — 出生点 / spawn point (start / boss)
  • xxx_checkpoint.yml — 存档点 / checkpoint (normal rooms)

房间类型由前缀决定 / Room type determined by prefix:

  • start* 起始房 / start room
  • boss* Boss 房 / boss room
  • fallback* 封堵房 / fallback room
  • 其他 / others → 普通房 / normal room

子目录递归扫描，rooms/combat/a.schem 的 baseName 为 combat/a。 Subdirectories are scanned recursively; rooms/combat/a.schem → baseName combat/a.

4. 命令 / Commands

**中文：**主命令 /dg，别名 /dungeon、/himdungeons。 English: Main command /dg, aliases /dungeon, /himdungeons.

玩家命令 / Player Commands

命令 / Command 权限 / Permission 说明 / Description
/dg start himdungeons.start 打开选择 GUI / Open selection GUI
/dg start <地牢> himdungeons.start 单人进入 / Enter solo
/dg start <地牢> multi himdungeons.start 附近 3 格潜行玩家组队 / Group nearby sneaking players
/dg start <地牢> party himdungeons.start 通过 Parties 组队 / Party via Parties
/dg start party confirm himdungeons.start 确认加入 / Confirm join
/dg leave himdungeons.leave 离开 / Leave
/dg leaderboard <地牢> himdungeons.start 排行榜 / Leaderboard
/dg help — 帮助 / Help

管理员命令 / Admin Commands

命令 / Command 权限 / Permission 说明 / Description
/dg edit himdungeons.admin.gui 打开编辑器 / Open editor
/dg edit .RootConfig himdungeons.admin.edit 全局配置 / Global config
/dg edit .RoomList himdungeons.admin.gui 地牢列表 / Dungeon list
/dg edit <地牢> himdungeons.admin.gui 实例编辑 / Edit instance
/dg edit <地牢> config <分类> himdungeons.admin.edit 分类配置 / Category config
/dg edit <地牢> roomConfig himdungeons.admin.edit 房间配置 / Room config
/dg edit <地牢> codeFiles himdungeons.admin.edit 脚本文件 / Script files
/dg create <地牢> himdungeons.admin 创建新地牢 / Create dungeon
/dg reload himdungeons.admin 重载全部 / Reload all
/dg reload <地牢> himdungeons.admin 重载单个 / Reload one
/dg list himdungeons.admin 运行中实例 / Running instances
/dg kick <玩家> himdungeons.admin 踢出玩家 / Kick player
/dg forceend <世界> himdungeons.admin.world 强制结束 / Force end
/dg validate <地牢> himdungeons.admin 校验房间 / Validate rooms
/dg lang <code> himdungeons.admin 切语言 / Switch language
/dg setlobby <地牢> himdungeons.admin 用当前位置设大厅 / Set lobby to current position
/dg blockpos <x> <y> <z> himdungeons.admin 相对坐标（调试） / Relative pos (debug)

5. 权限 / Permissions

**中文：**权限节点如下。 English: Permission nodes below.

himdungeons.start               默认 true / default true
himdungeons.leave               默认 true / default true
himdungeons.admin               默认 op / default op
  ├── himdungeons.admin.gui     只读 GUI / read-only GUI
  ├── himdungeons.admin.edit    修改配置 / edit config
  └── himdungeons.admin.world   测试世界 / test worlds
himdungeons.*                   全部 / everything

6. 快速开始 / Quick Start

中文：

  1. /dg create mydungeon 创建目录。
  2. 准备 4 个房间：start、boss、1~2 个普通、1 个 fallback。
  3. 创造模式 + OP，拿木镐，左键点角 1，右键点角 2。
  4. /dg edit mydungeon → 添加房间 → 输入基础名（如 start/main）→ 自动导出 .schem。
  5. 对准门锚点方块 → 添加门锚点 → 输入 start/main z+ default 10。
  6. 用玩家当前位置添加 _spawn.yml（start 必须有，boss 也需要）。
  7. 编辑 structureChoose 分配权重。
  8. /dg edit mydungeon → 生成测试世界 → 验证拼接。
  9. /dg start mydungeon。

English:

  1. Run /dg create mydungeon.
  2. Prepare 4 rooms: start, boss, 1–2 normal, 1 fallback.
  3. Creative + OP, hold a wooden pickaxe, left-click corner 1, right-click corner 2.
  4. /dg edit mydungeon → Add Room → enter base name (e.g. start/main) → auto-exports .schem.
  5. Aim at a door anchor block → Add Door Anchor → enter start/main z+ default 10.
  6. Add _spawn.yml using your current position (start and boss both need one).
  7. Edit structureChoose to assign weights.
  8. /dg edit mydungeon → Generate Test World → verify stitching.
  9. /dg start mydungeon.

7. 房间设置 / Room Setup

7.1 门锚点 / Door Anchors

**中文：**门锚点格式： English: Door anchor format:

doors:
  - x: 3
    y: 1
    z: 7
    facing: z+
    type: default
    weight: 10
字段 / Field 中文说明 English
x/y/z 相对选区 min 角坐标 Relative to selection min corner
facing 门朝向 x+/x-/y+/y-/z+/z- Door facing
type 门类型，同类型才对接 Door type; only same types connect
weight 被选中权重，默认 10 Weight for selection, default 10

**中文：**拼接规则：A.anchor + facingA = B.anchor 且 B.anchor + facingB = A.anchor。即两锚点相邻、朝向相反。 English: Matching rule: A.anchor + facingA = B.anchor AND B.anchor + facingB = A.anchor. i.e. anchors adjacent and facings opposite.

7.2 宝箱 / Chests

中文：_chest.yml 格式： English: _chest.yml format:

chests:
  - pos: [3, 1, 5]
    loot: "50 DIAMOND 1"
  - pos: [4, 1, 5]
    loot: "@common"
  - pos: [7, 8, 9]
    loot: "@rare 2"

中文：loot 格式：<概率 0-100> <Material 名> [数量]；支持 @表名 [数量] 引用战利品表。 English: loot format: <chance 0-100> <Material> [amount]; supports @table [count] to reference loot tables.

7.3 出生点 / Spawn Points

**中文：**start 和 boss 房间都需要 _spawn.yml；普通房间可选 _checkpoint.yml。 English: Both start and boss rooms need _spawn.yml; normal rooms may have _checkpoint.yml.

spawn:
  x: 5
  y: 1
  z: 5

7.4 房间权重 / Room Weights

中文：structureChoose 控制每种房间被抽中的概率，键为 baseName，值越大越常出现。 English: structureChoose controls room pick probabilities; keys are baseNames, larger values appear more often.

dungeonInstance:
  structureChoose:
    start/main: 100
    combat/straight: 80
    combat/corner: 60
    boss/final: 100
    fallback/wall: 10

7.5 生成算法 / Generation Algorithm

**中文：**主路径从 start 深度优先扩展至 startToBossRoomAmmount 下限后接 boss；分支从主路径所有空门出发广度优先扩展至 maxRoomAmount 或 dfsMaxDeep 深度；剩余空门用 fallback 封堵。 English: Main path extends DFS from start until reaching the lower bound of startToBossRoomAmmount, then attaches boss; branches expand BFS from every unused door on the main path until maxRoomAmount or dfsMaxDeep depth; remaining doors are sealed with fallback.

8. 全局配置 / Global Config

中文：config.yml 关键项： English: Key entries in config.yml:

configVersion: 1          # 配置版本 / config version (do not edit)
lang: zh_CN               # 全局语言 / global language
msgPrefix: "&a[HimDungeons] &r"
language:
  useClientLocale: false  # 按客户端语言自动切换 / auto switch by client locale
generateCooldown: 0       # 生成冷却秒 / generate cooldown (s)
scanAndRegisterNewRooms: true
keepTestWorld: false      # 保留测试世界 / keep test world
pasteSpeed: 2000          # 每 tick 粘贴方块数 / blocks per tick
entityCleanupInterval: 300# 实体清理秒 / entity cleanup (s)
debugLogToFile: false
metrics: true
updateCheck: true
schematic:
  readFormat: auto        # auto/sponge_v2/sponge_v3
  saveFormat: sponge_v3
键 / Key 默认 / Default 中文说明 English
configVersion 1 配置版本，自动迁移 config version, auto-migrated
lang zh_CN 语言文件代码 language file code
msgPrefix &a[HimDungeons] &r 全局前缀 global prefix
language.useClientLocale false 按客户端语言切换 switch by client locale
generateCooldown 0 全局生成冷却 global generate cooldown
scanAndRegisterNewRooms true 每 10 秒扫描房间 scan rooms every 10s
keepTestWorld false 保留测试世界 keep test world
pasteSpeed 2000 粘贴性能调优 paste performance tuning
entityCleanupInterval 300 实体清理间隔 entity cleanup interval
debugLogToFile false Debug 输出到文件 Debug output to file
metrics true bStats 统计 bStats metrics
updateCheck true 检查新版本 check for updates
schematic.readFormat auto 读取格式 read format
schematic.saveFormat sponge_v3 保存格式 save format

9. 实例配置 / Instance Config

**中文：**每个地牢的 config.yml 都有 dungeonInstance 根节点，所有键可选，缺失时自动补默认值。 English: Every dungeon's config.yml has a dungeonInstance root node; all keys are optional and defaults are auto-migrated.

9.1 基础 / Basic

dungeonInstance:
  enable: true
  displayName: "示例地牢"
  fileName: "example_dungeon"
  msgPrefix: "&a[示例] &r"     # 实例前缀 / instance prefix
  lobby: "world,0,64,0,0,0"

**中文：**推荐使用 /dg setlobby <地牢名> 命令设置大厅，会自动写入 world,x,y,z,yaw,pitch。 English: Use /dg setlobby <dungeon> to set the lobby; it automatically writes world,x,y,z,yaw,pitch.

9.2 生成算法 / Generation

dungeonInstance:
  minRoomAmount: 5
  maxRoomAmount: 12
  dfsMaxDeep: 8
  useBfsCheck: false
  useAabb: true
  disconnectedRoomDistance: 0
  allowRoomReuse: false
  allowDoorReuse: false
  allowFallbackDoorReuse: false
  startToBossRoomAmmount: "10 10"
  blockRoomGenerateBlocks: []
  generatorChoose: []
  scaleByPartySize: true
  mobSpawnRate: 1.0
  maxMobsPerRoom: 30
键 / Key 默认 / Default 中文说明 English
minRoomAmount 5 分支最小房间数 min rooms for branches
maxRoomAmount 12 总房间上限（不含 fallback） max rooms (excl. fallback)
dfsMaxDeep 8 分支最大深度 max branch depth
useBfsCheck false 生成后连通性检查 post-generation connectivity check
useAabb true 用 AABB 检测重叠 use AABB for overlap detection
disconnectedRoomDistance 0 房间最小间距（关 AABB 时生效） min room distance (when AABB off)
allowRoomReuse false 允许房间模板复用 allow template reuse
allowDoorReuse false 允许门复用 allow door reuse
allowFallbackDoorReuse false 允许 fallback 门复用 allow fallback door reuse
startToBossRoomAmmount "10 10" 主路径房间数范围 main path room count range
blockRoomGenerateBlocks [] 冲突方块类型（关 AABB 时生效） conflicting blocks (when AABB off)
generatorChoose [] 按类型覆盖权重 per-type weight override
scaleByPartySize true 按队伍人数缩放 Boss 血量 scale boss HP by party size
mobSpawnRate 1.0 怪物生成率倍率 mob spawn rate multiplier
maxMobsPerRoom 30 单房间怪物上限（半径 15 内） max mobs per room (radius 15)

9.3 世界规则 / World Rules

dungeonInstance:
  keepInventory: false
  deepCloneInventory: false
  time: 0
  dungeonTime: 1200
  advanceTime: false
  weather: clear
  difficulty: normal
  allowMobs: [all]
  tntExplosion: deny
  entityExplosion: deny
  blockExplosion: deny
  # P0
  respawnMode: checkpoint
  deathCooldown: 15
  playerCooldown: 300
  friendlyFire: false
  autoPickup: true
  teleportInvulnerable: 3
  # P1
  countdownWarn: [300, 180, 60, 30, 10]
  timeoutAction: forceEnd
  enterTitle: ""
  leaveTitle: ""
  roomProgress: true
  bossDirection: false
  soundVolume: 100
  allowSpectatorAfterDeath: true
  # P3
  roomFog: false
键 / Key 默认 / Default 中文说明 English
keepInventory false 死亡保留背包 keep inventory on death
deepCloneInventory false 备份并清空背包，离开恢复 backup and clear inventory, restore on leave
time 0 限时秒数，0 不限 time limit (s), 0 = unlimited
dungeonTime 1200 世界固定时间 (tick) fixed world time (ticks)
advanceTime false 时间自动推进 advance time automatically
weather clear clear/rain/thunder weather
difficulty normal 难度 difficulty
allowMobs [all] 允许怪物列表 allowed mobs
tntExplosion deny TNT 爆炸：allow/damage_only/deny TNT explosion mode
entityExplosion deny 实体爆炸模式 entity explosion mode
blockExplosion deny 方块爆炸模式 block explosion mode
respawnMode checkpoint lobby/checkpoint/spectator respawn mode
deathCooldown 15 死亡复活冷却秒 death respawn cooldown
playerCooldown 300 玩家入场冷却秒 player entry cooldown
friendlyFire false 允许友伤 allow friendly fire
autoPickup true 自动拾取 auto pickup
teleportInvulnerable 3 传送无敌秒 teleport invulnerability (s)
countdownWarn [300,180,60,30,10] 倒计时提示点 countdown warnings
timeoutAction forceEnd forceEnd/extend timeout action
enterTitle "" 进入 Title（%dungeon%） enter title
leaveTitle "" 离开 Title leave title
roomProgress true ActionBar 房间进度 ActionBar room progress
bossDirection false ActionBar Boss 方向 ActionBar boss direction
soundVolume 100 音效音量百分比 sound volume
allowSpectatorAfterDeath true 死后旁观（spectator 模式） spectator after death
roomFog false 房间迷雾动态视距 room fog dynamic view distance

9.4 玩家配置 / Player Config

dungeonInstance:
  commandsAllowListType: white
  commandsAllow: []
  buildSettingsListType: white
  buildSettings: []
  breakSettingsListType: white
  breakSettings: []
  interactionSettingsListType: white
  interactionSettings: []
  bossBar: true
  partyGlow: true

**中文：**白名单模式 white 表示仅列表允许，black 表示仅列表禁止。 English: white = only listed items allowed; black = only listed items blocked.

9.5 Boss 配置 / Boss Config

dungeonInstance:
  useMythicMobForBoss: false
  mythicMobBossName: ""
  bossType: [zombie]
  bossNbt: ["{Health:100.0f}"]
  bossHealthMultiplierPerPlayer: 1.5
  bossPhase:
    enabled: false
    phases: []

中文：bossHealthMultiplierPerPlayer 在 scaleByPartySize: true 时生效，每多一名玩家 Boss 血量乘以此值。 English: bossHealthMultiplierPerPlayer applies when scaleByPartySize: true; boss HP is multiplied by this value per extra player.

9.6 经济与奖励 / Economy & Rewards

dungeonInstance:
  enterCost:
    vault: {}
    playerPoints: {}
    consoleCommands: []
  rewards:
    vault: {}
    playerPoints: {}
    consoleCommands: []
    firstClearBonus:
      vault: {}
      playerPoints: {}
      consoleCommands: []
    shareMode: each          # each/split
    permissionMultiplier: {} # {himdungeons.reward.vip: 1.5}
  failurePenalty:
    vault: {}
    playerPoints: {}
    consoleCommands: []
  stats:
    trackFastestTime: true
  leaderboard: false
  lootTable:
    enabled: false
    tables: {}

**中文：**命令支持 {player} 占位符。shareMode: each 每人全额，split 平分。 English: Commands support {player}. shareMode: each gives full amount to every player; split divides it.

9.7 软依赖 / Soft Dependencies

dungeonInstance:
  allowParties: false
  allowSlimefun: false
  useMythicMobs: false

10. 编辑器 GUI / Editor GUI

中文：/dg edit 打开主页面。 English: /dg edit opens the main page.

10.1 主页面 / Main Page

图标 / Icon 功能 / Function
书本 / Book 修改根配置 / Edit global config
中继器 / Repeater 钩子管理 / Hook manager
箱子 / Chest 地牢实例配置 / Instance config
红石 / Redstone 重载插件 / Reload plugin
指南针 / Compass 地牢选择 / Dungeon selection

10.2 实例编辑 / Instance Editor

**中文：**添加/移除房间、门、箱子、出生点、存档点；配置分类页；生成测试世界。 English: Add/remove rooms, doors, chests, spawn points, checkpoints; config category pages; generate test world.

10.3 配置分类 / Config Categories

分类 / Category 内容 / Content
实例根配置 / Root enable / displayName / msgPrefix / lobby
生成算法 / Generation 房间数 / 深度 / AABB / 复用 / 队伍缩放 / 怪物率
世界规则 / World 时间 / 天气 / 难度 / 爆炸 / 重生 / 冷却 / 无敌 / 迷雾
玩家配置 / Player 白名单 / Boss 血条 / 队友发光
Boss 配置 / Boss MythicMobs / 类型 / 血量倍率 / 分阶段
经济与奖励 / Economy 入场费 / 奖励 / 首通 / 分配 / 倍率 / 失败惩罚 / 战利品表
软依赖 / Soft Parties / Slimefun / MythicMobs

10.4 字段交互 / Field Interaction

**中文：**布尔左键切换；数字/字符串左键输入；列表左键打开编辑器；枚举左键循环；嵌套结构提示手动编辑。 English: Booleans toggle on left-click; numbers/strings open chat input; lists open editor; enums cycle on left-click; complex structures prompt to edit config.yml manually.

**中文：**聊天输入支持 cancel 取消。 English: Chat input supports cancel to abort.

11. 钩子系统 / Hook System

**中文：**23 个生命周期钩子，通过 DungeonHookRegistry 注册和触发。单个监听器异常隔离，不影响其他监听器。 English: 23 lifecycle hooks registered and fired via DungeonHookRegistry. Exceptions in one listener are isolated from others.

分组 / Group 钩子 / Hooks
L1 实例 / Instance BeforeCreateWorld, AfterCreateWorld, BeforeGenerate, AfterGenerate, BeforePaste, AfterPaste, DungeonReady, BeforeDestroy, AfterDestroy
L2 房间 / Room RoomSelect, RoomPlaced, RoomPasted, ChestFill
L3 玩家 / Player BeforeEnter, AfterEnter, BeforeLeave, AfterLeave, Finish, Offline, Online
L4 Boss BossSpawn, BossDefeat

**中文：**注册示例： English: Registration example:

DungeonHookRegistry reg = HimDungeons.getInstance().getHookRegistry();

reg.onBeforeEnter(ctx -> {
    if (ctx.player.getLevel() < 10) {
        ctx.cancelled = true;
        ctx.player.sendMessage("§c需要 10 级才能进入 / Requires level 10");
    }
});

**中文：**通过 /dg edit → 钩子管理可查看当前接入的钩子并按类型清空。 English: Use /dg edit → Hook Manager to view registered hooks and clear by type.

12. 多语言 / i18n

中文：

  • 语言文件：plugins/HimDungeons/lang/<code>.yml
  • 切换全局：/dg lang en_US
  • 按客户端切换：config.yml 里 language.useClientLocale: true
  • 回退链：当前 → en_US → zh_CN → key 原文
  • 新增语言：复制 zh_CN.yml → 翻译 → /dg reload

English:

  • Language files: plugins/HimDungeons/lang/<code>.yml
  • Global switch: /dg lang en_US
  • Per-client switch: set language.useClientLocale: true in config.yml
  • Fallback chain: current → en_US → zh_CN → raw key
  • Adding a language: copy zh_CN.yml → translate → /dg reload

**中文：**前缀优先级：玩家所在地牢实例的 msgPrefix → 全局 msgPrefix。 English: Prefix priority: instance msgPrefix (if player is inside that dungeon world) → global msgPrefix.

13. 软依赖 / Soft Dependencies

**中文：**以下插件为可选依赖，未安装时对应功能自动降级。 English: The following plugins are optional; if absent, corresponding features gracefully degrade.

插件 / Plugin 中文作用 English
Vault 经济奖励 / 入场费 Economy rewards / entry cost
PlayerPoints 点券奖励 / 入场费 Points rewards / entry cost
Parties Party 模式组队 Party mode grouping
MythicMobs 自定义 Boss / 物品判断 Custom boss / item check
Slimefun Slimefun 物品拦截 Slimefun item interception
PlaceholderAPI 占位符扩展（预留） Placeholder extension (reserved)

**中文：**MythicMobs 自动识别 v4 (io.lumine.xikage) 和 v5 (io.lumine.mythic) 两套 API。 English: MythicMobs v4 (io.lumine.xikage) and v5 (io.lumine.mythic) APIs are auto-detected.

14. 高级功能 / Advanced

14.1 战利品表 / Loot Tables

**中文：**在 dungeonInstance.lootTable.tables 中定义命名表，在 _chest.yml 中用 @tableName [count] 引用。 English: Define named tables in dungeonInstance.lootTable.tables and reference them in _chest.yml via @tableName [count].

dungeonInstance:
  lootTable:
    enabled: true
    tables:
      common:
        - "60 IRON_INGOT 3"
        - "40 GOLD_INGOT 2"
        - "20 DIAMOND 1"
      rare:
        - "10 NETHERITE_INGOT 1"
      boss:
        - "100 DIAMOND 5"
# _chest.yml
chests:
  - pos: [1, 2, 3]
    loot: "@common"
  - pos: [4, 5, 6]
    loot: "@rare 2"
  - pos: [7, 8, 9]
    loot: "50 EMERALD 4"   # 直接写仍兼容 / direct loot still works

14.2 Boss 分阶段 / Boss Phases

**中文：**按血量百分比阈值触发 Title、音效、命令。 English: Trigger titles, sounds, and commands at HP percentage thresholds.

dungeonInstance:
  bossPhase:
    enabled: true
    phases:
      - threshold: 75
        title: "&c%name% &7进入 &c第二阶段&7！"
        subtitle: "&e小心，它变强了"
        sound: ENTITY_WITHER_SPAWN
        commands:
          - "mm skills cast %boss% Phase2 @self"
      - threshold: 25
        title: "&4%name% &7狂暴！"
        sound: ENTITY_WITHER_DEATH
        commands:
          - "mm skills cast %boss% Enrage @self"

**中文：**支持占位符 %name%（Boss 类型）、%phase%（阶段序号）、%boss%（命令中用）、%world%（命令中用）。血量跨越多个阈值时依次触发。 English: Supports placeholders %name% (boss type), %phase% (phase number), %boss% (commands), %world% (commands). Multiple thresholds crossed in one hit fire sequentially.

14.3 排行榜 / Leaderboard

**中文：**启用 leaderboard: true 和 stats.trackFastestTime: true，/dg leaderboard <地牢名> 打开 GUI，可在"最快通关"和"最多通关"间切换。 English: Enable leaderboard: true and stats.trackFastestTime: true. Run /dg leaderboard <dungeon> to open a GUI, switchable between Fastest Clear and Most Clears.

14.4 房间迷雾 / Room Fog

中文：roomFog: true 时按玩家所在房间尺寸动态调整客户端视距，离开地牢时恢复。 English: With roomFog: true, the client view distance is dynamically adjusted based on the player's room size and restored on leaving.

15. 常见问题 / FAQ

Q1: 房间重叠？ / Rooms overlap? **中文：**检查 useAabb: true；若关闭 AABB，请用 disconnectedRoomDistance 设置间距。 English: Check useAabb: true. If AABB is off, use disconnectedRoomDistance.

Q2: 门对接不上？ / Doors don't connect? **中文：**检查朝向是否相反、锚点是否相邻、类型是否一致。 English: Check that facings are opposite, anchors are adjacent, and types match.

Q3: 玩家掉入虚空？ / Players fall into the void? **中文：**start 房间的 _spawn.yml 未配置或坐标错误。 English: Missing or incorrect _spawn.yml in the start room.

Q4: Boss 不生成？ / Boss doesn't spawn? **中文：**检查 boss 房间、bossType/bossNbt、mythicMobBossName 是否正确。 English: Check the boss room, bossType/bossNbt, and mythicMobBossName.

Q5: 玩家背包丢失？ / Player inventory lost? **中文：**启用 deepCloneInventory: true 时插件备份背包；崩溃后重启会自动恢复。检查 backup.db。 English: With deepCloneInventory: true, the plugin backs up inventories and restores on crash. Check backup.db.

Q6: 地牢世界残留？ / Dungeon worlds remain? 中文：/dg list 找到实例 → /dg forceend <世界名>。 English: /dg list to find the instance → /dg forceend <world>.

Q7: 房间不生成？ / Room never generates? **中文：**检查 structureChoose、/dg validate 结果、.schem 和 _door.yml 是否存在。 English: Check structureChoose, /dg validate results, and existence of .schem and _door.yml.

Q8: 提示 "Missing lang key"？ / "Missing lang key"? **中文：**语言文件缺 key，补齐 en_US.yml 或切回 zh_CN。 English: The lang file lacks the key; fill in en_US.yml or switch back to zh_CN.

Q9: Party 模式不工作？ / Party mode not working? **中文：**确认 Parties 已安装、allowParties: true、队伍有在线成员。 English: Confirm Parties is installed, allowParties: true, and the party has online members.

Q10: MythicMobs Boss 不生效？ / MythicMobs boss not working? **中文：**v4/v5 自动识别，但需版本匹配；失败会降级到原版，检查 Debug 输出。 English: v4/v5 auto-detection requires a matching version; falls back to vanilla on failure — check Debug output.

Q11: 如何备份？ / How to back up? **中文：**直接备份整个 plugins/HimDungeons/ 目录。 English: Back up the entire plugins/HimDungeons/ directory.

Q12: 如何升级？ / How to upgrade? **中文：**备份 → 替换 JAR → 启动（自动迁移配置）→ /dg reload。 English: Back up → replace JAR → start server (config auto-migrated) → /dg reload.

最后更新 / Last Updated: 版本 / Version 4.0 · i18n + P0–P3 Config + Editor GUI

Clone this wiki locally