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

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
@@ -496,6 +581,36 @@ 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`.
+
+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:
@@ -524,6 +639,28 @@ export default provideActionBattle({
 });
 ```
 
+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

package/dist/ai.server.d.ts

@@ -1,7 +1,8 @@
 import { RpgEvent, RpgPlayer } from '@rpgjs/server';
+import { ActionBattleDamageResult } from './core/contracts';
 import { ActionBattleAnimationOptions } from './types';
 type RpgEventWithBattleAi = RpgEvent & {
-    battleAi: BattleAi;
+    battleAi?: BattleAi;
 };
 export interface BattleAiOptions {
     enemyType?: EnemyType;
@@ -27,6 +28,7 @@ export interface BattleAiOptions {
         assaultThreshold?: number;
         retreatThreshold?: number;
     };
+    behaviorKey?: string;
     animations?: ActionBattleAnimationOptions;
     /** Callback called when the AI is defeated */
     onDefeated?: (event: RpgEvent, attacker?: RpgPlayer) => void;
@@ -277,6 +279,8 @@ export declare class BattleAi {
     private lastMoveToTime;
     private retreatCooldown;
     private lastRetreatTime;
+    private timers;
+    private behaviorKey?;
     /**
      * Create a new Battle AI Controller
      *
@@ -483,6 +487,7 @@ export declare class BattleAi {
      * The actual damage is applied externally via RPGJS API.
      */
     takeDamage(attacker: RpgPlayer): boolean;
+    handleDamage(attacker: RpgPlayer, damageResult: ActionBattleDamageResult): boolean;
     /**
      * Kill this AI
      *
@@ -495,9 +500,11 @@ export declare class BattleAi {
      */
     private getDistance;
     private updateBehavior;
+    private applyCustomBehavior;
     private handleTacticalMovement;
     private handleAssaultMovement;
     private requestMoveTo;
+    private schedule;
     getHealth(): number;
     getMaxHealth(): number;
     getTarget(): InstanceType<typeof RpgPlayer> | null;

package/dist/client/index.js

@@ -1,35 +1,23 @@
-import client, { createActionBattleClient } from "./index2.js";
+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 { createModule } from "@rpgjs/common";
-import { AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_KNOCKBACK, EnemyType } from "./index3.js";
-import { ACTION_BATTLE_ACTION_BAR_GUI_ID, DEFAULT_PLAYER_ATTACK_HITBOXES, applyPlayerHitToEvent, createActionBattleServer, getPlayerWeaponKnockbackForce, openActionBattleActionBar, updateActionBattleActionBar } from "./index4.js";
-const server = null;
-const createActionBattleServer2 = null;
+//#region src/index.ts
+var server = null;
+var createActionBattleServer$1 = null;
 function provideActionBattle(options = {}) {
-  return createModule("ActionBattle", [
-    {
-      server: createActionBattleServer2?.(options),
-      client: createActionBattleClient?.(options)
-    }
-  ]);
+	return createModule("ActionBattle", [{
+		server: createActionBattleServer$1?.(options),
+		client: createActionBattleClient?.(options)
+	}]);
 }
-const index = {
-  server,
-  client
-};
-export {
-  ACTION_BATTLE_ACTION_BAR_GUI_ID,
-  AiDebug,
-  AiState,
-  AttackPattern,
-  BattleAi,
-  DEFAULT_KNOCKBACK,
-  DEFAULT_PLAYER_ATTACK_HITBOXES,
-  EnemyType,
-  applyPlayerHitToEvent,
-  createActionBattleServer,
-  index as default,
-  getPlayerWeaponKnockbackForce,
-  openActionBattleActionBar,
-  provideActionBattle,
-  updateActionBattleActionBar
+var src_default = {
+	server,
+	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 };

package/dist/client/index10.js

@@ -1,30 +1,143 @@
-const normalizeMaskRows = (mask) => {
-  if (!mask) return ["#"];
-  if (Array.isArray(mask)) return mask;
-  return mask.trim().split("\n").map((row) => row.replace(/\r/g, ""));
-};
-const parseAoeMask = (mask) => {
-  const rows = normalizeMaskRows(mask);
-  const height = rows.length;
-  const width = rows.reduce((max, row) => Math.max(max, row.length), 0);
-  const centerX = Math.floor(width / 2);
-  const centerY = Math.floor(height / 2);
-  const cells = [];
-  rows.forEach((row, y) => {
-    for (let x = 0; x < row.length; x++) {
-      const char = row[x];
-      if (char && char !== "." && char !== " ") {
-        cells.push({ dx: x - centerX, dy: y - centerY });
-      }
-    }
-  });
-  if (cells.length === 0) {
-    cells.push({ dx: 0, dy: 0 });
-  }
-  return { width, height, centerX, centerY, cells };
-};
-const manhattanDistance = (a, b) => Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
-export {
-  manhattanDistance,
-  parseAoeMask
+//#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 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
+	};
+};
+var defaultKnockbackResolver = (context) => {
+	const weapon = context.weapon ?? resolveEquippedWeapon(context.attacker);
+	return {
+		force: weapon?.knockbackForce ?? DEFAULT_CORE_KNOCKBACK.force,
+		duration: weapon?.knockbackDuration ?? DEFAULT_CORE_KNOCKBACK.duration,
+		direction: resolveDirection(context.attacker, context.target)
+	};
+};
+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 }
+};
+//#endregion
+export { DEFAULT_ZELDA_PLAYER_HITBOXES, createDefaultPlayerHitboxResolver, defaultActionBattleSystems, defaultCombatSystem, defaultEnemyBehaviors, defaultKnockbackResolver, defaultRpgjsDamageResolver };

package/dist/client/index11.js

@@ -0,0 +1,25 @@
+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);
+};
+var getActionBattleSystems = () => currentActionBattleSystems;
+var createActionBattleSystems = mergeSystems;
+//#endregion
+export { createActionBattleSystems, getActionBattleSystems, setActionBattleSystems };