@rpgjs/action-battle 5.0.0-beta.11 → 5.0.0-beta.13

package/src/ai.server.ts

@@ -1,9 +1,9 @@
 import { MAXHP, RpgEvent, RpgPlayer } from "@rpgjs/server";
 import {
   getActionBattleAnimationRemovalDelay,
-  playActionBattleAnimation,
   resolveActionBattleAnimation,
 } from "./animations";
+import { emitActionBattleClientVisual } from "./visual";
 import { getActionBattleOptions } from "./config";
 import { getActionBattleSystems } from "./core/context";
 import {
@@ -16,10 +16,40 @@ import {
   type NormalizedActionBattleEnemyAttackProfileMap,
 } from "./core/enemy-attack-profiles";
 import {
-  resolveActionBattleHitboxSpeed,
+  ActionBattleHitTracker,
+  runActionBattleActiveHitbox,
   scheduleActionBattleStartup,
 } from "./core/attack-runtime";
-import type { ActionBattleDamageResult } from "./core/contracts";
+import { applyActionBattleAttackDirection } from "./attack-input";
+import {
+  executeActionBattleUse,
+  getActionBattleActionRange,
+} from "./core/action-use";
+import { resolveActionBattleWeapon } from "./core/equipment";
+import { withActionBattleAnimationUnlocked } from "./locomotion";
+import { safeActionBattleDash } from "./movement";
+import {
+  defineAiBehavior,
+  defineAiTree,
+  type ActionBattleAiIntent,
+  type ActionBattleAiMemory,
+  type ActionBattleAiSimpleBehavior,
+  type ActionBattleAiTreeInput,
+  type ActionBattleAiTreeNode,
+} from "./core/ai-behavior-tree";
+import type {
+  ActionBattleAiBehavior,
+  ActionBattleAiDecision,
+  ActionBattleAiPreset,
+  ActionBattleDamageResult,
+  ActionBattleEntity,
+  ActionBattleHitbox,
+  ActionBattleTargetSelector,
+} from "./core/contracts";
+import {
+  canActionBattleTarget,
+  isActionBattlePlayer,
+} from "./core/targets";
 import type {
   NormalizedActionBattleAttackProfile,
   NormalizedActionBattleHitReactionProfile,
@@ -30,6 +60,31 @@ type RpgEventWithBattleAi = RpgEvent & {
   battleAi?: BattleAi;
 };
 
+type ResolvedMoveTarget =
+  | {
+      kind: "entity";
+      target: ActionBattleEntity;
+      id?: string;
+      x?: number;
+      y?: number;
+      signature: string;
+    }
+  | {
+      kind: "position";
+      target: { x: number; y: number };
+      x: number;
+      y: number;
+      signature: string;
+    };
+
+const resolveMoveCoordinate = (value: unknown): number | undefined => {
+  const raw = typeof value === "function" ? (value as () => unknown)() : value;
+  return typeof raw === "number" && Number.isFinite(raw) ? raw : undefined;
+};
+
+const createMoveSignature = (x: number, y: number): string =>
+  `position:${Math.round(x)}:${Math.round(y)}`;
+
 export interface BattleAiRewardItem {
   item?: any;
   itemId?: string;
@@ -51,7 +106,7 @@ export interface BattleAiDefeatReward {
 
 export interface BattleAiDefeatedContext {
   event: RpgEvent;
-  attacker?: RpgPlayer;
+  attacker?: ActionBattleEntity;
   reward: BattleAiDefeatReward;
   remove: () => void;
 }
@@ -62,10 +117,13 @@ export type BattleAiDefeatedCallback = (
 
 export type BattleAiLegacyDefeatedCallback = (
   event: RpgEvent,
-  attacker?: RpgPlayer
+  attacker?: ActionBattleEntity
 ) => void;
 
 export interface BattleAiBaseOptions {
+  preset?: string | ActionBattleAiPreset;
+  faction?: string;
+  targets?: ActionBattleTargetSelector;
   enemyType?: EnemyType;
   attackCooldown?: number;
   visionRange?: number;
@@ -91,6 +149,9 @@ export interface BattleAiBaseOptions {
     retreatThreshold?: number;
   };
   behaviorKey?: string;
+  tree?: ActionBattleAiTreeInput;
+  behaviorTree?: ActionBattleAiTreeInput;
+  simpleBehavior?: ActionBattleAiSimpleBehavior;
   animations?: ActionBattleAnimationOptions;
   rewards?: BattleAiRewards;
   autoAwardRewards?: boolean;
@@ -298,16 +359,10 @@ export const AiDebug = {
    * @param data - Optional additional data
    */
   log(category: string, eventId: string | undefined, message: string, data?: any): void {
-    if (!this.enabled) return;
-    if (this.filterEventId && eventId !== this.filterEventId) return;
-    if (this.categories.length > 0 && !this.categories.includes(category)) return;
-    
-    const prefix = `[AI:${category}]${eventId ? ` [${eventId.substring(0, 8)}]` : ''}`;
-    if (data !== undefined) {
-      console.log(prefix, message, data);
-    } else {
-      console.log(prefix, message);
-    }
+    void category;
+    void eventId;
+    void message;
+    void data;
   }
 };
 
@@ -363,6 +418,49 @@ export const DEFAULT_KNOCKBACK = {
   duration: 300
 };
 
+const mergeBattleAiPresetOptions = (
+  options: BattleAiOptions | BattleAiLegacyOptions,
+  seen: Set<string> = new Set()
+): BattleAiOptions | BattleAiLegacyOptions => {
+  if (!options.preset) return options;
+
+  if (typeof options.preset === "string") {
+    if (seen.has(options.preset)) {
+      throw new Error(`Circular action battle AI preset: ${options.preset}`);
+    }
+    seen.add(options.preset);
+  }
+
+  const preset =
+    typeof options.preset === "string"
+      ? getActionBattleSystems().ai.presets[options.preset]
+      : options.preset;
+
+  if (!preset) {
+    throw new Error(`Action battle AI preset not found: ${options.preset}`);
+  }
+
+  const resolvedPreset = mergeBattleAiPresetOptions(preset, seen);
+  const { preset: _preset, ...overrides } = options;
+
+  return {
+    ...resolvedPreset,
+    ...overrides,
+    behavior: {
+      ...resolvedPreset.behavior,
+      ...overrides.behavior,
+    },
+    animations: {
+      ...resolvedPreset.animations,
+      ...overrides.animations,
+    },
+    rewards: {
+      ...resolvedPreset.rewards,
+      ...overrides.rewards,
+    },
+  } as BattleAiOptions | BattleAiLegacyOptions;
+};
+
 /**
  * Advanced Battle AI Controller for events
  *
@@ -407,7 +505,7 @@ export const DEFAULT_KNOCKBACK = {
  */
 export class BattleAi {
   private event: RpgEvent;
-  private target: InstanceType<typeof RpgPlayer> | null = null;
+  private target: ActionBattleEntity | null = null;
   private lastAttackTime: number = 0;
   private updateInterval?: any;
 
@@ -418,6 +516,37 @@ export class BattleAi {
     AiDebug.log(category, this.event.id, message, data);
   }
 
+  private traceLog(category: string, message: string, data?: any): void {
+    void category;
+    void message;
+    void data;
+  }
+
+  private lockActionUntil(until: number, reason: string, data?: any): void {
+    if (until <= this.actionLockedUntil) return;
+    this.actionLockedUntil = until;
+    this.traceLog("state", "action locked", {
+      reason,
+      lockedMs: Math.max(0, until - Date.now()),
+      ...data,
+    });
+  }
+
+  private lockForAttack(
+    profile: NormalizedActionBattleAttackProfile,
+    pattern: AttackPattern
+  ): void {
+    this.isMovingToTarget = false;
+    this.event.stopMoveTo();
+    this.lockActionUntil(Date.now() + profile.totalDurationMs, "attack", {
+      pattern,
+      totalDurationMs: profile.totalDurationMs,
+      startupMs: profile.startupMs,
+      activeMs: profile.activeMs,
+      recoveryMs: profile.recoveryMs,
+    });
+  }
+
   // State machine
   private state: AiState = AiState.Idle;
   private stateStartTime: number = 0;
@@ -425,6 +554,8 @@ export class BattleAi {
 
   // Enemy type and behavior
   private enemyType: EnemyType;
+  private faction?: string;
+  private targets: ActionBattleTargetSelector = "players";
   private attackCooldown: number = 1000;
   private visionRange: number = 150;
   private attackRange: number = 60;
@@ -489,11 +620,23 @@ export class BattleAi {
   private lastMoveToTime: number = 0;
   private retreatCooldown: number = 600;
   private lastRetreatTime: number = 0;
+  private actionLockedUntil: number = 0;
+  private lastActionLockTraceTime: number = 0;
+  private lastMoveToCooldownTraceTime: number = 0;
+  private lastMoveToCooldownTraceSignature: string | null = null;
+  private lastTargetMovementSkipTraceTime: number = 0;
   private timers: ReturnType<typeof setTimeout>[] = [];
   private behaviorKey?: string;
+  private behaviorTree?: ActionBattleAiTreeNode;
+  private aiMemory: ActionBattleAiMemory = {};
   private poise: number = 0;
   private hitstunMs: number = 150;
   private invincibilityMs: number = 250;
+  private visionShape?: any;
+  private visionSetupRetries: number = 0;
+  private maxVisionSetupRetries: number = 20;
+  private destroyed: boolean = false;
+  private lastNoTargetTraceTime: number = 0;
 
   /**
    * Create a new Battle AI Controller
@@ -525,11 +668,14 @@ export class BattleAi {
     event: RpgEventWithBattleAi,
     options: BattleAiOptions | BattleAiLegacyOptions = {}
   ) {
+    options = mergeBattleAiPresetOptions(options);
     event.battleAi = this;
     this.event = event;
 
     // Set enemy type and apply behavior modifiers
     this.enemyType = options.enemyType || EnemyType.Aggressive;
+    this.faction = options.faction;
+    this.targets = options.targets ?? "players";
     this.behaviorKey = options.behaviorKey ?? this.enemyType;
     this.applyEnemyTypeBehavior(options);
 
@@ -597,9 +743,21 @@ export class BattleAi {
     if (options.invincibilityMs !== undefined) {
       this.invincibilityMs = Math.max(0, options.invincibilityMs);
     }
+    if (options.tree || options.behaviorTree) {
+      this.behaviorTree = defineAiTree(options.tree ?? options.behaviorTree!);
+    } else if (options.simpleBehavior) {
+      this.behaviorTree = defineAiBehavior(options.simpleBehavior);
+    }
+
+    if (options.attackRange === undefined) {
+      const actionRange = this.getCurrentActionRange();
+      if (actionRange !== undefined) {
+        this.attackRange = actionRange;
+      }
+    }
 
     // Setup AI systems
-    this.setupVision();
+    this.scheduleVisionSetup();
     this.startAiBehaviorLoop();
     if (this.patrolWaypoints.length > 0) {
       this.startPatrol();
@@ -681,14 +839,56 @@ export class BattleAi {
   /**
    * Setup vision detection
    */
-  private setupVision() {
+  private setupVision(): boolean {
+    if (this.visionShape) return true;
+    const map = this.event.getCurrentMap?.();
+    if (
+      map?.physic?.getEntityByUUID &&
+      !map.physic.getEntityByUUID(this.event.id)
+    ) {
+      this.traceLog("vision", "physics body not ready", {
+        retries: this.visionSetupRetries,
+        hasMap: !!map,
+      });
+      return false;
+    }
+
     const diameter = this.visionRange * 2;
-    this.event.attachShape(`vision_${this.event.id}`, {
+    const shape = this.event.attachShape(`vision_${this.event.id}`, {
       radius: this.visionRange,
       width: diameter,
       height: diameter,
       angle: 360,
     });
+    if (!shape) {
+      this.traceLog("vision", "attachShape returned no shape", {
+        retries: this.visionSetupRetries,
+        visionRange: this.visionRange,
+      });
+      return false;
+    }
+    this.visionShape = shape;
+    this.traceLog("vision", "vision attached", {
+      shapeId: (shape as any)?.id,
+      visionRange: this.visionRange,
+    });
+    return true;
+  }
+
+  private scheduleVisionSetup() {
+    if (this.destroyed || this.setupVision()) return;
+    if (this.visionSetupRetries >= this.maxVisionSetupRetries) {
+      this.traceLog("vision", "vision setup gave up", {
+        retries: this.visionSetupRetries,
+      });
+      return;
+    }
+
+    this.visionSetupRetries++;
+    this.schedule(() => {
+      if (this.destroyed || !this.event.getCurrentMap()) return;
+      this.scheduleVisionSetup();
+    }, 50);
   }
 
   /**
@@ -723,10 +923,19 @@ export class BattleAi {
 
     if (!validTransitions[this.state].includes(newState)) {
       this.debugLog('state', `INVALID transition ${this.state} -> ${newState}`);
+      this.traceLog("state", "invalid transition", {
+        from: this.state,
+        to: newState,
+      });
       return;
     }
 
     this.debugLog('state', `STATE change: ${this.state} -> ${newState}`);
+    this.traceLog("state", "state change", {
+      from: this.state,
+      to: newState,
+      targetId: this.target?.id,
+    });
     this.state = newState;
     this.stateStartTime = Date.now();
 
@@ -759,6 +968,14 @@ export class BattleAi {
   private updateAiBehavior() {
     const currentTime = Date.now();
 
+    if (this.target && this.isTargetDefeated(this.target)) {
+      this.debugLog('combat', `Target ${this.target.id} is defeated, returning to idle`);
+      this.clearTarget();
+      this.changeState(AiState.Idle);
+      this.checkDamageTaken();
+      return;
+    }
+
     // Update group behavior
     if (this.groupBehavior) {
       this.updateGroupBehavior();
@@ -772,6 +989,20 @@ export class BattleAi {
       return;
     }
 
+    if (currentTime < this.actionLockedUntil) {
+      if (this.target) this.faceTarget();
+      if (currentTime - this.lastActionLockTraceTime > 250) {
+        this.lastActionLockTraceTime = currentTime;
+        this.traceLog("state", "waiting action recovery", {
+          remainingMs: this.actionLockedUntil - currentTime,
+          state: this.state,
+          targetId: this.target?.id,
+        });
+      }
+      this.checkDamageTaken();
+      return;
+    }
+
     // Berserker: faster attacks when HP is low
     if (this.enemyType === EnemyType.Berserker && this.event.param[MAXHP]) {
       const hpPercent = this.event.hp / this.event.param[MAXHP];
@@ -784,7 +1015,18 @@ export class BattleAi {
       this.updateBehavior(currentTime);
     }
 
-    this.applyCustomBehavior(currentTime);
+    if (!this.target && this.state === AiState.Idle) {
+      const target = this.findNearestTarget();
+      if (target) {
+        this.engageTarget(target);
+      }
+    }
+
+    const customBehaviorHandled = this.applyCustomBehavior(currentTime);
+    if (customBehaviorHandled) {
+      this.checkDamageTaken();
+      return;
+    }
 
     // State-specific behavior
     switch (this.state) {
@@ -810,6 +1052,12 @@ export class BattleAi {
    * Update idle behavior (patrolling)
    */
   private updateIdleBehavior() {
+    const target = this.findNearestTarget();
+    if (target) {
+      this.engageTarget(target);
+      return;
+    }
+
     if (this.patrolWaypoints.length > 0) {
       const waypoint = this.patrolWaypoints[this.currentPatrolIndex];
       const distance = this.getDistance(this.event, {
@@ -832,8 +1080,28 @@ export class BattleAi {
       this.faceTarget();
       
       const distance = this.getDistance(this.event, this.target);
+      this.traceLog("movement", "alert update", {
+        targetId: this.target.id,
+        distance,
+        attackRange: this.attackRange,
+        visionRange: this.visionRange,
+        isMovingToTarget: this.isMovingToTarget,
+      });
       if (distance <= this.attackRange * 1.5) {
+        if (this.isMovingToTarget) {
+          this.isMovingToTarget = false;
+          this.event.stopMoveTo();
+        }
         this.changeState(AiState.Combat);
+      } else if (distance <= this.visionRange * 1.5) {
+        if (!this.isMovingToTarget) {
+          this.debugLog('movement', `Alert approach (dist=${distance.toFixed(1)}, attackRange=${this.attackRange})`);
+          this.requestTargetMovement();
+        }
+      } else {
+        this.debugLog('combat', `Alert target out of range (dist=${distance.toFixed(1)})`);
+        this.clearTarget();
+        this.changeState(AiState.Idle);
       }
     } else {
       this.changeState(AiState.Idle);
@@ -851,13 +1119,20 @@ export class BattleAi {
     }
 
     const distance = this.getDistance(this.event, this.target);
+    this.traceLog("combat", "combat update", {
+      targetId: this.target.id,
+      distance,
+      attackRange: this.attackRange,
+      visionRange: this.visionRange,
+      isMovingToTarget: this.isMovingToTarget,
+      behaviorEnabled: this.behaviorEnabled,
+      behaviorMode: this.behaviorMode,
+    });
 
     // Check if target is still in range
     if (distance > this.visionRange * 1.5) {
       this.debugLog('combat', `Target out of range (dist=${distance.toFixed(1)}, maxRange=${(this.visionRange * 1.5).toFixed(1)})`);
-      this.target = null;
-      this.isMovingToTarget = false;
-      this.event.stopMoveTo();
+      this.clearTarget();
       this.changeState(AiState.Idle);
       return;
     }
@@ -907,8 +1182,7 @@ export class BattleAi {
       } else if (distance > this.attackRange) {
         if (!this.isMovingToTarget) {
           this.debugLog('movement', `Moving to target (dist=${distance.toFixed(1)}, attackRange=${this.attackRange})`);
-          this.isMovingToTarget = true;
-          this.requestMoveTo(this.target);
+          this.requestTargetMovement();
         }
       } else {
         if (this.isMovingToTarget) {
@@ -921,8 +1195,7 @@ export class BattleAi {
       if (distance > this.attackRange) {
         if (!this.isMovingToTarget) {
           this.debugLog('movement', `Moving to target (dist=${distance.toFixed(1)}, attackRange=${this.attackRange})`);
-          this.isMovingToTarget = true;
-          this.requestMoveTo(this.target);
+          this.requestTargetMovement();
         }
       } else {
         if (this.isMovingToTarget) {
@@ -1068,11 +1341,10 @@ export class BattleAi {
     if (!this.target) return;
     const profile = this.getAttackProfile(AttackPattern.Melee);
 
-    this.faceTarget();
+    this.faceTarget({ force: true });
+    this.lockForAttack(profile, AttackPattern.Melee);
     this.telegraphAttack(profile);
-    playActionBattleAnimation("attack", this.event, this.animations, {
-      target: this.target,
-    });
+    this.playAttackVisual(profile, AttackPattern.Melee);
 
     this.scheduleAttackStartup(profile, () => {
       this.executeMeleeAttack(profile, AttackPattern.Melee);
@@ -1083,24 +1355,43 @@ export class BattleAi {
     profile: NormalizedActionBattleAttackProfile,
     pattern: AttackPattern
   ) {
-    if (!this.target) return;
+    if (!this.target || this.isTargetDefeated(this.target)) return;
     this.debugLog('attack', `Applying ${pattern} hit`);
 
-    // Use skill if available
     if (this.attackSkill) {
+      const resolvedSkill = this.resolveUsable(this.attackSkill);
       try {
-        playActionBattleAnimation("castSkill", this.event, this.animations, {
-          skill: this.attackSkill,
+        executeActionBattleUse({
+          attacker: this.event,
           target: this.target,
+          usable: resolvedSkill,
+          skill: resolvedSkill,
+          pattern,
+          profile,
         });
-        this.event.useSkill(this.attackSkill, this.target);
       } catch (e) {
         // Skill failed (no SP, etc.) - fall back to basic attack
         this.performBasicHitbox(profile, pattern);
       }
-    } else {
-      this.performBasicHitbox(profile, pattern);
+      return;
+    }
+
+    const weapon = resolveActionBattleWeapon(this.event);
+    if (
+      weapon &&
+      executeActionBattleUse({
+        attacker: this.event,
+        target: this.target,
+        usable: weapon,
+        weapon,
+        pattern,
+        profile,
+      })
+    ) {
+      return;
     }
+
+    this.performBasicHitbox(profile, pattern);
   }
 
   /**
@@ -1112,7 +1403,21 @@ export class BattleAi {
     ),
     pattern: AttackPattern = AttackPattern.Melee
   ) {
-    if (!this.target) return;
+    if (!this.target || this.isTargetDefeated(this.target)) return;
+
+    const hitTracker = new ActionBattleHitTracker(profile.hitPolicy);
+    runActionBattleActiveHitbox(
+      { ...profile, startupMs: 0 },
+      () => this.resolveBasicHitboxes(),
+      (hitboxes) => {
+        this.processHitboxHits(hitboxes, hitTracker, profile, pattern);
+      },
+      (scheduled, delay) => this.schedule(scheduled, delay)
+    );
+  }
+
+  private resolveBasicHitboxes(): ActionBattleHitbox[] {
+    if (!this.target || this.isTargetDefeated(this.target)) return [];
 
     const eventX = this.event.x();
     const eventY = this.event.y();
@@ -1120,30 +1425,51 @@ export class BattleAi {
     const dy = this.target.y() - eventY;
     const dist = Math.sqrt(dx * dx + dy * dy);
 
-    if (dist === 0) return;
+    if (dist === 0) return [];
 
     const dirX = dx / dist;
     const dirY = dy / dist;
 
-    const hitboxes = [{
+    return [{
       x: eventX + dirX * 30,
       y: eventY + dirY * 30,
       width: 40,
       height: 40,
     }];
+  }
 
+  private queryHitboxCandidates(hitboxes: ActionBattleHitbox[]) {
     const map = this.event.getCurrentMap();
-    map?.createMovingHitbox(hitboxes, {
-      speed: resolveActionBattleHitboxSpeed(profile, hitboxes.length),
-    }).subscribe({
-      next: (hits: any[]) => {
-        hits.forEach((hit: any) => {
-          if (hit instanceof RpgPlayer && hit !== this.event) {
-            this.applyHit(hit, undefined, profile, pattern);
-          }
-        });
-      },
-    });
+    if (!map || typeof (map as any).queryHitbox !== "function") return [];
+
+    const candidates = new Map<string, ActionBattleEntity>();
+    for (const hitbox of hitboxes) {
+      for (const hit of (map as any).queryHitbox(hitbox, {
+        excludeIds: [this.event.id],
+        kinds: ["players", "events"],
+      })) {
+        if (hit?.id) candidates.set(hit.id, hit);
+      }
+    }
+    return Array.from(candidates.values());
+  }
+
+  private processHitboxHits(
+    hitboxes: ActionBattleHitbox[],
+    hitTracker: ActionBattleHitTracker,
+    profile: NormalizedActionBattleAttackProfile,
+    pattern: AttackPattern
+  ) {
+    for (const hit of this.queryHitboxCandidates(hitboxes)) {
+      if (
+        hit !== this.event &&
+        this.canTarget(hit) &&
+        !this.isTargetDefeated(hit) &&
+        hitTracker.tryHit(hit)
+      ) {
+        this.applyHit(hit, undefined, profile, pattern);
+      }
+    }
   }
 
   /**
@@ -1175,13 +1501,24 @@ export class BattleAi {
    * ```
    */
   private applyHit(
-    target: RpgPlayer,
+    target: ActionBattleEntity,
     hooks?: ApplyHitHooks,
     profile: NormalizedActionBattleAttackProfile = this.getAttackProfile(
       AttackPattern.Melee
     ),
     pattern: AttackPattern = AttackPattern.Melee
   ): HitResult {
+    if (this.isTargetDefeated(target)) {
+      return {
+        damage: 0,
+        knockbackForce: 0,
+        knockbackDuration: 0,
+        defeated: true,
+        attacker: this.event,
+        target
+      };
+    }
+
     if (isActionBattleEntityInvincible(target)) {
       return {
         damage: 0,
@@ -1219,13 +1556,16 @@ export class BattleAi {
     }
 
     // Visual feedback
-    target.flash({
-      type: 'tint',
-      tint: 'red',
-      duration: 200,
-      cycles: 1
+    withActionBattleAnimationUnlocked(target, () => {
+      emitActionBattleClientVisual({
+        moment: "hurt",
+        entity: this.event,
+        target,
+        attacker: this.event,
+        damage: hitResult.damage,
+        result: hitResult,
+      });
     });
-    target.showHit(`-${hitResult.damage}`);
     setActionBattleInvincibility(
       target,
       profile.reaction.invincibilityMs
@@ -1251,6 +1591,16 @@ export class BattleAi {
       hooks.onAfterHit(hitResult);
     }
 
+    const targetAi = (target as any).battleAi as BattleAi | undefined;
+    if (targetAi) {
+      targetAi.handleDamage(this.event, {
+        damage: hitResult.damage,
+        defeated: hitResult.defeated,
+        raw: undefined,
+        reaction: profile.reaction,
+      });
+    }
+
     return hitResult;
   }
 
@@ -1294,11 +1644,10 @@ export class BattleAi {
 
     this.comboCount++;
     const profile = this.getAttackProfile(AttackPattern.Combo);
-    this.faceTarget();
+    this.faceTarget({ force: true });
+    this.lockForAttack(profile, AttackPattern.Combo);
     this.telegraphAttack(profile);
-    playActionBattleAnimation("attack", this.event, this.animations, {
-      target: this.target,
-    });
+    this.playAttackVisual(profile, AttackPattern.Combo);
     this.scheduleAttackStartup(profile, () => {
       this.executeMeleeAttack(profile, AttackPattern.Combo);
     });
@@ -1324,17 +1673,10 @@ export class BattleAi {
     const profile = this.getAttackProfile(AttackPattern.Charged);
 
     this.chargingAttack = true;
-    this.faceTarget();
+    this.faceTarget({ force: true });
+    this.lockForAttack(profile, AttackPattern.Charged);
     this.telegraphAttack(profile);
-    playActionBattleAnimation(
-      "attack",
-      this.event,
-      this.animations,
-      {
-        target: this.target,
-      },
-      { repeat: 2 }
-    );
+    this.playAttackVisual(profile, AttackPattern.Charged, { repeat: 2 });
 
     this.scheduleAttackStartup(profile, () => {
       if (!this.target || this.state !== AiState.Combat) {
@@ -1353,10 +1695,9 @@ export class BattleAi {
    */
   private performZoneAttack() {
     const profile = this.getAttackProfile(AttackPattern.Zone);
+    this.lockForAttack(profile, AttackPattern.Zone);
     this.telegraphAttack(profile);
-    playActionBattleAnimation("attack", this.event, this.animations, {
-      target: this.target ?? undefined,
-    });
+    this.playAttackVisual(profile, AttackPattern.Zone);
 
     const eventX = this.event.x();
     const eventY = this.event.y();
@@ -1376,18 +1717,20 @@ export class BattleAi {
     });
 
     this.scheduleAttackStartup(profile, () => {
-      const map = this.event.getCurrentMap();
-      map?.createMovingHitbox(hitboxes, {
-        speed: resolveActionBattleHitboxSpeed(profile, hitboxes.length),
-      }).subscribe({
-        next: (hits: any[]) => {
-          hits.forEach((hit: any) => {
-            if (hit instanceof RpgPlayer && hit !== this.event) {
-              this.applyHit(hit, undefined, profile, AttackPattern.Zone);
-            }
-          });
+      const hitTracker = new ActionBattleHitTracker(profile.hitPolicy);
+      runActionBattleActiveHitbox(
+        { ...profile, startupMs: 0 },
+        () => hitboxes,
+        (activeHitboxes) => {
+          this.processHitboxHits(
+            activeHitboxes,
+            hitTracker,
+            profile,
+            AttackPattern.Zone
+          );
         },
-      });
+        (scheduled, delay) => this.schedule(scheduled, delay)
+      );
     });
   }
 
@@ -1395,7 +1738,7 @@ export class BattleAi {
    * Perform dash attack
    */
   private performDashAttack() {
-    if (!this.target) return;
+    if (!this.target || this.isTargetDefeated(this.target)) return;
     const profile = this.getAttackProfile(AttackPattern.DashAttack);
 
     const dx = this.target.x() - this.event.x();
@@ -1407,12 +1750,14 @@ export class BattleAi {
     const dirX = dx / dist;
     const dirY = dy / dist;
 
-    this.faceTarget();
+    this.faceTarget({ force: true });
+    this.lockForAttack(profile, AttackPattern.DashAttack);
     this.telegraphAttack(profile);
+    this.playAttackVisual(profile, AttackPattern.DashAttack);
 
     this.scheduleAttackStartup(profile, () => {
       if (!this.target || this.state !== AiState.Combat) return;
-      this.event.dash({ x: dirX, y: dirY }, 10, 200);
+      safeActionBattleDash(this.event, { x: dirX, y: dirY }, 10, 200);
       this.schedule(() => {
         if (!this.target || this.state !== AiState.Combat) return;
         this.executeMeleeAttack(profile, AttackPattern.DashAttack);
@@ -1428,6 +1773,28 @@ export class BattleAi {
     ] ?? this.attackProfiles.melee;
   }
 
+  private playAttackVisual(
+    profile: NormalizedActionBattleAttackProfile,
+    pattern: AttackPattern,
+    animationDefaults?: { animationName?: string; repeat?: number }
+  ): void {
+    const moment =
+      profile.animationKey === "castSkill" || profile.animationKey === "castSpell"
+        ? "castSkill"
+        : "attack";
+
+    withActionBattleAnimationUnlocked(this.event, () => {
+      emitActionBattleClientVisual({
+        moment,
+        entity: this.event,
+        target: this.target ?? undefined,
+        pattern,
+        animations: this.animations,
+        animationDefaults,
+      });
+    });
+  }
+
   private telegraphAttack(profile: NormalizedActionBattleAttackProfile) {
     if (profile.startupMs <= 0) return;
     this.event.flash({
@@ -1455,7 +1822,7 @@ export class BattleAi {
    * 2. When near diagonal, require significant difference to change
    * 3. Only change if direction is clearly wrong (opposite)
    */
-  private faceTarget() {
+  private faceTarget(options: { force?: boolean } = {}) {
     if (!this.target) return;
 
     const dx = this.target.x() - this.event.x();
@@ -1464,11 +1831,12 @@ export class BattleAi {
     const absY = Math.abs(dy);
     const distance = Math.sqrt(dx * dx + dy * dy);
 
-    // When very close to target (in collision range), don't change direction
-    // This prevents flickering when in melee combat
-    const minDistanceForDirectionChange = 40;
+    // Avoid undefined facing only when both entities are effectively stacked.
+    // A larger dead-zone makes close melee targets keep stale directions after
+    // knockback, so keep this threshold intentionally tiny.
+    const minDistanceForDirectionChange = 4;
     if (this.lastFacingDirection && distance < minDistanceForDirectionChange) {
-      return; // Keep current direction when in collision
+      return;
     }
 
     // Calculate the "ideal" direction
@@ -1500,7 +1868,11 @@ export class BattleAi {
     }
 
     this.lastFacingDirection = newDirection;
-    this.event.changeDirection(newDirection as any);
+    if (options.force) {
+      applyActionBattleAttackDirection(this.event, newDirection as any);
+    } else {
+      this.event.changeDirection(newDirection as any);
+    }
   }
 
   /**
@@ -1531,7 +1903,9 @@ export class BattleAi {
     const side = Math.random() > 0.5 ? 1 : -1;
 
     this.debugLog('dodge', `Dodging (dir=${side > 0 ? 'right' : 'left'})`);
-    this.event.dash({ x: dodgeDirX * side, y: dodgeDirY * side }, 12, 300);
+    if (!safeActionBattleDash(this.event, { x: dodgeDirX * side, y: dodgeDirY * side }, 12, 300)) {
+      return false;
+    }
     this.lastDodgeTime = currentTime;
 
     // Counter-attack for defensive types
@@ -1570,8 +1944,8 @@ export class BattleAi {
     if (dist === 0) return;
 
     const fleeTarget = {
-      x: () => this.event.x() + (dx / dist) * 200,
-      y: () => this.event.y() + (dy / dist) * 200
+      x: this.event.x() + (dx / dist) * 200,
+      y: this.event.y() + (dy / dist) * 200
     };
 
     this.requestMoveTo(fleeTarget as any);
@@ -1593,7 +1967,9 @@ export class BattleAi {
 
     if (dist === 0) return;
 
-    this.event.dash({ x: dx / dist, y: dy / dist }, 8, 200);
+    if (!safeActionBattleDash(this.event, { x: dx / dist, y: dy / dist }, 8, 200)) {
+      return;
+    }
     this.lastRetreatTime = currentTime;
   }
 
@@ -1616,7 +1992,7 @@ export class BattleAi {
     if (this.patrolWaypoints.length === 0) return;
 
     const waypoint = this.patrolWaypoints[this.currentPatrolIndex];
-    this.requestMoveTo({ x: () => waypoint.x, y: () => waypoint.y } as any);
+    this.requestMoveTo({ x: waypoint.x, y: waypoint.y } as any);
   }
 
   /**
@@ -1688,16 +2064,37 @@ export class BattleAi {
     );
 
     if (distanceToFormation > 20) {
-      this.requestMoveTo({ x: () => formationX, y: () => formationY } as any);
+      this.requestMoveTo({ x: formationX, y: formationY } as any);
     }
   }
 
   /**
    * Handle player entering vision
    */
-  onDetectInShape(player: InstanceType<typeof RpgPlayer>, shape: any) {
-    this.debugLog('vision', `Player ${player.id} entered vision (state=${this.state})`);
-    this.target = player;
+  onDetectInShape(target: ActionBattleEntity, shape: any) {
+    const canTarget = this.canTarget(target);
+    const defeated = this.isTargetDefeated(target);
+    this.traceLog("vision", "detect in shape", {
+      targetId: target?.id,
+      shapeId: shape?.id,
+      canTarget,
+      defeated,
+      state: this.state,
+      targetHp: (target as any)?.hp,
+    });
+    if (!canTarget || defeated) return;
+    this.debugLog('vision', `Target ${target.id} entered vision (state=${this.state})`);
+    this.engageTarget(target);
+  }
+
+  private engageTarget(target: ActionBattleEntity) {
+    this.traceLog("target", "engage target", {
+      targetId: target.id,
+      previousTargetId: this.target?.id,
+      state: this.state,
+      distance: this.getDistance(this.event, target),
+    });
+    this.target = target;
 
     if (this.state === AiState.Idle) {
       this.changeState(AiState.Alert);
@@ -1709,12 +2106,16 @@ export class BattleAi {
   /**
    * Handle player leaving vision
    */
-  onDetectOutShape(player: InstanceType<typeof RpgPlayer>, shape: any) {
-    this.debugLog('vision', `Player ${player.id} left vision (wasTarget=${this.target === player})`);
-    if (this.target === player) {
-      this.target = null;
-      this.isMovingToTarget = false;
-      this.event.stopMoveTo();
+  onDetectOutShape(target: ActionBattleEntity, shape: any) {
+    this.debugLog('vision', `Target ${target.id} left vision (wasTarget=${this.target === target})`);
+    this.traceLog("vision", "detect out shape", {
+      targetId: target?.id,
+      shapeId: shape?.id,
+      wasTarget: this.target === target,
+      state: this.state,
+    });
+    if (this.target === target) {
+      this.clearTarget();
       this.changeState(AiState.Idle);
     }
   }
@@ -1725,7 +2126,7 @@ export class BattleAi {
    * This triggers state changes like stun and flee check.
    * The actual damage is applied externally via RPGJS API.
    */
-  takeDamage(attacker: RpgPlayer): boolean {
+  takeDamage(attacker: ActionBattleEntity): boolean {
     if (this.defeated) return true;
     // Apply damage using RPGJS system
     const raw = this.event.applyDamage(attacker);
@@ -1737,34 +2138,75 @@ export class BattleAi {
   }
 
   handleDamage(
-    attacker: RpgPlayer,
+    attacker: ActionBattleEntity,
     damageResult: ActionBattleDamageResult & {
       reaction?: NormalizedActionBattleHitReactionProfile;
     }
   ): boolean {
     if (this.defeated) return true;
-    const damage = damageResult.damage;
+    const damage = Number.isFinite(damageResult.damage) ? damageResult.damage : 0;
     this.debugLog('damage', `Took ${damage} damage from ${attacker.id} (HP: ${this.event.hp}/${this.event.param[MAXHP] || '?'})`);
+    const canRetaliate = attacker ? this.canTarget(attacker) : false;
+    const attackerDefeated = this.isTargetDefeated(attacker);
+    this.traceLog("damage", "handle damage", {
+      attackerId: attacker?.id,
+      damage,
+      defeated: damageResult.defeated,
+      eventHp: this.event.hp,
+      maxHp: this.event.param[MAXHP],
+      state: this.state,
+      canRetaliate,
+      attackerDefeated,
+      currentTargetId: this.target?.id,
+    });
 
     // Visual feedback
-    this.event.flash({
-      type: 'tint',
-      tint: 'red',
-      duration: 200,
-      cycles: 1
-    });
-    this.event.showHit(`-${damage}`);
-    playActionBattleAnimation("hurt", this.event, this.animations, {
-      attacker,
+    withActionBattleAnimationUnlocked(this.event, () => {
+      emitActionBattleClientVisual({
+        moment: "hurt",
+        entity: this.event,
+        target: this.event,
+        attacker,
+        damage,
+        defeated: damageResult.defeated,
+        result: damageResult,
+        animations: this.animations,
+      });
     });
 
     // Track damage
     this.recentDamageTaken += damage;
 
+    if (
+      attacker &&
+      this.canTarget(attacker) &&
+      !this.isTargetDefeated(attacker) &&
+      this.state !== AiState.Flee
+    ) {
+      this.traceLog("target", "retaliate against attacker", {
+        attackerId: attacker.id,
+        previousTargetId: this.target?.id,
+        state: this.state,
+      });
+      this.target = attacker;
+      if (this.state === AiState.Idle || this.state === AiState.Alert) {
+        this.isMovingToTarget = false;
+        this.changeState(AiState.Combat);
+      }
+    }
+
     const reaction = damageResult.reaction;
     const staggerPower = reaction?.staggerPower ?? damage;
     const hitstunMs = reaction?.hitstunMs ?? this.hitstunMs;
-    const shouldStun = staggerPower >= this.poise && hitstunMs > 0;
+    const shouldStun =
+      (damage > 0 || (reaction?.staggerPower ?? 0) > 0) &&
+      staggerPower >= this.poise &&
+      hitstunMs > 0;
+    this.lockActionUntil(Date.now() + Math.max(220, hitstunMs + 120), "damage recovery", {
+      attackerId: attacker?.id,
+      damage,
+      hitstunMs,
+    });
     setActionBattleInvincibility(
       this.event,
       reaction?.invincibilityMs ?? this.invincibilityMs
@@ -1794,7 +2236,7 @@ export class BattleAi {
    * Stops all movements, cleans up resources, calls the onDefeated hook,
    * and removes the event from the map.
    */
-  private kill(attacker?: RpgPlayer) {
+  private kill(attacker?: ActionBattleEntity) {
     if (this.defeated) return;
     this.defeated = true;
 
@@ -1828,7 +2270,7 @@ export class BattleAi {
       });
     };
 
-    if (this.autoAwardRewards) {
+    if (this.autoAwardRewards && attacker && isActionBattlePlayer(attacker)) {
       reward.giveTo(attacker);
     }
 
@@ -1846,7 +2288,7 @@ export class BattleAi {
         (
           this.onDefeatedCallback as (
             event: RpgEvent,
-            attacker?: RpgPlayer
+          attacker?: ActionBattleEntity
           ) => void
         )(this.event, attacker);
       } else {
@@ -1869,6 +2311,96 @@ export class BattleAi {
     return Math.sqrt(dx * dx + dy * dy);
   }
 
+  private resolveUsable(usable: any) {
+    if (!usable) return usable;
+    const id = typeof usable === "string" ? usable : usable.id;
+    const learned = id ? (this.event as any).getSkill?.(id) : undefined;
+    if (learned) return learned;
+    try {
+      return id ? (this.event as any).databaseById?.(id) ?? usable : usable;
+    } catch {
+      return usable;
+    }
+  }
+
+  private getCurrentActionRange(): number | undefined {
+    const skillRange = this.attackSkill
+      ? getActionBattleActionRange(this.resolveUsable(this.attackSkill))
+      : undefined;
+    if (skillRange !== undefined) return skillRange;
+    return getActionBattleActionRange(resolveActionBattleWeapon(this.event));
+  }
+
+  private canTarget(target: ActionBattleEntity): boolean {
+    return canActionBattleTarget(
+      this.event,
+      target,
+      this.targets,
+      getActionBattleOptions().combat?.targets
+    );
+  }
+
+  private findNearestTarget(): ActionBattleEntity | null {
+    const map = this.event.getCurrentMap();
+    if (!map) {
+      this.traceLog("target", "find nearest skipped: no map");
+      return null;
+    }
+
+    const candidates: ActionBattleEntity[] = [];
+    map.getPlayers?.().forEach((player: RpgPlayer) => candidates.push(player));
+    map.getEvents?.().forEach((event: RpgEvent) => candidates.push(event));
+
+    let nearest: ActionBattleEntity | null = null;
+    let nearestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+      if (!this.canTarget(candidate)) continue;
+      const distance = this.getDistance(this.event, candidate);
+      if (distance > this.visionRange) continue;
+      if (distance < nearestDistance) {
+        nearest = candidate;
+        nearestDistance = distance;
+      }
+    }
+
+    const now = Date.now();
+    if (nearest) {
+      this.traceLog("target", "nearest target found", {
+        targetId: nearest.id,
+        distance: nearestDistance,
+        visionRange: this.visionRange,
+        candidates: candidates.length,
+      });
+    } else if (now - this.lastNoTargetTraceTime > 1000) {
+      this.lastNoTargetTraceTime = now;
+      this.traceLog("target", "no target found", {
+        visionRange: this.visionRange,
+        candidates: candidates.map((candidate) => {
+          const distance = this.getDistance(this.event, candidate);
+          return {
+            id: candidate.id,
+            hp: (candidate as any).hp,
+            canTarget: this.canTarget(candidate),
+            defeated: this.isTargetDefeated(candidate),
+            distance,
+          };
+        }),
+      });
+    }
+
+    return nearest;
+  }
+
+  private isTargetDefeated(target: ActionBattleEntity | null | undefined): boolean {
+    return !target || target.hp <= 0;
+  }
+
+  private clearTarget() {
+    this.target = null;
+    this.isMovingToTarget = false;
+    this.event.stopMoveTo();
+  }
+
   private updateBehavior(currentTime: number) {
     if (currentTime - this.behaviorLastUpdate < this.behaviorUpdateInterval) {
       return;
@@ -1927,10 +2459,25 @@ export class BattleAi {
     }
   }
 
-  private applyCustomBehavior(currentTime: number) {
-    if (!this.behaviorKey) return;
+  private applyCustomBehavior(currentTime: number): boolean {
+    let handled = false;
+
+    if (this.behaviorTree) {
+      const result = this.behaviorTree.tick(this.createAiTreeContext(currentTime));
+      if (result.decision) {
+        handled = this.applyAiDecision(result.decision, currentTime) || handled;
+      }
+      if (result.intent) {
+        handled = this.executeAiIntents(result.intent, currentTime) || handled;
+      }
+      if (result.status === "running") {
+        handled = true;
+      }
+    }
+
+    if (!this.behaviorKey) return handled;
     const behavior = getActionBattleSystems().ai.behaviors[this.behaviorKey];
-    if (!behavior) return;
+    if (!behavior) return handled;
     const maxHp = this.event.param[MAXHP];
     const decision = behavior({
       event: this.event,
@@ -1941,7 +2488,16 @@ export class BattleAi {
       hpPercent: maxHp ? this.event.hp / maxHp : null,
       now: currentTime,
     });
-    if (!decision) return;
+    if (!decision) return handled;
+    return this.applyAiDecision(decision, currentTime) || handled;
+  }
+
+  private applyAiDecision(
+    decision: ActionBattleAiDecision | ReturnType<ActionBattleAiBehavior>,
+    currentTime: number
+  ): boolean {
+    if (!decision) return false;
+    let handled = false;
     if (decision.attackCooldown !== undefined) {
       this.attackCooldown = decision.attackCooldown;
     }
@@ -1955,6 +2511,162 @@ export class BattleAi {
       this.behaviorMode = decision.mode;
       this.behaviorEnabled = true;
     }
+    if (decision.intent) {
+      handled = this.executeAiIntents(decision.intent, currentTime);
+    }
+    return handled;
+  }
+
+  private createAiTreeContext(currentTime: number) {
+    const maxHp = this.event.param[MAXHP];
+    const distance = this.target ? this.getDistance(this.event, this.target) : null;
+    return {
+      event: this.event,
+      target: this.target,
+      state: this.state,
+      enemyType: this.enemyType,
+      distance,
+      hpPercent: maxHp ? this.event.hp / maxHp : null,
+      now: currentTime,
+      self: {
+        event: this.event,
+        state: this.state,
+        enemyType: this.enemyType,
+        hpPercent: maxHp ? this.event.hp / maxHp : null,
+        attackRange: this.attackRange,
+      },
+      targetInfo:
+        this.target && distance !== null
+          ? {
+              entity: this.target,
+              distance,
+              inAttackRange: distance <= this.attackRange,
+              visible: true,
+            }
+          : null,
+      memory: this.aiMemory,
+    };
+  }
+
+  private executeAiIntents(
+    input: ActionBattleAiIntent | ActionBattleAiIntent[],
+    currentTime: number
+  ): boolean {
+    const intents = Array.isArray(input) ? input : [input];
+    let handled = false;
+    for (const intent of intents) {
+      handled = this.executeAiIntent(intent, currentTime) || handled;
+    }
+    return handled;
+  }
+
+  private executeAiIntent(
+    intent: ActionBattleAiIntent,
+    currentTime: number
+  ): boolean {
+    const consumes = intent.consume !== false;
+
+    switch (intent.type) {
+      case "setMode":
+        this.behaviorMode = intent.mode;
+        this.behaviorEnabled = true;
+        return consumes;
+      case "idle":
+        this.isMovingToTarget = false;
+        this.event.stopMoveTo();
+        return consumes;
+      case "patrol":
+        this.startPatrol();
+        return consumes;
+      case "faceTarget":
+        this.faceTarget();
+        return consumes;
+      case "moveToTarget":
+        if (!this.target) return false;
+        this.requestTargetMovement();
+        return consumes;
+      case "fleeFromTarget":
+        if (!this.target) return false;
+        this.isMovingToTarget = false;
+        if (this.state === AiState.Combat) {
+          this.changeState(AiState.Flee);
+        } else {
+          this.fleeFromTarget();
+        }
+        return consumes;
+      case "keepDistance":
+        return this.executeKeepDistance(intent, consumes);
+      case "useAttack":
+        return this.executeRequestedAttack(intent.pattern, currentTime, consumes);
+      case "useSkill":
+        return this.executeRequestedSkill(intent.skill, currentTime, consumes);
+    }
+  }
+
+  private executeKeepDistance(
+    intent: Extract<ActionBattleAiIntent, { type: "keepDistance" }>,
+    consumes: boolean
+  ): boolean {
+    if (!this.target) return false;
+    const tolerance = intent.tolerance ?? Math.max(8, intent.distance * 0.15);
+    const distance = this.getDistance(this.event, this.target);
+    if (distance < intent.distance - tolerance) {
+      this.isMovingToTarget = false;
+      this.retreatFromTarget();
+      return consumes;
+    }
+    if (distance > intent.distance + tolerance) {
+      this.requestTargetMovement();
+      return consumes;
+    }
+    if (this.isMovingToTarget) {
+      this.isMovingToTarget = false;
+      this.event.stopMoveTo();
+    }
+    return consumes;
+  }
+
+  private executeRequestedAttack(
+    pattern: AttackPattern | string | undefined,
+    currentTime: number,
+    consumes: boolean
+  ): boolean {
+    if (!this.target || this.isTargetDefeated(this.target) || this.chargingAttack) return false;
+    const distance = this.getDistance(this.event, this.target);
+    if (distance > this.attackRange) return false;
+    if (currentTime - this.lastAttackTime < this.attackCooldown) return false;
+
+    if (pattern) {
+      this.performAttackPattern(pattern as AttackPattern);
+    } else {
+      this.selectAndPerformAttack();
+    }
+    this.lastAttackTime = currentTime;
+    return consumes;
+  }
+
+  private executeRequestedSkill(
+    skill: any,
+    currentTime: number,
+    consumes: boolean
+  ): boolean {
+    if (!this.target || this.isTargetDefeated(this.target) || !skill) return false;
+    const distance = this.getDistance(this.event, this.target);
+    const resolvedSkill = this.resolveUsable(skill);
+    const range = getActionBattleActionRange(resolvedSkill) ?? this.attackRange;
+    const cooldownRemaining = this.attackCooldown - (currentTime - this.lastAttackTime);
+    if (distance > range) return false;
+    if (cooldownRemaining > 0) return false;
+
+    executeActionBattleUse({
+      attacker: this.event,
+      target: this.target,
+      usable: resolvedSkill,
+      skill: resolvedSkill,
+      profile: this.getAttackProfile(AttackPattern.Melee),
+    });
+    this.lastAttackTime = currentTime;
+    return consumes;
   }
 
   private handleTacticalMovement(distance: number) {
@@ -1972,8 +2684,7 @@ export class BattleAi {
     if (distance > maxRange) {
       if (!this.isMovingToTarget) {
         this.debugLog('movement', `Tactical approach (dist=${distance.toFixed(1)}, maxRange=${maxRange.toFixed(1)})`);
-        this.isMovingToTarget = true;
-        this.requestMoveTo(this.target);
+        this.requestTargetMovement();
       }
       return;
     }
@@ -1990,8 +2701,7 @@ export class BattleAi {
     if (distance > this.attackRange) {
       if (!this.isMovingToTarget) {
         this.debugLog('movement', `Assault approach (dist=${distance.toFixed(1)}, attackRange=${this.attackRange})`);
-        this.isMovingToTarget = true;
-        this.requestMoveTo(this.target);
+        this.requestTargetMovement();
       }
       return;
     }
@@ -2003,19 +2713,118 @@ export class BattleAi {
     }
   }
 
+  private resolveMoveTarget(target: any): ResolvedMoveTarget | null {
+    if (!target) return null;
+
+    const targetId =
+      target.id !== undefined && target.id !== null ? String(target.id) : undefined;
+    const x = resolveMoveCoordinate(target.x);
+    const y = resolveMoveCoordinate(target.y);
+
+    if (targetId) {
+      return {
+        kind: "entity",
+        target,
+        id: targetId,
+        x,
+        y,
+        signature: `entity:${targetId}`,
+      };
+    }
+
+    if (x === undefined || y === undefined) {
+      return null;
+    }
+
+    return {
+      kind: "position",
+      target: { x, y },
+      x,
+      y,
+      signature: createMoveSignature(x, y),
+    };
+  }
+
   private requestMoveTo(target: any): boolean {
     const currentTime = Date.now();
+    const resolvedTarget = this.resolveMoveTarget(target);
+    if (!resolvedTarget) {
+      this.traceLog("movement", "moveTo skipped: invalid target", {
+        target,
+      });
+      return false;
+    }
+
     if (currentTime - this.lastMoveToTime < this.moveToCooldown) {
+      if (
+        this.lastMoveToCooldownTraceSignature !== resolvedTarget.signature ||
+        currentTime - this.lastMoveToCooldownTraceTime > 1000
+      ) {
+        this.lastMoveToCooldownTraceTime = currentTime;
+        this.lastMoveToCooldownTraceSignature = resolvedTarget.signature;
+        this.traceLog("movement", "moveTo skipped: cooldown", {
+          targetKind: resolvedTarget.kind,
+          targetId:
+            resolvedTarget.kind === "entity" ? resolvedTarget.id : undefined,
+          targetPosition: {
+            x: resolvedTarget.x,
+            y: resolvedTarget.y,
+          },
+          elapsed: currentTime - this.lastMoveToTime,
+          moveToCooldown: this.moveToCooldown,
+        });
+      }
       return false;
     }
-    this.event.moveTo(target as any);
+    const map = this.event.getCurrentMap?.() as any;
+    const hasBody =
+      !!map?.physic?.getEntityByUUID?.(this.event.id) ||
+      !!map?.getBody?.(this.event.id);
+    this.traceLog("movement", "moveTo requested", {
+      targetKind: resolvedTarget.kind,
+      targetId:
+        resolvedTarget.kind === "entity" ? resolvedTarget.id : undefined,
+      eventPosition: {
+        x: this.event.x?.(),
+        y: this.event.y?.(),
+      },
+      targetPosition: {
+        x: resolvedTarget.x,
+        y: resolvedTarget.y,
+      },
+      hasMap: !!map,
+      hasMovementBody: hasBody,
+    });
+    this.event.moveTo(resolvedTarget.target as any);
     this.lastMoveToTime = currentTime;
     return true;
   }
 
+  private requestTargetMovement(target: ActionBattleEntity | null = this.target): boolean {
+    if (!target) {
+      this.traceLog("movement", "target movement skipped: no target");
+      return false;
+    }
+    const started = this.requestMoveTo(target);
+    if (started) {
+      this.isMovingToTarget = true;
+    } else {
+      const now = Date.now();
+      if (now - this.lastTargetMovementSkipTraceTime > 1000) {
+        this.lastTargetMovementSkipTraceTime = now;
+        this.traceLog("movement", "target movement did not start", {
+          targetId: target.id,
+          isMovingToTarget: this.isMovingToTarget,
+        });
+      }
+    }
+    return started;
+  }
+
   private schedule(callback: () => void, delay: number) {
     const timer = setTimeout(() => {
       this.timers = this.timers.filter((entry) => entry !== timer);
+      if (this.destroyed) return;
       callback();
     }, delay);
     this.timers.push(timer);
@@ -2025,14 +2834,31 @@ export class BattleAi {
   // Public getters
   getHealth(): number { return this.event.hp; }
   getMaxHealth(): number { return this.event.param[MAXHP]; }
-  getTarget(): InstanceType<typeof RpgPlayer> | null { return this.target; }
+  getTarget(): ActionBattleEntity | null { return this.target; }
   getState(): AiState { return this.state; }
+  getFaction(): string | undefined {
+    return this.faction;
+  }
+  setFaction(faction: string | undefined): void {
+    this.faction = faction;
+  }
+  getTargets(): ActionBattleTargetSelector {
+    return this.targets;
+  }
+  setTargets(targets: ActionBattleTargetSelector): void {
+    this.targets = targets;
+    if (this.target && !this.canTarget(this.target)) {
+      this.clearTarget();
+      this.changeState(AiState.Idle);
+    }
+  }
   getEnemyType(): EnemyType { return this.enemyType; }
 
   /**
    * Clean up
    */
   destroy() {
+    this.destroyed = true;
     if (this.updateInterval) {
       clearInterval(this.updateInterval);
       this.updateInterval = undefined;