随机副本支持文档

下载与版本

当前正式版为 1.5.0，发布于 2026 年 10 月 18 日。 包含内置副本、管理员自建副本，以及怪物生成、血量同步和准备期间重复入场的修复。 插件页只保留一个最新版下载按钮。

完整更新记录和校验文件见 GitHub 正式发布页。 通过 83 项离线检查、视距与模拟距离均为 3 的隔离服 67 项自检，用户测试反馈良好； 不同服务端与插件组合仍应先在自己的测试环境验证。

安装与升级

1. 备份旧 JAR 和 plugins/NWNDungeon/ 数据目录。
2. 完整停止服务器，替换 JAR，并移走同插件的旧 JAR，避免重复加载。
3. 启动服务器，确认插件版本为 1.5.0，核对「启动配置校验完成」及各难度首领血量。
4. 执行 /nwd doctor，再验证一局清波、首领血量与血条、奖励和退出。

换 JAR 必须完整重启。/nwd reload只重载配置，不能把正在运行的旧插件代码换成新版。 每次启动都会从磁盘加载并校验配置；校验失败会停用副本功能并保留原文件，请先按日志修正再重新启动。

API 声明为 1.21，按 Java 21 目标编译；隔离服实测为 Purpur 26.1.2-2592 / Java 25。 具体 Java 要求以所用服务端为准，API 声明不等于所有小版本均已逐一测试。

怪物生成与首领血量

• 到达当前关卡才生成怪物，后面的关卡不会提前刷怪；按实体体型检查落脚点、危险方块和碰撞。
• 骷髅等怪物保留原版默认武器，自定义模板装备在原版初始化后覆盖。
• 怪物失踪时优先加载实际区块、找回原实体；确认缺失后至少等待 5 秒再有限补刷，每只怪整局最多 3 次。
• 普通怪恢复时保留装备和最近记录的剩余血量，每局每轮最多补刷 2 只；失踪不计击杀、不自动跳波。
• 首领必须确认由本局玩家击杀才算胜利；恢复预算耗尽或生成持续失败时结束本局，退还实际扣除的体力，不发通关奖励。

首领血量写在哪里？

血量单位是生命值点数，20 点 = 10 颗心，支持正数与小数。配置 160 时，真实最大血量应为 160， BossBar 显示当前血量 / 160；受伤、治疗后同步更新。运行中上限被改写时会校正上限并保留剩余血量。 服务器硬属性上限确实不足时会明确报错，请按错误检查 spigot.yml中的 settings.attribute.maxHealth.max。

修改后执行 /nwd reload并重新开局，回显会列出实际配置目录和新首领血量； 已有及准备中的内置局保留开局难度配置。只有开发权限的账号不会重载全局 config.yml，请使用管理员权限。

准备速度与进入倒计时

编辑 config.yml，下面是低配服务器优先的默认值：

trigger:
  cast-seconds: 3                   # 进入前倒计时；0 只取消倒计时

performance:
  max-active-runs: 2                # 内置/自建共享，准备中也占名额
  build-operations-per-tick: 2048   # 内置建造/清理操作数上限
  build-budget-ms: 2                # 达到时间预算后下个 tick 继续

「正在准备副本」是实际建造或复制过程，不能直接指定完成秒数。提高操作数和时间预算通常能加快内置副本准备， 也会增加主线程负担；例如 4096 / 4 ms 比默认预算更高，但不保证耗时减半。准备始终串行，重复按按钮不会重新开局。 修改后执行 /nwd reload。自建副本的模板复制耗时还受存档大小和磁盘速度影响。

入口权重如何理解？

入口保持两次抽选：符合条件的新区块先按 1 / generation.chance决定是否生成入口，默认为 1/400； 抽中后再按各候选入口的 weight / 总权重选择副本。权重 10 在总权重 100 时占 10%，总权重 110 时占 10/110， 并非固定 10%。自建副本开启随机入口后也会参与权重池。

这是什么

1.5.0 的定位是在原有内置副本之外，增加一套「管理员自建副本」体系，而不是替换内置副本。 两套入口共用同一棵命令树，互不影响。

一局一个世界

开局时，插件把模板文件夹复制成 nwndinst_<slug>_<序号> 并加载， 结束时卸载并删除。因此同时开几局就会同时加载几个世界。 config.yml中的performance.max-active-runs是内置与自建副本共享的全局并发上限，准备中的局也计入。

命令与权限

三个命令名等价

/dungeon  =  /nwd  =  /nwmdungeon

只有一个根命令，按子命令名分发。test、spawn、list 等子命令两边同名， 因此按参数判断走哪一套：后面接内置难度名（iron / gold / diamond）走内置副本， 否则当作自建副本的名字。

权限节点

旧的 nwndungeon.use / nwndungeon.admin / nwndungeon.dev 同样声明，代码里两套都认，已经发到玩家手上的权限组不需要改。

玩家命令

管理员命令

创作命令（nwd.dev）

以游戏内帮助为准。帮助文本由插件的命令登记表生成，不会与实现漂移； 本文的表格是同一份内容的整理版。用 /nwd help <子命令> 可以查单条命令的参数、权限、示例与易错点。

快速上手

① /nwd edit                      → 打开副本列表面板
② 点「新建副本」→ 在聊天里输入名字   → 进入虚空搭建世界（创造模式 + 飞行 + 自动发编辑时钟）
③ 搭房间、放门、放箱子
④ /nwd edit（或右键编辑时钟）      → 打开标记面板
⑤ 依次标记：落点 → 刷怪点（选波次）→ 关卡门（看着门）→ 检查点 → 首领位 → 出口门（看着门）
⑥ 点「保存」                      → 落盘并搬成模板
⑦ /nwd test <名字>               → 自己进去打一局

编辑时钟

进入编辑态或入口搭建态时，插件会自动发一个时钟到快捷栏第一个空位， 右键即可打开对应面板，保存或放弃后自动收回。因此不必反复输入命令。

四个面板

面板 A · 副本列表（/nwd edit）

界面大小按内容决定：没有副本时 9 格一行；不超过 18 个副本时 27 格；更多时用 45 或 54 格。 按钮居中排在最后一行：新建副本 · 新建入口建筑 · 这套怎么用 · 关闭。

• 左键副本图标 = 进入编辑
• 右键副本图标 = 删除（二次确认，模板挪进 _deleted/）

面板 B · 标记面板（编辑态下的 /nwd edit）

一行一个主题，其余格子用黑玻璃板填满：

• 标注「看着一扇门」的图标（关卡门、出口门、删除门），需要先用准星看着目标再点击
• 关卡门：左键登记，右键删除你看着的那一道
• 「删除这个副本」有二次确认；如果你正站在它的编辑世界里，会先按「放弃」把你送回主世界再删除

面板 C · 入口搭建（/nwd new entrance create）

面板 D · 说明页（「这套怎么用」）

27 格界面：返回(19) · 关闭(23)。「返回」会按你从哪个面板进入而回到对应面板。

标记的语义与规则

五条关键规则

1. 同一扇门不能既是关卡门又是出口门，两边都会拒绝并提示如何修改。
2. 删除关卡门会自动重排关卡：删掉第 i 道门后，原第 i 关与第 i+1 关合并，后续关卡的刷怪点与补给箱会自动前移一位（不前移就会挂到错误的关卡上）。
3. 门不记录材质：放的是什么门就存什么门，木门、铜门、铁门均可，命令里没有材质参数。
4. 未清场时关卡门打不开：插件每 5 tick 强制关门，同时取消右键与门附近 3 格内的压力板 / 按钮。
5. 「标记清单」会把所有标记逐条输出到聊天栏，「校验」会挑出缺失或失效的项。

入口建筑

流程

/nwd new entrance create <副本名>     → 进入虚空搭建世界
   搭一座门楼（放一扇门 + 一个按钮或压力板）
   在面板中点击「入口门」（看着门）→ 点击「触发点」（看着按钮）
   点击「保存入口」                     → 自动框选范围并保存为结构
/nwd spawn <名字>                   → 在你面前贴出一座，门与触发点一并登记好

实测行为

删除入口

已知问题：重复搭建会让入口越存越多。 重新进入入口搭建世界时，插件会把上次保存的入口贴回来供你修改。如果你在它旁边又搭了一座， 保存时自动框选会把两座一起框进去，之后每次 /nwd spawn 都会贴出两座。 处理办法：在入口面板点「删除这份入口结构」，再重新 new entrance create 搭一座并保存。

数据与文件

plugins/NWNDungeon/
├── config.yml            全局配置：规则、槽位、体力、触发、生成、世界名单
├── dungeons.yml          自建副本登记（含字段注释与示例）
├── registry.yml          副本名 → 世界 slug 的映射
├── loot.yml              掉落表（含 enchant-pool / enchant-levels）
├── mobs.yml              怪物模板
├── party.yml             组队相关
├── entrances.yml         世界入口登记（world / x / y / z / tier / alive / created）
├── pending-delete.txt    待删除清单（文件句柄释放后于下次启动删除）
├── stamina-refunds.yml   离线体力退款记录
├── diagnostics/
│   ├── failures.log          异常与恢复记录（含原因/堆栈）
│   └── failures.previous.log 上一份诊断日志（约1MB后轮转）
└── templates/
    ├── worlds/<slug>/                    模板世界（平时不加载）
    ├── entrances/<slug>.nbt + .yml       入口结构
    ├── _recovered/                       临时世界（重启时保存在里面的人的改动）
    ├── _deleted/                         已删除的副本模板（保留退路）
    └── _backup/                          被覆盖的旧模板（保存时自动备份）

世界维度

编辑与运行过程中的世界都以独立维度存在，命名如下：

• nwndtpl_<slug> —— 正在编辑的临时模板世界
• nwndinst_<slug>_<n> —— 正在运行的副本实例，结束后删除
• nwndent_<slug> —— 入口搭建世界

当前的存档布局中，所有维度都在同一个存档里（world/dimensions/minecraft/<名字>/）， 因此「复制一个世界」等于复制一个维度文件夹，通常不到 1 MB。维度名必须为 ASCII， 中文名只用于界面显示。

已知限制与注意事项

本版沿用现有配置，一个副本一个 YAML、数字房间 ID / 进入 Title、新的首领属性装备分区尚未完整落地； 每人独立通关奖励的完整接入也留在后续版本。以下边界需要服主了解：

常见问题