@rpgjs/action-battle 5.0.0-beta.10 → 5.0.0-beta.12

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,
@@ -51,7 +81,7 @@ export interface BattleAiDefeatReward {
 
 export interface BattleAiDefeatedContext {
   event: RpgEvent;
-  attacker?: RpgPlayer;
+  attacker?: ActionBattleEntity;
   reward: BattleAiDefeatReward;
   remove: () => void;
 }
@@ -62,10 +92,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 +124,9 @@ export interface BattleAiBaseOptions {
     retreatThreshold?: number;
   };
   behaviorKey?: string;
+  tree?: ActionBattleAiTreeInput;
+  behaviorTree?: ActionBattleAiTreeInput;
+  simpleBehavior?: ActionBattleAiSimpleBehavior;
   animations?: ActionBattleAnimationOptions;
   rewards?: BattleAiRewards;
   autoAwardRewards?: boolean;
@@ -363,6 +399,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 +486,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;
 
@@ -425,6 +504,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;
@@ -491,9 +572,15 @@ export class BattleAi {
   private lastRetreatTime: 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;
 
   /**
    * Create a new Battle AI Controller
@@ -525,11 +612,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 +687,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 +783,37 @@ 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)
+    ) {
+      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) return false;
+    this.visionShape = shape;
+    return true;
+  }
+
+  private scheduleVisionSetup() {
+    if (this.destroyed || this.setupVision()) return;
+    if (this.visionSetupRetries >= this.maxVisionSetupRetries) return;
+
+    this.visionSetupRetries++;
+    this.schedule(() => {
+      if (this.destroyed || !this.event.getCurrentMap()) return;
+      this.scheduleVisionSetup();
+    }, 50);
   }
 
   /**
@@ -759,6 +884,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();
@@ -784,7 +917,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 +954,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, {
@@ -855,9 +1005,7 @@ export class BattleAi {
     // 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;
     }
@@ -1068,10 +1216,15 @@ export class BattleAi {
     if (!this.target) return;
     const profile = this.getAttackProfile(AttackPattern.Melee);
 
-    this.faceTarget();
+    this.faceTarget({ force: true });
     this.telegraphAttack(profile);
-    playActionBattleAnimation("attack", this.event, this.animations, {
-      target: this.target,
+    withActionBattleAnimationUnlocked(this.event, () => {
+      emitActionBattleClientVisual({
+        moment: "attack",
+        entity: this.event,
+        target: this.target,
+        animations: this.animations,
+      });
     });
 
     this.scheduleAttackStartup(profile, () => {
@@ -1083,24 +1236,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 +1284,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 +1306,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 +1382,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 +1437,16 @@ export class BattleAi {
     }
 
     // Visual feedback
-    target.flash({
-      type: 'tint',
-      tint: 'red',
-      duration: 200,
-      cycles: 1
+    withActionBattleAnimationUnlocked(target, () => {
+      emitActionBattleClientVisual({
+        moment: "hit",
+        entity: this.event,
+        target,
+        damage: hitResult.damage,
+        result: hitResult,
+        animations: this.animations,
+      });
     });
-    target.showHit(`-${hitResult.damage}`);
     setActionBattleInvincibility(
       target,
       profile.reaction.invincibilityMs
@@ -1251,6 +1472,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,10 +1525,15 @@ export class BattleAi {
 
     this.comboCount++;
     const profile = this.getAttackProfile(AttackPattern.Combo);
-    this.faceTarget();
+    this.faceTarget({ force: true });
     this.telegraphAttack(profile);
-    playActionBattleAnimation("attack", this.event, this.animations, {
-      target: this.target,
+    withActionBattleAnimationUnlocked(this.event, () => {
+      emitActionBattleClientVisual({
+        moment: "attack",
+        entity: this.event,
+        target: this.target,
+        animations: this.animations,
+      });
     });
     this.scheduleAttackStartup(profile, () => {
       this.executeMeleeAttack(profile, AttackPattern.Combo);
@@ -1324,17 +1560,17 @@ export class BattleAi {
     const profile = this.getAttackProfile(AttackPattern.Charged);
 
     this.chargingAttack = true;
-    this.faceTarget();
+    this.faceTarget({ force: true });
     this.telegraphAttack(profile);
-    playActionBattleAnimation(
-      "attack",
-      this.event,
-      this.animations,
-      {
+    withActionBattleAnimationUnlocked(this.event, () => {
+      emitActionBattleClientVisual({
+        moment: "attack",
+        entity: this.event,
         target: this.target,
-      },
-      { repeat: 2 }
-    );
+        animations: this.animations,
+        animationDefaults: { repeat: 2 },
+      });
+    });
 
     this.scheduleAttackStartup(profile, () => {
       if (!this.target || this.state !== AiState.Combat) {
@@ -1354,8 +1590,13 @@ export class BattleAi {
   private performZoneAttack() {
     const profile = this.getAttackProfile(AttackPattern.Zone);
     this.telegraphAttack(profile);
-    playActionBattleAnimation("attack", this.event, this.animations, {
-      target: this.target ?? undefined,
+    withActionBattleAnimationUnlocked(this.event, () => {
+      emitActionBattleClientVisual({
+        moment: "attack",
+        entity: this.event,
+        target: this.target ?? undefined,
+        animations: this.animations,
+      });
     });
 
     const eventX = this.event.x();
@@ -1376,18 +1617,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 +1638,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 +1650,12 @@ export class BattleAi {
     const dirX = dx / dist;
     const dirY = dy / dist;
 
-    this.faceTarget();
+    this.faceTarget({ force: true });
     this.telegraphAttack(profile);
 
     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);
@@ -1455,7 +1698,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 +1707,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 +1744,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 +1779,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
@@ -1593,7 +1843,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;
   }
 
@@ -1695,9 +1947,14 @@ export class BattleAi {
   /**
    * 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) {
+    if (!this.canTarget(target) || this.isTargetDefeated(target)) return;
+    this.debugLog('vision', `Target ${target.id} entered vision (state=${this.state})`);
+    this.engageTarget(target);
+  }
+
+  private engageTarget(target: ActionBattleEntity) {
+    this.target = target;
 
     if (this.state === AiState.Idle) {
       this.changeState(AiState.Alert);
@@ -1709,12 +1966,10 @@ 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})`);
+    if (this.target === target) {
+      this.clearTarget();
       this.changeState(AiState.Idle);
     }
   }
@@ -1725,7 +1980,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,7 +1992,7 @@ export class BattleAi {
   }
 
   handleDamage(
-    attacker: RpgPlayer,
+    attacker: ActionBattleEntity,
     damageResult: ActionBattleDamageResult & {
       reaction?: NormalizedActionBattleHitReactionProfile;
     }
@@ -1747,15 +2002,17 @@ export class BattleAi {
     this.debugLog('damage', `Took ${damage} damage from ${attacker.id} (HP: ${this.event.hp}/${this.event.param[MAXHP] || '?'})`);
 
     // 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
@@ -1794,7 +2051,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 +2085,7 @@ export class BattleAi {
       });
     };
 
-    if (this.autoAwardRewards) {
+    if (this.autoAwardRewards && attacker && isActionBattlePlayer(attacker)) {
       reward.giveTo(attacker);
     }
 
@@ -1846,7 +2103,7 @@ export class BattleAi {
         (
           this.onDefeatedCallback as (
             event: RpgEvent,
-            attacker?: RpgPlayer
+          attacker?: ActionBattleEntity
           ) => void
         )(this.event, attacker);
       } else {
@@ -1869,6 +2126,68 @@ 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) 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;
+      }
+    }
+
+    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 +2246,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 +2275,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 +2298,164 @@ 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.isMovingToTarget = true;
+        this.requestMoveTo(this.target);
+        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.isMovingToTarget = true;
+      this.requestMoveTo(this.target);
+      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) {
@@ -2016,6 +2517,7 @@ export class BattleAi {
   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 +2527,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;