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

package/README.md

@@ -231,6 +231,24 @@ new BattleAi(event, {
     AttackPattern.Combo,
     AttackPattern.DashAttack
   ],
+
+  // Per-pattern enemy attack timing and reactions
+  attackProfiles: {
+    charged: {
+      startupMs: 900,
+      activeMs: 140,
+      recoveryMs: 300,
+      reaction: {
+        hitstunMs: 240,
+        staggerPower: 2
+      }
+    }
+  },
+
+  // Hit reaction tuning
+  poise: 1,
+  hitstunMs: 150,
+  invincibilityMs: 250,
   
   // Patrol waypoints (for idle state)
   patrolWaypoints: [
@@ -249,6 +267,11 @@ new BattleAi(event, {
 });
 ```
 
+`attackProfiles` lets enemies telegraph attacks with `startupMs`, keep hitboxes
+active for `activeMs`, and apply hit reactions. `poise` controls interruption:
+an incoming hit only stuns the enemy when its `reaction.staggerPower` is greater
+than or equal to the enemy's `poise`.
+
 ## Enemy Types
 
 Types modify AI **behavior** (cooldowns, ranges, dodge), not stats:
@@ -607,6 +630,98 @@ Player attacks are resolved with `createMovingHitbox()` instead of a passive
 contact collision. You can still customize the generated hitboxes with
 `attack.hitboxes` or `attack.resolveHitboxes`.
 
+### Attack profile model
+
+Use `attack.profile` to describe the timing model of a player attack in one
+typed object. A profile separates the attack into startup, active, and recovery
+phases so combat systems can share the same vocabulary.
+
+```ts
+import { provideActionBattle } from "@rpgjs/action-battle/server";
+
+export default provideActionBattle({
+  attack: {
+    profile: {
+      id: "iron-sword",
+      startupMs: 80,
+      activeMs: 120,
+      recoveryMs: 180,
+      cooldownMs: 380,
+      movementLock: true,
+      directionLock: true,
+      animationKey: "attack",
+      hitPolicy: "oncePerTarget",
+      reaction: {
+        invincibilityMs: 250,
+        hitstunMs: 150,
+        staggerPower: 1
+      },
+      hitboxes: {
+        right: { offsetX: 18, offsetY: -18, width: 42, height: 36 }
+      }
+    },
+    lockDurationMs: 380
+  }
+});
+```
+
+The default profile mirrors the legacy attack lock: no startup, a short active
+window, and recovery that totals `350ms`. The player attack runtime uses
+`startupMs` before creating the hitbox, `activeMs` to keep the hitbox active,
+and `totalDurationMs` for movement and direction locks. `hitPolicy:
+"oncePerTarget"` prevents the same attack window from damaging the same target
+multiple times.
+
+`reaction` describes what happens after the hit connects:
+
+- `invincibilityMs`: temporary invincibility after damage.
+- `hitstunMs`: stun duration requested by the hit.
+- `staggerPower`: value compared against enemy `poise`.
+
+```ts
+import {
+  normalizeActionBattleAttackProfile,
+  type ActionBattleAttackProfile
+} from "@rpgjs/action-battle/server";
+
+const sword: ActionBattleAttackProfile = {
+  id: "sword",
+  startupMs: 70,
+  activeMs: 110,
+  recoveryMs: 170
+};
+
+const normalized = normalizeActionBattleAttackProfile(sword);
+```
+
+Equipped weapons can override the player attack profile:
+
+```ts
+const Dagger = {
+  id: "dagger",
+  name: "Dagger",
+  _type: "weapon" as const,
+  atk: 8,
+  knockbackForce: 20,
+  attackProfile: {
+    id: "dagger",
+    startupMs: 40,
+    activeMs: 70,
+    recoveryMs: 110
+  }
+};
+```
+
+Enable lightweight attack logs while tuning profiles:
+
+```ts
+provideActionBattle({
+  debug: {
+    attacks: true
+  }
+});
+```
+
 When the action targets a normal event with no `BattleAi`, the server lets the
 event handle `onAction` and does not create the combat hitbox. Enemy events
 with `BattleAi` still trigger the A-RPG attack.

package/dist/ai.server.d.ts

@@ -1,6 +1,7 @@
 import { RpgEvent, RpgPlayer } from '@rpgjs/server';
+import { ActionBattleEnemyAttackProfileMap } from './core/enemy-attack-profiles';
 import { ActionBattleDamageResult } from './core/contracts';
-import { ActionBattleAnimationOptions } from './types';
+import { NormalizedActionBattleHitReactionProfile, ActionBattleAnimationOptions } from './types';
 type RpgEventWithBattleAi = RpgEvent & {
     battleAi?: BattleAi;
 };
@@ -14,6 +15,7 @@ export interface BattleAiOptions {
     fleeThreshold?: number;
     attackSkill?: any;
     attackPatterns?: AttackPattern[];
+    attackProfiles?: ActionBattleEnemyAttackProfileMap;
     patrolWaypoints?: Array<{
         x: number;
         y: number;
@@ -21,6 +23,9 @@ export interface BattleAiOptions {
     groupBehavior?: boolean;
     moveToCooldown?: number;
     retreatCooldown?: number;
+    poise?: number;
+    hitstunMs?: number;
+    invincibilityMs?: number;
     behavior?: {
         baseScore?: number;
         updateInterval?: number;
@@ -252,6 +257,7 @@ export declare class BattleAi {
     private fleeThreshold;
     private attackSkill;
     private attackPatterns;
+    private attackProfiles;
     private animations?;
     private comboCount;
     private comboMax;
@@ -281,6 +287,9 @@ export declare class BattleAi {
     private lastRetreatTime;
     private timers;
     private behaviorKey?;
+    private poise;
+    private hitstunMs;
+    private invincibilityMs;
     /**
      * Create a new Battle AI Controller
      *
@@ -362,6 +371,7 @@ export declare class BattleAi {
      * Uses skill if configured, otherwise creates hitbox
      */
     private performMeleeAttack;
+    private executeMeleeAttack;
     /**
      * Perform basic hitbox attack when no skill is set
      */
@@ -429,6 +439,9 @@ export declare class BattleAi {
      * Perform dash attack
      */
     private performDashAttack;
+    private getAttackProfile;
+    private telegraphAttack;
+    private scheduleAttackStartup;
     /**
      * Face the current target with hysteresis to prevent animation flickering
      *
@@ -487,7 +500,9 @@ export declare class BattleAi {
      * The actual damage is applied externally via RPGJS API.
      */
     takeDamage(attacker: RpgPlayer): boolean;
-    handleDamage(attacker: RpgPlayer, damageResult: ActionBattleDamageResult): boolean;
+    handleDamage(attacker: RpgPlayer, damageResult: ActionBattleDamageResult & {
+        reaction?: NormalizedActionBattleHitReactionProfile;
+    }): boolean;
     /**
      * Kill this AI
      *

package/dist/client/index.js

@@ -1,10 +1,15 @@
-import client_default, { createActionBattleClient } from "./index9.js";
-import { DEFAULT_ZELDA_PLAYER_HITBOXES, createDefaultPlayerHitboxResolver, defaultCombatSystem, defaultEnemyBehaviors, defaultKnockbackResolver, defaultRpgjsDamageResolver } from "./index10.js";
-import { createActionBattleSystems, getActionBattleSystems } from "./index11.js";
-import { AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_KNOCKBACK, EnemyType } from "./index12.js";
-import { applyActionBattleHit } from "./index13.js";
-import { createActionEnemy } from "./index14.js";
-import { ACTION_BATTLE_ACTION_BAR_GUI_ID, DEFAULT_PLAYER_ATTACK_HITBOXES, applyPlayerHitToEvent, createActionBattleServer, getPlayerWeaponKnockbackForce, openActionBattleActionBar, updateActionBattleActionBar } from "./index15.js";
+import { DEFAULT_ACTION_BATTLE_HIT_REACTION, isActionBattleEntityInvincible, normalizeActionBattleHitReaction, setActionBattleInvincibility } from "./index2.js";
+import { DEFAULT_ACTION_BATTLE_ATTACK_PROFILE, normalizeActionBattleAttackProfile } from "./index3.js";
+import { ACTION_BATTLE_HITBOX_FRAME_MS, ActionBattleHitTracker, createActionBattleAttackId, getNormalizedActionBattleAttackProfile, resolveActionBattleHitboxSpeed, scheduleActionBattleStartup } from "./index11.js";
+import client_default, { createActionBattleClient } from "./index12.js";
+import { DEFAULT_ZELDA_PLAYER_HITBOXES, createDefaultPlayerHitboxResolver, defaultCombatSystem, defaultEnemyBehaviors, defaultKnockbackResolver, defaultRpgjsDamageResolver } from "./index13.js";
+import { createActionBattleSystems, getActionBattleSystems } from "./index14.js";
+import { DEFAULT_ACTION_BATTLE_ENEMY_ATTACK_PROFILES, normalizeActionBattleEnemyAttackProfiles } from "./index15.js";
+import { AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_KNOCKBACK, EnemyType } from "./index16.js";
+import { resolveActionBattleWeaponAttackProfile } from "./index17.js";
+import { applyActionBattleHit } from "./index18.js";
+import { createActionEnemy } from "./index19.js";
+import { ACTION_BATTLE_ACTION_BAR_GUI_ID, DEFAULT_PLAYER_ATTACK_HITBOXES, applyPlayerHitToEvent, createActionBattleServer, getPlayerWeaponKnockbackForce, openActionBattleActionBar, updateActionBattleActionBar } from "./index20.js";
 import { createModule } from "@rpgjs/common";
 //#region src/index.ts
 var server = null;
@@ -20,4 +25,4 @@ var src_default = {
 	client: client_default
 };
 //#endregion
-export { ACTION_BATTLE_ACTION_BAR_GUI_ID, AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_KNOCKBACK, DEFAULT_PLAYER_ATTACK_HITBOXES, DEFAULT_ZELDA_PLAYER_HITBOXES, EnemyType, applyActionBattleHit, applyPlayerHitToEvent, createActionBattleServer, createActionBattleSystems, createActionEnemy, createDefaultPlayerHitboxResolver, src_default as default, defaultCombatSystem, defaultEnemyBehaviors, defaultKnockbackResolver, defaultRpgjsDamageResolver, getActionBattleSystems, getPlayerWeaponKnockbackForce, openActionBattleActionBar, provideActionBattle, updateActionBattleActionBar };
+export { ACTION_BATTLE_ACTION_BAR_GUI_ID, ACTION_BATTLE_HITBOX_FRAME_MS, ActionBattleHitTracker, AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_ACTION_BATTLE_ATTACK_PROFILE, DEFAULT_ACTION_BATTLE_ENEMY_ATTACK_PROFILES, DEFAULT_ACTION_BATTLE_HIT_REACTION, DEFAULT_KNOCKBACK, DEFAULT_PLAYER_ATTACK_HITBOXES, DEFAULT_ZELDA_PLAYER_HITBOXES, EnemyType, applyActionBattleHit, applyPlayerHitToEvent, createActionBattleAttackId, createActionBattleServer, createActionBattleSystems, createActionEnemy, createDefaultPlayerHitboxResolver, src_default as default, defaultCombatSystem, defaultEnemyBehaviors, defaultKnockbackResolver, defaultRpgjsDamageResolver, getActionBattleSystems, getNormalizedActionBattleAttackProfile, getPlayerWeaponKnockbackForce, isActionBattleEntityInvincible, normalizeActionBattleAttackProfile, normalizeActionBattleEnemyAttackProfiles, normalizeActionBattleHitReaction, openActionBattleActionBar, provideActionBattle, resolveActionBattleHitboxSpeed, resolveActionBattleWeaponAttackProfile, scheduleActionBattleStartup, setActionBattleInvincibility, updateActionBattleActionBar };

package/dist/client/index10.js

@@ -1,143 +1,61 @@
-//#region src/core/defaults.ts
-var DEFAULT_CORE_KNOCKBACK = {
-	force: 50,
-	duration: 300
-};
-var CoreAttackPattern = {
-	Melee: "melee",
-	Combo: "combo",
-	Charged: "charged",
-	Zone: "zone",
-	DashAttack: "dashAttack"
-};
-var CoreEnemyType = {
-	Aggressive: "aggressive",
-	Defensive: "defensive",
-	Ranged: "ranged",
-	Tank: "tank",
-	Berserker: "berserker"
-};
-var DEFAULT_ZELDA_PLAYER_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
-	}
-};
-var resolveEquippedWeapon = (entity) => {
-	const equipments = entity?.equipments?.() || [];
-	for (const item of equipments) {
-		const itemId = item?.id?.() ?? item?.id;
-		const itemData = entity?.databaseById?.(itemId);
-		if (itemData?._type === "weapon") return itemData;
-	}
-	return null;
-};
-var resolveDirection = (attacker, target) => {
-	const dx = target.x() - attacker.x();
-	const dy = target.y() - attacker.y();
-	const distance = Math.sqrt(dx * dx + dy * dy);
-	if (distance <= 0) return void 0;
-	return {
-		x: dx / distance,
-		y: dy / distance
+var DEFAULT_ANIMATION_BY_KEY = {
+	attack: "attack",
+	hurt: "hurt",
+	die: "die",
+	castSkill: "skill",
+	castSpell: "skill"
+};
+var getConfiguredAnimation = (key, animations) => {
+	if (!animations) return {
+		hasConfiguredAnimation: false,
+		configured: void 0
+	};
+	const hasConfiguredAnimation = Object.prototype.hasOwnProperty.call(animations, key);
+	if (hasConfiguredAnimation) return {
+		hasConfiguredAnimation,
+		configured: animations[key]
+	};
+	if (key === "castSkill") return {
+		hasConfiguredAnimation: Object.prototype.hasOwnProperty.call(animations, "castSpell"),
+		configured: animations.castSpell
 	};
-};
-var createDefaultPlayerHitboxResolver = (hitboxes = DEFAULT_ZELDA_PLAYER_HITBOXES) => (context) => {
-	const attacker = context.attacker;
-	const config = hitboxes[context.direction ?? (typeof attacker.getDirection === "function" ? attacker.getDirection() : "default")] || hitboxes.default;
-	return [{
-		x: attacker.x() + config.offsetX,
-		y: attacker.y() + config.offsetY,
-		width: config.width,
-		height: config.height
-	}];
-};
-var defaultRpgjsDamageResolver = (context) => {
-	const target = context.target;
-	const raw = target.applyDamage(context.attacker, context.skill);
 	return {
-		damage: raw?.damage ?? 0,
-		defeated: target.hp <= 0,
-		raw
+		hasConfiguredAnimation: false,
+		configured: void 0
 	};
 };
-var defaultKnockbackResolver = (context) => {
-	const weapon = context.weapon ?? resolveEquippedWeapon(context.attacker);
+function resolveActionBattleAnimation(key, entity, animations, context, defaults = {}) {
+	const defaultAnimationName = defaults.animationName ?? DEFAULT_ANIMATION_BY_KEY[key];
+	const defaultRepeat = defaults.repeat ?? 1;
+	const { hasConfiguredAnimation, configured: configuredAnimation } = getConfiguredAnimation(key, animations);
+	if (!hasConfiguredAnimation && key !== "attack") return null;
+	const configured = hasConfiguredAnimation ? configuredAnimation : defaultAnimationName;
+	const result = typeof configured === "function" ? configured(entity, context) : configured;
+	if (result == null) return null;
+	if (typeof result === "string") return {
+		animationName: result,
+		repeat: defaultRepeat,
+		waitEnd: false
+	};
 	return {
-		force: weapon?.knockbackForce ?? DEFAULT_CORE_KNOCKBACK.force,
-		duration: weapon?.knockbackDuration ?? DEFAULT_CORE_KNOCKBACK.duration,
-		direction: resolveDirection(context.attacker, context.target)
+		animationName: result.animationName ?? defaultAnimationName,
+		graphic: result.graphic,
+		repeat: result.repeat ?? defaultRepeat,
+		waitEnd: result.waitEnd ?? false,
+		delayMs: result.delayMs
 	};
-};
-var defaultCombatSystem = {
-	resolveHitboxes: createDefaultPlayerHitboxResolver(),
-	resolveDamage: defaultRpgjsDamageResolver,
-	resolveKnockback: defaultKnockbackResolver
-};
-var defaultEnemyBehaviors = {
-	[CoreEnemyType.Aggressive]: ({ hpPercent }) => ({
-		mode: hpPercent !== null && hpPercent < .15 ? "retreat" : "assault",
-		attackPatterns: [
-			CoreAttackPattern.Melee,
-			CoreAttackPattern.Combo,
-			CoreAttackPattern.DashAttack
-		]
-	}),
-	[CoreEnemyType.Defensive]: ({ hpPercent }) => ({
-		mode: hpPercent !== null && hpPercent < .3 ? "retreat" : "tactical",
-		attackPatterns: [CoreAttackPattern.Melee, CoreAttackPattern.Charged]
-	}),
-	[CoreEnemyType.Ranged]: ({ distance }) => ({
-		mode: distance !== null && distance < 80 ? "retreat" : "tactical",
-		attackPatterns: [CoreAttackPattern.Melee, CoreAttackPattern.Zone]
-	}),
-	[CoreEnemyType.Tank]: () => ({
-		mode: "assault",
-		attackPatterns: [
-			CoreAttackPattern.Melee,
-			CoreAttackPattern.Charged,
-			CoreAttackPattern.Zone
-		]
-	}),
-	[CoreEnemyType.Berserker]: ({ hpPercent }) => ({
-		mode: "assault",
-		attackCooldown: hpPercent === null ? void 0 : Math.max(250, 800 * Math.max(.3, hpPercent)),
-		attackPatterns: [
-			CoreAttackPattern.Melee,
-			CoreAttackPattern.Combo,
-			CoreAttackPattern.DashAttack
-		]
-	})
-};
-var defaultActionBattleSystems = {
-	combat: defaultCombatSystem,
-	ai: { behaviors: defaultEnemyBehaviors }
-};
+}
+function playActionBattleAnimation(key, entity, animations, context, defaults = {}) {
+	const animation = resolveActionBattleAnimation(key, entity, animations, context, defaults);
+	if (!animation) return null;
+	if (animation.graphic !== void 0) entity.setGraphicAnimation(animation.animationName, animation.graphic, animation.repeat);
+	else entity.setGraphicAnimation(animation.animationName, animation.repeat);
+	return animation;
+}
+function getActionBattleAnimationRemovalDelay(animation) {
+	if (!animation) return 0;
+	if (animation.delayMs !== void 0) return animation.delayMs;
+	return animation.waitEnd ? 500 : 0;
+}
 //#endregion
-export { DEFAULT_ZELDA_PLAYER_HITBOXES, createDefaultPlayerHitboxResolver, defaultActionBattleSystems, defaultCombatSystem, defaultEnemyBehaviors, defaultKnockbackResolver, defaultRpgjsDamageResolver };
+export { getActionBattleAnimationRemovalDelay, playActionBattleAnimation, resolveActionBattleAnimation };

package/dist/client/index11.js

@@ -1,25 +1,54 @@
-import { defaultActionBattleSystems } from "./index10.js";
-//#region src/core/context.ts
-var mergeSystems = (options = {}) => ({
-	combat: {
-		...defaultActionBattleSystems.combat,
-		resolveDamage: options.systems?.combat?.damage ?? defaultActionBattleSystems.combat.resolveDamage,
-		resolveKnockback: options.systems?.combat?.knockback ?? defaultActionBattleSystems.combat.resolveKnockback,
-		hooks: {
-			...defaultActionBattleSystems.combat.hooks,
-			...options.systems?.combat?.hooks
-		}
-	},
-	ai: { behaviors: {
-		...defaultActionBattleSystems.ai.behaviors,
-		...options.systems?.ai?.behaviors
-	} }
-});
-var currentActionBattleSystems = mergeSystems();
-var setActionBattleSystems = (options = {}) => {
-	currentActionBattleSystems = mergeSystems(options);
+import { normalizeActionBattleAttackProfile } from "./index3.js";
+//#region src/core/attack-runtime.ts
+var ACTION_BATTLE_HITBOX_FRAME_MS = 16;
+function getNormalizedActionBattleAttackProfile(options = {}) {
+	const attack = options.attack ?? {};
+	return normalizeActionBattleAttackProfile(attack.profile, {
+		lockMovement: attack.lockMovement,
+		lockDurationMs: attack.lockDurationMs,
+		hitboxes: attack.hitboxes
+	});
+}
+function resolveActionBattleHitboxSpeed(profile, hitboxCount) {
+	const positions = Math.max(1, Math.floor(hitboxCount));
+	const activeFrames = Math.max(1, Math.ceil(profile.activeMs / 16));
+	return Math.max(1, Math.ceil(activeFrames / positions));
+}
+function scheduleActionBattleStartup(profile, callback, scheduler = setTimeout) {
+	if (profile.startupMs <= 0) {
+		callback();
+		return null;
+	}
+	return scheduler(callback, profile.startupMs);
+}
+var attackIdCounter = 0;
+function createActionBattleAttackId(attackerId, profileId) {
+	attackIdCounter++;
+	return `${attackerId ?? "unknown"}:${profileId}:${Date.now()}:${attackIdCounter}`;
+}
+var getTargetKey = (target) => {
+	if (!target || target.id === void 0 || target.id === null) return null;
+	return String(target.id);
+};
+var ActionBattleHitTracker = class {
+	hitTargets = /* @__PURE__ */ new Set();
+	constructor(hitPolicy) {
+		this.hitPolicy = hitPolicy;
+	}
+	canHit(target) {
+		if (this.hitPolicy === "allowRepeatHits") return true;
+		const key = getTargetKey(target);
+		return !key || !this.hitTargets.has(key);
+	}
+	recordHit(target) {
+		const key = getTargetKey(target);
+		if (key) this.hitTargets.add(key);
+	}
+	tryHit(target) {
+		if (!this.canHit(target)) return false;
+		this.recordHit(target);
+		return true;
+	}
 };
-var getActionBattleSystems = () => currentActionBattleSystems;
-var createActionBattleSystems = mergeSystems;
 //#endregion
-export { createActionBattleSystems, getActionBattleSystems, setActionBattleSystems };
+export { ACTION_BATTLE_HITBOX_FRAME_MS, ActionBattleHitTracker, createActionBattleAttackId, getNormalizedActionBattleAttackProfile, resolveActionBattleHitboxSpeed, scheduleActionBattleStartup };