脚本配置 scripts.yml

scripts.yml 定义了地牢的生命周期脚本，在不同阶段自动执行。

完整配置

# 副本初始化时执行（世界创建完毕、玩家传送前）
init:
  - "action.world_time('day')"
  - "action.weather('clear')"

# 副本开始后执行
start:
  # 可选：开始条件（JavaScript 表达式，返回 true 才执行脚本）
  condition:
    - "dungeon.getOnlinePlayerCount() >= 1"
  script:
    - "action.title('@all', '&6地牢开始', '&7准备战斗！')"
    - "action.spawn_group('wave_1')"

# 副本通关时执行（调用 action.complete() 后触发）
complete:
  - "action.title('@all', '&a恭喜通关！', '&7即将返回大厅')"
  - "action.grant_reward('通关奖励')"
  - "action.wait('5s')"
  - "action.exit_dungeon()"

# 副本退出时执行（所有玩家被传送回主世界前）
exit:
  - "action.message('@all', '&7感谢参与！')"

# 副本失败时执行（调用 action.fail() 后触发）
fail:
  - "action.title('@all', '&c挑战失败', '&7再接再厉')"
  - "action.wait('3s')"
  - "action.exit_dungeon()"

# 玩家死亡时执行（每个玩家死亡都会触发）
player_death:
  - "action.message('@all', '{player.name} 倒下了！')"

# 全队死亡时执行（所有玩家都死亡）
all_death:
  - "action.fail('全员死亡')"

生命周期说明

事件	触发时机	说明
`init`	世界创建完成后	设置世界环境，创建初始障碍物等
`start`	玩家传送到副本后	可设置条件。用于开场演出和第一波怪物
`complete`	调用 `action.complete()` 后	发放奖励、播放通关效果
`exit`	玩家被传送回主世界前	清理工作
`fail`	调用 `action.fail()` 后	失败提示和退出处理
`player_death`	每个玩家死亡时	可用于复活机制
`all_death`	所有玩家都死亡时	通常直接调用 `action.fail()`；不写则全灭后自动判失败

死亡流程

副本内玩家受到致命伤害时，QueDP 会拦截这次伤害，不走原版死亡（不触发 PlayerDeathEvent、不掉落背包、不弹出重生界面）。流程如下：

记录一次死亡并触发 PlayerDeathInDungeonEvent；
玩家切换为旁观者模式，留在原地等待复活；
执行 player_death 脚本，脚本内可调用 action.revive(...) 让玩家复活；
脚本执行完毕且玩家未被复活时，该玩家计入「已死亡」；
全队都处于死亡状态时触发 all_death 脚本。

all_death 只负责执行脚本，副本是否结束由脚本自己决定 —— 想结束就调用 action.fail(...)（别名 fail_dungeon），不调用则副本继续运行，脚本仍可复活玩家。没写 all_death 时，全灭 2 秒后自动判定副本失败。

触发 all_death 的时机由 dungeon.yml 的 death_check_mode 控制：

strict（默认）：全队死亡的瞬间立即触发 all_death，不等 player_death 脚本跑完；
lenient：等所有 player_death 脚本执行完毕、且没有任何玩家还有待复活机会时再触发。

带复活倒计时、action.wait() 等异步逻辑的死亡脚本，建议使用 lenient，否则最后一名玩家的复活脚本还没跑完副本就已判定全灭。详见地牢配置。

多行字符串格式

脚本也可以使用 YAML 多行字符串格式，适合包含 if/else 等代码块：

complete: |-
  action.title('@all', '&a通关！', '')
  let time = dungeon.getRunningTime()
  if (time < 300) {
    action.grant_reward('速通奖励')
    action.message('@all', '&a速通奖励已发放！')
  } else {
    action.grant_reward('普通奖励')
  }
  action.wait('5s')
  action.exit_dungeon()

变量

脚本中可以使用以下内置变量：

player / trigger - 触发脚本的玩家对象
dungeon - 当前副本实例对象
action - 动作调用对象

详见脚本系统概述，其中包含各类动作（消息 / 地牢 / 世界 / 玩家 / 战斗等）的完整参考。