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

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2026 by Samuel Ronce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -496,6 +496,100 @@ The module handles player attacks via the `action` input:
 // Knockback force is based on equipped weapon's knockbackForce property
 ```
 
+## Configurable Combat Animations
+
+By default, player and AI attacks keep using the existing `attack` animation:
+
+```ts
+player.setGraphicAnimation("attack", 1);
+```
+
+Use `animations` when your combat sprites are stored in separate graphics such
+as `hero_attack`, `hero_hurt`, or `hero_die`.
+
+```ts
+import { provideActionBattle } from "@rpgjs/action-battle/server";
+
+export default provideActionBattle({
+  animations: {
+    attack: "attack",
+    hurt: "hurt",
+    die: {
+      animationName: "die",
+      repeat: 1,
+      delayMs: 500
+    },
+    castSkill: "skill"
+  }
+});
+```
+
+For data-driven spritesheets, use resolver functions:
+
+```ts
+provideActionBattle({
+  animations: {
+    attack: (entity) => ({
+      animationName: "walk",
+      graphic: entity.combatAnimations?.attack,
+      repeat: 1
+    }),
+    hurt: (entity) => ({
+      animationName: "walk",
+      graphic: entity.combatAnimations?.hurt,
+      repeat: 1
+    }),
+    die: (entity) => ({
+      animationName: "walk",
+      graphic: entity.combatAnimations?.die,
+      repeat: 1,
+      waitEnd: true
+    }),
+    castSkill: (entity, context) => ({
+      animationName: "walk",
+      graphic: entity.combatAnimations?.castSkill,
+      repeat: 1
+    })
+  }
+});
+```
+
+When `graphic` is provided, action-battle calls:
+
+```ts
+entity.setGraphicAnimation(animationName, graphic, repeat);
+```
+
+Otherwise it calls:
+
+```ts
+entity.setGraphicAnimation(animationName, repeat);
+```
+
+Return `null` or `undefined` from a resolver to skip the animation. `BattleAi`
+can also override the global configuration per enemy:
+
+```ts
+new BattleAi(this, {
+  animations: {
+    attack: {
+      animationName: "walk",
+      graphic: "slime_attack",
+      repeat: 1
+    },
+    die: {
+      animationName: "walk",
+      graphic: "slime_die",
+      repeat: 1,
+      delayMs: 700
+    }
+  }
+});
+```
+
+`waitEnd: true` delays event removal for defeated AI with the default delay used
+by action-battle. Use `delayMs` when you need an exact duration.
+
 ## Knockback System
 
 Knockback force is determined by the equipped weapon's `knockbackForce` property.

package/dist/ai.server.d.ts

@@ -1,7 +1,36 @@
 import { RpgEvent, RpgPlayer } from '@rpgjs/server';
+import { ActionBattleAnimationOptions } from './types';
 type RpgEventWithBattleAi = RpgEvent & {
     battleAi: BattleAi;
 };
+export interface BattleAiOptions {
+    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;
+    };
+    animations?: ActionBattleAnimationOptions;
+    /** Callback called when the AI is defeated */
+    onDefeated?: (event: RpgEvent, attacker?: RpgPlayer) => void;
+}
 /**
  * Hit result data returned after applying damage
  *
@@ -221,6 +250,7 @@ export declare class BattleAi {
     private fleeThreshold;
     private attackSkill;
     private attackPatterns;
+    private animations?;
     private comboCount;
     private comboMax;
     private chargingAttack;
@@ -271,33 +301,7 @@ export declare class BattleAi {
      * });
      * ```
      */
-    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;
-    });
+    constructor(event: RpgEventWithBattleAi, options?: BattleAiOptions);
     /**
      * Apply enemy type-specific behavior modifiers
      *

package/dist/animations.d.ts

@@ -0,0 +1,16 @@
+import { ActionBattleAnimationContext, ActionBattleAnimationEntity, ActionBattleAnimationKey, ActionBattleAnimationOptions } from './types';
+export declare const DEFAULT_DIE_ANIMATION_DELAY_MS = 500;
+export interface ResolvedActionBattleAnimation {
+    animationName: string;
+    graphic?: string | string[];
+    repeat: number;
+    waitEnd: boolean;
+    delayMs?: number;
+}
+export interface ActionBattleAnimationDefaults {
+    animationName?: string;
+    repeat?: number;
+}
+export declare function resolveActionBattleAnimation(key: ActionBattleAnimationKey, entity: ActionBattleAnimationEntity, animations?: ActionBattleAnimationOptions, context?: ActionBattleAnimationContext, defaults?: ActionBattleAnimationDefaults): ResolvedActionBattleAnimation | null;
+export declare function playActionBattleAnimation(key: ActionBattleAnimationKey, entity: ActionBattleAnimationEntity, animations?: ActionBattleAnimationOptions, context?: ActionBattleAnimationContext, defaults?: ActionBattleAnimationDefaults): ResolvedActionBattleAnimation | null;
+export declare function getActionBattleAnimationRemovalDelay(animation: ResolvedActionBattleAnimation | null): number;

package/dist/client/index10.js

@@ -0,0 +1,30 @@
+const normalizeMaskRows = (mask) => {
+  if (!mask) return ["#"];
+  if (Array.isArray(mask)) return mask;
+  return mask.trim().split("\n").map((row) => row.replace(/\r/g, ""));
+};
+const parseAoeMask = (mask) => {
+  const rows = normalizeMaskRows(mask);
+  const height = rows.length;
+  const width = rows.reduce((max, row) => Math.max(max, row.length), 0);
+  const centerX = Math.floor(width / 2);
+  const centerY = Math.floor(height / 2);
+  const cells = [];
+  rows.forEach((row, y) => {
+    for (let x = 0; x < row.length; x++) {
+      const char = row[x];
+      if (char && char !== "." && char !== " ") {
+        cells.push({ dx: x - centerX, dy: y - centerY });
+      }
+    }
+  });
+  if (cells.length === 0) {
+    cells.push({ dx: 0, dy: 0 });
+  }
+  return { width, height, centerX, centerY, cells };
+};
+const manhattanDistance = (a, b) => Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
+export {
+  manhattanDistance,
+  parseAoeMask
+};

package/dist/client/index3.js

@@ -1,3 +1,5 @@
+import { playActionBattleAnimation, getActionBattleAnimationRemovalDelay } from "./index9.js";
+import { getActionBattleOptions } from "./index8.js";
 const MAXHP = null;
 const RpgPlayer = null;
 const AiDebug = {
@@ -118,6 +120,10 @@ class BattleAi {
     this.enemyType = options.enemyType || "aggressive";
     this.applyEnemyTypeBehavior(options);
     this.attackSkill = options.attackSkill || null;
+    this.animations = {
+      ...getActionBattleOptions().animations,
+      ...options.animations
+    };
     this.attackPatterns = options.attackPatterns || [
       "melee",
       "combo",
@@ -643,9 +649,15 @@ class BattleAi {
   performMeleeAttack() {
     if (!this.target) return;
     this.faceTarget();
-    this.event.setGraphicAnimation("attack", 1);
+    playActionBattleAnimation("attack", this.event, this.animations, {
+      target: this.target
+    });
     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();
@@ -810,7 +822,15 @@ class BattleAi {
     if (!this.target) return;
     this.chargingAttack = true;
     this.faceTarget();
-    this.event.setGraphicAnimation("attack", 2);
+    playActionBattleAnimation(
+      "attack",
+      this.event,
+      this.animations,
+      {
+        target: this.target
+      },
+      { repeat: 2 }
+    );
     setTimeout(() => {
       if (!this.target || this.state !== "combat") {
         this.chargingAttack = false;
@@ -818,6 +838,10 @@ class BattleAi {
       }
       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();
@@ -832,7 +856,9 @@ class BattleAi {
    * Perform zone attack (360 degrees)
    */
   performZoneAttack() {
-    this.event.setGraphicAnimation("attack", 1);
+    playActionBattleAnimation("attack", this.event, this.animations, {
+      target: this.target ?? void 0
+    });
     const eventX = this.event.x();
     const eventY = this.event.y();
     const radius = 50;
@@ -1110,6 +1136,9 @@ class BattleAi {
       cycles: 1
     });
     this.event.showHit(`-${damage}`);
+    playActionBattleAnimation("hurt", this.event, this.animations, {
+      attacker
+    });
     this.recentDamageTaken += damage;
     if (this.state !== "stunned" && this.state !== "flee") {
       this.debugLog("damage", "Stunned from damage");
@@ -1134,11 +1163,24 @@ class BattleAi {
    * and removes the event from the map.
    */
   kill(attacker) {
+    const dieAnimation = playActionBattleAnimation(
+      "die",
+      this.event,
+      this.animations,
+      {
+        attacker
+      }
+    );
+    const removeDelay = getActionBattleAnimationRemovalDelay(dieAnimation);
     if (this.onDefeatedCallback) {
       this.onDefeatedCallback(this.event, attacker);
     }
     this.destroy();
-    this.event.remove();
+    if (removeDelay > 0) {
+      setTimeout(() => this.event.remove(), removeDelay);
+    } else {
+      this.event.remove();
+    }
   }
   /**
    * Get distance between entities

package/dist/client/index4.js

@@ -1,6 +1,7 @@
 import { defineModule, Control } from "@rpgjs/common";
-import { normalizeActionBattleOptions } from "./index8.js";
-import { manhattanDistance, parseAoeMask } from "./index9.js";
+import { normalizeActionBattleOptions, setActionBattleOptions } from "./index8.js";
+import { manhattanDistance, parseAoeMask } from "./index10.js";
+import { playActionBattleAnimation } from "./index9.js";
 const RpgEvent = null;
 const DEFAULT_KNOCKBACK = null;
 const ACTION_BATTLE_ACTION_BAR_GUI_ID = "action-battle-action-bar";
@@ -188,13 +189,20 @@ const getEntityTile = (entity, tileSize) => {
   return { x, y };
 };
 const handleActionBattleSkillUse = (player, skillId, target, options) => {
+  const skillData = resolveSkillData(player, skillId);
   const map = player.getCurrentMap();
   if (!map) {
+    playActionBattleAnimation("castSkill", player, options.animations, {
+      skill: skillData
+    });
     player.useSkill(skillId);
     return;
   }
   const targeting = resolveSkillTargeting(player, skillId, options);
   if (!targeting || !target) {
+    playActionBattleAnimation("castSkill", player, options.animations, {
+      skill: skillData
+    });
     player.useSkill(skillId);
     return;
   }
@@ -235,10 +243,15 @@ const handleActionBattleSkillUse = (player, skillId, target, options) => {
   if (!options.targeting?.allowEmptyTarget && targets.length === 0) {
     return;
   }
+  playActionBattleAnimation("castSkill", player, options.animations, {
+    skill: skillData,
+    target: targets[0]
+  });
   player.useSkill(skillId, targets);
 };
 const createActionBattleServer = (rawOptions = {}) => {
   const options = normalizeActionBattleOptions(rawOptions);
+  setActionBattleOptions(options);
   return defineModule({
     player: {
       /**
@@ -254,7 +267,7 @@ const createActionBattleServer = (rawOptions = {}) => {
        */
       onInput(player, input) {
         if (input.action == Control.Action) {
-          player.setGraphicAnimation("attack", 1);
+          playActionBattleAnimation("attack", player, options.animations);
           const playerX = player.x();
           const playerY = player.y();
           const direction = player.getDirection();

package/dist/client/index6.js

@@ -1,7 +1,7 @@
 import { useProps, useDefineProps, computed, h, Container, cond, Graphics } from "canvasengine";
 import { inject, RpgClientEngine } from "@rpgjs/client";
 import { actionBattleUiOptions, actionBattleTargetingState } from "./index7.js";
-import { parseAoeMask } from "./index9.js";
+import { parseAoeMask } from "./index10.js";
 function component($$props) {
   useProps($$props);
   const defineProps = useDefineProps($$props);

package/dist/client/index8.js

@@ -21,8 +21,10 @@ const DEFAULT_ACTION_BATTLE_OPTIONS = {
   targeting: {
     affects: "events",
     allowEmptyTarget: true
-  }
+  },
+  animations: {}
 };
+let currentActionBattleOptions = DEFAULT_ACTION_BATTLE_OPTIONS;
 function normalizeActionBattleOptions(options = {}) {
   return {
     ui: {
@@ -46,10 +48,22 @@ function normalizeActionBattleOptions(options = {}) {
     targeting: {
       ...DEFAULT_ACTION_BATTLE_OPTIONS.targeting,
       ...options.targeting
+    },
+    animations: {
+      ...DEFAULT_ACTION_BATTLE_OPTIONS.animations,
+      ...options.animations
     }
   };
 }
+function setActionBattleOptions(options) {
+  currentActionBattleOptions = options;
+}
+function getActionBattleOptions() {
+  return currentActionBattleOptions;
+}
 export {
   DEFAULT_ACTION_BATTLE_OPTIONS,
-  normalizeActionBattleOptions
+  getActionBattleOptions,
+  normalizeActionBattleOptions,
+  setActionBattleOptions
 };

package/dist/client/index9.js

@@ -1,30 +1,64 @@
-const normalizeMaskRows = (mask) => {
-  if (!mask) return ["#"];
-  if (Array.isArray(mask)) return mask;
-  return mask.trim().split("\n").map((row) => row.replace(/\r/g, ""));
+const DEFAULT_DIE_ANIMATION_DELAY_MS = 500;
+const DEFAULT_ANIMATION_BY_KEY = {
+  attack: "attack",
+  hurt: "hurt",
+  die: "die",
+  castSkill: "skill"
 };
-const parseAoeMask = (mask) => {
-  const rows = normalizeMaskRows(mask);
-  const height = rows.length;
-  const width = rows.reduce((max, row) => Math.max(max, row.length), 0);
-  const centerX = Math.floor(width / 2);
-  const centerY = Math.floor(height / 2);
-  const cells = [];
-  rows.forEach((row, y) => {
-    for (let x = 0; x < row.length; x++) {
-      const char = row[x];
-      if (char && char !== "." && char !== " ") {
-        cells.push({ dx: x - centerX, dy: y - centerY });
-      }
-    }
-  });
-  if (cells.length === 0) {
-    cells.push({ dx: 0, dy: 0 });
+function resolveActionBattleAnimation(key, entity, animations, context, defaults = {}) {
+  const defaultAnimationName = defaults.animationName ?? DEFAULT_ANIMATION_BY_KEY[key];
+  const defaultRepeat = defaults.repeat ?? 1;
+  const hasConfiguredAnimation = animations ? Object.prototype.hasOwnProperty.call(animations, key) : false;
+  if (!hasConfiguredAnimation && key !== "attack") {
+    return null;
   }
-  return { width, height, centerX, centerY, cells };
-};
-const manhattanDistance = (a, b) => Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
+  const configured = hasConfiguredAnimation ? animations?.[key] : defaultAnimationName;
+  const result = typeof configured === "function" ? configured(entity, context) : configured;
+  if (result == null) return null;
+  if (typeof result === "string") {
+    return {
+      animationName: result,
+      repeat: defaultRepeat,
+      waitEnd: false
+    };
+  }
+  const animationName = result.animationName ?? defaultAnimationName;
+  return {
+    animationName,
+    graphic: result.graphic,
+    repeat: result.repeat ?? defaultRepeat,
+    waitEnd: result.waitEnd ?? false,
+    delayMs: result.delayMs
+  };
+}
+function playActionBattleAnimation(key, entity, animations, context, defaults = {}) {
+  const animation = resolveActionBattleAnimation(
+    key,
+    entity,
+    animations,
+    context,
+    defaults
+  );
+  if (!animation) return null;
+  if (animation.graphic !== void 0) {
+    entity.setGraphicAnimation(
+      animation.animationName,
+      animation.graphic,
+      animation.repeat
+    );
+  } else {
+    entity.setGraphicAnimation(animation.animationName, animation.repeat);
+  }
+  return animation;
+}
+function getActionBattleAnimationRemovalDelay(animation) {
+  if (!animation) return 0;
+  if (animation.delayMs !== void 0) return animation.delayMs;
+  return animation.waitEnd ? DEFAULT_DIE_ANIMATION_DELAY_MS : 0;
+}
 export {
-  manhattanDistance,
-  parseAoeMask
+  DEFAULT_DIE_ANIMATION_DELAY_MS,
+  getActionBattleAnimationRemovalDelay,
+  playActionBattleAnimation,
+  resolveActionBattleAnimation
 };

package/dist/config.d.ts

@@ -1,3 +1,5 @@
 import { ActionBattleOptions } from './types';
 export declare const DEFAULT_ACTION_BATTLE_OPTIONS: ActionBattleOptions;
 export declare function normalizeActionBattleOptions(options?: ActionBattleOptions): ActionBattleOptions;
+export declare function setActionBattleOptions(options: ActionBattleOptions): void;
+export declare function getActionBattleOptions(): ActionBattleOptions;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ActionBattleOptions } from './types';
 export { BattleAi, AiState, EnemyType, AttackPattern, AiDebug, DEFAULT_KNOCKBACK } from './ai.server';
-export type { HitResult, ApplyHitHooks } from './ai.server';
-export type { ActionBattleOptions, ActionBattleActionBarData, ActionBattleActionBarItem, ActionBattleActionBarSkill, ActionBattleSkillTargeting, ActionBattleSkillTargetingResolver, ActionBattleUiOptions, ActionBattleUiActionBarOptions, ActionBattleUiTargetingOptions, } from './types';
+export type { HitResult, ApplyHitHooks, BattleAiOptions } from './ai.server';
+export type { ActionBattleAnimationContext, ActionBattleAnimationEntity, ActionBattleAnimationKey, ActionBattleAnimationOptions, ActionBattleAnimationResolver, ActionBattleAnimationResult, ActionBattleOptions, ActionBattleActionBarData, ActionBattleActionBarItem, ActionBattleActionBarSkill, ActionBattleSkillTargeting, ActionBattleSkillTargetingResolver, ActionBattleUiOptions, ActionBattleUiActionBarOptions, ActionBattleUiTargetingOptions, } from './types';
 export { DEFAULT_PLAYER_ATTACK_HITBOXES, getPlayerWeaponKnockbackForce, applyPlayerHitToEvent, ACTION_BATTLE_ACTION_BAR_GUI_ID, openActionBattleActionBar, updateActionBattleActionBar, createActionBattleServer, } from './server';
 export declare function provideActionBattle(options?: ActionBattleOptions): any;
 declare const _default: {

package/dist/server/index2.js

@@ -1,8 +1,9 @@
 import { RpgEvent } from "@rpgjs/server";
 import { defineModule, Control } from "@rpgjs/common";
 import { DEFAULT_KNOCKBACK } from "./index3.js";
-import { normalizeActionBattleOptions } from "./index4.js";
+import { normalizeActionBattleOptions, setActionBattleOptions } from "./index4.js";
 import { manhattanDistance, parseAoeMask } from "./index5.js";
+import { playActionBattleAnimation } from "./index6.js";
 const ACTION_BATTLE_ACTION_BAR_GUI_ID = "action-battle-action-bar";
 const DEFAULT_PLAYER_ATTACK_HITBOXES = {
   up: { offsetX: -16, offsetY: -48, width: 32, height: 32 },
@@ -188,13 +189,20 @@ const getEntityTile = (entity, tileSize) => {
   return { x, y };
 };
 const handleActionBattleSkillUse = (player, skillId, target, options) => {
+  const skillData = resolveSkillData(player, skillId);
   const map = player.getCurrentMap();
   if (!map) {
+    playActionBattleAnimation("castSkill", player, options.animations, {
+      skill: skillData
+    });
     player.useSkill(skillId);
     return;
   }
   const targeting = resolveSkillTargeting(player, skillId, options);
   if (!targeting || !target) {
+    playActionBattleAnimation("castSkill", player, options.animations, {
+      skill: skillData
+    });
     player.useSkill(skillId);
     return;
   }
@@ -235,10 +243,15 @@ const handleActionBattleSkillUse = (player, skillId, target, options) => {
   if (!options.targeting?.allowEmptyTarget && targets.length === 0) {
     return;
   }
+  playActionBattleAnimation("castSkill", player, options.animations, {
+    skill: skillData,
+    target: targets[0]
+  });
   player.useSkill(skillId, targets);
 };
 const createActionBattleServer = (rawOptions = {}) => {
   const options = normalizeActionBattleOptions(rawOptions);
+  setActionBattleOptions(options);
   return defineModule({
     player: {
       /**
@@ -254,7 +267,7 @@ const createActionBattleServer = (rawOptions = {}) => {
        */
       onInput(player, input) {
         if (input.action == Control.Action) {
-          player.setGraphicAnimation("attack", 1);
+          playActionBattleAnimation("attack", player, options.animations);
           const playerX = player.x();
           const playerY = player.y();
           const direction = player.getDirection();

package/dist/server/index3.js

@@ -1,4 +1,6 @@
 import { MAXHP, RpgPlayer } from "@rpgjs/server";
+import { playActionBattleAnimation, getActionBattleAnimationRemovalDelay } from "./index6.js";
+import { getActionBattleOptions } from "./index4.js";
 const AiDebug = {
   /** Enable/disable all AI debug logs */
   enabled: typeof process !== "undefined" && process.env?.RPGJS_DEBUG_AI === "1" || false,
@@ -117,6 +119,10 @@ class BattleAi {
     this.enemyType = options.enemyType || "aggressive";
     this.applyEnemyTypeBehavior(options);
     this.attackSkill = options.attackSkill || null;
+    this.animations = {
+      ...getActionBattleOptions().animations,
+      ...options.animations
+    };
     this.attackPatterns = options.attackPatterns || [
       "melee",
       "combo",
@@ -642,9 +648,15 @@ class BattleAi {
   performMeleeAttack() {
     if (!this.target) return;
     this.faceTarget();
-    this.event.setGraphicAnimation("attack", 1);
+    playActionBattleAnimation("attack", this.event, this.animations, {
+      target: this.target
+    });
     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();
@@ -809,7 +821,15 @@ class BattleAi {
     if (!this.target) return;
     this.chargingAttack = true;
     this.faceTarget();
-    this.event.setGraphicAnimation("attack", 2);
+    playActionBattleAnimation(
+      "attack",
+      this.event,
+      this.animations,
+      {
+        target: this.target
+      },
+      { repeat: 2 }
+    );
     setTimeout(() => {
       if (!this.target || this.state !== "combat") {
         this.chargingAttack = false;
@@ -817,6 +837,10 @@ class BattleAi {
       }
       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();
@@ -831,7 +855,9 @@ class BattleAi {
    * Perform zone attack (360 degrees)
    */
   performZoneAttack() {
-    this.event.setGraphicAnimation("attack", 1);
+    playActionBattleAnimation("attack", this.event, this.animations, {
+      target: this.target ?? void 0
+    });
     const eventX = this.event.x();
     const eventY = this.event.y();
     const radius = 50;
@@ -1109,6 +1135,9 @@ class BattleAi {
       cycles: 1
     });
     this.event.showHit(`-${damage}`);
+    playActionBattleAnimation("hurt", this.event, this.animations, {
+      attacker
+    });
     this.recentDamageTaken += damage;
     if (this.state !== "stunned" && this.state !== "flee") {
       this.debugLog("damage", "Stunned from damage");
@@ -1133,11 +1162,24 @@ class BattleAi {
    * and removes the event from the map.
    */
   kill(attacker) {
+    const dieAnimation = playActionBattleAnimation(
+      "die",
+      this.event,
+      this.animations,
+      {
+        attacker
+      }
+    );
+    const removeDelay = getActionBattleAnimationRemovalDelay(dieAnimation);
     if (this.onDefeatedCallback) {
       this.onDefeatedCallback(this.event, attacker);
     }
     this.destroy();
-    this.event.remove();
+    if (removeDelay > 0) {
+      setTimeout(() => this.event.remove(), removeDelay);
+    } else {
+      this.event.remove();
+    }
   }
   /**
    * Get distance between entities

package/dist/server/index4.js

@@ -21,8 +21,10 @@ const DEFAULT_ACTION_BATTLE_OPTIONS = {
   targeting: {
     affects: "events",
     allowEmptyTarget: true
-  }
+  },
+  animations: {}
 };
+let currentActionBattleOptions = DEFAULT_ACTION_BATTLE_OPTIONS;
 function normalizeActionBattleOptions(options = {}) {
   return {
     ui: {
@@ -46,10 +48,22 @@ function normalizeActionBattleOptions(options = {}) {
     targeting: {
       ...DEFAULT_ACTION_BATTLE_OPTIONS.targeting,
       ...options.targeting
+    },
+    animations: {
+      ...DEFAULT_ACTION_BATTLE_OPTIONS.animations,
+      ...options.animations
     }
   };
 }
+function setActionBattleOptions(options) {
+  currentActionBattleOptions = options;
+}
+function getActionBattleOptions() {
+  return currentActionBattleOptions;
+}
 export {
   DEFAULT_ACTION_BATTLE_OPTIONS,
-  normalizeActionBattleOptions
+  getActionBattleOptions,
+  normalizeActionBattleOptions,
+  setActionBattleOptions
 };

package/dist/server/index6.js

@@ -0,0 +1,64 @@
+const DEFAULT_DIE_ANIMATION_DELAY_MS = 500;
+const DEFAULT_ANIMATION_BY_KEY = {
+  attack: "attack",
+  hurt: "hurt",
+  die: "die",
+  castSkill: "skill"
+};
+function resolveActionBattleAnimation(key, entity, animations, context, defaults = {}) {
+  const defaultAnimationName = defaults.animationName ?? DEFAULT_ANIMATION_BY_KEY[key];
+  const defaultRepeat = defaults.repeat ?? 1;
+  const hasConfiguredAnimation = animations ? Object.prototype.hasOwnProperty.call(animations, key) : false;
+  if (!hasConfiguredAnimation && key !== "attack") {
+    return null;
+  }
+  const configured = hasConfiguredAnimation ? animations?.[key] : defaultAnimationName;
+  const result = typeof configured === "function" ? configured(entity, context) : configured;
+  if (result == null) return null;
+  if (typeof result === "string") {
+    return {
+      animationName: result,
+      repeat: defaultRepeat,
+      waitEnd: false
+    };
+  }
+  const animationName = result.animationName ?? defaultAnimationName;
+  return {
+    animationName,
+    graphic: result.graphic,
+    repeat: result.repeat ?? defaultRepeat,
+    waitEnd: result.waitEnd ?? false,
+    delayMs: result.delayMs
+  };
+}
+function playActionBattleAnimation(key, entity, animations, context, defaults = {}) {
+  const animation = resolveActionBattleAnimation(
+    key,
+    entity,
+    animations,
+    context,
+    defaults
+  );
+  if (!animation) return null;
+  if (animation.graphic !== void 0) {
+    entity.setGraphicAnimation(
+      animation.animationName,
+      animation.graphic,
+      animation.repeat
+    );
+  } else {
+    entity.setGraphicAnimation(animation.animationName, animation.repeat);
+  }
+  return animation;
+}
+function getActionBattleAnimationRemovalDelay(animation) {
+  if (!animation) return 0;
+  if (animation.delayMs !== void 0) return animation.delayMs;
+  return animation.waitEnd ? DEFAULT_DIE_ANIMATION_DELAY_MS : 0;
+}
+export {
+  DEFAULT_DIE_ANIMATION_DELAY_MS,
+  getActionBattleAnimationRemovalDelay,
+  playActionBattleAnimation,
+  resolveActionBattleAnimation
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpgjs/action-battle",
-  "version": "5.0.0-alpha.44",
+  "version": "5.0.0-beta.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -23,10 +23,10 @@
   "description": "RPGJS is a framework for creating RPG/MMORPG games",
   "peerDependencies": {
     "@canvasengine/presets": "*",
-    "@rpgjs/client": "5.0.0-alpha.44",
-    "@rpgjs/common": "5.0.0-alpha.44",
-    "@rpgjs/server": "5.0.0-alpha.44",
-    "@rpgjs/vite": "5.0.0-alpha.44",
+    "@rpgjs/client": "5.0.0-beta.2",
+    "@rpgjs/common": "5.0.0-beta.2",
+    "@rpgjs/server": "5.0.0-beta.2",
+    "@rpgjs/vite": "5.0.0-beta.2",
     "canvasengine": "*"
   },
   "publishConfig": {

package/src/ai.server.ts

@@ -1,9 +1,41 @@
 import { MAXHP, RpgEvent, RpgPlayer } from "@rpgjs/server";
+import {
+  getActionBattleAnimationRemovalDelay,
+  playActionBattleAnimation,
+} from "./animations";
+import { getActionBattleOptions } from "./config";
+import type { ActionBattleAnimationOptions } from "./types";
 
 type RpgEventWithBattleAi = RpgEvent & {
   battleAi: BattleAi;
 };
 
+export interface BattleAiOptions {
+  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;
+  };
+  animations?: ActionBattleAnimationOptions;
+  /** Callback called when the AI is defeated */
+  onDefeated?: (event: RpgEvent, attacker?: RpgPlayer) => void;
+}
+
 /**
  * Hit result data returned after applying damage
  * 
@@ -258,6 +290,7 @@ export class BattleAi {
   // Attack configuration
   private attackSkill: any | null; // Skill to use for attacks
   private attackPatterns: AttackPattern[];
+  private animations?: ActionBattleAnimationOptions;
   private comboCount: number = 0;
   private comboMax: number = 3;
   private chargingAttack: boolean = false;
@@ -327,30 +360,7 @@ export class BattleAi {
    */
   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 = {}
   ) {
     event.battleAi = this;
     this.event = event;
@@ -361,6 +371,10 @@ export class BattleAi {
 
     // Store attack skill reference
     this.attackSkill = options.attackSkill || null;
+    this.animations = {
+      ...getActionBattleOptions().animations,
+      ...options.animations,
+    };
 
     // Initialize attack patterns
     this.attackPatterns = options.attackPatterns || [
@@ -867,11 +881,17 @@ export class BattleAi {
     if (!this.target) return;
 
     this.faceTarget();
-    this.event.setGraphicAnimation('attack', 1);
+    playActionBattleAnimation("attack", this.event, this.animations, {
+      target: this.target,
+    });
 
     // 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
@@ -1066,7 +1086,15 @@ export class BattleAi {
 
     this.chargingAttack = true;
     this.faceTarget();
-    this.event.setGraphicAnimation('attack', 2);
+    playActionBattleAnimation(
+      "attack",
+      this.event,
+      this.animations,
+      {
+        target: this.target,
+      },
+      { repeat: 2 }
+    );
 
     setTimeout(() => {
       if (!this.target || this.state !== AiState.Combat) {
@@ -1077,6 +1105,10 @@ export class BattleAi {
       // 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();
@@ -1093,7 +1125,9 @@ export class BattleAi {
    * Perform zone attack (360 degrees)
    */
   private performZoneAttack() {
-    this.event.setGraphicAnimation('attack', 1);
+    playActionBattleAnimation("attack", this.event, this.animations, {
+      target: this.target ?? undefined,
+    });
 
     const eventX = this.event.x();
     const eventY = this.event.y();
@@ -1439,6 +1473,9 @@ export class BattleAi {
       cycles: 1
     });
     this.event.showHit(`-${damage}`);
+    playActionBattleAnimation("hurt", this.event, this.animations, {
+      attacker,
+    });
 
     // Track damage
     this.recentDamageTaken += damage;
@@ -1468,13 +1505,27 @@ export class BattleAi {
    * and removes the event from the map.
    */
   private kill(attacker?: RpgPlayer) {
+    const dieAnimation = playActionBattleAnimation(
+      "die",
+      this.event,
+      this.animations,
+      {
+        attacker,
+      }
+    );
+    const removeDelay = getActionBattleAnimationRemovalDelay(dieAnimation);
+
     // Call onDefeated hook before cleanup
     if (this.onDefeatedCallback) {
       this.onDefeatedCallback(this.event, attacker);
     }
     
     this.destroy();
-    this.event.remove();
+    if (removeDelay > 0) {
+      setTimeout(() => this.event.remove(), removeDelay);
+    } else {
+      this.event.remove();
+    }
   }
 
   /**

package/src/animations.ts

@@ -0,0 +1,110 @@
+import type {
+  ActionBattleAnimationContext,
+  ActionBattleAnimationEntity,
+  ActionBattleAnimationKey,
+  ActionBattleAnimationOptions,
+} from "./types";
+
+export const DEFAULT_DIE_ANIMATION_DELAY_MS = 500;
+
+export interface ResolvedActionBattleAnimation {
+  animationName: string;
+  graphic?: string | string[];
+  repeat: number;
+  waitEnd: boolean;
+  delayMs?: number;
+}
+
+export interface ActionBattleAnimationDefaults {
+  animationName?: string;
+  repeat?: number;
+}
+
+const DEFAULT_ANIMATION_BY_KEY: Record<ActionBattleAnimationKey, string> = {
+  attack: "attack",
+  hurt: "hurt",
+  die: "die",
+  castSkill: "skill",
+};
+
+export function resolveActionBattleAnimation(
+  key: ActionBattleAnimationKey,
+  entity: ActionBattleAnimationEntity,
+  animations?: ActionBattleAnimationOptions,
+  context?: ActionBattleAnimationContext,
+  defaults: ActionBattleAnimationDefaults = {}
+): ResolvedActionBattleAnimation | null {
+  const defaultAnimationName =
+    defaults.animationName ?? DEFAULT_ANIMATION_BY_KEY[key];
+  const defaultRepeat = defaults.repeat ?? 1;
+  const hasConfiguredAnimation = animations
+    ? Object.prototype.hasOwnProperty.call(animations, key)
+    : false;
+  if (!hasConfiguredAnimation && key !== "attack") {
+    return null;
+  }
+
+  const configured = hasConfiguredAnimation
+    ? animations?.[key]
+    : defaultAnimationName;
+  const result =
+    typeof configured === "function"
+      ? configured(entity, context)
+      : configured;
+
+  if (result == null) return null;
+
+  if (typeof result === "string") {
+    return {
+      animationName: result,
+      repeat: defaultRepeat,
+      waitEnd: false,
+    };
+  }
+
+  const animationName = result.animationName ?? defaultAnimationName;
+  return {
+    animationName,
+    graphic: result.graphic,
+    repeat: result.repeat ?? defaultRepeat,
+    waitEnd: result.waitEnd ?? false,
+    delayMs: result.delayMs,
+  };
+}
+
+export function playActionBattleAnimation(
+  key: ActionBattleAnimationKey,
+  entity: ActionBattleAnimationEntity,
+  animations?: ActionBattleAnimationOptions,
+  context?: ActionBattleAnimationContext,
+  defaults: ActionBattleAnimationDefaults = {}
+): ResolvedActionBattleAnimation | null {
+  const animation = resolveActionBattleAnimation(
+    key,
+    entity,
+    animations,
+    context,
+    defaults
+  );
+  if (!animation) return null;
+
+  if (animation.graphic !== undefined) {
+    entity.setGraphicAnimation(
+      animation.animationName,
+      animation.graphic,
+      animation.repeat
+    );
+  } else {
+    entity.setGraphicAnimation(animation.animationName, animation.repeat);
+  }
+
+  return animation;
+}
+
+export function getActionBattleAnimationRemovalDelay(
+  animation: ResolvedActionBattleAnimation | null
+): number {
+  if (!animation) return 0;
+  if (animation.delayMs !== undefined) return animation.delayMs;
+  return animation.waitEnd ? DEFAULT_DIE_ANIMATION_DELAY_MS : 0;
+}

package/src/config.ts

@@ -24,8 +24,12 @@ export const DEFAULT_ACTION_BATTLE_OPTIONS: ActionBattleOptions = {
     affects: "events",
     allowEmptyTarget: true,
   },
+  animations: {},
 };
 
+let currentActionBattleOptions: ActionBattleOptions =
+  DEFAULT_ACTION_BATTLE_OPTIONS;
+
 export function normalizeActionBattleOptions(
   options: ActionBattleOptions = {}
 ): ActionBattleOptions {
@@ -52,5 +56,17 @@ export function normalizeActionBattleOptions(
       ...DEFAULT_ACTION_BATTLE_OPTIONS.targeting,
       ...options.targeting,
     },
+    animations: {
+      ...DEFAULT_ACTION_BATTLE_OPTIONS.animations,
+      ...options.animations,
+    },
   };
 }
+
+export function setActionBattleOptions(options: ActionBattleOptions) {
+  currentActionBattleOptions = options;
+}
+
+export function getActionBattleOptions(): ActionBattleOptions {
+  return currentActionBattleOptions;
+}

package/src/index.ts

@@ -7,8 +7,14 @@ import type { ActionBattleOptions } from "./types";
 export { BattleAi, AiState, EnemyType, AttackPattern, AiDebug, DEFAULT_KNOCKBACK } from "./ai.server";
 
 // Types exports
-export type { HitResult, ApplyHitHooks } from "./ai.server";
+export type { HitResult, ApplyHitHooks, BattleAiOptions } from "./ai.server";
 export type {
+  ActionBattleAnimationContext,
+  ActionBattleAnimationEntity,
+  ActionBattleAnimationKey,
+  ActionBattleAnimationOptions,
+  ActionBattleAnimationResolver,
+  ActionBattleAnimationResult,
   ActionBattleOptions,
   ActionBattleActionBarData,
   ActionBattleActionBarItem,

package/src/server.ts

@@ -6,8 +6,9 @@ import {
   ActionBattleActionBarSkill,
   ActionBattleOptions,
 } from "./types";
-import { normalizeActionBattleOptions } from "./config";
+import { normalizeActionBattleOptions, setActionBattleOptions } from "./config";
 import { manhattanDistance, parseAoeMask } from "./targeting";
+import { playActionBattleAnimation } from "./animations";
 
 export const ACTION_BATTLE_ACTION_BAR_GUI_ID = "action-battle-action-bar";
 
@@ -330,13 +331,21 @@ const handleActionBattleSkillUse = (
   target: { x: number; y: number } | undefined,
   options: ActionBattleOptions
 ) => {
+  const skillData = resolveSkillData(player, skillId);
+
   const map = player.getCurrentMap();
   if (!map) {
+    playActionBattleAnimation("castSkill", player, options.animations, {
+      skill: skillData,
+    });
     player.useSkill(skillId);
     return;
   }
   const targeting = resolveSkillTargeting(player, skillId, options);
   if (!targeting || !target) {
+    playActionBattleAnimation("castSkill", player, options.animations, {
+      skill: skillData,
+    });
     player.useSkill(skillId);
     return;
   }
@@ -383,6 +392,10 @@ const handleActionBattleSkillUse = (
     return;
   }
 
+  playActionBattleAnimation("castSkill", player, options.animations, {
+    skill: skillData,
+    target: targets[0],
+  });
   player.useSkill(skillId, targets as any);
 };
 
@@ -390,6 +403,7 @@ export const createActionBattleServer = (
   rawOptions: ActionBattleOptions = {}
 ) => {
   const options = normalizeActionBattleOptions(rawOptions);
+  setActionBattleOptions(options);
   return defineModule<RpgServer>({
     player: {
       /**
@@ -405,8 +419,7 @@ export const createActionBattleServer = (
        */
       onInput(player: RpgPlayer, input: any) {
         if (input.action == Control.Action) {
-          // Trigger attack animation
-          player.setGraphicAnimation("attack", 1);
+          playActionBattleAnimation("attack", player, options.animations);
 
           // Get player position
           const playerX = player.x();

package/src/types.ts

@@ -4,6 +4,52 @@ export type ActionBattleActionBarMode = "items" | "skills" | "both";
 
 export type ActionBattleTargetingAffects = "events" | "players" | "both";
 
+export type ActionBattleAnimationKey =
+  | "attack"
+  | "hurt"
+  | "die"
+  | "castSkill";
+
+export type ActionBattleAnimationResult =
+  | string
+  | {
+      animationName?: string;
+      graphic?: string | string[];
+      repeat?: number;
+      waitEnd?: boolean;
+      delayMs?: number;
+    }
+  | null
+  | undefined;
+
+export type ActionBattleAnimationEntity = {
+  setGraphicAnimation(animationName: string, repeat: number): void;
+  setGraphicAnimation(
+    animationName: string,
+    graphic: string | string[],
+    repeat: number
+  ): void;
+  [key: string]: any;
+};
+
+export interface ActionBattleAnimationContext {
+  skill?: any;
+  attacker?: ActionBattleAnimationEntity;
+  target?: ActionBattleAnimationEntity;
+}
+
+export type ActionBattleAnimationResolver = (
+  entity: ActionBattleAnimationEntity,
+  context?: ActionBattleAnimationContext
+) => ActionBattleAnimationResult;
+
+export type ActionBattleAnimationOptions = Partial<
+  Record<
+    ActionBattleAnimationKey,
+    ActionBattleAnimationResult | ActionBattleAnimationResolver
+  >
+>;
+
 export interface ActionBattleSkillTargeting {
   range: number;
   aoeMask?: ActionBattleAoeMask;
@@ -49,6 +95,7 @@ export interface ActionBattleOptions {
   ui?: ActionBattleUiOptions;
   skills?: ActionBattleSkillOptions;
   targeting?: ActionBattleTargetingOptions;
+  animations?: ActionBattleAnimationOptions;
 }
 
 export interface ActionBattleActionBarItem {