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

package/dist/server/ai.server.d.ts

@@ -0,0 +1,569 @@
+import { RpgEvent, RpgPlayer } from '@rpgjs/server';
+import { ActionBattleEnemyAttackProfileMap } from './core/enemy-attack-profiles';
+import { ActionBattleDamageResult } from './core/contracts';
+import { NormalizedActionBattleHitReactionProfile, ActionBattleAnimationOptions } from './types';
+type RpgEventWithBattleAi = RpgEvent & {
+    battleAi?: BattleAi;
+};
+export interface BattleAiRewardItem {
+    item?: any;
+    itemId?: string;
+    amount?: number;
+    chance?: number;
+}
+export interface BattleAiRewards {
+    exp?: number;
+    gold?: number;
+    items?: Array<BattleAiRewardItem | string>;
+    showNotification?: boolean;
+}
+export interface BattleAiDefeatReward {
+    readonly awarded: boolean;
+    giveTo(player?: RpgPlayer | null): void;
+}
+export interface BattleAiDefeatedContext {
+    event: RpgEvent;
+    attacker?: RpgPlayer;
+    reward: BattleAiDefeatReward;
+    remove: () => void;
+}
+export type BattleAiDefeatedCallback = (context: BattleAiDefeatedContext) => void;
+export type BattleAiLegacyDefeatedCallback = (event: RpgEvent, attacker?: RpgPlayer) => void;
+export interface BattleAiBaseOptions {
+    enemyType?: EnemyType;
+    attackCooldown?: number;
+    visionRange?: number;
+    attackRange?: number;
+    dodgeChance?: number;
+    dodgeCooldown?: number;
+    fleeThreshold?: number;
+    attackSkill?: any;
+    attackPatterns?: AttackPattern[];
+    attackProfiles?: ActionBattleEnemyAttackProfileMap;
+    patrolWaypoints?: Array<{
+        x: number;
+        y: number;
+    }>;
+    groupBehavior?: boolean;
+    moveToCooldown?: number;
+    retreatCooldown?: number;
+    poise?: number;
+    hitstunMs?: number;
+    invincibilityMs?: number;
+    behavior?: {
+        baseScore?: number;
+        updateInterval?: number;
+        minStateDuration?: number;
+        assaultThreshold?: number;
+        retreatThreshold?: number;
+    };
+    behaviorKey?: string;
+    animations?: ActionBattleAnimationOptions;
+    rewards?: BattleAiRewards;
+    autoAwardRewards?: boolean;
+}
+export interface BattleAiOptions extends BattleAiBaseOptions {
+    /** Callback called when the AI is defeated */
+    onDefeated?: BattleAiDefeatedCallback;
+}
+export interface BattleAiLegacyOptions extends BattleAiBaseOptions {
+    /** @deprecated Use the context callback signature instead. */
+    onDefeated?: BattleAiLegacyDefeatedCallback;
+}
+/**
+ * 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 attackProfiles;
+    private animations?;
+    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 rewards?;
+    private autoAwardRewards;
+    private defeated;
+    private lastFacingDirection;
+    private behaviorScore;
+    private behaviorMode;
+    private behaviorLastUpdate;
+    private behaviorUpdateInterval;
+    private behaviorAssaultThreshold;
+    private behaviorRetreatThreshold;
+    private behaviorMinStateDuration;
+    private behaviorEnabled;
+    private moveToCooldown;
+    private lastMoveToTime;
+    private retreatCooldown;
+    private lastRetreatTime;
+    private timers;
+    private behaviorKey?;
+    private poise;
+    private hitstunMs;
+    private invincibilityMs;
+    /**
+     * 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?: BattleAiOptions);
+    constructor(event: RpgEventWithBattleAi, options?: BattleAiLegacyOptions);
+    /**
+     * 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;
+    private executeMeleeAttack;
+    /**
+     * 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;
+    private getAttackProfile;
+    private telegraphAttack;
+    private scheduleAttackStartup;
+    /**
+     * 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;
+    handleDamage(attacker: RpgPlayer, damageResult: ActionBattleDamageResult & {
+        reaction?: NormalizedActionBattleHitReactionProfile;
+    }): 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;
+    private updateBehavior;
+    private applyCustomBehavior;
+    private handleTacticalMovement;
+    private handleAssaultMovement;
+    private requestMoveTo;
+    private schedule;
+    getHealth(): number;
+    getMaxHealth(): number;
+    getTarget(): InstanceType<typeof RpgPlayer> | null;
+    getState(): AiState;
+    getEnemyType(): EnemyType;
+    /**
+     * Clean up
+     */
+    destroy(): void;
+}
+export {};

package/dist/server/animations.d.ts

@@ -0,0 +1,16 @@
+import { ActionBattleAnimationContext, ActionBattleAnimationEntity, ActionBattleAnimationKey, ActionBattleAnimationOptions } from './types';
+export declare 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;
+}
+export declare function resolveActionBattleAnimation(key: ActionBattleAnimationKey, entity: ActionBattleAnimationEntity, animations?: ActionBattleAnimationOptions, context?: ActionBattleAnimationContext, defaults?: ActionBattleAnimationDefaults): ResolvedActionBattleAnimation | null;
+export declare function playActionBattleAnimation(key: ActionBattleAnimationKey, entity: ActionBattleAnimationEntity, animations?: ActionBattleAnimationOptions, context?: ActionBattleAnimationContext, defaults?: ActionBattleAnimationDefaults): ResolvedActionBattleAnimation | null;
+export declare function getActionBattleAnimationRemovalDelay(animation: ResolvedActionBattleAnimation | null): number;

package/dist/server/config.d.ts

@@ -0,0 +1,5 @@
+import { ActionBattleOptions } from './types';
+export declare const DEFAULT_ACTION_BATTLE_OPTIONS: ActionBattleOptions;
+export declare function normalizeActionBattleOptions(options?: ActionBattleOptions): ActionBattleOptions;
+export declare function setActionBattleOptions(options: ActionBattleOptions): void;
+export declare function getActionBattleOptions(): ActionBattleOptions;

package/dist/server/core/attack-profile.d.ts

@@ -0,0 +1,9 @@
+import { ActionBattleAttackHitboxMap, ActionBattleAttackProfile, NormalizedActionBattleAttackProfile } from '../types';
+export declare const DEFAULT_ACTION_BATTLE_ATTACK_PROFILE: NormalizedActionBattleAttackProfile;
+export interface ActionBattleAttackProfileFallbacks {
+    id?: string;
+    lockMovement?: boolean;
+    lockDurationMs?: number;
+    hitboxes?: ActionBattleAttackHitboxMap;
+}
+export declare function normalizeActionBattleAttackProfile(profile?: ActionBattleAttackProfile | undefined, fallbacks?: ActionBattleAttackProfileFallbacks): NormalizedActionBattleAttackProfile;

package/dist/server/core/attack-runtime.d.ts

@@ -0,0 +1,20 @@
+import { ActionBattleAttackHitPolicy, ActionBattleOptions, NormalizedActionBattleAttackProfile } from '../types';
+export declare const ACTION_BATTLE_HITBOX_FRAME_MS = 16;
+export declare function getNormalizedActionBattleAttackProfile(options?: ActionBattleOptions): NormalizedActionBattleAttackProfile;
+export declare function resolveActionBattleHitboxSpeed(profile: NormalizedActionBattleAttackProfile, hitboxCount: number): number;
+export declare function scheduleActionBattleStartup(profile: NormalizedActionBattleAttackProfile, callback: () => void, scheduler?: (callback: () => void, delayMs: number) => unknown): unknown;
+export declare function createActionBattleAttackId(attackerId: string | number | undefined, profileId: string): string;
+export declare class ActionBattleHitTracker {
+    private readonly hitPolicy;
+    private hitTargets;
+    constructor(hitPolicy: ActionBattleAttackHitPolicy);
+    canHit(target: {
+        id?: string | number;
+    } | undefined): boolean;
+    recordHit(target: {
+        id?: string | number;
+    } | undefined): void;
+    tryHit(target: {
+        id?: string | number;
+    } | undefined): boolean;
+}

package/dist/server/core/context.d.ts

@@ -0,0 +1,5 @@
+import { ActionBattleOptions } from '../types';
+import { ActionBattleSystems } from './contracts';
+export declare const setActionBattleSystems: (options?: ActionBattleOptions) => void;
+export declare const getActionBattleSystems: () => ActionBattleSystems;
+export declare const createActionBattleSystems: (options?: ActionBattleOptions) => ActionBattleSystems;

package/dist/server/core/defaults.d.ts

@@ -0,0 +1,81 @@
+import { RpgPlayer } from '@rpgjs/server';
+import { ActionBattleAiBehavior, ActionBattleAttackContext, ActionBattleCombatSystem, ActionBattleDamageContext, ActionBattleKnockbackContext, ActionBattleKnockbackResult, ActionBattleSystems } from './contracts';
+export declare const DEFAULT_ZELDA_PLAYER_HITBOXES: {
+    up: {
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+    down: {
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+    left: {
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+    right: {
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+    default: {
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+};
+export declare const createDefaultPlayerHitboxResolver: (hitboxes?: {
+    up: {
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+    down: {
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+    left: {
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+    right: {
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+    default: {
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+}) => (context: ActionBattleAttackContext) => {
+    x: any;
+    y: any;
+    width: number;
+    height: number;
+}[];
+export declare const defaultRpgjsDamageResolver: (context: ActionBattleDamageContext) => {
+    damage: any;
+    defeated: boolean;
+    raw: any;
+};
+export declare const defaultKnockbackResolver: (context: ActionBattleKnockbackContext) => ActionBattleKnockbackResult;
+export declare const defaultCombatSystem: ActionBattleCombatSystem;
+export declare const defaultEnemyBehaviors: Record<string, ActionBattleAiBehavior>;
+export declare const defaultActionBattleSystems: ActionBattleSystems;
+export declare const getEntityWeaponKnockbackForce: (entity: RpgPlayer) => number;