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

package/src/core/attack-profile.ts

@@ -0,0 +1,100 @@
+import type {
+  ActionBattleAttackHitboxMap,
+  ActionBattleAttackHitPolicy,
+  ActionBattleAttackProfile,
+  ActionBattleAnimationKey,
+  NormalizedActionBattleAttackProfile,
+} from "../types";
+import {
+  DEFAULT_ACTION_BATTLE_HIT_REACTION,
+  normalizeActionBattleHitReaction,
+} from "./hit-reaction";
+
+export const DEFAULT_ACTION_BATTLE_ATTACK_PROFILE:
+  NormalizedActionBattleAttackProfile = {
+  id: "basic",
+  startupMs: 0,
+  activeMs: 120,
+  recoveryMs: 230,
+  cooldownMs: 350,
+  movementLock: true,
+  directionLock: true,
+  animationKey: "attack",
+  hitPolicy: "oncePerTarget",
+  reaction: DEFAULT_ACTION_BATTLE_HIT_REACTION,
+  totalDurationMs: 350,
+};
+
+export interface ActionBattleAttackProfileFallbacks {
+  id?: string;
+  lockMovement?: boolean;
+  lockDurationMs?: number;
+  hitboxes?: ActionBattleAttackHitboxMap;
+}
+
+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 positiveMs = (value: unknown, fallback: number) =>
+  isFiniteNumber(value) ? Math.max(1, value) : fallback;
+
+const resolveHitPolicy = (
+  value: ActionBattleAttackHitPolicy | undefined
+): ActionBattleAttackHitPolicy =>
+  value === "allowRepeatHits" ? "allowRepeatHits" : "oncePerTarget";
+
+const resolveAnimationKey = (
+  value: ActionBattleAnimationKey | undefined
+): ActionBattleAnimationKey =>
+  value ?? DEFAULT_ACTION_BATTLE_ATTACK_PROFILE.animationKey;
+
+export function normalizeActionBattleAttackProfile(
+  profile: ActionBattleAttackProfile | undefined = {},
+  fallbacks: ActionBattleAttackProfileFallbacks = {}
+): NormalizedActionBattleAttackProfile {
+  const startupMs = nonNegativeMs(
+    profile.startupMs,
+    DEFAULT_ACTION_BATTLE_ATTACK_PROFILE.startupMs
+  );
+  const activeMs = positiveMs(
+    profile.activeMs,
+    DEFAULT_ACTION_BATTLE_ATTACK_PROFILE.activeMs
+  );
+  const legacyDuration = nonNegativeMs(
+    fallbacks.lockDurationMs,
+    DEFAULT_ACTION_BATTLE_ATTACK_PROFILE.totalDurationMs
+  );
+  const fallbackRecoveryMs = Math.max(0, legacyDuration - startupMs - activeMs);
+  const recoveryMs = nonNegativeMs(profile.recoveryMs, fallbackRecoveryMs);
+  const totalDurationMs = startupMs + activeMs + recoveryMs;
+  const cooldownMs = nonNegativeMs(profile.cooldownMs, totalDurationMs);
+  const hitboxes = profile.hitboxes ?? fallbacks.hitboxes;
+
+  const normalized: NormalizedActionBattleAttackProfile = {
+    id: profile.id || fallbacks.id || DEFAULT_ACTION_BATTLE_ATTACK_PROFILE.id,
+    startupMs,
+    activeMs,
+    recoveryMs,
+    cooldownMs,
+    movementLock:
+      profile.movementLock ??
+      fallbacks.lockMovement ??
+      DEFAULT_ACTION_BATTLE_ATTACK_PROFILE.movementLock,
+    directionLock:
+      profile.directionLock ??
+      DEFAULT_ACTION_BATTLE_ATTACK_PROFILE.directionLock,
+    animationKey: resolveAnimationKey(profile.animationKey),
+    hitPolicy: resolveHitPolicy(profile.hitPolicy),
+    reaction: normalizeActionBattleHitReaction(profile.reaction),
+    totalDurationMs,
+  };
+
+  if (hitboxes) {
+    normalized.hitboxes = hitboxes;
+  }
+
+  return normalized;
+}

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

@@ -0,0 +1,103 @@
+import { describe, expect, test, vi } from "vitest";
+import {
+  ActionBattleHitTracker,
+  createActionBattleAttackId,
+  getNormalizedActionBattleAttackProfile,
+  resolveActionBattleHitboxSpeed,
+  scheduleActionBattleStartup,
+} from "./attack-runtime";
+
+describe("attack runtime helpers", () => {
+  test("resolves a normalized profile from action battle options", () => {
+    const profile = getNormalizedActionBattleAttackProfile({
+      attack: {
+        lockDurationMs: 420,
+        profile: {
+          startupMs: 100,
+          activeMs: 80,
+        },
+      },
+    });
+
+    expect(profile).toMatchObject({
+      startupMs: 100,
+      activeMs: 80,
+      recoveryMs: 240,
+      totalDurationMs: 420,
+    });
+  });
+
+  test("maps activeMs to moving hitbox speed", () => {
+    const profile = getNormalizedActionBattleAttackProfile({
+      attack: {
+        profile: {
+          activeMs: 96,
+        },
+      },
+    });
+
+    expect(resolveActionBattleHitboxSpeed(profile, 1)).toBe(6);
+    expect(resolveActionBattleHitboxSpeed(profile, 3)).toBe(2);
+  });
+
+  test("runs startup immediately when there is no wind-up", () => {
+    const callback = vi.fn();
+    const scheduler = vi.fn();
+    const profile = getNormalizedActionBattleAttackProfile({
+      attack: {
+        profile: {
+          startupMs: 0,
+        },
+      },
+    });
+
+    const timer = scheduleActionBattleStartup(profile, callback, scheduler);
+
+    expect(timer).toBeNull();
+    expect(callback).toHaveBeenCalledOnce();
+    expect(scheduler).not.toHaveBeenCalled();
+  });
+
+  test("schedules startup when wind-up is configured", () => {
+    const callback = vi.fn();
+    const scheduler = vi.fn(() => "timer-id");
+    const profile = getNormalizedActionBattleAttackProfile({
+      attack: {
+        profile: {
+          startupMs: 120,
+        },
+      },
+    });
+
+    const timer = scheduleActionBattleStartup(profile, callback, scheduler);
+
+    expect(timer).toBe("timer-id");
+    expect(callback).not.toHaveBeenCalled();
+    expect(scheduler).toHaveBeenCalledWith(callback, 120);
+  });
+
+  test("creates stable unique attack ids", () => {
+    const first = createActionBattleAttackId("player-1", "sword");
+    const second = createActionBattleAttackId("player-1", "sword");
+
+    expect(first).toContain("player-1:sword:");
+    expect(second).toContain("player-1:sword:");
+    expect(first).not.toBe(second);
+  });
+
+  test("tracks once-per-target hit policy", () => {
+    const tracker = new ActionBattleHitTracker("oncePerTarget");
+    const target = { id: "enemy-1" };
+
+    expect(tracker.tryHit(target)).toBe(true);
+    expect(tracker.tryHit(target)).toBe(false);
+  });
+
+  test("allows repeated hits when configured", () => {
+    const tracker = new ActionBattleHitTracker("allowRepeatHits");
+    const target = { id: "enemy-1" };
+
+    expect(tracker.tryHit(target)).toBe(true);
+    expect(tracker.tryHit(target)).toBe(true);
+  });
+});

package/src/core/attack-runtime.ts

@@ -0,0 +1,83 @@
+import type {
+  ActionBattleAttackHitPolicy,
+  ActionBattleOptions,
+  NormalizedActionBattleAttackProfile,
+} from "../types";
+import { normalizeActionBattleAttackProfile } from "./attack-profile";
+
+export const ACTION_BATTLE_HITBOX_FRAME_MS = 16;
+
+export function getNormalizedActionBattleAttackProfile(
+  options: ActionBattleOptions = {}
+): NormalizedActionBattleAttackProfile {
+  const attack = options.attack ?? {};
+  return normalizeActionBattleAttackProfile(attack.profile, {
+    lockMovement: attack.lockMovement,
+    lockDurationMs: attack.lockDurationMs,
+    hitboxes: attack.hitboxes,
+  });
+}
+
+export function resolveActionBattleHitboxSpeed(
+  profile: NormalizedActionBattleAttackProfile,
+  hitboxCount: number
+): number {
+  const positions = Math.max(1, Math.floor(hitboxCount));
+  const activeFrames = Math.max(
+    1,
+    Math.ceil(profile.activeMs / ACTION_BATTLE_HITBOX_FRAME_MS)
+  );
+  return Math.max(1, Math.ceil(activeFrames / positions));
+}
+
+export function scheduleActionBattleStartup(
+  profile: NormalizedActionBattleAttackProfile,
+  callback: () => void,
+  scheduler: (callback: () => void, delayMs: number) => unknown = setTimeout
+) {
+  if (profile.startupMs <= 0) {
+    callback();
+    return null;
+  }
+  return scheduler(callback, profile.startupMs);
+}
+
+let attackIdCounter = 0;
+
+export function createActionBattleAttackId(
+  attackerId: string | number | undefined,
+  profileId: string
+): string {
+  attackIdCounter++;
+  return `${attackerId ?? "unknown"}:${profileId}:${Date.now()}:${attackIdCounter}`;
+}
+
+const getTargetKey = (target: { id?: string | number } | undefined) => {
+  if (!target || target.id === undefined || target.id === null) return null;
+  return String(target.id);
+};
+
+export class ActionBattleHitTracker {
+  private hitTargets = new Set<string>();
+
+  constructor(private readonly hitPolicy: ActionBattleAttackHitPolicy) {}
+
+  canHit(target: { id?: string | number } | undefined): boolean {
+    if (this.hitPolicy === "allowRepeatHits") return true;
+    const key = getTargetKey(target);
+    return !key || !this.hitTargets.has(key);
+  }
+
+  recordHit(target: { id?: string | number } | undefined): void {
+    const key = getTargetKey(target);
+    if (key) {
+      this.hitTargets.add(key);
+    }
+  }
+
+  tryHit(target: { id?: string | number } | undefined): boolean {
+    if (!this.canHit(target)) return false;
+    this.recordHit(target);
+    return true;
+  }
+}

package/src/core/contracts.ts

@@ -1,5 +1,6 @@
 import type { RpgEvent, RpgPlayer } from "@rpgjs/server";
 import type { AttackPattern, EnemyType, AiState } from "../ai.server";
+import type { NormalizedActionBattleHitReactionProfile } from "../types";
 
 export type ActionBattleEntity = RpgPlayer | RpgEvent;
 
@@ -58,6 +59,7 @@ export interface ActionBattleHitContext {
   pattern?: AttackPattern | string;
   damage?: ActionBattleDamageResult;
   knockback?: ActionBattleKnockbackResult;
+  reaction?: NormalizedActionBattleHitReactionProfile;
   cancelled?: boolean;
   metadata?: Record<string, any>;
 }
@@ -70,6 +72,7 @@ export interface ActionBattleHitResult {
   attacker: ActionBattleEntity;
   target: ActionBattleEntity;
   rawDamage?: any;
+  reaction?: NormalizedActionBattleHitReactionProfile;
   cancelled?: boolean;
   metadata?: Record<string, any>;
 }

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

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "vitest";
+import {
+  DEFAULT_ACTION_BATTLE_ENEMY_ATTACK_PROFILES,
+  normalizeActionBattleEnemyAttackProfiles,
+} from "./enemy-attack-profiles";
+
+describe("enemy attack profiles", () => {
+  test("normalizes every built-in enemy attack pattern", () => {
+    const profiles = normalizeActionBattleEnemyAttackProfiles();
+
+    expect(Object.keys(profiles).sort()).toEqual(
+      Object.keys(DEFAULT_ACTION_BATTLE_ENEMY_ATTACK_PROFILES).sort()
+    );
+    expect(profiles.charged.startupMs).toBe(800);
+    expect(profiles.zone.reaction.staggerPower).toBe(1.25);
+  });
+
+  test("overrides individual pattern timing", () => {
+    const profiles = normalizeActionBattleEnemyAttackProfiles({
+      melee: {
+        startupMs: 60,
+        activeMs: 40,
+        recoveryMs: 100,
+      },
+    });
+
+    expect(profiles.melee).toMatchObject({
+      startupMs: 60,
+      activeMs: 40,
+      recoveryMs: 100,
+      totalDurationMs: 200,
+    });
+    expect(profiles.charged.startupMs).toBe(800);
+  });
+});

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

@@ -1,6 +1,7 @@
-import { describe, expect, test, vi } from "vitest";
+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,
@@ -10,6 +11,10 @@ const entity = (hp = 100) => ({
 });
 
 describe("applyActionBattleHit", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   test("runs beforeHit before resolving damage", () => {
     const calls: string[] = [];
     const attacker = entity();
@@ -55,4 +60,52 @@ describe("applyActionBattleHit", () => {
     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);
+  });
 });