main.yml

main.yml 是副本模板的总控文件。

这份文件决定谁能进本、副本如何开始、何时算通关、失败后怎样收尾，以及全局事件如何响应。

如果你第一次接触 DM，先把这份文件看明白，后面做阶段、区域、怪物组会顺很多。

这份文件的职责

• 副本 ID 与显示信息
• 基础设置
• 进入条件
• 通关条件
• 事件绑定
• 难度、评级、扫荡、词缀、物品限制
• 进本成本、回传位置、结算节奏

最小可运行示例

ID: first_dungeon
显示名称: '&6第一个地牢'
描述:
  - '&7一个基础测试副本'
图标: DIAMOND_SWORD

设置:
  最小人数: 1
  最大人数: 2
  时间限制: 900
  倒计时: 5
  世界模板: shadow_dungeon_map
  建图模式: standard
  建图超时: 45
  出生点: '0,65,0,0,0'

进入条件: {}
通关条件: '阶段.全部完成()'

事件绑定:
  副本开始:
    脚本: |
      消息.全体("&e副本开始")

先抓住这几块

基础信息

• ID：副本唯一标识
• 显示名称：玩家看到的副本名
• 描述：副本简介
• 图标：菜单或界面里展示的材质

ID 最好稳定，正式服不要频繁改。

设置

设置 这一段管的是人数、时间、地图、进本成本、回传位置和结算节奏。

源码当前实际会读取这些字段：

字段	作用	说明
最小人数	进本人数下限	大于 0 才有意义
最大人数	进本人数上限	大于 0 才会限制
时间限制	副本超时秒数	大于 0 才会在运行中超时结束
倒计时	开战前倒计时秒数	从准备阶段进入正式战斗前使用
世界模板	实例复制来源	不写时通常按副本 ID 找世界模板
建图模式	单个副本的建图方式	常用 standard
建图超时	单个副本的建图超时秒数	超时会打建图阶段日志
出生点	进本传送点	支持 x,y,z[,yaw,pitch]
出生朝向	给 出生点 补方向	只在 出生点 没写朝向时拼进去
冷却时间	两次进本之间的冷却秒数	按玩家单独检查
每日限制	每天最多可进次数	大于 0 才生效
消耗活力值	进本要扣的活力值	大于 0 才生效
返回点	出本传送位置	支持 世界名,x,y,z[,yaw,pitch]
结算延迟	通关后延迟出本的 Tick 数	只影响通关结算阶段
允许重进	模板层保留开关	当前主进入流程没有把它当成硬性判定

建图模式 和 建图超时 这两个字段也值得顺手记一下：

• 建图模式 是每个副本模板自己的建图方式，不是全局配置
• 建图超时 是建图阶段的超时秒数，超时后会输出建图阶段日志，方便排查地图加载卡在哪一步

建图模式

常用写法：

设置:
  世界模板: shadow_dungeon_map
  建图模式: standard
  建图超时: 45

当前源码支持两个值：

• standard
• catserver_112_compat

实际用法很简单：

• 正常的 Spigot / Paper / Purpur 体系，直接用 standard
• 只有在老的 CatServer / Mohist 1.12 上，世界加载兼容有问题时，再试 catserver_112_compat

这项配置的实际行为是：

• standard 会走 DM 当前默认的建图流程
• catserver_112_compat 只给 CatServer / Mohist 1.12 兼容模式用
• 如果你当前服务端并不是 CatServer / Mohist 1.12，哪怕你写了 catserver_112_compat，源码也会回退到 standard

服主视角下直接记住一条就够了：

• 没碰到特殊兼容问题，不要改，保持 standard

出生点、出生朝向、返回点

出生点 最常见写法是：

设置:
  出生点: '0,65,0,180,0'

如果你只想写坐标，也可以把朝向拆开：

设置:
  出生点: '0,65,0'
  出生朝向:
    yaw: 180
    pitch: 0

当前加载器会把这两种写法统一成同一套出生数据。
正式服建议直接把朝向一起写上，排查时最省事。

返回点 则建议始终带世界名：

设置:
  返回点: 'world,0,80,0,0,0'

源码支持只写 x,y,z，这种情况下会回到服务器当前第一个已加载世界。
这个回退更适合临时测试，正式服不要这么配。

冷却时间、每日限制、消耗活力值

这三个字段都在玩家进本前检查：

设置:
  冷却时间: 300
  每日限制: 3
  消耗活力值: 10

• 冷却时间 单位是秒，按玩家单独计算
• 每日限制 大于 0 才生效，达到上限会直接拦住进本
• 消耗活力值 大于 0 才生效，活力不足会直接拦住进本

普通 /dm join 和 /dm admin join 都会吃这套检查。

结算延迟

这个字段只影响通关结算：

设置:
  结算延迟: 40

单位是 Tick。
副本 CLEAR 后会先跑结算，再按这个延迟把玩家传送出去。
如果你想给通关动画、播报、奖励展示留一点时间，就在这里配。

允许重进

这个字段现在会被加载器读取，编辑器里也有入口，但当前主进入流程没有把它当成硬性开关。

如果你要做真实生效的重进限制，优先用这些：

• 冷却时间
• 每日限制
• 模块.yml -> 冷却递增

进入条件

这里控制进本资格。

常见拿来做：

• 等级门槛
• 门票或材料门槛
• 前置任务要求
• 每日次数或特殊资格限制

测试副本可以先留空：

进入条件: {}

要真正启用时，当前最稳的写法是按“条件名 -> 条件区块”来配：

进入条件:
  等级限制:
    条件: '@player.level >= 30'
    拒绝提示: '&c需要达到 30 级'

这块运行时的规则很简单：

• 每一项都要过
• 任意一项不通过，就直接拦住进本
• 拒绝提示 会发给没通过检查的玩家

条件 不是脚本块，它就是一条返回真假的表达式。
具体写法直接看 条件表达式。

通关条件

最稳的入门写法还是：

通关条件: '阶段.全部完成()'

这样整场副本是否通关，直接交给阶段系统判断。

如果你的副本流程就是“清第一波 -> 打 Boss -> 结束”，这套写法最省心。

当前主流程最稳的写法，就是这里直接放一条表达式字符串。
比如：

通关条件: '阶段.全部完成()'

如果你想自己写表达式规则，语法同样看 条件表达式。

main.yml 和其他文件的边界

这部分要分清。

适合放在 main.yml 的

• 整场副本共用的规则
• 整体进入和通关逻辑
• 全局播报
• 全局变量初始化
• 通关或失败前的统一收尾

更适合拆到其他文件的

• 某个阶段专属的刷怪、开门、切流程：放 阶段.yml
• 某个区域专属的进入离开处理：放 区域.yml
• 某一波怪物自己的生成或全灭逻辑：放 怪物组.yml
• 某个按钮、拉杆、实体交互：放 交互.yml
• 某个全息点的触发效果：放 全息.yml

一句话记住：

• main.yml 管整场副本
• 其他文件管各自那一块

事件绑定

事件绑定 是 main.yml 里最常用的一块。

它更适合放整场副本共用的全局钩子，比如：

• 开场提示
• 全局变量初始化
• 整队播报
• 通关表现
• 团灭收尾

例如：

事件绑定:
  副本开始:
    脚本: |
      副本.设置变量("暴雪开启", 1)
      消息.全体("&b暴雪即将开始")
  全员阵亡:
    脚本: |
      消息.全体("&c队伍全灭")

如果你的逻辑明显只属于某个阶段、某个区域、某个怪物组、某个交互点，优先回到对应配置里写脚本，维护会清楚很多。

完整事件列表和触发时机，直接看 事件绑定。

一套常见的拆法

假设你要做一场有天气机制的副本：

• main.yml 里在 副本开始 初始化全局变量
• 阶段.yml 里控制每个阶段什么时候刷怪、什么时候切状态
• 区域.yml 里定义暴雪区、Boss 房、奖励区
• 外部道具通过 /dm script 改副本变量

拆开之后，每一层都只管自己的事，后面维护会轻松很多。

配置建议

• 第一版副本先跑通“进入 -> 开始 -> 刷怪 -> 通关 -> 发奖”。
• 不要一开始就把所有玩法都堆进 main.yml。
• 能拆到专属文件的逻辑尽量拆出去。
• ID、区域名、阶段名、怪物组名最好统一风格，后面查问题更快。

常见问题

副本能进，但一直通关不了

优先检查：

• 通关条件 是否真的会成立
• 阶段是不是都能正常完成
• main.yml 和 阶段.yml 里的变量名、怪物组名、阶段名有没有写错

main.yml 里脚本越写越多

这通常说明文件边界已经开始混了。

这时候最该做的是回头拆：

• 阶段逻辑拆回 阶段.yml
• 区域专属处理拆回 区域.yml
• 交互逻辑拆回 交互.yml

一改 main.yml 就牵一大片

这也是典型的总控文件过重。

后面做正式副本时，尽量把 main.yml 保持在“总控层”，会稳很多。

下一步阅读

• 条件表达式
• 阶段.yml
• 区域.yml
• 事件绑定
• 脚本概览