地牢类动作

用于控制地牢的各种行为。

完成地牢

标记地牢完成并自动退出玩家。

语法

action.complete()
action.complete_dungeon()

示例

// scripts.yml - 完成脚本
action.title('@所有玩家', '&a&l恭喜通关', '');
action.wait('3秒');
action.complete();  // 自动退出并清理

---

失败地牢

标记地牢失败并自动退出玩家。

语法

action.fail([原因])
action.fail_dungeon([原因])

参数

参数	类型	说明
原因	String	自定义失败原因字符串，会传递给 fail 脚本

失败原因变量

在 fail 脚本中可以使用以下变量获取失败原因：

• {失败原因} - 中文变量名
• {fail_reason} - 英文变量名

示例

// all_death 脚本中调用
action.fail_dungeon('全队阵亡，挑战失败！');

// 或自定义任何原因
action.fail_dungeon('Boss逃跑了');
action.fail_dungeon('核心被摧毁');

# scripts.yml - fail 脚本中使用变量
fail: |-
  action.title('@all', '&c&l副本失败', '&7{失败原因}')
  action.message('@all', '&c失败原因: {fail_reason}')
  action.sound('@all', 'ENTITY_VILLAGER_NO', 1.0, 1.0)

---

生成怪物组

生成配置好的怪物组。

语法

action.spawn_group(怪物组名称)

示例

// 生成第一波
action.spawn_group('第一波');

// 波次系统
action.spawn_group('第一波');
action.wait_clear('第一波');
action.spawn_group('第二波');

---

随机选择怪物

从怪物组中随机选择一个怪物ID。支持传入多个怪物组名，会先随机选择一个组，再从中随机选择一个怪物。

语法

action.random_monster_group(怪物组名称, [是否刷新])
action.random_monster_group(怪物组1, 怪物组2, ..., [是否刷新])

参数

参数	类型	必需	默认值	说明
怪物组名称	String	是	-	单个或多个怪物组名称
是否刷新	Boolean	否	false	true=刷新怪物组并注册追踪，false=只返回ID

返回值

返回随机选中的怪物ID（字符串），如果怪物组不存在或为空则返回 null。

刷新参数说明

• false（默认）: 只返回怪物ID，不刷新怪物，杀死后不会触发组完成事件
• true: 返回怪物ID并只刷新这一只怪物，杀死后会触发怪物组的完成事件

示例

// 基础用法：只获取ID，不刷新
var mobId = action.random_monster_group('Boss组');
log('随机选择的Boss: ' + mobId);

// 多个怪物组 - 增加随机性
var randomMob = action.random_monster_group('火系怪物', '冰系怪物', '雷系怪物');
action.message('@all', '&c本次刷新: ' + randomMob);

// 高级用法：获取ID并刷新这一只怪物（会触发完成事件）
var bossId = action.random_monster_group('火龙Boss', '冰龙Boss', '雷龙Boss', true);
action.message('@all', '&c随机Boss: ' + bossId + ' 已刷新！');
// 只刷新被选中的这一只怪物（不是整个组）
// 杀死这只怪物后会触发对应怪物组的完成脚本

// 结合条件判断
var bossId = action.random_monster_group('龙族Boss', '恶魔Boss', '巨人Boss', true);
if (bossId === 'Dragon') {
  action.weather('clear');
  action.message('@all', '&c火龙降临！');
} else if (bossId === 'Demon') {
  action.weather('thunder');
  action.message('@all', '&8恶魔降临！');
}
// 杀死这只怪物后会触发怪物组的完成事件

---

随机刷新怪物组

从多个怪物组中随机选择一个并刷新。

语法

action.random_spawn_group(怪物组1, 怪物组2, ...)

参数

参数	类型	说明
怪物组1, 怪物组2...	String	多个怪物组名称，将随机选择一个刷新

返回值

返回被刷新的怪物组名称（字符串），如果怪物组不存在则返回 null。

示例

// 随机刷新一个Boss
var spawnedBoss = action.random_spawn_group('火龙Boss', '冰龙Boss', '雷龙Boss');
action.message('@all', '&c&l' + spawnedBoss + ' 已降临！');

// 根据刷新的组设置不同环境
if (spawnedBoss === '火龙Boss') {
  action.time('day');
  action.weather('clear');
} else if (spawnedBoss === '冰龙Boss') {
  action.time('night');
  action.weather('snow');
}

// 等待清理后继续
action.wait_clear(spawnedBoss);
action.message('@all', '&a' + spawnedBoss + ' 已被击败！');

// 组合使用：随机波次系统
var wave1 = action.random_spawn_group('普通A', '普通B', '普通C');
action.wait_clear(wave1);

var wave2 = action.random_spawn_group('精英A', '精英B', '精英C');
action.wait_clear(wave2);

var boss = action.random_spawn_group('Boss1', 'Boss2', 'Boss3');
action.wait_clear(boss);
action.complete();

---

创建障碍物

在指定位置创建障碍物。

语法

action.create_obstacle(障碍物名称)

示例

// 封锁大门
action.create_obstacle('大门');

// 怪物波次封锁
action.spawn_group('第一波');
action.create_obstacle('返回大门');

---

删除障碍物

删除指定的障碍物。

语法

action.remove_obstacle(障碍物名称)
action.delete_obstacle(障碍物名称)

示例

// 打开大门
action.remove_obstacle('大门');

// 怪物清空后开门
action.wait_clear('第一波');
action.remove_obstacle('返回大门');
action.message('@所有玩家', '&a大门已开启！');

---

发放奖励

发放配置好的奖励。

语法

action.reward(奖励名称)

示例

// 发放基础奖励
action.reward('普通礼包');

// 根据得分发放
var score = getVar('总分');
if (score >= 1500) {
  action.reward('传说礼包');
} else {
  action.reward('普通礼包');
}

---

打开箱子奖励UI 🆕

打开箱子奖励UI界面，让玩家选择想要的奖励。

语法

action.open_chest_ui('@选择器', '箱子ID')
action.打开宝箱UI('@选择器', '箱子ID')
action.打开箱子('@选择器', '箱子ID')
action.宝箱UI('@选择器', '箱子ID')

参数

参数	类型	说明
选择器	String	目标玩家选择器（@trigger, @all, @party）
箱子ID	String	chest_rewards.yml 中配置的箱子ID

配置文件

箱子UI需要在地牢的 chest_rewards.yml 中配置，奖励在 rewards.yml 中配置。

chest_rewards.yml 示例：

箱子:
  普通宝箱:
    标题: "&6&l✦ 普通宝箱 ✦"
    行数: 3
    模式: single
    背景: BLACK_STAINED_GLASS_PANE

    选项:
      - 槽位: 11
        图标: DIAMOND
        名称: "&b钻石礼包"
        描述:
          - "&7包含:"
          - "&8▸ &f钻石 x3"
          - "&8▸ &6金币 +1000"
        奖励: "基础奖励"

示例

// 触发者打开宝箱
action.open_chest_ui('@trigger', '普通宝箱');

// 所有玩家都打开（各自选择）
action.open_chest_ui('@all', 'Boss宝箱');

// 队伍成员打开
action.open_chest_ui('@party', '稀有宝箱');

配合交互点使用

interacts.yml：

interacts:
  奖励宝箱:
    type: "RIGHT_CLICK_BLOCK"
    once: true
    parameters:
      location: "15,64,0"
      block_type: "CHEST"
    triggered_message: "&c你已经打开过这个宝箱了"
    script: |-
      action.sound('@trigger', 'BLOCK_CHEST_OPEN', 1.0, 1.0)
      action.effect('VILLAGER_HAPPY', '15,65,0', 20, 0.5, 0.3)
      action.open_chest_ui('@trigger', '普通宝箱')

完整示例：Boss战利品宝箱

// scripts.yml - 怪物组完成脚本
monsters:
  Boss战:
    完成时: |-
      action.title('@all', '&a&lBOSS击败', '&7获得战利品')
      action.sound('@all', 'UI_TOAST_CHALLENGE_COMPLETE', 1.0, 1.0)

      // 延迟2秒显示宝箱UI
      action.wait('2秒')
      action.open_chest_ui('@all', 'Boss宝箱')

chest_rewards.yml：

箱子:
  Boss宝箱:
    标题: "&c&l✦ Boss战利品 ✦"
    行数: 5
    模式: single
    背景: RED_STAINED_GLASS_PANE

    选项:
      - 槽位: 13
        图标: NETHERITE_SWORD
        名称: "&c&l神话级武器"
        描述:
          - "&d&l特殊奖励"
          - ""
          - "&8▸ &cBoss战利品 x1"
          - "&8▸ &6金币 +30000"
        奖励: "Boss击杀奖励"

      - 槽位: 21
        图标: GOLDEN_APPLE
        名称: "&6幸运礼包"
        描述:
          - "&8▸ &e金苹果 x5"
          - "&8▸ &6金币 +2000"
        奖励: "幸运礼包"

注意事项

• 每个玩家会独立看到UI界面
• 配合交互点的 once: true 可以防止重复领取
• 奖励必须在 rewards.yml 中配置
• 支持随机奖励（在 rewards.yml 中配置 type: random）

更多配置示例请参考 奖励配置 - 箱子奖励UI系统

---

完整示例

波次战斗

// monsters.yml
怪物组:
  第一波:
    auto-start: true
    开始时: |
      action.title('@所有玩家', '&c第一波', '');
      action.create_obstacle('大门');
    完成时: |
      action.remove_obstacle('大门');
      action.wait('3秒');
      action.spawn_group('第二波');
  
  Boss战:
    auto-start: false
    完成时: |
      action.title('@所有玩家', '&a&l胜利', '');
      action.wait('3秒');
      action.complete();