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

package/dist/client/index16.js

@@ -0,0 +1,1281 @@
+import { isActionBattleEntityInvincible, setActionBattleInvincibility } from "./index2.js";
+import { getActionBattleOptions } from "./index4.js";
+import { getActionBattleAnimationRemovalDelay, playActionBattleAnimation } 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;
+/**
+* AI Debug Logger
+* 
+* Conditional logging utility for AI behavior debugging.
+* Enable by setting `AiDebug.enabled = true` or via environment variable `RPGJS_DEBUG_AI=1`
+* 
+* @example
+* ```ts
+* // Enable debug logging
+* AiDebug.enabled = true;
+* 
+* // Or filter by event ID
+* AiDebug.filterEventId = 'goblin-1';
+* ```
+*/
+var AiDebug = {
+	/** Enable/disable all AI debug logs */
+	enabled: globalThis.process?.env?.RPGJS_DEBUG_AI === "1" || false,
+	/** Filter logs to a specific event ID (null = all events) */
+	filterEventId: null,
+	/** Log categories to enable (empty = all) */
+	categories: [],
+	/**
+	* Log an AI debug message
+	* 
+	* @param category - Log category (e.g., 'state', 'attack', 'movement', 'damage')
+	* @param eventId - Event ID for filtering
+	* @param message - Log message
+	* @param data - Optional additional data
+	*/
+	log(category, eventId, message, data) {
+		if (!this.enabled) return;
+		if (this.filterEventId && eventId !== this.filterEventId) return;
+		if (this.categories.length > 0 && !this.categories.includes(category)) return;
+		const prefix = `[AI:${category}]${eventId ? ` [${eventId.substring(0, 8)}]` : ""}`;
+		if (data !== void 0) console.log(prefix, message, data);
+		else console.log(prefix, message);
+	}
+};
+/**
+* AI State enumeration
+* 
+* Defines the different states an AI can be in, each with its own behavior.
+*/
+var AiState = /* @__PURE__ */ function(AiState) {
+	AiState["Idle"] = "idle";
+	AiState["Alert"] = "alert";
+	AiState["Combat"] = "combat";
+	AiState["Flee"] = "flee";
+	AiState["Stunned"] = "stunned";
+	return AiState;
+}({});
+/**
+* Enemy Type enumeration
+* 
+* Defines different enemy archetypes with unique behaviors.
+* Stats (HP, ATK, etc.) should be set on the event itself via onInit.
+*/
+var EnemyType = /* @__PURE__ */ function(EnemyType) {
+	EnemyType["Aggressive"] = "aggressive";
+	EnemyType["Defensive"] = "defensive";
+	EnemyType["Ranged"] = "ranged";
+	EnemyType["Tank"] = "tank";
+	EnemyType["Berserker"] = "berserker";
+	return EnemyType;
+}({});
+/**
+* Attack Pattern enumeration
+* 
+* Different attack patterns the AI can use.
+*/
+var AttackPattern = /* @__PURE__ */ function(AttackPattern) {
+	AttackPattern["Melee"] = "melee";
+	AttackPattern["Combo"] = "combo";
+	AttackPattern["Charged"] = "charged";
+	AttackPattern["Zone"] = "zone";
+	AttackPattern["DashAttack"] = "dashAttack";
+	return AttackPattern;
+}({});
+/**
+* Default knockback configuration
+* 
+* Used when no weapon is equipped or weapon doesn't specify knockback.
+*/
+var DEFAULT_KNOCKBACK = {
+	/** Default knockback force */
+	force: 50,
+	/** Default knockback duration in milliseconds */
+	duration: 300
+};
+/**
+* Advanced Battle AI Controller for events
+*
+* This class provides intelligent combat behavior control for events.
+* It uses the existing RPGJS API for stats, skills, items, etc.
+* The AI only manages behavior - the event's stats should be configured
+* in onInit using standard RPGJS methods.
+*
+* ## Usage with RPGJS API
+* 
+* Configure the event stats using standard RPGJS methods:
+* - `this.hp = 100` - Set health
+* - `this.learnSkill(FireBall)` - Learn a skill
+* - `this.addItem(Potion, 3)` - Add items
+* - `this.equip(Sword)` - Equip items
+* - `this.setClass(WarriorClass)` - Set class
+* - `this.param[ATK] = 20` - Set parameters
+*
+* @example
+* ```ts
+* function GoblinEnemy() {
+*   return {
+*     name: "Goblin",
+*     onInit() {
+*       this.setGraphic("goblin");
+*       
+*       // Configure stats using RPGJS API
+*       this.hp = 80;
+*       this.param[ATK] = 15;
+*       this.param[PDEF] = 5;
+*       this.learnSkill(Slash);
+*       
+*       // Apply AI behavior
+*       new BattleAi(this, {
+*         enemyType: EnemyType.Aggressive,
+*         attackSkill: Slash
+*       });
+*     }
+*   };
+* }
+* ```
+*/
+var BattleAi = class {
+	event;
+	target = null;
+	lastAttackTime = 0;
+	updateInterval;
+	/**
+	* Log AI debug message for this event
+	*/
+	debugLog(category, message, data) {
+		AiDebug.log(category, this.event.id, message, data);
+	}
+	state = AiState.Idle;
+	stateStartTime = 0;
+	stunnedUntil = 0;
+	enemyType;
+	attackCooldown = 1e3;
+	visionRange = 150;
+	attackRange = 60;
+	dodgeChance = .2;
+	dodgeCooldown = 2e3;
+	lastDodgeTime = 0;
+	fleeThreshold = .2;
+	attackSkill;
+	attackPatterns;
+	attackProfiles;
+	animations;
+	comboCount = 0;
+	comboMax = 3;
+	chargingAttack = false;
+	groupBehavior;
+	nearbyEnemies = [];
+	groupUpdateInterval = 0;
+	patrolWaypoints = [];
+	currentPatrolIndex = 0;
+	lastHpCheck = 0;
+	recentDamageTaken = 0;
+	damageCheckInterval = 2e3;
+	isMovingToTarget = false;
+	onDefeatedCallback;
+	lastFacingDirection = null;
+	behaviorScore = 50;
+	behaviorMode = "tactical";
+	behaviorLastUpdate = 0;
+	behaviorUpdateInterval = 400;
+	behaviorAssaultThreshold = 65;
+	behaviorRetreatThreshold = 35;
+	behaviorMinStateDuration = 600;
+	behaviorEnabled = false;
+	moveToCooldown = 400;
+	lastMoveToTime = 0;
+	retreatCooldown = 600;
+	lastRetreatTime = 0;
+	timers = [];
+	behaviorKey;
+	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;
+		this.enemyType = options.enemyType || EnemyType.Aggressive;
+		this.behaviorKey = options.behaviorKey ?? this.enemyType;
+		this.applyEnemyTypeBehavior(options);
+		this.attackSkill = options.attackSkill || null;
+		this.animations = {
+			...getActionBattleOptions().animations,
+			...options.animations
+		};
+		this.attackPatterns = options.attackPatterns || [
+			AttackPattern.Melee,
+			AttackPattern.Combo,
+			AttackPattern.DashAttack
+		];
+		this.attackProfiles = normalizeActionBattleEnemyAttackProfiles(options.attackProfiles);
+		this.groupBehavior = options.groupBehavior || false;
+		this.patrolWaypoints = options.patrolWaypoints || [];
+		this.currentPatrolIndex = 0;
+		this.onDefeatedCallback = options.onDefeated;
+		if (options.behavior) {
+			this.behaviorEnabled = true;
+			if (options.behavior.baseScore !== void 0) this.behaviorScore = options.behavior.baseScore;
+			if (options.behavior.updateInterval !== void 0) this.behaviorUpdateInterval = options.behavior.updateInterval;
+			if (options.behavior.minStateDuration !== void 0) this.behaviorMinStateDuration = options.behavior.minStateDuration;
+			if (options.behavior.assaultThreshold !== void 0) this.behaviorAssaultThreshold = options.behavior.assaultThreshold;
+			if (options.behavior.retreatThreshold !== void 0) this.behaviorRetreatThreshold = options.behavior.retreatThreshold;
+		}
+		if (options.moveToCooldown !== void 0) this.moveToCooldown = options.moveToCooldown;
+		if (options.retreatCooldown !== void 0) this.retreatCooldown = options.retreatCooldown;
+		if (options.poise !== void 0) this.poise = Math.max(0, options.poise);
+		if (options.hitstunMs !== void 0) this.hitstunMs = Math.max(0, options.hitstunMs);
+		if (options.invincibilityMs !== void 0) this.invincibilityMs = Math.max(0, options.invincibilityMs);
+		this.setupVision();
+		this.startAiBehaviorLoop();
+		if (this.patrolWaypoints.length > 0) this.startPatrol();
+		this.debugLog("init", `AI created (type=${this.enemyType}, visionRange=${this.visionRange}, attackRange=${this.attackRange})`);
+	}
+	/**
+	* Apply enemy type-specific behavior modifiers
+	* 
+	* This only affects AI behavior (cooldowns, ranges, dodge).
+	* Stats should be set on the event itself.
+	*/
+	applyEnemyTypeBehavior(options) {
+		switch (this.enemyType) {
+			case EnemyType.Aggressive:
+				this.attackCooldown = options.attackCooldown ?? 600;
+				this.visionRange = options.visionRange ?? 150;
+				this.attackRange = options.attackRange ?? 50;
+				this.dodgeChance = options.dodgeChance ?? .1;
+				this.dodgeCooldown = options.dodgeCooldown ?? 3e3;
+				this.fleeThreshold = options.fleeThreshold ?? .15;
+				break;
+			case EnemyType.Defensive:
+				this.attackCooldown = options.attackCooldown ?? 1500;
+				this.visionRange = options.visionRange ?? 120;
+				this.attackRange = options.attackRange ?? 60;
+				this.dodgeChance = options.dodgeChance ?? .5;
+				this.dodgeCooldown = options.dodgeCooldown ?? 1500;
+				this.fleeThreshold = options.fleeThreshold ?? .3;
+				break;
+			case EnemyType.Ranged:
+				this.attackCooldown = options.attackCooldown ?? 1200;
+				this.visionRange = options.visionRange ?? 200;
+				this.attackRange = options.attackRange ?? 120;
+				this.dodgeChance = options.dodgeChance ?? .4;
+				this.dodgeCooldown = options.dodgeCooldown ?? 2e3;
+				this.fleeThreshold = options.fleeThreshold ?? .25;
+				break;
+			case EnemyType.Tank:
+				this.attackCooldown = options.attackCooldown ?? 2e3;
+				this.visionRange = options.visionRange ?? 100;
+				this.attackRange = options.attackRange ?? 50;
+				this.dodgeChance = 0;
+				this.dodgeCooldown = options.dodgeCooldown ?? 5e3;
+				this.fleeThreshold = options.fleeThreshold ?? .1;
+				break;
+			case EnemyType.Berserker:
+				this.attackCooldown = options.attackCooldown ?? 800;
+				this.visionRange = options.visionRange ?? 180;
+				this.attackRange = options.attackRange ?? 55;
+				this.dodgeChance = options.dodgeChance ?? .15;
+				this.dodgeCooldown = options.dodgeCooldown ?? 2500;
+				this.fleeThreshold = options.fleeThreshold ?? .05;
+				break;
+			default:
+				this.attackCooldown = options.attackCooldown ?? 1e3;
+				this.visionRange = options.visionRange ?? 150;
+				this.attackRange = options.attackRange ?? 60;
+				this.dodgeChance = options.dodgeChance ?? .2;
+				this.dodgeCooldown = options.dodgeCooldown ?? 2e3;
+				this.fleeThreshold = options.fleeThreshold ?? .2;
+		}
+	}
+	/**
+	* Setup vision detection
+	*/
+	setupVision() {
+		const diameter = this.visionRange * 2;
+		this.event.attachShape(`vision_${this.event.id}`, {
+			radius: this.visionRange,
+			width: diameter,
+			height: diameter,
+			angle: 360
+		});
+	}
+	/**
+	* Start the AI behavior loop
+	*/
+	startAiBehaviorLoop() {
+		const updateInterval = setInterval(() => {
+			if (!this.event.getCurrentMap()) {
+				this.destroy();
+				return;
+			}
+			this.updateAiBehavior();
+		}, 100);
+		this.updateInterval = updateInterval;
+	}
+	/**
+	* Change AI state with validated transitions
+	*/
+	changeState(newState) {
+		if (newState === this.state) return;
+		if (!{
+			[AiState.Idle]: [AiState.Alert, AiState.Combat],
+			[AiState.Alert]: [AiState.Idle, AiState.Combat],
+			[AiState.Combat]: [
+				AiState.Idle,
+				AiState.Flee,
+				AiState.Stunned
+			],
+			[AiState.Flee]: [AiState.Idle, AiState.Combat],
+			[AiState.Stunned]: [AiState.Combat, AiState.Idle]
+		}[this.state].includes(newState)) {
+			this.debugLog("state", `INVALID transition ${this.state} -> ${newState}`);
+			return;
+		}
+		this.debugLog("state", `STATE change: ${this.state} -> ${newState}`);
+		this.state = newState;
+		this.stateStartTime = Date.now();
+		switch (newState) {
+			case AiState.Idle:
+				if (this.patrolWaypoints.length > 0) this.startPatrol();
+				break;
+			case AiState.Alert:
+				this.event.stopMoveTo();
+				break;
+			case AiState.Combat:
+				this.comboCount = 0;
+				break;
+			case AiState.Flee:
+				if (this.target) this.fleeFromTarget();
+				break;
+			case AiState.Stunned:
+				this.event.stopMoveTo();
+				break;
+		}
+	}
+	/**
+	* Main AI behavior update loop
+	*/
+	updateAiBehavior() {
+		const currentTime = Date.now();
+		if (this.groupBehavior) this.updateGroupBehavior();
+		if (this.state === AiState.Stunned) {
+			if (currentTime >= this.stunnedUntil) this.changeState(AiState.Combat);
+			return;
+		}
+		if (this.enemyType === EnemyType.Berserker && this.event.param[MAXHP]) {
+			const hpPercent = this.event.hp / this.event.param[MAXHP];
+			const berserkerModifier = Math.max(.3, hpPercent);
+			this.attackCooldown = 800 * berserkerModifier;
+		}
+		if (this.behaviorEnabled) this.updateBehavior(currentTime);
+		this.applyCustomBehavior(currentTime);
+		switch (this.state) {
+			case AiState.Idle:
+				this.updateIdleBehavior();
+				break;
+			case AiState.Alert:
+				this.updateAlertBehavior();
+				break;
+			case AiState.Combat:
+				this.updateCombatBehavior(currentTime);
+				break;
+			case AiState.Flee:
+				this.updateFleeBehavior();
+				break;
+		}
+		this.checkDamageTaken();
+	}
+	/**
+	* Update idle behavior (patrolling)
+	*/
+	updateIdleBehavior() {
+		if (this.patrolWaypoints.length > 0) {
+			const waypoint = this.patrolWaypoints[this.currentPatrolIndex];
+			if (this.getDistance(this.event, {
+				x: () => waypoint.x,
+				y: () => waypoint.y
+			}) < 10) {
+				this.currentPatrolIndex = (this.currentPatrolIndex + 1) % this.patrolWaypoints.length;
+				this.startPatrol();
+			}
+		}
+	}
+	/**
+	* Update alert behavior
+	*/
+	updateAlertBehavior() {
+		if (this.target) {
+			this.faceTarget();
+			if (this.getDistance(this.event, this.target) <= this.attackRange * 1.5) this.changeState(AiState.Combat);
+		} else this.changeState(AiState.Idle);
+	}
+	/**
+	* Update combat behavior
+	*/
+	updateCombatBehavior(currentTime) {
+		if (!this.target) {
+			this.debugLog("combat", "No target, returning to idle");
+			this.changeState(AiState.Idle);
+			return;
+		}
+		const distance = this.getDistance(this.event, this.target);
+		if (distance > this.visionRange * 1.5) {
+			this.debugLog("combat", `Target out of range (dist=${distance.toFixed(1)}, maxRange=${(this.visionRange * 1.5).toFixed(1)})`);
+			this.target = null;
+			this.isMovingToTarget = false;
+			this.event.stopMoveTo();
+			this.changeState(AiState.Idle);
+			return;
+		}
+		if (this.event.param[MAXHP]) {
+			const hpPercent = this.event.hp / this.event.param[MAXHP];
+			if (hpPercent <= this.fleeThreshold) {
+				this.debugLog("combat", `HP low (${(hpPercent * 100).toFixed(0)}%), fleeing`);
+				this.isMovingToTarget = false;
+				this.changeState(AiState.Flee);
+				return;
+			}
+		}
+		if (this.canDodge() && this.shouldDodge()) {
+			this.debugLog("combat", "Attempting dodge");
+			if (this.tryDodge()) {
+				this.isMovingToTarget = false;
+				return;
+			}
+		}
+		if (this.behaviorEnabled) {
+			if (this.behaviorMode === "tactical") this.handleTacticalMovement(distance);
+			else if (this.behaviorMode === "assault") this.handleAssaultMovement(distance);
+			else if (this.behaviorMode === "retreat") {
+				this.isMovingToTarget = false;
+				this.fleeFromTarget();
+				return;
+			}
+		}
+		if (this.behaviorEnabled && this.behaviorMode === "assault") {} else if (this.behaviorEnabled && this.behaviorMode === "tactical") {} else if (this.enemyType === EnemyType.Ranged) {
+			if (distance < this.attackRange * .6) {
+				this.debugLog("movement", `Retreating (dist=${distance.toFixed(1)}, minRange=${(this.attackRange * .6).toFixed(1)})`);
+				this.isMovingToTarget = false;
+				this.retreatFromTarget();
+			} else if (distance > this.attackRange) {
+				if (!this.isMovingToTarget) {
+					this.debugLog("movement", `Moving to target (dist=${distance.toFixed(1)}, attackRange=${this.attackRange})`);
+					this.isMovingToTarget = true;
+					this.requestMoveTo(this.target);
+				}
+			} else if (this.isMovingToTarget) {
+				this.debugLog("movement", `In range, stopping (dist=${distance.toFixed(1)})`);
+				this.isMovingToTarget = false;
+				this.event.stopMoveTo();
+			}
+		} else if (distance > this.attackRange) {
+			if (!this.isMovingToTarget) {
+				this.debugLog("movement", `Moving to target (dist=${distance.toFixed(1)}, attackRange=${this.attackRange})`);
+				this.isMovingToTarget = true;
+				this.requestMoveTo(this.target);
+			}
+		} else if (this.isMovingToTarget) {
+			this.debugLog("movement", `In range, stopping (dist=${distance.toFixed(1)})`);
+			this.isMovingToTarget = false;
+			this.event.stopMoveTo();
+		}
+		if (distance <= this.attackRange && currentTime - this.lastAttackTime >= this.attackCooldown) {
+			if (!this.chargingAttack) {
+				this.debugLog("attack", `Attacking (dist=${distance.toFixed(1)}, cooldown=${this.attackCooldown}ms)`);
+				this.selectAndPerformAttack();
+				this.lastAttackTime = currentTime;
+			}
+		}
+	}
+	/**
+	* Update flee behavior
+	*/
+	updateFleeBehavior() {
+		if (!this.target) {
+			this.changeState(AiState.Idle);
+			return;
+		}
+		const distance = this.getDistance(this.event, this.target);
+		if (this.event.param[MAXHP]) {
+			if (this.event.hp / this.event.param[MAXHP] > this.fleeThreshold * 1.5 || distance > this.visionRange * 2) {
+				this.changeState(AiState.Combat);
+				return;
+			}
+		}
+		this.fleeFromTarget();
+	}
+	/**
+	* Select and perform an attack pattern
+	*/
+	selectAndPerformAttack() {
+		if (!this.target) return;
+		if (this.comboCount > 0 && this.comboCount < this.comboMax) {
+			this.debugLog("attack", `Continuing combo (${this.comboCount}/${this.comboMax})`);
+			this.performComboAttack();
+			return;
+		}
+		const pattern = this.selectAttackPattern();
+		this.debugLog("attack", `Selected pattern: ${pattern}`);
+		this.performAttackPattern(pattern);
+	}
+	/**
+	* Select attack pattern with weighted probability
+	*/
+	selectAttackPattern() {
+		const weights = {
+			[AttackPattern.Melee]: 40,
+			[AttackPattern.Combo]: 25,
+			[AttackPattern.Charged]: 15,
+			[AttackPattern.Zone]: 10,
+			[AttackPattern.DashAttack]: 10
+		};
+		switch (this.enemyType) {
+			case EnemyType.Aggressive:
+				weights[AttackPattern.Combo] += 20;
+				weights[AttackPattern.DashAttack] += 15;
+				break;
+			case EnemyType.Defensive:
+				weights[AttackPattern.Charged] += 25;
+				break;
+			case EnemyType.Ranged:
+				weights[AttackPattern.Zone] += 20;
+				break;
+			case EnemyType.Tank:
+				weights[AttackPattern.Charged] += 30;
+				weights[AttackPattern.Zone] += 15;
+				break;
+			case EnemyType.Berserker:
+				weights[AttackPattern.Combo] += 35;
+				break;
+		}
+		let total = 0;
+		const available = [];
+		this.attackPatterns.forEach((p) => {
+			const weight = weights[p] || 10;
+			total += weight;
+			available.push({
+				pattern: p,
+				weight
+			});
+		});
+		let random = Math.random() * total;
+		for (const item of available) {
+			random -= item.weight;
+			if (random <= 0) return item.pattern;
+		}
+		return this.attackPatterns[0] || AttackPattern.Melee;
+	}
+	/**
+	* Perform attack pattern
+	*/
+	performAttackPattern(pattern) {
+		switch (pattern) {
+			case AttackPattern.Melee:
+				this.performMeleeAttack();
+				break;
+			case AttackPattern.Combo:
+				this.performComboAttack();
+				break;
+			case AttackPattern.Charged:
+				this.performChargedAttack();
+				break;
+			case AttackPattern.Zone:
+				this.performZoneAttack();
+				break;
+			case AttackPattern.DashAttack:
+				this.performDashAttack();
+				break;
+		}
+	}
+	/**
+	* Perform melee attack
+	* Uses skill if configured, otherwise creates hitbox
+	*/
+	performMeleeAttack() {
+		if (!this.target) return;
+		const profile = this.getAttackProfile(AttackPattern.Melee);
+		this.faceTarget();
+		this.telegraphAttack(profile);
+		playActionBattleAnimation("attack", this.event, this.animations, { target: this.target });
+		this.scheduleAttackStartup(profile, () => {
+			this.executeMeleeAttack(profile, AttackPattern.Melee);
+		});
+	}
+	executeMeleeAttack(profile, pattern) {
+		if (!this.target) return;
+		this.debugLog("attack", `Applying ${pattern} hit`);
+		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(profile, pattern);
+		}
+		else this.performBasicHitbox(profile, pattern);
+	}
+	/**
+	* Perform basic hitbox attack when no skill is set
+	*/
+	performBasicHitbox(profile = this.getAttackProfile(AttackPattern.Melee), pattern = AttackPattern.Melee) {
+		if (!this.target) return;
+		const eventX = this.event.x();
+		const eventY = this.event.y();
+		const dx = this.target.x() - eventX;
+		const dy = this.target.y() - eventY;
+		const dist = Math.sqrt(dx * dx + dy * dy);
+		if (dist === 0) return;
+		const dirX = dx / dist;
+		const dirY = dy / dist;
+		const hitboxes = [{
+			x: eventX + dirX * 30,
+			y: eventY + dirY * 30,
+			width: 40,
+			height: 40
+		}];
+		this.event.getCurrentMap()?.createMovingHitbox(hitboxes, { speed: resolveActionBattleHitboxSpeed(profile, hitboxes.length) }).subscribe({ next: (hits) => {
+			hits.forEach((hit) => {
+				if (hit instanceof RpgPlayer && hit !== this.event) this.applyHit(hit, void 0, profile, pattern);
+			});
+		} });
+	}
+	/**
+	* Apply hit to target using RPGJS damage system with knockback
+	* 
+	* Calculates damage using RPGJS formula, applies knockback based on
+	* equipped weapon's knockbackForce property, and triggers visual effects.
+	* Supports hooks for customizing behavior.
+	* 
+	* @param target - The player or entity being hit
+	* @param hooks - Optional hooks for customizing hit behavior
+	* @returns The hit result containing damage and knockback info
+	* 
+	* @example
+	* ```ts
+	* // Basic hit
+	* this.applyHit(player);
+	* 
+	* // With custom hooks
+	* this.applyHit(player, {
+	*   onBeforeHit(result) {
+	*     result.knockbackForce *= 1.5; // Increase knockback
+	*     return result;
+	*   },
+	*   onAfterHit(result) {
+	*     console.log(`Dealt ${result.damage} damage!`);
+	*   }
+	* });
+	* ```
+	*/
+	applyHit(target, hooks, profile = this.getAttackProfile(AttackPattern.Melee), pattern = AttackPattern.Melee) {
+		if (isActionBattleEntityInvincible(target)) return {
+			damage: 0,
+			knockbackForce: 0,
+			knockbackDuration: 0,
+			defeated: false,
+			attacker: this.event,
+			target
+		};
+		const { damage } = target.applyDamage(this.event);
+		let hitResult = {
+			damage,
+			knockbackForce: this.getWeaponKnockbackForce(),
+			knockbackDuration: DEFAULT_KNOCKBACK.duration,
+			defeated: target.hp <= 0,
+			attacker: this.event,
+			target
+		};
+		if (hooks?.onBeforeHit) {
+			const modified = hooks.onBeforeHit(hitResult);
+			if (modified) hitResult = modified;
+		}
+		target.flash({
+			type: "tint",
+			tint: "red",
+			duration: 200,
+			cycles: 1
+		});
+		target.showHit(`-${hitResult.damage}`);
+		setActionBattleInvincibility(target, profile.reaction.invincibilityMs);
+		if (hitResult.knockbackForce > 0) {
+			const dx = target.x() - this.event.x();
+			const dy = target.y() - this.event.y();
+			const distance = Math.sqrt(dx * dx + dy * dy);
+			if (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;
+	}
+	/**
+	* Get knockback force from equipped weapon
+	* 
+	* Retrieves the knockbackForce property from the event's equipped weapon.
+	* Falls back to DEFAULT_KNOCKBACK.force if no weapon or property is set.
+	* 
+	* @returns Knockback force value
+	* 
+	* @example
+	* ```ts
+	* // Weapon with knockbackForce: 80
+	* const force = this.getWeaponKnockbackForce(); // 80
+	* 
+	* // No weapon equipped
+	* const force = this.getWeaponKnockbackForce(); // 50 (default)
+	* ```
+	*/
+	getWeaponKnockbackForce() {
+		try {
+			const equipments = this.event.equipments?.() || [];
+			for (const item of equipments) {
+				const itemData = this.event.databaseById?.(item.id());
+				if (itemData?._type === "weapon" && itemData.knockbackForce !== void 0) return itemData.knockbackForce;
+			}
+		} catch {}
+		return DEFAULT_KNOCKBACK.force;
+	}
+	/**
+	* Perform combo attack
+	*/
+	performComboAttack() {
+		if (!this.target) return;
+		this.comboCount++;
+		const profile = this.getAttackProfile(AttackPattern.Combo);
+		this.faceTarget();
+		this.telegraphAttack(profile);
+		playActionBattleAnimation("attack", this.event, this.animations, { target: this.target });
+		this.scheduleAttackStartup(profile, () => {
+			this.executeMeleeAttack(profile, AttackPattern.Combo);
+		});
+		if (this.comboCount < this.comboMax) this.schedule(() => {
+			if (this.target && this.state === AiState.Combat) this.performComboAttack();
+			else this.comboCount = 0;
+		}, 300);
+		else this.comboCount = 0;
+	}
+	/**
+	* Perform charged attack
+	*/
+	performChargedAttack() {
+		if (!this.target) return;
+		const profile = this.getAttackProfile(AttackPattern.Charged);
+		this.chargingAttack = true;
+		this.faceTarget();
+		this.telegraphAttack(profile);
+		playActionBattleAnimation("attack", this.event, this.animations, { target: this.target }, { repeat: 2 });
+		this.scheduleAttackStartup(profile, () => {
+			if (!this.target || this.state !== AiState.Combat) {
+				this.chargingAttack = false;
+				return;
+			}
+			this.executeMeleeAttack(profile, AttackPattern.Charged);
+		});
+		this.schedule(() => {
+			this.chargingAttack = false;
+		}, profile.totalDurationMs);
+	}
+	/**
+	* Perform zone attack (360 degrees)
+	*/
+	performZoneAttack() {
+		const profile = this.getAttackProfile(AttackPattern.Zone);
+		this.telegraphAttack(profile);
+		playActionBattleAnimation("attack", this.event, this.animations, { target: this.target ?? void 0 });
+		const eventX = this.event.x();
+		const eventY = this.event.y();
+		const radius = 50;
+		const hitboxes = [];
+		[
+			0,
+			90,
+			180,
+			270
+		].forEach((angle) => {
+			const rad = angle * Math.PI / 180;
+			hitboxes.push({
+				x: eventX + Math.cos(rad) * radius,
+				y: eventY + Math.sin(rad) * radius,
+				width: 40,
+				height: 40
+			});
+		});
+		this.scheduleAttackStartup(profile, () => {
+			this.event.getCurrentMap()?.createMovingHitbox(hitboxes, { speed: resolveActionBattleHitboxSpeed(profile, hitboxes.length) }).subscribe({ next: (hits) => {
+				hits.forEach((hit) => {
+					if (hit instanceof RpgPlayer && hit !== this.event) this.applyHit(hit, void 0, profile, AttackPattern.Zone);
+				});
+			} });
+		});
+	}
+	/**
+	* Perform dash attack
+	*/
+	performDashAttack() {
+		if (!this.target) return;
+		const profile = this.getAttackProfile(AttackPattern.DashAttack);
+		const dx = this.target.x() - this.event.x();
+		const dy = this.target.y() - this.event.y();
+		const dist = Math.sqrt(dx * dx + dy * dy);
+		if (dist === 0) return;
+		const dirX = dx / dist;
+		const dirY = dy / dist;
+		this.faceTarget();
+		this.telegraphAttack(profile);
+		this.scheduleAttackStartup(profile, () => {
+			if (!this.target || this.state !== AiState.Combat) return;
+			this.event.dash({
+				x: dirX,
+				y: dirY
+			}, 10, 200);
+			this.schedule(() => {
+				if (!this.target || this.state !== AiState.Combat) return;
+				this.executeMeleeAttack(profile, AttackPattern.DashAttack);
+			}, 200);
+		});
+	}
+	getAttackProfile(pattern) {
+		return this.attackProfiles[pattern] ?? this.attackProfiles.melee;
+	}
+	telegraphAttack(profile) {
+		if (profile.startupMs <= 0) return;
+		this.event.flash({
+			type: "tint",
+			tint: "white",
+			duration: Math.min(profile.startupMs, 300),
+			cycles: 1
+		});
+	}
+	scheduleAttackStartup(profile, callback) {
+		return scheduleActionBattleStartup(profile, callback, (scheduled, delay) => this.schedule(scheduled, delay));
+	}
+	/**
+	* Face the current target with hysteresis to prevent animation flickering
+	* 
+	* Uses multiple strategies to prevent flickering:
+	* 1. When very close to target (collision), keep current direction
+	* 2. When near diagonal, require significant difference to change
+	* 3. Only change if direction is clearly wrong (opposite)
+	*/
+	faceTarget() {
+		if (!this.target) return;
+		const dx = this.target.x() - this.event.x();
+		const dy = this.target.y() - this.event.y();
+		const absX = Math.abs(dx);
+		const absY = Math.abs(dy);
+		const distance = Math.sqrt(dx * dx + dy * dy);
+		if (this.lastFacingDirection && distance < 40) return;
+		let newDirection;
+		if (absX >= absY) newDirection = dx >= 0 ? "right" : "left";
+		else newDirection = dy >= 0 ? "down" : "up";
+		const hysteresisThreshold = .2;
+		const ratio = absX > 0 || absY > 0 ? Math.min(absX, absY) / Math.max(absX, absY) : 0;
+		if (this.lastFacingDirection && ratio > 1 - hysteresisThreshold) {
+			if (!(this.lastFacingDirection === "left" && dx > 20 || this.lastFacingDirection === "right" && dx < -20 || this.lastFacingDirection === "up" && dy > 20 || this.lastFacingDirection === "down" && dy < -20)) return;
+		}
+		this.lastFacingDirection = newDirection;
+		this.event.changeDirection(newDirection);
+	}
+	/**
+	* Try to dodge
+	*/
+	tryDodge() {
+		const currentTime = Date.now();
+		if (currentTime - this.lastDodgeTime < this.dodgeCooldown) {
+			this.debugLog("dodge", `Dodge on cooldown (${this.dodgeCooldown - (currentTime - this.lastDodgeTime)}ms remaining)`);
+			return false;
+		}
+		if (Math.random() > this.dodgeChance) {
+			this.debugLog("dodge", `Dodge roll failed (chance=${(this.dodgeChance * 100).toFixed(0)}%)`);
+			return false;
+		}
+		if (!this.target) return false;
+		const dx = this.target.x() - this.event.x();
+		const dy = this.target.y() - this.event.y();
+		const dist = Math.sqrt(dx * dx + dy * dy);
+		if (dist === 0) return false;
+		const dodgeDirX = -dy / dist;
+		const dodgeDirY = dx / dist;
+		const side = Math.random() > .5 ? 1 : -1;
+		this.debugLog("dodge", `Dodging (dir=${side > 0 ? "right" : "left"})`);
+		this.event.dash({
+			x: dodgeDirX * side,
+			y: dodgeDirY * side
+		}, 12, 300);
+		this.lastDodgeTime = currentTime;
+		if (this.enemyType === EnemyType.Defensive && Math.random() < .5) {
+			this.debugLog("dodge", "Counter-attack after dodge");
+			this.schedule(() => {
+				if (this.target && this.state === AiState.Combat) this.selectAndPerformAttack();
+			}, 400);
+		}
+		return true;
+	}
+	canDodge() {
+		if (this.dodgeChance === 0) return false;
+		return Date.now() - this.lastDodgeTime >= this.dodgeCooldown;
+	}
+	shouldDodge() {
+		if (!this.target) return false;
+		return this.getDistance(this.event, this.target) < this.attackRange * .8;
+	}
+	/**
+	* Flee from target
+	*/
+	fleeFromTarget() {
+		if (!this.target) return;
+		const dx = this.event.x() - this.target.x();
+		const dy = this.event.y() - this.target.y();
+		const dist = Math.sqrt(dx * dx + dy * dy);
+		if (dist === 0) return;
+		this.requestMoveTo({
+			x: () => this.event.x() + dx / dist * 200,
+			y: () => this.event.y() + dy / dist * 200
+		});
+	}
+	/**
+	* Retreat from target (temporary)
+	*/
+	retreatFromTarget() {
+		if (!this.target) return;
+		const currentTime = Date.now();
+		if (currentTime - this.lastRetreatTime < this.retreatCooldown) return;
+		const dx = this.event.x() - this.target.x();
+		const dy = this.event.y() - this.target.y();
+		const dist = Math.sqrt(dx * dx + dy * dy);
+		if (dist === 0) return;
+		this.event.dash({
+			x: dx / dist,
+			y: dy / dist
+		}, 8, 200);
+		this.lastRetreatTime = currentTime;
+	}
+	/**
+	* Check damage taken for retreat decision
+	*/
+	checkDamageTaken() {
+		const currentTime = Date.now();
+		if (currentTime - this.lastHpCheck >= this.damageCheckInterval) {
+			this.recentDamageTaken = 0;
+			this.lastHpCheck = currentTime;
+		}
+	}
+	/**
+	* Start patrol
+	*/
+	startPatrol() {
+		if (this.patrolWaypoints.length === 0) return;
+		const waypoint = this.patrolWaypoints[this.currentPatrolIndex];
+		this.requestMoveTo({
+			x: () => waypoint.x,
+			y: () => waypoint.y
+		});
+	}
+	/**
+	* Update group behavior
+	*/
+	updateGroupBehavior() {
+		if (!this.groupBehavior) return;
+		this.groupUpdateInterval++;
+		if (this.groupUpdateInterval >= 20) {
+			this.groupUpdateInterval = 0;
+			this.findNearbyEnemies();
+		}
+		if (this.nearbyEnemies.length > 0 && this.target && this.state === AiState.Combat) this.applyFormation();
+	}
+	/**
+	* Find nearby enemies
+	*/
+	findNearbyEnemies() {
+		this.nearbyEnemies = [];
+		const map = this.event.getCurrentMap();
+		if (!map) return;
+		const allEvents = Object.values(map.events());
+		const groupRadius = 150;
+		allEvents.forEach((event) => {
+			if (event === this.event) return;
+			const ai = event.battleAi;
+			if (ai && ai.groupBehavior) {
+				if (this.getDistance(this.event, event) <= groupRadius) this.nearbyEnemies.push(ai);
+			}
+		});
+	}
+	/**
+	* Apply formation around target
+	*/
+	applyFormation() {
+		if (!this.target || this.nearbyEnemies.length === 0) return;
+		const totalEnemies = this.nearbyEnemies.length + 1;
+		const angleStep = 2 * Math.PI / totalEnemies;
+		let ourIndex = 0;
+		for (let i = 0; i < this.nearbyEnemies.length; i++) if (this.nearbyEnemies[i].event.id < this.event.id) ourIndex++;
+		const angle = angleStep * ourIndex;
+		const formationRadius = this.attackRange * 1.2;
+		const formationX = this.target.x() + Math.cos(angle) * formationRadius;
+		const formationY = this.target.y() + Math.sin(angle) * formationRadius;
+		if (Math.sqrt(Math.pow(this.event.x() - formationX, 2) + Math.pow(this.event.y() - formationY, 2)) > 20) this.requestMoveTo({
+			x: () => formationX,
+			y: () => formationY
+		});
+	}
+	/**
+	* Handle player entering vision
+	*/
+	onDetectInShape(player, shape) {
+		this.debugLog("vision", `Player ${player.id} entered vision (state=${this.state})`);
+		this.target = player;
+		if (this.state === AiState.Idle) this.changeState(AiState.Alert);
+		else if (this.state === AiState.Alert) this.changeState(AiState.Combat);
+	}
+	/**
+	* Handle player leaving vision
+	*/
+	onDetectOutShape(player, shape) {
+		this.debugLog("vision", `Player ${player.id} left vision (wasTarget=${this.target === player})`);
+		if (this.target === player) {
+			this.target = null;
+			this.isMovingToTarget = false;
+			this.event.stopMoveTo();
+			this.changeState(AiState.Idle);
+		}
+	}
+	/**
+	* Handle taking damage (called from server.ts)
+	* 
+	* This triggers state changes like stun and flee check.
+	* The actual damage is applied externally via RPGJS API.
+	*/
+	takeDamage(attacker) {
+		const raw = this.event.applyDamage(attacker);
+		return this.handleDamage(attacker, {
+			damage: raw.damage ?? 0,
+			defeated: this.event.hp <= 0,
+			raw
+		});
+	}
+	handleDamage(attacker, damageResult) {
+		const damage = damageResult.damage;
+		this.debugLog("damage", `Took ${damage} damage from ${attacker.id} (HP: ${this.event.hp}/${this.event.param[MAXHP] || "?"})`);
+		this.event.flash({
+			type: "tint",
+			tint: "red",
+			duration: 200,
+			cycles: 1
+		});
+		this.event.showHit(`-${damage}`);
+		playActionBattleAnimation("hurt", this.event, this.animations, { attacker });
+		this.recentDamageTaken += damage;
+		const reaction = damageResult.reaction;
+		const staggerPower = reaction?.staggerPower ?? damage;
+		const hitstunMs = reaction?.hitstunMs ?? this.hitstunMs;
+		const shouldStun = staggerPower >= this.poise && hitstunMs > 0;
+		setActionBattleInvincibility(this.event, reaction?.invincibilityMs ?? this.invincibilityMs);
+		if (shouldStun && this.state !== AiState.Stunned && this.state !== AiState.Flee) {
+			this.debugLog("damage", "Stunned from damage");
+			this.isMovingToTarget = false;
+			this.stunnedUntil = Date.now() + hitstunMs;
+			this.changeState(AiState.Stunned);
+		}
+		if (damageResult.defeated || this.event.hp <= 0) {
+			this.debugLog("damage", "Defeated!");
+			this.kill(attacker);
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Kill this AI
+	* 
+	* Stops all movements, cleans up resources, calls the onDefeated hook,
+	* 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);
+		this.destroy();
+		if (removeDelay > 0) this.schedule(() => this.event.remove(), removeDelay);
+		else this.event.remove();
+	}
+	/**
+	* Get distance between entities
+	*/
+	getDistance(entity1, entity2) {
+		const dx = entity1.x() - entity2.x();
+		const dy = entity1.y() - entity2.y();
+		return Math.sqrt(dx * dx + dy * dy);
+	}
+	updateBehavior(currentTime) {
+		if (currentTime - this.behaviorLastUpdate < this.behaviorUpdateInterval) return;
+		this.behaviorLastUpdate = currentTime;
+		let score = this.behaviorScore;
+		const maxHp = this.event.param[MAXHP];
+		if (maxHp) {
+			const hpPercent = this.event.hp / maxHp;
+			score += (hpPercent - .5) * 40;
+		}
+		if (this.recentDamageTaken > 0) score -= Math.min(30, this.recentDamageTaken * .5);
+		if (this.target) {
+			const distance = this.getDistance(this.event, this.target);
+			if (distance <= this.attackRange) score += 10;
+			else if (distance > this.visionRange) score -= 10;
+		}
+		if (this.groupBehavior && this.nearbyEnemies.length > 0) score += Math.min(15, this.nearbyEnemies.length * 5);
+		score = Math.max(0, Math.min(100, score));
+		this.behaviorScore = score;
+		const previousMode = this.behaviorMode;
+		if (score >= this.behaviorAssaultThreshold) this.behaviorMode = "assault";
+		else if (score <= this.behaviorRetreatThreshold) this.behaviorMode = "retreat";
+		else this.behaviorMode = "tactical";
+		if (previousMode !== this.behaviorMode) this.debugLog("state", `Behavior mode: ${previousMode} -> ${this.behaviorMode} (score=${score.toFixed(0)})`);
+		if (this.behaviorMode === "retreat" && this.state === AiState.Combat) {
+			if (currentTime - this.stateStartTime >= this.behaviorMinStateDuration) {
+				this.isMovingToTarget = false;
+				this.changeState(AiState.Flee);
+			}
+		} else if (this.behaviorMode === "assault" && this.state === AiState.Flee) {
+			if (currentTime - this.stateStartTime >= this.behaviorMinStateDuration) this.changeState(AiState.Combat);
+		}
+	}
+	applyCustomBehavior(currentTime) {
+		if (!this.behaviorKey) return;
+		const behavior = getActionBattleSystems().ai.behaviors[this.behaviorKey];
+		if (!behavior) return;
+		const maxHp = this.event.param[MAXHP];
+		const decision = behavior({
+			event: this.event,
+			target: this.target,
+			state: this.state,
+			enemyType: this.enemyType,
+			distance: this.target ? this.getDistance(this.event, this.target) : null,
+			hpPercent: maxHp ? this.event.hp / maxHp : null,
+			now: currentTime
+		});
+		if (!decision) return;
+		if (decision.attackCooldown !== void 0) this.attackCooldown = decision.attackCooldown;
+		if (decision.moveToCooldown !== void 0) this.moveToCooldown = decision.moveToCooldown;
+		if (decision.attackPatterns?.length) this.attackPatterns = decision.attackPatterns;
+		if (decision.mode) {
+			this.behaviorMode = decision.mode;
+			this.behaviorEnabled = true;
+		}
+	}
+	handleTacticalMovement(distance) {
+		if (!this.target) return;
+		const minRange = this.attackRange * .7;
+		const maxRange = this.attackRange * 1.2;
+		if (distance < minRange) {
+			this.debugLog("movement", `Tactical retreat (dist=${distance.toFixed(1)}, minRange=${minRange.toFixed(1)})`);
+			this.isMovingToTarget = false;
+			this.retreatFromTarget();
+			return;
+		}
+		if (distance > maxRange) {
+			if (!this.isMovingToTarget) {
+				this.debugLog("movement", `Tactical approach (dist=${distance.toFixed(1)}, maxRange=${maxRange.toFixed(1)})`);
+				this.isMovingToTarget = true;
+				this.requestMoveTo(this.target);
+			}
+			return;
+		}
+		if (this.isMovingToTarget) {
+			this.debugLog("movement", `Tactical hold (dist=${distance.toFixed(1)})`);
+			this.isMovingToTarget = false;
+			this.event.stopMoveTo();
+		}
+	}
+	handleAssaultMovement(distance) {
+		if (!this.target) return;
+		if (distance > this.attackRange) {
+			if (!this.isMovingToTarget) {
+				this.debugLog("movement", `Assault approach (dist=${distance.toFixed(1)}, attackRange=${this.attackRange})`);
+				this.isMovingToTarget = true;
+				this.requestMoveTo(this.target);
+			}
+			return;
+		}
+		if (this.isMovingToTarget) {
+			this.debugLog("movement", `Assault hold (dist=${distance.toFixed(1)})`);
+			this.isMovingToTarget = false;
+			this.event.stopMoveTo();
+		}
+	}
+	requestMoveTo(target) {
+		const currentTime = Date.now();
+		if (currentTime - this.lastMoveToTime < this.moveToCooldown) return false;
+		this.event.moveTo(target);
+		this.lastMoveToTime = currentTime;
+		return true;
+	}
+	schedule(callback, delay) {
+		const timer = setTimeout(() => {
+			this.timers = this.timers.filter((entry) => entry !== timer);
+			callback();
+		}, delay);
+		this.timers.push(timer);
+		return timer;
+	}
+	getHealth() {
+		return this.event.hp;
+	}
+	getMaxHealth() {
+		return this.event.param[MAXHP];
+	}
+	getTarget() {
+		return this.target;
+	}
+	getState() {
+		return this.state;
+	}
+	getEnemyType() {
+		return this.enemyType;
+	}
+	/**
+	* Clean up
+	*/
+	destroy() {
+		if (this.updateInterval) {
+			clearInterval(this.updateInterval);
+			this.updateInterval = void 0;
+		}
+		this.target = null;
+		this.nearbyEnemies = [];
+		this.timers.forEach((timer) => clearTimeout(timer));
+		this.timers = [];
+	}
+};
+//#endregion
+export { AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_KNOCKBACK, EnemyType };