@rpgjs/action-battle 5.0.0-beta.3 → 5.0.0-beta.5

package/src/server.ts

@@ -9,8 +9,13 @@ import {
 import { normalizeActionBattleOptions, setActionBattleOptions } from "./config";
 import { manhattanDistance, parseAoeMask } from "./targeting";
 import { playActionBattleAnimation } from "./animations";
+import { getActionBattleSystems, setActionBattleSystems } from "./core/context";
+import { applyActionBattleHit } from "./core/hit";
+import { DEFAULT_ZELDA_PLAYER_HITBOXES } from "./core/defaults";
+import type { ActionBattleHitbox } from "./core/contracts";
 
 export const ACTION_BATTLE_ACTION_BAR_GUI_ID = "action-battle-action-bar";
+const DEFAULT_ATTACK_LOCK_DURATION_MS = 350;
 
 /**
  * Default player attack hitboxes offsets for each direction
@@ -20,11 +25,113 @@ export const ACTION_BATTLE_ACTION_BAR_GUI_ID = "action-battle-action-bar";
  * when creating the moving hitbox.
  */
 export const DEFAULT_PLAYER_ATTACK_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 }
+  ...DEFAULT_ZELDA_PLAYER_HITBOXES,
+};
+
+const beginPlayerAttackLock = (
+  player: RpgPlayer,
+  map: ReturnType<RpgPlayer["getCurrentMap"]> | undefined,
+  durationMs: number
+): boolean => {
+  if (durationMs <= 0) 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 =
+    typeof player.canMove === "function" ? player.canMove() : true;
+  const previousDirectionFixed = player.directionFixed;
+  const previousAnimationFixed = player.animationFixed;
+
+  player.pendingInputs = [];
+  player.lastProcessedInputTs = 0;
+  (map as any)?.stopMovement?.(player);
+  player.canMove.set(false);
+  player.directionFixed = true;
+
+  setTimeout(() => {
+    if (runtimePlayer.__actionBattleAttackLockId !== lockId) return;
+    runtimePlayer.__actionBattleAttackLockedUntil = 0;
+    player.canMove.set(previousCanMove);
+    player.directionFixed = previousDirectionFixed;
+    player.animationFixed = previousAnimationFixed;
+  }, durationMs);
+
+  return true;
+};
+
+const isBattleEvent = (event: RpgEvent) => !!(event as any).battleAi;
+
+const rectsOverlap = (
+  a: { x: number; y: number; width: number; height: number },
+  b: { x: number; y: number; width: number; height: number }
+) =>
+  a.x < b.x + b.width &&
+  a.x + a.width > b.x &&
+  a.y < b.y + b.height &&
+  a.y + a.height > b.y;
+
+const eventRect = (event: RpgEvent) => {
+  const hitbox =
+    typeof event.hitbox === "function" ? event.hitbox() : (event as any).hitbox;
+  return {
+    x: event.x(),
+    y: event.y(),
+    width: hitbox?.w ?? 32,
+    height: hitbox?.h ?? 32,
+  };
+};
+
+const getVisibleActionEvents = (
+  player: RpgPlayer,
+  map: ReturnType<RpgPlayer["getCurrentMap"]> | undefined,
+  hitboxes: Array<{ x: number; y: number; width: number; height: number }>
+) => {
+  if (!map) return [];
+
+  const eventsById = new Map<string, RpgEvent>();
+  const addEvent = (event: RpgEvent | undefined) => {
+    if (!event) return;
+    const isVisible =
+      typeof (map as any).isEventVisibleForPlayer === "function"
+        ? (map as any).isEventVisibleForPlayer(event, player)
+        : true;
+    if (!isVisible) return;
+    eventsById.set(event.id, event);
+  };
+
+  const collisions = (map as any).getCollisions?.(player.id);
+  if (Array.isArray(collisions)) {
+    collisions.forEach((id: string) => addEvent(map.getEvent(id)));
+  }
+
+  for (const event of map.getEvents()) {
+    const rect = eventRect(event);
+    if (hitboxes.some((hitbox) => rectsOverlap(hitbox, rect))) {
+      addEvent(event);
+    }
+  }
+
+  return Array.from(eventsById.values());
+};
+
+const isActionReservedForNormalEvent = (
+  player: RpgPlayer,
+  map: ReturnType<RpgPlayer["getCurrentMap"]> | undefined,
+  hitboxes: Array<{ x: number; y: number; width: number; height: number }>
+) => {
+  const events = getVisibleActionEvents(player, map, hitboxes);
+  return events.length > 0 && !events.some(isBattleEvent);
 };
 
 /**
@@ -98,52 +205,97 @@ export function applyPlayerHitToEvent(
   const ai = (target as any).battleAi as BattleAi;
   if (!ai) return undefined;
 
-  // Get knockback force from player's weapon
-  const knockbackForce = getPlayerWeaponKnockbackForce(player);
-
-  // Apply damage to AI
-  const defeated = ai.takeDamage(player);
-
-  // Calculate knockback direction (away from player)
-  const dx = target.x() - player.x();
-  const dy = target.y() - player.y();
-  const distance = Math.sqrt(dx * dx + dy * dy);
-
-  // Create hit result
-  let hitResult: HitResult = {
-    damage: 0, // Will be set by takeDamage internally
-    knockbackForce,
-    knockbackDuration: DEFAULT_KNOCKBACK.duration,
-    defeated,
-    attacker: player,
-    target
-  };
-
-  // Call onBeforeHit hook
-  if (hooks?.onBeforeHit) {
-    const modified = hooks.onBeforeHit(hitResult);
-    if (modified) {
-      hitResult = modified;
+  const systems = getActionBattleSystems();
+  const result = applyActionBattleHit(
+    {
+      ...systems.combat,
+      hooks: hooks
+        ? {
+            ...systems.combat.hooks,
+            beforeHit(context) {
+              const before = systems.combat.hooks?.beforeHit?.(context);
+              if (before === false) return false;
+              const nextContext = before || context;
+              const legacyResult = toLegacyHitResult(nextContext);
+              const modified = hooks.onBeforeHit?.(legacyResult);
+              if (!modified) return nextContext;
+              return {
+                ...nextContext,
+                damage: {
+                  damage: modified.damage,
+                  defeated: modified.defeated,
+                  raw: nextContext.damage?.raw,
+                },
+                knockback: {
+                  force: modified.knockbackForce,
+                  duration: modified.knockbackDuration,
+                  direction: nextContext.knockback?.direction,
+                },
+              };
+            },
+            afterHit(result) {
+              systems.combat.hooks?.afterHit?.(result);
+              hooks.onAfterHit?.(result as HitResult);
+            },
+          }
+        : systems.combat.hooks,
+    },
+    {
+      attacker: player,
+      target,
     }
-  }
-
-  // Apply knockback only if not defeated (entity still exists)
-  if (!hitResult.defeated && hitResult.knockbackForce > 0 && distance > 0) {
-    const knockbackDirection = {
-      x: dx / distance,
-      y: dy / distance
-    };
-    target.knockback(knockbackDirection, hitResult.knockbackForce, hitResult.knockbackDuration);
-  }
+  );
 
-  // Call onAfterHit hook
-  if (hooks?.onAfterHit) {
-    hooks.onAfterHit(hitResult);
+  if (!result.cancelled) {
+    ai.handleDamage(player, {
+      damage: result.damage,
+      defeated: result.defeated,
+      raw: result.rawDamage,
+    });
   }
 
-  return hitResult;
+  return result as HitResult;
 }
 
+const toLegacyHitResult = (context: any): HitResult => ({
+  damage: context.damage?.damage ?? 0,
+  knockbackForce: context.knockback?.force ?? getPlayerWeaponKnockbackForce(context.attacker),
+  knockbackDuration: context.knockback?.duration ?? DEFAULT_KNOCKBACK.duration,
+  defeated: context.damage?.defeated ?? false,
+  attacker: context.attacker,
+  target: context.target,
+});
+
+const resolvePlayerAttackHitboxes = (
+  player: RpgPlayer,
+  directionKey: string,
+  options: ActionBattleOptions
+): ActionBattleHitbox[] => {
+  const configuredHitboxes = {
+    ...DEFAULT_PLAYER_ATTACK_HITBOXES,
+    ...options.attack?.hitboxes,
+  };
+  const hitboxConfig =
+    configuredHitboxes[
+      directionKey as keyof typeof DEFAULT_PLAYER_ATTACK_HITBOXES
+    ] || configuredHitboxes.default;
+  const defaultHitboxes = [
+    {
+      x: player.x() + hitboxConfig.offsetX,
+      y: player.y() + hitboxConfig.offsetY,
+      width: hitboxConfig.width,
+      height: hitboxConfig.height,
+    },
+  ];
+  return (
+    options.attack?.resolveHitboxes?.({
+      player,
+      direction: directionKey,
+      defaultHitboxes,
+    }) ?? defaultHitboxes
+  );
+};
+
 const resolveSignal = (value: any) =>
   typeof value === "function" ? value() : value;
 
@@ -404,6 +556,7 @@ export const createActionBattleServer = (
 ) => {
   const options = normalizeActionBattleOptions(rawOptions);
   setActionBattleOptions(options);
+  setActionBattleSystems(options);
   return defineModule<RpgServer>({
     player: {
       /**
@@ -419,38 +572,39 @@ export const createActionBattleServer = (
        */
       onInput(player: RpgPlayer, input: any) {
         if (input.action == Control.Action) {
-          playActionBattleAnimation("attack", player, options.animations);
-
-          // Get player position
-          const playerX = player.x();
-          const playerY = player.y();
+          const map = player.getCurrentMap();
           const direction = player.getDirection();
 
           // Convert Direction enum to string key
           const directionKey = direction as string;
 
-          // Get hitbox configuration for the direction
-          const hitboxConfig =
-            DEFAULT_PLAYER_ATTACK_HITBOXES[
-              directionKey as keyof typeof DEFAULT_PLAYER_ATTACK_HITBOXES
-            ] || DEFAULT_PLAYER_ATTACK_HITBOXES.default;
-
-          // Convert relative hitbox to absolute coordinates
-          const hitboxes: Array<{
-            x: number;
-            y: number;
-            width: number;
-            height: number;
-          }> = [
-            {
-              x: playerX + hitboxConfig.offsetX,
-              y: playerY + hitboxConfig.offsetY,
-              width: hitboxConfig.width,
-              height: hitboxConfig.height,
-            },
-          ];
+          const hitboxes = resolvePlayerAttackHitboxes(
+            player,
+            directionKey,
+            options
+          );
+
+          if (isActionReservedForNormalEvent(player, map, hitboxes)) {
+            return;
+          }
+
+          const lockMovement = options.attack?.lockMovement !== false;
+          const lockDurationMs =
+            options.attack?.lockDurationMs ?? DEFAULT_ATTACK_LOCK_DURATION_MS;
+          let movementLocked = false;
+
+          if (
+            lockMovement &&
+            !beginPlayerAttackLock(player, map, Math.max(0, lockDurationMs))
+          ) {
+            return;
+          }
+          movementLocked = lockMovement && lockDurationMs > 0;
 
-          const map = player.getCurrentMap();
+          playActionBattleAnimation("attack", player, options.animations);
+          if (movementLocked) {
+            player.animationFixed = true;
+          }
 
           map?.createMovingHitbox(hitboxes, { speed: 3 }).subscribe({
             next(hits) {
@@ -507,3 +661,13 @@ export const createActionBattleServer = (
 };
 
 export default createActionBattleServer();
+
+export {
+  AiDebug,
+  AiState,
+  AttackPattern,
+  BattleAi,
+  DEFAULT_KNOCKBACK,
+  EnemyType,
+} from "./ai.server";
+export type { ApplyHitHooks, BattleAiOptions, HitResult } from "./ai.server";

package/src/targeting.spec.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "vitest";
+import { manhattanDistance, parseAoeMask } from "./targeting";
+
+describe("targeting helpers", () => {
+  test("parses an ASCII AoE mask around its center", () => {
+    const mask = parseAoeMask([".#.", "###", ".#."]);
+
+    expect(mask.width).toBe(3);
+    expect(mask.height).toBe(3);
+    expect(mask.cells).toEqual(
+      expect.arrayContaining([
+        { dx: 0, dy: -1 },
+        { dx: -1, dy: 0 },
+        { dx: 0, dy: 0 },
+        { dx: 1, dy: 0 },
+        { dx: 0, dy: 1 },
+      ])
+    );
+  });
+
+  test("uses Manhattan distance for tile targeting", () => {
+    expect(manhattanDistance({ x: 2, y: 3 }, { x: 5, y: 1 })).toBe(5);
+  });
+});

package/src/types/canvas-engine.d.ts

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

package/src/types.ts

@@ -1,3 +1,10 @@
+import type {
+  ActionBattleAiBehavior,
+  ActionBattleCombatSystem,
+  ActionBattleHitHooks,
+  ActionBattleHitbox,
+} from "./core/contracts";
+
 export type ActionBattleAoeMask = string[] | string;
 
 export type ActionBattleActionBarMode = "items" | "skills" | "both";
@@ -8,7 +15,8 @@ export type ActionBattleAnimationKey =
   | "attack"
   | "hurt"
   | "die"
-  | "castSkill";
+  | "castSkill"
+  | "castSpell";
 
 export type ActionBattleAnimationResult =
   | string
@@ -91,11 +99,48 @@ export interface ActionBattleTargetingOptions {
   allowEmptyTarget?: boolean;
 }
 
+export interface ActionBattleAttackOptions {
+  lockMovement?: boolean;
+  lockDurationMs?: number;
+  showPreview?: boolean;
+  previewDurationMs?: number;
+  previewColor?: number;
+  previewAccentColor?: number;
+  hitboxes?: Partial<
+    Record<
+      "up" | "down" | "left" | "right" | "default",
+      { offsetX: number; offsetY: number; width: number; height: number }
+    >
+  >;
+  resolveHitboxes?: (context: {
+    player: any;
+    direction: string;
+    defaultHitboxes: ActionBattleHitbox[];
+  }) => ActionBattleHitbox[];
+}
+
+export interface ActionBattleCombatOptions {
+  damage?: ActionBattleCombatSystem["resolveDamage"];
+  knockback?: ActionBattleCombatSystem["resolveKnockback"];
+  hooks?: ActionBattleHitHooks;
+}
+
+export interface ActionBattleAiSystemOptions {
+  behaviors?: Record<string, ActionBattleAiBehavior>;
+}
+
+export interface ActionBattleSystemOptions {
+  combat?: ActionBattleCombatOptions;
+  ai?: ActionBattleAiSystemOptions;
+}
+
 export interface ActionBattleOptions {
   ui?: ActionBattleUiOptions;
   skills?: ActionBattleSkillOptions;
   targeting?: ActionBattleTargetingOptions;
+  attack?: ActionBattleAttackOptions;
   animations?: ActionBattleAnimationOptions;
+  systems?: ActionBattleSystemOptions;
 }
 
 export interface ActionBattleActionBarItem {

package/src/ui/state.ts

@@ -2,6 +2,16 @@ import { signal } from "canvasengine";
 import { ActionBattleActionBarSkill, ActionBattleOptions } from "../types";
 import { DEFAULT_ACTION_BATTLE_OPTIONS, normalizeActionBattleOptions } from "../config";
 
+export interface ActionBattleAttackPreviewState {
+  active: boolean;
+  id: number;
+  direction: string;
+  startedAt: number;
+  durationMs: number;
+  color: number;
+  accentColor: number;
+}
+
 export interface ActionBattleTargetingState {
   active: boolean;
   skill: ActionBattleActionBarSkill | null;
@@ -18,6 +28,16 @@ const defaultTargetingState: ActionBattleTargetingState = {
   aoeMask: DEFAULT_ACTION_BATTLE_OPTIONS.skills?.defaultAoeMask || ["#"],
 };
 
+const defaultAttackPreviewState: ActionBattleAttackPreviewState = {
+  active: false,
+  id: 0,
+  direction: "down",
+  startedAt: 0,
+  durationMs: 180,
+  color: 0xfff3b0,
+  accentColor: 0xffffff,
+};
+
 export const actionBattleUiOptions = signal(
   normalizeActionBattleOptions({}).ui || {}
 );
@@ -28,6 +48,10 @@ export const actionBattleSkillOptions = signal(
 export const actionBattleTargetingState = signal<ActionBattleTargetingState>({
   ...defaultTargetingState,
 });
+export const actionBattleAttackPreviewState =
+  signal<ActionBattleAttackPreviewState>({
+    ...defaultAttackPreviewState,
+  });
 
 export const setActionBattleOptions = (options: ActionBattleOptions = {}) => {
   const normalized = normalizeActionBattleOptions(options);
@@ -66,3 +90,36 @@ export const moveTargetingOffset = (dx: number, dy: number) => {
     offset: next,
   });
 };
+
+export const startAttackPreview = (options: {
+  direction: string;
+  durationMs?: number;
+  color?: number;
+  accentColor?: number;
+}) => {
+  const current = actionBattleAttackPreviewState();
+  const id = current.id + 1;
+  const durationMs = Math.max(
+    1,
+    options.durationMs ?? defaultAttackPreviewState.durationMs
+  );
+  actionBattleAttackPreviewState.set({
+    active: true,
+    id,
+    direction: options.direction,
+    startedAt: Date.now(),
+    durationMs,
+    color: options.color ?? defaultAttackPreviewState.color,
+    accentColor: options.accentColor ?? defaultAttackPreviewState.accentColor,
+  });
+  return id;
+};
+
+export const stopAttackPreview = (id?: number) => {
+  const current = actionBattleAttackPreviewState();
+  if (id !== undefined && current.id !== id) return;
+  actionBattleAttackPreviewState.set({
+    ...current,
+    active: false,
+  });
+};