diff --git a/java/noppes/npcs/api/entity/IEnergyBeam.java b/java/noppes/npcs/api/entity/IEnergyBeam.java
index f951dcb..7d9d739 100644
--- a/java/noppes/npcs/api/entity/IEnergyBeam.java
+++ b/java/noppes/npcs/api/entity/IEnergyBeam.java
@@ -3,10 +3,17 @@ package noppes.npcs.api.entity;
import net.minecraft.entity.Entity;
/**
- * Represents an energy beam projectile - a directional beam with a trailing path.
+ * A directional beam projectile with a trailing path and optional head orb.
+ *
+ * Beams travel forward from their origin, dealing damage along their length.
+ * They can optionally stay attached to their owner and follow the owner's movement.
+ *
+ * Beams use {@code startFiring} internally rather than {@code startMoving} —
+ * this is handled automatically by the fire methods.
*/
public interface IEnergyBeam extends IEnergyProjectile {
+ /** Width of the beam trail. */
float getBeamWidth();
void setBeamWidth(float width);
diff --git a/java/noppes/npcs/api/entity/IEnergyDisc.java b/java/noppes/npcs/api/entity/IEnergyDisc.java
index cfb772f..17b27df 100644
--- a/java/noppes/npcs/api/entity/IEnergyDisc.java
+++ b/java/noppes/npcs/api/entity/IEnergyDisc.java
@@ -3,10 +3,14 @@ package noppes.npcs.api.entity;
import net.minecraft.entity.Entity;
/**
- * Represents an energy disc projectile - a flat spinning disc with optional boomerang behavior.
+ * A flat spinning disc projectile with optional boomerang behavior.
+ *
+ * Discs can be oriented vertically or horizontally, and can return to their owner
+ * like a boomerang after a configurable delay.
*/
public interface IEnergyDisc extends IEnergyProjectile {
+ /** Radius of the disc. */
float getDiscRadius();
void setDiscRadius(float radius);
diff --git a/java/noppes/npcs/api/entity/IEnergyLaser.java b/java/noppes/npcs/api/entity/IEnergyLaser.java
index 6433086..844b1c0 100644
--- a/java/noppes/npcs/api/entity/IEnergyLaser.java
+++ b/java/noppes/npcs/api/entity/IEnergyLaser.java
@@ -3,10 +3,18 @@ package noppes.npcs.api.entity;
import net.minecraft.entity.Entity;
/**
- * Represents an energy laser entity - a sweeping beam that follows the caster's look vector.
+ * A continuous laser beam that extends outward from its origin along a direction vector.
+ *
+ * Unlike other projectiles, lasers don't move through the world — they extend from their
+ * origin point along a direction, hitting everything in their path up to {@link #getMaxLength()}.
+ * The direction can be set explicitly via {@link #setDirection(double, double, double)}.
+ *
+ * The coordinate-based {@code fireAt(x, y, z)} calculates and sets the direction vector
+ * automatically, then uses the laser's internal launch sequence.
*/
public interface IEnergyLaser extends IEnergyProjectile {
+ /** Width of the laser beam. */
float getLaserWidth();
void setLaserWidth(float width);
diff --git a/java/noppes/npcs/api/entity/IEnergyOrb.java b/java/noppes/npcs/api/entity/IEnergyOrb.java
index 70af189..7205b72 100644
--- a/java/noppes/npcs/api/entity/IEnergyOrb.java
+++ b/java/noppes/npcs/api/entity/IEnergyOrb.java
@@ -3,8 +3,23 @@ package noppes.npcs.api.entity;
import net.minecraft.entity.Entity;
/**
- * Represents an energy orb projectile - a spherical homing energy ball.
- * Orbs use the base IEnergyProjectile properties with no additional methods.
+ * A spherical homing energy ball.
+ *
+ * Orbs travel in a straight line toward their target and can optionally home in on living entities.
+ * Use the base {@link IEnergyProjectile} methods for size, speed, damage, homing, and launch control.
+ *
+ * Example usage:
+ *
+ * // Fire from a specific position toward a target
+ * var orb = API.getEnergyController().createOrb(world, player, x, y, z, 1.0);
+ * orb.setDamage(10);
+ * orb.setHoming(true);
+ * orb.fireAt(target); // launches from (x,y,z) toward target
+ *
+ * // Fire from the caster's eye position using look-vector snap
+ * var orb2 = API.getEnergyController().createOrb(world, player, 0, 0, 0, 1.0);
+ * orb2.fireFrom(player, target); // repositions to player's eye, then fires toward target
+ *
*/
public interface IEnergyOrb extends IEnergyProjectile {
}
diff --git a/java/noppes/npcs/api/entity/IEnergyProjectile.java b/java/noppes/npcs/api/entity/IEnergyProjectile.java
index 6f1a3ca..4168f9d 100644
--- a/java/noppes/npcs/api/entity/IEnergyProjectile.java
+++ b/java/noppes/npcs/api/entity/IEnergyProjectile.java
@@ -3,29 +3,49 @@ package noppes.npcs.api.entity;
import net.minecraft.entity.Entity;
/**
- * Represents an energy projectile entity (Orb, Beam, Disc, Laser).
- * Extends IEnergyAbility for shared display/lightning/owner/charging methods.
+ * Base interface for all energy projectile entities (Orb, Beam, Disc, Laser, Slicer).
+ *
+ * Extends {@link IEnergyAbility} for shared display, lightning, owner, and charging methods.
+ *
+ * Fire methods — launch from current position (no repositioning):
+ *
+ * - {@link #fireAt(IEntity)} — toward an entity
+ * - {@link #fireAt(double, double, double)} — toward world coordinates
+ * - {@link #fireDirection(float, float)} — in a yaw/pitch direction
+ *
+ * FireFrom methods — reposition to caster's eye, then launch (look-vector snap):
+ *
+ * - {@link #fireFrom(IEntityLivingBase)} — fire along caster's look direction
+ * - {@link #fireFrom(IEntityLivingBase, IEntity)} — fire toward a target entity
+ *
*/
public interface IEnergyProjectile extends IEnergyAbility {
// ==================== OWNER & TARGET ====================
+ /** Sets the owner entity (used for homing return, damage attribution, etc.). */
void setOwner(IEntity owner);
+ /** @return the entity ID of the current homing/tracking target, or -1 if none */
int getTargetEntityId();
+ /** @return the current homing/tracking target entity, or null if none */
IEntity getTarget();
+ /** Sets the homing/tracking target entity. Pass null to clear. */
void setTarget(IEntity target);
// ==================== SIZE ====================
+ /** @return the projectile's visual and collision size */
float getSize();
+ /** Sets the projectile's visual and collision size. */
void setSize(float size);
// ==================== DISPLAY (PROJECTILE-SPECIFIC) ====================
+ /** @return the visual rotation speed (degrees per tick) */
float getRotationSpeed();
void setRotationSpeed(float speed);
@@ -42,72 +62,88 @@ public interface IEnergyProjectile extends IEnergyAbility {
// ==================== LIFESPAN ====================
+ /** @return maximum travel distance before the projectile despawns (0 = unlimited) */
float getMaxDistance();
void setMaxDistance(float distance);
+ /** @return maximum lifetime in ticks before the projectile despawns (0 = unlimited) */
int getMaxLifetime();
void setMaxLifetime(int ticks);
// ==================== COMBAT ====================
+ /** @return base damage dealt on hit */
float getDamage();
void setDamage(float damage);
+ /** @return horizontal knockback strength */
float getKnockback();
void setKnockback(float knockback);
+ /** @return upward knockback strength */
float getKnockbackUp();
void setKnockbackUp(float knockbackUp);
+ /** @return true if the projectile explodes on impact */
boolean isExplosive();
void setExplosive(boolean explosive);
+ /** @return explosion radius (only used if {@link #isExplosive()} is true) */
float getExplosionRadius();
void setExplosionRadius(float radius);
+ /** @return damage falloff multiplier over explosion radius (0 = no falloff, 1 = full falloff) */
float getExplosionDamageFalloff();
void setExplosionDamageFalloff(float falloff);
+ /** @return hit behavior type (0 = single hit, 1 = pierce, 2 = multi-hit with delay) */
int getHitType();
void setHitType(int hitType);
+ /** @return ticks between multi-hit damage ticks on the same entity */
int getMultiHitDelayTicks();
void setMultiHitDelayTicks(int delayTicks);
+ /** @return maximum number of entities this projectile can hit (0 = unlimited) */
int getMaxHits();
void setMaxHits(int maxHits);
// ==================== MOVEMENT ====================
+ /** @return travel speed (blocks per tick) */
float getSpeed();
void setSpeed(float speed);
+ /** @return true if the projectile homes toward its target */
boolean isHoming();
void setHoming(boolean homing);
+ /** @return how aggressively the projectile turns toward its target (higher = tighter turns) */
float getHomingStrength();
void setHomingStrength(float strength);
+ /** @return maximum range at which homing will acquire/track a target */
float getHomingRange();
void setHomingRange(float range);
// ==================== ANCHOR ====================
+ /** @return anchor point type used during the charge/windup phase */
int getAnchor();
float getAnchorOffsetX();
@@ -118,47 +154,92 @@ public interface IEnergyProjectile extends IEnergyAbility {
// ==================== POSITION ====================
+ /** @return X coordinate where the projectile was launched from */
double getStartX();
+ /** @return Y coordinate where the projectile was launched from */
double getStartY();
+ /** @return Z coordinate where the projectile was launched from */
double getStartZ();
// ==================== STATE ====================
+ /** @return true if the projectile has hit something */
boolean hasHit();
/**
* Returns the energy projectile sub-type.
- * 0=Orb, 1=Beam, 2=Disc, 3=Laser
+ * @return 0=Orb, 1=Beam, 2=Disc, 3=Laser, 4=Slicer
*/
int getEnergyType();
// ==================== FIRE / LAUNCH ====================
/**
- * Spawns the projectile in the world (if not yet spawned) and starts it moving toward the target entity.
+ * Spawns the projectile and launches it from its current position toward the target entity.
+ *
+ * No look-vector repositioning occurs — the projectile fires from exactly where it was
+ * placed by {@code createOrb}/{@code createBeam}/etc. If the target is a living entity,
+ * it is also set as the homing target for projectiles with homing enabled.
+ *
+ * To launch from the owner's eye position with look-vector snapping, use
+ * {@link #fireFrom(IEntityLivingBase, IEntity)} instead.
+ *
+ * @param target the entity to fire toward (can be null for untargeted launch)
*/
void fireAt(IEntity target);
/**
- * Spawns the projectile in the world (if not yet spawned) and starts it moving toward the specified coordinates.
+ * Spawns the projectile and launches it toward the specified world coordinates.
+ *
+ * The projectile fires from its current position — no look-vector repositioning occurs.
+ * Motion is calculated as a normalized direction vector scaled by the projectile's speed.
+ *
+ * @param x target X coordinate
+ * @param y target Y coordinate
+ * @param z target Z coordinate
*/
void fireAt(double x, double y, double z);
/**
- * Spawns the projectile in the world (if not yet spawned) and starts it moving in the specified direction.
+ * Spawns the projectile and launches it in the specified yaw/pitch direction.
+ *
+ * The projectile fires from its current position — no look-vector repositioning occurs.
+ *
+ * @param yaw horizontal angle in degrees (0 = south, 90 = west, like Minecraft yaw)
+ * @param pitch vertical angle in degrees (negative = up, positive = down)
*/
void fireDirection(float yaw, float pitch);
/**
- * Sets the owner, positions the projectile at the caster's eye level, and fires in the caster's look direction.
- * Convenience method similar to how fireKiAttack works.
+ * Sets the owner, positions the projectile at the caster's eye level, and launches it
+ * using the entity's full launch sequence ({@code startMoving}/{@code startFiring}).
+ *
+ * For player-owned projectiles, this snaps the projectile to the owner's look-vector
+ * position and fires in the caster's look direction. This is the intended method for
+ * "cast from self" behavior. The projectile's position set by {@code createOrb}/etc. is
+ * overridden.
+ *
+ * Use {@link #fireAt(IEntity)} or {@link #fireAt(double, double, double)} instead if you
+ * want to launch from a specific custom position.
+ *
+ * @param caster the entity to fire from
*/
void fireFrom(IEntityLivingBase caster);
/**
- * Sets the owner, positions the projectile at the caster's eye level, and fires toward the target entity.
+ * Sets the owner, positions the projectile at the caster's eye level, and launches it
+ * toward the target entity using the entity's full launch sequence.
+ *
+ * For player-owned projectiles, this snaps the projectile to the owner's look-vector
+ * position before firing toward the target. The projectile's position set by
+ * {@code createOrb}/etc. is overridden.
+ *
+ * Use {@link #fireAt(IEntity)} instead if you want to launch from a specific custom position.
+ *
+ * @param caster the entity to fire from
+ * @param target the entity to fire toward
*/
void fireFrom(IEntityLivingBase caster, IEntity target);
diff --git a/java/noppes/npcs/api/entity/IEnergySlicer.java b/java/noppes/npcs/api/entity/IEnergySlicer.java
index ed547a8..7a20182 100644
--- a/java/noppes/npcs/api/entity/IEnergySlicer.java
+++ b/java/noppes/npcs/api/entity/IEnergySlicer.java
@@ -3,10 +3,13 @@ package noppes.npcs.api.entity;
import net.minecraft.entity.Entity;
/**
- * Represents an energy slicer projectile - a thin, wide blade that slices through targets.
+ * A thin, wide blade projectile that slices through targets.
+ *
+ * Slicers travel in a straight line, cutting through entities in their path.
*/
public interface IEnergySlicer extends IEnergyProjectile {
+ /** Width of the slicer blade. */
float getSliceWidth();
void setSliceWidth(float width);