@rpgjs/action-battle 5.0.0-beta.1 → 5.0.0-beta.10

package/src/core/enemy-attack-profiles.ts

@@ -0,0 +1,103 @@
+import type {
+  ActionBattleAttackProfile,
+  NormalizedActionBattleAttackProfile,
+} from "../types";
+import { normalizeActionBattleAttackProfile } from "./attack-profile";
+
+export type ActionBattleEnemyAttackProfileKey =
+  | "melee"
+  | "combo"
+  | "charged"
+  | "zone"
+  | "dashAttack";
+
+export const DEFAULT_ACTION_BATTLE_ENEMY_ATTACK_PROFILES: Record<
+  ActionBattleEnemyAttackProfileKey,
+  ActionBattleAttackProfile
+> = {
+  melee: {
+    id: "enemy-melee",
+    startupMs: 120,
+    activeMs: 100,
+    recoveryMs: 220,
+    cooldownMs: 440,
+    reaction: {
+      invincibilityMs: 250,
+      hitstunMs: 120,
+      staggerPower: 1,
+    },
+  },
+  combo: {
+    id: "enemy-combo",
+    startupMs: 80,
+    activeMs: 80,
+    recoveryMs: 140,
+    cooldownMs: 300,
+    reaction: {
+      invincibilityMs: 180,
+      hitstunMs: 90,
+      staggerPower: 0.75,
+    },
+  },
+  charged: {
+    id: "enemy-charged",
+    startupMs: 800,
+    activeMs: 140,
+    recoveryMs: 320,
+    cooldownMs: 1260,
+    reaction: {
+      invincibilityMs: 350,
+      hitstunMs: 220,
+      staggerPower: 2,
+    },
+  },
+  zone: {
+    id: "enemy-zone",
+    startupMs: 450,
+    activeMs: 180,
+    recoveryMs: 320,
+    cooldownMs: 950,
+    reaction: {
+      invincibilityMs: 300,
+      hitstunMs: 160,
+      staggerPower: 1.25,
+    },
+  },
+  dashAttack: {
+    id: "enemy-dash",
+    startupMs: 180,
+    activeMs: 120,
+    recoveryMs: 260,
+    cooldownMs: 560,
+    reaction: {
+      invincibilityMs: 280,
+      hitstunMs: 150,
+      staggerPower: 1.2,
+    },
+  },
+};
+
+export type ActionBattleEnemyAttackProfileMap = Partial<
+  Record<ActionBattleEnemyAttackProfileKey, ActionBattleAttackProfile>
+>;
+
+export type NormalizedActionBattleEnemyAttackProfileMap = Record<
+  ActionBattleEnemyAttackProfileKey,
+  NormalizedActionBattleAttackProfile
+>;
+
+export function normalizeActionBattleEnemyAttackProfiles(
+  overrides: ActionBattleEnemyAttackProfileMap = {}
+): NormalizedActionBattleEnemyAttackProfileMap {
+  return Object.fromEntries(
+    Object.entries(DEFAULT_ACTION_BATTLE_ENEMY_ATTACK_PROFILES).map(
+      ([key, defaultProfile]) => [
+        key,
+        normalizeActionBattleAttackProfile({
+          ...defaultProfile,
+          ...overrides[key as ActionBattleEnemyAttackProfileKey],
+        }),
+      ]
+    )
+  ) as NormalizedActionBattleEnemyAttackProfileMap;
+}

package/src/core/equipment.spec.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "vitest";
+import { resolveActionBattleWeaponAttackProfile } from "./equipment";
+
+describe("equipment helpers", () => {
+  test("resolves attack profile from equipped weapon data", () => {
+    const attackProfile = {
+      id: "dagger",
+      startupMs: 40,
+      activeMs: 70,
+      recoveryMs: 120,
+    };
+    const entity = {
+      equipments: () => [{ id: () => "dagger" }],
+      databaseById: (id: string) =>
+        id === "dagger"
+          ? {
+              _type: "weapon",
+              attackProfile,
+            }
+          : null,
+    };
+
+    expect(resolveActionBattleWeaponAttackProfile(entity)).toBe(attackProfile);
+  });
+
+  test("ignores non-weapon equipment", () => {
+    const entity = {
+      equipments: () => [{ id: () => "ring" }],
+      databaseById: () => ({
+        _type: "armor",
+        attackProfile: { id: "invalid" },
+      }),
+    };
+
+    expect(resolveActionBattleWeaponAttackProfile(entity)).toBeNull();
+  });
+});

package/src/core/equipment.ts

@@ -0,0 +1,17 @@
+import type { ActionBattleAttackProfile } from "../types";
+
+const resolveItemId = (item: any) => item?.id?.() ?? item?.id;
+
+export function resolveActionBattleWeaponAttackProfile(
+  entity: any
+): ActionBattleAttackProfile | 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;
+    }
+  }
+  return null;
+}

package/src/core/hit-reaction.spec.ts

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import {
+  DEFAULT_ACTION_BATTLE_HIT_REACTION,
+  isActionBattleEntityInvincible,
+  normalizeActionBattleHitReaction,
+  setActionBattleInvincibility,
+} from "./hit-reaction";
+
+describe("hit reaction helpers", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("normalizes hit reaction defaults", () => {
+    expect(normalizeActionBattleHitReaction(undefined)).toEqual(
+      DEFAULT_ACTION_BATTLE_HIT_REACTION
+    );
+  });
+
+  test("normalizes unsafe reaction values", () => {
+    expect(
+      normalizeActionBattleHitReaction({
+        invincibilityMs: -10,
+        hitstunMs: -20,
+        staggerPower: -1,
+      })
+    ).toEqual({
+      invincibilityMs: 0,
+      hitstunMs: 0,
+      staggerPower: 0,
+    });
+  });
+
+  test("tracks invincibility windows on entities", () => {
+    const entity = {};
+    vi.spyOn(Date, "now").mockReturnValue(1000);
+
+    setActionBattleInvincibility(entity, 250);
+
+    expect(isActionBattleEntityInvincible(entity, 1100)).toBe(true);
+    expect(isActionBattleEntityInvincible(entity, 1300)).toBe(false);
+  });
+});

package/src/core/hit-reaction.ts

@@ -0,0 +1,70 @@
+import type {
+  ActionBattleHitReactionProfile,
+  NormalizedActionBattleHitReactionProfile,
+} from "../types";
+
+export const DEFAULT_ACTION_BATTLE_HIT_REACTION: NormalizedActionBattleHitReactionProfile = {
+  invincibilityMs: 250,
+  hitstunMs: 150,
+  staggerPower: 1,
+};
+
+const STATE_KEY = "__actionBattleHitReaction";
+
+interface ActionBattleHitReactionRuntimeState {
+  invincibleUntil: number;
+}
+
+const isFiniteNumber = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value);
+
+const nonNegativeMs = (value: unknown, fallback: number) =>
+  isFiniteNumber(value) ? Math.max(0, value) : fallback;
+
+const nonNegativeValue = (value: unknown, fallback: number) =>
+  isFiniteNumber(value) ? Math.max(0, value) : fallback;
+
+const getRuntimeState = (entity: any): ActionBattleHitReactionRuntimeState => {
+  if (!entity[STATE_KEY]) {
+    entity[STATE_KEY] = {
+      invincibleUntil: 0,
+    };
+  }
+  return entity[STATE_KEY];
+};
+
+export function normalizeActionBattleHitReaction(
+  reaction: ActionBattleHitReactionProfile | undefined,
+  defaults: NormalizedActionBattleHitReactionProfile =
+    DEFAULT_ACTION_BATTLE_HIT_REACTION
+): NormalizedActionBattleHitReactionProfile {
+  return {
+    invincibilityMs: nonNegativeMs(
+      reaction?.invincibilityMs,
+      defaults.invincibilityMs
+    ),
+    hitstunMs: nonNegativeMs(reaction?.hitstunMs, defaults.hitstunMs),
+    staggerPower: nonNegativeValue(
+      reaction?.staggerPower,
+      defaults.staggerPower
+    ),
+  };
+}
+
+export function isActionBattleEntityInvincible(
+  entity: any,
+  now = Date.now()
+): boolean {
+  if (!entity) return false;
+  return getRuntimeState(entity).invincibleUntil > now;
+}
+
+export function setActionBattleInvincibility(
+  entity: any,
+  durationMs: number,
+  now = Date.now()
+): void {
+  if (!entity || durationMs <= 0) return;
+  const state = getRuntimeState(entity);
+  state.invincibleUntil = Math.max(state.invincibleUntil, now + durationMs);
+}

package/src/core/hit.spec.ts

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { applyActionBattleHit } from "./hit";
+import type { ActionBattleCombatSystem } from "./contracts";
+import { setActionBattleInvincibility } from "./hit-reaction";
+
+const entity = (hp = 100) => ({
+  hp,
+  x: () => 0,
+  y: () => 0,
+  knockback: vi.fn(),
+});
+
+describe("applyActionBattleHit", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("runs beforeHit before resolving damage", () => {
+    const calls: string[] = [];
+    const attacker = entity();
+    const target = entity();
+    const system: ActionBattleCombatSystem = {
+      resolveHitboxes: () => [],
+      resolveDamage: () => {
+        calls.push("damage");
+        return { damage: 12, defeated: false };
+      },
+      resolveKnockback: () => ({ force: 0, duration: 0 }),
+      hooks: {
+        beforeHit() {
+          calls.push("before");
+        },
+        afterHit() {
+          calls.push("after");
+        },
+      },
+    };
+
+    const result = applyActionBattleHit(system, { attacker: attacker as any, target: target as any });
+
+    expect(result.damage).toBe(12);
+    expect(calls).toEqual(["before", "damage", "after"]);
+  });
+
+  test("can cancel a hit before damage is resolved", () => {
+    const resolveDamage = vi.fn();
+    const attacker = entity();
+    const target = entity();
+    const system: ActionBattleCombatSystem = {
+      resolveHitboxes: () => [],
+      resolveDamage,
+      resolveKnockback: () => ({ force: 0, duration: 0 }),
+      hooks: {
+        beforeHit: () => false,
+      },
+    };
+
+    const result = applyActionBattleHit(system, { attacker: attacker as any, target: target as any });
+
+    expect(result.cancelled).toBe(true);
+    expect(resolveDamage).not.toHaveBeenCalled();
+  });
+
+  test("cancels a hit when the target is invincible", () => {
+    const resolveDamage = vi.fn();
+    const attacker = entity();
+    const target = entity();
+    setActionBattleInvincibility(target, 500, 1000);
+    vi.spyOn(Date, "now").mockReturnValue(1100);
+    const system: ActionBattleCombatSystem = {
+      resolveHitboxes: () => [],
+      resolveDamage,
+      resolveKnockback: () => ({ force: 0, duration: 0 }),
+    };
+
+    const result = applyActionBattleHit(system, {
+      attacker: attacker as any,
+      target: target as any,
+    });
+
+    expect(result.cancelled).toBe(true);
+    expect(resolveDamage).not.toHaveBeenCalled();
+  });
+
+  test("applies invincibility from hit reaction after damage", () => {
+    vi.spyOn(Date, "now").mockReturnValue(2000);
+    const attacker = entity();
+    const target = entity();
+    const system: ActionBattleCombatSystem = {
+      resolveHitboxes: () => [],
+      resolveDamage: () => ({ damage: 12, defeated: false }),
+      resolveKnockback: () => ({ force: 0, duration: 0 }),
+    };
+
+    const result = applyActionBattleHit(system, {
+      attacker: attacker as any,
+      target: target as any,
+      reaction: {
+        invincibilityMs: 300,
+        hitstunMs: 120,
+        staggerPower: 1,
+      },
+    });
+
+    expect(result.cancelled).toBeUndefined();
+    expect(applyActionBattleHit(system, {
+      attacker: attacker as any,
+      target: target as any,
+    }).cancelled).toBe(true);
+  });
+});

package/src/core/hit.ts

@@ -0,0 +1,92 @@
+import type { ActionBattleCombatSystem, ActionBattleHitContext, ActionBattleHitResult } from "./contracts";
+import {
+  isActionBattleEntityInvincible,
+  setActionBattleInvincibility,
+} from "./hit-reaction";
+
+export const applyActionBattleHit = (
+  system: ActionBattleCombatSystem,
+  context: ActionBattleHitContext
+): ActionBattleHitResult => {
+  let hitContext = { ...context };
+  const before = system.hooks?.beforeHit?.(hitContext);
+  if (before === false) {
+    return {
+      damage: 0,
+      knockbackForce: 0,
+      knockbackDuration: 0,
+      defeated: false,
+      attacker: hitContext.attacker,
+      target: hitContext.target,
+      cancelled: true,
+      metadata: hitContext.metadata,
+    };
+  }
+  if (before) hitContext = before;
+
+  if (isActionBattleEntityInvincible(hitContext.target)) {
+    return {
+      damage: 0,
+      knockbackForce: 0,
+      knockbackDuration: 0,
+      defeated: false,
+      attacker: hitContext.attacker,
+      target: hitContext.target,
+      cancelled: true,
+      metadata: hitContext.metadata,
+      reaction: hitContext.reaction,
+    };
+  }
+
+  const damage =
+    hitContext.damage ??
+    system.resolveDamage({
+      attacker: hitContext.attacker,
+      target: hitContext.target,
+      skill: hitContext.skill,
+      pattern: hitContext.pattern,
+    });
+  hitContext.damage = damage;
+
+  const afterDamage = system.hooks?.afterDamage?.(hitContext);
+  if (afterDamage) hitContext = afterDamage;
+
+  const knockback =
+    hitContext.knockback ??
+    system.resolveKnockback({
+      attacker: hitContext.attacker,
+      target: hitContext.target,
+      damage,
+    });
+  hitContext.knockback = knockback;
+
+  if (!damage.defeated && knockback.force > 0 && knockback.direction) {
+    (hitContext.target as any).knockback?.(
+      knockback.direction,
+      knockback.force,
+      knockback.duration
+    );
+  }
+
+  if (!damage.defeated && hitContext.reaction?.invincibilityMs) {
+    setActionBattleInvincibility(
+      hitContext.target,
+      hitContext.reaction.invincibilityMs
+    );
+  }
+
+  const result: ActionBattleHitResult = {
+    damage: damage.damage,
+    knockbackForce: knockback.force,
+    knockbackDuration: knockback.duration,
+    defeated: damage.defeated,
+    attacker: hitContext.attacker,
+    target: hitContext.target,
+    rawDamage: damage.raw,
+    reaction: hitContext.reaction,
+    metadata: hitContext.metadata,
+  };
+
+  system.hooks?.afterHit?.(result);
+  return result;
+};

package/src/enemies/factory.ts

@@ -0,0 +1,25 @@
+import type { RpgEvent } from "@rpgjs/server";
+import { BattleAi, type BattleAiOptions } from "../ai.server";
+
+export interface ActionBattleEnemyPreset extends BattleAiOptions {
+  stats?: (event: RpgEvent) => void;
+}
+
+export type ActionBattleEnemyPresetMap = Record<string, ActionBattleEnemyPreset>;
+
+export const createActionEnemy = (
+  event: RpgEvent,
+  presetOrOptions: string | BattleAiOptions,
+  presets: ActionBattleEnemyPresetMap = {}
+) => {
+  const options =
+    typeof presetOrOptions === "string"
+      ? presets[presetOrOptions]
+      : presetOrOptions;
+  if (!options) {
+    throw new Error(`Action battle enemy preset not found: ${presetOrOptions}`);
+  }
+  const preset = options as ActionBattleEnemyPreset;
+  preset.stats?.(event);
+  return new BattleAi(event, options);
+};

package/src/index.ts

@@ -7,18 +7,111 @@ import type { ActionBattleOptions } from "./types";
 export { BattleAi, AiState, EnemyType, AttackPattern, AiDebug, DEFAULT_KNOCKBACK } from "./ai.server";
 
 // Types exports
-export type { HitResult, ApplyHitHooks } from "./ai.server";
 export type {
+  HitResult,
+  ApplyHitHooks,
+  BattleAiOptions,
+  BattleAiDefeatedCallback,
+  BattleAiDefeatedContext,
+  BattleAiDefeatReward,
+  BattleAiLegacyDefeatedCallback,
+  BattleAiLegacyOptions,
+  BattleAiRewardItem,
+  BattleAiRewards,
+} from "./ai.server";
+export type {
+  ActionBattleAnimationContext,
+  ActionBattleAnimationEntity,
+  ActionBattleAnimationKey,
+  ActionBattleAnimationOptions,
+  ActionBattleAnimationResolver,
+  ActionBattleAnimationResult,
   ActionBattleOptions,
   ActionBattleActionBarData,
   ActionBattleActionBarItem,
   ActionBattleActionBarSkill,
   ActionBattleSkillTargeting,
   ActionBattleSkillTargetingResolver,
+  ActionBattleAttackOptions,
   ActionBattleUiOptions,
   ActionBattleUiActionBarOptions,
   ActionBattleUiTargetingOptions,
+  ActionBattleAttackDirection,
+  ActionBattleAttackHitboxConfig,
+  ActionBattleAttackHitboxMap,
+  ActionBattleAttackHitPolicy,
+  ActionBattleAttackProfile,
+  ActionBattleDebugOptions,
+  ActionBattleHitReactionProfile,
+  NormalizedActionBattleHitReactionProfile,
+  NormalizedActionBattleAttackProfile,
+  ActionBattleCombatOptions,
+  ActionBattleSystemOptions,
+  ActionBattleAiSystemOptions,
 } from "./types";
+export type {
+  ActionBattleAiBehavior,
+  ActionBattleAiContext,
+  ActionBattleAiDecision,
+  ActionBattleAttackContext,
+  ActionBattleCombatSystem,
+  ActionBattleDamageContext,
+  ActionBattleDamageResult,
+  ActionBattleDirection,
+  ActionBattleEntity,
+  ActionBattleHitContext,
+  ActionBattleHitHooks,
+  ActionBattleHitResult,
+  ActionBattleHitbox,
+  ActionBattleKnockbackContext,
+  ActionBattleKnockbackResult,
+  ActionBattleSystems,
+} from "./core/contracts";
+export {
+  DEFAULT_ACTION_BATTLE_ATTACK_PROFILE,
+  normalizeActionBattleAttackProfile,
+  type ActionBattleAttackProfileFallbacks,
+} from "./core/attack-profile";
+export {
+  ACTION_BATTLE_HITBOX_FRAME_MS,
+  ActionBattleHitTracker,
+  createActionBattleAttackId,
+  getNormalizedActionBattleAttackProfile,
+  resolveActionBattleHitboxSpeed,
+  scheduleActionBattleStartup,
+} from "./core/attack-runtime";
+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 {
+  DEFAULT_ZELDA_PLAYER_HITBOXES,
+  createDefaultPlayerHitboxResolver,
+  defaultCombatSystem,
+  defaultEnemyBehaviors,
+  defaultKnockbackResolver,
+  defaultRpgjsDamageResolver,
+} from "./core/defaults";
+export {
+  createActionBattleSystems,
+  getActionBattleSystems,
+} from "./core/context";
+export { applyActionBattleHit } from "./core/hit";
+export {
+  createActionEnemy,
+  type ActionBattleEnemyPreset,
+  type ActionBattleEnemyPresetMap,
+} from "./enemies/factory";
 
 // Server exports
 export {