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

package/dist/server.d.ts

@@ -90,11 +90,17 @@ export declare function getPlayerWeaponKnockbackForce(player: RpgPlayer): number
  * });
  * ```
  */
-export declare function applyPlayerHitToEvent(player: RpgPlayer, target: RpgEvent, hooks?: ApplyHitHooks): HitResult | undefined;
+export declare function applyPlayerHitToEvent(player: RpgPlayer, target: RpgEvent, hooks?: ApplyHitHooks, metadata?: Record<string, any>): HitResult | undefined;
 export declare const openActionBattleActionBar: (player: RpgPlayer, rawOptions?: ActionBattleOptions) => void;
 export declare const updateActionBattleActionBar: (player: RpgPlayer, rawOptions?: ActionBattleOptions) => void;
 export declare const createActionBattleServer: (rawOptions?: ActionBattleOptions) => RpgServer;
 declare const _default: RpgServer;
 export default _default;
+export { ACTION_BATTLE_HITBOX_FRAME_MS, ActionBattleHitTracker, createActionBattleAttackId, getNormalizedActionBattleAttackProfile, resolveActionBattleHitboxSpeed, scheduleActionBattleStartup, } from './core/attack-runtime';
+export { DEFAULT_ACTION_BATTLE_ATTACK_PROFILE, normalizeActionBattleAttackProfile, type ActionBattleAttackProfileFallbacks, } from './core/attack-profile';
+export type { ActionBattleAttackDirection, ActionBattleAttackHitboxConfig, ActionBattleAttackHitboxMap, ActionBattleAttackHitPolicy, ActionBattleAttackProfile, ActionBattleDebugOptions, ActionBattleHitReactionProfile, NormalizedActionBattleHitReactionProfile, NormalizedActionBattleAttackProfile, } from './types';
+export { DEFAULT_ACTION_BATTLE_HIT_REACTION, isActionBattleEntityInvincible, normalizeActionBattleHitReaction, setActionBattleInvincibility, } from './core/hit-reaction';
+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';

package/package.json

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

package/src/ai.server.ts

@@ -5,7 +5,24 @@ import {
 } from "./animations";
 import { getActionBattleOptions } from "./config";
 import { getActionBattleSystems } from "./core/context";
+import {
+  isActionBattleEntityInvincible,
+  setActionBattleInvincibility,
+} from "./core/hit-reaction";
+import {
+  normalizeActionBattleEnemyAttackProfiles,
+  type ActionBattleEnemyAttackProfileMap,
+  type NormalizedActionBattleEnemyAttackProfileMap,
+} from "./core/enemy-attack-profiles";
+import {
+  resolveActionBattleHitboxSpeed,
+  scheduleActionBattleStartup,
+} from "./core/attack-runtime";
 import type { ActionBattleDamageResult } from "./core/contracts";
+import type {
+  NormalizedActionBattleAttackProfile,
+  NormalizedActionBattleHitReactionProfile,
+} from "./types";
 import type { ActionBattleAnimationOptions } from "./types";
 
 type RpgEventWithBattleAi = RpgEvent & {
@@ -22,10 +39,14 @@ export interface BattleAiOptions {
   fleeThreshold?: number;
   attackSkill?: any;
   attackPatterns?: AttackPattern[];
+  attackProfiles?: ActionBattleEnemyAttackProfileMap;
   patrolWaypoints?: Array<{ x: number; y: number }>;
   groupBehavior?: boolean;
   moveToCooldown?: number;
   retreatCooldown?: number;
+  poise?: number;
+  hitstunMs?: number;
+  invincibilityMs?: number;
   behavior?: {
     baseScore?: number;
     updateInterval?: number;
@@ -295,6 +316,7 @@ export class BattleAi {
   // Attack configuration
   private attackSkill: any | null; // Skill to use for attacks
   private attackPatterns: AttackPattern[];
+  private attackProfiles: NormalizedActionBattleEnemyAttackProfileMap;
   private animations?: ActionBattleAnimationOptions;
   private comboCount: number = 0;
   private comboMax: number = 3;
@@ -340,6 +362,9 @@ export class BattleAi {
   private lastRetreatTime: number = 0;
   private timers: ReturnType<typeof setTimeout>[] = [];
   private behaviorKey?: string;
+  private poise: number = 0;
+  private hitstunMs: number = 150;
+  private invincibilityMs: number = 250;
 
   /**
    * Create a new Battle AI Controller
@@ -390,6 +415,9 @@ export class BattleAi {
       AttackPattern.Combo,
       AttackPattern.DashAttack
     ];
+    this.attackProfiles = normalizeActionBattleEnemyAttackProfiles(
+      options.attackProfiles
+    );
 
     // Initialize group behavior
     this.groupBehavior = options.groupBehavior || false;
@@ -427,6 +455,15 @@ export class BattleAi {
     if (options.retreatCooldown !== undefined) {
       this.retreatCooldown = options.retreatCooldown;
     }
+    if (options.poise !== undefined) {
+      this.poise = Math.max(0, options.poise);
+    }
+    if (options.hitstunMs !== undefined) {
+      this.hitstunMs = Math.max(0, options.hitstunMs);
+    }
+    if (options.invincibilityMs !== undefined) {
+      this.invincibilityMs = Math.max(0, options.invincibilityMs);
+    }
 
     // Setup AI systems
     this.setupVision();
@@ -896,12 +933,26 @@ export class BattleAi {
    */
   private 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);
+    });
+  }
+
+  private executeMeleeAttack(
+    profile: NormalizedActionBattleAttackProfile,
+    pattern: AttackPattern
+  ) {
+    if (!this.target) return;
+    this.debugLog('attack', `Applying ${pattern} hit`);
+
     // Use skill if available
     if (this.attackSkill) {
       try {
@@ -912,17 +963,22 @@ export class BattleAi {
         this.event.useSkill(this.attackSkill, this.target);
       } catch (e) {
         // Skill failed (no SP, etc.) - fall back to basic attack
-        this.performBasicHitbox();
+        this.performBasicHitbox(profile, pattern);
       }
     } else {
-      this.performBasicHitbox();
+      this.performBasicHitbox(profile, pattern);
     }
   }
 
   /**
    * Perform basic hitbox attack when no skill is set
    */
-  private performBasicHitbox() {
+  private performBasicHitbox(
+    profile: NormalizedActionBattleAttackProfile = this.getAttackProfile(
+      AttackPattern.Melee
+    ),
+    pattern: AttackPattern = AttackPattern.Melee
+  ) {
     if (!this.target) return;
 
     const eventX = this.event.x();
@@ -944,11 +1000,13 @@ export class BattleAi {
     }];
 
     const map = this.event.getCurrentMap();
-    map?.createMovingHitbox(hitboxes, { speed: 5 }).subscribe({
-      next: (hits) => {
-        hits.forEach((hit) => {
+    map?.createMovingHitbox(hitboxes, {
+      speed: resolveActionBattleHitboxSpeed(profile, hitboxes.length),
+    }).subscribe({
+      next: (hits: any[]) => {
+        hits.forEach((hit: any) => {
           if (hit instanceof RpgPlayer && hit !== this.event) {
-            this.applyHit(hit);
+            this.applyHit(hit, undefined, profile, pattern);
           }
         });
       },
@@ -983,7 +1041,25 @@ export class BattleAi {
    * });
    * ```
    */
-  private applyHit(target: RpgPlayer, hooks?: ApplyHitHooks): HitResult {
+  private applyHit(
+    target: RpgPlayer,
+    hooks?: ApplyHitHooks,
+    profile: NormalizedActionBattleAttackProfile = this.getAttackProfile(
+      AttackPattern.Melee
+    ),
+    pattern: AttackPattern = AttackPattern.Melee
+  ): HitResult {
+    if (isActionBattleEntityInvincible(target)) {
+      return {
+        damage: 0,
+        knockbackForce: 0,
+        knockbackDuration: 0,
+        defeated: false,
+        attacker: this.event,
+        target
+      };
+    }
+
     // Use RPGJS damage formula
     const { damage } = target.applyDamage(this.event as any);
 
@@ -1017,6 +1093,10 @@ export class BattleAi {
       cycles: 1
     });
     target.showHit(`-${hitResult.damage}`);
+    setActionBattleInvincibility(
+      target,
+      profile.reaction.invincibilityMs
+    );
 
     // Apply knockback
     if (hitResult.knockbackForce > 0) {
@@ -1080,7 +1160,15 @@ export class BattleAi {
     if (!this.target) return;
 
     this.comboCount++;
-    this.performMeleeAttack();
+    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(() => {
@@ -1100,9 +1188,11 @@ export class BattleAi {
    */
   private performChargedAttack() {
     if (!this.target) return;
+    const profile = this.getAttackProfile(AttackPattern.Charged);
 
     this.chargingAttack = true;
     this.faceTarget();
+    this.telegraphAttack(profile);
     playActionBattleAnimation(
       "attack",
       this.event,
@@ -1113,35 +1203,24 @@ export class BattleAi {
       { repeat: 2 }
     );
 
-    this.schedule(() => {
+    this.scheduleAttackStartup(profile, () => {
       if (!this.target || this.state !== AiState.Combat) {
         this.chargingAttack = false;
         return;
       }
-
-      // Charged attacks can use a stronger skill or wider hitbox
-      if (this.attackSkill) {
-        try {
-          playActionBattleAnimation("castSkill", this.event, this.animations, {
-            skill: this.attackSkill,
-            target: this.target,
-          });
-          this.event.useSkill(this.attackSkill, this.target);
-        } catch (e) {
-          this.performBasicHitbox();
-        }
-      } else {
-        this.performBasicHitbox();
-      }
-      
+      this.executeMeleeAttack(profile, AttackPattern.Charged);
+    });
+    this.schedule(() => {
       this.chargingAttack = false;
-    }, 800);
+    }, profile.totalDurationMs);
   }
 
   /**
    * Perform zone attack (360 degrees)
    */
   private performZoneAttack() {
+    const profile = this.getAttackProfile(AttackPattern.Zone);
+    this.telegraphAttack(profile);
     playActionBattleAnimation("attack", this.event, this.animations, {
       target: this.target ?? undefined,
     });
@@ -1163,15 +1242,19 @@ export class BattleAi {
       });
     });
 
-    const map = this.event.getCurrentMap();
-    map?.createMovingHitbox(hitboxes, { speed: 5 }).subscribe({
-      next: (hits) => {
-        hits.forEach((hit) => {
-          if (hit instanceof RpgPlayer && hit !== this.event) {
-            this.applyHit(hit);
-          }
-        });
-      },
+    this.scheduleAttackStartup(profile, () => {
+      const map = this.event.getCurrentMap();
+      map?.createMovingHitbox(hitboxes, {
+        speed: resolveActionBattleHitboxSpeed(profile, hitboxes.length),
+      }).subscribe({
+        next: (hits: any[]) => {
+          hits.forEach((hit: any) => {
+            if (hit instanceof RpgPlayer && hit !== this.event) {
+              this.applyHit(hit, undefined, profile, AttackPattern.Zone);
+            }
+          });
+        },
+      });
     });
   }
 
@@ -1180,6 +1263,7 @@ export class BattleAi {
    */
   private 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();
@@ -1191,12 +1275,43 @@ export class BattleAi {
     const dirY = dy / dist;
 
     this.faceTarget();
-    this.event.dash({ x: dirX, y: dirY }, 10, 200);
+    this.telegraphAttack(profile);
 
-    this.schedule(() => {
+    this.scheduleAttackStartup(profile, () => {
       if (!this.target || this.state !== AiState.Combat) return;
-      this.performMeleeAttack();
-    }, 200);
+      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);
+    });
+  }
+
+  private getAttackProfile(
+    pattern: AttackPattern
+  ): NormalizedActionBattleAttackProfile {
+    return this.attackProfiles[
+      pattern as keyof NormalizedActionBattleEnemyAttackProfileMap
+    ] ?? this.attackProfiles.melee;
+  }
+
+  private telegraphAttack(profile: NormalizedActionBattleAttackProfile) {
+    if (profile.startupMs <= 0) return;
+    this.event.flash({
+      type: 'tint',
+      tint: 'white',
+      duration: Math.min(profile.startupMs, 300),
+      cycles: 1
+    });
+  }
+
+  private scheduleAttackStartup(
+    profile: NormalizedActionBattleAttackProfile,
+    callback: () => void
+  ) {
+    return scheduleActionBattleStartup(profile, callback, (scheduled, delay) =>
+      this.schedule(scheduled, delay)
+    );
   }
 
   /**
@@ -1487,7 +1602,12 @@ export class BattleAi {
     });
   }
 
-  handleDamage(attacker: RpgPlayer, damageResult: ActionBattleDamageResult): boolean {
+  handleDamage(
+    attacker: RpgPlayer,
+    damageResult: ActionBattleDamageResult & {
+      reaction?: NormalizedActionBattleHitReactionProfile;
+    }
+  ): boolean {
     const damage = damageResult.damage;
     this.debugLog('damage', `Took ${damage} damage from ${attacker.id} (HP: ${this.event.hp}/${this.event.param[MAXHP] || '?'})`);
 
@@ -1506,11 +1626,20 @@ export class BattleAi {
     // Track damage
     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
+    );
+
     // Brief stun
-    if (this.state !== AiState.Stunned && this.state !== AiState.Flee) {
+    if (shouldStun && this.state !== AiState.Stunned && this.state !== AiState.Flee) {
       this.debugLog('damage', 'Stunned from damage');
       this.isMovingToTarget = false;
-      this.stunnedUntil = Date.now() + 150;
+      this.stunnedUntil = Date.now() + hitstunMs;
       this.changeState(AiState.Stunned);
     }
 

package/src/client.ts

@@ -14,12 +14,14 @@ import {
 import { ActionBattleOptions } from "./types";
 import { normalizeActionBattleOptions } from "./config";
 import { resolveActionBattleAnimation } from "./animations";
+import { getNormalizedActionBattleAttackProfile } from "./core/attack-runtime";
 
 const DEFAULT_ATTACK_LOCK_DURATION_MS = 350;
 
 const beginLocalPlayerAttackLock = (
   engine: RpgClientEngine,
-  durationMs: number
+  durationMs: number,
+  locks: { movement: boolean; direction: boolean }
 ): boolean => {
   if (durationMs <= 0) return true;
 
@@ -44,13 +46,17 @@ const beginLocalPlayerAttackLock = (
   const previousDirectionFixed = player.directionFixed;
   const previousAnimationFixed = player.animationFixed;
 
-  if (typeof engine.interruptCurrentPlayerMovement === "function") {
-    engine.interruptCurrentPlayerMovement(player);
-  } else {
-    (engine.scene as any)?.stopMovement?.(player);
+  if (locks.movement) {
+    if (typeof engine.interruptCurrentPlayerMovement === "function") {
+      engine.interruptCurrentPlayerMovement(player);
+    } else {
+      (engine.scene as any)?.stopMovement?.(player);
+    }
+    player.canMove.set(false);
+  }
+  if (locks.direction) {
+    player.directionFixed = true;
   }
-  player.canMove.set(false);
-  player.directionFixed = true;
   player.animationFixed = true;
 
   setTimeout(() => {
@@ -154,14 +160,17 @@ export const createActionBattleClient = (
         if (input !== "action") return;
         const player = engine.scene?.getCurrentPlayer?.() as any;
         if (!player) return;
+        const attackProfile = getNormalizedActionBattleAttackProfile(normalized);
         const lockDurationMs = Math.max(
           0,
-          normalized.attack?.lockDurationMs ?? DEFAULT_ATTACK_LOCK_DURATION_MS
-        );
-        beginLocalPlayerAttackLock(
-          engine,
-          normalized.attack?.lockMovement === false ? 0 : lockDurationMs
+          attackProfile.totalDurationMs ?? DEFAULT_ATTACK_LOCK_DURATION_MS
         );
+        if (attackProfile.movementLock || attackProfile.directionLock) {
+          beginLocalPlayerAttackLock(engine, lockDurationMs, {
+            movement: attackProfile.movementLock,
+            direction: attackProfile.directionLock,
+          });
+        }
         playLocalPlayerAttackAnimation(player, normalized);
         showLocalAttackPreview(player, normalized);
       },

package/src/config.ts

@@ -1,4 +1,5 @@
 import { ActionBattleOptions } from "./types";
+import { normalizeActionBattleAttackProfile } from "./core/attack-profile";
 
 export const DEFAULT_ACTION_BATTLE_OPTIONS: ActionBattleOptions = {
   ui: {
@@ -41,6 +42,16 @@ let currentActionBattleOptions: ActionBattleOptions =
 export function normalizeActionBattleOptions(
   options: ActionBattleOptions = {}
 ): ActionBattleOptions {
+  const attack = {
+    ...DEFAULT_ACTION_BATTLE_OPTIONS.attack,
+    ...options.attack,
+  };
+  const attackProfile = normalizeActionBattleAttackProfile(attack.profile, {
+    lockMovement: attack.lockMovement,
+    lockDurationMs: attack.lockDurationMs,
+    hitboxes: attack.hitboxes,
+  });
+
   return {
     ui: {
       actionBar: {
@@ -64,9 +75,13 @@ export function normalizeActionBattleOptions(
       ...DEFAULT_ACTION_BATTLE_OPTIONS.targeting,
       ...options.targeting,
     },
+    debug: {
+      ...DEFAULT_ACTION_BATTLE_OPTIONS.debug,
+      ...options.debug,
+    },
     attack: {
-      ...DEFAULT_ACTION_BATTLE_OPTIONS.attack,
-      ...options.attack,
+      ...attack,
+      profile: attackProfile,
     },
     animations: {
       ...DEFAULT_ACTION_BATTLE_OPTIONS.animations,

package/src/core/attack-profile.spec.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "vitest";
+import {
+  DEFAULT_ACTION_BATTLE_ATTACK_PROFILE,
+  normalizeActionBattleAttackProfile,
+} from "./attack-profile";
+import { normalizeActionBattleOptions } from "../config";
+import type { NormalizedActionBattleAttackProfile } from "../types";
+
+describe("normalizeActionBattleAttackProfile", () => {
+  test("creates a default profile compatible with the legacy 350ms attack lock", () => {
+    const profile = normalizeActionBattleAttackProfile();
+
+    expect(profile).toEqual(DEFAULT_ACTION_BATTLE_ATTACK_PROFILE);
+  });
+
+  test("derives recovery from the legacy lock duration when recovery is omitted", () => {
+    const profile = normalizeActionBattleAttackProfile(
+      {
+        startupMs: 80,
+        activeMs: 90,
+      },
+      {
+        lockDurationMs: 400,
+      }
+    );
+
+    expect(profile.recoveryMs).toBe(230);
+    expect(profile.totalDurationMs).toBe(400);
+    expect(profile.cooldownMs).toBe(400);
+  });
+
+  test("keeps explicit timing, movement, hit policy, animation, and hitboxes", () => {
+    const hitboxes = {
+      right: { offsetX: 18, offsetY: -18, width: 42, height: 36 },
+    };
+    const profile = normalizeActionBattleAttackProfile({
+      id: "heavy-sword",
+      startupMs: 140,
+      activeMs: 100,
+      recoveryMs: 260,
+      cooldownMs: 650,
+      movementLock: false,
+      directionLock: false,
+      animationKey: "castSkill",
+      hitPolicy: "allowRepeatHits",
+      hitboxes,
+    });
+
+    expect(profile).toMatchObject({
+      id: "heavy-sword",
+      startupMs: 140,
+      activeMs: 100,
+      recoveryMs: 260,
+      cooldownMs: 650,
+      movementLock: false,
+      directionLock: false,
+      animationKey: "castSkill",
+      hitPolicy: "allowRepeatHits",
+      totalDurationMs: 500,
+    });
+    expect(profile.hitboxes).toBe(hitboxes);
+  });
+
+  test("normalizes unsafe timing values to playable bounds", () => {
+    const profile = normalizeActionBattleAttackProfile({
+      startupMs: -20,
+      activeMs: 0,
+      recoveryMs: -10,
+      cooldownMs: -1,
+    });
+
+    expect(profile.startupMs).toBe(0);
+    expect(profile.activeMs).toBe(1);
+    expect(profile.recoveryMs).toBe(0);
+    expect(profile.cooldownMs).toBe(0);
+    expect(profile.totalDurationMs).toBe(1);
+  });
+
+  test("normalizes attack.profile through action battle options", () => {
+    const options = normalizeActionBattleOptions({
+      attack: {
+        lockMovement: false,
+        lockDurationMs: 300,
+        profile: {
+          id: "quick-slash",
+          startupMs: 60,
+          activeMs: 80,
+        },
+      },
+    });
+    const profile = options.attack
+      ?.profile as NormalizedActionBattleAttackProfile;
+
+    expect(profile).toMatchObject({
+      id: "quick-slash",
+      startupMs: 60,
+      activeMs: 80,
+      recoveryMs: 160,
+      cooldownMs: 300,
+      movementLock: false,
+      totalDurationMs: 300,
+    });
+  });
+
+  test("keeps legacy lockDurationMs when no explicit profile is provided", () => {
+    const options = normalizeActionBattleOptions({
+      attack: {
+        lockDurationMs: 500,
+      },
+    });
+    const profile = options.attack
+      ?.profile as NormalizedActionBattleAttackProfile;
+
+    expect(profile.totalDurationMs).toBe(500);
+    expect(profile.recoveryMs).toBe(380);
+    expect(profile.cooldownMs).toBe(500);
+  });
+});