Implementation of richer playEffect methods. Addresses BUKKIT-857

By: Celtic Minstrel <celtic.minstrel.ca@some.place>

paper-api/src/main/java/org/bukkit/Effect.java

@@ -4,30 +4,41 @@ import java.util.Map;
 
 import com.google.common.collect.Maps;
 
+import org.bukkit.block.BlockFace;
+import org.bukkit.potion.Potion;
+
 /**
  * A list of effects that the server is able to send to players.
  */
 public enum Effect {
-    CLICK2(1000),
+    CLICK2(1000, Type.SOUND),
-    CLICK1(1001),
+    CLICK1(1001, Type.SOUND),
-    BOW_FIRE(1002),
+    BOW_FIRE(1002, Type.SOUND),
-    DOOR_TOGGLE(1003),
+    DOOR_TOGGLE(1003, Type.SOUND),
-    EXTINGUISH(1004),
+    EXTINGUISH(1004, Type.SOUND),
-    RECORD_PLAY(1005),
+    RECORD_PLAY(1005, Type.SOUND, Material.class),
-    GHAST_SHRIEK(1007),
+    GHAST_SHRIEK(1007, Type.SOUND),
-    GHAST_SHOOT(1008),
+    GHAST_SHOOT(1008, Type.SOUND),
-    BLAZE_SHOOT(1009),
+    BLAZE_SHOOT(1009, Type.SOUND),
-    SMOKE(2000),
+    SMOKE(2000, Type.VISUAL, BlockFace.class),
-    STEP_SOUND(2001),
+    STEP_SOUND(2001, Type.SOUND, Material.class),
-    POTION_BREAK(2002),
+    POTION_BREAK(2002, Type.VISUAL, Potion.class),
-    ENDER_SIGNAL(2003),
+    ENDER_SIGNAL(2003, Type.VISUAL),
-    MOBSPAWNER_FLAMES(2004);
+    MOBSPAWNER_FLAMES(2004, Type.VISUAL);
 
     private final int id;
+    private final Type type;
+    private final Class<?> data;
     private static final Map<Integer, Effect> BY_ID = Maps.newHashMap();
 
-    Effect(int id) {
+    Effect(int id, Type type) {
+        this(id,type,null);
+    }
+
+    Effect(int id, Type type, Class<?> data) {
         this.id = id;
+        this.type = type;
+        this.data = data;
     }
 
     /**
@@ -39,6 +50,20 @@ public enum Effect {
         return this.id;
     }
 
+    /**
+     * @return The type of the effect.
+     */
+    public Type getType() {
+        return this.type;
+    }
+
+    /**
+     * @return The class which represents data for this effect, or null if none
+     */
+    public Class<?> getData() {
+        return this.data;
+    }
+
     /**
      * Gets the Effect associated with the given ID.
      *
@@ -54,4 +79,9 @@ public enum Effect {
             BY_ID.put(effect.id, effect);
         }
     }
+
+    /**
+     * Represents the type of an effect.
+     */
+    public enum Type {SOUND, VISUAL}
 }

paper-api/src/main/java/org/bukkit/Material.java

@@ -476,4 +476,11 @@ public enum Material {
             BY_NAME.put(material.name(), material);
         }
     }
+
+    /**
+     * @return True if this material represents a playable music disk.
+     */
+    public boolean isRecord() {
+        return id >= GOLD_RECORD.id && id <= RECORD_11.id;
+    }
 }

paper-api/src/main/java/org/bukkit/World.java

@@ -620,7 +620,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      *
      * @param location the {@link Location} around which players must be to hear the sound
      * @param effect the {@link Effect}
-     * @param data a data bit needed for the RECORD_PLAY, SMOKE, and STEP_SOUND sounds
+     * @param data a data bit needed for some effects
      */
     public void playEffect(Location location, Effect effect, int data);
 
@@ -629,11 +629,30 @@ public interface World extends PluginMessageRecipient, Metadatable {
      *
      * @param location the {@link Location} around which players must be to hear the effect
      * @param effect the {@link Effect}
-     * @param data a data bit needed for the RECORD_PLAY, SMOKE, and STEP effects
+     * @param data a data bit needed for some effects
      * @param radius the radius around the location
      */
     public void playEffect(Location location, Effect effect, int data, int radius);
 
+    /**
+     * Plays an effect to all players within a default radius around a given location.
+     *
+     * @param location the {@link Location} around which players must be to hear the sound
+     * @param effect the {@link Effect}
+     * @param data a data bit needed for some effects
+     */
+    public <T> void playEffect(Location location, Effect effect, T data);
+
+    /**
+     * Plays an effect to all players within a given radius around a location.
+     *
+     * @param location the {@link Location} around which players must be to hear the effect
+     * @param effect the {@link Effect}
+     * @param data a data bit needed for some effects
+     * @param radius the radius around the location
+     */
+    public <T> void playEffect(Location location, Effect effect, T data, int radius);
+
     /**
      * Get empty chunk snapshot (equivalent to all air blocks), optionally including valid biome
      * data. Used for representing an ungenerated chunk, or for fetching only biome data without loading a chunk.

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

@@ -201,10 +201,19 @@ public interface Player extends HumanEntity, CommandSender, OfflinePlayer, Plugi
      *
      * @param loc the location to play the effect at
      * @param effect the {@link Effect}
-     * @param data a data bit needed for the RECORD_PLAY, SMOKE, and STEP_SOUND sounds
+     * @param data a data bit needed for some effects
      */
     public void playEffect(Location loc, Effect effect, int data);
 
+    /**
+     * Plays an effect to just this player.
+     *
+     * @param loc the location to play the effect at
+     * @param effect the {@link Effect}
+     * @param data a data bit needed for some effects
+     */
+    public <T> void playEffect(Location loc, Effect effect, T data);
+
     /**
      * Send a block change. This fakes a block change packet for a user at
      * a certain location. This will not actually change the world in any way.

paper-api/src/test/java/org/bukkit/plugin/messaging/TestPlayer.java

@@ -675,4 +675,8 @@ public class TestPlayer implements Player {
     public void removeMetadata(String metadataKey, Plugin owningPlugin) {
         throw new UnsupportedOperationException("Not supported yet.");
     }
+
+    public <T> void playEffect(Location loc, Effect effect, T data) {
+        throw new UnsupportedOperationException("Not supported yet.");
+    }
 }