@rpgjs/action-battle 5.0.0-alpha.44 → 5.0.0-beta.10

package/src/ai.server.ts

@@ -1,9 +1,111 @@
 import { MAXHP, RpgEvent, RpgPlayer } from "@rpgjs/server";
+import {
+  getActionBattleAnimationRemovalDelay,
+  playActionBattleAnimation,
+  resolveActionBattleAnimation,
+} from "./animations";
+import { getActionBattleOptions } from "./config";
+import { getActionBattleSystems } from "./core/context";
+import {
+  isActionBattleEntityInvincible,
+  setActionBattleInvincibility,
+} from "./core/hit-reaction";
+import {
+  normalizeActionBattleEnemyAttackProfiles,
+  type ActionBattleEnemyAttackProfileMap,
+  type NormalizedActionBattleEnemyAttackProfileMap,
+} from "./core/enemy-attack-profiles";
+import {
+  resolveActionBattleHitboxSpeed,
+  scheduleActionBattleStartup,
+} from "./core/attack-runtime";
+import type { ActionBattleDamageResult } from "./core/contracts";
+import type {
+  NormalizedActionBattleAttackProfile,
+  NormalizedActionBattleHitReactionProfile,
+} from "./types";
+import type { ActionBattleAnimationOptions } from "./types";
 
 type RpgEventWithBattleAi = RpgEvent & {
-  battleAi: BattleAi;
+  battleAi?: BattleAi;
 };
 
+export interface BattleAiRewardItem {
+  item?: any;
+  itemId?: string;
+  amount?: number;
+  chance?: number;
+}
+
+export interface BattleAiRewards {
+  exp?: number;
+  gold?: number;
+  items?: Array<BattleAiRewardItem | string>;
+  showNotification?: boolean;
+}
+
+export interface BattleAiDefeatReward {
+  readonly awarded: boolean;
+  giveTo(player?: RpgPlayer | null): void;
+}
+
+export interface BattleAiDefeatedContext {
+  event: RpgEvent;
+  attacker?: RpgPlayer;
+  reward: BattleAiDefeatReward;
+  remove: () => void;
+}
+
+export type BattleAiDefeatedCallback = (
+  context: BattleAiDefeatedContext
+) => void;
+
+export type BattleAiLegacyDefeatedCallback = (
+  event: RpgEvent,
+  attacker?: RpgPlayer
+) => void;
+
+export interface BattleAiBaseOptions {
+  enemyType?: EnemyType;
+  attackCooldown?: number;
+  visionRange?: number;
+  attackRange?: number;
+  dodgeChance?: number;
+  dodgeCooldown?: number;
+  fleeThreshold?: number;
+  attackSkill?: any;
+  attackPatterns?: AttackPattern[];
+  attackProfiles?: ActionBattleEnemyAttackProfileMap;
+  patrolWaypoints?: Array<{ x: number; y: number }>;
+  groupBehavior?: boolean;
+  moveToCooldown?: number;
+  retreatCooldown?: number;
+  poise?: number;
+  hitstunMs?: number;
+  invincibilityMs?: number;
+  behavior?: {
+    baseScore?: number;
+    updateInterval?: number;
+    minStateDuration?: number;
+    assaultThreshold?: number;
+    retreatThreshold?: number;
+  };
+  behaviorKey?: string;
+  animations?: ActionBattleAnimationOptions;
+  rewards?: BattleAiRewards;
+  autoAwardRewards?: boolean;
+}
+
+export interface BattleAiOptions extends BattleAiBaseOptions {
+  /** Callback called when the AI is defeated */
+  onDefeated?: BattleAiDefeatedCallback;
+}
+
+export interface BattleAiLegacyOptions extends BattleAiBaseOptions {
+  /** @deprecated Use the context callback signature instead. */
+  onDefeated?: BattleAiLegacyDefeatedCallback;
+}
+
 /**
  * Hit result data returned after applying damage
  * 
@@ -38,6 +140,84 @@ export interface HitResult {
   target: RpgPlayer | RpgEvent;
 }
 
+const normalizeRewardItem = (
+  item: BattleAiRewardItem | string
+): BattleAiRewardItem => {
+  if (typeof item === "string") {
+    return { itemId: item, amount: 1, chance: 100 };
+  }
+  return {
+    ...item,
+    amount: item.amount ?? 1,
+    chance: item.chance ?? 100,
+  };
+};
+
+const getRewardItemRef = (item: BattleAiRewardItem) => item.item ?? item.itemId;
+
+const getPlayerMap = (player: RpgPlayer) => {
+  return typeof (player as any).getCurrentMap === "function"
+    ? (player as any).getCurrentMap()
+    : undefined;
+};
+
+const getRewardItemName = (inventoryItem: any, itemRef: any): string => {
+  if (inventoryItem && typeof inventoryItem.name === "function") {
+    return inventoryItem.name();
+  }
+  if (inventoryItem?.name) return inventoryItem.name;
+  if (typeof itemRef === "string") return itemRef;
+  if (itemRef?.name) return itemRef.name;
+  if (itemRef?.id) return itemRef.id;
+  return "item";
+};
+
+const createDefeatReward = (
+  rewards: BattleAiRewards | undefined
+): BattleAiDefeatReward => {
+  let awarded = false;
+  return {
+    get awarded() {
+      return awarded;
+    },
+    giveTo(player?: RpgPlayer | null) {
+      if (!player || awarded || !rewards) return;
+      awarded = true;
+
+      const exp = rewards.exp ?? 0;
+      const gold = rewards.gold ?? 0;
+      if (exp > 0) player.exp += exp;
+      if (gold > 0) player.gold += gold;
+
+      if (rewards.showNotification && (exp > 0 || gold > 0)) {
+        player.showNotification(`You won ${exp} experience and ${gold} gold`);
+      }
+
+      for (const rawItem of rewards.items ?? []) {
+        const item = normalizeRewardItem(rawItem);
+        const itemRef = getRewardItemRef(item);
+        if (!itemRef) continue;
+        if (Math.random() * 100 >= (item.chance ?? 100)) continue;
+
+        const amount = item.amount ?? 1;
+        const inventoryItem = player.addItem(itemRef, amount);
+        if (rewards.showNotification) {
+          const itemData =
+            typeof itemRef === "string"
+              ? getPlayerMap(player)?.database?.()?.[itemRef]
+              : undefined;
+          player.showNotification(
+            `You won ${amount} ${getRewardItemName(inventoryItem, itemRef)}`,
+            {
+              icon: itemData?.icon,
+            }
+          );
+        }
+      }
+    },
+  };
+};
+
 /**
  * Hook options for customizing hit behavior
  * 
@@ -99,7 +279,9 @@ export interface ApplyHitHooks {
  */
 export const AiDebug = {
   /** Enable/disable all AI debug logs */
-  enabled: (typeof process !== 'undefined' && process.env?.RPGJS_DEBUG_AI === '1') || false,
+  enabled:
+    ((globalThis as { process?: { env?: Record<string, string> } }).process
+      ?.env?.RPGJS_DEBUG_AI === "1") || false,
   
   /** Filter logs to a specific event ID (null = all events) */
   filterEventId: null as string | null,
@@ -243,21 +425,23 @@ export class BattleAi {
 
   // Enemy type and behavior
   private enemyType: EnemyType;
-  private attackCooldown: number;
-  private visionRange: number;
-  private attackRange: number;
+  private attackCooldown: number = 1000;
+  private visionRange: number = 150;
+  private attackRange: number = 60;
 
   // Dodge system
-  private dodgeChance: number;
-  private dodgeCooldown: number;
+  private dodgeChance: number = 0.2;
+  private dodgeCooldown: number = 2000;
   private lastDodgeTime: number = 0;
 
   // Flee threshold (HP percentage)
-  private fleeThreshold: number;
+  private fleeThreshold: number = 0.2;
 
   // Attack configuration
   private attackSkill: any | null; // Skill to use for attacks
   private attackPatterns: AttackPattern[];
+  private attackProfiles: NormalizedActionBattleEnemyAttackProfileMap;
+  private animations?: ActionBattleAnimationOptions;
   private comboCount: number = 0;
   private comboMax: number = 3;
   private chargingAttack: boolean = false;
@@ -280,7 +464,12 @@ export class BattleAi {
   private isMovingToTarget: boolean = false;
 
   // Callback when AI is defeated
-  private onDefeatedCallback?: (event: RpgEvent, attacker?: RpgPlayer) => void;
+  private onDefeatedCallback?:
+    | BattleAiDefeatedCallback
+    | BattleAiLegacyDefeatedCallback;
+  private rewards?: BattleAiRewards;
+  private autoAwardRewards: boolean = true;
+  private defeated: boolean = false;
 
   // Direction hysteresis to prevent animation flickering
   private lastFacingDirection: string | null = null;
@@ -300,6 +489,11 @@ export class BattleAi {
   private lastMoveToTime: number = 0;
   private retreatCooldown: number = 600;
   private lastRetreatTime: number = 0;
+  private timers: ReturnType<typeof setTimeout>[] = [];
+  private behaviorKey?: string;
+  private poise: number = 0;
+  private hitstunMs: number = 150;
+  private invincibilityMs: number = 250;
 
   /**
    * Create a new Battle AI Controller
@@ -325,42 +519,26 @@ export class BattleAi {
    * });
    * ```
    */
+  constructor(event: RpgEventWithBattleAi, options?: BattleAiOptions);
+  constructor(event: RpgEventWithBattleAi, options?: BattleAiLegacyOptions);
   constructor(
     event: RpgEventWithBattleAi,
-    options: {
-      enemyType?: EnemyType;
-      attackCooldown?: number;
-      visionRange?: number;
-      attackRange?: number;
-      dodgeChance?: number;
-      dodgeCooldown?: number;
-      fleeThreshold?: number;
-      attackSkill?: any;
-      attackPatterns?: AttackPattern[];
-      patrolWaypoints?: Array<{ x: number; y: number }>;
-      groupBehavior?: boolean;
-      moveToCooldown?: number;
-      retreatCooldown?: number;
-      behavior?: {
-        baseScore?: number;
-        updateInterval?: number;
-        minStateDuration?: number;
-        assaultThreshold?: number;
-        retreatThreshold?: number;
-      };
-      /** Callback called when the AI is defeated */
-      onDefeated?: (event: RpgEvent, attacker?: RpgPlayer) => void;
-    } = {}
+    options: BattleAiOptions | BattleAiLegacyOptions = {}
   ) {
     event.battleAi = this;
     this.event = event;
 
     // Set enemy type and apply behavior modifiers
     this.enemyType = options.enemyType || EnemyType.Aggressive;
+    this.behaviorKey = options.behaviorKey ?? this.enemyType;
     this.applyEnemyTypeBehavior(options);
 
     // Store attack skill reference
     this.attackSkill = options.attackSkill || null;
+    this.animations = {
+      ...getActionBattleOptions().animations,
+      ...options.animations,
+    };
 
     // Initialize attack patterns
     this.attackPatterns = options.attackPatterns || [
@@ -368,6 +546,9 @@ export class BattleAi {
       AttackPattern.Combo,
       AttackPattern.DashAttack
     ];
+    this.attackProfiles = normalizeActionBattleEnemyAttackProfiles(
+      options.attackProfiles
+    );
 
     // Initialize group behavior
     this.groupBehavior = options.groupBehavior || false;
@@ -378,6 +559,8 @@ export class BattleAi {
 
     // Initialize defeat callback
     this.onDefeatedCallback = options.onDefeated;
+    this.rewards = options.rewards;
+    this.autoAwardRewards = options.autoAwardRewards ?? true;
 
     // Behavior gauge settings
     if (options.behavior) {
@@ -405,11 +588,22 @@ export class BattleAi {
     if (options.retreatCooldown !== undefined) {
       this.retreatCooldown = options.retreatCooldown;
     }
+    if (options.poise !== undefined) {
+      this.poise = Math.max(0, options.poise);
+    }
+    if (options.hitstunMs !== undefined) {
+      this.hitstunMs = Math.max(0, options.hitstunMs);
+    }
+    if (options.invincibilityMs !== undefined) {
+      this.invincibilityMs = Math.max(0, options.invincibilityMs);
+    }
 
     // Setup AI systems
     this.setupVision();
     this.startAiBehaviorLoop();
-    this.changeState(AiState.Idle);
+    if (this.patrolWaypoints.length > 0) {
+      this.startPatrol();
+    }
 
     this.debugLog('init', `AI created (type=${this.enemyType}, visionRange=${this.visionRange}, attackRange=${this.attackRange})`);
   }
@@ -516,6 +710,9 @@ export class BattleAi {
    * Change AI state with validated transitions
    */
   private changeState(newState: AiState) {
+    if (newState === this.state) {
+      return;
+    }
     const validTransitions: Record<AiState, AiState[]> = {
       [AiState.Idle]: [AiState.Alert, AiState.Combat],
       [AiState.Alert]: [AiState.Idle, AiState.Combat],
@@ -587,6 +784,8 @@ export class BattleAi {
       this.updateBehavior(currentTime);
     }
 
+    this.applyCustomBehavior(currentTime);
+
     // State-specific behavior
     switch (this.state) {
       case AiState.Idle:
@@ -620,6 +819,7 @@ export class BattleAi {
 
       if (distance < 10) {
         this.currentPatrolIndex = (this.currentPatrolIndex + 1) % this.patrolWaypoints.length;
+        this.startPatrol();
       }
     }
   }
@@ -676,9 +876,10 @@ export class BattleAi {
     // Try dodge
     if (this.canDodge() && this.shouldDodge()) {
       this.debugLog('combat', 'Attempting dodge');
-      this.isMovingToTarget = false;
-      this.tryDodge();
-      return;
+      if (this.tryDodge()) {
+        this.isMovingToTarget = false;
+        return;
+      }
     }
 
     if (this.behaviorEnabled) {
@@ -865,27 +1066,52 @@ export class BattleAi {
    */
   private performMeleeAttack() {
     if (!this.target) return;
+    const profile = this.getAttackProfile(AttackPattern.Melee);
 
     this.faceTarget();
-    this.event.setGraphicAnimation('attack', 1);
+    this.telegraphAttack(profile);
+    playActionBattleAnimation("attack", this.event, this.animations, {
+      target: this.target,
+    });
+
+    this.scheduleAttackStartup(profile, () => {
+      this.executeMeleeAttack(profile, AttackPattern.Melee);
+    });
+  }
+
+  private executeMeleeAttack(
+    profile: NormalizedActionBattleAttackProfile,
+    pattern: AttackPattern
+  ) {
+    if (!this.target) return;
+    this.debugLog('attack', `Applying ${pattern} hit`);
 
     // Use skill if available
     if (this.attackSkill) {
       try {
+        playActionBattleAnimation("castSkill", this.event, this.animations, {
+          skill: this.attackSkill,
+          target: this.target,
+        });
         this.event.useSkill(this.attackSkill, this.target);
       } catch (e) {
         // Skill failed (no SP, etc.) - fall back to basic attack
-        this.performBasicHitbox();
+        this.performBasicHitbox(profile, pattern);
       }
     } else {
-      this.performBasicHitbox();
+      this.performBasicHitbox(profile, pattern);
     }
   }
 
   /**
    * Perform basic hitbox attack when no skill is set
    */
-  private performBasicHitbox() {
+  private performBasicHitbox(
+    profile: NormalizedActionBattleAttackProfile = this.getAttackProfile(
+      AttackPattern.Melee
+    ),
+    pattern: AttackPattern = AttackPattern.Melee
+  ) {
     if (!this.target) return;
 
     const eventX = this.event.x();
@@ -907,11 +1133,13 @@ export class BattleAi {
     }];
 
     const map = this.event.getCurrentMap();
-    map?.createMovingHitbox(hitboxes, { speed: 5 }).subscribe({
-      next: (hits) => {
-        hits.forEach((hit) => {
+    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);
+            this.applyHit(hit, undefined, profile, pattern);
           }
         });
       },
@@ -946,7 +1174,25 @@ export class BattleAi {
    * });
    * ```
    */
-  private applyHit(target: RpgPlayer, hooks?: ApplyHitHooks): HitResult {
+  private applyHit(
+    target: RpgPlayer,
+    hooks?: ApplyHitHooks,
+    profile: NormalizedActionBattleAttackProfile = this.getAttackProfile(
+      AttackPattern.Melee
+    ),
+    pattern: AttackPattern = AttackPattern.Melee
+  ): HitResult {
+    if (isActionBattleEntityInvincible(target)) {
+      return {
+        damage: 0,
+        knockbackForce: 0,
+        knockbackDuration: 0,
+        defeated: false,
+        attacker: this.event,
+        target
+      };
+    }
+
     // Use RPGJS damage formula
     const { damage } = target.applyDamage(this.event as any);
 
@@ -980,6 +1226,10 @@ export class BattleAi {
       cycles: 1
     });
     target.showHit(`-${hitResult.damage}`);
+    setActionBattleInvincibility(
+      target,
+      profile.reaction.invincibilityMs
+    );
 
     // Apply knockback
     if (hitResult.knockbackForce > 0) {
@@ -1043,10 +1293,18 @@ export class BattleAi {
     if (!this.target) return;
 
     this.comboCount++;
-    this.performMeleeAttack();
+    const profile = this.getAttackProfile(AttackPattern.Combo);
+    this.faceTarget();
+    this.telegraphAttack(profile);
+    playActionBattleAnimation("attack", this.event, this.animations, {
+      target: this.target,
+    });
+    this.scheduleAttackStartup(profile, () => {
+      this.executeMeleeAttack(profile, AttackPattern.Combo);
+    });
 
     if (this.comboCount < this.comboMax) {
-      setTimeout(() => {
+      this.schedule(() => {
         if (this.target && this.state === AiState.Combat) {
           this.performComboAttack();
         } else {
@@ -1063,37 +1321,42 @@ export class BattleAi {
    */
   private performChargedAttack() {
     if (!this.target) return;
+    const profile = this.getAttackProfile(AttackPattern.Charged);
 
     this.chargingAttack = true;
     this.faceTarget();
-    this.event.setGraphicAnimation('attack', 2);
+    this.telegraphAttack(profile);
+    playActionBattleAnimation(
+      "attack",
+      this.event,
+      this.animations,
+      {
+        target: this.target,
+      },
+      { repeat: 2 }
+    );
 
-    setTimeout(() => {
+    this.scheduleAttackStartup(profile, () => {
       if (!this.target || this.state !== AiState.Combat) {
         this.chargingAttack = false;
         return;
       }
-
-      // Charged attacks can use a stronger skill or wider hitbox
-      if (this.attackSkill) {
-        try {
-          this.event.useSkill(this.attackSkill, this.target);
-        } catch (e) {
-          this.performBasicHitbox();
-        }
-      } else {
-        this.performBasicHitbox();
-      }
-      
+      this.executeMeleeAttack(profile, AttackPattern.Charged);
+    });
+    this.schedule(() => {
       this.chargingAttack = false;
-    }, 800);
+    }, profile.totalDurationMs);
   }
 
   /**
    * Perform zone attack (360 degrees)
    */
   private performZoneAttack() {
-    this.event.setGraphicAnimation('attack', 1);
+    const profile = this.getAttackProfile(AttackPattern.Zone);
+    this.telegraphAttack(profile);
+    playActionBattleAnimation("attack", this.event, this.animations, {
+      target: this.target ?? undefined,
+    });
 
     const eventX = this.event.x();
     const eventY = this.event.y();
@@ -1112,15 +1375,19 @@ export class BattleAi {
       });
     });
 
-    const map = this.event.getCurrentMap();
-    map?.createMovingHitbox(hitboxes, { speed: 5 }).subscribe({
-      next: (hits) => {
-        hits.forEach((hit) => {
-          if (hit instanceof RpgPlayer && hit !== this.event) {
-            this.applyHit(hit);
-          }
-        });
-      },
+    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);
+            }
+          });
+        },
+      });
     });
   }
 
@@ -1129,6 +1396,7 @@ export class BattleAi {
    */
   private performDashAttack() {
     if (!this.target) return;
+    const profile = this.getAttackProfile(AttackPattern.DashAttack);
 
     const dx = this.target.x() - this.event.x();
     const dy = this.target.y() - this.event.y();
@@ -1140,12 +1408,43 @@ export class BattleAi {
     const dirY = dy / dist;
 
     this.faceTarget();
-    this.event.dash({ x: dirX, y: dirY }, 10, 200);
+    this.telegraphAttack(profile);
 
-    setTimeout(() => {
+    this.scheduleAttackStartup(profile, () => {
       if (!this.target || this.state !== AiState.Combat) return;
-      this.performMeleeAttack();
-    }, 200);
+      this.event.dash({ x: dirX, y: dirY }, 10, 200);
+      this.schedule(() => {
+        if (!this.target || this.state !== AiState.Combat) return;
+        this.executeMeleeAttack(profile, AttackPattern.DashAttack);
+      }, 200);
+    });
+  }
+
+  private getAttackProfile(
+    pattern: AttackPattern
+  ): NormalizedActionBattleAttackProfile {
+    return this.attackProfiles[
+      pattern as keyof NormalizedActionBattleEnemyAttackProfileMap
+    ] ?? this.attackProfiles.melee;
+  }
+
+  private telegraphAttack(profile: NormalizedActionBattleAttackProfile) {
+    if (profile.startupMs <= 0) return;
+    this.event.flash({
+      type: 'tint',
+      tint: 'white',
+      duration: Math.min(profile.startupMs, 300),
+      cycles: 1
+    });
+  }
+
+  private scheduleAttackStartup(
+    profile: NormalizedActionBattleAttackProfile,
+    callback: () => void
+  ) {
+    return scheduleActionBattleStartup(profile, callback, (scheduled, delay) =>
+      this.schedule(scheduled, delay)
+    );
   }
 
   /**
@@ -1207,24 +1506,24 @@ export class BattleAi {
   /**
    * Try to dodge
    */
-  private tryDodge() {
+  private tryDodge(): boolean {
     const currentTime = Date.now();
 
     if (currentTime - this.lastDodgeTime < this.dodgeCooldown) {
       this.debugLog('dodge', `Dodge on cooldown (${this.dodgeCooldown - (currentTime - this.lastDodgeTime)}ms remaining)`);
-      return;
+      return false;
     }
     if (Math.random() > this.dodgeChance) {
       this.debugLog('dodge', `Dodge roll failed (chance=${(this.dodgeChance * 100).toFixed(0)}%)`);
-      return;
+      return false;
     }
-    if (!this.target) return;
+    if (!this.target) return false;
 
     const dx = this.target.x() - this.event.x();
     const dy = this.target.y() - this.event.y();
     const dist = Math.sqrt(dx * dx + dy * dy);
 
-    if (dist === 0) return;
+    if (dist === 0) return false;
 
     // Perpendicular direction
     const dodgeDirX = -dy / dist;
@@ -1238,12 +1537,13 @@ export class BattleAi {
     // Counter-attack for defensive types
     if (this.enemyType === EnemyType.Defensive && Math.random() < 0.5) {
       this.debugLog('dodge', 'Counter-attack after dodge');
-      setTimeout(() => {
+      this.schedule(() => {
         if (this.target && this.state === AiState.Combat) {
           this.selectAndPerformAttack();
         }
       }, 400);
     }
+    return true;
   }
 
   private canDodge(): boolean {
@@ -1426,9 +1726,24 @@ export class BattleAi {
    * The actual damage is applied externally via RPGJS API.
    */
   takeDamage(attacker: RpgPlayer): boolean {
+    if (this.defeated) return true;
     // Apply damage using RPGJS system
-    const { damage } = this.event.applyDamage(attacker);
+    const raw = this.event.applyDamage(attacker);
+    return this.handleDamage(attacker, {
+      damage: raw.damage ?? 0,
+      defeated: this.event.hp <= 0,
+      raw,
+    });
+  }
 
+  handleDamage(
+    attacker: RpgPlayer,
+    damageResult: ActionBattleDamageResult & {
+      reaction?: NormalizedActionBattleHitReactionProfile;
+    }
+  ): boolean {
+    if (this.defeated) return true;
+    const damage = damageResult.damage;
     this.debugLog('damage', `Took ${damage} damage from ${attacker.id} (HP: ${this.event.hp}/${this.event.param[MAXHP] || '?'})`);
 
     // Visual feedback
@@ -1439,20 +1754,32 @@ export class BattleAi {
       cycles: 1
     });
     this.event.showHit(`-${damage}`);
+    playActionBattleAnimation("hurt", this.event, this.animations, {
+      attacker,
+    });
 
     // Track damage
     this.recentDamageTaken += damage;
 
+    const reaction = damageResult.reaction;
+    const staggerPower = reaction?.staggerPower ?? damage;
+    const hitstunMs = reaction?.hitstunMs ?? this.hitstunMs;
+    const shouldStun = staggerPower >= this.poise && hitstunMs > 0;
+    setActionBattleInvincibility(
+      this.event,
+      reaction?.invincibilityMs ?? this.invincibilityMs
+    );
+
     // Brief stun
-    if (this.state !== AiState.Stunned && this.state !== AiState.Flee) {
+    if (shouldStun && this.state !== AiState.Stunned && this.state !== AiState.Flee) {
       this.debugLog('damage', 'Stunned from damage');
       this.isMovingToTarget = false;
-      this.stunnedUntil = Date.now() + 150;
+      this.stunnedUntil = Date.now() + hitstunMs;
       this.changeState(AiState.Stunned);
     }
 
     // Check death
-    if (this.event.hp <= 0) {
+    if (damageResult.defeated || this.event.hp <= 0) {
       this.debugLog('damage', 'Defeated!');
       this.kill(attacker);
       return true;
@@ -1468,13 +1795,69 @@ export class BattleAi {
    * and removes the event from the map.
    */
   private kill(attacker?: RpgPlayer) {
-    // Call onDefeated hook before cleanup
+    if (this.defeated) return;
+    this.defeated = true;
+
+    const dieAnimation = resolveActionBattleAnimation(
+      "die",
+      this.event,
+      this.animations,
+      {
+        attacker,
+      }
+    );
+    const removeDelay = getActionBattleAnimationRemovalDelay(dieAnimation);
+    const reward = createDefeatReward(this.rewards);
+    let removed = false;
+    const remove = () => {
+      if (removed) return;
+      removed = true;
+      this.event.remove({
+        reason: "defeated",
+        data: {
+          animation: dieAnimation,
+        },
+        transition: dieAnimation
+          ? {
+              animation: dieAnimation.animationName,
+              graphic: dieAnimation.graphic,
+              duration: removeDelay,
+            }
+          : undefined,
+        timeoutMs: removeDelay,
+      });
+    };
+
+    if (this.autoAwardRewards) {
+      reward.giveTo(attacker);
+    }
+
+    const context: BattleAiDefeatedContext = {
+      event: this.event,
+      attacker,
+      reward,
+      remove,
+    };
+
+    // Call onDefeated hook before cleanup. One-argument callbacks receive the
+    // newer context object; two-argument callbacks keep the legacy signature.
     if (this.onDefeatedCallback) {
-      this.onDefeatedCallback(this.event, attacker);
+      if (this.onDefeatedCallback.length >= 2) {
+        (
+          this.onDefeatedCallback as (
+            event: RpgEvent,
+            attacker?: RpgPlayer
+          ) => void
+        )(this.event, attacker);
+      } else {
+        (this.onDefeatedCallback as (context: BattleAiDefeatedContext) => void)(
+          context
+        );
+      }
     }
-    
+
     this.destroy();
-    this.event.remove();
+    remove();
   }
 
   /**
@@ -1544,6 +1927,36 @@ export class BattleAi {
     }
   }
 
+  private applyCustomBehavior(currentTime: number) {
+    if (!this.behaviorKey) return;
+    const behavior = getActionBattleSystems().ai.behaviors[this.behaviorKey];
+    if (!behavior) return;
+    const maxHp = this.event.param[MAXHP];
+    const decision = behavior({
+      event: this.event,
+      target: this.target,
+      state: this.state,
+      enemyType: this.enemyType,
+      distance: this.target ? this.getDistance(this.event, this.target) : null,
+      hpPercent: maxHp ? this.event.hp / maxHp : null,
+      now: currentTime,
+    });
+    if (!decision) return;
+    if (decision.attackCooldown !== undefined) {
+      this.attackCooldown = decision.attackCooldown;
+    }
+    if (decision.moveToCooldown !== undefined) {
+      this.moveToCooldown = decision.moveToCooldown;
+    }
+    if (decision.attackPatterns?.length) {
+      this.attackPatterns = decision.attackPatterns;
+    }
+    if (decision.mode) {
+      this.behaviorMode = decision.mode;
+      this.behaviorEnabled = true;
+    }
+  }
+
   private handleTacticalMovement(distance: number) {
     if (!this.target) return;
     const minRange = this.attackRange * 0.7;
@@ -1600,6 +2013,15 @@ export class BattleAi {
     return true;
   }
 
+  private schedule(callback: () => void, delay: number) {
+    const timer = setTimeout(() => {
+      this.timers = this.timers.filter((entry) => entry !== timer);
+      callback();
+    }, delay);
+    this.timers.push(timer);
+    return timer;
+  }
+
   // Public getters
   getHealth(): number { return this.event.hp; }
   getMaxHealth(): number { return this.event.param[MAXHP]; }
@@ -1617,5 +2039,7 @@ export class BattleAi {
     }
     this.target = null;
     this.nearbyEnemies = [];
+    this.timers.forEach((timer) => clearTimeout(timer));
+    this.timers = [];
   }
 }