脚本系统

Abyss 的副本流程由 scripts.yml 中的生命周期脚本驱动。每个脚本段是一串动作行，按顺序执行；wait <秒> 挂起当前脚本（不阻塞其他脚本），{player}/{killer} 等占位符在运行时展开。

生命周期段

段名	触发时机
`world-init`	世界就绪、区块预载完成后、玩家传送之前——造平台/铺场景专用（void 世界必须用它建落脚处；大量 fillblocks/paste_region 在此段跑）
`init`	全员进图后、副本激活前（玩法对象尚未初始化——不要在这里搭地形，玩家已落地）
`start`	副本激活（怪组已注册，AUTO_START 组已刷）
`complete`	通关（脚本 `complete_dungeon` 或怪物组条件触发）
`fail`	失败（脚本 `fail_dungeon`、团灭、超时 FAIL）
`player-death`	副本内玩家死亡（`{player}` = 死者，`@trigger` 指向该玩家）
`all-death`	全员死亡（配合 `team-wipe-mode`）
`exit`	玩家离开副本（`@trigger` = 离开者）

world-init:                      # 传送前跑——虚空世界在此建场景
  - "fillblocks -6,79,-6 6,79,6 END_STONE"
 
init:
  - "message @all &7正在构建竞技场..."
 
start:
  - "bossbar @all 600 RED SOLID &c虚空试炼场"
 
complete:
  - "grant_reward @all clear_pack"
  - "wait 3"
  - "exit_dungeon @all"
 
fail:
  - "exit_dungeon @all"
 
player-death:
  - "wait 5"
  - "revive_player @trigger"
 
all-death:
  - "fail_dungeon"

选择器

动作行中 选择器 位置支持：

选择器	指向
`@all`	副本内全部玩家
`@trigger`	触发者（交互点触发者/死亡者/NPC 点击者等上下文玩家）
`@random`	随机一名副本内玩家
`@dead`	当前死亡的玩家
玩家名	指定玩家

动作清单

统一格式：<动作> [选择器] <参数...>。无选择器的动作直接作用于副本上下文。

消息与展示

动作	用法
`message`	`message <选择器> <文本>` 发消息（& 颜色码）
`broadcast`	`broadcast <文本>` 全服广播
`title`	`title <选择器> <fadeIn> <stay> <fadeOut> <主标题\|副标题>`
`actionbar`	`actionbar <选择器> <文本>`
`sound`	`sound <选择器> <音效> <音量> <音高>`
`effect`	`effect <选择器> <粒子> <参数>`
`firework`	`firework <选择器> <类型> <颜色>`
`bossbar`	`bossbar <选择器> <秒> <颜色> <样式> <标题>`
`announce`	`announce <选择器> <big\|small> <内容>` 大标题/actionbar 展示

玩家操作

动作	用法
`teleport`	`teleport <选择器> <x,y,z>` 副本内传送
`teleport_dungeon`	传送进副本出生点
`heal`	`heal <选择器> <血量>`
`feed`	`feed <选择器>` 恢复饥饿
`gamemode`	`gamemode <选择器> <模式>`
`fly`	`fly <选择器> <true/false>`
`apply_potion`	`apply_potion <选择器> <药水> <秒> <等级>`
`clear_potion`	`clear_potion <选择器>`
`give_exp`	`give_exp <选择器> <经验>`
`setlevel`	`setlevel <选择器> <等级>`
`velocity`	`velocity <选择器> <x,y,z>` 击退/推进
`revive_player`	`revive_player <选择器>` 复活副本内死亡玩家

物品与命令

动作	用法
`give_item`	`give_item <选择器> <物品描述>`
`take_item`	`take_item <选择器> <物品描述>`
`clear_inventory`	`clear_inventory <选择器>`
`command`	`command <选择器> <命令>` 玩家执行
`console`	`console <命令>` 控制台执行（`%player%` 占位）
`player_command`	玩家身份执行命令
`op_command`	以 OP 权限执行
`give_money`	`give_money <选择器> <金额>`

副本流程控制

动作	用法
`complete_dungeon`	判定通关
`fail_dungeon`	判定失败
`cancel_dungeon`	取消副本（不算胜负）
`exit_dungeon`	`exit_dungeon <选择器>` 传送回原位置并退出
`kick_all_players`	踢出全部玩家
`run_script`	`run_script <段名>` 调用其他脚本段
`delay` / `wait`	`wait <秒>` 挂起当前脚本
`setvar` / `delvar` / `addvar`	副本变量读写
`random`	`random <变量> <min> <max>` 写均匀随机整数到实例变量
`if_var`	`if_var <变量> <op> <值>` 实例变量不满足则中止本段（不依赖玩家，world-init 可用）
`check`	`check <选择器> <条件>` 目标不满足条件时中止当前脚本

随机分支模式：random 掷变量 → run_script 调多个变体段 → 各段首行 if_var <变量> == N 门控，不匹配只终止该段（run_script 开独立会话）。check 逐玩家评估，world-init 阶段无玩家会空转——变量门控请用 if_var。

全服共享计数

跨副本/跨实例的服务器级计数器（持久化到数据库，重启不丢）。典型用途：全服收集进度（"重启密钥归档"）、全服完成率统计、全服事件的触发数据源。

动作	用法
`global_add`	`global_add <键> [增量]` 累加（默认 +1），命中阈值自动发事件
`global_set`	`global_set <键> <值>` 直接设定
`global_get`	`global_get <键> <变量>` 把全服计数读进实例变量（配合 `check` 判断）
`global_reset`	`global_reset <键>` 归零并清阈值触发记录（一轮全服事件结束用）

阈值事件：模块配置 ArcartXAbyss.yml 的 global-thresholds 节声明阈值表：

global-thresholds:
  reboot_key_fragments: [50, 100]   # 到达 50 / 100 时各发一次 axs.abyss.global_threshold

计数每次变更发 axs.abyss.global_change（payload：key/value/delta/dungeon/instance/player）；首次跨越阈值额外发 axs.abyss.global_threshold（payload 加 threshold），同一阈值只触发一次，global_reset 后可重新触发。事件本体（全服防守战/阵营混战等）由 eventpacket 规则或外部玩法模块订阅实现——abyss 只出数据源。

怪物与方块

动作	用法
`spawn_group`	`spawn_group <怪物组>` 触发波次
`kill_group` / `remove_group`	击杀/跳过指定组（未刷出的组经 kill_group 视同完成走联动链；remove_group 静默移除不计完成）
`group_alive_count`	`group_alive_count <组>` 存活数（配合 check）
`kill_all_mobs`	清全部副本怪
`cast_skill`	`cast_skill <怪物> <技能>` MythicMobs 技能
`play_model_animation`	播放模型动画
`setblock`	`setblock <x,y,z> <Material>`
`fillblocks`	`fillblocks <x1,y1,z1> <x2,y2,z2> <Material>`
`paste_region`	`paste_region <名> <x,y,z> [full]` 铺放 `/axs abyss region` 圈选的区域模板——默认跳过 AIR（结构嵌入地形），`full` 连空气覆盖（挖空腔体/虚空铺房）

障碍物 / 交互点 / NPC / 任务

动作	用法
`create_obstacle` / `delete_obstacle`	`create_obstacle <名>` 放置/移除障碍物
`create_interact` / `delete_interact`	动态启停交互点
`floor_next`	强制推进下一层（floors 模式）
`room_lock` / `room_unlock`	`room_lock <房id>` 手动锁门/清房开门（floors 模式）
`room_status`	`room_status <房id> <变量>` 写房间状态到变量（SEALED/FIGHTING/CLEARED/UNKNOWN）
`puzzle_prompt`	`puzzle_prompt <机关id>` 给触发者打开 input 型机关的输入面板（puzzles.yml）
`puzzle_prompt_player`	`puzzle_prompt_player <玩家\|@all> <机关id>` 指定玩家打开输入面板
`puzzle_reset`	`puzzle_reset <机关id>` 机关进度/锁定清零，回到初始状态
`puzzle_solve`	`puzzle_solve <机关id>` 直接判定完成（触发 on-complete + 事件）
`puzzle_state`	`puzzle_state <机关id> <变量>` 机关进度写入变量（无此机关=-1）
`spawn_npc` / `remove_npc`	`spawn_npc <名>` 生成/移除 npcs.yml 定义的 NPC（Adyeshach 公共临时实体）
`npc_dialog`	`npc_dialog <名> [sel]` 触发 NPC 对话——已绑 Chemdah 会话→真会话 UI，否则 `dialogs` 聊天栏兜底
`play_model_animation`	`play_model_animation <npc名> <动画名> [速度] [过渡tick] [保持tick]` Adyeshach 模型动画
`accept_quest` / `submit_quest`	`accept_quest <任务> [sel]` / `submit_quest <任务> [sel]`——经 questgps 接取 Chemdah 任务 / manual-claim 领取副本奖励
`quest_step`	`quest_step <任务>` 智能一步：未接取→接取，已完成→领取（推荐 NPC click-script 用）
`quest_status`	`quest_status <任务> <变量>` 写触发玩家的 Chemdah 状态（NONE/ACTIVE/COMPLETED）到变量，配 `check` 分支

副本内引导（路标/路径渲染）

调用 api.util.NavigationTargetService——HUD 目标行 + 客户端路标 + 路径标记链直达目标，到达发事件并可自动跑脚本段。

动作	用法
`guide_point`	`guide_point <navId> <x,y,z> [到达半径] <标题...>` 全员登记导航目标（同 navId 覆盖）
`guide_clear`	`guide_clear <navId\|all>` 撤下目标

start:
  - "guide_point pump_room 90,64,-55 3 &e前往泵房"
 
# 到达回调：scripts.yml 里定义 guide_<navId> 段自动运行
guide_pump_room:
  - "guide_clear pump_room"
  - "message @all &a已抵达泵房"

到达同时发 axs.abyss.guide_arrive 事件（payload：nav）。HUD 顶部常驻显示最新一条目标标题；玩家退出/副本结束自动清理；中途进本的玩家自动补推当前目标。ArcartX 路标桥不可用时动作静默跳过。

增益选择池（buffs.yml）

动作	用法
`buff_offer`	`buff_offer <池id>` 发起增益选择（panel=弹卡片面板 / hud=直接生效）
`buff_grant`	`buff_grant <池id> <选择器> [optionId]` 直接赋予（不弹窗；optionId 空=权重随机）
`buff_clear`	`buff_clear <池id>` 撤下未完成的待选面板

实例变量 {var:buff.<池id>}=所选 option id、{var:buff.<池id>.count}=发放人次；事件 axs.abyss.buff_offer/buff_pick。详见 buffs.yml 增益选择池。

奖励

动作	用法
`grant_reward`	`grant_reward <选择器> <奖励集名>` 发放 `rewards.yml` 命名集
`open_chest_ui`	`open_chest_ui <选择器> <宝箱名>` 打开宝箱 UI
`open_shop_ui`	`open_shop_ui <选择器> <商店id>` 打开 `shops.yml` 商店 UI（NPC click-script/台座入口）
`time` / `weather`	设置副本世界时间/天气

跨模块联动

以下动作调用其他 AXS 模块的 capability；目标模块未启用时静默跳过，不报错不阻塞。

动作	用法	依赖模块
`signal`	`signal <选择器> <信号名>` 触发 EventPacket 规则引擎信号	eventpacket
`announce_global`	`announce_global <文本> [forward]` Announcer 全服公告（`forward`/`true` 结尾=跨服）	announcer
`qq_group`	`qq_group [群号] <消息>` QQ 群推送（群号省略=全部已配置群）	qqbot
`subtitle`	`subtitle <选择器> <字幕组id>` 播放字幕组	subtitle
`chat_card`	`chat_card <选择器> <卡片id> [k=v,k=v]` 发送聊天卡片	chat
`quest_track`	`quest_track <任务> [taskId\|-] [@sel]` QuestGPS 任务追踪卡片：本地任务 id 自动解析成 chemdah-id；taskId 省略或 `-`=追踪整个任务，否则追踪指定步骤；选择器缺省 `@trigger`	questgps
`quest_offer`	`quest_offer <任务> [sel] [menu]` questgps 推送任务供玩家选择接取；`menu`=弹任务菜单	questgps
`quest_menu`	`quest_menu [sel]` 打开 questgps 任务菜单	questgps
`open_conversation`	`open_conversation <npcId> [sel]` 强制打开该 Adyeshach NPC 绑定的 Chemdah 会话（不要求在 npcs.yml 登记）	conversation
`play_cinematic`	`play_cinematic <序列id> [sel]` 播放 conversation 模块电影序列	conversation

# 进本后给全员挂上"讨伐魔君"任务追踪；到泵房时切到具体步骤
start:
  - "quest_track demon_slayer - @all"
on-room-clear:
  - "quest_track demon_slayer reach_pump @all"

注意 announce（本地 title/actionbar 展示）与 announce_global（announcer 模块全服公告）是两个动作，不要混淆。

内联脚本与占位符

动作行可用 aria: <表达式> / js: <代码> 前缀走 Aria/JavaScript 脚本（js: 需服务端有 Nashorn/GraalJS，否则跳过并警告）
条件字段支持 PAPI 占位符比较：%axsabyss_dungeon_kills% >= 5（完整占位符见命令与占位符）
check 动作可在脚本中途做条件判断，不满足即中止本段后续动作

实例变量

setvar/delvar/addvar 读写副本实例级变量（如 setvar last_killer {killer}），生命周期随实例结束销毁。占位符 {变量名} 在后续动作行中展开。

预置变量（进本/推进流程自动写入，无需 setvar）：

变量	内容	来源
`{plan}` / `{plan_name}`	作战方案 id / 显示名	地牢定义了 `plans` 时，进本选定的方案
`{floor}` / `{floor_name}` / `{floors_total}`	当前层序号 / 层名 / 总层数	floors 模式推进时写入
`{room}`	当前房间 id	floors 模式进房时写入
`{player}` / `{killer}` 等	触发者/击杀者	事件脚本上下文

脚本系统

本页目录