@rpgjs/action-battle 5.0.0-beta.11 → 5.0.0-beta.13

package/src/core/contracts.ts

@@ -1,9 +1,114 @@
 import type { RpgEvent, RpgPlayer } from "@rpgjs/server";
 import type { AttackPattern, EnemyType, AiState } from "../ai.server";
 import type { NormalizedActionBattleHitReactionProfile } from "../types";
+import type {
+  ActionBattleAiIntent,
+  ActionBattleAiSimpleBehavior,
+  ActionBattleAiTreeInput,
+} from "./ai-behavior-tree";
 
 export type ActionBattleEntity = RpgPlayer | RpgEvent;
 
+export type ActionBattleTargetSelector =
+  | "players"
+  | "events"
+  | "all"
+  | "hostile"
+  | string[]
+  | ((context: ActionBattleTargetContext) => boolean);
+
+export interface ActionBattleTargetContext {
+  attacker: ActionBattleEntity;
+  target: ActionBattleEntity;
+  attackerFaction?: string;
+  targetFaction?: string;
+}
+
+export interface ActionBattleTargetOptions {
+  faction?: string;
+  targets?: ActionBattleTargetSelector;
+  getFaction?: (entity: ActionBattleEntity) => string | undefined;
+  canTarget?: (context: ActionBattleTargetContext) => boolean;
+}
+
+export type ActionBattleActionMode = "instant" | "melee" | "projectile";
+
+export type ActionBattleActionTarget = "enemy" | "ally" | "self" | "any";
+
+export interface ActionBattleProjectileOptions {
+  type: string;
+  speed?: number;
+  range?: number;
+  /**
+   * Random direction offset in degrees, applied as +/- half this value.
+   * Useful for less accurate ranged attacks.
+   */
+  spreadDegrees?: number;
+  /**
+   * Convenience precision value from 0 to 1. Ignored when `spreadDegrees` is set.
+   * `1` is perfectly accurate, `0` can deviate up to 30 degrees.
+   */
+  accuracy?: number;
+  trajectory?: any;
+  direction?: { x: number; y: number };
+  origin?: { x: number; y: number };
+  collision?: any;
+  repeat?: any;
+  pattern?: any;
+  payload?: Record<string, unknown>;
+  params?: Record<string, unknown>;
+  onImpact?: (
+    context: ActionBattleProjectileImpactContext,
+    action: ActionBattleUseContext
+  ) => void;
+}
+
+export interface ActionBattleActionConfig {
+  target?: ActionBattleActionTarget;
+  range?: number;
+  cooldownMs?: number;
+  mode?: ActionBattleActionMode;
+  projectile?: Omit<ActionBattleProjectileOptions, "onImpact">;
+}
+
+export interface ActionBattleProjectileImpactContext {
+  attacker: ActionBattleEntity;
+  target?: ActionBattleEntity;
+  projectile: any;
+  hit: any;
+  map: any;
+}
+
+export interface ActionBattleUseContext {
+  attacker: ActionBattleEntity;
+  user: ActionBattleEntity;
+  target?: ActionBattleEntity | ActionBattleEntity[] | null;
+  usable: any;
+  skill?: any;
+  weapon?: any;
+  action?: ActionBattleActionConfig;
+  pattern?: AttackPattern | string;
+  defaultEffect(target?: ActionBattleEntity | ActionBattleEntity[] | null): any;
+  damage(target?: ActionBattleEntity | null): any;
+  heal(
+    target: ActionBattleEntity | ActionBattleEntity[] | null | undefined,
+    amount: number
+  ): number;
+  projectile(options?: ActionBattleProjectileOptions): any[];
+}
+
+export interface ActionBattleUsable {
+  id?: string;
+  _type?: string;
+  action?: ActionBattleActionConfig;
+  actionBattle?: ActionBattleActionConfig;
+  onUse?: (
+    user: ActionBattleEntity,
+    target: ActionBattleEntity | ActionBattleEntity[] | null | undefined,
+    action: ActionBattleUseContext
+  ) => any;
+}
+
 export interface ActionBattleHitbox {
   x: number;
   y: number;
@@ -98,7 +203,7 @@ export interface ActionBattleCombatSystem {
 
 export interface ActionBattleAiContext {
   event: RpgEvent;
-  target: RpgPlayer | null;
+  target: ActionBattleEntity | null;
   state: AiState;
   enemyType: EnemyType;
   distance: number | null;
@@ -111,6 +216,7 @@ export interface ActionBattleAiDecision {
   attackPatterns?: AttackPattern[];
   attackCooldown?: number;
   moveToCooldown?: number;
+  intent?: ActionBattleAiIntent | ActionBattleAiIntent[];
   metadata?: Record<string, any>;
 }
 
@@ -118,9 +224,48 @@ export type ActionBattleAiBehavior = (
   context: ActionBattleAiContext
 ) => ActionBattleAiDecision | void;
 
+export interface ActionBattleAiPreset {
+  preset?: string | ActionBattleAiPreset;
+  faction?: string;
+  targets?: ActionBattleTargetSelector;
+  enemyType?: EnemyType;
+  attackCooldown?: number;
+  visionRange?: number;
+  attackRange?: number;
+  dodgeChance?: number;
+  dodgeCooldown?: number;
+  fleeThreshold?: number;
+  attackSkill?: any;
+  attackPatterns?: AttackPattern[];
+  attackProfiles?: any;
+  patrolWaypoints?: Array<{ x: number; y: number }>;
+  groupBehavior?: boolean;
+  moveToCooldown?: number;
+  retreatCooldown?: number;
+  poise?: number;
+  hitstunMs?: number;
+  invincibilityMs?: number;
+  behavior?: {
+    baseScore?: number;
+    updateInterval?: number;
+    minStateDuration?: number;
+    assaultThreshold?: number;
+    retreatThreshold?: number;
+  };
+  behaviorKey?: string;
+  tree?: ActionBattleAiTreeInput;
+  behaviorTree?: ActionBattleAiTreeInput;
+  simpleBehavior?: ActionBattleAiSimpleBehavior;
+  animations?: any;
+  rewards?: any;
+  autoAwardRewards?: boolean;
+  onDefeated?: any;
+}
+
 export interface ActionBattleSystems {
   combat: ActionBattleCombatSystem;
   ai: {
     behaviors: Record<string, ActionBattleAiBehavior>;
+    presets: Record<string, ActionBattleAiPreset>;
   };
 }

package/src/core/defaults.ts

@@ -1,6 +1,7 @@
 import type { RpgPlayer } from "@rpgjs/server";
 import type {
   ActionBattleAiBehavior,
+  ActionBattleAiPreset,
   ActionBattleAttackContext,
   ActionBattleCombatSystem,
   ActionBattleDamageContext,
@@ -84,9 +85,24 @@ export const defaultRpgjsDamageResolver = (
   context: ActionBattleDamageContext
 ) => {
   const target = context.target as any;
+  const previousHp =
+    typeof target.hp === "number" && Number.isFinite(target.hp)
+      ? target.hp
+      : undefined;
   const raw = target.applyDamage(context.attacker as any, context.skill);
+  const resolvedDamage = Number(raw?.damage ?? 0);
+  if (!Number.isFinite(resolvedDamage)) {
+    if (previousHp !== undefined) {
+      target.hp = previousHp;
+    }
+    return {
+      damage: 0,
+      defeated: false,
+      raw,
+    };
+  }
   return {
-    damage: raw?.damage ?? 0,
+    damage: resolvedDamage,
     defeated: target.hp <= 0,
     raw,
   };
@@ -146,10 +162,65 @@ export const defaultEnemyBehaviors: Record<string, ActionBattleAiBehavior> = {
   }),
 };
 
+export const defaultEnemyPresets: Record<string, ActionBattleAiPreset> = {
+  [CoreEnemyType.Aggressive]: {
+    enemyType: CoreEnemyType.Aggressive as any,
+    attackCooldown: 600,
+    visionRange: 150,
+    attackRange: 50,
+    dodgeChance: 0.1,
+    dodgeCooldown: 3000,
+    fleeThreshold: 0.15,
+    behaviorKey: CoreEnemyType.Aggressive,
+  },
+  [CoreEnemyType.Defensive]: {
+    enemyType: CoreEnemyType.Defensive as any,
+    attackCooldown: 1500,
+    visionRange: 120,
+    attackRange: 60,
+    dodgeChance: 0.5,
+    dodgeCooldown: 1500,
+    fleeThreshold: 0.3,
+    behaviorKey: CoreEnemyType.Defensive,
+  },
+  [CoreEnemyType.Ranged]: {
+    enemyType: CoreEnemyType.Ranged as any,
+    attackCooldown: 1200,
+    visionRange: 200,
+    attackRange: 120,
+    dodgeChance: 0.4,
+    dodgeCooldown: 2000,
+    fleeThreshold: 0.25,
+    behaviorKey: CoreEnemyType.Ranged,
+  },
+  [CoreEnemyType.Tank]: {
+    enemyType: CoreEnemyType.Tank as any,
+    attackCooldown: 2000,
+    visionRange: 100,
+    attackRange: 50,
+    dodgeChance: 0,
+    dodgeCooldown: 5000,
+    fleeThreshold: 0.1,
+    poise: 2,
+    behaviorKey: CoreEnemyType.Tank,
+  },
+  [CoreEnemyType.Berserker]: {
+    enemyType: CoreEnemyType.Berserker as any,
+    attackCooldown: 800,
+    visionRange: 180,
+    attackRange: 55,
+    dodgeChance: 0.15,
+    dodgeCooldown: 2500,
+    fleeThreshold: 0.05,
+    behaviorKey: CoreEnemyType.Berserker,
+  },
+};
+
 export const defaultActionBattleSystems: ActionBattleSystems = {
   combat: defaultCombatSystem,
   ai: {
     behaviors: defaultEnemyBehaviors,
+    presets: defaultEnemyPresets,
   },
 };
 

package/src/core/equipment.ts

@@ -2,16 +2,20 @@ import type { ActionBattleAttackProfile } from "../types";
 
 const resolveItemId = (item: any) => item?.id?.() ?? item?.id;
 
-export function resolveActionBattleWeaponAttackProfile(
-  entity: any
-): ActionBattleAttackProfile | null {
+export function resolveActionBattleWeapon(entity: any): any | null {
   const equipments = entity?.equipments?.() || [];
   for (const item of equipments) {
     const itemId = resolveItemId(item);
     const itemData = entity?.databaseById?.(itemId);
-    if (itemData?._type === "weapon" && itemData.attackProfile) {
-      return itemData.attackProfile;
+    if (itemData?._type === "weapon") {
+      return itemData;
     }
   }
   return null;
 }
+
+export function resolveActionBattleWeaponAttackProfile(
+  entity: any
+): ActionBattleAttackProfile | null {
+  return resolveActionBattleWeapon(entity)?.attackProfile ?? null;
+}

package/src/core/hit.spec.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, test, vi } from "vitest";
 import { applyActionBattleHit } from "./hit";
+import { defaultRpgjsDamageResolver } from "./defaults";
 import type { ActionBattleCombatSystem } from "./contracts";
 import { setActionBattleInvincibility } from "./hit-reaction";
 
@@ -108,4 +109,24 @@ describe("applyActionBattleHit", () => {
       target: target as any,
     }).cancelled).toBe(true);
   });
+
+  test("normalizes invalid RPGJS damage without poisoning target hp", () => {
+    const attacker = entity();
+    const target = {
+      ...entity(100),
+      applyDamage() {
+        this.hp = Number.NaN;
+        return { damage: Number.NaN };
+      },
+    };
+
+    const result = defaultRpgjsDamageResolver({
+      attacker: attacker as any,
+      target: target as any,
+    });
+
+    expect(result.damage).toBe(0);
+    expect(result.defeated).toBe(false);
+    expect(target.hp).toBe(100);
+  });
 });

package/src/core/targets.spec.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test } from "vitest";
+import { RpgEvent } from "@rpgjs/server";
+import { BattleAi } from "../ai.server";
+import {
+  canActionBattleTarget,
+  getActionBattleEntityKind,
+  getActionBattleFaction,
+  getActionBattleTargets,
+} from "./targets";
+
+const player = (id: string, faction?: string) =>
+  ({
+    id,
+    hp: 100,
+    actionBattleFaction: faction,
+  }) as any;
+
+const battleEvent = (id: string, faction?: string) =>
+  ({
+    id,
+    hp: 100,
+    actionBattleFaction: faction,
+    battleAi: {
+      getFaction: () => faction,
+      getTargets: () => "players",
+    },
+    attachShape() {},
+  }) as any;
+
+describe("action battle targets", () => {
+  test("keeps player default targets on action battle events", () => {
+    const attacker = player("player-1");
+    const target = battleEvent("enemy-1", "enemies");
+
+    expect(getActionBattleTargets(attacker, "events")).toBe("events");
+    expect(canActionBattleTarget(attacker, target, "events")).toBe(true);
+    expect(canActionBattleTarget(attacker, player("player-2"), "events")).toBe(false);
+  });
+
+  test("classifies runtime RpgEvent enemies before their RpgPlayer base class", () => {
+    const attacker = player("player-1");
+    const target = new RpgEvent() as any;
+    target.id = "enemy-1";
+    target.hp = 100;
+    target.battleAi = {
+      getFaction: () => "enemies",
+      getTargets: () => "players",
+    };
+
+    expect(getActionBattleEntityKind(target)).toBe("event");
+    expect(canActionBattleTarget(attacker, target, "events")).toBe(true);
+    expect(canActionBattleTarget(attacker, target, "players")).toBe(false);
+  });
+
+  test("classifies runtime players with shape helpers as players", () => {
+    const attacker = battleEvent("enemy-1", "enemies");
+    const target = {
+      ...player("player-1"),
+      attachShape() {},
+      isEvent: () => false,
+    };
+
+    expect(getActionBattleEntityKind(target as any)).toBe("player");
+    expect(canActionBattleTarget(attacker, target as any, "players")).toBe(true);
+  });
+
+  test("supports player targets explicitly", () => {
+    const attacker = player("player-1");
+    const target = player("player-2");
+
+    expect(canActionBattleTarget(attacker, target, "players")).toBe(true);
+  });
+
+  test("supports all targets", () => {
+    const attacker = battleEvent("enemy-1", "enemies");
+
+    expect(canActionBattleTarget(attacker, player("player-1"), "all")).toBe(true);
+    expect(canActionBattleTarget(attacker, battleEvent("enemy-2", "enemies"), "all")).toBe(true);
+  });
+
+  test("supports hostile targets from different factions", () => {
+    const guard = battleEvent("guard-1", "guards");
+    const guardAlly = battleEvent("guard-2", "guards");
+    const bandit = battleEvent("bandit-1", "bandits");
+
+    expect(canActionBattleTarget(guard, guardAlly, "hostile")).toBe(false);
+    expect(canActionBattleTarget(guard, bandit, "hostile")).toBe(true);
+  });
+
+  test("supports explicit faction target lists", () => {
+    const guard = battleEvent("guard-1", "guards");
+    const bandit = battleEvent("bandit-1", "bandits");
+    const monster = battleEvent("monster-1", "monsters");
+
+    expect(canActionBattleTarget(guard, bandit, ["bandits"])).toBe(true);
+    expect(canActionBattleTarget(guard, monster, ["bandits"])).toBe(false);
+  });
+
+  test("BattleAi exposes runtime faction and targets", () => {
+    const event = {
+      id: "guard-1",
+      hp: 100,
+      param: {},
+      attachShape: () => ({ id: "vision_guard-1" }),
+      getCurrentMap: () => ({}),
+      stopMoveTo() {},
+    };
+    const ai = new BattleAi(event as any, {
+      faction: "guards",
+      targets: ["bandits"],
+    });
+
+    expect(getActionBattleFaction(event as any)).toBe("guards");
+    expect(getActionBattleTargets(event as any, "players")).toEqual(["bandits"]);
+
+    ai.setFaction("bandits");
+    ai.setTargets("hostile");
+
+    expect(getActionBattleFaction(event as any)).toBe("bandits");
+    expect(getActionBattleTargets(event as any, "players")).toBe("hostile");
+
+    ai.destroy();
+  });
+});

package/src/core/targets.ts

@@ -0,0 +1,150 @@
+import { RpgEvent, RpgPlayer } from "@rpgjs/server";
+import type {
+  ActionBattleEntity,
+  ActionBattleTargetContext,
+  ActionBattleTargetOptions,
+  ActionBattleTargetSelector,
+} from "./contracts";
+
+export const ACTION_BATTLE_PLAYER_FACTION = "players";
+export const ACTION_BATTLE_ENEMY_FACTION = "enemies";
+
+type EntityKind = "player" | "event";
+
+const getBattleAi = (entity: ActionBattleEntity) => (entity as any)?.battleAi;
+
+export const getActionBattleEntityKind = (
+  entity: ActionBattleEntity
+): EntityKind => {
+  if (getBattleAi(entity)) return "event";
+  if (typeof (entity as any)?.isEvent === "function") {
+    return (entity as any).isEvent() ? "event" : "player";
+  }
+  if ((entity as any) instanceof RpgEvent) return "event";
+  if ((entity as any) instanceof RpgPlayer) return "player";
+  if (typeof (entity as any)?.attachShape === "function") return "event";
+  return "player";
+};
+
+export const isActionBattlePlayer = (entity: ActionBattleEntity): boolean =>
+  getActionBattleEntityKind(entity) === "player";
+
+export const isActionBattleEvent = (entity: ActionBattleEntity): boolean =>
+  getActionBattleEntityKind(entity) === "event";
+
+export const isActionBattleCombatEntity = (
+  entity: ActionBattleEntity | undefined | null
+): entity is ActionBattleEntity => {
+  if (!entity) return false;
+  if (isActionBattlePlayer(entity as ActionBattleEntity)) return true;
+  return !!getBattleAi(entity as ActionBattleEntity);
+};
+
+export const getActionBattleFaction = (
+  entity: ActionBattleEntity,
+  options: ActionBattleTargetOptions = {}
+): string | undefined => {
+  const configured = options.getFaction?.(entity);
+  if (configured !== undefined) return configured;
+
+  const battleAi = getBattleAi(entity);
+  if (battleAi && typeof battleAi.getFaction === "function") {
+    const faction = battleAi.getFaction();
+    if (faction !== undefined) return faction;
+  }
+
+  const entityFaction =
+    (entity as any).actionBattleFaction ?? (entity as any).faction;
+  if (entityFaction !== undefined) return String(entityFaction);
+
+  if (isActionBattlePlayer(entity)) return ACTION_BATTLE_PLAYER_FACTION;
+  if (battleAi) return ACTION_BATTLE_ENEMY_FACTION;
+  return undefined;
+};
+
+export const getActionBattleTargets = (
+  entity: ActionBattleEntity,
+  fallback: ActionBattleTargetSelector
+): ActionBattleTargetSelector => {
+  const battleAi = getBattleAi(entity);
+  if (battleAi && typeof battleAi.getTargets === "function") {
+    return battleAi.getTargets();
+  }
+  return (entity as any).actionBattleTargets ?? fallback;
+};
+
+export const isActionBattleTargetDefeated = (
+  target: ActionBattleEntity | null | undefined
+): boolean => {
+  if (!target) return true;
+  const hp = (target as any).hp;
+  return typeof hp === "number" && hp <= 0;
+};
+
+export const matchesActionBattleTargetSelector = (
+  selector: ActionBattleTargetSelector | undefined,
+  context: ActionBattleTargetContext
+): boolean => {
+  if (!selector) return false;
+  if (typeof selector === "function") return selector(context);
+  if (selector === "all") return true;
+  if (selector === "players") return isActionBattlePlayer(context.target);
+  if (selector === "events") return isActionBattleEvent(context.target);
+  if (selector === "hostile") {
+    return (
+      !!context.attackerFaction &&
+      !!context.targetFaction &&
+      context.attackerFaction !== context.targetFaction
+    );
+  }
+  if (Array.isArray(selector)) {
+    return !!context.targetFaction && selector.includes(context.targetFaction);
+  }
+  return false;
+};
+
+export const canActionBattleTarget = (
+  attacker: ActionBattleEntity,
+  target: ActionBattleEntity,
+  selector: ActionBattleTargetSelector | undefined,
+  options: ActionBattleTargetOptions = {}
+): boolean => {
+  if (attacker === target) return false;
+  if (!isActionBattleCombatEntity(target)) return false;
+  if (isActionBattleTargetDefeated(target)) return false;
+
+  const context: ActionBattleTargetContext = {
+    attacker,
+    target,
+    attackerFaction: getActionBattleFaction(attacker, options),
+    targetFaction: getActionBattleFaction(target, options),
+  };
+
+  const allowed = options.canTarget?.(context);
+  if (allowed !== undefined) return allowed;
+
+  return matchesActionBattleTargetSelector(selector, context);
+};
+
+export const getActionBattleEntitiesInRange = (
+  attacker: ActionBattleEntity,
+  radius: number,
+  selector: ActionBattleTargetSelector | undefined,
+  options: ActionBattleTargetOptions = {}
+): ActionBattleEntity[] => {
+  const map = (attacker as any).getCurrentMap?.();
+  if (!map) return [];
+
+  const candidates: ActionBattleEntity[] = [];
+  map.getPlayers?.().forEach((player: RpgPlayer) => candidates.push(player));
+  map.getEvents?.().forEach((event: RpgEvent) => candidates.push(event));
+
+  return candidates.filter((candidate) => {
+    if (!canActionBattleTarget(attacker, candidate, selector, options)) {
+      return false;
+    }
+    const dx = (attacker as any).x() - (candidate as any).x();
+    const dy = (attacker as any).y() - (candidate as any).y();
+    return Math.sqrt(dx * dx + dy * dy) <= radius;
+  });
+};

package/src/enemies/factory.ts

@@ -7,6 +7,14 @@ export interface ActionBattleEnemyPreset extends BattleAiOptions {
 
 export type ActionBattleEnemyPresetMap = Record<string, ActionBattleEnemyPreset>;
 
+export const defineActionBattleEnemy = <T extends ActionBattleEnemyPreset>(
+  preset: T
+): T => preset;
+
+export const defineActionBattleAiPreset = <T extends BattleAiOptions>(
+  preset: T
+): T => preset;
+
 export const createActionEnemy = (
   event: RpgEvent,
   presetOrOptions: string | BattleAiOptions,