bl/docs/boss-script-hookaction-guide-2026-04-05.md

# Boss Script（HookAction）接入说明

日期：2026-04-05

## 1. 执行流程

1. 先执行战斗效果链 `HookAction()`
2. 执行脚本 `hookAction(hookaction)`
3. 用脚本返回值决定是否继续出手
4. 脚本可直接调用 Go 绑定函数：`useSkill()`、`switchPet()`

## 2. JS 可调用的 Go 函数

1. `useSkill(skillId: number)`
2. `switchPet(catchTime: number)`

## 3. `hookaction` 参数字段

基础字段：

1. `hookaction.hookaction: boolean`
2. `hookaction.round: number`
3. `hookaction.is_first: boolean`
4. `hookaction.our: { pet_id, catch_time, hp, max_hp } | null`
5. `hookaction.opp: { pet_id, catch_time, hp, max_hp } | null`
6. `hookaction.skills: Array<{ skill_id, pp, can_use }>`

AttackValue 映射字段（重点）：

1. `hookaction.our_attack`
2. `hookaction.opp_attack`

结构：

```ts
{
  skill_id: number;
  attack_time: number;
  is_critical: number;
  lost_hp: number;
  gain_hp: number;
  remain_hp: number;
  max_hp: number;
  state: number;
  offensive: number;
  status: number[]; // 对应 AttackValue.Status[20]
  prop: number[];   // 对应 AttackValue.Prop[6]
}
```

其中：

- `prop` 索引：`[攻, 防, 特攻, 特防, 速度, 命中]`
- 对应值 `> 0` 代表强化，`< 0` 代表下降，`0` 代表无变化

返回值：

- `true`：继续行动
- `false`：阻止行动
- 不返回：默认回退到 `hookaction.hookaction`

## 4. 脚本示例

### 4.1 判断对方是否存在强化（你问的这个）

```js
function hookAction(hookaction) {
  if (!hookaction.hookaction) return false;

  var oppAtk = hookaction.opp_attack;
  var oppHasBuff = false;
  if (oppAtk && oppAtk.prop) {
    for (var i = 0; i < oppAtk.prop.length; i++) {
      if (oppAtk.prop[i] > 0) {
        oppHasBuff = true;
        break;
      }
    }
  }

  if (oppHasBuff) {
    // 对方有强化时，放一个针对技能
    useSkill(5001);
    return true;
  }

  return true;
}
```

### 4.2 判断对方是否有异常状态

```js
function hookAction(hookaction) {
  if (!hookaction.hookaction) return false;

  var oppAtk = hookaction.opp_attack;
  var hasStatus = false;
  if (oppAtk && oppAtk.status) {
    for (var i = 0; i < oppAtk.status.length; i++) {
      if (oppAtk.status[i] > 0) {
        hasStatus = true;
        break;
      }
    }
  }

  if (!hasStatus) {
    // 没有异常时尝试上异常
    useSkill(6002);
  }

  return true;
}
```

## 5. Monaco 类型提示

```ts
import * as monaco from "monaco-editor";

monaco.languages.typescript.javascriptDefaults.setCompilerOptions({
  allowNonTsExtensions: true,
  checkJs: true,
  target: monaco.languages.typescript.ScriptTarget.ES2020,
});

monaco.languages.typescript.javascriptDefaults.addExtraLib(
  `
interface BossHookPetContext {
  pet_id: number;
  catch_time: number;
  hp: number;
  max_hp: number;
}

interface BossHookSkillContext {
  skill_id: number;
  pp: number;
  can_use: boolean;
}

interface BossHookAttackContext {
  skill_id: number;
  attack_time: number;
  is_critical: number;
  lost_hp: number;
  gain_hp: number;
  remain_hp: number;
  max_hp: number;
  state: number;
  offensive: number;
  status: number[];
  prop: number[];
}

interface BossHookActionContext {
  hookaction: boolean;
  round: number;
  is_first: boolean;
  our: BossHookPetContext | null;
  opp: BossHookPetContext | null;
  skills: BossHookSkillContext[];
  our_attack: BossHookAttackContext | null;
  opp_attack: BossHookAttackContext | null;
}

declare function hookAction(hookaction: BossHookActionContext): boolean;
declare function HookAction(hookaction: BossHookActionContext): boolean;
declare function hookaction(hookaction: BossHookActionContext): boolean;

declare function useSkill(skillId: number): void;
declare function switchPet(catchTime: number): void;
`,
  "ts:boss-script.d.ts"
);
```

## 6. 后端代码

- 脚本执行器与函数绑定：`modules/config/model/boss_pet.go`
- AI 出手转发与上下文构建：`logic/service/fight/input/ai.go`