mioku-plugin-mc 2.0.0 → 3.0.0

package/play/behavior/base-behavior.ts

@@ -0,0 +1,82 @@
+import type { Bot } from "mineflayer";
+import type { MovementsConfig } from "../path-engine";
+
+export interface BehaviorContext {
+  bot: Bot;
+  movements: MovementsConfig;
+  log: (msg: string) => void;
+}
+
+export interface BehaviorMissionReporter {
+  progress(value: unknown): void;
+  succeed(detail?: string, progress?: unknown): void;
+  fail(code: import("../state/mode").MissionErrorCode, detail: string, progress?: unknown): void;
+  block(code: import("../state/mode").MissionErrorCode, detail: string, progress?: unknown): void;
+  isCurrent(): boolean;
+}
+
+export type BehaviorCategory = "survival" | "combat" | "maintenance" | "movement";
+
+export const CATEGORY_PRIORITY: Record<BehaviorCategory, number> = {
+  survival: 100,
+  combat: 70,
+  maintenance: 60,
+  movement: 50,
+};
+
+export abstract class Behavior {
+  abstract readonly name: string;
+  abstract readonly category: BehaviorCategory;
+  readonly priorityOverride?: number;
+  enabled = false;
+  protected params: Record<string, string> = {};
+  protected mission?: BehaviorMissionReporter;
+
+  get priority(): number {
+    return this.priorityOverride ?? CATEGORY_PRIORITY[this.category];
+  }
+
+  get effectivelyEnabled(): boolean {
+    return this.enabled || this.category === "survival";
+  }
+
+  isActive(_ctx: BehaviorContext): boolean {
+    return true;
+  }
+
+  onStart(_ctx: BehaviorContext): void | Promise<void> {
+    // noop by default
+  }
+
+  abstract onTick(ctx: BehaviorContext): void | Promise<void>;
+
+  onStop(_ctx: BehaviorContext): void | Promise<void> {
+    // noop by default
+  }
+
+  isFinished(): boolean {
+    return false;
+  }
+
+  /**
+   * 对外暴露的内部状态（LLM 调试 / snapshot 用）。
+   * 默认返回空对象；子类覆写以贡献字段。键名应稳定、字符串或简单类型，
+   * 不返回 entity.position 等敏感坐标（距离/ID/名字 安全）。
+   */
+  contributesState(_ctx: BehaviorContext): Record<string, unknown> {
+    return {};
+  }
+
+  configure(params: Record<string, string>): void {
+    this.params = params;
+    this.onConfigure(params);
+  }
+
+  protected onConfigure(_params: Record<string, string>): void {
+    // subclasses read params here
+  }
+
+  bindMission(reporter: BehaviorMissionReporter): void {
+    this.mission = reporter;
+  }
+}

package/play/behavior/catalog/approach-player.ts

@@ -0,0 +1,65 @@
+import { Behavior, type BehaviorContext } from "../base-behavior";
+import { GoalFollow } from "../../path-engine";
+import { entityDistance } from "../../util/entities";
+
+export class ApproachPlayerBehavior extends Behavior {
+  readonly name = "approach_player";
+  readonly category = "movement" as const;
+  private target = "";
+  private distance = 3;
+  private lastGoalAt = 0;
+  private missingSince = 0;
+
+  protected onConfigure(params: Record<string, string>): void {
+    this.target = params.target ?? "";
+    this.distance = Math.max(1, Number(params.distance) || 3);
+  }
+
+  isActive(): boolean {
+    return !!this.target;
+  }
+
+  onTick(ctx: BehaviorContext): void {
+    const player = ctx.bot.players[this.target]?.entity;
+    if (!player) {
+      if (!this.missingSince) this.missingSince = Date.now();
+      if (Date.now() - this.missingSince >= 5_000) {
+        this.mission?.block("target_not_found", `找不到玩家 ${this.target}`);
+      }
+      return;
+    }
+    this.missingSince = 0;
+    const distance = entityDistance(ctx.bot.entity, player);
+    this.mission?.progress({
+      target: this.target,
+      distance: Math.round(distance * 10) / 10,
+    });
+    if (distance <= this.distance) {
+      this.mission?.succeed(`已接近玩家 ${this.target}`, {
+        target: this.target,
+        distance,
+      });
+      return;
+    }
+    const engine = ctx.bot.pathEngine;
+    if (!engine || engine.isMoving() || Date.now() - this.lastGoalAt < 2_000)
+      return;
+    try {
+      engine.setGoal(new GoalFollow(player, this.distance), true);
+      this.lastGoalAt = Date.now();
+    } catch (error) {
+      this.mission?.fail("path_unreachable", String(error), {
+        target: this.target,
+        distance,
+      });
+    }
+  }
+
+  onStop(ctx: BehaviorContext): void {
+    try {
+      ctx.bot.pathEngine?.stop();
+    } catch {
+      // ignore
+    }
+  }
+}

package/play/behavior/catalog/defend.ts

@@ -0,0 +1,68 @@
+import { Behavior, type BehaviorContext } from "../base-behavior";
+import { nearestHostile, entityName, entityDistance } from "../../util/entities";
+import { equipSword } from "../../util/inventory";
+
+export class SelfDefenseBehavior extends Behavior {
+  readonly name = "defend";
+  readonly category = "combat" as const;
+  private radius = 8;
+  private armed = false;
+  private attacking = false;
+
+  protected onConfigure(params: Record<string, string>): void {
+    this.radius = Number(params.radius) || 8;
+  }
+
+  isActive(ctx: BehaviorContext): boolean {
+    return nearestHostile(ctx.bot, this.radius) !== null;
+  }
+
+  onStart(): void {
+    this.armed = false;
+    this.attacking = false;
+  }
+
+  async onTick(ctx: BehaviorContext): Promise<void> {
+    const combat = ctx.bot.combat;
+    if (!combat) return;
+    if (!this.armed) {
+      await equipSword(ctx.bot);
+      this.armed = true;
+    }
+    const target = nearestHostile(ctx.bot, this.radius);
+    if (!target) {
+      this.attacking = false;
+      combat.stop();
+      return;
+    }
+    if (this.attacking) return;
+    ctx.log(
+      `defend 攻击 ${entityName(target)} (dist=${entityDistance(ctx.bot.entity, target).toFixed(1)})`,
+    );
+    this.attacking = true;
+    combat
+      .attack(target)
+      .catch(() => {
+        // ignore
+      })
+      .finally(() => {
+        this.attacking = false;
+      });
+  }
+
+  onStop(ctx: BehaviorContext): void {
+    try {
+      ctx.bot.combat?.stop();
+    } catch {
+      // ignore
+    }
+  }
+
+  contributesState(): Record<string, unknown> {
+    return {
+      radius: this.radius,
+      armed: this.armed,
+      attacking: this.attacking,
+    };
+  }
+}

package/play/behavior/catalog/explore.ts

@@ -0,0 +1,72 @@
+import { Behavior, type BehaviorContext } from "../base-behavior";
+import { GoalXZ } from "../../path-engine";
+
+const EXPLORE_HALF_RANGE = 12;
+const GOTO_TIMEOUT_MS = 10_000;
+
+export class ExploreBehavior extends Behavior {
+  readonly name = "explore";
+  readonly category = "movement" as const;
+  private exploring = false;
+
+  onTick(ctx: BehaviorContext): void {
+    if (this.exploring) return;
+    const engine = ctx.bot.pathEngine;
+    if (!engine) return;
+    const pos = ctx.bot.entity?.position;
+    if (!pos) return;
+    const gx = Math.floor(pos.x + (Math.random() - 0.5) * EXPLORE_HALF_RANGE * 2);
+    const gz = Math.floor(pos.z + (Math.random() - 0.5) * EXPLORE_HALF_RANGE * 2);
+    this.exploring = true;
+    ctx.log(`explore -> (${gx},${gz})`);
+
+    const gotoPromise = engine.goto(new GoalXZ(gx, gz));
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        engine.stop();
+      } catch {
+        // ignore
+      }
+    }, GOTO_TIMEOUT_MS);
+
+    gotoPromise
+      .then(() => {
+        if (!timedOut) {
+          ctx.log(`explore 到达 (${gx},${gz})`);
+          this.mission?.succeed("已完成一次探索移动", { x: gx, z: gz });
+        } else {
+          this.mission?.fail("path_timeout", `探索目标 (${gx},${gz}) 超时`);
+        }
+      })
+      .catch((e: any) => {
+        ctx.log(`explore 放弃 (${gx},${gz}): ${e}`);
+        this.mission?.fail("path_unreachable", String(e), { x: gx, z: gz });
+      })
+      .finally(() => {
+        clearTimeout(timer);
+        try {
+          engine.setGoal(null);
+        } catch {
+          // ignore
+        }
+        this.exploring = false;
+      });
+  }
+
+  onStop(ctx: BehaviorContext): void {
+    try {
+      ctx.bot.pathEngine?.stop();
+    } catch {
+      // ignore
+    }
+    this.exploring = false;
+  }
+
+  contributesState(): Record<string, unknown> {
+    return {
+      exploring: this.exploring,
+    };
+  }
+}

package/play/behavior/catalog/factory.ts

@@ -0,0 +1,26 @@
+import type { Behavior } from "../base-behavior";
+import type { MovementInit } from "../../types";
+import { IdleWanderBehavior } from "./idle";
+import { FollowPlayerBehavior } from "./follow";
+import { GatherResourceBehavior } from "./gather";
+import { FarmMobsBehavior } from "./farm-mobs";
+import { ExploreBehavior } from "./explore";
+
+const MOVEMENT_FACTORIES: Record<string, () => Behavior> = {
+  idle: () => new IdleWanderBehavior(),
+  follow: () => new FollowPlayerBehavior(),
+  gather: () => new GatherResourceBehavior(),
+  farm_mobs: () => new FarmMobsBehavior(),
+  explore: () => new ExploreBehavior(),
+};
+
+export function createBehavior(init: MovementInit): Behavior {
+  const factory = MOVEMENT_FACTORIES[init.name];
+  const behavior = factory ? factory() : new IdleWanderBehavior();
+  behavior.configure(init.params ?? {});
+  return behavior;
+}
+
+export function hasMovementFactory(name: string): boolean {
+  return name in MOVEMENT_FACTORIES;
+}

package/play/behavior/catalog/farm-mobs.ts

@@ -0,0 +1,43 @@
+import { Behavior, type BehaviorContext } from "../base-behavior";
+import { nearestPassiveMob } from "../../util/entities";
+import { equipSword } from "../../util/inventory";
+
+const HUNT_RADIUS = 20;
+
+export class FarmMobsBehavior extends Behavior {
+  readonly name = "farm_mobs";
+  readonly category = "movement" as const;
+  private hunting = false;
+
+  async onTick(ctx: BehaviorContext): Promise<void> {
+    if (this.hunting) return;
+    const combat = ctx.bot.combat;
+    if (!combat) return;
+    const target = nearestPassiveMob(ctx.bot, HUNT_RADIUS);
+    if (!target) return;
+    this.hunting = true;
+    await equipSword(ctx.bot);
+    combat
+      .attack(target)
+      .catch(() => {
+        // ignore
+      })
+      .finally(() => {
+        this.hunting = false;
+      });
+  }
+
+  onStop(ctx: BehaviorContext): void {
+    try {
+      ctx.bot.combat?.stop();
+    } catch {
+      // ignore
+    }
+  }
+
+  contributesState(): Record<string, unknown> {
+    return {
+      hunting: this.hunting,
+    };
+  }
+}

package/play/behavior/catalog/follow.ts

@@ -0,0 +1,80 @@
+import { Behavior, type BehaviorContext } from "../base-behavior";
+import { GoalFollow } from "../../path-engine";
+import { entityDistance } from "../../util/entities";
+
+export class FollowPlayerBehavior extends Behavior {
+  readonly name = "follow";
+  readonly category = "movement" as const;
+  private target = "";
+  private distance = 3;
+  private lastDist = -1;
+  private warnedNoEntity = false;
+  private lastGoalAt = 0;
+  private missingSince = 0;
+  private seenTarget = false;
+
+  protected onConfigure(params: Record<string, string>): void {
+    this.target = params.target ?? "";
+    this.distance = Number(params.distance) || 3;
+  }
+
+  isActive(ctx: BehaviorContext): boolean {
+    void ctx;
+    return !!this.target;
+  }
+
+  onTick(ctx: BehaviorContext): void {
+    const bot = ctx.bot;
+    const engine = bot.pathEngine;
+    const player = bot.players[this.target]?.entity;
+    if (!player) {
+      if (!this.missingSince) this.missingSince = Date.now();
+      if (!this.warnedNoEntity) {
+        ctx.log(`follow 找不到玩家 ${this.target} 的实体（不在视野/未加载）`);
+        this.warnedNoEntity = true;
+      }
+      if (Date.now() - this.missingSince >= (this.seenTarget ? 3_000 : 5_000)) {
+        const code = this.seenTarget ? "target_lost" : "target_not_found";
+        this.mission?.block(code, `无法继续跟随玩家 ${this.target}`, {
+          target: this.target,
+          seenTarget: this.seenTarget,
+        });
+      }
+      return;
+    }
+    this.seenTarget = true;
+    this.missingSince = 0;
+    this.warnedNoEntity = false;
+    this.lastDist = entityDistance(bot.entity, player);
+    if (!engine) return;
+    if (engine.isMoving()) return;
+    const now = Date.now();
+    if (now - this.lastGoalAt < 2000) return;
+    if (this.lastDist > this.distance + 1) {
+      try {
+        engine.setGoal(new GoalFollow(player, this.distance), true);
+        this.lastGoalAt = now;
+        ctx.log(`follow -> ${this.target} (dist=${this.lastDist.toFixed(1)}, goal=${this.distance})`);
+      } catch (e) {
+        ctx.log(`follow 寻路失败: ${e}`);
+      }
+    }
+  }
+
+  onStop(ctx: BehaviorContext): void {
+    try {
+      ctx.bot.pathEngine?.stop();
+    } catch {
+      // ignore
+    }
+  }
+
+  contributesState(): Record<string, unknown> {
+    return {
+      target: this.target || null,
+      distance: this.distance,
+      lastObservedDist: this.lastDist < 0 ? null : Math.round(this.lastDist * 10) / 10,
+      seenTarget: this.seenTarget,
+    };
+  }
+}

package/play/behavior/catalog/gather.ts

@@ -0,0 +1,135 @@
+import { Behavior, type BehaviorContext } from "../base-behavior";
+import { GoalGetToBlock } from "../../path-engine";
+import { equipToolFor } from "../../util/inventory";
+
+const RESOURCE_MATCHERS: Record<string, (name: string) => boolean> = {
+  wood: (n) => /_log$/.test(n),
+  stone: (n) =>
+    /^(stone|cobblestone|andesite|diorite|granite|deepslate|tuff|basalt|calcite|dripstone_block)/.test(
+      n,
+    ),
+  coal: (n) => /coal_ore/.test(n),
+  iron: (n) => /iron_ore/.test(n),
+  dirt: (n) => /^(dirt|grass_block|coarse_dirt|rooted_dirt|podzol|mycelium)$/.test(n),
+};
+
+export class GatherResourceBehavior extends Behavior {
+  readonly name = "gather";
+  readonly category = "movement" as const;
+  private resource = "wood";
+  private targetCount = 1;
+  private gathered = 0;
+  private mining = false;
+  private missingSince = 0;
+
+  protected onConfigure(params: Record<string, string>): void {
+    this.resource = params.resource ?? "wood";
+    this.targetCount = Math.max(1, Number(params.count) || 1);
+  }
+
+  onTick(ctx: BehaviorContext): void {
+    if (this.mining) return;
+    const matcher = RESOURCE_MATCHERS[this.resource];
+    if (!matcher) return;
+    const block = ctx.bot.findBlock({
+      matching: (b: any) => !!b && matcher(b.name),
+      maxDistance: 32,
+    } as any);
+    if (!block) {
+      if (!this.missingSince) this.missingSince = Date.now();
+      if (Date.now() - this.missingSince >= 5_000) {
+        this.mission?.block("resource_not_found", `附近找不到资源 ${this.resource}`, {
+          resource: this.resource,
+          gathered: this.gathered,
+          targetCount: this.targetCount,
+        });
+      }
+      return;
+    }
+    this.missingSince = 0;
+
+    const engine = ctx.bot.pathEngine;
+    if (!engine) return;
+
+    this.mining = true;
+    void (async () => {
+      const timer = setTimeout(() => {
+        try {
+          engine.stop();
+        } catch {
+          // ignore
+        }
+      }, 12_000);
+      try {
+        const emptySlots = (ctx.bot.inventory as any)?.emptySlotCount?.();
+        if (emptySlots === 0) {
+          this.mission?.block("inventory_full", "背包已满，无法继续采集", {
+            resource: this.resource,
+            gathered: this.gathered,
+            targetCount: this.targetCount,
+          });
+          return;
+        }
+        const needsTool = this.resource !== "wood" && this.resource !== "dirt";
+        const equipped = await equipToolFor(ctx.bot, this.resource);
+        if (needsTool && !equipped) {
+          this.mission?.block("missing_tool", `采集 ${this.resource} 需要合适的镐`, {
+            resource: this.resource,
+            gathered: this.gathered,
+            targetCount: this.targetCount,
+          });
+          return;
+        }
+        if (this.mission && !this.mission.isCurrent()) return;
+        await engine.goto(
+          new GoalGetToBlock(block.position.x, block.position.y, block.position.z),
+        );
+        if (this.mission && !this.mission.isCurrent()) return;
+        await ctx.bot.dig(block);
+        this.gathered++;
+        const progress = {
+          resource: this.resource,
+          gathered: this.gathered,
+          targetCount: this.targetCount,
+        };
+        this.mission?.progress(progress);
+        if (this.gathered >= this.targetCount) {
+          this.mission?.succeed(`已采集 ${this.gathered} 个 ${this.resource}`, progress);
+        }
+      } catch (e) {
+        ctx.log(`gather 失败: ${e}`);
+        const message = String(e);
+        this.mission?.fail(
+          /timeout/i.test(message) ? "path_timeout" : "path_unreachable",
+          message,
+          { resource: this.resource, gathered: this.gathered, targetCount: this.targetCount },
+        );
+      } finally {
+        clearTimeout(timer);
+        try {
+          engine.setGoal(null);
+        } catch {
+          // ignore
+        }
+        this.mining = false;
+      }
+    })();
+  }
+
+  onStop(ctx: BehaviorContext): void {
+    try {
+      ctx.bot.pathEngine?.stop();
+    } catch {
+      // ignore
+    }
+  }
+
+  contributesState(): Record<string, unknown> {
+    return {
+      resource: this.resource,
+      targetCount: this.targetCount,
+      gathered: this.gathered,
+      mining: this.mining,
+    };
+  }
+}

package/play/behavior/catalog/idle.ts

@@ -0,0 +1,130 @@
+import { Behavior, type BehaviorContext } from "../base-behavior";
+import { nearestPlayer, nearestPassiveMob, nearestHostile } from "../../util/entities";
+
+const LOOK_INTERVAL_MS = 500;
+const WANDER_INTERVAL_MS = 4_000;
+const WANDER_JITTER_MS = 3_000;
+const STEP_MS = 800;
+const LOOK_IDLE_MS = 1_500;
+const DO_NOTHING_MIN_MS = 1_500;
+const DO_NOTHING_JITTER_MS = 1_500;
+const LOOK_RADIUS = 8;
+
+type Action = "look" | "walk" | "idle";
+
+export class IdleWanderBehavior extends Behavior {
+  readonly name = "idle";
+  readonly category = "movement" as const;
+  private nextWanderAt = 0;
+  private nextLookAt = 0;
+  private movingUntil = 0;
+  private idleUntil = 0;
+  private lastAction: Action = "idle";
+  private lookTarget: "player" | "passive" | "hostile" | null = null;
+
+  onStart(): void {
+    const now = Date.now();
+    this.nextWanderAt = now + 1_000;
+    this.nextLookAt = now;
+    this.movingUntil = 0;
+    this.idleUntil = 0;
+    this.lastAction = "idle";
+    this.lookTarget = null;
+  }
+
+  onTick(ctx: BehaviorContext): void {
+    const now = Date.now();
+    if (this.movingUntil && now >= this.movingUntil) {
+      try {
+        ctx.bot.clearControlStates();
+      } catch {
+        // ignore
+      }
+      this.movingUntil = 0;
+    }
+    if (!this.movingUntil && now >= this.nextLookAt) {
+      this.tickLook(ctx);
+      this.nextLookAt = now + LOOK_INTERVAL_MS;
+    }
+    if (this.idleUntil && now < this.idleUntil) return;
+    if (now >= this.nextWanderAt) {
+      this.tickRandomAction(ctx, now);
+    } else if (this.movingUntil > now) {
+      this.lastAction = "walk";
+    } else {
+      this.lastAction = "idle";
+    }
+  }
+
+  private tickLook(ctx: BehaviorContext): void {
+    const target = this.pickLookTarget(ctx);
+    try {
+      if (target) {
+        ctx.bot.lookAt(target.position.offset(0, 1, 0), true);
+      } else {
+        ctx.bot.look(Math.random() * Math.PI * 2, (Math.random() - 0.5) * 0.6, true);
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  private pickLookTarget(ctx: BehaviorContext): any | null {
+    const player = nearestPlayer(ctx.bot, LOOK_RADIUS);
+    if (player) {
+      this.lookTarget = "player";
+      return player;
+    }
+    const passive = nearestPassiveMob(ctx.bot, LOOK_RADIUS);
+    if (passive) {
+      this.lookTarget = "passive";
+      return passive;
+    }
+    const hostile = nearestHostile(ctx.bot, LOOK_RADIUS);
+    if (hostile) {
+      this.lookTarget = "hostile";
+      return hostile;
+    }
+    this.lookTarget = null;
+    return null;
+  }
+
+  private tickRandomAction(ctx: BehaviorContext, now: number): void {
+    const r = Math.random() * 7;
+    if (r < 2) {
+      this.lastAction = "look";
+      this.idleUntil = now + LOOK_IDLE_MS;
+    } else if (r < 4) {
+      try {
+        ctx.bot.look(Math.random() * Math.PI * 2, 0, true);
+        ctx.bot.setControlState("forward", true);
+        this.movingUntil = now + STEP_MS;
+        this.lastAction = "walk";
+      } catch {
+        // ignore
+      }
+    } else {
+      this.lastAction = "idle";
+      this.idleUntil = now + DO_NOTHING_MIN_MS + Math.random() * DO_NOTHING_JITTER_MS;
+    }
+    this.nextWanderAt = now + WANDER_INTERVAL_MS + Math.random() * WANDER_JITTER_MS;
+  }
+
+  onStop(ctx: BehaviorContext): void {
+    try {
+      ctx.bot.clearControlStates();
+    } catch {
+      // ignore
+    }
+  }
+
+  contributesState(): Record<string, unknown> {
+    const now = Date.now();
+    return {
+      lastAction: this.lastAction,
+      lookTarget: this.lookTarget,
+      nextWanderInMs: Math.max(0, this.nextWanderAt - now),
+      moving: this.movingUntil > now,
+    };
+  }
+}