Add the ability to play sounds from the recipient of the sound

KyoriPowered · Jun 6, 2021 · e279a0f · e279a0f
1 parent b3f0482
commit e279a0f
Show file tree

Hide file tree

Showing 3 changed files with 19 additions and 3 deletions.
diff --git a/api/src/main/java/net/kyori/adventure/audience/Audience.java b/api/src/main/java/net/kyori/adventure/audience/Audience.java
@@ -444,7 +444,9 @@ default void hideBossBar(final @NotNull BossBar bar) {
   }
 
   /**
-   * Plays a sound.
+   * Plays a sound at the location of the recipient of the sound.
+   *
+   * <p>To play a sound that follows the recipient, use {@link #playSound(Sound, Sound.Emitter)} with {@link Sound.Emitter#self()}.</p>
    *
    * @param sound a sound
    * @see Sound
@@ -470,15 +472,16 @@ default void playSound(final @NotNull Sound sound, final double x, final double
    * Plays a sound from an emitter, usually an entity.
    *
    * <p>
-   *   Sounds played from an emitter will follow the entity unless the sound is custom sound.
-   *   In the case where a custom sound is provided, the sound will be played at the location of the emitter at the time of calling.
+   *   Sounds played using this method will follow the emitter unless the sound is a custom sound.
+   *   In this case the sound will be played at the location of the emitter and will not follow them.
    * </p>
    *
    * <p><b>Note</b>: Due to <a href="https://bugs.mojang.com/browse/MC-138832">MC-138832</a>, the volume and pitch may be ignored when using this method.</p>
    *
    * @param sound a sound
    * @param emitter an emitter
    * @see Sound
+   * @see Sound.Emitter
    * @since 4.8.0
    */
   default void playSound(final @NotNull Sound sound, final Sound.@NotNull Emitter emitter) {

diff --git a/api/src/main/java/net/kyori/adventure/sound/Sound.java b/api/src/main/java/net/kyori/adventure/sound/Sound.java
@@ -254,5 +254,16 @@ interface Type extends Keyed {
    * @since 4.8.0
    */
   interface Emitter {
+    /**
+     * An emitter representing the recipient of a sound.
+     *
+     * <p>When used with {@link net.kyori.adventure.audience.Audience#playSound(Sound, Emitter)}, the sound will be emitted from the recipient of the sound.</p>
+     *
+     * @return the emitter
+     * @since 4.8.0
+     */
+    static @NotNull Emitter self() {
+      return SoundImpl.SELF;
+    }
   }
 }
diff --git a/api/src/main/java/net/kyori/adventure/sound/SoundImpl.java b/api/src/main/java/net/kyori/adventure/sound/SoundImpl.java
@@ -31,6 +31,8 @@
 import org.jetbrains.annotations.Nullable;
 
 abstract class SoundImpl implements Sound {
+  static final Emitter SELF = new Emitter() {};
+
   private final Source source;
   private final float volume;
   private final float pitch;