@rpgjs/action-battle 5.0.0-beta.1 → 5.0.0-beta.3

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/index.js

@@ -1,35 +1,19 @@
-import client, { createActionBattleClient } from "./index2.js";
+import client_default, { createActionBattleClient } from "./index7.js";
+import { AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_KNOCKBACK, EnemyType } from "./index9.js";
+import { ACTION_BATTLE_ACTION_BAR_GUI_ID, DEFAULT_PLAYER_ATTACK_HITBOXES, applyPlayerHitToEvent, createActionBattleServer, getPlayerWeaponKnockbackForce, openActionBattleActionBar, updateActionBattleActionBar } from "./index10.js";
 import { createModule } from "@rpgjs/common";
-import { AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_KNOCKBACK, EnemyType } from "./index3.js";
-import { ACTION_BATTLE_ACTION_BAR_GUI_ID, DEFAULT_PLAYER_ATTACK_HITBOXES, applyPlayerHitToEvent, createActionBattleServer, getPlayerWeaponKnockbackForce, openActionBattleActionBar, updateActionBattleActionBar } from "./index4.js";
-const server = null;
-const createActionBattleServer2 = null;
+//#region src/index.ts
+var server = null;
+var createActionBattleServer$1 = null;
 function provideActionBattle(options = {}) {
-  return createModule("ActionBattle", [
-    {
-      server: createActionBattleServer2?.(options),
-      client: createActionBattleClient?.(options)
-    }
-  ]);
+	return createModule("ActionBattle", [{
+		server: createActionBattleServer$1?.(options),
+		client: createActionBattleClient?.(options)
+	}]);
 }
-const index = {
-  server,
-  client
-};
-export {
-  ACTION_BATTLE_ACTION_BAR_GUI_ID,
-  AiDebug,
-  AiState,
-  AttackPattern,
-  BattleAi,
-  DEFAULT_KNOCKBACK,
-  DEFAULT_PLAYER_ATTACK_HITBOXES,
-  EnemyType,
-  applyPlayerHitToEvent,
-  createActionBattleServer,
-  index as default,
-  getPlayerWeaponKnockbackForce,
-  openActionBattleActionBar,
-  provideActionBattle,
-  updateActionBattleActionBar
+var src_default = {
+	server,
+	client: client_default
 };
+//#endregion
+export { ACTION_BATTLE_ACTION_BAR_GUI_ID, AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_KNOCKBACK, DEFAULT_PLAYER_ATTACK_HITBOXES, EnemyType, applyPlayerHitToEvent, createActionBattleServer, src_default as default, getPlayerWeaponKnockbackForce, openActionBattleActionBar, provideActionBattle, updateActionBattleActionBar };

package/dist/client/index10.js

@@ -0,0 +1,376 @@
+import { normalizeActionBattleOptions, setActionBattleOptions } from "./index2.js";
+import { manhattanDistance, parseAoeMask } from "./index5.js";
+import { playActionBattleAnimation } from "./index8.js";
+import { Control, defineModule } from "@rpgjs/common";
+//#region src/server.ts
+var RpgEvent = null;
+var DEFAULT_KNOCKBACK = null;
+var ACTION_BATTLE_ACTION_BAR_GUI_ID = "action-battle-action-bar";
+/**
+* Default player attack hitboxes offsets for each direction
+* 
+* These hitboxes define the attack areas relative to the player's position
+* for each cardinal direction. They are converted to absolute coordinates
+* when creating the moving hitbox.
+*/
+var DEFAULT_PLAYER_ATTACK_HITBOXES = {
+	up: {
+		offsetX: -16,
+		offsetY: -48,
+		width: 32,
+		height: 32
+	},
+	down: {
+		offsetX: -16,
+		offsetY: 16,
+		width: 32,
+		height: 32
+	},
+	left: {
+		offsetX: -48,
+		offsetY: -16,
+		width: 32,
+		height: 32
+	},
+	right: {
+		offsetX: 16,
+		offsetY: -16,
+		width: 32,
+		height: 32
+	},
+	default: {
+		offsetX: 0,
+		offsetY: -32,
+		width: 32,
+		height: 32
+	}
+};
+/**
+* Get knockback force from player's equipped weapon
+* 
+* Retrieves the knockbackForce property from the player's equipped weapon.
+* Falls back to DEFAULT_KNOCKBACK.force if no weapon or property is set.
+* 
+* @param player - The player to get weapon knockback from
+* @returns Knockback force value
+* 
+* @example
+* ```ts
+* // Player with weapon having knockbackForce: 80
+* const force = getPlayerWeaponKnockbackForce(player); // 80
+* 
+* // No weapon equipped
+* const force = getPlayerWeaponKnockbackForce(player); // 50 (default)
+* ```
+*/
+function getPlayerWeaponKnockbackForce(player) {
+	try {
+		const equipments = player.equipments?.() || [];
+		for (const item of equipments) {
+			const itemData = player.databaseById?.(item.id());
+			if (itemData?._type === "weapon" && itemData.knockbackForce !== void 0) return itemData.knockbackForce;
+		}
+	} catch {}
+	return DEFAULT_KNOCKBACK.force;
+}
+/**
+* Apply hit from player to target (event with AI)
+* 
+* Handles damage calculation, knockback based on weapon, and visual effects.
+* Can be customized using hooks.
+* 
+* @param player - The attacking player
+* @param target - The event being hit
+* @param hooks - Optional hooks for customizing hit behavior
+* @returns Hit result if AI exists, undefined otherwise
+* 
+* @example
+* ```ts
+* // Basic hit
+* const result = applyPlayerHitToEvent(player, event);
+* 
+* // With custom hooks
+* const result = applyPlayerHitToEvent(player, event, {
+*   onBeforeHit(result) {
+*     result.knockbackForce *= 2; // Double knockback
+*     return result;
+*   },
+*   onAfterHit(result) {
+*     if (result.defeated) {
+*       player.gold += 10;
+*     }
+*   }
+* });
+* ```
+*/
+function applyPlayerHitToEvent(player, target, hooks) {
+	const ai = target.battleAi;
+	if (!ai) return void 0;
+	const knockbackForce = getPlayerWeaponKnockbackForce(player);
+	const defeated = ai.takeDamage(player);
+	const dx = target.x() - player.x();
+	const dy = target.y() - player.y();
+	const distance = Math.sqrt(dx * dx + dy * dy);
+	let hitResult = {
+		damage: 0,
+		knockbackForce,
+		knockbackDuration: DEFAULT_KNOCKBACK.duration,
+		defeated,
+		attacker: player,
+		target
+	};
+	if (hooks?.onBeforeHit) {
+		const modified = hooks.onBeforeHit(hitResult);
+		if (modified) hitResult = modified;
+	}
+	if (!hitResult.defeated && hitResult.knockbackForce > 0 && distance > 0) {
+		const knockbackDirection = {
+			x: dx / distance,
+			y: dy / distance
+		};
+		target.knockback(knockbackDirection, hitResult.knockbackForce, hitResult.knockbackDuration);
+	}
+	if (hooks?.onAfterHit) hooks.onAfterHit(hitResult);
+	return hitResult;
+}
+var resolveSignal = (value) => typeof value === "function" ? value() : value;
+var resolveItemData = (player, itemId) => {
+	try {
+		return player.databaseById?.(itemId);
+	} catch {
+		return null;
+	}
+};
+var resolveSkillData = (player, skillId) => {
+	try {
+		return player.databaseById?.(skillId);
+	} catch {
+		return null;
+	}
+};
+var resolveSkillTargeting = (player, skillId, options) => {
+	const skillsOptions = options.skills;
+	const skillData = resolveSkillData(player, skillId);
+	if (skillsOptions?.getTargeting) return skillsOptions.getTargeting(skillData);
+	const range = skillData?.range ?? skillData?.targeting?.range ?? skillData?.targeting?.distance;
+	const aoeMask = skillData?.aoeMask ?? skillData?.targeting?.aoeMask ?? skillData?.targeting?.mask;
+	if (range === void 0 && aoeMask === void 0) return null;
+	return {
+		range: range ?? 0,
+		aoeMask
+	};
+};
+var normalizeMaskRows = (mask) => {
+	if (!mask) return [];
+	if (Array.isArray(mask)) return mask;
+	return mask.trim().split("\n").map((row) => row.replace(/\r/g, ""));
+};
+var buildActionBarData = (player, options) => {
+	return {
+		items: (player.items?.() || []).map((item) => {
+			const id = item.id?.() ?? item.id;
+			const data = resolveItemData(player, id);
+			const name = resolveSignal(data?.name) ?? resolveSignal(item.name) ?? id;
+			const description = resolveSignal(data?.description) ?? resolveSignal(item.description) ?? "";
+			const icon = resolveSignal(data?.icon) ?? resolveSignal(item.icon);
+			const quantity = resolveSignal(item.quantity) ?? 1;
+			const consumable = resolveSignal(data?.consumable);
+			const itemType = resolveSignal(data?._type);
+			return {
+				id,
+				name,
+				description,
+				icon,
+				quantity,
+				usable: quantity > 0 && consumable !== false && (itemType ? itemType === "item" : true)
+			};
+		}),
+		skills: (player.skills?.() || []).map((skill) => {
+			const id = skill.id?.() ?? skill.id;
+			const data = resolveSkillData(player, id) || skill;
+			const name = resolveSignal(data?.name) ?? resolveSignal(skill.name) ?? id;
+			const description = resolveSignal(data?.description) ?? resolveSignal(skill.description) ?? "";
+			const icon = resolveSignal(data?.icon) ?? resolveSignal(skill.icon);
+			const spCost = resolveSignal(data?.spCost) ?? resolveSignal(skill.spCost) ?? 0;
+			const usable = spCost <= player.sp;
+			const targeting = resolveSkillTargeting(player, id, options);
+			const skillEntry = {
+				id,
+				name,
+				description,
+				icon,
+				spCost,
+				usable,
+				range: targeting?.range ?? 0
+			};
+			if (targeting) {
+				const mask = targeting.aoeMask ?? options.skills?.defaultAoeMask;
+				if (mask) skillEntry.aoeMask = normalizeMaskRows(mask);
+			}
+			return skillEntry;
+		})
+	};
+};
+var ensureActionBarGui = (player, options) => {
+	const gui = player.getGui?.("action-battle-action-bar") || player.gui("action-battle-action-bar");
+	if (!gui.__actionBattleReady) {
+		gui.__actionBattleReady = true;
+		gui.on("useItem", ({ id }) => {
+			try {
+				player.useItem(id);
+			} catch {}
+			gui.update(buildActionBarData(player, options));
+		});
+		gui.on("useSkill", ({ id, target }) => {
+			handleActionBattleSkillUse(player, id, target, options);
+			gui.update(buildActionBarData(player, options));
+		});
+		gui.on("refresh", () => {
+			gui.update(buildActionBarData(player, options));
+		});
+	}
+	return gui;
+};
+var openActionBattleActionBar = (player, rawOptions = {}) => {
+	const options = normalizeActionBattleOptions(rawOptions);
+	ensureActionBarGui(player, options).open(buildActionBarData(player, options));
+};
+var updateActionBattleActionBar = (player, rawOptions = {}) => {
+	const options = normalizeActionBattleOptions(rawOptions);
+	const gui = player.getGui?.(ACTION_BATTLE_ACTION_BAR_GUI_ID);
+	if (gui) gui.update(buildActionBarData(player, options));
+};
+var getTileSize = (map) => ({
+	width: map?.tileWidth ?? 32,
+	height: map?.tileHeight ?? 32
+});
+var getEntityTile = (entity, tileSize) => {
+	const hitbox = entity.hitbox?.() || {
+		w: tileSize.width,
+		h: tileSize.height
+	};
+	return {
+		x: Math.floor((entity.x() + hitbox.w / 2) / tileSize.width),
+		y: Math.floor((entity.y() + hitbox.h / 2) / tileSize.height)
+	};
+};
+var 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;
+	}
+	const tileSize = getTileSize(map);
+	const origin = getEntityTile(player, tileSize);
+	const targetTile = {
+		x: target.x,
+		y: target.y
+	};
+	if (manhattanDistance(origin, targetTile) > targeting.range) return;
+	const mask = parseAoeMask(targeting.aoeMask || options.skills?.defaultAoeMask);
+	const affected = /* @__PURE__ */ new Set();
+	mask.cells.forEach((cell) => {
+		const x = targetTile.x + cell.dx;
+		const y = targetTile.y + cell.dy;
+		affected.add(`${x},${y}`);
+	});
+	const targets = [];
+	const affects = options.targeting?.affects || "events";
+	if (affects === "events" || affects === "both") map.getEvents().forEach((event) => {
+		const tile = getEntityTile(event, tileSize);
+		if (affected.has(`${tile.x},${tile.y}`)) targets.push(event);
+	});
+	if (affects === "players" || affects === "both") map.getPlayers().forEach((other) => {
+		if (other.id === player.id) return;
+		const tile = getEntityTile(other, tileSize);
+		if (affected.has(`${tile.x},${tile.y}`)) targets.push(other);
+	});
+	if (!options.targeting?.allowEmptyTarget && targets.length === 0) return;
+	playActionBattleAnimation("castSkill", player, options.animations, {
+		skill: skillData,
+		target: targets[0]
+	});
+	player.useSkill(skillId, targets);
+};
+var createActionBattleServer = (rawOptions = {}) => {
+	const options = normalizeActionBattleOptions(rawOptions);
+	setActionBattleOptions(options);
+	return defineModule({
+		player: {
+			/**
+			* Handle player input for combat actions
+			*
+			* When a player presses the action key, create an attack hitbox
+			* that can damage AI enemies within range and knockback the event.
+			* Knockback force is based on the player's equipped weapon.
+			* Triggers attack animation and visual effects.
+			*
+			* @param player - The player performing the action
+			* @param input - Input data containing pressed keys
+			*/
+			onInput(player, input) {
+				if (input.action == Control.Action) {
+					playActionBattleAnimation("attack", player, options.animations);
+					const playerX = player.x();
+					const playerY = player.y();
+					const hitboxConfig = DEFAULT_PLAYER_ATTACK_HITBOXES[player.getDirection()] || DEFAULT_PLAYER_ATTACK_HITBOXES.default;
+					const hitboxes = [{
+						x: playerX + hitboxConfig.offsetX,
+						y: playerY + hitboxConfig.offsetY,
+						width: hitboxConfig.width,
+						height: hitboxConfig.height
+					}];
+					player.getCurrentMap()?.createMovingHitbox(hitboxes, { speed: 3 }).subscribe({ next(hits) {
+						hits.forEach((hit) => {
+							if (hit instanceof RpgEvent) {
+								if (applyPlayerHitToEvent(player, hit)?.defeated) console.log(`Player ${player.id} defeated AI ${hit.id}`);
+							}
+						});
+					} });
+				}
+			},
+			onConnected(player) {
+				if (options.ui?.actionBar?.enabled && options.ui?.actionBar?.autoOpen) openActionBattleActionBar(player, options);
+			}
+		},
+		event: {
+			/**
+			* Handle player detection when entering AI vision
+			*
+			* Called when a player enters an AI event's vision range.
+			* The AI will start pursuing and attacking the player.
+			*
+			* @param event - The AI event
+			* @param player - The player entering vision
+			* @param shape - The vision shape
+			*/
+			onDetectInShape(event, player, shape) {
+				event.battleAi?.onDetectInShape(player, shape);
+			},
+			/**
+			* Handle player leaving AI vision
+			*
+			* Called when a player leaves an AI event's vision range.
+			* The AI will stop pursuing the player.
+			*
+			* @param event - The AI event
+			* @param player - The player leaving vision
+			* @param shape - The vision shape
+			*/
+			onDetectOutShape(event, player, shape) {
+				event.battleAi?.onDetectOutShape(player, shape);
+			}
+		}
+	});
+};
+createActionBattleServer();
+//#endregion
+export { ACTION_BATTLE_ACTION_BAR_GUI_ID, DEFAULT_PLAYER_ATTACK_HITBOXES, applyPlayerHitToEvent, createActionBattleServer, getPlayerWeaponKnockbackForce, openActionBattleActionBar, updateActionBattleActionBar };