From 6faa544f6f481690dfcbf55af130978a9402c35f Mon Sep 17 00:00:00 2001 From: Kam Date: Sat, 7 Mar 2026 15:30:11 -0500 Subject: [PATCH] Fix some Firing Script Behavior for Energy Projectiles --- java/noppes/npcs/api/entity/IEnergyBeam.java | 9 +- java/noppes/npcs/api/entity/IEnergyDisc.java | 6 +- java/noppes/npcs/api/entity/IEnergyLaser.java | 10 +- java/noppes/npcs/api/entity/IEnergyOrb.java | 19 +++- .../npcs/api/entity/IEnergyProjectile.java | 99 +++++++++++++++++-- .../noppes/npcs/api/entity/IEnergySlicer.java | 5 +- 6 files changed, 133 insertions(+), 15 deletions(-) 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);