区域配置 zones.yml

zones.yml 给副本定义房间边界、进出脚本和命名点位。这个文件是可选的——不建它，副本行为与以前完全一致。

它最实在的价值是命名点位：坐标只写一次，怪物组、障碍物锚点、传送脚本都引用同一份。改图时只改 zones.yml，其余配置自动跟上。

最小示例

四行就能跑：进 Boss 房弹标题。

Boss房:
  范围: "20,60,-10 ~ 40,80,10"
  进入脚本: "action.title('@trigger', '&cBoss 房', '')"

顶层直接写区域名即可，也可以用 区域:（或 zones:）包一层。

完整示例

战斗区:
  名称: "&e前厅战斗区"                  # 可省略，默认用区域 key
  范围: "-10,60,-10 ~ 10,80,10"        # 两点顺序随意，自动取 min/max
  默认开启: true                        # 可省略，默认 true
  进入脚本: |-
    action.message('@trigger', '&e你进入了前厅')
  离开脚本: |-
    action.message('@trigger', '&7你离开了前厅')
  点位:                                 # 命名点位
    中心: "0,65,0"
    左侧: "-4,65,3"
    落点: "0,65,-8,180,0"               # 可带 yaw,pitch

Boss房:
  名称: "&cBoss 房"
  范围: "20,60,-10 ~ 40,80,10"
  默认开启: false                       # 开局不生效，由脚本 enable_zone 打开
  点位:
    落点: "30,65,0,180,0"
    Boss刷新: "30,65,-5"

字段表

键（中/英）	类型	必填	默认	说明
`名称` / `name`	String	否	区域 key	显示名，支持 `&` 颜色
`范围` / `bounds`	String	是	—	`x,y,z ~ x,y,z`，两点顺序随意
`默认开启` / `enabled`	Boolean	否	`true`	`false` = 开局不触发进出脚本
`进入脚本` / `on_enter`	列表/多行	否	空	玩家进入时执行，`@trigger` = 进入者
`离开脚本` / `on_leave`	列表/多行	否	空	玩家离开时执行
`点位` / `points`	Map	否	空	`名字: "x,y,z[,yaw,pitch]"`

范围也接受分开写的兼容格式，与 ENTER_REGION 交互点一致：

Boss房:
  最小点: "20,60,-10"
  最大点: "40,80,10"

脚本占位符

进入 / 离开脚本里额外可用：

占位符	说明
`{zone}` / `{区域}`	当前区域 key
`{zone.name}` / `{区域名称}`	当前区域显示名
`{from_zone}` / `{来源区域}`	上一个所在区域，从无区域进入时为空
`@trigger`	进入 / 离开的那个玩家

命名点位

点位写一次，四处引用，语法统一为 区域名.点位名：

action.teleport_zone('@all', 'Boss房')          // 传到 Boss房.落点
action.teleport_point('@trigger', '战斗区.中心')

区域没有 落点（或 spawn）点位时，teleport_zone 会退到区域中心。

脚本 API

动作

动作	说明
`action.enable_zone('区域')`	开启区域，进出脚本开始生效
`action.disable_zone('区域')`	关闭区域，进出脚本不再触发
`action.teleport_zone('@all', '区域')`	传送到该区域的落点
`action.teleport_point('@trigger', '区域.点位')`	传送到指定点位

中文别名分别是 开启区域 / 关闭区域 / 传送到区域 / 传送到点位。

查询

方法	返回	说明
`dungeon.getZone(player)`	String	玩家当前所在区域 key，重叠时返回体积最小的
`dungeon.getZoneName(player)`	String	当前区域显示名
`dungeon.getZones(player)`	List	玩家命中的全部区域
`dungeon.isInZone(player, '区域')`	Boolean	是否在某区域内
`dungeon.getZonePlayerCount('区域')`	Int	区域内玩家数
`dungeon.isZoneEnabled('区域')`	Boolean	区域是否开启

未配置 zones.yml 时，这些方法分别返回空串 / 空列表 / false / 0，不会报错。

区域进出也是阶段系统的推进时机，所以阶段的通关条件可以直接写「有人进了 Boss 房」：

开门:
  通关条件: "dungeon.getZonePlayerCount('Boss房') >= 1"
  下一阶段: Boss战

PAPI 变量

变量	说明
`%quedp_zone%`	玩家当前所在区域的显示名
`%quedp_zone_id%`	玩家当前所在区域的 key

编辑器

不用手写坐标。进编辑模式后，物品栏第二行第一格是区域工具（木棍）：

操作	效果
左键方块	设为点 1
右键方块	设为点 2
Shift + 左键	打开区域管理界面
Shift + 右键	在当前站位给选中区域加一个命名点位

两点选完会显示粒子边框（只有你自己看得见）。也可以从主编辑器界面的「区域」入口进管理界面。

管理界面里可以：用当前选区创建区域、改显示名、用选区覆盖范围、切换默认开启、编辑进出脚本、管理点位（传送过去 / 用我当前位置覆盖 / 删除）。删除区域和点位走点击确认，Shift+右键 触发。

和 ENTER_REGION 交互点的区别

两者都保留，定位不同：

ENTER_REGION 交互点 = 一次性机关，踩到就触发一次
区域 = 持续的空间状态，有进有出、可开可关、带命名点位

老副本的 ENTER_REGION 继续用，不做自动转换。

限制

单副本最多 64 个区域，超出的在加载时被忽略并打 warn。区域不是用来把地图切碎的
只支持长方体（AABB）范围，不支持球形或多边形
区域的开 / 关状态是运行期状态，副本结束即重置为 默认开启 的值