@rpgjs/action-battle 5.0.0-alpha.28

package/dist/ai.server.d.ts

@@ -0,0 +1,482 @@
+import { RpgEvent, RpgPlayer } from '@rpgjs/server';
+type RpgEventWithBattleAi = RpgEvent & {
+    battleAi: BattleAi;
+};
+/**
+ * Hit result data returned after applying damage
+ *
+ * Contains information about the hit including damage dealt,
+ * knockback parameters, and whether the target was defeated.
+ * Used by hooks to customize hit behavior.
+ *
+ * @example
+ * ```ts
+ * const hitResult: HitResult = {
+ *   damage: 25,
+ *   knockbackForce: 50,
+ *   knockbackDuration: 300,
+ *   defeated: false,
+ *   attacker: this.event,
+ *   target: player
+ * };
+ * ```
+ */
+export interface HitResult {
+    /** Damage dealt to the target */
+    damage: number;
+    /** Knockback force applied (from weapon or default) */
+    knockbackForce: number;
+    /** Knockback duration in milliseconds */
+    knockbackDuration: number;
+    /** Whether the target was defeated */
+    defeated: boolean;
+    /** The entity that attacked */
+    attacker: RpgEvent | RpgPlayer;
+    /** The entity that was hit */
+    target: RpgPlayer | RpgEvent;
+}
+/**
+ * Hook options for customizing hit behavior
+ *
+ * Allows overriding knockback parameters and adding custom effects
+ * when a hit is applied.
+ *
+ * @example
+ * ```ts
+ * const hooks: ApplyHitHooks = {
+ *   onBeforeHit(result) {
+ *     // Reduce knockback for armored enemies
+ *     if (result.target.hasState('armored')) {
+ *       result.knockbackForce *= 0.5;
+ *     }
+ *     return result;
+ *   },
+ *   onAfterHit(result) {
+ *     // Add poison effect on hit
+ *     if (Math.random() < 0.3) {
+ *       result.target.addState('poison');
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface ApplyHitHooks {
+    /**
+     * Called before the hit is applied
+     * Can modify the hit result before damage and knockback
+     *
+     * @param result - The hit result data
+     * @returns Modified hit result or void to use original
+     */
+    onBeforeHit?: (result: HitResult) => HitResult | void;
+    /**
+     * Called after the hit is applied
+     * Used for side effects like adding states, playing sounds, etc.
+     *
+     * @param result - The final hit result data
+     */
+    onAfterHit?: (result: HitResult) => void;
+}
+/**
+ * AI Debug Logger
+ *
+ * Conditional logging utility for AI behavior debugging.
+ * Enable by setting `AiDebug.enabled = true` or via environment variable `RPGJS_DEBUG_AI=1`
+ *
+ * @example
+ * ```ts
+ * // Enable debug logging
+ * AiDebug.enabled = true;
+ *
+ * // Or filter by event ID
+ * AiDebug.filterEventId = 'goblin-1';
+ * ```
+ */
+export declare const AiDebug: {
+    /** Enable/disable all AI debug logs */
+    enabled: boolean;
+    /** Filter logs to a specific event ID (null = all events) */
+    filterEventId: string | null;
+    /** Log categories to enable (empty = all) */
+    categories: string[];
+    /**
+     * Log an AI debug message
+     *
+     * @param category - Log category (e.g., 'state', 'attack', 'movement', 'damage')
+     * @param eventId - Event ID for filtering
+     * @param message - Log message
+     * @param data - Optional additional data
+     */
+    log(category: string, eventId: string | undefined, message: string, data?: any): void;
+};
+/**
+ * AI State enumeration
+ *
+ * Defines the different states an AI can be in, each with its own behavior.
+ */
+export declare enum AiState {
+    Idle = "idle",
+    Alert = "alert",
+    Combat = "combat",
+    Flee = "flee",
+    Stunned = "stunned"
+}
+/**
+ * Enemy Type enumeration
+ *
+ * Defines different enemy archetypes with unique behaviors.
+ * Stats (HP, ATK, etc.) should be set on the event itself via onInit.
+ */
+export declare enum EnemyType {
+    Aggressive = "aggressive",
+    Defensive = "defensive",
+    Ranged = "ranged",
+    Tank = "tank",
+    Berserker = "berserker"
+}
+/**
+ * Attack Pattern enumeration
+ *
+ * Different attack patterns the AI can use.
+ */
+export declare enum AttackPattern {
+    Melee = "melee",
+    Combo = "combo",
+    Charged = "charged",
+    Zone = "zone",
+    DashAttack = "dashAttack"
+}
+/**
+ * Default knockback configuration
+ *
+ * Used when no weapon is equipped or weapon doesn't specify knockback.
+ */
+export declare const DEFAULT_KNOCKBACK: {
+    /** Default knockback force */
+    force: number;
+    /** Default knockback duration in milliseconds */
+    duration: number;
+};
+/**
+ * Advanced Battle AI Controller for events
+ *
+ * This class provides intelligent combat behavior control for events.
+ * It uses the existing RPGJS API for stats, skills, items, etc.
+ * The AI only manages behavior - the event's stats should be configured
+ * in onInit using standard RPGJS methods.
+ *
+ * ## Usage with RPGJS API
+ *
+ * Configure the event stats using standard RPGJS methods:
+ * - `this.hp = 100` - Set health
+ * - `this.learnSkill(FireBall)` - Learn a skill
+ * - `this.addItem(Potion, 3)` - Add items
+ * - `this.equip(Sword)` - Equip items
+ * - `this.setClass(WarriorClass)` - Set class
+ * - `this.param[ATK] = 20` - Set parameters
+ *
+ * @example
+ * ```ts
+ * function GoblinEnemy() {
+ *   return {
+ *     name: "Goblin",
+ *     onInit() {
+ *       this.setGraphic("goblin");
+ *
+ *       // Configure stats using RPGJS API
+ *       this.hp = 80;
+ *       this.param[ATK] = 15;
+ *       this.param[PDEF] = 5;
+ *       this.learnSkill(Slash);
+ *
+ *       // Apply AI behavior
+ *       new BattleAi(this, {
+ *         enemyType: EnemyType.Aggressive,
+ *         attackSkill: Slash
+ *       });
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export declare class BattleAi {
+    private event;
+    private target;
+    private lastAttackTime;
+    private updateInterval?;
+    /**
+     * Log AI debug message for this event
+     */
+    private debugLog;
+    private state;
+    private stateStartTime;
+    private stunnedUntil;
+    private enemyType;
+    private attackCooldown;
+    private visionRange;
+    private attackRange;
+    private dodgeChance;
+    private dodgeCooldown;
+    private lastDodgeTime;
+    private fleeThreshold;
+    private attackSkill;
+    private attackPatterns;
+    private comboCount;
+    private comboMax;
+    private chargingAttack;
+    private groupBehavior;
+    private nearbyEnemies;
+    private groupUpdateInterval;
+    private patrolWaypoints;
+    private currentPatrolIndex;
+    private lastHpCheck;
+    private recentDamageTaken;
+    private damageCheckInterval;
+    private isMovingToTarget;
+    private onDefeatedCallback?;
+    private lastFacingDirection;
+    /**
+     * Create a new Battle AI Controller
+     *
+     * The AI controls behavior only. Stats should be set on the event
+     * using standard RPGJS methods (hp, param, learnSkill, etc.)
+     *
+     * @param event - The event to control
+     * @param options - AI behavior configuration
+     *
+     * @example
+     * ```ts
+     * // In your event's onInit
+     * this.hp = 100;
+     * this.param[ATK] = 20;
+     * this.learnSkill(FireBall);
+     *
+     * new BattleAi(this, {
+     *   enemyType: EnemyType.Ranged,
+     *   attackSkill: FireBall,
+     *   visionRange: 200,
+     *   fleeThreshold: 0.2
+     * });
+     * ```
+     */
+    constructor(event: RpgEventWithBattleAi, options?: {
+        enemyType?: EnemyType;
+        attackCooldown?: number;
+        visionRange?: number;
+        attackRange?: number;
+        dodgeChance?: number;
+        dodgeCooldown?: number;
+        fleeThreshold?: number;
+        attackSkill?: any;
+        attackPatterns?: AttackPattern[];
+        patrolWaypoints?: Array<{
+            x: number;
+            y: number;
+        }>;
+        groupBehavior?: boolean;
+        /** Callback called when the AI is defeated */
+        onDefeated?: (event: RpgEvent) => void;
+    });
+    /**
+     * Apply enemy type-specific behavior modifiers
+     *
+     * This only affects AI behavior (cooldowns, ranges, dodge).
+     * Stats should be set on the event itself.
+     */
+    private applyEnemyTypeBehavior;
+    /**
+     * Setup vision detection
+     */
+    private setupVision;
+    /**
+     * Start the AI behavior loop
+     */
+    private startAiBehaviorLoop;
+    /**
+     * Change AI state with validated transitions
+     */
+    private changeState;
+    /**
+     * Main AI behavior update loop
+     */
+    private updateAiBehavior;
+    /**
+     * Update idle behavior (patrolling)
+     */
+    private updateIdleBehavior;
+    /**
+     * Update alert behavior
+     */
+    private updateAlertBehavior;
+    /**
+     * Update combat behavior
+     */
+    private updateCombatBehavior;
+    /**
+     * Update flee behavior
+     */
+    private updateFleeBehavior;
+    /**
+     * Select and perform an attack pattern
+     */
+    private selectAndPerformAttack;
+    /**
+     * Select attack pattern with weighted probability
+     */
+    private selectAttackPattern;
+    /**
+     * Perform attack pattern
+     */
+    private performAttackPattern;
+    /**
+     * Perform melee attack
+     * Uses skill if configured, otherwise creates hitbox
+     */
+    private performMeleeAttack;
+    /**
+     * Perform basic hitbox attack when no skill is set
+     */
+    private performBasicHitbox;
+    /**
+     * Apply hit to target using RPGJS damage system with knockback
+     *
+     * Calculates damage using RPGJS formula, applies knockback based on
+     * equipped weapon's knockbackForce property, and triggers visual effects.
+     * Supports hooks for customizing behavior.
+     *
+     * @param target - The player or entity being hit
+     * @param hooks - Optional hooks for customizing hit behavior
+     * @returns The hit result containing damage and knockback info
+     *
+     * @example
+     * ```ts
+     * // Basic hit
+     * this.applyHit(player);
+     *
+     * // With custom hooks
+     * this.applyHit(player, {
+     *   onBeforeHit(result) {
+     *     result.knockbackForce *= 1.5; // Increase knockback
+     *     return result;
+     *   },
+     *   onAfterHit(result) {
+     *     console.log(`Dealt ${result.damage} damage!`);
+     *   }
+     * });
+     * ```
+     */
+    private applyHit;
+    /**
+     * Get knockback force from equipped weapon
+     *
+     * Retrieves the knockbackForce property from the event's equipped weapon.
+     * Falls back to DEFAULT_KNOCKBACK.force if no weapon or property is set.
+     *
+     * @returns Knockback force value
+     *
+     * @example
+     * ```ts
+     * // Weapon with knockbackForce: 80
+     * const force = this.getWeaponKnockbackForce(); // 80
+     *
+     * // No weapon equipped
+     * const force = this.getWeaponKnockbackForce(); // 50 (default)
+     * ```
+     */
+    private getWeaponKnockbackForce;
+    /**
+     * Perform combo attack
+     */
+    private performComboAttack;
+    /**
+     * Perform charged attack
+     */
+    private performChargedAttack;
+    /**
+     * Perform zone attack (360 degrees)
+     */
+    private performZoneAttack;
+    /**
+     * Perform dash attack
+     */
+    private performDashAttack;
+    /**
+     * Face the current target with hysteresis to prevent animation flickering
+     *
+     * Uses multiple strategies to prevent flickering:
+     * 1. When very close to target (collision), keep current direction
+     * 2. When near diagonal, require significant difference to change
+     * 3. Only change if direction is clearly wrong (opposite)
+     */
+    private faceTarget;
+    /**
+     * Try to dodge
+     */
+    private tryDodge;
+    private canDodge;
+    private shouldDodge;
+    /**
+     * Flee from target
+     */
+    private fleeFromTarget;
+    /**
+     * Retreat from target (temporary)
+     */
+    private retreatFromTarget;
+    /**
+     * Check damage taken for retreat decision
+     */
+    private checkDamageTaken;
+    /**
+     * Start patrol
+     */
+    private startPatrol;
+    /**
+     * Update group behavior
+     */
+    private updateGroupBehavior;
+    /**
+     * Find nearby enemies
+     */
+    private findNearbyEnemies;
+    /**
+     * Apply formation around target
+     */
+    private applyFormation;
+    /**
+     * Handle player entering vision
+     */
+    onDetectInShape(player: InstanceType<typeof RpgPlayer>, shape: any): void;
+    /**
+     * Handle player leaving vision
+     */
+    onDetectOutShape(player: InstanceType<typeof RpgPlayer>, shape: any): void;
+    /**
+     * Handle taking damage (called from server.ts)
+     *
+     * This triggers state changes like stun and flee check.
+     * The actual damage is applied externally via RPGJS API.
+     */
+    takeDamage(attacker: RpgPlayer): boolean;
+    /**
+     * Kill this AI
+     *
+     * Stops all movements, cleans up resources, calls the onDefeated hook,
+     * and removes the event from the map.
+     */
+    private kill;
+    /**
+     * Get distance between entities
+     */
+    private getDistance;
+    getHealth(): number;
+    getMaxHealth(): number;
+    getTarget(): InstanceType<typeof RpgPlayer> | null;
+    getState(): AiState;
+    getEnemyType(): EnemyType;
+    /**
+     * Clean up
+     */
+    destroy(): void;
+}
+export {};

package/dist/client/index.js

@@ -0,0 +1,25 @@
+import client from "./index2.js";
+import { createModule } from "@rpgjs/common";
+import { AiDebug, AiState, AttackPattern, BattleAi, DEFAULT_KNOCKBACK, EnemyType } from "./index3.js";
+import { DEFAULT_PLAYER_ATTACK_HITBOXES, applyPlayerHitToEvent, getPlayerWeaponKnockbackForce } from "./index4.js";
+const server = null;
+function provideActionBattle() {
+  return createModule("ActionBattle", [
+    {
+      server,
+      client
+    }
+  ]);
+}
+export {
+  AiDebug,
+  AiState,
+  AttackPattern,
+  BattleAi,
+  DEFAULT_KNOCKBACK,
+  DEFAULT_PLAYER_ATTACK_HITBOXES,
+  EnemyType,
+  applyPlayerHitToEvent,
+  getPlayerWeaponKnockbackForce,
+  provideActionBattle
+};

package/dist/client/index2.js

@@ -0,0 +1,13 @@
+import { PrebuiltComponentAnimations } from "@rpgjs/client";
+import { defineModule } from "@rpgjs/common";
+const client = defineModule({
+  componentAnimations: [
+    {
+      id: "hit",
+      component: PrebuiltComponentAnimations.Hit
+    }
+  ]
+});
+export {
+  client as default
+};