Add ray tracing and bounding box API

2 files changed, 84 insertions, 2 deletions

diff --git a/src/main/java/org/bukkit/entity/Entity.java b/src/main/java/org/bukkit/entity/Entity.java
index c798998c..1a7ec6da 100644
--- a/src/main/java/org/bukkit/entity/Entity.java
+++ b/src/main/java/org/bukkit/entity/Entity.java
@@ -9,6 +9,7 @@ import org.bukkit.block.BlockFace;
 import org.bukkit.event.entity.EntityDamageEvent;
 import org.bukkit.material.Directional;
 import org.bukkit.metadata.Metadatable;
+import org.bukkit.util.BoundingBox;
 import org.bukkit.util.Vector;
 
 import java.util.List;
@@ -70,6 +71,16 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
     public double getWidth();
 
     /**
+     * Gets the entity's current bounding box.
+     * <p>
+     * The returned bounding box reflects the entity's current location and
+     * size.
+     *
+     * @return the entity's current bounding box
+     */
+    public BoundingBox getBoundingBox();
+
+    /**
      * Returns true if the entity is supported by a block. This value is a
      * state updated by the server and is not recalculated unless the entity
      * moves.
diff --git a/src/main/java/org/bukkit/entity/LivingEntity.java b/src/main/java/org/bukkit/entity/LivingEntity.java
index 6a5de671..ed1d5064 100644
--- a/src/main/java/org/bukkit/entity/LivingEntity.java
+++ b/src/main/java/org/bukkit/entity/LivingEntity.java
@@ -5,14 +5,18 @@ import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
+import org.bukkit.FluidCollisionMode;
 import org.bukkit.Location;
 import org.bukkit.Material;
+import org.bukkit.World;
 import org.bukkit.attribute.Attributable;
 import org.bukkit.block.Block;
 import org.bukkit.inventory.EntityEquipment;
 import org.bukkit.potion.PotionEffect;
 import org.bukkit.potion.PotionEffectType;
 import org.bukkit.projectiles.ProjectileSource;
+import org.bukkit.util.RayTraceResult;
+import org.bukkit.util.Vector;
 
 /**
  * Represents a living entity, such as a monster or player
@@ -46,7 +50,7 @@ public interface LivingEntity extends Attributable, Entity, Damageable, Projecti
      * Gets all blocks along the living entity's line of sight.
      * <p>
      * This list contains all blocks from the living entity's eye position to
-     * target inclusive.
+     * target inclusive. This method considers all blocks as 1x1x1 in size.
      *
      * @param transparent HashSet containing all transparent block Materials (set to
      *     null for only air)
@@ -59,6 +63,10 @@ public interface LivingEntity extends Attributable, Entity, Damageable, Projecti
 
     /**
      * Gets the block that the living entity has targeted.
+     * <p>
+     * This method considers all blocks as 1x1x1 in size. To take exact block
+     * collision shapes into account, see {@link #getTargetBlockExact(int,
+     * FluidCollisionMode)}.
      *
      * @param transparent HashSet containing all transparent block Materials (set to
      *     null for only air)
@@ -71,7 +79,8 @@ public interface LivingEntity extends Attributable, Entity, Damageable, Projecti
     /**
      * Gets the last two blocks along the living entity's line of sight.
      * <p>
-     * The target block will be the last block in the list.
+     * The target block will be the last block in the list. This method
+     * considers all blocks as 1x1x1 in size.
      *
      * @param transparent HashSet containing all transparent block Materials (set to
      *     null for only air)
@@ -83,6 +92,68 @@ public interface LivingEntity extends Attributable, Entity, Damageable, Projecti
     public List<Block> getLastTwoTargetBlocks(Set<Material> transparent, int maxDistance);
 
     /**
+     * Gets the block that the living entity has targeted.
+     * <p>
+     * This takes the blocks' precise collision shapes into account. Fluids are
+     * ignored.
+     * <p>
+     * This may cause loading of chunks! Some implementations may impose
+     * artificial restrictions on the maximum distance.
+     *
+     * @param maxDistance the maximum distance to scan
+     * @return block that the living entity has targeted
+     * @see #getTargetBlockExact(int, org.bukkit.FluidCollisionMode)
+     */
+    public Block getTargetBlockExact(int maxDistance);
+
+    /**
+     * Gets the block that the living entity has targeted.
+     * <p>
+     * This takes the blocks' precise collision shapes into account.
+     * <p>
+     * This may cause loading of chunks! Some implementations may impose
+     * artificial restrictions on the maximum distance.
+     *
+     * @param maxDistance the maximum distance to scan
+     * @param fluidCollisionMode the fluid collision mode
+     * @return block that the living entity has targeted
+     * @see #rayTraceBlocks(double, FluidCollisionMode)
+     */
+    public Block getTargetBlockExact(int maxDistance, FluidCollisionMode fluidCollisionMode);
+
+    /**
+     * Performs a ray trace that provides information on the targeted block.
+     * <p>
+     * This takes the blocks' precise collision shapes into account. Fluids are
+     * ignored.
+     * <p>
+     * This may cause loading of chunks! Some implementations may impose
+     * artificial restrictions on the maximum distance.
+     *
+     * @param maxDistance the maximum distance to scan
+     * @return information on the targeted block, or <code>null</code> if there
+     *     is no targeted block in range
+     * @see #rayTraceBlocks(double, FluidCollisionMode)
+     */
+    public RayTraceResult rayTraceBlocks(double maxDistance);
+
+    /**
+     * Performs a ray trace that provides information on the targeted block.
+     * <p>
+     * This takes the blocks' precise collision shapes into account.
+     * <p>
+     * This may cause loading of chunks! Some implementations may impose
+     * artificial restrictions on the maximum distance.
+     *
+     * @param maxDistance the maximum distance to scan
+     * @param fluidCollisionMode the fluid collision mode
+     * @return information on the targeted block, or <code>null</code> if there
+     *     is no targeted block in range
+     * @see World#rayTraceBlocks(Location, Vector, double, FluidCollisionMode)
+     */
+    public RayTraceResult rayTraceBlocks(double maxDistance, FluidCollisionMode fluidCollisionMode);
+
+    /**
      * Returns the amount of air that the living entity has remaining, in
      * ticks.
      *