CustomNPC-Plus-API/java/noppes/npcs/api/event/IPlayerAbilityEvent.java

package noppes.npcs.api.event;

import cpw.mods.fml.common.eventhandler.Cancelable;
import noppes.npcs.api.IDamageSource;
import noppes.npcs.api.ability.IAbility;
import noppes.npcs.api.entity.IEntityLivingBase;

/**
 * Events related to player ability execution.
 * These events are fired during the ability lifecycle when a player uses an ability.
 */
public interface IPlayerAbilityEvent extends IPlayerEvent {

    /**
     * Get the ability involved in this event.
     */
    IAbility getAbility();

    /**
     * Get the target of the ability, or null if no target.
     */
    IEntityLivingBase getTarget();

    /**
     * Fired when a player's ability starts executing (enters WINDUP phase).
     * Canceling prevents the ability from starting.
     *
     * @hookName abilityStart
     */
    @Cancelable
    interface StartEvent extends IPlayerAbilityEvent {
    }

    /**
     * Fired when a player's ability enters the ACTIVE phase and performs its effect.
     * Canceling prevents the ability effect from occurring.
     *
     * @hookName abilityExecute
     */
    @Cancelable
    interface ExecuteEvent extends IPlayerAbilityEvent {
    }

    /**
     * Fired when a player's ability is interrupted by damage.
     *
     * @hookName abilityInterrupt
     */
    interface InterruptEvent extends IPlayerAbilityEvent {
        /**
         * Get the damage source that caused the interruption, or null if not damage-triggered.
         */
        IDamageSource getDamageSource();

        /**
         * Get the amount of damage that caused the interruption.
         */
        float getDamage();
    }

    /**
     * Fired when a player's ability completes its full execution cycle.
     *
     * @hookName abilityComplete
     */
    interface CompleteEvent extends IPlayerAbilityEvent {
    }

    /**
     * Fired every tick while a player's ability is executing.
     * Provides the current phase and tick count.
     *
     * @hookName abilityTick
     */
    interface TickEvent extends IPlayerAbilityEvent {
        /**
         * Get the current phase of the ability.
         * 0 = IDLE, 1 = WINDUP, 2 = ACTIVE, 3 = RECOVERY
         */
        int getAbilityPhase();

        /**
         * Get the current tick count within the phase.
         */
        int getTick();
    }

    /**
     * Fired when a toggle ability is switched ON or OFF.
     * Canceling prevents the toggle from changing state.
     *
     * @hookName abilityToggle
     */
    @Cancelable
    interface ToggleEvent extends IPlayerAbilityEvent {
        /**
         * @return true if the toggle is being turned ON (any state), false if being turned OFF
         */
        boolean isTogglingOn();

        /**
         * @return the previous state (0 = was off, 1+ = previous active state)
         */
        int getOldState();

        /**
         * @return the new state (0 = turning off, 1+ = new active state)
         */
        int getNewState();
    }

    /**
     * Fired every 10 ticks for each active toggle ability.
     * Scripts can call {@link #setEnabled(boolean)} with false to force-deactivate the toggle.
     *
     * @hookName abilityToggleUpdate
     */
    interface ToggleUpdateEvent extends IPlayerAbilityEvent {
        /**
         * @return the tick count since the toggle was activated
         */
        int getTick();

        /**
         * @return the current toggle state (1+)
         */
        int getState();

        /**
         * @return whether the toggle should remain active
         */
        boolean isEnabled();

        /**
         * Set to false to force-deactivate the toggle after this event completes.
         */
        void setEnabled(boolean enabled);
    }

    /**
     * Fired when a player's ability hits an entity with damage.
     * Canceling this event prevents the damage from being applied.
     *
     * @hookName abilityHit
     */
    @Cancelable
    interface HitEvent extends IPlayerAbilityEvent {
        /**
         * Get the entity that was hit by the ability.
         */
        IEntityLivingBase getHitEntity();

        /**
         * Get the damage amount.
         */
        float getDamage();

        /**
         * Set the damage amount. Allows scripts to modify damage.
         */
        void setDamage(float damage);

        /**
         * Get the horizontal knockback amount.
         */
        float getKnockback();

        /**
         * Set the horizontal knockback amount.
         */
        void setKnockback(float knockback);

        /**
         * Get the vertical knockback (upward force) amount.
         */
        float getKnockbackUp();

        /**
         * Set the vertical knockback (upward force) amount.
         */
        void setKnockbackUp(float knockbackUp);
    }
}