Update API and Cleanup Unused Code

java/noppes/npcs/api/ability/IAbility.java

@@ -16,6 +16,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set the unique ID of this ability instance.
+     * @param id Unique ability ID.
      */
     void setId(String id);
 
@@ -26,6 +27,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set the unique identifier/name of this ability.
+     * @param name Unique identifier.
      */
     void setName(String name);
 
@@ -36,6 +38,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set the display name (cosmetic). Pass empty string to use getName() as display.
+     * @param displayName Display name, or empty string for default.
      */
     void setDisplayName(String displayName);
 
@@ -51,6 +54,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Enable or disable this ability.
+     * @param enabled Whether the ability is enabled.
      */
     void setEnabled(boolean enabled);
 
@@ -62,6 +66,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set the selection weight.
+     * @param weight Selection weight (higher = more likely).
      */
     void setWeight(int weight);
 
@@ -72,6 +77,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set the minimum range.
+     * @param range Minimum range in blocks.
      */
     void setMinRange(float range);
 
@@ -82,6 +88,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set the maximum range.
+     * @param range Maximum range in blocks.
      */
     void setMaxRange(float range);
 
@@ -92,6 +99,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set the cooldown time in ticks.
+     * @param ticks Cooldown duration in ticks.
      */
     void setCooldownTicks(int ticks);
 
@@ -102,6 +110,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set the wind-up time in ticks.
+     * @param ticks Wind-up duration in ticks.
      */
     void setWindUpTicks(int ticks);
 
@@ -112,6 +121,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set the dazed time in ticks.
+     * @param ticks Dazed duration in ticks.
      */
     void setDazedTicks(int ticks);
 
@@ -122,6 +132,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set whether this ability can be interrupted.
+     * @param interruptible Whether the ability is interruptible.
      */
     void setInterruptible(boolean interruptible);
 
@@ -223,6 +234,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set whether this ability ignores cooldowns.
+     * @param ignore Whether to ignore cooldowns.
      */
     void setIgnoreCooldown(boolean ignore);
 
@@ -234,6 +246,7 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set whether this ability uses per-ability cooldown.
+     * @param perAbility Whether to use per-ability cooldown.
      */
     void setPerAbilityCooldown(boolean perAbility);
 
@@ -244,29 +257,40 @@ public interface IAbility extends IAbilityAction {
 
     /**
      * Set this ability's data from NBT.
+     * @param nbt NBT data to load.
      */
     void setNbt(INbt nbt);
 
     // Burst system
 
+    /** @return Whether burst firing is enabled (fires multiple instances in rapid succession). */
     boolean isBurstEnabled();
 
+    /** @param enabled Whether burst firing is enabled. */
     void setBurstEnabled(boolean enabled);
 
+    /** @return Number of times the ability fires per burst. */
     int getBurstAmount();
 
+    /** @param amount Number of shots per burst. */
     void setBurstAmount(int amount);
 
+    /** @return Delay in ticks between each burst shot. */
     int getBurstDelay();
 
+    /** @param delay Delay in ticks between burst shots. */
     void setBurstDelay(int delay);
 
+    /** @return Whether animations replay for each burst shot. */
     boolean isBurstReplayAnimations();
 
+    /** @param replay Whether to replay animations per burst shot. */
     void setBurstReplayAnimations(boolean replay);
 
+    /** @return Whether burst shots can overlap (fire before previous shot ends). */
     boolean isBurstOverlap();
 
+    /** @param overlap Whether burst shots can overlap. */
     void setBurstOverlap(boolean overlap);
 
     // Toggle system
@@ -285,12 +309,14 @@ public interface IAbility extends IAbilityAction {
     /**
      * Set the number of toggle states.
      * 0 = not toggleable, 1 = binary on/off, 2+ = multi-state cycling.
+     * @param states Number of toggle states.
      */
     void setToggleStates(int states);
 
     /**
      * Get the display label for a specific toggle state (1-indexed).
-     * @return the label, or null if none set
+     * @param state Toggle state number (1-indexed).
+     * @return the label, or null if none set.
      */
     String getToggleStateLabel(int state);
 }

java/noppes/npcs/api/ability/IAbilityAction.java

@@ -6,20 +6,24 @@ package noppes.npcs.api.ability;
  */
 public interface IAbilityAction {
 
+    /** @return The unique identifier/name of this action. */
     String getName();
 
+    /** @return Whether this action is enabled. */
     boolean isEnabled();
 
+    /** @return Selection weight for random ability selection (higher = more likely). */
     int getWeight();
 
+    /** @return Cooldown duration in ticks after this action is used. */
     int getCooldownTicks();
 
+    /** @return Minimum range in blocks at which this action can be used. */
     float getMinRange();
 
+    /** @return Maximum range in blocks at which this action can be used. */
     float getMaxRange();
 
-    /**
-     * Whether this action is a chained ability (sequence) vs an individual ability.
-     */
+    /** @return Whether this action is a chained ability (sequence) vs an individual ability. */
     boolean isChain();
 }

java/noppes/npcs/api/ability/IChainedAbility.java

@@ -6,13 +6,27 @@ package noppes.npcs.api.ability;
  */
 public interface IChainedAbility extends IAbilityAction {
 
+    /** @return Whether all entries wind up simultaneously before execution begins. */
     boolean isWindUpAll();
 
+    /** @return The number of ability entries in this chain. */
     int getEntryCount();
 
+    /**
+     * @param index Entry index in the chain.
+     * @return The ability reference ID at the given index.
+     */
     String getEntryReference(int index);
 
+    /**
+     * @param index Entry index in the chain.
+     * @return The delay in ticks before executing this entry.
+     */
     int getEntryDelay(int index);
 
+    /**
+     * @param index Entry index in the chain.
+     * @return Whether this entry executes inline (overlapping with previous).
+     */
     boolean isEntryInline(int index);
 }

java/noppes/npcs/api/ability/data/IEnergyAnchorData.java

@@ -1,19 +1,31 @@
 package noppes.npcs.api.ability.data;
 
+/**
+ * Configuration for the anchor point of an energy ability projectile.
+ * Controls where the projectile spawns relative to the caster.
+ */
 public interface IEnergyAnchorData {
+    /** @return Anchor point ordinal (0=FEET, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=HEAD, 5=FRONT, 6=ABOVE_HEAD). */
     int getAnchor();
 
+    /** Set the anchor point. @param anchor Anchor ordinal (0=FEET, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=HEAD, 5=FRONT, 6=ABOVE_HEAD). */
     void setAnchor(int anchor);
 
+    /** @return X offset from the anchor point (positive = right). */
     float getAnchorOffsetX();
 
+    /** @param anchorOffsetX X offset from anchor (positive = right). */
     void setAnchorOffsetX(float anchorOffsetX);
 
+    /** @return Y offset from the anchor point (positive = up). */
     float getAnchorOffsetY();
 
+    /** @param anchorOffsetY Y offset from anchor (positive = up). */
     void setAnchorOffsetY(float anchorOffsetY);
 
+    /** @return Z offset from the anchor point (positive = forward). */
     float getAnchorOffsetZ();
 
+    /** @param anchorOffsetZ Z offset from anchor (positive = forward). */
     void setAnchorOffsetZ(float anchorOffsetZ);
 }

java/noppes/npcs/api/ability/data/IEnergyCombatData.java

@@ -1,27 +1,43 @@
 package noppes.npcs.api.ability.data;
 
+/**
+ * Combat properties for energy ability projectiles.
+ * Controls damage, knockback, and explosion behavior.
+ */
 public interface IEnergyCombatData {
+    /** @return Base damage dealt on hit. */
     float getDamage();
 
+    /** @param damage Base damage on hit. */
     void setDamage(float damage);
 
+    /** @return Horizontal knockback strength applied on hit. */
     float getKnockback();
 
+    /** @param knockback Horizontal knockback strength. */
     void setKnockback(float knockback);
 
+    /** @return Vertical knockback strength applied on hit. */
     float getKnockbackUp();
 
+    /** @param knockbackUp Vertical knockback strength. */
     void setKnockbackUp(float knockbackUp);
 
+    /** @return Whether the projectile explodes on impact. */
     boolean isExplosive();
 
+    /** @param explosive Whether to explode on impact. */
     void setExplosive(boolean explosive);
 
+    /** @return Explosion radius in blocks. */
     float getExplosionRadius();
 
+    /** @param explosionRadius Explosion radius in blocks. */
     void setExplosionRadius(float explosionRadius);
 
+    /** @return Damage falloff multiplier over distance (0.0-1.0). */
     float getExplosionDamageFalloff();
 
+    /** @param explosionDamageFalloff Damage falloff multiplier (0.0-1.0). */
     void setExplosionDamageFalloff(float explosionDamageFalloff);
 }

java/noppes/npcs/api/ability/data/IEnergyDisplayData.java

@@ -1,31 +1,49 @@
 package noppes.npcs.api.ability.data;
 
+/**
+ * Visual display properties for energy ability projectiles.
+ * Controls colors, transparency, and rotation speed.
+ */
 public interface IEnergyDisplayData {
+    /** @return Inner (core) color as a packed RGB integer. */
     int getInnerColor();
 
+    /** @param innerColor Inner color as a packed RGB integer. */
     void setInnerColor(int innerColor);
 
+    /** @return Outer (glow) color as a packed RGB integer. */
     int getOuterColor();
 
+    /** @param outerColor Outer color as a packed RGB integer. */
     void setOuterColor(int outerColor);
 
+    /** @return Whether the outer color layer is rendered. */
     boolean isOuterColorEnabled();
 
+    /** @param outerColorEnabled Whether to render the outer color layer. */
     void setOuterColorEnabled(boolean outerColorEnabled);
 
+    /** @return Width of the outer color layer relative to the projectile size. */
     float getOuterColorWidth();
 
+    /** @param outerColorWidth Outer color layer width. */
     void setOuterColorWidth(float outerColorWidth);
 
+    /** @return Alpha (opacity) of the outer color layer (0.0-1.0). */
     float getOuterColorAlpha();
 
+    /** @param outerColorAlpha Outer color opacity (0.0-1.0). */
     void setOuterColorAlpha(float outerColorAlpha);
 
+    /** @return Alpha (opacity) of the inner color layer (0.0-1.0). */
     float getInnerAlpha();
 
+    /** @param innerAlpha Inner color opacity (0.0-1.0). */
     void setInnerAlpha(float innerAlpha);
 
+    /** @return Visual rotation speed in degrees per tick. */
     float getRotationSpeed();
 
+    /** @param rotationSpeed Rotation speed in degrees per tick. */
     void setRotationSpeed(float rotationSpeed);
 }

java/noppes/npcs/api/ability/data/IEnergyHomingData.java

@@ -1,19 +1,31 @@
 package noppes.npcs.api.ability.data;
 
+/**
+ * Homing and speed properties for energy ability projectiles.
+ * Controls projectile velocity and target-seeking behavior.
+ */
 public interface IEnergyHomingData {
+    /** @return Projectile travel speed in blocks per tick. */
     float getSpeed();
 
+    /** @param speed Travel speed in blocks per tick. */
     void setSpeed(float speed);
 
+    /** @return Whether the projectile tracks its target. */
     boolean isHoming();
 
+    /** @param homing Whether to track the target. */
     void setHoming(boolean homing);
 
+    /** @return Homing turn strength (higher = tighter turns). */
     float getHomingStrength();
 
+    /** @param homingStrength Homing turn strength. */
     void setHomingStrength(float homingStrength);
 
+    /** @return Maximum distance at which homing activates, in blocks. */
     float getHomingRange();
 
+    /** @param homingRange Maximum homing activation range in blocks. */
     void setHomingRange(float homingRange);
 }

java/noppes/npcs/api/ability/data/IEnergyLifespanData.java

@@ -1,11 +1,19 @@
 package noppes.npcs.api.ability.data;
 
+/**
+ * Lifespan properties for energy ability projectiles.
+ * Controls how far and how long a projectile can travel before expiring.
+ */
 public interface IEnergyLifespanData {
+    /** @return Maximum travel distance in blocks before the projectile expires. */
     float getMaxDistance();
 
+    /** @param maxDistance Maximum travel distance in blocks. */
     void setMaxDistance(float maxDistance);
 
+    /** @return Maximum lifetime in ticks before the projectile expires. */
     int getMaxLifetime();
 
+    /** @param maxLifetime Maximum lifetime in ticks. */
     void setMaxLifetime(int maxLifetime);
 }

java/noppes/npcs/api/ability/data/IEnergyLightningData.java

@@ -1,19 +1,31 @@
 package noppes.npcs.api.ability.data;
 
+/**
+ * Lightning visual effect properties for energy ability projectiles.
+ * Controls the electric arc effect rendered around the projectile.
+ */
 public interface IEnergyLightningData {
+    /** @return Whether the lightning visual effect is enabled. */
     boolean isLightningEffect();
 
+    /** @param lightningEffect Whether to enable the lightning effect. */
     void setLightningEffect(boolean lightningEffect);
 
+    /** @return Density of lightning arcs (higher = more arcs). */
     float getLightningDensity();
 
+    /** @param lightningDensity Lightning arc density. */
     void setLightningDensity(float lightningDensity);
 
+    /** @return Radius of the lightning effect around the projectile, in blocks. */
     float getLightningRadius();
 
+    /** @param lightningRadius Lightning effect radius in blocks. */
     void setLightningRadius(float lightningRadius);
 
+    /** @return Fade-out time for lightning arcs in ticks. */
     int getLightningFadeTime();
 
+    /** @param lightningFadeTime Fade-out time in ticks. */
     void setLightningFadeTime(int lightningFadeTime);
 }

java/noppes/npcs/api/ability/type/IAbilityCharge.java

@@ -8,19 +8,27 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityCharge extends IAbility {
 
+    /** @return Movement speed during the charge in blocks per tick. */
     float getChargeSpeed();
 
+    /** @param speed Movement speed in blocks per tick. */
     void setChargeSpeed(float speed);
 
+    /** @return Damage dealt to entities hit during the charge. */
     float getDamage();
 
+    /** @param damage Damage on charge impact. */
     void setDamage(float damage);
 
+    /** @return Knockback strength applied to entities hit during the charge. */
     float getKnockback();
 
+    /** @param knockback Knockback strength on impact. */
     void setKnockback(float knockback);
 
+    /** @return Width of the charge hit area in blocks. */
     float getHitWidth();
 
+    /** @param width Hit area width in blocks. */
     void setHitWidth(float width);
 }

java/noppes/npcs/api/ability/type/IAbilityCounter.java

@@ -6,15 +6,21 @@ package noppes.npcs.api.ability.type;
  */
 public interface IAbilityCounter extends IAbilityDefend {
 
+    /** @return Counter-attack type ordinal (determines how counter damage is calculated). */
     int getCounterType();
 
+    /** @param type Counter-attack type ordinal. */
     void setCounterType(int type);
 
+    /** @return Counter-attack value (meaning depends on counter type, e.g. flat damage or multiplier). */
     float getCounterValue();
 
+    /** @param value Counter-attack value (flat damage or multiplier). */
     void setCounterValue(float value);
 
+    /** @return Animation ID played when the counter-attack triggers, or -1 for none. */
     int getCounterAnimationId();
 
+    /** @param animationId Animation ID for the counter-attack, or -1 for none. */
     void setCounterAnimationId(int animationId);
 }

java/noppes/npcs/api/ability/type/IAbilityCutter.java

@@ -8,42 +8,57 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityCutter extends IAbility {
 
+    /** @return Arc angle of the sweep in degrees. */
     float getArcAngle();
 
+    /** @param angle Arc angle in degrees. */
     void setArcAngle(float angle);
 
+    /** @return Range of the sweep attack in blocks. */
     float getRange();
 
+    /** @param range Sweep range in blocks. */
     void setRange(float range);
 
+    /** @return Damage dealt to entities hit by the sweep. */
     float getDamage();
 
+    /** @param damage Sweep damage amount. */
     void setDamage(float damage);
 
+    /** @return Knockback strength applied to entities hit. */
     float getKnockback();
 
+    /** @param knockback Knockback strength. */
     void setKnockback(float knockback);
 
-    /**
-     * Get the sweep mode (0 = SWIPE, 1 = SPIN).
-     */
+    /** @return Sweep mode ordinal (0=SWIPE, 1=SPIN). */
     int getSweepMode();
 
+    /** @param mode Sweep mode ordinal (0=SWIPE, 1=SPIN). */
     void setSweepMode(int mode);
 
+    /** @return Speed of the sweep animation. */
     float getSweepSpeed();
 
+    /** @param speed Sweep animation speed. */
     void setSweepSpeed(float speed);
 
+    /** @return Duration of the spin in ticks (only used in SPIN mode). */
     int getSpinDurationTicks();
 
+    /** @param ticks Spin duration in ticks. */
     void setSpinDurationTicks(int ticks);
 
+    /** @return Whether the sweep hits through multiple targets. */
     boolean isPiercing();
 
+    /** @param piercing Whether the sweep pierces through targets. */
     void setPiercing(boolean piercing);
 
+    /** @return Inner radius of the sweep arc in blocks (creates a donut-shaped hitbox). */
     float getInnerRadius();
 
+    /** @param radius Inner radius in blocks. */
     void setInnerRadius(float radius);
 }

java/noppes/npcs/api/ability/type/IAbilityDash.java

@@ -8,26 +8,33 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityDash extends IAbility {
 
-    /**
-     * Get the dash mode (0 = AGGRESSIVE, 1 = DEFENSIVE, 2 = DIRECTIONAL).
-     */
+    /** @return Dash mode ordinal (0=AGGRESSIVE, 1=DEFENSIVE, 2=DIRECTIONAL). */
     int getDashMode();
 
+    /** @param mode Dash mode ordinal (0=AGGRESSIVE, 1=DEFENSIVE, 2=DIRECTIONAL). */
     void setDashMode(int mode);
 
+    /** @return Distance covered by the dash in blocks. */
     float getDashDistance();
 
+    /** @param distance Dash distance in blocks. */
     void setDashDistance(float distance);
 
+    /** @return Speed of the dash movement. */
     float getDashSpeed();
 
+    /** @param speed Dash movement speed. */
     void setDashSpeed(float speed);
 
+    /** @return Angle offset of the dash direction in degrees. */
     float getDashAngle();
 
+    /** @param dashAngle Direction angle offset in degrees. */
     void setDashAngle(float dashAngle);
 
+    /** @return Dash direction ordinal (determines lateral movement direction). */
     int getDashDirection();
 
+    /** @param mode Dash direction ordinal. */
     void setDashDirection(int mode);
 }

java/noppes/npcs/api/ability/type/IAbilityDefend.java

@@ -7,13 +7,18 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityDefend extends IAbility {
 
+    /** @return Maximum duration of the defensive stance in ticks. */
     int getDurationTicks();
 
+    /** @param ticks Maximum duration in ticks. */
     void setDurationTicks(int ticks);
 
+    /** @return Maximum number of hits that can be absorbed before the defense breaks. */
     int getMaxHitAmount();
 
+    /** @param amount Maximum hit count before breaking. */
     void setMaxHitAmount(int amount);
 
+    /** @return Whether the entity is currently in a defensive stance. */
     boolean isDefending();
 }

java/noppes/npcs/api/ability/type/IAbilityDisc.java

@@ -6,64 +6,113 @@ package noppes.npcs.api.ability.type;
  */
 public interface IAbilityDisc extends IAbilityEnergyProjectile {
 
+    /** @return Travel speed of the disc in blocks per tick. */
     float getSpeed();
 
+    /** @param speed Travel speed in blocks per tick. */
     void setSpeed(float speed);
 
+    /** @return Visual radius of the disc in blocks. */
     float getDiscRadius();
 
+    /** @param radius Disc radius in blocks. */
     void setDiscRadius(float radius);
 
+    /** @return Thickness of the disc in blocks. */
     float getDiscThickness();
 
+    /** @param thickness Disc thickness in blocks. */
     void setDiscThickness(float thickness);
 
+    /** @return Whether the disc spins on a vertical axis (blade-like). */
     boolean isVertical();
 
+    /** @param vertical Whether the disc spins vertically. */
     void setVertical(boolean vertical);
 
+    /** @return Whether the disc returns to the caster after reaching max distance. */
     boolean isBoomerang();
 
+    /** @param boomerang Whether the disc returns to the caster. */
     void setBoomerang(boolean boomerang);
 
+    /** @return Delay in ticks before the disc begins returning. */
     int getBoomerangDelay();
 
+    /** @param ticks Boomerang return delay in ticks. */
     void setBoomerangDelay(int ticks);
 
+    /** @return Whether the disc tracks its target. */
     boolean isHoming();
 
+    /** @param homing Whether to track the target. */
     void setHoming(boolean homing);
 
+    /** @return Homing turn strength (higher = tighter turns). */
     float getHomingStrength();
 
+    /** @param strength Homing turn strength. */
     void setHomingStrength(float strength);
 
+    /** @return Maximum distance at which homing activates, in blocks. */
     float getHomingRange();
 
+    /** @param range Maximum homing activation range in blocks. */
     void setHomingRange(float range);
 
+    /** @return Visual rotation speed of the disc in degrees per tick. */
     float getRotationSpeed();
 
+    /** @param speed Rotation speed in degrees per tick. */
     void setRotationSpeed(float speed);
 
+    /** @return Number of disc projectiles fired per use. */
     int getProjectileCount();
 
+    /** @param count Number of projectiles per use. */
     void setProjectileCount(int count);
 
+    /** @return Delay in ticks between each projectile in a multi-projectile volley. */
     int getFireDelay();
 
+    /** @param delay Delay in ticks between projectiles. */
     void setFireDelay(int delay);
 
-    // Indexed accessors
+    // Indexed accessors (per-projectile overrides)
+
+    /**
+     * @param projectileIndex Projectile index.
+     * @return Inner color as a packed RGB integer.
+     */
     int getInnerColor(int projectileIndex);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @param color Inner color as a packed RGB integer.
+     */
     void setInnerColor(int projectileIndex, int color);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @return Outer color as a packed RGB integer.
+     */
     int getOuterColor(int projectileIndex);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @param color Outer color as a packed RGB integer.
+     */
     void setOuterColor(int projectileIndex, int color);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @return Anchor point ordinal.
+     */
     int getAnchorPoint(int projectileIndex);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @param point Anchor point ordinal.
+     */
     void setAnchorPoint(int projectileIndex, int point);
 }

java/noppes/npcs/api/ability/type/IAbilityDodge.java

@@ -6,15 +6,21 @@ package noppes.npcs.api.ability.type;
  */
 public interface IAbilityDodge extends IAbilityDefend {
 
+    /** @return Animation ID for dodge variant 1, or -1 for none. */
     int getDodgeAnimation1Id();
 
+    /** @param animationId Animation ID, or -1 for none. */
     void setDodgeAnimation1Id(int animationId);
 
+    /** @return Animation ID for dodge variant 2, or -1 for none. */
     int getDodgeAnimation2Id();
 
+    /** @param animationId Animation ID, or -1 for none. */
     void setDodgeAnimation2Id(int animationId);
 
+    /** @return Animation ID for dodge variant 3, or -1 for none. */
     int getDodgeAnimation3Id();
 
+    /** @param animationId Animation ID, or -1 for none. */
     void setDodgeAnimation3Id(int animationId);
 }

java/noppes/npcs/api/ability/type/IAbilityEffect.java

@@ -9,22 +9,34 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityEffect extends IAbility {
 
+    /** @return Duration of the effect in ticks. */
     int getDurationTicks();
+    /** @param ticks Effect duration in ticks. */
     void setDurationTicks(int ticks);
 
+    /** @return Flat heal amount per tick (body HP). */
     float getHealAmount();
+    /** @param amount Flat heal amount per tick. */
     void setHealAmount(float amount);
 
+    /** @return Heal amount as a percentage of max health per tick (0.0-100.0). */
     float getHealPercent();
+    /** @param percent Heal percentage per tick (0.0-100.0). */
     void setHealPercent(float percent);
 
+    /** @return Whether the caster is also affected by the effect. */
     boolean isIncludeSelf();
+    /** @param includeSelf Whether to include the caster. */
     void setIncludeSelf(boolean includeSelf);
 
+    /** @return Area-of-effect radius in blocks. */
     float getRadius();
+    /** @param radius AoE radius in blocks. */
     void setRadius(float radius);
 
+    /** @return Whether healing is applied all at once instead of over time. */
     boolean isInstantHeal();
+    /** @param instant Whether healing is instant. */
     void setInstantHeal(boolean instant);
 
     /**

java/noppes/npcs/api/ability/type/IAbilityEnergyBeam.java

@@ -6,52 +6,95 @@ package noppes.npcs.api.ability.type;
  */
 public interface IAbilityEnergyBeam extends IAbilityEnergyProjectile {
 
+    /** @return Travel speed of the beam head in blocks per tick. */
     float getSpeed();
 
+    /** @param speed Travel speed in blocks per tick. */
     void setSpeed(float speed);
 
+    /** @return Width of the beam trail in blocks. */
     float getBeamWidth();
 
+    /** @param width Beam trail width in blocks. */
     void setBeamWidth(float width);
 
+    /** @return Size of the beam head sphere in blocks. */
     float getHeadSize();
 
+    /** @param size Beam head size in blocks. */
     void setHeadSize(float size);
 
+    /** @return Whether the beam head tracks its target. */
     boolean isHoming();
 
+    /** @param homing Whether to track the target. */
     void setHoming(boolean homing);
 
+    /** @return Homing turn strength (higher = tighter turns). */
     float getHomingStrength();
 
+    /** @param strength Homing turn strength. */
     void setHomingStrength(float strength);
 
+    /** @return Maximum distance at which homing activates, in blocks. */
     float getHomingRange();
 
+    /** @param range Maximum homing activation range in blocks. */
     void setHomingRange(float range);
 
+    /** @return Visual rotation speed of the beam head in degrees per tick. */
     float getRotationSpeed();
 
+    /** @param speed Rotation speed in degrees per tick. */
     void setRotationSpeed(float speed);
 
+    /** @return Number of beam projectiles fired per use. */
     int getProjectileCount();
 
+    /** @param count Number of projectiles per use. */
     void setProjectileCount(int count);
 
+    /** @return Delay in ticks between each projectile in a multi-projectile volley. */
     int getFireDelay();
 
+    /** @param delay Delay in ticks between projectiles. */
     void setFireDelay(int delay);
 
-    // Indexed accessors
+    // Indexed accessors (per-projectile overrides)
+
+    /**
+     * @param projectileIndex Projectile index.
+     * @return Inner color as a packed RGB integer.
+     */
     int getInnerColor(int projectileIndex);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @param color Inner color as a packed RGB integer.
+     */
     void setInnerColor(int projectileIndex, int color);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @return Outer color as a packed RGB integer.
+     */
     int getOuterColor(int projectileIndex);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @param color Outer color as a packed RGB integer.
+     */
     void setOuterColor(int projectileIndex, int color);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @return Anchor point ordinal.
+     */
     int getAnchorPoint(int projectileIndex);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @param point Anchor point ordinal.
+     */
     void setAnchorPoint(int projectileIndex, int point);
 }

java/noppes/npcs/api/ability/type/IAbilityEnergyProjectile.java

@@ -8,88 +8,133 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityEnergyProjectile extends IAbility {
 
-    // Combat
+    // ==================== COMBAT ====================
+
+    /** @return Base damage dealt on hit. */
     float getDamage();
 
+    /** @param damage Base damage on hit. */
     void setDamage(float damage);
 
+    /** @return Horizontal knockback strength applied on hit. */
     float getKnockback();
 
+    /** @param knockback Horizontal knockback strength. */
     void setKnockback(float knockback);
 
+    /** @return Vertical knockback strength applied on hit. */
     float getKnockbackUp();
 
+    /** @param knockback Vertical knockback strength. */
     void setKnockbackUp(float knockback);
 
+    /** @return Whether the projectile explodes on impact. */
     boolean isExplosive();
 
+    /** @param explosive Whether to explode on impact. */
     void setExplosive(boolean explosive);
 
+    /** @return Explosion radius in blocks. */
     float getExplosionRadius();
 
+    /** @param radius Explosion radius in blocks. */
     void setExplosionRadius(float radius);
 
+    /** @return Damage falloff multiplier over explosion distance (0.0-1.0). */
     float getExplosionDamageFalloff();
 
+    /** @param falloff Damage falloff multiplier (0.0-1.0). */
     void setExplosionDamageFalloff(float falloff);
 
+    /** @return Hit type ordinal (determines how repeated hits are handled). */
     int getHitType();
 
+    /** @param hitType Hit type ordinal. */
     void setHitType(int hitType);
 
+    /** @return Delay in ticks between repeated hits on the same target. */
     int getMultiHitDelayTicks();
 
+    /** @param delayTicks Delay in ticks between repeated hits. */
     void setMultiHitDelayTicks(int delayTicks);
 
+    /** @return Maximum number of times this projectile can hit the same target. */
     int getMaxHits();
 
+    /** @param maxHits Maximum hit count per target. */
     void setMaxHits(int maxHits);
 
-    // Lifespan
+    // ==================== LIFESPAN ====================
+
+    /** @return Maximum travel distance in blocks before the projectile expires. */
     float getMaxDistance();
 
+    /** @param distance Maximum travel distance in blocks. */
     void setMaxDistance(float distance);
 
+    /** @return Maximum lifetime in ticks before the projectile expires. */
     int getMaxLifetime();
 
+    /** @param ticks Maximum lifetime in ticks. */
     void setMaxLifetime(int ticks);
 
-    // Colors
+    // ==================== COLORS ====================
+
+    /** @return Inner (core) color as a packed RGB integer. */
     int getInnerColor();
 
+    /** @param color Inner color as a packed RGB integer. */
     void setInnerColor(int color);
 
+    /** @return Outer (glow) color as a packed RGB integer. */
     int getOuterColor();
 
+    /** @param color Outer color as a packed RGB integer. */
     void setOuterColor(int color);
 
+    /** @return Whether the outer color layer is rendered. */
     boolean isOuterColorEnabled();
 
+    /** @param enabled Whether to render the outer color layer. */
     void setOuterColorEnabled(boolean enabled);
 
+    /** @return Width of the outer color layer relative to the projectile size. */
     float getOuterColorWidth();
 
+    /** @param width Outer color layer width. */
     void setOuterColorWidth(float width);
 
+    /** @return Alpha (opacity) of the outer color layer (0.0-1.0). */
     float getOuterColorAlpha();
 
+    /** @param alpha Outer color opacity (0.0-1.0). */
     void setOuterColorAlpha(float alpha);
 
-    // Lightning
+    // ==================== LIGHTNING ====================
+
+    /** @return Whether the lightning visual effect is enabled. */
     boolean hasLightningEffect();
 
+    /** @param enabled Whether to enable the lightning effect. */
     void setLightningEffect(boolean enabled);
 
+    /** @return Density of lightning arcs (higher = more arcs). */
     float getLightningDensity();
 
+    /** @param density Lightning arc density. */
     void setLightningDensity(float density);
 
+    /** @return Radius of the lightning effect around the projectile, in blocks. */
     float getLightningRadius();
 
+    /** @param radius Lightning effect radius in blocks. */
     void setLightningRadius(float radius);
 
-    // Anchor
+    // ==================== ANCHOR ====================
+
+    /** @return Anchor point ordinal (0=FEET, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=HEAD, 5=FRONT, 6=ABOVE_HEAD). */
     int getAnchorPoint();
 
+    /** @param point Anchor point ordinal (0=FEET, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=HEAD, 5=FRONT, 6=ABOVE_HEAD). */
     void setAnchorPoint(int point);
 }

java/noppes/npcs/api/ability/type/IAbilityGuard.java

@@ -6,7 +6,9 @@ package noppes.npcs.api.ability.type;
  */
 public interface IAbilityGuard extends IAbilityDefend {
 
+    /** @return Damage reduction multiplier while guarding (0.0 = full block, 1.0 = no reduction). */
     float getDamageReduction();
 
+    /** @param reduction Damage reduction multiplier (0.0 = full block, 1.0 = no reduction). */
     void setDamageReduction(float reduction);
 }

java/noppes/npcs/api/ability/type/IAbilityHazard.java

@@ -6,23 +6,33 @@ package noppes.npcs.api.ability.type;
  */
 public interface IAbilityHazard extends IAbilityZone {
 
+    /** @return Damage radius of the hazard zone in blocks. */
     float getRadius();
 
+    /** @param radius Damage radius in blocks. */
     void setRadius(float radius);
 
+    /** @return Damage dealt per damage interval tick. */
     float getDamagePerSecond();
 
+    /** @param damage Damage per interval. */
     void setDamagePerSecond(float damage);
 
+    /** @return Interval in ticks between damage applications. */
     int getDamageInterval();
 
+    /** @param interval Damage interval in ticks. */
     void setDamageInterval(int interval);
 
+    /** @return Whether damage ignores entity invulnerability frames. */
     boolean isIgnoreInvulnFrames();
 
+    /** @param ignore Whether to ignore invulnerability frames. */
     void setIgnoreInvulnFrames(boolean ignore);
 
+    /** @return Whether the hazard also damages the caster. */
     boolean isAffectsCaster();
 
+    /** @param affects Whether the hazard affects the caster. */
     void setAffectsCaster(boolean affects);
 }

java/noppes/npcs/api/ability/type/IAbilityHeavyHit.java

@@ -8,19 +8,27 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityHeavyHit extends IAbility {
 
+    /** @return Damage dealt to entities in the hit area. */
     float getDamage();
 
+    /** @param damage Damage amount. */
     void setDamage(float damage);
 
+    /** @return Knockback strength applied to entities hit. */
     float getKnockback();
 
+    /** @param knockback Knockback strength. */
     void setKnockback(float knockback);
 
+    /** @return Length of the rectangular hit area in blocks (forward from caster). */
     float getHitLength();
 
+    /** @param hitLength Hit area length in blocks. */
     void setHitLength(float hitLength);
 
+    /** @return Width of the rectangular hit area in blocks. */
     float getHitWidth();
 
+    /** @param hitWidth Hit area width in blocks. */
     void setHitWidth(float hitWidth);
 }

java/noppes/npcs/api/ability/type/IAbilityLaser.java

@@ -6,15 +6,21 @@ package noppes.npcs.api.ability.type;
  */
 public interface IAbilityLaser extends IAbilityEnergyProjectile {
 
+    /** @return Width of the laser beam in blocks. */
     float getLaserWidth();
 
+    /** @param width Laser beam width in blocks. */
     void setLaserWidth(float width);
 
+    /** @return Speed at which the laser extends to its max length, in blocks per tick. */
     float getExpansionSpeed();
 
+    /** @param speed Expansion speed in blocks per tick. */
     void setExpansionSpeed(float speed);
 
+    /** @return Maximum length the laser can reach in blocks. */
     float getMaxLength();
 
+    /** @param maxLength Maximum laser length in blocks. */
     void setMaxLength(float maxLength);
 }

java/noppes/npcs/api/ability/type/IAbilityOrb.java

@@ -6,48 +6,89 @@ package noppes.npcs.api.ability.type;
  */
 public interface IAbilityOrb extends IAbilityEnergyProjectile {
 
+    /** @return Travel speed of the orb in blocks per tick. */
     float getOrbSpeed();
 
+    /** @param speed Travel speed in blocks per tick. */
     void setOrbSpeed(float speed);
 
+    /** @return Visual size (radius) of the orb in blocks. */
     float getOrbSize();
 
+    /** @param size Orb size in blocks. */
     void setOrbSize(float size);
 
+    /** @return Whether the orb tracks its target. */
     boolean isHoming();
 
+    /** @param homing Whether to track the target. */
     void setHoming(boolean homing);
 
+    /** @return Homing turn strength (higher = tighter turns). */
     float getHomingStrength();
 
+    /** @param strength Homing turn strength. */
     void setHomingStrength(float strength);
 
+    /** @return Maximum distance at which homing activates, in blocks. */
     float getHomingRange();
 
+    /** @param range Maximum homing activation range in blocks. */
     void setHomingRange(float range);
 
+    /** @return Visual rotation speed of the orb in degrees per tick. */
     float getRotationSpeed();
 
+    /** @param speed Rotation speed in degrees per tick. */
     void setRotationSpeed(float speed);
 
+    /** @return Number of orb projectiles fired per use. */
     int getProjectileCount();
 
+    /** @param count Number of projectiles per use. */
     void setProjectileCount(int count);
 
+    /** @return Delay in ticks between each projectile in a multi-projectile volley. */
     int getFireDelay();
 
+    /** @param delay Delay in ticks between projectiles. */
     void setFireDelay(int delay);
 
-    // Indexed accessors
+    // Indexed accessors (per-projectile overrides)
+
+    /**
+     * @param projectileIndex Projectile index.
+     * @return Inner color as a packed RGB integer.
+     */
     int getInnerColor(int projectileIndex);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @param color Inner color as a packed RGB integer.
+     */
     void setInnerColor(int projectileIndex, int color);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @return Outer color as a packed RGB integer.
+     */
     int getOuterColor(int projectileIndex);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @param color Outer color as a packed RGB integer.
+     */
     void setOuterColor(int projectileIndex, int color);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @return Anchor point ordinal.
+     */
     int getAnchorPoint(int projectileIndex);
 
+    /**
+     * @param projectileIndex Projectile index.
+     * @param point Anchor point ordinal.
+     */
     void setAnchorPoint(int projectileIndex, int point);
 }

java/noppes/npcs/api/ability/type/IAbilityProjectile.java

@@ -8,35 +8,51 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityProjectile extends IAbility {
 
+    /** @return Base damage dealt on hit. */
     float getDamage();
 
+    /** @param damage Base damage on hit. */
     void setDamage(float damage);
 
+    /** @return Travel speed of the projectile in blocks per tick. */
     float getSpeed();
 
+    /** @param speed Travel speed in blocks per tick. */
     void setSpeed(float speed);
 
+    /** @return Knockback strength applied on hit. */
     float getKnockback();
 
+    /** @param knockback Knockback strength. */
     void setKnockback(float knockback);
 
+    /** @return The projectile type identifier (e.g. arrow, snowball). */
     String getProjectileType();
 
+    /** @param type Projectile type identifier. */
     void setProjectileType(String type);
 
+    /** @return Whether the projectile explodes on impact. */
     boolean isExplosive();
 
+    /** @param explosive Whether to explode on impact. */
     void setExplosive(boolean explosive);
 
+    /** @return Explosion radius in blocks. */
     float getExplosionRadius();
 
+    /** @param radius Explosion radius in blocks. */
     void setExplosionRadius(float radius);
 
+    /** @return Whether the projectile tracks its target. */
     boolean isHoming();
 
+    /** @param homing Whether to track the target. */
     void setHoming(boolean homing);
 
+    /** @return Homing turn strength (higher = tighter turns). */
     float getHomingStrength();
 
+    /** @param strength Homing turn strength. */
     void setHomingStrength(float strength);
 }

java/noppes/npcs/api/ability/type/IAbilityShockwave.java

@@ -8,19 +8,27 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityShockwave extends IAbility {
 
+    /** @return Radius of the push effect in blocks. */
     float getPushRadius();
 
+    /** @param radius Push radius in blocks. */
     void setPushRadius(float radius);
 
+    /** @return Strength of the outward push force. */
     float getPushStrength();
 
+    /** @param strength Push force strength. */
     void setPushStrength(float strength);
 
+    /** @return Damage dealt to entities caught in the shockwave. */
     float getDamage();
 
+    /** @param damage Shockwave damage. */
     void setDamage(float damage);
 
+    /** @return Whether the shockwave hits all entities in radius (true) or only the target (false). */
     boolean isAoe();
 
+    /** @param aoe Whether the shockwave is area-of-effect. */
     void setAoe(boolean aoe);
 }

java/noppes/npcs/api/ability/type/IAbilitySlam.java

@@ -8,23 +8,33 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilitySlam extends IAbility {
 
+    /** @return Damage dealt on ground impact. */
     float getDamage();
 
+    /** @param damage Impact damage amount. */
     void setDamage(float damage);
 
+    /** @return Radius of the impact area in blocks. */
     float getRadius();
 
+    /** @param radius Impact radius in blocks. */
     void setRadius(float radius);
 
+    /** @return Knockback strength applied to entities in the impact area. */
     float getKnockbackStrength();
 
+    /** @param knockback Knockback strength. */
     void setKnockbackStrength(float knockback);
 
+    /** @return Horizontal speed of the leap toward the target. */
     float getLeapSpeed();
 
+    /** @param speed Leap speed. */
     void setLeapSpeed(float speed);
 
+    /** @return Vertical height of the leap in blocks. */
     float getLeapHeight();
 
+    /** @param height Leap height in blocks. */
     void setLeapHeight(float height);
 }

java/noppes/npcs/api/ability/type/IAbilitySweeper.java

@@ -8,55 +8,81 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilitySweeper extends IAbility {
 
+    /** @return Length of the sweeping beam in blocks. */
     float getBeamLength();
 
+    /** @param length Beam length in blocks. */
     void setBeamLength(float length);
 
+    /** @return Width of the sweeping beam in blocks. */
     float getBeamWidth();
 
+    /** @param width Beam width in blocks. */
     void setBeamWidth(float width);
 
+    /** @return Height of the sweeping beam in blocks. */
     float getBeamHeight();
 
+    /** @param height Beam height in blocks. */
     void setBeamHeight(float height);
 
+    /** @return Damage dealt per hit to entities caught in the beam. */
     float getDamage();
 
+    /** @param damage Damage per hit. */
     void setDamage(float damage);
 
+    /** @return Interval in ticks between damage applications to the same target. */
     int getDamageInterval();
 
+    /** @param interval Damage interval in ticks. */
     void setDamageInterval(int interval);
 
+    /** @return Whether the beam can hit through multiple targets. */
     boolean isPiercing();
 
+    /** @param piercing Whether the beam pierces through targets. */
     void setPiercing(boolean piercing);
 
+    /** @return Rotation speed of the sweep in degrees per tick. */
     float getSweepSpeed();
 
+    /** @param speed Sweep rotation speed in degrees per tick. */
     void setSweepSpeed(float speed);
 
+    /** @return Number of full rotations the beam completes before stopping. */
     int getNumberOfRotations();
 
+    /** @param rotations Number of full rotations. */
     void setNumberOfRotations(int rotations);
 
+    /** @return Whether the beam pivot tracks the target instead of rotating freely. */
     boolean isLockOnTarget();
 
+    /** @param lock Whether the beam locks on to the target. */
     void setLockOnTarget(boolean lock);
 
+    /** @return Inner (core) color of the beam as a packed RGB integer. */
     int getInnerColor();
 
+    /** @param color Inner color as a packed RGB integer. */
     void setInnerColor(int color);
 
+    /** @return Outer (glow) color of the beam as a packed RGB integer. */
     int getOuterColor();
 
+    /** @param color Outer color as a packed RGB integer. */
     void setOuterColor(int color);
 
+    /** @return Width of the outer color layer relative to the beam width. */
     float getOuterColorWidth();
 
+    /** @param width Outer color layer width. */
     void setOuterColorWidth(float width);
 
+    /** @return Whether the outer color layer is rendered. */
     boolean isOuterColorEnabled();
 
+    /** @param enabled Whether to render the outer color layer. */
     void setOuterColorEnabled(boolean enabled);
 }

java/noppes/npcs/api/ability/type/IAbilityTeleport.java

@@ -8,46 +8,63 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityTeleport extends IAbility {
 
-    /**
-     * Get the teleport mode (0 = BLINK, 1 = BEHIND, 2 = SINGLE).
-     */
+    /** @return Teleport mode ordinal (0=BLINK, 1=BEHIND, 2=SINGLE). */
     int getMode();
 
+    /** @param mode Teleport mode ordinal (0=BLINK, 1=BEHIND, 2=SINGLE). */
     void setMode(int mode);
 
+    /** @return Number of rapid blink teleports in BLINK mode. */
     int getBlinkCount();
 
+    /** @param count Number of blink teleports. */
     void setBlinkCount(int count);
 
+    /** @return Delay in ticks between blink teleports. */
     int getBlinkDelayTicks();
 
+    /** @param ticks Delay in ticks between blinks. */
     void setBlinkDelayTicks(int ticks);
 
+    /** @return Maximum random offset radius for blink teleports in blocks. */
     float getBlinkRadius();
 
+    /** @param radius Blink offset radius in blocks. */
     void setBlinkRadius(float radius);
 
+    /** @return Distance behind the target to teleport to in BEHIND mode. */
     float getBehindDistance();
 
+    /** @param distance Behind-target distance in blocks. */
     void setBehindDistance(float distance);
 
+    /** @return Whether the teleport requires clear line of sight to the destination. */
     boolean isRequireLineOfSight();
 
+    /** @param require Whether line of sight is required. */
     void setRequireLineOfSight(boolean require);
 
+    /** @return Whether damage is dealt at the departure location. */
     boolean isDamageAtStart();
 
+    /** @param damage Whether to deal damage at departure. */
     void setDamageAtStart(boolean damage);
 
+    /** @return Whether damage is dealt at the arrival location. */
     boolean isDamageAtEnd();
 
+    /** @param damage Whether to deal damage at arrival. */
     void setDamageAtEnd(boolean damage);
 
+    /** @return Damage dealt at teleport locations. */
     float getDamage();
 
+    /** @param damage Teleport damage amount. */
     void setDamage(float damage);
 
+    /** @return Radius of the damage area at teleport locations in blocks. */
     float getDamageRadius();
 
+    /** @param radius Damage area radius in blocks. */
     void setDamageRadius(float radius);
 }

java/noppes/npcs/api/ability/type/IAbilityTrap.java

@@ -6,35 +6,51 @@ package noppes.npcs.api.ability.type;
  */
 public interface IAbilityTrap extends IAbilityZone {
 
+    /** @return Radius in blocks at which entities trigger the trap. */
     float getTriggerRadius();
 
+    /** @param radius Trigger detection radius in blocks. */
     void setTriggerRadius(float radius);
 
+    /** @return Time in ticks before the trap becomes active after placement. */
     int getArmTime();
 
+    /** @param ticks Arming time in ticks. */
     void setArmTime(int ticks);
 
+    /** @return Maximum number of times the trap can trigger before expiring. */
     int getMaxTriggers();
 
+    /** @param max Maximum trigger count. */
     void setMaxTriggers(int max);
 
+    /** @return Cooldown in ticks between consecutive triggers. */
     int getTriggerCooldown();
 
+    /** @param cooldown Trigger cooldown in ticks. */
     void setTriggerCooldown(int cooldown);
 
+    /** @return Damage dealt when the trap triggers. */
     float getDamage();
 
+    /** @param damage Trigger damage amount. */
     void setDamage(float damage);
 
+    /** @return Radius of the damage area when triggered, in blocks. */
     float getDamageRadius();
 
+    /** @param radius Damage area radius in blocks. */
     void setDamageRadius(float radius);
 
+    /** @return Knockback strength applied to entities caught in the trigger. */
     float getKnockback();
 
+    /** @param knockback Knockback strength. */
     void setKnockback(float knockback);
 
+    /** @return Whether the trap is visible to entities. */
     boolean isVisible();
 
+    /** @param visible Whether the trap is visible. */
     void setVisible(boolean visible);
 }

java/noppes/npcs/api/ability/type/IAbilityVortex.java

@@ -8,31 +8,45 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityVortex extends IAbility {
 
+    /** @return Radius of the pull effect in blocks. */
     float getPullRadius();
 
+    /** @param radius Pull effect radius in blocks. */
     void setPullRadius(float radius);
 
+    /** @return Strength of the inward pull force. */
     float getPullStrength();
 
+    /** @param strength Pull force strength. */
     void setPullStrength(float strength);
 
+    /** @return Damage dealt on initial vortex hit. */
     float getDamage();
 
+    /** @param damage Initial hit damage. */
     void setDamage(float damage);
 
+    /** @return Knockback strength applied on initial hit. */
     float getKnockback();
 
+    /** @param knockback Knockback strength. */
     void setKnockback(float knockback);
 
+    /** @return Whether the vortex hits all entities in radius (true) or only the target (false). */
     boolean isAoe();
 
+    /** @param aoe Whether the vortex is area-of-effect. */
     void setAoe(boolean aoe);
 
+    /** @return Whether continuous damage is dealt while pulling entities. */
     boolean isDamageOnPull();
 
+    /** @param damage Whether to deal damage during pull. */
     void setDamageOnPull(boolean damage);
 
+    /** @return Damage dealt per tick while pulling entities. */
     float getPullDamage();
 
+    /** @param damage Per-tick pull damage. */
     void setPullDamage(float damage);
 }

java/noppes/npcs/api/ability/type/IAbilityZone.java

@@ -8,119 +8,163 @@ import noppes.npcs.api.ability.IAbility;
  */
 public interface IAbilityZone extends IAbility {
 
+    /** @return Duration of the zone in ticks. */
     int getDurationTicks();
 
+    /** @param ticks Zone duration in ticks. */
     void setDurationTicks(int ticks);
 
-    /**
-     * Get the zone shape (0 = CIRCLE, 1 = SQUARE).
-     */
+    /** @return Zone shape ordinal (0=CIRCLE, 1=SQUARE). */
     int getZoneShapeOrdinal();
 
+    /** @param shape Zone shape ordinal (0=CIRCLE, 1=SQUARE). */
     void setZoneShapeOrdinal(int shape);
 
+    /** @return Spawn offset radius from the caster in blocks. */
     float getSpawnRadius();
 
+    /** @param radius Spawn offset radius in blocks. */
     void setSpawnRadius(float radius);
 
+    /** @return Number of zones spawned per use. */
     int getZoneCount();
 
+    /** @param count Number of zones to spawn. */
     void setZoneCount(int count);
 
+    /** @return Visual height of the zone in blocks. */
     float getZoneHeight();
 
+    /** @param height Zone height in blocks. */
     void setZoneHeight(float height);
 
+    /** @return Density of particles in the zone effect. */
     float getParticleDensity();
 
+    /** @param density Particle density. */
     void setParticleDensity(float density);
 
+    /** @return Scale of individual particles. */
     float getParticleScale();
 
+    /** @param scale Particle scale. */
     void setParticleScale(float scale);
 
+    /** @return Animation speed multiplier for zone visual effects. */
     float getAnimSpeed();
 
+    /** @param speed Animation speed multiplier. */
     void setAnimSpeed(float speed);
 
+    /** @return Density of lightning arcs in the zone. */
     float getLightningDensity();
 
+    /** @param density Lightning arc density. */
     void setLightningDensity(float density);
 
-    // Color controls
+    // ==================== COLORS ====================
+
+    /** @return Inner (core) color as a packed RGB integer. */
     int getInnerColor();
 
+    /** @param color Inner color as a packed RGB integer. */
     void setInnerColor(int color);
 
+    /** @return Outer (glow) color as a packed RGB integer. */
     int getOuterColor();
 
+    /** @param color Outer color as a packed RGB integer. */
     void setOuterColor(int color);
 
+    /** @return Whether the outer color layer is rendered. */
     boolean isOuterColorEnabled();
 
+    /** @param enabled Whether to render the outer color layer. */
     void setOuterColorEnabled(boolean enabled);
 
-    // Visual layer controls
+    // ==================== VISUAL LAYERS ====================
 
+    /** @return Whether the ground fill layer is rendered. */
     boolean isGroundFill();
 
+    /** @param enabled Whether to render the ground fill. */
     void setGroundFill(boolean enabled);
 
+    /** @return Alpha (opacity) of the ground fill layer (0.0-1.0). */
     float getGroundAlpha();
 
+    /** @param alpha Ground fill opacity (0.0-1.0). */
     void setGroundAlpha(float alpha);
 
+    /** @return Whether ring decorations are rendered. */
     boolean isRings();
 
+    /** @param enabled Whether to render rings. */
     void setRings(boolean enabled);
 
+    /** @return Number of concentric rings in the zone. */
     int getRingCount();
 
+    /** @param count Number of rings. */
     void setRingCount(int count);
 
+    /** @return Whether the border outline is rendered. */
     boolean isBorder();
 
+    /** @param enabled Whether to render the border. */
     void setBorder(boolean enabled);
 
+    /** @return Rotation speed of the border in degrees per tick. */
     float getBorderSpeed();
 
+    /** @param speed Border rotation speed. */
     void setBorderSpeed(float speed);
 
+    /** @return Whether accent decorations are rendered. */
     boolean isAccents();
 
+    /** @param enabled Whether to render accents. */
     void setAccents(boolean enabled);
 
-    /**
-     * Get the accent style (0=STATIC, 1=SWAYING, 2=FLICKERING).
-     */
+    /** @return Accent style ordinal (0=STATIC, 1=SWAYING, 2=FLICKERING). */
     int getAccentStyle();
 
+    /** @param style Accent style ordinal (0=STATIC, 1=SWAYING, 2=FLICKERING). */
     void setAccentStyle(int style);
 
+    /** @return Whether lightning arcs are rendered in the zone. */
     boolean isLightning();
 
+    /** @param enabled Whether to render lightning. */
     void setLightning(boolean enabled);
 
+    /** @return Whether particles are rendered in the zone. */
     boolean isParticles();
 
+    /** @param enabled Whether to render particles. */
     void setParticles(boolean enabled);
 
-    /**
-     * Get the particle motion style (0=RISING, 1=DRIFTING, 2=SPARKS).
-     */
+    /** @return Particle motion style ordinal (0=RISING, 1=DRIFTING, 2=SPARKS). */
     int getParticleMotion();
 
+    /** @param motion Particle motion style ordinal (0=RISING, 1=DRIFTING, 2=SPARKS). */
     void setParticleMotion(int motion);
 
+    /** @return Resource directory path for custom particle textures. */
     String getParticleDir();
 
+    /** @param directory Resource directory path for particle textures. */
     void setParticleDir(String directory);
 
+    /** @return Size of individual particles in pixels. */
     int getParticleSize();
 
+    /** @param size Particle size in pixels. */
     void setParticleSize(int size);
 
+    /** @return Whether particles use the glow (fullbright) render mode. */
     boolean isParticleGlow();
 
+    /** @param glow Whether particles glow. */
     void setParticleGlow(boolean glow);
 }

java/noppes/npcs/api/entity/IEnergyAbility.java

@@ -10,57 +10,81 @@ public interface IEnergyAbility<T extends Entity> extends IEntity<T> {
 
     // ==================== OWNER ====================
 
+    /** @return Entity ID of the caster who spawned this energy ability. */
     int getOwnerEntityId();
 
+    /** @return The caster entity who spawned this energy ability, or null if not found. */
     IEntity getOwner();
 
     // ==================== DISPLAY ====================
 
+    /** @return Inner (core) color as a packed RGB integer. */
     int getInnerColor();
 
+    /** @param color Inner color as a packed RGB integer. */
     void setInnerColor(int color);
 
+    /** @return Alpha (opacity) of the inner color layer (0.0-1.0). */
     float getInnerAlpha();
 
+    /** @param alpha Inner color opacity (0.0-1.0). */
     void setInnerAlpha(float alpha);
 
+    /** @return Outer (glow) color as a packed RGB integer. */
     int getOuterColor();
 
+    /** @param color Outer color as a packed RGB integer. */
     void setOuterColor(int color);
 
+    /** @return Whether the outer color layer is rendered. */
     boolean isOuterColorEnabled();
 
+    /** @param enabled Whether to render the outer color layer. */
     void setOuterColorEnabled(boolean enabled);
 
+    /** @return Width of the outer color layer relative to the entity size. */
     float getOuterColorWidth();
 
+    /** @param width Outer color layer width. */
     void setOuterColorWidth(float width);
 
+    /** @return Alpha (opacity) of the outer color layer (0.0-1.0). */
     float getOuterColorAlpha();
 
+    /** @param alpha Outer color opacity (0.0-1.0). */
     void setOuterColorAlpha(float alpha);
 
     // ==================== LIGHTNING ====================
 
+    /** @return Whether the lightning visual effect is enabled. */
     boolean hasLightningEffect();
 
+    /** @param enabled Whether to render the lightning effect. */
     void setLightningEffect(boolean enabled);
 
+    /** @return Density of lightning arcs (higher = more arcs). */
     float getLightningDensity();
 
+    /** @param density Lightning arc density. */
     void setLightningDensity(float density);
 
+    /** @return Radius of the lightning effect around the entity, in blocks. */
     float getLightningRadius();
 
+    /** @param radius Lightning effect radius in blocks. */
     void setLightningRadius(float radius);
 
+    /** @return Fade-out time for lightning arcs in ticks. */
     int getLightningFadeTime();
 
+    /** @param ticks Lightning fade-out time in ticks. */
     void setLightningFadeTime(int ticks);
 
     // ==================== STATE ====================
 
+    /** @return Whether this energy ability is currently in its charging phase. */
     boolean isCharging();
 
+    /** @return Charge progress as a fraction (0.0-1.0). */
     float getChargeProgress();
 }