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)`
   - 作用：指定本回合使用技能
   - 示例：`useSkill(5001)`

2. `switchPet(catchTime: number)`
   - 作用：指定本回合切换精灵
   - 示例：`switchPet(2)`

## 3. `hookaction` 参数字段

1. `hookaction.hookaction: boolean`
   - effect 链原始判定
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 }>`
   - 我方当前技能快照

返回值：

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

## 4. 脚本示例

### 4.1 第3回合固定放技能

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

  if (hookaction.round === 3) {
    useSkill(5001);
  }

  return true;
}
```

### 4.2 低血切宠

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

  var hpRate = hookaction.our.max_hp > 0 ? hookaction.our.hp / hookaction.our.max_hp : 1;
  if (hpRate < 0.3) {
    switchPet(2);
  }

  return true;
}
```

### 4.3 读取技能可用性后出招

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

  for (var i = 0; i < hookaction.skills.length; i++) {
    var s = hookaction.skills[i];
    if (s.can_use && s.skill_id === 5001) {
      useSkill(s.skill_id);
      break;
    }
  }

  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 BossHookActionContext {
  hookaction: boolean;
  round: number;
  is_first: boolean;
  our: BossHookPetContext | null;
  opp: BossHookPetContext | null;
  skills: BossHookSkillContext[];
}

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. Monaco 补全（可选）

```ts
monaco.languages.registerCompletionItemProvider("javascript", {
  provideCompletionItems() {
    return {
      suggestions: [
        {
          label: "boss hookAction",
          kind: monaco.languages.CompletionItemKind.Snippet,
          insertTextRules:
            monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet,
          insertText: [
            "function hookAction(hookaction) {",
            "  if (!hookaction.hookaction) return false;",
            "  if (hookaction.round >= 3) useSkill(5001);",
            "  return true;",
            "}",
          ].join("\\n"),
          documentation: "Boss脚本模板：可读取回合/血量并调用 useSkill/switchPet。",
        },
      ],
    };
  },
});
```

## 7. 后端代码

- 脚本执行器与函数绑定：`modules/config/model/boss_pet.go`
- AI 出手转发：`logic/service/fight/input/ai.go`
- BOSS 脚本注入：
  - `logic/controller/fight_boss野怪和地图怪.go`
  - `logic/controller/fight_塔.go`