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

package/src/index.ts

@@ -26,6 +26,7 @@ export type {
   ActionBattleAnimationOptions,
   ActionBattleAnimationResolver,
   ActionBattleAnimationResult,
+  ActionBattleAiOptions,
   ActionBattleOptions,
   ActionBattleActionBarData,
   ActionBattleActionBarItem,
@@ -35,30 +36,49 @@ export type {
   ActionBattleAttackOptions,
   ActionBattleUiOptions,
   ActionBattleUiActionBarOptions,
+  ActionBattleUiAttackPreviewOptions,
+  ActionBattleUiGuiEntry,
   ActionBattleUiTargetingOptions,
   ActionBattleAttackDirection,
   ActionBattleAttackHitboxConfig,
   ActionBattleAttackHitboxMap,
   ActionBattleAttackHitPolicy,
   ActionBattleAttackProfile,
-  ActionBattleDebugOptions,
   ActionBattleHitReactionProfile,
   NormalizedActionBattleHitReactionProfile,
   NormalizedActionBattleAttackProfile,
   ActionBattleCombatOptions,
   ActionBattleSystemOptions,
   ActionBattleAiSystemOptions,
+  ActionBattleVisualComposer,
+  ActionBattleVisualContext,
+  ActionBattleVisualHelpers,
+  ActionBattleVisualInput,
+  ActionBattleVisualMoment,
+  ActionBattleVisualPart,
+  ActionBattleVisualPreset,
 } from "./types";
 export type {
   ActionBattleAiBehavior,
   ActionBattleAiContext,
   ActionBattleAiDecision,
+  ActionBattleAiPreset,
   ActionBattleAttackContext,
   ActionBattleCombatSystem,
   ActionBattleDamageContext,
   ActionBattleDamageResult,
   ActionBattleDirection,
   ActionBattleEntity,
+  ActionBattleActionConfig,
+  ActionBattleActionMode,
+  ActionBattleActionTarget,
+  ActionBattleTargetContext,
+  ActionBattleTargetOptions,
+  ActionBattleTargetSelector,
+  ActionBattleProjectileImpactContext,
+  ActionBattleProjectileOptions,
+  ActionBattleUsable,
+  ActionBattleUseContext,
   ActionBattleHitContext,
   ActionBattleHitHooks,
   ActionBattleHitResult,
@@ -67,6 +87,50 @@ export type {
   ActionBattleKnockbackResult,
   ActionBattleSystems,
 } from "./core/contracts";
+export {
+  action,
+  chase,
+  condition,
+  decision,
+  defineAiBehavior,
+  defineAiTree,
+  distanceLessThan,
+  faceTarget,
+  flee,
+  fleeFromTarget,
+  hpBelow,
+  idle,
+  ifDistanceLessThan,
+  ifHpBelow,
+  ifTargetInRange,
+  ifTargetVisible,
+  inState,
+  isEnemyType,
+  keepDistance,
+  moveToTarget,
+  patrol,
+  rule,
+  selector,
+  sequence,
+  setMode,
+  targetInRange,
+  targetVisible,
+  useAttack,
+  useSkill,
+  type ActionBattleAiCondition,
+  type ActionBattleAiIntent,
+  type ActionBattleAiIntentInput,
+  type ActionBattleAiMemory,
+  type ActionBattleAiRule,
+  type ActionBattleAiSimpleBehavior,
+  type ActionBattleAiSnapshotSelf,
+  type ActionBattleAiSnapshotTarget,
+  type ActionBattleAiTreeContext,
+  type ActionBattleAiTreeInput,
+  type ActionBattleAiTreeNode,
+  type ActionBattleAiTreeResult,
+  type ActionBattleAiTreeStatus,
+} from "./core/ai-behavior-tree";
 export {
   DEFAULT_ACTION_BATTLE_ATTACK_PROFILE,
   normalizeActionBattleAttackProfile,
@@ -78,8 +142,18 @@ export {
   createActionBattleAttackId,
   getNormalizedActionBattleAttackProfile,
   resolveActionBattleHitboxSpeed,
+  runActionBattleActiveHitbox,
   scheduleActionBattleStartup,
 } from "./core/attack-runtime";
+export {
+  canActionBattleUseTarget,
+  executeActionBattleUse,
+  getActionBattleActionConfig,
+  getActionBattleActionRange,
+  handleActionBattleProjectileDestroy,
+  handleActionBattleProjectileImpact,
+  shouldUseActionBattleUsable,
+} from "./core/action-use";
 export {
   DEFAULT_ACTION_BATTLE_HIT_REACTION,
   isActionBattleEntityInvincible,
@@ -93,22 +167,56 @@ export {
   type ActionBattleEnemyAttackProfileMap,
   type NormalizedActionBattleEnemyAttackProfileMap,
 } from "./core/enemy-attack-profiles";
-export { resolveActionBattleWeaponAttackProfile } from "./core/equipment";
+export {
+  resolveActionBattleWeapon,
+  resolveActionBattleWeaponAttackProfile,
+} from "./core/equipment";
 export {
   DEFAULT_ZELDA_PLAYER_HITBOXES,
   createDefaultPlayerHitboxResolver,
   defaultCombatSystem,
   defaultEnemyBehaviors,
+  defaultEnemyPresets,
   defaultKnockbackResolver,
   defaultRpgjsDamageResolver,
 } from "./core/defaults";
+export {
+  ACTION_BATTLE_ENEMY_FACTION,
+  ACTION_BATTLE_PLAYER_FACTION,
+  canActionBattleTarget,
+  getActionBattleFaction,
+  getActionBattleTargets,
+  isActionBattleCombatEntity,
+  isActionBattleEvent,
+  isActionBattlePlayer,
+  matchesActionBattleTargetSelector,
+} from "./core/targets";
 export {
   createActionBattleSystems,
   getActionBattleSystems,
 } from "./core/context";
 export { applyActionBattleHit } from "./core/hit";
+export {
+  ACTION_BATTLE_CLIENT_VISUAL_ID,
+  ACTION_BATTLE_HIT_FX_COMPONENT_ID,
+  createActionBattleClientVisuals,
+  createActionBattleVisual,
+  createClassicActionBattleVisual,
+  createFxActionBattleVisual,
+  emitActionBattleClientVisual,
+  playActionBattleVisual,
+  setActionBattlePreviewStarter,
+} from "./visual";
+export {
+  ActionBattleUi,
+  createActionBattleUi,
+  resolveActionBattleUi,
+  type ResolvedActionBattleUi,
+} from "./ui";
 export {
   createActionEnemy,
+  defineActionBattleAiPreset,
+  defineActionBattleEnemy,
   type ActionBattleEnemyPreset,
   type ActionBattleEnemyPresetMap,
 } from "./enemies/factory";
@@ -117,6 +225,7 @@ export {
 export {
   DEFAULT_PLAYER_ATTACK_HITBOXES,
   getPlayerWeaponKnockbackForce,
+  applyActionBattleEntityHit,
   applyPlayerHitToEvent,
   ACTION_BATTLE_ACTION_BAR_GUI_ID,
   openActionBattleActionBar,

package/src/locomotion.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test, vi } from "vitest";
+import {
+  forceActionBattleLocomotionAnimation,
+  withActionBattleAnimationUnlocked,
+} from "./locomotion";
+
+describe("action battle locomotion helpers", () => {
+  test("temporarily unlocks animation to restore locomotion state", () => {
+    const entity = {
+      animationFixed: true,
+      setGraphicAnimation: vi.fn(function (this: { animationFixed: boolean }) {
+        expect(this.animationFixed).toBe(false);
+      }),
+    };
+
+    forceActionBattleLocomotionAnimation(entity, "stand");
+
+    expect(entity.setGraphicAnimation).toHaveBeenCalledWith("stand");
+    expect(entity.animationFixed).toBe(true);
+  });
+
+  test("updates client-side animation signals when no server animation API exists", () => {
+    const setAnimationName = vi.fn();
+    const entity = {
+      animationFixed: false,
+      animationName: {
+        set: setAnimationName,
+      },
+      resetAnimationState: vi.fn(),
+    };
+
+    forceActionBattleLocomotionAnimation(entity, "stand");
+
+    expect(setAnimationName).toHaveBeenCalledWith("stand");
+    expect(entity.resetAnimationState).toHaveBeenCalled();
+    expect(entity.resetAnimationState.mock.invocationCallOrder[0]).toBeLessThan(
+      setAnimationName.mock.invocationCallOrder[0]
+    );
+  });
+
+  test("temporarily unlocks action animations while preserving the current lock", () => {
+    const entity = { animationFixed: true };
+    const callback = vi.fn(() => {
+      expect(entity.animationFixed).toBe(false);
+      return "played";
+    });
+
+    expect(withActionBattleAnimationUnlocked(entity, callback)).toBe("played");
+    expect(entity.animationFixed).toBe(true);
+  });
+});

package/src/locomotion.ts

@@ -0,0 +1,48 @@
+type LocomotionEntity = {
+  animationFixed?: boolean;
+  setGraphicAnimation?: (...args: any[]) => unknown;
+  animationName?: {
+    set?: (animationName: string) => unknown;
+  };
+  resetAnimationState?: () => unknown;
+};
+
+export const withActionBattleAnimationUnlocked = <T>(
+  entity: LocomotionEntity | undefined,
+  callback: () => T
+): T => {
+  if (!entity) return callback();
+
+  const previousAnimationFixed = entity.animationFixed;
+  entity.animationFixed = false;
+
+  try {
+    return callback();
+  } finally {
+    entity.animationFixed = previousAnimationFixed;
+  }
+};
+
+/**
+ * Force a locomotion animation even when an action lock temporarily froze
+ * animation changes. This keeps server state and local rendering coherent
+ * after attack recovery interrupts movement.
+ */
+export const forceActionBattleLocomotionAnimation = (
+  entity: LocomotionEntity | undefined,
+  animationName: "stand" | "walk"
+) => {
+  if (!entity) return;
+
+  withActionBattleAnimationUnlocked(entity, () => {
+    if (typeof entity.resetAnimationState === "function") {
+      entity.resetAnimationState();
+    }
+
+    if (typeof entity.setGraphicAnimation === "function") {
+      entity.setGraphicAnimation(animationName);
+    } else if (typeof entity.animationName?.set === "function") {
+      entity.animationName.set(animationName);
+    }
+  });
+};

package/src/movement.spec.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test, vi } from "vitest";
+import {
+  hasActionBattlePhysicsBody,
+  isActionBattleMovementResolutionError,
+  safeActionBattleDash,
+} from "./movement";
+
+describe("action battle movement helpers", () => {
+  test("does not dash when the entity physics body has already been removed", () => {
+    const entity = {
+      id: "enemy-1",
+      getCurrentMap: vi.fn(() => ({
+        getBody: vi.fn(() => undefined),
+      })),
+      dash: vi.fn(),
+    };
+
+    expect(safeActionBattleDash(entity, { x: 1, y: 0 }, 10, 200)).toBe(false);
+    expect(entity.dash).not.toHaveBeenCalled();
+  });
+
+  test("dashes when the entity still has a physics body", () => {
+    const entity = {
+      id: "enemy-1",
+      getCurrentMap: vi.fn(() => ({
+        getBody: vi.fn(() => ({ id: "enemy-1" })),
+      })),
+      dash: vi.fn(),
+    };
+
+    expect(safeActionBattleDash(entity, { x: 1, y: 0 }, 10, 200)).toBe(true);
+    expect(entity.dash).toHaveBeenCalledWith({ x: 1, y: 0 }, 10, 200);
+  });
+
+  test("absorbs teardown races between body check and dash registration", () => {
+    const entity = {
+      id: "enemy-1",
+      getCurrentMap: vi.fn(() => ({
+        getBody: vi.fn(() => ({ id: "enemy-1" })),
+      })),
+      dash: vi.fn(() => {
+        throw new Error("MovementManager: unable to resolve entity for identifier enemy-1.");
+      }),
+    };
+
+    expect(safeActionBattleDash(entity, { x: 1, y: 0 }, 10, 200)).toBe(false);
+  });
+
+  test("keeps unexpected movement errors visible", () => {
+    const entity = {
+      id: "enemy-1",
+      getCurrentMap: vi.fn(() => ({
+        getBody: vi.fn(() => ({ id: "enemy-1" })),
+      })),
+      dash: vi.fn(() => {
+        throw new Error("boom");
+      }),
+    };
+
+    expect(() => safeActionBattleDash(entity, { x: 1, y: 0 }, 10, 200)).toThrow(
+      "boom"
+    );
+  });
+
+  test("detects unavailable bodies only when the map exposes body lookup", () => {
+    expect(
+      hasActionBattlePhysicsBody({
+        id: "enemy-1",
+        getCurrentMap: () => ({}),
+      })
+    ).toBe(true);
+    expect(
+      isActionBattleMovementResolutionError(
+        new Error("MovementManager: unable to resolve entity for identifier enemy-1.")
+      )
+    ).toBe(true);
+  });
+});

package/src/movement.ts

@@ -0,0 +1,46 @@
+const UNRESOLVED_ENTITY_MESSAGE = "unable to resolve entity";
+
+export type ActionBattleDashEntity = {
+  id?: string;
+  getCurrentMap?: () => any;
+  dash?: (
+    direction: { x: number; y: number },
+    additionalSpeed?: number,
+    duration?: number
+  ) => unknown;
+};
+
+export const isActionBattleMovementResolutionError = (error: unknown): boolean => {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  return message.includes(UNRESOLVED_ENTITY_MESSAGE);
+};
+
+export const hasActionBattlePhysicsBody = (
+  entity: ActionBattleDashEntity | null | undefined
+): boolean => {
+  if (!entity) return false;
+  const map = entity.getCurrentMap?.();
+  if (!map) return false;
+  if (typeof map.getBody !== "function" || !entity.id) return true;
+  return Boolean(map.getBody(entity.id));
+};
+
+export const safeActionBattleDash = (
+  entity: ActionBattleDashEntity | null | undefined,
+  direction: { x: number; y: number },
+  additionalSpeed?: number,
+  duration?: number
+): boolean => {
+  if (!entity || typeof entity.dash !== "function") return false;
+  if (!hasActionBattlePhysicsBody(entity)) return false;
+
+  try {
+    entity.dash(direction, additionalSpeed, duration);
+    return true;
+  } catch (error) {
+    if (isActionBattleMovementResolutionError(error)) {
+      return false;
+    }
+    throw error;
+  }
+};