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

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/context.ts

@@ -0,0 +1,35 @@
+import type { ActionBattleOptions } from "../types";
+import { defaultActionBattleSystems } from "./defaults";
+import type { ActionBattleSystems } from "./contracts";
+
+const mergeSystems = (options: ActionBattleOptions = {}): ActionBattleSystems => ({
+  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,
+    },
+  },
+});
+
+let currentActionBattleSystems = mergeSystems();
+
+export const setActionBattleSystems = (options: ActionBattleOptions = {}) => {
+  currentActionBattleSystems = mergeSystems(options);
+};
+
+export const getActionBattleSystems = () => currentActionBattleSystems;
+
+export const createActionBattleSystems = mergeSystems;

package/src/core/contracts.ts

@@ -0,0 +1,126 @@
+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;
+
+export interface ActionBattleHitbox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface ActionBattleDirection {
+  x: number;
+  y: number;
+}
+
+export interface ActionBattleAttackContext {
+  attacker: ActionBattleEntity;
+  target?: ActionBattleEntity | null;
+  direction?: string;
+  skill?: any;
+  pattern?: AttackPattern | string;
+  map?: any;
+  now: number;
+}
+
+export interface ActionBattleDamageContext {
+  attacker: ActionBattleEntity;
+  target: ActionBattleEntity;
+  skill?: any;
+  pattern?: AttackPattern | string;
+}
+
+export interface ActionBattleDamageResult {
+  damage: number;
+  defeated: boolean;
+  raw?: any;
+}
+
+export interface ActionBattleKnockbackContext {
+  attacker: ActionBattleEntity;
+  target: ActionBattleEntity;
+  damage: ActionBattleDamageResult;
+  weapon?: any;
+}
+
+export interface ActionBattleKnockbackResult {
+  force: number;
+  duration: number;
+  direction?: ActionBattleDirection;
+}
+
+export interface ActionBattleHitContext {
+  attacker: ActionBattleEntity;
+  target: ActionBattleEntity;
+  skill?: any;
+  pattern?: AttackPattern | string;
+  damage?: ActionBattleDamageResult;
+  knockback?: ActionBattleKnockbackResult;
+  reaction?: NormalizedActionBattleHitReactionProfile;
+  cancelled?: boolean;
+  metadata?: Record<string, any>;
+}
+
+export interface ActionBattleHitResult {
+  damage: number;
+  knockbackForce: number;
+  knockbackDuration: number;
+  defeated: boolean;
+  attacker: ActionBattleEntity;
+  target: ActionBattleEntity;
+  rawDamage?: any;
+  reaction?: NormalizedActionBattleHitReactionProfile;
+  cancelled?: boolean;
+  metadata?: Record<string, any>;
+}
+
+export interface ActionBattleHitHooks {
+  beforeHit?: (
+    context: ActionBattleHitContext
+  ) => ActionBattleHitContext | false | void;
+  afterDamage?: (
+    context: ActionBattleHitContext
+  ) => ActionBattleHitContext | void;
+  afterHit?: (result: ActionBattleHitResult) => void;
+}
+
+export interface ActionBattleCombatSystem {
+  resolveHitboxes(context: ActionBattleAttackContext): ActionBattleHitbox[];
+  resolveDamage(context: ActionBattleDamageContext): ActionBattleDamageResult;
+  resolveKnockback(
+    context: ActionBattleKnockbackContext
+  ): ActionBattleKnockbackResult;
+  hooks?: ActionBattleHitHooks;
+}
+
+export interface ActionBattleAiContext {
+  event: RpgEvent;
+  target: RpgPlayer | null;
+  state: AiState;
+  enemyType: EnemyType;
+  distance: number | null;
+  hpPercent: number | null;
+  now: number;
+}
+
+export interface ActionBattleAiDecision {
+  mode?: "assault" | "tactical" | "retreat";
+  attackPatterns?: AttackPattern[];
+  attackCooldown?: number;
+  moveToCooldown?: number;
+  metadata?: Record<string, any>;
+}
+
+export type ActionBattleAiBehavior = (
+  context: ActionBattleAiContext
+) => ActionBattleAiDecision | void;
+
+export interface ActionBattleSystems {
+  combat: ActionBattleCombatSystem;
+  ai: {
+    behaviors: Record<string, ActionBattleAiBehavior>;
+  };
+}

package/src/core/defaults.ts

@@ -0,0 +1,162 @@
+import type { RpgPlayer } from "@rpgjs/server";
+import type {
+  ActionBattleAiBehavior,
+  ActionBattleAttackContext,
+  ActionBattleCombatSystem,
+  ActionBattleDamageContext,
+  ActionBattleKnockbackContext,
+  ActionBattleKnockbackResult,
+  ActionBattleSystems,
+} from "./contracts";
+
+const DEFAULT_CORE_KNOCKBACK = {
+  force: 50,
+  duration: 300,
+};
+
+const CoreAttackPattern = {
+  Melee: "melee",
+  Combo: "combo",
+  Charged: "charged",
+  Zone: "zone",
+  DashAttack: "dashAttack",
+} as const;
+
+const CoreEnemyType = {
+  Aggressive: "aggressive",
+  Defensive: "defensive",
+  Ranged: "ranged",
+  Tank: "tank",
+  Berserker: "berserker",
+} as const;
+
+export const 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 },
+};
+
+const resolveEquippedWeapon = (entity: any) => {
+  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;
+};
+
+const resolveDirection = (attacker: any, target: any) => {
+  const dx = target.x() - attacker.x();
+  const dy = target.y() - attacker.y();
+  const distance = Math.sqrt(dx * dx + dy * dy);
+  if (distance <= 0) return undefined;
+  return {
+    x: dx / distance,
+    y: dy / distance,
+  };
+};
+
+export const createDefaultPlayerHitboxResolver =
+  (hitboxes = DEFAULT_ZELDA_PLAYER_HITBOXES) =>
+  (context: ActionBattleAttackContext) => {
+    const attacker = context.attacker as any;
+    const direction =
+      context.direction ??
+      (typeof attacker.getDirection === "function"
+        ? attacker.getDirection()
+        : "default");
+    const config =
+      hitboxes[direction as keyof typeof hitboxes] || hitboxes.default;
+    return [
+      {
+        x: attacker.x() + config.offsetX,
+        y: attacker.y() + config.offsetY,
+        width: config.width,
+        height: config.height,
+      },
+    ];
+  };
+
+export const defaultRpgjsDamageResolver = (
+  context: ActionBattleDamageContext
+) => {
+  const target = context.target as any;
+  const raw = target.applyDamage(context.attacker as any, context.skill);
+  return {
+    damage: raw?.damage ?? 0,
+    defeated: target.hp <= 0,
+    raw,
+  };
+};
+
+export const defaultKnockbackResolver = (
+  context: ActionBattleKnockbackContext
+): ActionBattleKnockbackResult => {
+  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 as any, context.target as any),
+  };
+};
+
+export const defaultCombatSystem: ActionBattleCombatSystem = {
+  resolveHitboxes: createDefaultPlayerHitboxResolver(),
+  resolveDamage: defaultRpgjsDamageResolver,
+  resolveKnockback: defaultKnockbackResolver,
+};
+
+export const defaultEnemyBehaviors: Record<string, ActionBattleAiBehavior> = {
+  [CoreEnemyType.Aggressive]: ({ hpPercent }) => ({
+    mode: hpPercent !== null && hpPercent < 0.15 ? "retreat" : "assault",
+    attackPatterns: [
+      CoreAttackPattern.Melee as any,
+      CoreAttackPattern.Combo as any,
+      CoreAttackPattern.DashAttack as any,
+    ],
+  }),
+  [CoreEnemyType.Defensive]: ({ hpPercent }) => ({
+    mode: hpPercent !== null && hpPercent < 0.3 ? "retreat" : "tactical",
+    attackPatterns: [CoreAttackPattern.Melee as any, CoreAttackPattern.Charged as any],
+  }),
+  [CoreEnemyType.Ranged]: ({ distance }) => ({
+    mode: distance !== null && distance < 80 ? "retreat" : "tactical",
+    attackPatterns: [CoreAttackPattern.Melee as any, CoreAttackPattern.Zone as any],
+  }),
+  [CoreEnemyType.Tank]: () => ({
+    mode: "assault",
+    attackPatterns: [
+      CoreAttackPattern.Melee as any,
+      CoreAttackPattern.Charged as any,
+      CoreAttackPattern.Zone as any,
+    ],
+  }),
+  [CoreEnemyType.Berserker]: ({ hpPercent }) => ({
+    mode: "assault",
+    attackCooldown:
+      hpPercent === null ? undefined : Math.max(250, 800 * Math.max(0.3, hpPercent)),
+    attackPatterns: [
+      CoreAttackPattern.Melee as any,
+      CoreAttackPattern.Combo as any,
+      CoreAttackPattern.DashAttack as any,
+    ],
+  }),
+};
+
+export const defaultActionBattleSystems: ActionBattleSystems = {
+  combat: defaultCombatSystem,
+  ai: {
+    behaviors: defaultEnemyBehaviors,
+  },
+};
+
+export const getEntityWeaponKnockbackForce = (entity: RpgPlayer): number => {
+  return defaultKnockbackResolver({
+    attacker: entity,
+    target: entity,
+    damage: { damage: 0, defeated: false },
+  }).force;
+};

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);
+  });
+});