| name | agent-auto-battle-config |
| description | OneDragon ZZZ 脚本速成指南 - 自动战斗 YAML 配置的完整语法与设计模式 |
| version | 1.0.0 |
| author | OneDragon-Anything |
| tags | ["zzz","auto-battle","yaml","script","automation"] |
OneDragon ZZZ 脚本速成指南
#----------------------------------------------------------------------
1. 操作 (Operations)
operations 是所有动作的基础，它是一个包含多个原子操作的列表，会按顺序执行。
#----------------------------------------------------------------------
1.1 操作的语法
基础操作：op_name
op_name 定义了要执行的按键操作。
可用 op_name 列表:
战斗相关: 按键-闪避, 按键-普通攻击, 按键-特殊攻击, 按键-终结技, 按键-快速支援
角色切换: 按键-切换角色-下一个, 按键-切换角色-上一个, 按键-切换角色 (需 agent_name 参数)
连携技: 按键-连携技-左, 按键-连携技-右, 按键-连携技-取消
移动: 按键-移动-前, 按键-移动-后, 按键-移动-左, 按键-移动-右
其他: 按键-锁定敌人
操作变体 (点击, 按下, 松开)
每个按键都支持三种模式：
1. 点击 (默认)
执行一次快速的按下和松开。
operations:
- op_name: "按键-普通攻击"
2. 按下
只执行"按下"动作，通常用于长按。
operations:
- op_name: "按键-特殊攻击-按下"
3. 松开
只执行"松开"动作，用于结束长按或防止按键卡住。
operations:
- op_name: "按键-特殊攻击-松开"
1.2 如何编写连贯的操作 (连招)
通过组合操作和使用参数，可以编写出连贯的连招。
核心参数:
repeat: 重复执行同一操作的次数。post_delay: 在操作执行后等待的秒数。此参数不支持在长按操作中用于定义按住时间！禁止接在长按后面。op_name: "等待秒数": 在两个操作之间插入明确的停顿。
重要规则: 绝区零游戏引擎目前只接受0.1秒以上的按键间隔。因此，在连续操作之间，必须使用 post_delay 或 等待秒数 来确保每个动作之间至少有0.1秒的间隔。
示例 1: "普攻x2 -> 停0.5秒 -> 特殊攻击"
operations:
- op_name: "按键-普通攻击"
repeat: 2
post_delay: 0.1
- op_name: "等待秒数"
seconds: 0.5
- op_name: "按键-特殊攻击"
示例 2: 长按特殊攻击 1.5 秒
operations:
- op_name: "按键-特殊攻击-按下"
- op_name: "等待秒数"
seconds: 0.5
- op_name: "按键-特殊攻击-按下"
- op_name: "等待秒数"
seconds: 0.5
- op_name: "按键-特殊攻击-按下"
- op_name: "等待秒数"
seconds: 0.5
- op_name: "按键-特殊攻击-松开"
长按规则: 使用“按下 → 每 0.5 秒重复按下 → 松开”。不要只按下一次后长时间等待：其他并发操作可能发出松开事件，导致长按提前结束。
#----------------------------------------------------------------------
2. 状态 (States)
states 是决策的核心，它定义了执行某个 operations 列表所需满足的条件。
#----------------------------------------------------------------------
2.1 状态语法
基本格式: [状态名, 时间下限, 时间上限]{值下限, 值上限}
- 时间窗口:
[状态名, 时间下限, 时间上限] 检查状态的触发时间是否在此范围内。
- 例如
[状态名, 2, 10] 表示"状态在过去2到10秒内触发过"。
- 时间下限为负数时，表示"倒计时"或"未来事件"。例如
[状态名, -5, -1] 表示"状态将在未来1到5秒内触发"。
- 数值范围:
[耀嘉音-能量]{0, 120} 表示"耀嘉音的能量值在 0 到 120 之间"。仅使用 {下限, 上限}，不要把时间段和数值段拼在一起（错误写法：[能量值, 0, 999]{50, 120}）。
- 数值相等:
[敌人数量]{3} 表示"敌人数量等于3"。
- 逻辑运算: 使用
& (与), | (或), ! (非) 和 () 括号来组合复杂逻辑。
- 示例:
([状态A] | [状态B]) & ![状态C]
2.2 如何设置与清除状态
通过 设置状态 和 清除状态 操作，可以精准地管理自定义状态，实现脚本不同部分的通信。
1. 设置状态 (AtomicSetState)
推荐格式:
- op_name: "设置状态"
state: "状态名"
seconds: 5.0
seconds_add: 2.0
value: 100
add: 50
2. 清除状态 (AtomicClearState)
- op_name: "清除状态"
state_list: ["状态1", "状态2"]
2.3 如何编写状态树 (IF-ELIF-ELSE)
状态树通过 handlers 列表构建，它是一个从上到下匹配的 IF-ELIF-ELSE 逻辑链。
处理器结构:
- states: "[条件A] & ![条件C]"
debug_name: "简要说明此分支意图"
interrupt_states: "[紧急条件]"
operations:
示例: 安比的技能决策树
handlers:
- states: "[前台-安比]"
sub_handlers:
- states: "[安比-能量]{80, 120} & [安比-终结技可用]"
operations:
- op_name: "按键-终结技"
- states: "[安比-特殊技可用]"
operations:
- op_name: "按键-特殊攻击"
- states: ""
operations:
- op_name: "按键-普通攻击"
2.4 高阶技巧：使用负数时间实现动态倒计时
核心机制
- 设置倒计时: 使用
seconds: -N 设置一个持续 N 秒的倒计时。
- 延长倒计时: 使用
seconds_add: -M 为倒计时增加 M 秒。
- 补偿 CG 暂停的失衡计时: 若终结技或其他演出期间游戏内失衡计时暂停，按实测 CG 时长设置
state: "自定义-失衡时间" 与 seconds_add: -<CG秒数>，补回脚本仍按真实时间流逝而错误扣除的时长。
- 判断倒计时: 使用
[状态名, -N, 0] 判断一个倒计时是否仍在生效。
#----------------------------------------------------------------------
3. 场景 (Scenes)
scenes 是组织所有决策逻辑的顶层容器。
#----------------------------------------------------------------------
3.1 如何构建 Scenes
一个完整的脚本由一个 scenes 列表构成。每个 scene 包含：
triggers (触发器): 定义什么事件会"激活"这个场景。priority (优先级): 数字越大，优先级越高。handlers (处理器): 状态树。
3.2 Scenes 的运作机制：事件驱动与抢占
Scenes 运作方式是事件驱动与抢占模型：
- 事件驱动激活: 每个
scene 监听其 triggers，当状态被检测到或更新时唤醒对应 scene。
- 执行与抢占: 执行中会屏蔽 ≤ 当前优先级的触发器，但持续监听 > 当前优先级的触发器，高优场景可立即抢占。
#----------------------------------------------------------------------
4. 模板 (Templates) - 模块化与代码复用
#----------------------------------------------------------------------
4.1 模板的层级与引用规则
- 战斗模板 (
config/auto_battle/*.yml): 顶层策略，定义 scenes 和 priority。
- 状态模板 (
config/auto_battle_state_handler/*.yml): 中层决策树。
- 操作模板 (
config/auto_battle_operation/*.yml): 底层原子化连招。
引用规则: 只能引用同层级或更低层级的模板。
4.2 语法与用法
state_template: "模板名": 调用状态模板operation_template: "模板名": 调用操作模板
4.4 合并运行配置
只编辑 sample.yml，不要手动编辑 .merged.yml。
修改或新增自动战斗的操作、状态处理或顶层配置后，按 new-config 的流程运行：
powershell -File skills/new-config/new-config.ps1
该脚本会从全部 sample.yml 生成 .merged.yml。构建成功后检查生成文件的差异，并将相关 sample.yml 与 .merged.yml 一并提交。
#----------------------------------------------------------------------
5. 全局参数
#----------------------------------------------------------------------
check_dodge_interval: 闪避识别检测间隔（秒）check_agent_interval: 代理人状态检测间隔（秒）check_chain_interval: 连携技检测间隔（秒）check_quick_interval: 快速支援检测间隔（秒）auto_lock_interval: 自动锁定敌人间隔（-1 表示不自动锁定）auto_turn_interval: 镜头自动转向间隔
#----------------------------------------------------------------------
6. 设计思路：全配队通用
#----------------------------------------------------------------------
"全配队通用"脚本的核心设计思想是模块化与事件驱动分层，将战略 (何时做)、决策 (做什么) 和 动作 (如何做) 分离。
文件结构：
config/
├── auto_battle/ # 顶层战略（战斗模板）
│ └── 全配队通用.yml
├── auto_battle_state_handler/ # 中层决策（状态模板）
│ ├── 速切模板-全角色.yml
│ └── ...
└── auto_battle_operation/ # 底层动作（操作模板）
└── ...
6.3 实践：如何新增一个角色
- 创建角色的操作模板（
config/auto_battle_operation/）
- 创建角色的状态模板（
config/auto_battle_state_handler/）
- 注册到分派器（
速切模板-全角色.yml 中增加引用）
- 融入团队轮换（修改
轮换-合轴-全角色.yml 和 轮换-紧急-全角色.yml）
#----------------------------------------------------------------------
7. 参考脚本示例
#----------------------------------------------------------------------
- 星见雅：最复杂示例，含多种形态切换、资源条管理、连招嵌套
- 普罗米娅：最典型示例，含标准站场循环、连携技、长按模式
