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

package/src/animations.spec.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test, vi } from "vitest";
+import { playActionBattleAnimation } from "./animations";
+
+describe("action battle animations", () => {
+  test("uses setGraphicAnimation when the entity exposes the server animation API", () => {
+    const entity = {
+      setGraphicAnimation: vi.fn(),
+      setAnimation: vi.fn(),
+    };
+
+    playActionBattleAnimation("attack", entity);
+
+    expect(entity.setGraphicAnimation).toHaveBeenCalledWith("attack", 1);
+    expect(entity.setAnimation).not.toHaveBeenCalled();
+  });
+
+  test("falls back to setAnimation for client sprite objects", () => {
+    const entity = {
+      setAnimation: vi.fn(),
+    };
+
+    playActionBattleAnimation("attack", entity, {
+      attack: {
+        animationName: "slash",
+        graphic: "hero-slash",
+        repeat: 2,
+      },
+    });
+
+    expect(entity.setAnimation).toHaveBeenCalledWith(
+      "slash",
+      "hero-slash",
+      2
+    );
+  });
+
+  test("does not throw when the entity has no animation API", () => {
+    expect(() => playActionBattleAnimation("attack", {})).not.toThrow();
+  });
+});

package/src/animations.ts

@@ -20,6 +20,36 @@ export interface ActionBattleAnimationDefaults {
   repeat?: number;
 }
 
+const playResolvedAnimation = (
+  entity: ActionBattleAnimationEntity,
+  animation: ResolvedActionBattleAnimation
+) => {
+  if (typeof entity.setGraphicAnimation === "function") {
+    if (animation.graphic !== undefined) {
+      entity.setGraphicAnimation(
+        animation.animationName,
+        animation.graphic,
+        animation.repeat
+      );
+    } else {
+      entity.setGraphicAnimation(animation.animationName, animation.repeat);
+    }
+    return;
+  }
+
+  if (typeof entity.setAnimation === "function") {
+    if (animation.graphic !== undefined) {
+      entity.setAnimation(
+        animation.animationName,
+        animation.graphic,
+        animation.repeat
+      );
+    } else {
+      entity.setAnimation(animation.animationName, animation.repeat);
+    }
+  }
+};
+
 const DEFAULT_ANIMATION_BY_KEY: Record<ActionBattleAnimationKey, string> = {
   attack: "attack",
   hurt: "hurt",
@@ -127,15 +157,7 @@ export function playActionBattleAnimation(
   );
   if (!animation) return null;
 
-  if (animation.graphic !== undefined) {
-    entity.setGraphicAnimation(
-      animation.animationName,
-      animation.graphic,
-      animation.repeat
-    );
-  } else {
-    entity.setGraphicAnimation(animation.animationName, animation.repeat);
-  }
+  playResolvedAnimation(entity, animation);
 
   return animation;
 }

package/src/attack-input.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test, vi } from "vitest";
+import {
+  applyActionBattleAttackDirection,
+  resolveActionBattleAttackDirection,
+} from "./attack-input";
+
+describe("action battle attack input", () => {
+  test("prefers the direction carried by the action payload", () => {
+    const entity = {
+      getDirection: () => "left",
+    };
+
+    expect(
+      resolveActionBattleAttackDirection(entity, {
+        data: { direction: "right" },
+      })
+    ).toBe("right");
+  });
+
+  test("falls back to the entity direction when the payload is missing", () => {
+    const entity = {
+      getDirection: () => "up",
+    };
+
+    expect(resolveActionBattleAttackDirection(entity)).toBe("up");
+  });
+
+  test("applies the captured attack direction before direction lock", () => {
+    const entity = {
+      changeDirection: vi.fn(),
+    };
+
+    applyActionBattleAttackDirection(entity, "down");
+
+    expect(entity.changeDirection).toHaveBeenCalledWith("down");
+  });
+
+  test("temporarily unlocks direction so attack intent can face while knocked back", () => {
+    const entity = {
+      directionFixed: true,
+      changeDirection: vi.fn(function (this: { directionFixed: boolean }) {
+        expect(this.directionFixed).toBe(false);
+      }),
+    };
+
+    applyActionBattleAttackDirection(entity, "right");
+
+    expect(entity.changeDirection).toHaveBeenCalledWith("right");
+    expect(entity.directionFixed).toBe(true);
+  });
+});

package/src/attack-input.ts

@@ -0,0 +1,59 @@
+export type ActionBattleResolvedDirection = "up" | "down" | "left" | "right";
+
+const ACTION_BATTLE_DIRECTIONS = new Set([
+  "up",
+  "down",
+  "left",
+  "right",
+]);
+
+const normalizeDirection = (
+  value: unknown
+): ActionBattleResolvedDirection | undefined => {
+  if (typeof value !== "string") return undefined;
+  return ACTION_BATTLE_DIRECTIONS.has(value)
+    ? (value as ActionBattleResolvedDirection)
+    : undefined;
+};
+
+export const resolveActionBattleAttackDirection = (
+  entity: any,
+  input?: any
+): ActionBattleResolvedDirection => {
+  const payloadDirection =
+    normalizeDirection(input?.data?.direction) ??
+    normalizeDirection(input?.data?.attackDirection) ??
+    normalizeDirection(input?.direction);
+  if (payloadDirection) return payloadDirection;
+
+  if (typeof entity?.getDirection === "function") {
+    const direction = normalizeDirection(entity.getDirection());
+    if (direction) return direction;
+  }
+
+  if (typeof entity?.direction === "function") {
+    const direction = normalizeDirection(entity.direction());
+    if (direction) return direction;
+  }
+
+  return normalizeDirection(entity?.direction) ?? "down";
+};
+
+export const applyActionBattleAttackDirection = (
+  entity: any,
+  direction: ActionBattleResolvedDirection
+) => {
+  if (typeof entity?.changeDirection === "function") {
+    const previousDirectionFixed = entity.directionFixed;
+    if (previousDirectionFixed === true) {
+      entity.directionFixed = false;
+    }
+    try {
+      entity.changeDirection(direction);
+    } finally {
+      if (previousDirectionFixed === true) {
+        entity.directionFixed = previousDirectionFixed;
+      }
+    }
+  }
+};

package/src/client.ts

@@ -1,11 +1,5 @@
-import { inject, PrebuiltComponentAnimations, RpgClient, RpgClientEngine, RpgGui } from "@rpgjs/client";
+import { PrebuiltComponentAnimations, RpgClient, RpgClientEngine, RpgGui, inject } from "@rpgjs/client";
 import { defineModule } from "@rpgjs/common";
-// @ts-ignore CanvasEngine components are compiled by @canvasengine/compiler.
-import ActionBarComponent from "./components/action-bar.ce";
-// @ts-ignore CanvasEngine components are compiled by @canvasengine/compiler.
-import TargetingOverlayComponent from "./components/targeting-overlay.ce";
-// @ts-ignore CanvasEngine components are compiled by @canvasengine/compiler.
-import AttackPreviewComponent from "./components/attack-preview.ce";
 import {
   setActionBattleOptions,
   startAttackPreview,
@@ -13,8 +7,22 @@ import {
 } from "./ui/state";
 import { ActionBattleOptions } from "./types";
 import { normalizeActionBattleOptions } from "./config";
-import { resolveActionBattleAnimation } from "./animations";
 import { getNormalizedActionBattleAttackProfile } from "./core/attack-runtime";
+import {
+  applyActionBattleAttackDirection,
+  resolveActionBattleAttackDirection,
+} from "./attack-input";
+import {
+  forceActionBattleLocomotionAnimation,
+  withActionBattleAnimationUnlocked,
+} from "./locomotion";
+import { resolveActionBattleUi } from "./ui";
+import {
+  ACTION_BATTLE_HIT_FX_COMPONENT_ID,
+  createActionBattleClientVisuals,
+  playActionBattleVisual,
+  setActionBattlePreviewStarter,
+} from "./visual";
 
 const DEFAULT_ATTACK_LOCK_DURATION_MS = 350;
 
@@ -64,6 +72,9 @@ const beginLocalPlayerAttackLock = (
     player.canMove = previousCanMove;
     player.directionFixed = previousDirectionFixed;
     player.animationFixed = previousAnimationFixed;
+    if (locks.movement && !previousAnimationFixed) {
+      forceActionBattleLocomotionAnimation(player, "stand");
+    }
   }, durationMs);
 
   return true;
@@ -79,35 +90,21 @@ const playLocalPlayerAttackAnimation = (
   player: any,
   options: ActionBattleOptions
 ) => {
-  if (!player || typeof player.setAnimation !== "function") return;
-  const animation = resolveActionBattleAnimation(
-    "attack",
-    player,
-    options.animations
-  );
-  if (!animation) return;
-
-  if (animation.graphic !== undefined) {
-    player.setAnimation(
-      animation.animationName,
-      animation.graphic,
-      animation.repeat
-    );
-    return;
-  }
-  player.setAnimation(animation.animationName, animation.repeat);
+  withActionBattleAnimationUnlocked(player, () => {
+    playActionBattleVisual(options.visual, {
+      moment: "attack",
+      entity: player,
+    });
+  });
 };
 
 const showLocalAttackPreview = (player: any, options: ActionBattleOptions) => {
-  if (!player || options.attack?.showPreview === false) return;
-  const durationMs = Math.max(1, options.attack?.previewDurationMs ?? 180);
-  const previewId = startAttackPreview({
-    direction: resolveLocalPlayerDirection(player),
-    durationMs,
-    color: options.attack?.previewColor,
-    accentColor: options.attack?.previewAccentColor,
+  const attackPreview = options.ui?.attackPreview as any;
+  if (!player || attackPreview?.enabled === false) return;
+  playActionBattleVisual(options.visual, {
+    moment: "preview",
+    entity: player,
   });
-  setTimeout(() => stopAttackPreview(previewId), durationMs);
 };
 
 export const createActionBattleClient = (
@@ -115,60 +112,76 @@ export const createActionBattleClient = (
 ) => {
   const normalized = normalizeActionBattleOptions(options);
   setActionBattleOptions(normalized);
-  const actionBarEnabled = normalized.ui?.actionBar?.enabled;
-  const targetingEnabled = normalized.ui?.targeting?.enabled;
-  const componentsInFront = [
-    ...(targetingEnabled ? [TargetingOverlayComponent] : []),
-    AttackPreviewComponent,
-  ];
+  setActionBattlePreviewStarter((entity, previewOptions = {}) => {
+    const direction = previewOptions.direction ?? resolveLocalPlayerDirection(entity);
+    const durationMs = Math.max(
+      1,
+      previewOptions.durationMs ?? normalized.attack?.previewDurationMs ?? 180
+    );
+    const previewId = startAttackPreview({
+      direction,
+      durationMs,
+      color: previewOptions.color ?? normalized.attack?.previewColor,
+      accentColor:
+        previewOptions.accentColor ?? normalized.attack?.previewAccentColor,
+    });
+    setTimeout(() => stopAttackPreview(previewId), durationMs);
+  });
+  const resolvedUi = resolveActionBattleUi(normalized.ui);
+  const actionBarEnabled = resolvedUi.actionBar.enabled;
   const hitComponent = PrebuiltComponentAnimations?.Hit;
+  const fxComponent = PrebuiltComponentAnimations?.Fx;
   return defineModule<RpgClient>({
-    componentAnimations: hitComponent
-      ? [
-          {
-            id: "hit",
-            component: hitComponent,
-          },
-        ]
-      : [],
-    gui: actionBarEnabled
-      ? [
-          {
-            id: "action-battle-action-bar",
-            component: ActionBarComponent,
-            dependencies: () => {
-              const engine = inject(RpgClientEngine)
-              return [engine.scene.currentPlayer]
+    componentAnimations: [
+      ...(hitComponent
+        ? [
+            {
+              id: "hit",
+              component: hitComponent,
+            },
+          ]
+        : []),
+      ...(fxComponent
+        ? [
+            {
+              id: ACTION_BATTLE_HIT_FX_COMPONENT_ID,
+              component: fxComponent,
             },
-          },
-        ]
-      : [],
+          ]
+        : []),
+    ],
+    clientVisuals: createActionBattleClientVisuals(normalized),
+    gui: resolvedUi.gui,
     sprite: {
-      componentsInFront,
+      componentsBehind: resolvedUi.sprite.componentsBehind,
+      componentsInFront: resolvedUi.sprite.componentsInFront,
     },
     sceneMap: {
       onAfterLoading() {
-        if (actionBarEnabled && normalized.ui?.actionBar?.autoOpen) {
+        if (actionBarEnabled && resolvedUi.actionBar.autoOpen) {
           const gui = inject(RpgGui)
           gui.display('action-battle-action-bar')
         }
       }
     },
     engine: {
-      onInput(engine: RpgClientEngine, { input }: { input: string }) {
+      onInput(engine: RpgClientEngine, { input, data }: any) {
         if (input !== "action") return;
         const player = engine.scene?.getCurrentPlayer?.() as any;
         if (!player) return;
+        const direction = resolveActionBattleAttackDirection(player, { data });
+        applyActionBattleAttackDirection(player, direction);
         const attackProfile = getNormalizedActionBattleAttackProfile(normalized);
         const lockDurationMs = Math.max(
           0,
           attackProfile.totalDurationMs ?? DEFAULT_ATTACK_LOCK_DURATION_MS
         );
         if (attackProfile.movementLock || attackProfile.directionLock) {
-          beginLocalPlayerAttackLock(engine, lockDurationMs, {
+          const locked = beginLocalPlayerAttackLock(engine, lockDurationMs, {
             movement: attackProfile.movementLock,
             direction: attackProfile.directionLock,
           });
+          if (!locked) return;
         }
         playLocalPlayerAttackAnimation(player, normalized);
         showLocalAttackPreview(player, normalized);

package/src/config.ts

@@ -42,68 +42,115 @@ let currentActionBattleOptions: ActionBattleOptions =
 export function normalizeActionBattleOptions(
   options: ActionBattleOptions = {}
 ): ActionBattleOptions {
+  const combat = {
+    ...DEFAULT_ACTION_BATTLE_OPTIONS.systems?.combat,
+    ...options.systems?.combat,
+    ...options.combat,
+    hooks: {
+      ...DEFAULT_ACTION_BATTLE_OPTIONS.systems?.combat?.hooks,
+      ...options.systems?.combat?.hooks,
+      ...options.combat?.hooks,
+    },
+  };
   const attack = {
     ...DEFAULT_ACTION_BATTLE_OPTIONS.attack,
     ...options.attack,
+    ...combat.attack,
   };
   const attackProfile = normalizeActionBattleAttackProfile(attack.profile, {
     lockMovement: attack.lockMovement,
     lockDurationMs: attack.lockDurationMs,
     hitboxes: attack.hitboxes,
   });
+  const normalizedAttack = {
+    ...attack,
+    profile: attackProfile,
+  };
+  const skills = {
+    ...DEFAULT_ACTION_BATTLE_OPTIONS.skills,
+    ...options.skills,
+  };
+  skills.targeting = skills.targeting ?? skills.getTargeting;
+  skills.getTargeting = skills.getTargeting ?? skills.targeting;
+
+  const defaultActionBar = DEFAULT_ACTION_BATTLE_OPTIONS.ui?.actionBar as any;
+  const defaultTargeting = DEFAULT_ACTION_BATTLE_OPTIONS.ui?.targeting as any;
+  const optionActionBar = options.ui?.actionBar as any;
+  const optionTargeting = options.ui?.targeting as any;
+  const optionAttackPreview = options.ui?.attackPreview as any;
+  const actionBar =
+    options.ui?.actionBar === false
+      ? { ...defaultActionBar, enabled: false }
+      : {
+          ...defaultActionBar,
+          ...(options.ui?.actionBar === true ? { enabled: true } : optionActionBar),
+        };
+  const legacyPreviewEnabled = normalizedAttack.showPreview !== false;
+  const attackPreview =
+    options.ui?.attackPreview === false
+      ? { enabled: false }
+      : {
+          enabled: options.ui?.attackPreview === true ? true : legacyPreviewEnabled,
+          ...(options.ui?.attackPreview === true ? {} : optionAttackPreview),
+        };
+  const targeting =
+    options.ui?.targeting === false
+      ? { ...defaultTargeting, enabled: false }
+      : {
+          ...defaultTargeting,
+          ...(options.ui?.targeting === true ? { enabled: true } : optionTargeting),
+          colors: {
+            ...defaultTargeting?.colors,
+            ...(typeof options.ui?.targeting === "object"
+              ? optionTargeting?.colors
+              : undefined),
+          },
+        };
+  const ai = {
+    ...DEFAULT_ACTION_BATTLE_OPTIONS.systems?.ai,
+    ...options.systems?.ai,
+    ...options.ai,
+    behaviors: {
+      ...DEFAULT_ACTION_BATTLE_OPTIONS.systems?.ai?.behaviors,
+      ...options.systems?.ai?.behaviors,
+      ...options.ai?.behaviors,
+    },
+    presets: {
+      ...DEFAULT_ACTION_BATTLE_OPTIONS.systems?.ai?.presets,
+      ...options.systems?.ai?.presets,
+      ...options.ai?.presets,
+    },
+  };
 
   return {
     ui: {
-      actionBar: {
-        ...DEFAULT_ACTION_BATTLE_OPTIONS.ui?.actionBar,
-        ...options.ui?.actionBar,
-      },
-      targeting: {
-        ...DEFAULT_ACTION_BATTLE_OPTIONS.ui?.targeting,
-        ...options.ui?.targeting,
-        colors: {
-          ...DEFAULT_ACTION_BATTLE_OPTIONS.ui?.targeting?.colors,
-          ...options.ui?.targeting?.colors,
-        },
-      },
-    },
-    skills: {
-      ...DEFAULT_ACTION_BATTLE_OPTIONS.skills,
-      ...options.skills,
+      ...options.ui,
+      actionBar,
+      targeting,
+      attackPreview,
     },
+    skills,
     targeting: {
       ...DEFAULT_ACTION_BATTLE_OPTIONS.targeting,
       ...options.targeting,
     },
-    debug: {
-      ...DEFAULT_ACTION_BATTLE_OPTIONS.debug,
-      ...options.debug,
-    },
-    attack: {
-      ...attack,
-      profile: attackProfile,
+    attack: normalizedAttack,
+    combat: {
+      ...combat,
+      attack: normalizedAttack,
     },
+    ai,
+    visual: options.visual,
     animations: {
       ...DEFAULT_ACTION_BATTLE_OPTIONS.animations,
       ...options.animations,
     },
     systems: {
       combat: {
-        ...DEFAULT_ACTION_BATTLE_OPTIONS.systems?.combat,
-        ...options.systems?.combat,
-        hooks: {
-          ...DEFAULT_ACTION_BATTLE_OPTIONS.systems?.combat?.hooks,
-          ...options.systems?.combat?.hooks,
-        },
-      },
-      ai: {
-        ...DEFAULT_ACTION_BATTLE_OPTIONS.systems?.ai,
-        ...options.systems?.ai,
-        behaviors: {
-          ...DEFAULT_ACTION_BATTLE_OPTIONS.systems?.ai?.behaviors,
-          ...options.systems?.ai?.behaviors,
-        },
+        ...combat,
+        attack: normalizedAttack,
       },
+      ai,
     },
   };
 }