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

package/src/ai.server.ts

@@ -4,10 +4,12 @@ import {
   playActionBattleAnimation,
 } from "./animations";
 import { getActionBattleOptions } from "./config";
+import { getActionBattleSystems } from "./core/context";
+import type { ActionBattleDamageResult } from "./core/contracts";
 import type { ActionBattleAnimationOptions } from "./types";
 
 type RpgEventWithBattleAi = RpgEvent & {
-  battleAi: BattleAi;
+  battleAi?: BattleAi;
 };
 
 export interface BattleAiOptions {
@@ -31,6 +33,7 @@ export interface BattleAiOptions {
     assaultThreshold?: number;
     retreatThreshold?: number;
   };
+  behaviorKey?: string;
   animations?: ActionBattleAnimationOptions;
   /** Callback called when the AI is defeated */
   onDefeated?: (event: RpgEvent, attacker?: RpgPlayer) => void;
@@ -131,7 +134,9 @@ export interface ApplyHitHooks {
  */
 export const AiDebug = {
   /** Enable/disable all AI debug logs */
-  enabled: (typeof process !== 'undefined' && process.env?.RPGJS_DEBUG_AI === '1') || false,
+  enabled:
+    ((globalThis as { process?: { env?: Record<string, string> } }).process
+      ?.env?.RPGJS_DEBUG_AI === "1") || false,
   
   /** Filter logs to a specific event ID (null = all events) */
   filterEventId: null as string | null,
@@ -275,17 +280,17 @@ export class BattleAi {
 
   // Enemy type and behavior
   private enemyType: EnemyType;
-  private attackCooldown: number;
-  private visionRange: number;
-  private attackRange: number;
+  private attackCooldown: number = 1000;
+  private visionRange: number = 150;
+  private attackRange: number = 60;
 
   // Dodge system
-  private dodgeChance: number;
-  private dodgeCooldown: number;
+  private dodgeChance: number = 0.2;
+  private dodgeCooldown: number = 2000;
   private lastDodgeTime: number = 0;
 
   // Flee threshold (HP percentage)
-  private fleeThreshold: number;
+  private fleeThreshold: number = 0.2;
 
   // Attack configuration
   private attackSkill: any | null; // Skill to use for attacks
@@ -333,6 +338,8 @@ export class BattleAi {
   private lastMoveToTime: number = 0;
   private retreatCooldown: number = 600;
   private lastRetreatTime: number = 0;
+  private timers: ReturnType<typeof setTimeout>[] = [];
+  private behaviorKey?: string;
 
   /**
    * Create a new Battle AI Controller
@@ -367,6 +374,7 @@ export class BattleAi {
 
     // Set enemy type and apply behavior modifiers
     this.enemyType = options.enemyType || EnemyType.Aggressive;
+    this.behaviorKey = options.behaviorKey ?? this.enemyType;
     this.applyEnemyTypeBehavior(options);
 
     // Store attack skill reference
@@ -423,7 +431,9 @@ export class BattleAi {
     // Setup AI systems
     this.setupVision();
     this.startAiBehaviorLoop();
-    this.changeState(AiState.Idle);
+    if (this.patrolWaypoints.length > 0) {
+      this.startPatrol();
+    }
 
     this.debugLog('init', `AI created (type=${this.enemyType}, visionRange=${this.visionRange}, attackRange=${this.attackRange})`);
   }
@@ -530,6 +540,9 @@ export class BattleAi {
    * Change AI state with validated transitions
    */
   private changeState(newState: AiState) {
+    if (newState === this.state) {
+      return;
+    }
     const validTransitions: Record<AiState, AiState[]> = {
       [AiState.Idle]: [AiState.Alert, AiState.Combat],
       [AiState.Alert]: [AiState.Idle, AiState.Combat],
@@ -601,6 +614,8 @@ export class BattleAi {
       this.updateBehavior(currentTime);
     }
 
+    this.applyCustomBehavior(currentTime);
+
     // State-specific behavior
     switch (this.state) {
       case AiState.Idle:
@@ -634,6 +649,7 @@ export class BattleAi {
 
       if (distance < 10) {
         this.currentPatrolIndex = (this.currentPatrolIndex + 1) % this.patrolWaypoints.length;
+        this.startPatrol();
       }
     }
   }
@@ -690,9 +706,10 @@ export class BattleAi {
     // Try dodge
     if (this.canDodge() && this.shouldDodge()) {
       this.debugLog('combat', 'Attempting dodge');
-      this.isMovingToTarget = false;
-      this.tryDodge();
-      return;
+      if (this.tryDodge()) {
+        this.isMovingToTarget = false;
+        return;
+      }
     }
 
     if (this.behaviorEnabled) {
@@ -1066,7 +1083,7 @@ export class BattleAi {
     this.performMeleeAttack();
 
     if (this.comboCount < this.comboMax) {
-      setTimeout(() => {
+      this.schedule(() => {
         if (this.target && this.state === AiState.Combat) {
           this.performComboAttack();
         } else {
@@ -1096,7 +1113,7 @@ export class BattleAi {
       { repeat: 2 }
     );
 
-    setTimeout(() => {
+    this.schedule(() => {
       if (!this.target || this.state !== AiState.Combat) {
         this.chargingAttack = false;
         return;
@@ -1176,7 +1193,7 @@ export class BattleAi {
     this.faceTarget();
     this.event.dash({ x: dirX, y: dirY }, 10, 200);
 
-    setTimeout(() => {
+    this.schedule(() => {
       if (!this.target || this.state !== AiState.Combat) return;
       this.performMeleeAttack();
     }, 200);
@@ -1241,24 +1258,24 @@ export class BattleAi {
   /**
    * Try to dodge
    */
-  private tryDodge() {
+  private tryDodge(): boolean {
     const currentTime = Date.now();
 
     if (currentTime - this.lastDodgeTime < this.dodgeCooldown) {
       this.debugLog('dodge', `Dodge on cooldown (${this.dodgeCooldown - (currentTime - this.lastDodgeTime)}ms remaining)`);
-      return;
+      return false;
     }
     if (Math.random() > this.dodgeChance) {
       this.debugLog('dodge', `Dodge roll failed (chance=${(this.dodgeChance * 100).toFixed(0)}%)`);
-      return;
+      return false;
     }
-    if (!this.target) return;
+    if (!this.target) return false;
 
     const dx = this.target.x() - this.event.x();
     const dy = this.target.y() - this.event.y();
     const dist = Math.sqrt(dx * dx + dy * dy);
 
-    if (dist === 0) return;
+    if (dist === 0) return false;
 
     // Perpendicular direction
     const dodgeDirX = -dy / dist;
@@ -1272,12 +1289,13 @@ export class BattleAi {
     // Counter-attack for defensive types
     if (this.enemyType === EnemyType.Defensive && Math.random() < 0.5) {
       this.debugLog('dodge', 'Counter-attack after dodge');
-      setTimeout(() => {
+      this.schedule(() => {
         if (this.target && this.state === AiState.Combat) {
           this.selectAndPerformAttack();
         }
       }, 400);
     }
+    return true;
   }
 
   private canDodge(): boolean {
@@ -1461,8 +1479,16 @@ export class BattleAi {
    */
   takeDamage(attacker: RpgPlayer): boolean {
     // Apply damage using RPGJS system
-    const { damage } = this.event.applyDamage(attacker);
+    const raw = this.event.applyDamage(attacker);
+    return this.handleDamage(attacker, {
+      damage: raw.damage ?? 0,
+      defeated: this.event.hp <= 0,
+      raw,
+    });
+  }
 
+  handleDamage(attacker: RpgPlayer, damageResult: ActionBattleDamageResult): boolean {
+    const damage = damageResult.damage;
     this.debugLog('damage', `Took ${damage} damage from ${attacker.id} (HP: ${this.event.hp}/${this.event.param[MAXHP] || '?'})`);
 
     // Visual feedback
@@ -1489,7 +1515,7 @@ export class BattleAi {
     }
 
     // Check death
-    if (this.event.hp <= 0) {
+    if (damageResult.defeated || this.event.hp <= 0) {
       this.debugLog('damage', 'Defeated!');
       this.kill(attacker);
       return true;
@@ -1522,7 +1548,7 @@ export class BattleAi {
     
     this.destroy();
     if (removeDelay > 0) {
-      setTimeout(() => this.event.remove(), removeDelay);
+      this.schedule(() => this.event.remove(), removeDelay);
     } else {
       this.event.remove();
     }
@@ -1595,6 +1621,36 @@ export class BattleAi {
     }
   }
 
+  private applyCustomBehavior(currentTime: number) {
+    if (!this.behaviorKey) return;
+    const behavior = getActionBattleSystems().ai.behaviors[this.behaviorKey];
+    if (!behavior) return;
+    const maxHp = this.event.param[MAXHP];
+    const decision = behavior({
+      event: this.event,
+      target: this.target,
+      state: this.state,
+      enemyType: this.enemyType,
+      distance: this.target ? this.getDistance(this.event, this.target) : null,
+      hpPercent: maxHp ? this.event.hp / maxHp : null,
+      now: currentTime,
+    });
+    if (!decision) return;
+    if (decision.attackCooldown !== undefined) {
+      this.attackCooldown = decision.attackCooldown;
+    }
+    if (decision.moveToCooldown !== undefined) {
+      this.moveToCooldown = decision.moveToCooldown;
+    }
+    if (decision.attackPatterns?.length) {
+      this.attackPatterns = decision.attackPatterns;
+    }
+    if (decision.mode) {
+      this.behaviorMode = decision.mode;
+      this.behaviorEnabled = true;
+    }
+  }
+
   private handleTacticalMovement(distance: number) {
     if (!this.target) return;
     const minRange = this.attackRange * 0.7;
@@ -1651,6 +1707,15 @@ export class BattleAi {
     return true;
   }
 
+  private schedule(callback: () => void, delay: number) {
+    const timer = setTimeout(() => {
+      this.timers = this.timers.filter((entry) => entry !== timer);
+      callback();
+    }, delay);
+    this.timers.push(timer);
+    return timer;
+  }
+
   // Public getters
   getHealth(): number { return this.event.hp; }
   getMaxHealth(): number { return this.event.param[MAXHP]; }
@@ -1668,5 +1733,7 @@ export class BattleAi {
     }
     this.target = null;
     this.nearbyEnemies = [];
+    this.timers.forEach((timer) => clearTimeout(timer));
+    this.timers = [];
   }
 }

package/src/animations.ts

@@ -25,6 +25,46 @@ const DEFAULT_ANIMATION_BY_KEY: Record<ActionBattleAnimationKey, string> = {
   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(
@@ -37,15 +77,14 @@ export function resolveActionBattleAnimation(
   const defaultAnimationName =
     defaults.animationName ?? DEFAULT_ANIMATION_BY_KEY[key];
   const defaultRepeat = defaults.repeat ?? 1;
-  const hasConfiguredAnimation = animations
-    ? Object.prototype.hasOwnProperty.call(animations, key)
-    : false;
+  const { hasConfiguredAnimation, configured: configuredAnimation } =
+    getConfiguredAnimation(key, animations);
   if (!hasConfiguredAnimation && key !== "attack") {
     return null;
   }
 
   const configured = hasConfiguredAnimation
-    ? animations?.[key]
+    ? configuredAnimation
     : defaultAnimationName;
   const result =
     typeof configured === "function"

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,109 @@
 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";
+
+const DEFAULT_ATTACK_LOCK_DURATION_MS = 350;
+
+const beginLocalPlayerAttackLock = (
+  engine: RpgClientEngine,
+  durationMs: number
+): 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 =
+    typeof player.canMove === "function" ? player.canMove() : true;
+  const previousDirectionFixed = player.directionFixed;
+  const previousAnimationFixed = player.animationFixed;
+
+  if (typeof engine.interruptCurrentPlayerMovement === "function") {
+    engine.interruptCurrentPlayerMovement(player);
+  } else {
+    (engine.scene as any)?.stopMovement?.(player);
+  }
+  player.canMove.set(false);
+  player.directionFixed = true;
+  player.animationFixed = true;
+
+  setTimeout(() => {
+    if (runtimePlayer.__actionBattleAttackLockId !== lockId) return;
+    runtimePlayer.__actionBattleAttackLockedUntil = 0;
+    player.canMove.set(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 +112,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 +139,7 @@ export const createActionBattleClient = (
         ]
       : [],
     sprite: {
-      componentsInFront: targetingEnabled ? [TargetingOverlayComponent] : [],
+      componentsInFront,
     },
     sceneMap: {
       onAfterLoading() {
@@ -45,6 +148,23 @@ 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 lockDurationMs = Math.max(
+          0,
+          normalized.attack?.lockDurationMs ?? DEFAULT_ATTACK_LOCK_DURATION_MS
+        );
+        beginLocalPlayerAttackLock(
+          engine,
+          normalized.attack?.lockMovement === false ? 0 : lockDurationMs
+        );
+        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

@@ -24,6 +24,14 @@ 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: {},
 };
 
@@ -56,10 +64,32 @@ export function normalizeActionBattleOptions(
       ...DEFAULT_ACTION_BATTLE_OPTIONS.targeting,
       ...options.targeting,
     },
+    attack: {
+      ...DEFAULT_ACTION_BATTLE_OPTIONS.attack,
+      ...options.attack,
+    },
     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,
+        },
+      },
+    },
   };
 }