agent-auto-battle-config

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 包含：

1. triggers (触发器): 定义什么事件会"激活"这个场景。
2. priority (优先级): 数字越大，优先级越高。
3. handlers (处理器): 状态树。

3.2 Scenes 的运作机制：事件驱动与抢占

Scenes 运作方式是事件驱动与抢占模型：

1. 事件驱动激活: 每个 scene 监听其 triggers，当状态被检测到或更新时唤醒对应 scene。
2. 执行与抢占: 执行中会屏蔽 ≤ 当前优先级的触发器，但持续监听 > 当前优先级的触发器，高优场景可立即抢占。

#----------------------------------------------------------------------

4. 模板 (Templates) - 模块化与代码复用

#----------------------------------------------------------------------

4.1 模板的层级与引用规则

1. 战斗模板 (config/auto_battle/*.yml): 顶层策略，定义 scenes 和 priority。
2. 状态模板 (config/auto_battle_state_handler/*.yml): 中层决策树。
3. 操作模板 (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 实践：如何新增一个角色

1. 创建角色的操作模板（config/auto_battle_operation/）
2. 创建角色的状态模板（config/auto_battle_state_handler/）
3. 注册到分派器（速切模板-全角色.yml 中增加引用）
4. 融入团队轮换（修改 轮换-合轴-全角色.yml 和 轮换-紧急-全角色.yml）

#----------------------------------------------------------------------

7. 参考脚本示例

#----------------------------------------------------------------------

• 星见雅：最复杂示例，含多种形态切换、资源条管理、连招嵌套
• 普罗米娅：最典型示例，含标准站场循环、连携技、长按模式