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

package/src/animations.ts

@@ -0,0 +1,149 @@
+import type {
+  ActionBattleAnimationContext,
+  ActionBattleAnimationEntity,
+  ActionBattleAnimationKey,
+  ActionBattleAnimationOptions,
+} from "./types";
+
+export const DEFAULT_DIE_ANIMATION_DELAY_MS = 500;
+
+export interface ResolvedActionBattleAnimation {
+  animationName: string;
+  graphic?: string | string[];
+  repeat: number;
+  waitEnd: boolean;
+  delayMs?: number;
+}
+
+export interface ActionBattleAnimationDefaults {
+  animationName?: string;
+  repeat?: number;
+}
+
+const DEFAULT_ANIMATION_BY_KEY: Record<ActionBattleAnimationKey, string> = {
+  attack: "attack",
+  hurt: "hurt",
+  die: "die",
+  castSkill: "skill",
+  castSpell: "skill",
+};
+
+const getConfiguredAnimation = (
+  key: ActionBattleAnimationKey,
+  animations?: ActionBattleAnimationOptions,
+) => {
+  if (!animations) {
+    return {
+      hasConfiguredAnimation: false,
+      configured: undefined,
+    };
+  }
+
+  const hasConfiguredAnimation = Object.prototype.hasOwnProperty.call(
+    animations,
+    key,
+  );
+  if (hasConfiguredAnimation) {
+    return {
+      hasConfiguredAnimation,
+      configured: animations[key],
+    };
+  }
+
+  if (key === "castSkill") {
+    const hasCastSpellAlias = Object.prototype.hasOwnProperty.call(
+      animations,
+      "castSpell",
+    );
+    return {
+      hasConfiguredAnimation: hasCastSpellAlias,
+      configured: animations.castSpell,
+    };
+  }
+
+  return {
+    hasConfiguredAnimation: false,
+    configured: undefined,
+  };
+};
+
+export function resolveActionBattleAnimation(
+  key: ActionBattleAnimationKey,
+  entity: ActionBattleAnimationEntity,
+  animations?: ActionBattleAnimationOptions,
+  context?: ActionBattleAnimationContext,
+  defaults: ActionBattleAnimationDefaults = {}
+): ResolvedActionBattleAnimation | null {
+  const defaultAnimationName =
+    defaults.animationName ?? DEFAULT_ANIMATION_BY_KEY[key];
+  const defaultRepeat = defaults.repeat ?? 1;
+  const { hasConfiguredAnimation, configured: configuredAnimation } =
+    getConfiguredAnimation(key, animations);
+  if (!hasConfiguredAnimation && key !== "attack") {
+    return null;
+  }
+
+  const configured = hasConfiguredAnimation
+    ? configuredAnimation
+    : defaultAnimationName;
+  const result =
+    typeof configured === "function"
+      ? configured(entity, context)
+      : configured;
+
+  if (result == null) return null;
+
+  if (typeof result === "string") {
+    return {
+      animationName: result,
+      repeat: defaultRepeat,
+      waitEnd: false,
+    };
+  }
+
+  const animationName = result.animationName ?? defaultAnimationName;
+  return {
+    animationName,
+    graphic: result.graphic,
+    repeat: result.repeat ?? defaultRepeat,
+    waitEnd: result.waitEnd ?? false,
+    delayMs: result.delayMs,
+  };
+}
+
+export function playActionBattleAnimation(
+  key: ActionBattleAnimationKey,
+  entity: ActionBattleAnimationEntity,
+  animations?: ActionBattleAnimationOptions,
+  context?: ActionBattleAnimationContext,
+  defaults: ActionBattleAnimationDefaults = {}
+): ResolvedActionBattleAnimation | null {
+  const animation = resolveActionBattleAnimation(
+    key,
+    entity,
+    animations,
+    context,
+    defaults
+  );
+  if (!animation) return null;
+
+  if (animation.graphic !== undefined) {
+    entity.setGraphicAnimation(
+      animation.animationName,
+      animation.graphic,
+      animation.repeat
+    );
+  } else {
+    entity.setGraphicAnimation(animation.animationName, animation.repeat);
+  }
+
+  return animation;
+}
+
+export function getActionBattleAnimationRemovalDelay(
+  animation: ResolvedActionBattleAnimation | null
+): number {
+  if (!animation) return 0;
+  if (animation.delayMs !== undefined) return animation.delayMs;
+  return animation.waitEnd ? DEFAULT_DIE_ANIMATION_DELAY_MS : 0;
+}

package/src/canvas-engine-shim.ts

@@ -0,0 +1,4 @@
+declare module "*.ce" {
+  const component: any;
+  export default component;
+}

package/src/client.ts

@@ -1,10 +1,114 @@
 import { inject, PrebuiltComponentAnimations, RpgClient, RpgClientEngine, RpgGui } 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";
-import { setActionBattleOptions } from "./ui/state";
+// @ts-ignore CanvasEngine components are compiled by @canvasengine/compiler.
+import AttackPreviewComponent from "./components/attack-preview.ce";
+import {
+  setActionBattleOptions,
+  startAttackPreview,
+  stopAttackPreview,
+} from "./ui/state";
 import { ActionBattleOptions } from "./types";
 import { normalizeActionBattleOptions } from "./config";
+import { resolveActionBattleAnimation } from "./animations";
+import { getNormalizedActionBattleAttackProfile } from "./core/attack-runtime";
+
+const DEFAULT_ATTACK_LOCK_DURATION_MS = 350;
+
+const beginLocalPlayerAttackLock = (
+  engine: RpgClientEngine,
+  durationMs: number,
+  locks: { movement: boolean; direction: boolean }
+): boolean => {
+  if (durationMs <= 0) return true;
+
+  const player = engine.scene?.getCurrentPlayer?.() as any;
+  if (!player) return true;
+
+  const runtimePlayer = player as any;
+  const now = Date.now();
+  if (
+    typeof runtimePlayer.__actionBattleAttackLockedUntil === "number" &&
+    runtimePlayer.__actionBattleAttackLockedUntil > now
+  ) {
+    return false;
+  }
+
+  const lockId = (runtimePlayer.__actionBattleAttackLockId ?? 0) + 1;
+  runtimePlayer.__actionBattleAttackLockId = lockId;
+  runtimePlayer.__actionBattleAttackLockedUntil = now + durationMs;
+
+  const previousCanMove = player.canMove;
+  const previousDirectionFixed = player.directionFixed;
+  const previousAnimationFixed = player.animationFixed;
+
+  if (locks.movement) {
+    if (typeof engine.interruptCurrentPlayerMovement === "function") {
+      engine.interruptCurrentPlayerMovement(player);
+    } else {
+      (engine.scene as any)?.stopMovement?.(player);
+    }
+    player.canMove = false;
+  }
+  if (locks.direction) {
+    player.directionFixed = true;
+  }
+  player.animationFixed = true;
+
+  setTimeout(() => {
+    if (runtimePlayer.__actionBattleAttackLockId !== lockId) return;
+    runtimePlayer.__actionBattleAttackLockedUntil = 0;
+    player.canMove = previousCanMove;
+    player.directionFixed = previousDirectionFixed;
+    player.animationFixed = previousAnimationFixed;
+  }, durationMs);
+
+  return true;
+};
+
+const resolveLocalPlayerDirection = (player: any) => {
+  if (typeof player.getDirection === "function") return player.getDirection();
+  if (typeof player.direction === "function") return player.direction();
+  return player.direction ?? "down";
+};
+
+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);
+};
+
+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,
+  });
+  setTimeout(() => stopAttackPreview(previewId), durationMs);
+};
 
 export const createActionBattleClient = (
   options: ActionBattleOptions = {}
@@ -13,6 +117,10 @@ export const createActionBattleClient = (
   setActionBattleOptions(normalized);
   const actionBarEnabled = normalized.ui?.actionBar?.enabled;
   const targetingEnabled = normalized.ui?.targeting?.enabled;
+  const componentsInFront = [
+    ...(targetingEnabled ? [TargetingOverlayComponent] : []),
+    AttackPreviewComponent,
+  ];
   const hitComponent = PrebuiltComponentAnimations?.Hit;
   return defineModule<RpgClient>({
     componentAnimations: hitComponent
@@ -36,7 +144,7 @@ export const createActionBattleClient = (
         ]
       : [],
     sprite: {
-      componentsInFront: targetingEnabled ? [TargetingOverlayComponent] : [],
+      componentsInFront,
     },
     sceneMap: {
       onAfterLoading() {
@@ -45,6 +153,26 @@ export const createActionBattleClient = (
           gui.display('action-battle-action-bar')
         }
       }
+    },
+    engine: {
+      onInput(engine: RpgClientEngine, { input }: { input: string }) {
+        if (input !== "action") return;
+        const player = engine.scene?.getCurrentPlayer?.() as any;
+        if (!player) return;
+        const attackProfile = getNormalizedActionBattleAttackProfile(normalized);
+        const lockDurationMs = Math.max(
+          0,
+          attackProfile.totalDurationMs ?? DEFAULT_ATTACK_LOCK_DURATION_MS
+        );
+        if (attackProfile.movementLock || attackProfile.directionLock) {
+          beginLocalPlayerAttackLock(engine, lockDurationMs, {
+            movement: attackProfile.movementLock,
+            direction: attackProfile.directionLock,
+          });
+        }
+        playLocalPlayerAttackAnimation(player, normalized);
+        showLocalAttackPreview(player, normalized);
+      },
     }
   });
 };

package/src/components/action-bar.ce

@@ -72,7 +72,6 @@
   const engine = inject(RpgClientEngine);
   const keyboardControls = engine.globalConfig.keyboardControls;
   const { data, onInteraction, onBack } = defineProps();
-  const currentPlayer = engine.getCurrentPlayer();
   const ACTION_BAR_SIZE = 10;
   const SLOT_LABELS = ["1", "2", "3", "4", "5", "6", "7", "8", "9", "0"];
   const SLOT_CONFIG_KEYS = [
@@ -107,10 +106,13 @@
     playing: "default"
   });
 
+  const resolveProp = (value) => typeof value === "function" ? value() : value;
+  const actionBarData = computed(() => resolveProp(data) || { items: [], skills: [] });
+
   const actionBarSlots = computed(() => {
     const entries = [];
     if (showSkills()) {
-      currentPlayer.skills().forEach((skill, index) => {
+      (actionBarData().skills || []).forEach((skill, index) => {
         entries.push({
           type: "skill",
           skill,
@@ -120,7 +122,7 @@
       });
     }
     if (showItems()) {
-      currentPlayer.items().forEach((item, index) => {
+      (actionBarData().items || []).forEach((item, index) => {
         entries.push({
           type: "item",
           skill: null,

package/src/components/attack-preview.ce

@@ -0,0 +1,90 @@
+<Container>
+  @if (shouldRender) {
+    <Graphics draw={drawSlash} />
+  }
+</Container>
+
+<script>
+  import { computed, signal, tick } from "canvasengine";
+  import { inject, RpgClientEngine } from "@rpgjs/client";
+  import { actionBattleAttackPreviewState } from "../ui/state";
+
+  const { object } = defineProps();
+  const engine = inject(RpgClientEngine);
+  const now = signal(Date.now());
+
+  tick(() => {
+    if (actionBattleAttackPreviewState().active) {
+      now.set(Date.now());
+    }
+  });
+
+  const isCurrentPlayer = computed(() => {
+    if (!object?.id) return false;
+    const idValue = typeof object.id === "function" ? object.id() : object.id;
+    return idValue === engine.playerId;
+  });
+
+  const preview = computed(() => actionBattleAttackPreviewState());
+  const progress = computed(() => {
+    const state = preview();
+    if (!state.active) return 1;
+    const elapsed = now() - state.startedAt;
+    return Math.max(0, Math.min(1, elapsed / state.durationMs));
+  });
+
+  const shouldRender = computed(() => {
+    const state = preview();
+    return isCurrentPlayer() && state.active && progress() < 1;
+  });
+
+  const getHitbox = () => object.hitbox?.() || { w: 32, h: 32 };
+
+  const drawRect = (g, x, y, width, height, color, alpha) => {
+    g.rect(x, y, width, height);
+    g.fill({ color, alpha });
+  };
+
+  const drawSlash = (g) => {
+    g.clear();
+    if (!shouldRender()) return;
+
+    const state = preview();
+    const p = progress();
+    const alpha = Math.sin(Math.PI * p);
+    if (alpha <= 0) return;
+
+    const hitbox = getHitbox();
+    const width = hitbox.w || 32;
+    const height = hitbox.h || 32;
+    const reach = 16 + 18 * p;
+    const thickness = 4 + 3 * (1 - p);
+    const color = state.color;
+    const accent = state.accentColor;
+
+    if (state.direction === "left") {
+      drawRect(g, -reach - 6, height * 0.24, reach, thickness, accent, alpha * 0.55);
+      drawRect(g, -reach - 10, height * 0.46, reach + 4, thickness + 2, color, alpha);
+      drawRect(g, -reach - 6, height * 0.70, reach, thickness, accent, alpha * 0.4);
+      return;
+    }
+
+    if (state.direction === "right") {
+      drawRect(g, width + 6, height * 0.24, reach, thickness, accent, alpha * 0.55);
+      drawRect(g, width + 6, height * 0.46, reach + 4, thickness + 2, color, alpha);
+      drawRect(g, width + 6, height * 0.70, reach, thickness, accent, alpha * 0.4);
+      return;
+    }
+
+    if (state.direction === "up") {
+      drawRect(g, width * 0.24, -reach - 6, thickness, reach, accent, alpha * 0.55);
+      drawRect(g, width * 0.46, -reach - 10, thickness + 2, reach + 4, color, alpha);
+      drawRect(g, width * 0.70, -reach - 6, thickness, reach, accent, alpha * 0.4);
+      return;
+    }
+
+    drawRect(g, width * 0.24, height + 6, thickness, reach, accent, alpha * 0.55);
+    drawRect(g, width * 0.46, height + 6, thickness + 2, reach + 4, color, alpha);
+    drawRect(g, width * 0.70, height + 6, thickness, reach, accent, alpha * 0.4);
+  };
+</script>

package/src/config.ts

@@ -1,4 +1,5 @@
 import { ActionBattleOptions } from "./types";
+import { normalizeActionBattleAttackProfile } from "./core/attack-profile";
 
 export const DEFAULT_ACTION_BATTLE_OPTIONS: ActionBattleOptions = {
   ui: {
@@ -24,11 +25,33 @@ export const DEFAULT_ACTION_BATTLE_OPTIONS: ActionBattleOptions = {
     affects: "events",
     allowEmptyTarget: true,
   },
+  attack: {
+    lockMovement: true,
+    lockDurationMs: 350,
+    showPreview: true,
+    previewDurationMs: 180,
+    previewColor: 0xfff3b0,
+    previewAccentColor: 0xffffff,
+  },
+  animations: {},
 };
 
+let currentActionBattleOptions: ActionBattleOptions =
+  DEFAULT_ACTION_BATTLE_OPTIONS;
+
 export function normalizeActionBattleOptions(
   options: ActionBattleOptions = {}
 ): ActionBattleOptions {
+  const attack = {
+    ...DEFAULT_ACTION_BATTLE_OPTIONS.attack,
+    ...options.attack,
+  };
+  const attackProfile = normalizeActionBattleAttackProfile(attack.profile, {
+    lockMovement: attack.lockMovement,
+    lockDurationMs: attack.lockDurationMs,
+    hitboxes: attack.hitboxes,
+  });
+
   return {
     ui: {
       actionBar: {
@@ -52,5 +75,43 @@ export function normalizeActionBattleOptions(
       ...DEFAULT_ACTION_BATTLE_OPTIONS.targeting,
       ...options.targeting,
     },
+    debug: {
+      ...DEFAULT_ACTION_BATTLE_OPTIONS.debug,
+      ...options.debug,
+    },
+    attack: {
+      ...attack,
+      profile: attackProfile,
+    },
+    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,
+        },
+      },
+    },
   };
 }
+
+export function setActionBattleOptions(options: ActionBattleOptions) {
+  currentActionBattleOptions = options;
+}
+
+export function getActionBattleOptions(): ActionBattleOptions {
+  return currentActionBattleOptions;
+}

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

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "vitest";
+import {
+  DEFAULT_ACTION_BATTLE_ATTACK_PROFILE,
+  normalizeActionBattleAttackProfile,
+} from "./attack-profile";
+import { normalizeActionBattleOptions } from "../config";
+import type { NormalizedActionBattleAttackProfile } from "../types";
+
+describe("normalizeActionBattleAttackProfile", () => {
+  test("creates a default profile compatible with the legacy 350ms attack lock", () => {
+    const profile = normalizeActionBattleAttackProfile();
+
+    expect(profile).toEqual(DEFAULT_ACTION_BATTLE_ATTACK_PROFILE);
+  });
+
+  test("derives recovery from the legacy lock duration when recovery is omitted", () => {
+    const profile = normalizeActionBattleAttackProfile(
+      {
+        startupMs: 80,
+        activeMs: 90,
+      },
+      {
+        lockDurationMs: 400,
+      }
+    );
+
+    expect(profile.recoveryMs).toBe(230);
+    expect(profile.totalDurationMs).toBe(400);
+    expect(profile.cooldownMs).toBe(400);
+  });
+
+  test("keeps explicit timing, movement, hit policy, animation, and hitboxes", () => {
+    const hitboxes = {
+      right: { offsetX: 18, offsetY: -18, width: 42, height: 36 },
+    };
+    const profile = normalizeActionBattleAttackProfile({
+      id: "heavy-sword",
+      startupMs: 140,
+      activeMs: 100,
+      recoveryMs: 260,
+      cooldownMs: 650,
+      movementLock: false,
+      directionLock: false,
+      animationKey: "castSkill",
+      hitPolicy: "allowRepeatHits",
+      hitboxes,
+    });
+
+    expect(profile).toMatchObject({
+      id: "heavy-sword",
+      startupMs: 140,
+      activeMs: 100,
+      recoveryMs: 260,
+      cooldownMs: 650,
+      movementLock: false,
+      directionLock: false,
+      animationKey: "castSkill",
+      hitPolicy: "allowRepeatHits",
+      totalDurationMs: 500,
+    });
+    expect(profile.hitboxes).toBe(hitboxes);
+  });
+
+  test("normalizes unsafe timing values to playable bounds", () => {
+    const profile = normalizeActionBattleAttackProfile({
+      startupMs: -20,
+      activeMs: 0,
+      recoveryMs: -10,
+      cooldownMs: -1,
+    });
+
+    expect(profile.startupMs).toBe(0);
+    expect(profile.activeMs).toBe(1);
+    expect(profile.recoveryMs).toBe(0);
+    expect(profile.cooldownMs).toBe(0);
+    expect(profile.totalDurationMs).toBe(1);
+  });
+
+  test("normalizes attack.profile through action battle options", () => {
+    const options = normalizeActionBattleOptions({
+      attack: {
+        lockMovement: false,
+        lockDurationMs: 300,
+        profile: {
+          id: "quick-slash",
+          startupMs: 60,
+          activeMs: 80,
+        },
+      },
+    });
+    const profile = options.attack
+      ?.profile as NormalizedActionBattleAttackProfile;
+
+    expect(profile).toMatchObject({
+      id: "quick-slash",
+      startupMs: 60,
+      activeMs: 80,
+      recoveryMs: 160,
+      cooldownMs: 300,
+      movementLock: false,
+      totalDurationMs: 300,
+    });
+  });
+
+  test("keeps legacy lockDurationMs when no explicit profile is provided", () => {
+    const options = normalizeActionBattleOptions({
+      attack: {
+        lockDurationMs: 500,
+      },
+    });
+    const profile = options.attack
+      ?.profile as NormalizedActionBattleAttackProfile;
+
+    expect(profile.totalDurationMs).toBe(500);
+    expect(profile.recoveryMs).toBe(380);
+    expect(profile.cooldownMs).toBe(500);
+  });
+});