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

package/README.md

@@ -260,7 +260,7 @@ new BattleAi(event, {
   groupBehavior: true,
   
   // Callback when AI is defeated
-  onDefeated: (event, attacker) => {
+  onDefeated: ({ event, attacker }) => {
     const name = attacker?.name?.() ?? "Unknown";
     console.log(`${event.name()} was defeated by ${name}!`);
   }
@@ -839,8 +839,9 @@ new BattleAi(this, {
 });
 ```
 
-`waitEnd: true` delays event removal for defeated AI with the default delay used
-by action-battle. Use `delayMs` when you need an exact duration.
+`waitEnd: true` uses the default defeated transition timeout. Use `delayMs`
+when you need an exact duration. The visual transition itself is handled by the
+client `sprite.onBeforeRemove` hook.
 
 ## Knockback System
 
@@ -992,25 +993,57 @@ console.log(`Player knockback force: ${force}`);
 
 ## onDefeated Hook
 
-The `onDefeated` callback is triggered when an AI enemy is killed. It receives the defeated event and the player who landed the killing blow (if available). Use it to:
+The `onDefeated` callback is triggered when an AI enemy is killed. The simplest
+reward flow is configured directly on `BattleAi`; the reward is given to the
+player who landed the killing blow.
+
+```typescript
+new BattleAi(this, {
+  enemyType: EnemyType.Aggressive,
+  animations: {
+    die: {
+      animationName: "die",
+      graphic: "goblin_die",
+      repeat: 1,
+      delayMs: 700
+    }
+  },
+  rewards: {
+    exp: 50,
+    gold: 25,
+    items: [{ itemId: "health_potion", amount: 1, chance: 30 }],
+    showNotification: true
+  }
+});
+```
+
+On defeat, `BattleAi` stops the AI, awards configured rewards once, and calls
+`event.remove({ reason: "defeated", transition })`. The client can use
+`sprite.onBeforeRemove` to play the `die` transition before the sprite
+disappears.
+
+`onDefeated` receives a context object in new code:
 - Award experience, gold, or items to the player
 - Spawn loot drops
 - Trigger events or cutscenes
 - Update quest progress
-- Play death animations or sounds
+- Play death sounds
 
 ### Basic Usage
 
 ```typescript
 new BattleAi(this, {
   enemyType: EnemyType.Aggressive,
-  onDefeated: (event, attacker) => {
+  onDefeated: ({ event, attacker }) => {
     const name = attacker?.name?.() ?? "Unknown";
     console.log(`${event.name()} was defeated by ${name}!`);
   }
 });
 ```
 
+The legacy `(event, attacker)` callback signature is still supported for
+two-argument callbacks.
+
 ### Award Rewards on Kill
 
 ```typescript
@@ -1025,19 +1058,10 @@ function Goblin() {
       
       new BattleAi(this, {
         enemyType: EnemyType.Aggressive,
-        onDefeated: (event, attacker) => {
-          if (!attacker) return;
-
-          // Award gold
-          attacker.gold += 25;
-          
-          // Award experience
-          attacker.exp += 50;
-          
-          // Random loot drop
-          if (Math.random() < 0.3) {
-            attacker.addItem(HealthPotion);
-          }
+        rewards: {
+          gold: 25,
+          exp: 50,
+          items: [{ item: HealthPotion, amount: 1, chance: 30 }]
         }
       });
     }
@@ -1049,7 +1073,7 @@ function Goblin() {
 
 ```typescript
 new BattleAi(this, {
-  onDefeated: (event, attacker) => {
+  onDefeated: ({ event }) => {
     const map = event.getCurrentMap();
     if (!map) return;
     
@@ -1069,7 +1093,7 @@ new BattleAi(this, {
 let killCount = 0;
 
 new BattleAi(this, {
-  onDefeated: (event, attacker) => {
+  onDefeated: () => {
     killCount++;
     
     // Check quest progress
@@ -1093,7 +1117,7 @@ function DragonBoss() {
       
       new BattleAi(this, {
         enemyType: EnemyType.Tank,
-        onDefeated: (event, attacker) => {
+        onDefeated: ({ event }) => {
           const map = event.getCurrentMap();
           
           // Announce victory

package/dist/ai.server.d.ts

@@ -5,7 +5,31 @@ import { NormalizedActionBattleHitReactionProfile, ActionBattleAnimationOptions
 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;
@@ -35,8 +59,16 @@ 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;
 }
 /**
  * Hit result data returned after applying damage
@@ -272,6 +304,9 @@ export declare class BattleAi {
     private damageCheckInterval;
     private isMovingToTarget;
     private onDefeatedCallback?;
+    private rewards?;
+    private autoAwardRewards;
+    private defeated;
     private lastFacingDirection;
     private behaviorScore;
     private behaviorMode;
@@ -315,6 +350,7 @@ export declare class BattleAi {
      * ```
      */
     constructor(event: RpgEventWithBattleAi, options?: BattleAiOptions);
+    constructor(event: RpgEventWithBattleAi, options?: BattleAiLegacyOptions);
     /**
      * Apply enemy type-specific behavior modifiers
      *

package/dist/client/index16.js

@@ -1,12 +1,65 @@
 import { isActionBattleEntityInvincible, setActionBattleInvincibility } from "./index2.js";
 import { getActionBattleOptions } from "./index4.js";
-import { getActionBattleAnimationRemovalDelay, playActionBattleAnimation } from "./index10.js";
+import { getActionBattleAnimationRemovalDelay, playActionBattleAnimation, resolveActionBattleAnimation } from "./index10.js";
 import { resolveActionBattleHitboxSpeed, scheduleActionBattleStartup } from "./index11.js";
 import { getActionBattleSystems } from "./index14.js";
 import { normalizeActionBattleEnemyAttackProfiles } from "./index15.js";
 //#region src/ai.server.ts
 var MAXHP = null;
 var RpgPlayer = null;
+var normalizeRewardItem = (item) => {
+	if (typeof item === "string") return {
+		itemId: item,
+		amount: 1,
+		chance: 100
+	};
+	return {
+		...item,
+		amount: item.amount ?? 1,
+		chance: item.chance ?? 100
+	};
+};
+var getRewardItemRef = (item) => item.item ?? item.itemId;
+var getPlayerMap = (player) => {
+	return typeof player.getCurrentMap === "function" ? player.getCurrentMap() : void 0;
+};
+var getRewardItemName = (inventoryItem, itemRef) => {
+	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";
+};
+var createDefeatReward = (rewards) => {
+	let awarded = false;
+	return {
+		get awarded() {
+			return awarded;
+		},
+		giveTo(player) {
+			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] : void 0;
+					player.showNotification(`You won ${amount} ${getRewardItemName(inventoryItem, itemRef)}`, { icon: itemData?.icon });
+				}
+			}
+		}
+	};
+};
 /**
 * AI Debug Logger
 * 
@@ -178,6 +231,9 @@ var BattleAi = class {
 	damageCheckInterval = 2e3;
 	isMovingToTarget = false;
 	onDefeatedCallback;
+	rewards;
+	autoAwardRewards = true;
+	defeated = false;
 	lastFacingDirection = null;
 	behaviorScore = 50;
 	behaviorMode = "tactical";
@@ -196,30 +252,6 @@ var BattleAi = class {
 	poise = 0;
 	hitstunMs = 150;
 	invincibilityMs = 250;
-	/**
-	* Create a new Battle AI Controller
-	*
-	* The AI controls behavior only. Stats should be set on the event
-	* using standard RPGJS methods (hp, param, learnSkill, etc.)
-	*
-	* @param event - The event to control
-	* @param options - AI behavior configuration
-	*
-	* @example
-	* ```ts
-	* // In your event's onInit
-	* this.hp = 100;
-	* this.param[ATK] = 20;
-	* this.learnSkill(FireBall);
-	* 
-	* new BattleAi(this, {
-	*   enemyType: EnemyType.Ranged,
-	*   attackSkill: FireBall,
-	*   visionRange: 200,
-	*   fleeThreshold: 0.2
-	* });
-	* ```
-	*/
 	constructor(event, options = {}) {
 		event.battleAi = this;
 		this.event = event;
@@ -241,6 +273,8 @@ var BattleAi = class {
 		this.patrolWaypoints = options.patrolWaypoints || [];
 		this.currentPatrolIndex = 0;
 		this.onDefeatedCallback = options.onDefeated;
+		this.rewards = options.rewards;
+		this.autoAwardRewards = options.autoAwardRewards ?? true;
 		if (options.behavior) {
 			this.behaviorEnabled = true;
 			if (options.behavior.baseScore !== void 0) this.behaviorScore = options.behavior.baseScore;
@@ -1080,6 +1114,7 @@ var BattleAi = class {
 	* The actual damage is applied externally via RPGJS API.
 	*/
 	takeDamage(attacker) {
+		if (this.defeated) return true;
 		const raw = this.event.applyDamage(attacker);
 		return this.handleDamage(attacker, {
 			damage: raw.damage ?? 0,
@@ -1088,6 +1123,7 @@ var BattleAi = class {
 		});
 	}
 	handleDamage(attacker, damageResult) {
+		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] || "?"})`);
 		this.event.flash({
@@ -1124,11 +1160,37 @@ var BattleAi = class {
 	* and removes the event from the map.
 	*/
 	kill(attacker) {
-		const removeDelay = getActionBattleAnimationRemovalDelay(playActionBattleAnimation("die", this.event, this.animations, { attacker }));
-		if (this.onDefeatedCallback) this.onDefeatedCallback(this.event, attacker);
+		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
+				} : void 0,
+				timeoutMs: removeDelay
+			});
+		};
+		if (this.autoAwardRewards) reward.giveTo(attacker);
+		const context = {
+			event: this.event,
+			attacker,
+			reward,
+			remove
+		};
+		if (this.onDefeatedCallback) if (this.onDefeatedCallback.length >= 2) this.onDefeatedCallback(this.event, attacker);
+		else this.onDefeatedCallback(context);
 		this.destroy();
-		if (removeDelay > 0) this.schedule(() => this.event.remove(), removeDelay);
-		else this.event.remove();
+		remove();
 	}
 	/**
 	* Get distance between entities

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ActionBattleOptions } from './types';
 export { BattleAi, AiState, EnemyType, AttackPattern, AiDebug, DEFAULT_KNOCKBACK } from './ai.server';
-export type { HitResult, ApplyHitHooks, BattleAiOptions } from './ai.server';
+export type { HitResult, ApplyHitHooks, BattleAiOptions, BattleAiDefeatedCallback, BattleAiDefeatedContext, BattleAiDefeatReward, BattleAiLegacyDefeatedCallback, BattleAiLegacyOptions, BattleAiRewardItem, BattleAiRewards, } from './ai.server';
 export type { ActionBattleAnimationContext, ActionBattleAnimationEntity, ActionBattleAnimationKey, ActionBattleAnimationOptions, ActionBattleAnimationResolver, ActionBattleAnimationResult, ActionBattleOptions, ActionBattleActionBarData, ActionBattleActionBarItem, ActionBattleActionBarSkill, ActionBattleSkillTargeting, ActionBattleSkillTargetingResolver, ActionBattleAttackOptions, ActionBattleUiOptions, ActionBattleUiActionBarOptions, ActionBattleUiTargetingOptions, ActionBattleAttackDirection, ActionBattleAttackHitboxConfig, ActionBattleAttackHitboxMap, ActionBattleAttackHitPolicy, ActionBattleAttackProfile, ActionBattleDebugOptions, ActionBattleHitReactionProfile, NormalizedActionBattleHitReactionProfile, NormalizedActionBattleAttackProfile, ActionBattleCombatOptions, ActionBattleSystemOptions, ActionBattleAiSystemOptions, } from './types';
 export type { ActionBattleAiBehavior, ActionBattleAiContext, ActionBattleAiDecision, ActionBattleAttackContext, ActionBattleCombatSystem, ActionBattleDamageContext, ActionBattleDamageResult, ActionBattleDirection, ActionBattleEntity, ActionBattleHitContext, ActionBattleHitHooks, ActionBattleHitResult, ActionBattleHitbox, ActionBattleKnockbackContext, ActionBattleKnockbackResult, ActionBattleSystems, } from './core/contracts';
 export { DEFAULT_ACTION_BATTLE_ATTACK_PROFILE, normalizeActionBattleAttackProfile, type ActionBattleAttackProfileFallbacks, } from './core/attack-profile';

package/dist/server/index10.js

@@ -1,4 +1,4 @@
-import { getActionBattleAnimationRemovalDelay, playActionBattleAnimation } from "./index2.js";
+import { getActionBattleAnimationRemovalDelay, playActionBattleAnimation, resolveActionBattleAnimation } from "./index2.js";
 import { isActionBattleEntityInvincible, setActionBattleInvincibility } from "./index3.js";
 import { getActionBattleOptions } from "./index5.js";
 import { getActionBattleSystems } from "./index7.js";
@@ -6,6 +6,59 @@ import { normalizeActionBattleEnemyAttackProfiles } from "./index8.js";
 import { resolveActionBattleHitboxSpeed, scheduleActionBattleStartup } from "./index9.js";
 import { MAXHP, RpgPlayer } from "@rpgjs/server";
 //#region src/ai.server.ts
+var normalizeRewardItem = (item) => {
+	if (typeof item === "string") return {
+		itemId: item,
+		amount: 1,
+		chance: 100
+	};
+	return {
+		...item,
+		amount: item.amount ?? 1,
+		chance: item.chance ?? 100
+	};
+};
+var getRewardItemRef = (item) => item.item ?? item.itemId;
+var getPlayerMap = (player) => {
+	return typeof player.getCurrentMap === "function" ? player.getCurrentMap() : void 0;
+};
+var getRewardItemName = (inventoryItem, itemRef) => {
+	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";
+};
+var createDefeatReward = (rewards) => {
+	let awarded = false;
+	return {
+		get awarded() {
+			return awarded;
+		},
+		giveTo(player) {
+			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] : void 0;
+					player.showNotification(`You won ${amount} ${getRewardItemName(inventoryItem, itemRef)}`, { icon: itemData?.icon });
+				}
+			}
+		}
+	};
+};
 /**
 * AI Debug Logger
 * 
@@ -177,6 +230,9 @@ var BattleAi = class {
 	damageCheckInterval = 2e3;
 	isMovingToTarget = false;
 	onDefeatedCallback;
+	rewards;
+	autoAwardRewards = true;
+	defeated = false;
 	lastFacingDirection = null;
 	behaviorScore = 50;
 	behaviorMode = "tactical";
@@ -195,30 +251,6 @@ var BattleAi = class {
 	poise = 0;
 	hitstunMs = 150;
 	invincibilityMs = 250;
-	/**
-	* Create a new Battle AI Controller
-	*
-	* The AI controls behavior only. Stats should be set on the event
-	* using standard RPGJS methods (hp, param, learnSkill, etc.)
-	*
-	* @param event - The event to control
-	* @param options - AI behavior configuration
-	*
-	* @example
-	* ```ts
-	* // In your event's onInit
-	* this.hp = 100;
-	* this.param[ATK] = 20;
-	* this.learnSkill(FireBall);
-	* 
-	* new BattleAi(this, {
-	*   enemyType: EnemyType.Ranged,
-	*   attackSkill: FireBall,
-	*   visionRange: 200,
-	*   fleeThreshold: 0.2
-	* });
-	* ```
-	*/
 	constructor(event, options = {}) {
 		event.battleAi = this;
 		this.event = event;
@@ -240,6 +272,8 @@ var BattleAi = class {
 		this.patrolWaypoints = options.patrolWaypoints || [];
 		this.currentPatrolIndex = 0;
 		this.onDefeatedCallback = options.onDefeated;
+		this.rewards = options.rewards;
+		this.autoAwardRewards = options.autoAwardRewards ?? true;
 		if (options.behavior) {
 			this.behaviorEnabled = true;
 			if (options.behavior.baseScore !== void 0) this.behaviorScore = options.behavior.baseScore;
@@ -1079,6 +1113,7 @@ var BattleAi = class {
 	* The actual damage is applied externally via RPGJS API.
 	*/
 	takeDamage(attacker) {
+		if (this.defeated) return true;
 		const raw = this.event.applyDamage(attacker);
 		return this.handleDamage(attacker, {
 			damage: raw.damage ?? 0,
@@ -1087,6 +1122,7 @@ var BattleAi = class {
 		});
 	}
 	handleDamage(attacker, damageResult) {
+		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] || "?"})`);
 		this.event.flash({
@@ -1123,11 +1159,37 @@ var BattleAi = class {
 	* and removes the event from the map.
 	*/
 	kill(attacker) {
-		const removeDelay = getActionBattleAnimationRemovalDelay(playActionBattleAnimation("die", this.event, this.animations, { attacker }));
-		if (this.onDefeatedCallback) this.onDefeatedCallback(this.event, attacker);
+		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
+				} : void 0,
+				timeoutMs: removeDelay
+			});
+		};
+		if (this.autoAwardRewards) reward.giveTo(attacker);
+		const context = {
+			event: this.event,
+			attacker,
+			reward,
+			remove
+		};
+		if (this.onDefeatedCallback) if (this.onDefeatedCallback.length >= 2) this.onDefeatedCallback(this.event, attacker);
+		else this.onDefeatedCallback(context);
 		this.destroy();
-		if (removeDelay > 0) this.schedule(() => this.event.remove(), removeDelay);
-		else this.event.remove();
+		remove();
 	}
 	/**
 	* Get distance between entities

package/dist/server/index2.js

@@ -58,4 +58,4 @@ function getActionBattleAnimationRemovalDelay(animation) {
 	return animation.waitEnd ? 500 : 0;
 }
 //#endregion
-export { getActionBattleAnimationRemovalDelay, playActionBattleAnimation };
+export { getActionBattleAnimationRemovalDelay, playActionBattleAnimation, resolveActionBattleAnimation };

package/dist/server.d.ts

@@ -103,4 +103,4 @@ export { DEFAULT_ACTION_BATTLE_HIT_REACTION, isActionBattleEntityInvincible, nor
 export { DEFAULT_ACTION_BATTLE_ENEMY_ATTACK_PROFILES, normalizeActionBattleEnemyAttackProfiles, type ActionBattleEnemyAttackProfileKey, type ActionBattleEnemyAttackProfileMap, type NormalizedActionBattleEnemyAttackProfileMap, } from './core/enemy-attack-profiles';
 export { resolveActionBattleWeaponAttackProfile } from './core/equipment';
 export { AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_KNOCKBACK, EnemyType, } from './ai.server';
-export type { ApplyHitHooks, BattleAiOptions, HitResult } from './ai.server';
+export type { ApplyHitHooks, BattleAiDefeatedCallback, BattleAiDefeatedContext, BattleAiDefeatReward, BattleAiLegacyDefeatedCallback, BattleAiLegacyOptions, BattleAiOptions, BattleAiRewardItem, BattleAiRewards, HitResult, } from './ai.server';

package/dist/ui/state.d.ts

@@ -18,10 +18,10 @@ export interface ActionBattleTargetingState {
     };
     aoeMask: string[] | string;
 }
-export declare const actionBattleUiOptions: import('canvasengine').WritableObjectSignal<import('..').ActionBattleUiOptions>;
-export declare const actionBattleSkillOptions: import('canvasengine').WritableObjectSignal<import('../types').ActionBattleSkillOptions>;
-export declare const actionBattleTargetingState: import('canvasengine').WritableObjectSignal<ActionBattleTargetingState>;
-export declare const actionBattleAttackPreviewState: import('canvasengine').WritableObjectSignal<ActionBattleAttackPreviewState>;
+export declare const actionBattleUiOptions: any;
+export declare const actionBattleSkillOptions: any;
+export declare const actionBattleTargetingState: any;
+export declare const actionBattleAttackPreviewState: any;
 export declare const setActionBattleOptions: (options?: ActionBattleOptions) => void;
 export declare const startTargeting: (skill: ActionBattleActionBarSkill) => void;
 export declare const stopTargeting: () => void;
@@ -31,5 +31,5 @@ export declare const startAttackPreview: (options: {
     durationMs?: number;
     color?: number;
     accentColor?: number;
-}) => number;
+}) => any;
 export declare const stopAttackPreview: (id?: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpgjs/action-battle",
-  "version": "5.0.0-beta.6",
+  "version": "5.0.0-beta.7",
   "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-beta.6",
-    "@rpgjs/common": "5.0.0-beta.6",
-    "@rpgjs/server": "5.0.0-beta.6",
-    "@rpgjs/vite": "5.0.0-beta.6",
+    "@rpgjs/client": "5.0.0-beta.7",
+    "@rpgjs/common": "5.0.0-beta.7",
+    "@rpgjs/server": "5.0.0-beta.7",
+    "@rpgjs/vite": "5.0.0-beta.7",
     "canvasengine": "*"
   },
   "publishConfig": {

package/src/ai.server.spec.ts

@@ -0,0 +1,120 @@
+import { MAXHP } from "@rpgjs/server";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { BattleAi } from "./ai.server";
+
+const createEvent = () => ({
+  id: "monster-1",
+  hp: 0,
+  param: {
+    [MAXHP]: 10,
+  },
+  attachShape: vi.fn(),
+  flash: vi.fn(),
+  showHit: vi.fn(),
+  setGraphicAnimation: vi.fn(),
+  stopMoveTo: vi.fn(),
+  getCurrentMap: vi.fn(() => ({})),
+  remove: vi.fn(),
+  x: vi.fn(() => 0),
+  y: vi.fn(() => 0),
+  direction: vi.fn(() => "down"),
+});
+
+const createPlayer = () => ({
+  id: "player-1",
+  exp: 0,
+  gold: 0,
+  addItem: vi.fn(() => ({ name: () => "Potion" })),
+  showNotification: vi.fn(),
+  getCurrentMap: vi.fn(() => ({
+    database: () => ({
+      potion: { icon: "potion-icon" },
+    }),
+  })),
+});
+
+describe("BattleAi defeat flow", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  test("awards the attacker and requests a defeated remove transition", () => {
+    const event = createEvent();
+    const attacker = createPlayer();
+    const ai = new BattleAi(event as any, {
+      animations: {
+        die: {
+          animationName: "die",
+          repeat: 1,
+          delayMs: 700,
+        },
+      },
+      rewards: {
+        exp: 25,
+        gold: 7,
+        items: [{ itemId: "potion", amount: 2, chance: 100 }],
+        showNotification: true,
+      },
+    });
+
+    expect(ai.handleDamage(attacker as any, { damage: 10, defeated: true })).toBe(true);
+
+    expect(attacker.exp).toBe(25);
+    expect(attacker.gold).toBe(7);
+    expect(attacker.addItem).toHaveBeenCalledWith("potion", 2);
+    expect(event.setGraphicAnimation).not.toHaveBeenCalledWith("die", 1);
+    expect(event.remove).toHaveBeenCalledWith({
+      reason: "defeated",
+      data: {
+        animation: expect.objectContaining({
+          animationName: "die",
+          delayMs: 700,
+        }),
+      },
+      transition: {
+        animation: "die",
+        graphic: undefined,
+        duration: 700,
+      },
+      timeoutMs: 700,
+    });
+  });
+
+  test("supports the context onDefeated callback and manual reward control", () => {
+    const event = createEvent();
+    const attacker = createPlayer();
+    const onDefeated = vi.fn(({ reward }) => {
+      expect(reward.awarded).toBe(false);
+      reward.giveTo(attacker as any);
+      expect(reward.awarded).toBe(true);
+    });
+    const ai = new BattleAi(event as any, {
+      autoAwardRewards: false,
+      rewards: {
+        exp: 10,
+      },
+      onDefeated,
+    });
+
+    ai.handleDamage(attacker as any, { damage: 10, defeated: true });
+
+    expect(onDefeated).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event,
+        attacker,
+        reward: expect.any(Object),
+        remove: expect.any(Function),
+      })
+    );
+    expect(attacker.exp).toBe(10);
+    expect(event.remove).toHaveBeenCalledWith({
+      reason: "defeated",
+      data: {
+        animation: null,
+      },
+      transition: undefined,
+      timeoutMs: 0,
+    });
+  });
+});

package/src/ai.server.ts

@@ -2,6 +2,7 @@ import { MAXHP, RpgEvent, RpgPlayer } from "@rpgjs/server";
 import {
   getActionBattleAnimationRemovalDelay,
   playActionBattleAnimation,
+  resolveActionBattleAnimation,
 } from "./animations";
 import { getActionBattleOptions } from "./config";
 import { getActionBattleSystems } from "./core/context";
@@ -29,7 +30,42 @@ 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;
@@ -56,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;
 }
 
 /**
@@ -94,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
  * 
@@ -340,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;
@@ -390,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;
@@ -428,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) {
@@ -1593,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, {
@@ -1608,6 +1742,7 @@ export class BattleAi {
       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] || '?'})`);
 
@@ -1660,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,
@@ -1669,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();
   }
 
   /**

package/src/index.ts

@@ -7,7 +7,18 @@ import type { ActionBattleOptions } from "./types";
 export { BattleAi, AiState, EnemyType, AttackPattern, AiDebug, DEFAULT_KNOCKBACK } from "./ai.server";
 
 // Types exports
-export type { HitResult, ApplyHitHooks, BattleAiOptions } from "./ai.server";
+export type {
+  HitResult,
+  ApplyHitHooks,
+  BattleAiOptions,
+  BattleAiDefeatedCallback,
+  BattleAiDefeatedContext,
+  BattleAiDefeatReward,
+  BattleAiLegacyDefeatedCallback,
+  BattleAiLegacyOptions,
+  BattleAiRewardItem,
+  BattleAiRewards,
+} from "./ai.server";
 export type {
   ActionBattleAnimationContext,
   ActionBattleAnimationEntity,

package/src/server.ts

@@ -817,4 +817,15 @@ export {
   DEFAULT_KNOCKBACK,
   EnemyType,
 } from "./ai.server";
-export type { ApplyHitHooks, BattleAiOptions, HitResult } from "./ai.server";
+export type {
+  ApplyHitHooks,
+  BattleAiDefeatedCallback,
+  BattleAiDefeatedContext,
+  BattleAiDefeatReward,
+  BattleAiLegacyDefeatedCallback,
+  BattleAiLegacyOptions,
+  BattleAiOptions,
+  BattleAiRewardItem,
+  BattleAiRewards,
+  HitResult,
+} from "./ai.server";