CustomNPC-Plus-API/java/noppes/npcs/api/ability/IAbility.java

package noppes.npcs.api.ability;

import noppes.npcs.api.INbt;

/**
 * Interface for NPC abilities.
 * Abilities are special attacks or actions that NPCs can perform during combat.
 */
public interface IAbility extends IAbilityAction {

    /**
     * Get the unique ID (UUID for custom abilities, registry key for built-in).
     * This is the stable reference that never changes after creation.
     */
    String getId();

    /**
     * Set the unique ID of this ability instance.
     */
    void setId(String id);

    /**
     * Get the unique identifier/name of this ability (used for file naming, commands, search).
     */
    String getName();

    /**
     * Set the unique identifier/name of this ability.
     */
    void setName(String name);

    /**
     * Get the display name (cosmetic). Falls back to getName() if not set.
     */
    String getDisplayName();

    /**
     * Set the display name (cosmetic). Pass empty string to use getName() as display.
     */
    void setDisplayName(String displayName);

    /**
     * Get the type ID of this ability (e.g., "cnpc:slam", "cnpc:beam").
     */
    String getTypeId();

    /**
     * Check if this ability is enabled.
     */
    boolean isEnabled();

    /**
     * Enable or disable this ability.
     */
    void setEnabled(boolean enabled);

    /**
     * Get the selection weight for random ability selection.
     * Higher weight = more likely to be selected.
     */
    int getWeight();

    /**
     * Set the selection weight.
     */
    void setWeight(int weight);

    /**
     * Get the minimum range at which this ability can be used.
     */
    float getMinRange();

    /**
     * Set the minimum range.
     */
    void setMinRange(float range);

    /**
     * Get the maximum range at which this ability can be used.
     */
    float getMaxRange();

    /**
     * Set the maximum range.
     */
    void setMaxRange(float range);

    /**
     * Get the cooldown time in ticks.
     */
    int getCooldownTicks();

    /**
     * Set the cooldown time in ticks.
     */
    void setCooldownTicks(int ticks);

    /**
     * Get the wind-up time in ticks (telegraph phase).
     */
    int getWindUpTicks();

    /**
     * Set the wind-up time in ticks.
     */
    void setWindUpTicks(int ticks);

    /**
     * Get the dazed time in ticks (stun after interrupt during WINDUP).
     */
    int getDazedTicks();

    /**
     * Set the dazed time in ticks.
     */
    void setDazedTicks(int ticks);

    /**
     * Check if this ability can be interrupted by damage.
     */
    boolean isInterruptible();

    /**
     * Set whether this ability can be interrupted.
     */
    void setInterruptible(boolean interruptible);

    /**
     * Get the lock movement type for this ability.
     *
     * @return 0=NO, 1=WINDUP, 2=ACTIVE, 3=WINDUP_AND_ACTIVE
     */
    int getLockMovementType();

    /**
     * Set the lock movement type for this ability.
     *
     * @param type 0=NO, 1=WINDUP, 2=ACTIVE, 3=WINDUP_AND_ACTIVE
     */
    void setLockMovementType(int type);

    /**
     * Get the rotation mode for this ability.
     *
     * @return 0=FREE, 1=LOCKED, 2=TRACK
     */
    int getRotationModeType();

    /**
     * Set the rotation mode for this ability.
     *
     * @param type 0=FREE, 1=LOCKED, 2=TRACK
     */
    void setRotationModeType(int type);

    /**
     * Get the rotation phase for this ability (when rotation mode applies).
     *
     * @return 0=NO, 1=WINDUP, 2=ACTIVE, 3=WINDUP_AND_ACTIVE
     */
    int getRotationPhaseType();

    /**
     * Set the rotation phase for this ability.
     *
     * @param type 0=NO, 1=WINDUP, 2=ACTIVE, 3=WINDUP_AND_ACTIVE
     */
    void setRotationPhaseType(int type);

    /**
     * Check if movement (pathfinding/motion) is locked during the WINDUP phase.
     */
    boolean isMovementLockedDuringWindup();

    /**
     * Check if movement (pathfinding/motion) is locked during the ACTIVE phase.
     */
    boolean isMovementLockedDuringActive();

    /**
     * Check if rotation (yaw/pitch) is locked during the WINDUP phase.
     */
    boolean isRotationLockedDuringWindup();

    /**
     * Check if rotation (yaw/pitch) is locked during the ACTIVE phase.
     */
    boolean isRotationLockedDuringActive();

    /**
     * Check if this ability is currently being executed.
     */
    boolean isExecuting();

    /**
     * Get the current execution phase (0=IDLE, 1=WINDUP, 2=ACTIVE, 3=DAZED).
     */
    int getPhaseInt();

    /**
     * Get the current tick within the current phase.
     */
    int getCurrentTick();

    /**
     * Get the allowed user type for this ability.
     *
     * @return 0=NPC_ONLY, 1=PLAYER_ONLY, 2=BOTH
     */
    int getAllowedByType();

    /**
     * Set the allowed user type for this ability.
     *
     * @param type 0=NPC_ONLY, 1=PLAYER_ONLY, 2=BOTH
     */
    void setAllowedByType(int type);

    /**
     * Check if this ability ignores cooldowns.
     */
    boolean isIgnoreCooldown();

    /**
     * Set whether this ability ignores cooldowns.
     */
    void setIgnoreCooldown(boolean ignore);

    /**
     * Check if this ability uses per-ability cooldown instead of global cooldown.
     * When true, using this ability only puts THIS ability on cooldown, not all abilities.
     */
    boolean isPerAbilityCooldown();

    /**
     * Set whether this ability uses per-ability cooldown.
     */
    void setPerAbilityCooldown(boolean perAbility);

    /**
     * Get this ability's data as NBT.
     */
    INbt getNbt();

    /**
     * Set this ability's data from NBT.
     */
    void setNbt(INbt nbt);

    // Burst system

    boolean isBurstEnabled();

    void setBurstEnabled(boolean enabled);

    int getBurstAmount();

    void setBurstAmount(int amount);

    int getBurstDelay();

    void setBurstDelay(int delay);

    boolean isBurstReplayAnimations();

    void setBurstReplayAnimations(boolean replay);

    boolean isBurstOverlap();

    void setBurstOverlap(boolean overlap);

    // Toggle system

    /**
     * Check if this ability is toggleable (has at least 1 toggle state).
     */
    boolean isToggleable();

    /**
     * Get the number of toggle states.
     * 0 = not toggleable, 1 = binary on/off, 2+ = multi-state cycling.
     */
    int getToggleStates();

    /**
     * Set the number of toggle states.
     * 0 = not toggleable, 1 = binary on/off, 2+ = multi-state cycling.
     */
    void setToggleStates(int states);

    /**
     * Get the display label for a specific toggle state (1-indexed).
     * @return the label, or null if none set
     */
    String getToggleStateLabel(int state);
}