@rpgjs/action-battle 5.0.0-alpha.44 → 5.0.0-beta.10

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# @rpgjs/action-battle
+
+## 5.0.0-beta.10
+
+### Patch Changes
+
+- Updated dependencies
+  - @rpgjs/client@5.0.0-beta.10
+  - @rpgjs/server@5.0.0-beta.10
+  - @rpgjs/vite@5.0.0-beta.10
+
+## 5.0.0-beta.9
+
+### Major Changes
+
+- c456d25: beta.9
+
+### Patch Changes
+
+- Updated dependencies [c456d25]
+  - @rpgjs/client@5.0.0-beta.9
+  - @rpgjs/common@5.0.0-beta.9
+  - @rpgjs/server@5.0.0-beta.9
+  - @rpgjs/vite@5.0.0-beta.9
+
+## 5.0.0-beta.8
+
+### Major Changes
+
+- 35e7fa4: beta.8
+
+### Patch Changes
+
+- Updated dependencies [35e7fa4]
+  - @rpgjs/client@5.0.0-beta.8
+  - @rpgjs/common@5.0.0-beta.8
+  - @rpgjs/server@5.0.0-beta.8
+  - @rpgjs/vite@5.0.0-beta.8

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2026 by Samuel Ronce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -7,6 +7,7 @@ The AI controller manages **behavior only** - all stats (HP, ATK, skills, items,
 ## Features
 
 - **State Machine AI**: Enemies with dynamic behaviors (Idle, Alert, Combat, Flee, Stunned)
+- **Plugin-first architecture**: Replace damage, hitboxes, knockback, hooks, and AI behaviors independently
 - **Multiple Enemy Types**: Aggressive, Defensive, Ranged, Tank, Berserker
 - **Attack Patterns**: Melee, Combo, Charged, Zone, Dash Attack
 - **Skill Support**: AI can use any RPGJS skill
@@ -22,6 +23,90 @@ The AI controller manages **behavior only** - all stats (HP, ATK, skills, items,
 npm install @rpgjs/action-battle
 ```
 
+## Plugin-First Customization
+
+`provideActionBattle()` ships with Zelda-like defaults, but each combat system
+can be replaced without rewriting the module.
+
+```ts
+import { provideActionBattle } from "@rpgjs/action-battle/server";
+
+export default provideActionBattle({
+  attack: {
+    lockMovement: true,
+    lockDurationMs: 280,
+    hitboxes: {
+      right: { offsetX: 18, offsetY: -18, width: 42, height: 36 }
+    }
+  },
+  systems: {
+    combat: {
+      damage({ attacker, target, skill }) {
+        const raw = target.applyDamage(attacker, skill);
+        return {
+          damage: raw.damage,
+          defeated: target.hp <= 0,
+          raw
+        };
+      },
+      knockback({ attacker, target }) {
+        const dx = target.x() - attacker.x();
+        const dy = target.y() - attacker.y();
+        const distance = Math.max(1, Math.sqrt(dx * dx + dy * dy));
+        return {
+          force: 70,
+          duration: 220,
+          direction: { x: dx / distance, y: dy / distance }
+        };
+      },
+      hooks: {
+        beforeHit(context) {
+          // Return false to cancel a hit, or return a modified context.
+          return context;
+        },
+        afterHit(result) {
+          console.log(`Damage: ${result.damage}`);
+        }
+      }
+    },
+    ai: {
+      behaviors: {
+        slime({ hpPercent }) {
+          return {
+            mode: hpPercent !== null && hpPercent < 0.25 ? "retreat" : "assault",
+            attackCooldown: 900
+          };
+        }
+      }
+    }
+  }
+});
+```
+
+The main extension contracts are:
+
+- `ActionBattleCombatSystem`: resolves hitboxes, damage, knockback, and hooks.
+- `ActionBattleAiBehavior`: returns lightweight AI decisions from event state.
+- `ActionBattleHitHooks`: `beforeHit`, `afterDamage`, and `afterHit`.
+
+Use `createActionEnemy()` when you want data-driven enemy presets:
+
+```ts
+import { createActionEnemy, EnemyType } from "@rpgjs/action-battle/server";
+
+const enemyPresets = {
+  slime: {
+    enemyType: EnemyType.Aggressive,
+    behaviorKey: "slime",
+    stats(event) {
+      event.hp = 40;
+    }
+  }
+};
+
+createActionEnemy(this, "slime", enemyPresets);
+```
+
 ## Quick Start
 
 ```typescript
@@ -146,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: [
@@ -157,13 +260,18 @@ 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}!`);
+    console.log(`${event.name} was defeated by ${name}!`);
   }
 });
 ```
 
+`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:
@@ -496,6 +604,245 @@ The module handles player attacks via the `action` input:
 // Knockback force is based on equipped weapon's knockbackForce property
 ```
 
+By default, the player is locked in place for `350ms` when attacking, similar
+to classic A-RPG combat where the attack resolves before movement resumes.
+
+```ts
+provideActionBattle({
+  attack: {
+    lockMovement: true,
+    lockDurationMs: 350,
+    showPreview: true,
+    previewDurationMs: 180,
+    previewColor: 0xfff3b0,
+    previewAccentColor: 0xffffff
+  }
+});
+```
+
+Set `lockMovement` to `false` if your game should allow moving attacks.
+The client also stops predicted movement immediately and shows a short slash
+preview so the action feels responsive even before the server hit resolves. Set
+`showPreview` to `false` if your project uses only spritesheet combat
+animations.
+
+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.
+
+## Configurable Combat Animations
+
+By default, player and AI attacks keep using the existing `attack` animation:
+
+```ts
+player.setGraphicAnimation("attack", 1);
+```
+
+Use `animations` when your combat sprites are stored in separate graphics such
+as `hero_attack`, `hero_hurt`, or `hero_die`.
+
+```ts
+import { provideActionBattle } from "@rpgjs/action-battle/server";
+
+export default provideActionBattle({
+  animations: {
+    attack: "attack",
+    hurt: "hurt",
+    die: {
+      animationName: "die",
+      repeat: 1,
+      delayMs: 500
+    },
+    castSkill: "skill"
+  }
+});
+```
+
+RPGJS Studio stores combat animations as spritesheet media ids. If
+`provideStudioGame()` is installed, `createStudioActionBattleAnimations()` can
+read the project animations attached to the player at runtime. By default, the
+helper plays Studio attack spritesheets with
+`setGraphicAnimation("attack", graphic, 1)`:
+
+```ts
+import { provideActionBattle } from "@rpgjs/action-battle/server";
+import { createStudioActionBattleAnimations } from "@rpgjs/studio/server";
+
+export default provideActionBattle({
+  animations: createStudioActionBattleAnimations()
+});
+```
+
+You can also pass a static Studio animation object to override the media ids
+manually. Animation values may be media ids or media objects returned by the
+Studio game API.
+
+The Studio field `castSpell` is accepted as an alias for action-battle's
+`castSkill` animation key.
+
+For data-driven spritesheets, use resolver functions:
+
+```ts
+provideActionBattle({
+  animations: {
+    attack: (entity) => ({
+      animationName: "walk",
+      graphic: entity.combatAnimations?.attack,
+      repeat: 1
+    }),
+    hurt: (entity) => ({
+      animationName: "walk",
+      graphic: entity.combatAnimations?.hurt,
+      repeat: 1
+    }),
+    die: (entity) => ({
+      animationName: "walk",
+      graphic: entity.combatAnimations?.die,
+      repeat: 1,
+      waitEnd: true
+    }),
+    castSkill: (entity, context) => ({
+      animationName: "walk",
+      graphic: entity.combatAnimations?.castSkill,
+      repeat: 1
+    })
+  }
+});
+```
+
+When `graphic` is provided, action-battle calls:
+
+```ts
+entity.setGraphicAnimation(animationName, graphic, repeat);
+```
+
+Otherwise it calls:
+
+```ts
+entity.setGraphicAnimation(animationName, repeat);
+```
+
+Return `null` or `undefined` from a resolver to skip the animation. `BattleAi`
+can also override the global configuration per enemy:
+
+```ts
+new BattleAi(this, {
+  animations: {
+    attack: {
+      animationName: "walk",
+      graphic: "slime_attack",
+      repeat: 1
+    },
+    die: {
+      animationName: "walk",
+      graphic: "slime_die",
+      repeat: 1,
+      delayMs: 700
+    }
+  }
+});
+```
+
+`waitEnd: true` 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
 
 Knockback force is determined by the equipped weapon's `knockbackForce` property.
@@ -646,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}!`);
+    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
@@ -679,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 }]
         }
       });
     }
@@ -703,7 +1073,7 @@ function Goblin() {
 
 ```typescript
 new BattleAi(this, {
-  onDefeated: (event, attacker) => {
+  onDefeated: ({ event }) => {
     const map = event.getCurrentMap();
     if (!map) return;
     
@@ -723,7 +1093,7 @@ new BattleAi(this, {
 let killCount = 0;
 
 new BattleAi(this, {
-  onDefeated: (event, attacker) => {
+  onDefeated: () => {
     killCount++;
     
     // Check quest progress
@@ -747,7 +1117,7 @@ function DragonBoss() {
       
       new BattleAi(this, {
         enemyType: EnemyType.Tank,
-        onDefeated: (event, attacker) => {
+        onDefeated: ({ event }) => {
           const map = event.getCurrentMap();
           
           // Announce victory