[Bleeding] Add ProjectileSource interface. Addresses BUKKIT-1038, BUKKIT-1156

By: t00thpick1 <t00thpick1dirko@gmail.com>

paper-api/src/main/java/org/bukkit/block/Dispenser.java

@@ -1,14 +1,25 @@
 package org.bukkit.block;
 
+import org.bukkit.projectiles.BlockProjectileSource;
+
 /**
  * Represents a dispenser.
  */
 public interface Dispenser extends BlockState, ContainerBlock {
 
     /**
-     * Attempts to dispense the contents of this block
+     * Gets the BlockProjectileSource object for this dispenser.
      * <p>
-     * If the block is no longer a dispenser, this will return false
+     * If the block is no longer a dispenser, this will return null.
+     *
+     * @return a BlockProjectileSource if valid, otherwise null
+     */
+    public BlockProjectileSource getBlockProjectileSource();
+
+    /**
+     * Attempts to dispense the contents of this block.
+     * <p>
+     * If the block is no longer a dispenser, this will return false.
      *
      * @return true if successful, otherwise false
      */

paper-api/src/main/java/org/bukkit/entity/LivingEntity.java

@@ -9,11 +9,12 @@ 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;
 
 /**
  * Represents a living entity, such as a monster or player
  */
-public interface LivingEntity extends Entity, Damageable {
+public interface LivingEntity extends Entity, Damageable, ProjectileSource {
 
     /**
      * Gets the height of the living entity's eyes above its Location.
@@ -111,14 +112,6 @@ public interface LivingEntity extends Entity, Damageable {
     @Deprecated
     public Arrow shootArrow();
 
-    /**
-     * Launches a {@link Projectile} from the living entity.
-     *
-     * @param projectile class of the projectile to launch
-     * @return the launched projectile
-     */
-    public <T extends Projectile> T launchProjectile(Class<? extends T> projectile);
-
     /**
      * Returns the amount of air that the living entity has remaining, in
      * ticks.

paper-api/src/main/java/org/bukkit/entity/Projectile.java

@@ -1,26 +1,41 @@
 package org.bukkit.entity;
 
-import org.bukkit.block.Dispenser;
+import org.bukkit.projectiles.ProjectileSource;
 
 /**
- * Represents a shootable entity
+ * Represents a shootable entity.
  */
 public interface Projectile extends Entity {
 
     /**
-     * Retrieve the shooter of this projectile. The returned value can be null
+     * This method exists for legacy reasons to provide backwards
-     * for projectiles shot from a {@link Dispenser} for example.
+     * compatibility. It will not exist at runtime and should not be used
-     *
+     * under any circumstances.
-     * @return the {@link LivingEntity} that shot this projectile
      */
-    public LivingEntity getShooter();
+    @Deprecated
+    public LivingEntity _INVALID_getShooter();
 
     /**
-     * Set the shooter of this projectile
+     * Retrieve the shooter of this projectile.
      *
-     * @param shooter the {@link LivingEntity} that shot this projectile
+     * @return the {@link ProjectileSource} that shot this projectile
      */
-    public void setShooter(LivingEntity shooter);
+    public ProjectileSource getShooter();
+
+    /**
+     * This method exists for legacy reasons to provide backwards
+     * compatibility. It will not exist at runtime and should not be used
+     * under any circumstances.
+     */
+    @Deprecated
+    public void _INVALID_setShooter(LivingEntity shooter);
+
+    /**
+     * Set the shooter of this projectile.
+     *
+     * @param shooter the {@link ProjectileSource} that shot this projectile
+     */
+    public void setShooter(ProjectileSource source);
 
     /**
      * Determine if this projectile should bounce or not when it hits.

paper-api/src/main/java/org/bukkit/projectiles/BlockProjectileSource.java

@@ -0,0 +1,13 @@
+package org.bukkit.projectiles;
+
+import org.bukkit.block.Block;
+
+public interface BlockProjectileSource extends ProjectileSource {
+
+    /**
+     * Gets the block this projectile source belongs to.
+     *
+     * @return Block for the projectile source
+     */
+    public Block getBlock();
+}

paper-api/src/main/java/org/bukkit/projectiles/ProjectileSource.java

@@ -0,0 +1,28 @@
+package org.bukkit.projectiles;
+
+import org.bukkit.entity.Projectile;
+import org.bukkit.util.Vector;
+
+/**
+ * Represents a valid source of a projectile.
+ */
+public interface ProjectileSource {
+
+    /**
+     * Launches a {@link Projectile} from the ProjectileSource.
+     *
+     * @param projectile class of the projectile to launch
+     * @return the launched projectile
+     */
+    public <T extends Projectile> T launchProjectile(Class<? extends T> projectile);
+
+    /**
+     * Launches a {@link Projectile} from the ProjectileSource with an
+     * initial velocity.
+     *
+     * @param projectile class of the projectile to launch
+     * @param velocity the velocity with which to launch
+     * @return the launched projectile
+     */
+    public <T extends Projectile> T launchProjectile(Class<? extends T> projectile, Vector velocity);
+}

paper-api/src/main/javadoc/org/bukkit/projectiles/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes to represent the source of a projectile
+ * <p>
+ */
+package org.bukkit.projectiles;
+