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

结构：

{
  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 判断对方是否存在强化（你问的这个）

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 判断对方是否有异常状态

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 类型提示

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