@rpgjs/action-battle 5.0.0-beta.5 → 5.0.0-beta.7

package/src/ai.server.ts

@@ -2,17 +2,70 @@ 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;
 };
 
-export interface BattleAiOptions {
+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;
@@ -22,10 +75,14 @@ export interface BattleAiOptions {
   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;
@@ -35,8 +92,18 @@ export interface BattleAiOptions {
   };
   behaviorKey?: string;
   animations?: ActionBattleAnimationOptions;
+  rewards?: BattleAiRewards;
+  autoAwardRewards?: boolean;
+}
+
+export interface BattleAiOptions extends BattleAiBaseOptions {
   /** Callback called when the AI is defeated */
-  onDefeated?: (event: RpgEvent, attacker?: RpgPlayer) => void;
+  onDefeated?: BattleAiDefeatedCallback;
+}
+
+export interface BattleAiLegacyOptions extends BattleAiBaseOptions {
+  /** @deprecated Use the context callback signature instead. */
+  onDefeated?: BattleAiLegacyDefeatedCallback;
 }
 
 /**
@@ -73,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
  * 
@@ -295,6 +440,7 @@ export class BattleAi {
   // 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;
@@ -318,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;
@@ -340,6 +491,9 @@ export class BattleAi {
   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
@@ -365,9 +519,11 @@ export class BattleAi {
    * });
    * ```
    */
+  constructor(event: RpgEventWithBattleAi, options?: BattleAiOptions);
+  constructor(event: RpgEventWithBattleAi, options?: BattleAiLegacyOptions);
   constructor(
     event: RpgEventWithBattleAi,
-    options: BattleAiOptions = {}
+    options: BattleAiOptions | BattleAiLegacyOptions = {}
   ) {
     event.battleAi = this;
     this.event = event;
@@ -390,6 +546,9 @@ export class BattleAi {
       AttackPattern.Combo,
       AttackPattern.DashAttack
     ];
+    this.attackProfiles = normalizeActionBattleEnemyAttackProfiles(
+      options.attackProfiles
+    );
 
     // Initialize group behavior
     this.groupBehavior = options.groupBehavior || false;
@@ -400,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) {
@@ -427,6 +588,15 @@ 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();
@@ -896,12 +1066,26 @@ export class BattleAi {
    */
   private performMeleeAttack() {
     if (!this.target) return;
+    const profile = this.getAttackProfile(AttackPattern.Melee);
 
     this.faceTarget();
+    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 {
@@ -912,17 +1096,22 @@ export class BattleAi {
         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();
@@ -944,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);
           }
         });
       },
@@ -983,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);
 
@@ -1017,6 +1226,10 @@ export class BattleAi {
       cycles: 1
     });
     target.showHit(`-${hitResult.damage}`);
+    setActionBattleInvincibility(
+      target,
+      profile.reaction.invincibilityMs
+    );
 
     // Apply knockback
     if (hitResult.knockbackForce > 0) {
@@ -1080,7 +1293,15 @@ 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) {
       this.schedule(() => {
@@ -1100,9 +1321,11 @@ export class BattleAi {
    */
   private performChargedAttack() {
     if (!this.target) return;
+    const profile = this.getAttackProfile(AttackPattern.Charged);
 
     this.chargingAttack = true;
     this.faceTarget();
+    this.telegraphAttack(profile);
     playActionBattleAnimation(
       "attack",
       this.event,
@@ -1113,35 +1336,24 @@ export class BattleAi {
       { repeat: 2 }
     );
 
-    this.schedule(() => {
+    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 {
-          playActionBattleAnimation("castSkill", this.event, this.animations, {
-            skill: this.attackSkill,
-            target: this.target,
-          });
-          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() {
+    const profile = this.getAttackProfile(AttackPattern.Zone);
+    this.telegraphAttack(profile);
     playActionBattleAnimation("attack", this.event, this.animations, {
       target: this.target ?? undefined,
     });
@@ -1163,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);
+            }
+          });
+        },
+      });
     });
   }
 
@@ -1180,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();
@@ -1191,12 +1408,43 @@ export class BattleAi {
     const dirY = dy / dist;
 
     this.faceTarget();
-    this.event.dash({ x: dirX, y: dirY }, 10, 200);
+    this.telegraphAttack(profile);
 
-    this.schedule(() => {
+    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)
+    );
   }
 
   /**
@@ -1478,6 +1726,7 @@ 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 raw = this.event.applyDamage(attacker);
     return this.handleDamage(attacker, {
@@ -1487,7 +1736,13 @@ export class BattleAi {
     });
   }
 
-  handleDamage(attacker: RpgPlayer, damageResult: ActionBattleDamageResult): boolean {
+  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] || '?'})`);
 
@@ -1506,11 +1761,20 @@ export class BattleAi {
     // 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);
     }
 
@@ -1531,7 +1795,10 @@ export class BattleAi {
    * and removes the event from the map.
    */
   private kill(attacker?: RpgPlayer) {
-    const dieAnimation = playActionBattleAnimation(
+    if (this.defeated) return;
+    this.defeated = true;
+
+    const dieAnimation = resolveActionBattleAnimation(
       "die",
       this.event,
       this.animations,
@@ -1540,18 +1807,57 @@ export class BattleAi {
       }
     );
     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,
+      });
+    };
 
-    // Call onDefeated hook before cleanup
+    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();
-    if (removeDelay > 0) {
-      this.schedule(() => this.event.remove(), removeDelay);
-    } else {
-      this.event.remove();
-    }
+    remove();
   }
 
   /**