From 0bb0794be611f0711aa1f91fd3d4209aa96a09f3 Mon Sep 17 00:00:00 2001
From: Bukkit/Spigot <noreply+git-bukkit@papermc.io>
Date: Sat, 28 Jan 2023 11:38:58 +1100
Subject: [PATCH] #808: Add custom sound parameter option for playSound with
 entity as source

By: Gero <gecam59@gmail.com>
---
 paper-api/src/main/java/org/bukkit/World.java | 45 ++++++++++++++-----
 .../main/java/org/bukkit/entity/Player.java   | 41 +++++++++++++----
 2 files changed, 68 insertions(+), 18 deletions(-)

diff --git a/paper-api/src/main/java/org/bukkit/World.java b/paper-api/src/main/java/org/bukkit/World.java
index aa67bd2e6e..456b8d9376 100644
--- a/paper-api/src/main/java/org/bukkit/World.java
+++ b/paper-api/src/main/java/org/bukkit/World.java
@@ -2157,10 +2157,10 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * sound will be heard by the players if their clients do not have the
      * respective sound for the value passed.
      *
-     * @param location the location to play the sound
-     * @param sound the internal sound name to play
-     * @param volume the volume of the sound
-     * @param pitch the pitch of the sound
+     * @param location The location to play the sound
+     * @param sound The internal sound name to play
+     * @param volume The volume of the sound
+     * @param pitch The pitch of the sound
      */
     void playSound(@NotNull Location location, @NotNull String sound, float volume, float pitch);
 
@@ -2184,11 +2184,11 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * will be heard by the players if their clients do not have the respective
      * sound for the value passed.
      *
-     * @param location the location to play the sound
-     * @param sound the internal sound name to play
-     * @param category the category of the sound
-     * @param volume the volume of the sound
-     * @param pitch the pitch of the sound
+     * @param location The location to play the sound
+     * @param sound The internal sound name to play
+     * @param category The category of the sound
+     * @param volume The volume of the sound
+     * @param pitch The pitch of the sound
      */
     void playSound(@NotNull Location location, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch);
 
@@ -2211,12 +2211,37 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *
      * @param entity The entity to play the sound
      * @param sound The sound to play
-     * @param category the category of the sound
+     * @param volume The volume of the sound
+     * @param pitch The pitch of the sound
+     */
+    void playSound(@NotNull Entity entity, @NotNull String sound, float volume, float pitch);
+
+    /**
+     * Play a Sound at the location of the provided entity in the World.
+     * <p>
+     * This function will fail silently if Entity or Sound are null.
+     *
+     * @param entity The entity to play the sound
+     * @param sound The sound to play
+     * @param category The category of the sound
      * @param volume The volume of the sound
      * @param pitch The pitch of the sound
      */
     void playSound(@NotNull Entity entity, @NotNull Sound sound, @NotNull SoundCategory category, float volume, float pitch);
 
+    /**
+     * Play a Sound at the location of the provided entity in the World.
+     * <p>
+     * This function will fail silently if Entity or Sound are null.
+     *
+     * @param entity The entity to play the sound
+     * @param sound The sound to play
+     * @param category The category of the sound
+     * @param volume The volume of the sound
+     * @param pitch The pitch of the sound
+     */
+    void playSound(@NotNull Entity entity, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch);
+
     /**
      * Get an array containing the names of all the {@link GameRule}s.
      *
diff --git a/paper-api/src/main/java/org/bukkit/entity/Player.java b/paper-api/src/main/java/org/bukkit/entity/Player.java
index 14ca647820..55d0a82c5d 100644
--- a/paper-api/src/main/java/org/bukkit/entity/Player.java
+++ b/paper-api/src/main/java/org/bukkit/entity/Player.java
@@ -325,10 +325,10 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * sound will be heard by the player if their client does not have the
      * respective sound for the value passed.
      *
-     * @param location the location to play the sound
-     * @param sound the internal sound name to play
-     * @param volume the volume of the sound
-     * @param pitch the pitch of the sound
+     * @param location The location to play the sound
+     * @param sound The internal sound name to play
+     * @param volume The volume of the sound
+     * @param pitch The pitch of the sound
      */
     public void playSound(@NotNull Location location, @NotNull String sound, float volume, float pitch);
 
@@ -352,11 +352,11 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * will be heard by the player if their client does not have the respective
      * sound for the value passed.
      *
-     * @param location the location to play the sound
-     * @param sound the internal sound name to play
+     * @param location The location to play the sound
+     * @param sound The internal sound name to play
      * @param category The category of the sound
-     * @param volume the volume of the sound
-     * @param pitch the pitch of the sound
+     * @param volume The volume of the sound
+     * @param pitch The pitch of the sound
      */
     public void playSound(@NotNull Location location, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch);
 
@@ -372,6 +372,18 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      */
     public void playSound(@NotNull Entity entity, @NotNull Sound sound, float volume, float pitch);
 
+    /**
+     * Play a sound for a player at the location of the entity.
+     * <p>
+     * This function will fail silently if Entity or Sound are null.
+     *
+     * @param entity The entity to play the sound
+     * @param sound The sound to play
+     * @param volume The volume of the sound
+     * @param pitch The pitch of the sound
+     */
+    public void playSound(@NotNull Entity entity, @NotNull String sound, float volume, float pitch);
+
     /**
      * Play a sound for a player at the location of the entity.
      * <p>
@@ -385,6 +397,19 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      */
     public void playSound(@NotNull Entity entity, @NotNull Sound sound, @NotNull SoundCategory category, float volume, float pitch);
 
+    /**
+     * Play a sound for a player at the location of the entity.
+     * <p>
+     * This function will fail silently if Entity or Sound are null.
+     *
+     * @param entity The entity to play the sound
+     * @param sound The sound to play
+     * @param category The category of the sound
+     * @param volume The volume of the sound
+     * @param pitch The pitch of the sound
+     */
+    public void playSound(@NotNull Entity entity, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch);
+
     /**
      * Stop the specified sound from playing.
      *