mioku-plugin-mc 2.1.0 → 3.0.1

package/play/bot/bot-controller.ts

@@ -0,0 +1,276 @@
+import { createBot, type Bot } from "mineflayer";
+import mcData from "minecraft-data";
+import type { PlayServerConfig } from "../types";
+import { resolveMinecraftEndpoint } from "../util/endpoint";
+import { withTimeoutMs } from "../util/async";
+import { PlayBus, type GameChatLine } from "./play-bus";
+import {
+  PathEngine,
+  DEFAULT_MOVEMENTS,
+  type MovementsConfig,
+} from "../path-engine";
+import { Combat } from "../combat";
+
+const PVP_FOLLOW_RANGE = 2;
+const PVP_ATTACK_RANGE = 3.0;
+
+export interface BotControllerOptions {
+  server: PlayServerConfig;
+  bus: PlayBus;
+  log: (msg: string) => void;
+}
+
+export class BotController {
+  bot: Bot | null = null;
+  readonly server: PlayServerConfig;
+  private readonly bus: PlayBus;
+  private readonly log: (msg: string) => void;
+  private pathEngine?: PathEngine;
+  private combat?: Combat;
+  private joinedOnce = false;
+
+  constructor(opts: BotControllerOptions) {
+    this.server = opts.server;
+    this.bus = opts.bus;
+    this.log = opts.log;
+  }
+
+  async connect(): Promise<void> {
+    const { host, port } = await resolveMinecraftEndpoint(this.server.host);
+    const bot = createBot({
+      host,
+      port,
+      username: this.server.username,
+      auth: this.server.auth ?? "offline",
+      password: this.server.password,
+      version: this.server.version || undefined,
+      viewDistance: "normal",
+    } as any);
+    this.bot = bot;
+
+    this.attachListeners(bot);
+
+    return new Promise<void>((resolve, reject) => {
+      let settled = false;
+      const clean = () => {
+        bot.removeListener("spawn", onSpawn);
+        bot.removeListener("error", onEarlyError);
+        bot.removeListener("end", onEarlyEnd);
+        bot.removeListener("kicked", onEarlyKicked);
+      };
+      const onSpawn = () => {
+        if (settled) return;
+        settled = true;
+        this.setupPathEngine();
+        clean();
+        resolve();
+      };
+      const onEarlyError = (err: Error) => {
+        if (settled) return;
+        settled = true;
+        clean();
+        reject(err);
+      };
+      const onEarlyEnd = (reason: string) => {
+        if (settled) return;
+        settled = true;
+        clean();
+        reject(new Error(`连接结束: ${reason}`));
+      };
+      const onEarlyKicked = (reason: string) => {
+        if (settled) return;
+        settled = true;
+        clean();
+        reject(new Error(`被服务器踢出: ${reason}`));
+      };
+      bot.once("spawn", onSpawn);
+      bot.once("error", onEarlyError);
+      bot.once("end", onEarlyEnd);
+      bot.once("kicked", onEarlyKicked);
+    });
+  }
+
+  private attachListeners(bot: Bot): void {
+    bot.on("spawn", () => {
+      this.setupPathEngine();
+      this.bus.emit("spawn");
+      if (!this.joinedOnce) {
+        this.joinedOnce = true;
+        this.scheduleJoinCommands();
+      }
+    });
+    bot.on("chat", (username: string, message: string) => {
+      if (username === bot.username) return;
+      this.emitChat({ kind: "chat", username, text: message, at: Date.now() });
+    });
+    bot.on("whisper", (username: string, message: string) => {
+      if (username === bot.username) return;
+      this.emitChat({
+        kind: "whisper",
+        username,
+        text: message,
+        at: Date.now(),
+      });
+    });
+    bot.on("messagestr", (message: string) => {
+      const text = String(message || "").trim();
+      if (!text) return;
+      this.emitChat({ kind: "system", text, at: Date.now() });
+    });
+    bot.on("playerJoined", (player: any) => {
+      const name = player?.username;
+      if (!name || name === bot.username) return;
+      this.bus.emit("playerJoined", name);
+      this.emitChat({
+        kind: "join",
+        username: name,
+        text: `${name} 加入了游戏`,
+        at: Date.now(),
+      });
+    });
+    bot.on("playerLeft", (player: any) => {
+      const name = player?.username;
+      if (!name || name === bot.username) return;
+      this.bus.emit("playerLeft", name);
+      this.emitChat({
+        kind: "left",
+        username: name,
+        text: `${name} 离开了游戏`,
+        at: Date.now(),
+      });
+    });
+    bot.on("health", () => this.bus.emit("health"));
+    bot.on("death", () => {
+      this.bus.emit("death");
+      this.emitChat({
+        kind: "death",
+        username: bot.username,
+        text: `${bot.username} 死亡了`,
+        at: Date.now(),
+      });
+    });
+    bot.on("respawn", () => this.bus.emit("respawn"));
+    bot.on("entityHurt", (entity: any) => this.bus.emit("entityHurt", entity));
+    (bot as any).on("playerCollect", (collector: any) => {
+      if (collector?.id === bot.entity?.id) this.bus.emit("inventoryChanged");
+    });
+    (bot as any).on("heldItemChanged", () => this.bus.emit("inventoryChanged"));
+    (bot.inventory as any)?.on?.("updateSlot", () => this.bus.emit("inventoryChanged"));
+    bot.on("physicTick", () => this.bus.emit("physicTick"));
+    bot.on("kicked", (reason: string) =>
+      this.bus.emit("kicked", String(reason || "")),
+    );
+    bot.on("end", (reason: string) =>
+      this.bus.emit("end", String(reason || "")),
+    );
+    bot.on("error", (err: Error) => {
+      this.log(`bot 错误: ${err}`);
+      this.bus.emit("error", err);
+    });
+  }
+
+  private setupPathEngine(): void {
+    const bot = this.bot;
+    if (!bot) return;
+    try {
+      const movements: MovementsConfig = { ...DEFAULT_MOVEMENTS };
+      this.pathEngine = new PathEngine(bot, (m) => this.log(m));
+      this.pathEngine.setMovements(movements);
+      this.pathEngine.thinkTimeout = 5_000;
+      this.pathEngine.tickTimeout = 40;
+      (bot as any).pathEngine = this.pathEngine;
+      this.combat = new Combat(bot, movements);
+      this.combat.followRange = PVP_FOLLOW_RANGE;
+      this.combat.attackRange = PVP_ATTACK_RANGE;
+      (bot as any).combat = this.combat;
+      this.log(
+        `PathEngine + Combat 已初始化 canDig=${movements.canDig} parkour=${movements.allowParkour} sprint=${movements.allowSprinting} tower=${movements.allow1by1towers} thinkTimeout=${this.pathEngine.thinkTimeout}`,
+      );
+    } catch (err) {
+      this.log(`初始化 PathEngine 失败: ${err}`);
+    }
+  }
+
+  getMovements(): MovementsConfig | undefined {
+    return this.pathEngine?.movements;
+  }
+
+  async waitForChunksLoaded(): Promise<void> {
+    const bot = this.bot;
+    if (!bot) return;
+    const deadline = Date.now() + 20_000;
+    try {
+      await withTimeoutMs((bot as any).waitForChunksToLoad(), 20_000);
+    } catch {
+      this.log("等待区块加载超时，继续确认脚下方块");
+    }
+    while (Date.now() < deadline) {
+      const feet = bot.entity?.position;
+      if (feet && bot.blockAt(feet) != null) {
+        this.log("区块加载完成（脚下方块就绪）");
+        return;
+      }
+      await new Promise((r) => setTimeout(r, 300));
+    }
+    this.log("脚下区块仍未加载，物理 tick 可能跳过");
+  }
+
+  private scheduleJoinCommands(): void {
+    const cmds = this.server.joinCommands ?? [];
+    if (cmds.length === 0) return;
+    const run = () => {
+      const bot = this.bot;
+      if (!bot) return;
+      cmds.forEach((cmd, i) => {
+        setTimeout(() => {
+          try {
+            bot.chat(cmd);
+          } catch (e) {
+            this.log(`执行加入命令失败 (${i}): ${e}`);
+          }
+        }, i * 1_000);
+      });
+    };
+    setTimeout(run, 2_000);
+  }
+
+  private emitChat(line: GameChatLine): void {
+    this.bus.emit("chat", line);
+  }
+
+  chat(message: string): void {
+    const bot = this.bot;
+    if (!bot) return;
+    try {
+      bot.chat(message);
+    } catch (err) {
+      this.log(`发送聊天失败: ${err}`);
+    }
+  }
+
+  async disconnect(reason = "leaving"): Promise<void> {
+    const bot = this.bot;
+    if (!bot) return;
+    try {
+      this.pathEngine?.stop();
+    } catch {
+      // ignore
+    }
+    try {
+      bot.quit(reason);
+    } catch {
+      // ignore
+    }
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(() => resolve(), 2_000);
+      bot.once("end", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+
+  isOnline(): boolean {
+    return !!this.bot && !!(this.bot as any).entity;
+  }
+}

package/play/bot/play-bus.ts

@@ -0,0 +1,48 @@
+import { EventEmitter } from "events";
+
+export interface GameChatLine {
+  kind: "chat" | "whisper" | "join" | "left" | "death" | "system";
+  username?: string;
+  text: string;
+  at: number;
+}
+
+export interface PlayBusEvents {
+  spawn: () => void;
+  chat: (line: GameChatLine) => void;
+  health: () => void;
+  death: () => void;
+  respawn: () => void;
+  kicked: (reason: string) => void;
+  end: (reason: string) => void;
+  error: (err: Error) => void;
+  playerJoined: (username: string) => void;
+  playerLeft: (username: string) => void;
+  entityHurt: (entity: any) => void;
+  inventoryChanged: () => void;
+  physicTick: () => void;
+}
+
+export type PlayBusEvent = keyof PlayBusEvents;
+
+export class PlayBus {
+  private emitter = new EventEmitter();
+
+  emit<K extends PlayBusEvent>(event: K, ...args: any[]): void {
+    this.emitter.emit(event, ...args);
+  }
+
+  on<K extends PlayBusEvent>(event: K, listener: PlayBusEvents[K]): this {
+    this.emitter.on(event, listener as (...args: any[]) => void);
+    return this;
+  }
+
+  off<K extends PlayBusEvent>(event: K, listener: PlayBusEvents[K]): this {
+    this.emitter.off(event, listener as (...args: any[]) => void);
+    return this;
+  }
+
+  removeAll(): void {
+    this.emitter.removeAllListeners();
+  }
+}

package/play/combat/combat.ts

@@ -0,0 +1,225 @@
+import type { Bot } from "mineflayer";
+import { GoalFollow, type MovementsConfig } from "../path-engine";
+import { entityName } from "../util/entities";
+import { hasShield } from "../util/inventory";
+
+const SHIELD_BLOCK_DURATION_MS = 2000;
+const PRE_ATTACK_DELAY_MS = 50;
+const POST_ATTACK_DELAY_MS = 50;
+const ATTACK_COOLDOWN_TICKS = 12;
+const REEQUIP_INTERVAL_MS = 3000;
+
+export class Combat {
+  private readonly bot: Bot;
+  private target: any = null;
+  private attacking = false;
+  private timeToNextAttack = 0;
+  private lastShieldBlockAt = 0;
+  private lastEquipAt = 0;
+  private resolveAttack: (() => void) | null = null;
+
+  movements: MovementsConfig;
+  followRange = 2;
+  attackRange = 3.5;
+  viewDistance = 128;
+
+  constructor(bot: Bot, movements: MovementsConfig) {
+    this.bot = bot;
+    this.movements = movements;
+    bot.on("physicTick", () => this.update());
+  }
+
+  attack(target: any): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.target && this.target !== target) {
+        this.stop();
+      }
+      this.target = target;
+      this.attacking = false;
+      this.timeToNextAttack = 0;
+      this.lastShieldBlockAt = 0;
+      this.lastEquipAt = 0;
+      this.resolveAttack = resolve;
+
+      void this.equipBestWeapon();
+      const engine = (this.bot as any).pathEngine;
+      if (engine) {
+        try {
+          engine.setGoal(new GoalFollow(target, this.followRange), true);
+        } catch {
+          // ignore
+        }
+      }
+    });
+  }
+
+  stop(): void {
+    if (this.resolveAttack) {
+      this.resolveAttack();
+      this.resolveAttack = null;
+    }
+    this.target = null;
+    this.attacking = false;
+    const engine = (this.bot as any).pathEngine;
+    if (engine) {
+      try {
+        engine.setGoal(null);
+      } catch {
+        // ignore
+      }
+    }
+    if (this.lastShieldBlockAt > 0) {
+      try {
+        (this.bot as any).deactivateItem();
+      } catch {
+        // ignore
+      }
+      this.lastShieldBlockAt = 0;
+    }
+  }
+
+  isInCombat(): boolean {
+    return this.target !== null;
+  }
+
+  getTarget(): any | null {
+    return this.target;
+  }
+
+  private async equipBestWeapon(): Promise<void> {
+    try {
+      const items = this.bot.inventory?.items?.() ?? [];
+      const sword = items.find((i: any) => /_sword$/.test(i.name));
+      const axe = items.find((i: any) => /_axe$/.test(i.name) && !/pickaxe/.test(i.name));
+      const best = sword ?? axe;
+      if (best) {
+        const held = this.bot.heldItem;
+        if (!held || held.type !== best.type) {
+          await this.bot.equip(best, "hand");
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  private update(): void {
+    if (!this.target) return;
+    const entity = this.bot.entity;
+    if (!entity) return;
+
+    if (!this.target.position) {
+      this.stop();
+      return;
+    }
+
+    const targetPos = this.target.position;
+    const dist = Math.sqrt(
+      (targetPos.x - entity.position.x) ** 2 +
+        (targetPos.y - entity.position.y) ** 2 +
+        (targetPos.z - entity.position.z) ** 2,
+    );
+
+    if (dist > this.viewDistance) {
+      this.stop();
+      return;
+    }
+
+    this.handleShield(targetPos, dist);
+
+    if (dist <= this.attackRange) {
+      if (!this.attacking && this.timeToNextAttack <= 0) {
+        const now = Date.now();
+        if (now - this.lastEquipAt > REEQUIP_INTERVAL_MS) {
+          this.lastEquipAt = now;
+          void this.equipBestWeapon();
+        }
+        this.attacking = true;
+        this.attemptAttack(targetPos);
+      }
+    } else {
+      this.attacking = false;
+    }
+
+    if (this.timeToNextAttack > 0) this.timeToNextAttack--;
+  }
+
+  private handleShield(targetPos: any, _dist: number): void {
+    if (entityName(this.target) !== "creeper") {
+      if (this.lastShieldBlockAt > 0 && Date.now() - this.lastShieldBlockAt > SHIELD_BLOCK_DURATION_MS) {
+        try {
+          (this.bot as any).deactivateItem();
+        } catch {
+          // ignore
+        }
+        this.lastShieldBlockAt = 0;
+      }
+      return;
+    }
+
+    const fuseActive = this.target.metadata?.[16] === 1;
+    if (fuseActive && hasShield(this.bot) && this.lastShieldBlockAt === 0) {
+      this.lastShieldBlockAt = Date.now();
+      try {
+        (this.bot as any).pathEngine?.stop();
+        (this.bot as any).lookAt(targetPos.offset(0, 1, 0), true);
+        (this.bot as any).activateItem(true);
+      } catch {
+        // ignore
+      }
+      return;
+    }
+
+    if (this.lastShieldBlockAt > 0 && Date.now() - this.lastShieldBlockAt > SHIELD_BLOCK_DURATION_MS) {
+      try {
+        (this.bot as any).deactivateItem();
+      } catch {
+        // ignore
+      }
+      this.lastShieldBlockAt = 0;
+    }
+  }
+
+  private async attemptAttack(targetPos: any): Promise<void> {
+    const target = this.target;
+    if (!target) {
+      this.attacking = false;
+      return;
+    }
+    const shield = hasShield(this.bot);
+    try {
+      if (shield) {
+        try {
+          (this.bot as any).deactivateItem();
+        } catch {
+          // ignore
+        }
+        await new Promise((r) => setTimeout(r, PRE_ATTACK_DELAY_MS));
+      }
+      const height = target.height ?? 1;
+      try {
+        await (this.bot as any).lookAt(targetPos.offset(0, height, 0), true);
+      } catch {
+        // ignore
+      }
+      try {
+        await (this.bot as any).attack(target);
+      } catch {
+        // ignore
+      }
+      if (shield) {
+        await new Promise((r) => setTimeout(r, POST_ATTACK_DELAY_MS));
+        try {
+          (this.bot as any).activateItem(true);
+        } catch {
+          // ignore
+        }
+      }
+      this.timeToNextAttack = ATTACK_COOLDOWN_TICKS;
+    } catch {
+      // ignore
+    } finally {
+      this.attacking = false;
+    }
+  }
+}

package/play/combat/index.ts

@@ -0,0 +1 @@
+export * from "./combat";

package/play/config.ts

@@ -0,0 +1,39 @@
+import type { ConfigService } from "mioku";
+import {
+  DEFAULT_PLAY_CONFIG,
+  normalizePlayConfig,
+  type GroupBinding,
+  type PlayConfig,
+  type PlayServerConfig,
+} from "./types";
+
+export function createPlayConfigHandler(configService: ConfigService | undefined) {
+  let currentConfig: PlayConfig = { ...DEFAULT_PLAY_CONFIG };
+
+  const register = async () => {
+    if (!configService) return;
+    await configService.registerConfig("mc", "play", DEFAULT_PLAY_CONFIG);
+    const raw = await configService.getConfig("mc", "play");
+    currentConfig = normalizePlayConfig(raw);
+    configService.onConfigChange("mc", "play", (next) => {
+      currentConfig = normalizePlayConfig(next);
+    });
+  };
+
+  const getConfig = () => currentConfig;
+
+  const findServer = (serverId: string): PlayServerConfig | null => {
+    const id = String(serverId ?? "").trim();
+    return currentConfig.servers.find((s) => s.id === id) ?? null;
+  };
+
+  const findBinding = (groupId: number | string): GroupBinding | null => {
+    const gid = Number(groupId);
+    if (!Number.isFinite(gid) || gid <= 0) return null;
+    return currentConfig.groups.find((g) => g.groupId === gid) ?? null;
+  };
+
+  return { register, getConfig, findServer, findBinding };
+}
+
+export type PlayConfigHandler = ReturnType<typeof createPlayConfigHandler>;

package/play/context.ts

@@ -0,0 +1,26 @@
+import type { MiokiContext } from "mioki";
+import type { AIService, AIInstance, ConfigService } from "mioku";
+import type { PlayConfig } from "./types";
+import type { ConfigHandler } from "../utils/config-handler";
+import type { WorkSubroutine, WorkTerminator } from "./ai/work-subroutine";
+import type { PlaySession } from "./session";
+
+export interface PlayPluginContext {
+  ctx: MiokiContext;
+  config: PlayConfig;
+  aiService: AIService | undefined;
+  configService: ConfigService | undefined;
+  syncConfigHandler: ConfigHandler;
+  mainInstance: AIInstance | undefined;
+  workInstance: AIInstance | undefined;
+  getPlayConfig: () => PlayConfig;
+  refreshInstances: () => void;
+  createWorkSubroutine: (opts: {
+    session: PlaySession;
+    goal: string;
+    terminator: WorkTerminator;
+    maxMs?: number;
+    maxIterations?: number;
+  }) => WorkSubroutine;
+  notifyChatScan?: () => void;
+}

package/play/debug/README.md

@@ -0,0 +1,74 @@
+# mc play 调试命令
+
+> 仅当 `config/mc/play.json` 的 `debug.enabled = true` 且发送者为 bot 主人（owner）时生效。
+> 这些命令不注册到帮助系统，仅供调试/测试行为引擎使用，不会触发 AI 循环。
+
+正常模式下 AI 采用事件驱动：稳定执行任务时不会周期调用 Working AI；新主指令、受伤、昼夜变化或任务失败才会唤醒它。QQ 消息只进入 MC Main AI 的下次上下文，不单独触发，也不会由 MC Main AI 回复。
+
+## 开关
+
+在 `config/mc/play.json` 中：
+
+```json
+{ "debug": { "enabled": true } }
+```
+
+开启后，bot 主人在**已配置游玩绑定的群**里发送以下命令即可。`/join` 进入后**不会启动主模型循环**，bot 只连接服务器并保持 idle 行为；主人用命令手动操控。
+
+## 命令清单
+
+| 命令 | 作用 | 示例 |
+|------|------|------|
+| `/join <服务器ID>` | 以 debug 模式进入服务器（无 AI 循环） | `/join survival` |
+| `/play <服务器ID>` | 进入服务器并启动完整 AI 循环（等同主人让 bot 正常进服） | `/play survival` |
+| `/exit` | 离开当前服务器 | `/exit` |
+| `/say <文本>` | 让 bot 在游戏内发言 | `/say 大家好~` |
+| `/motion <移动行为> [key=value ...]` | 设置移动行为 | `/motion follow target=Steve distance=3` |
+| `/motion <defend\|auto_eat> [key=...]` | 切换叠加状态（开/关） | `/motion defend radius=10` |
+| `/stop` | 停止移动，回 idle（叠加状态保留） | `/stop` |
+| `/clear` | 清空所有状态（移动 + 叠加） | `/clear` |
+| `/off <名称>` | 关闭指定叠加状态 | `/off defend` |
+| `/status` | 查看启用的状态 & 正在执行的行为 | `/status` |
+| `/behaviors` | 列出所有行为及参数 | `/behaviors` |
+| `/actions` | 列出 Working AI 可用的一次性动作 | `/actions` |
+
+行为系统的并发模型、每个状态的含义、参数说明详见 [`play/behavior/README.md`](../behavior/README.md)。
+
+## 移动行为（`/motion`，同时只能有一个）
+
+- `idle`
+- `follow target=<玩家名> [distance=<格>]`
+- `gather resource=<wood|stone|coal|iron>`
+- `farm_mobs`
+- `explore`
+- `approach_player target=<玩家名> [distance=<格>]`
+- `seek_shelter`
+
+## 叠加状态（`/motion`，可同时开多个，按优先级抢占移动）
+
+- `defend [radius=<格, 默认8>]` - 自动战斗，敌对生物靠近时抢占移动去攻击
+- `auto_eat` - 自动进食，饥饿且有食物且不在战斗时进食
+
+生存层（escape_lava / mlg_fall / flee_creeper / escape_water）常驻，无需开启。
+
+### 示例：同时跟随 + 自动战斗 + 自动进食
+
+```
+/join survival
+/motion auto_eat                          # 开自动进食
+/motion defend                            # 开自动战斗
+/motion follow target=Steve distance=3    # 跟随 Steve
+/status                                   # 看三个状态都启用了
+/stop                                     # 停跟随（叠加保留）
+/clear                                    # 全清
+/exit
+```
+
+## 说明
+
+- `/join` 走的是 debug 入口：bot 连接服务器、启动行为引擎与生存层（岩浆/MLG/苦力怕/溺水/饥饿仍会自动抢占保护），但**不启动主模型循环和工作模型**。所以 bot 不会自己说话或决策，全靠主人的命令。
+- `/play` 走的是正常入口：bot 连接服务器并启动完整的 main + work AI 循环（与 QQ 触发 `control_bot` 进服效果一致）。**仅在调试时观察 AI 实际行为**时使用；生产场景请走 `control_bot` 工具。
+- `/say` 和 `/motion` 需要已有一个进行中的会话（先 `/join` 或 `/play`）。bot 尚未连接完成时会回复"bot 尚未连接到服务器"。
+- 生存层在 debug 模式下仍然生效——例如测试 `follow` 时若苦力怕靠近，会自动撤离。
+- 正常的 AI 入口（chat 主模型调用 `mc.control_bot` 工具）与 debug 互不影响；AI 入口会启动完整循环。
+- 关闭 debug 后这些命令不再被拦截，会当作普通群消息处理。