Add registry builders for SoundEvent and JukeboxSong

paper-api/src/main/java/io/papermc/paper/registry/TypedKeyImpl.java

@@ -1,16 +1,19 @@
 package io.papermc.paper.registry;
 
 import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.KeyPattern;
 import org.jspecify.annotations.NullMarked;
 
 @NullMarked
 record TypedKeyImpl<T>(Key key, RegistryKey<T> registryKey) implements TypedKey<T> {
     // Wrap key methods to make this easier to use
+    @KeyPattern.Namespace
     @Override
     public String namespace() {
         return this.key.namespace();
     }
 
+    @KeyPattern.Value
     @Override
     public String value() {
         return this.key.value();

paper-api/src/main/java/io/papermc/paper/registry/data/JukeboxSongRegistryEntry.java

@@ -0,0 +1,122 @@
+package io.papermc.paper.registry.data;
+
+
+import io.papermc.paper.registry.RegistryBuilder;
+import io.papermc.paper.registry.TypedKey;
+import io.papermc.paper.util.Either;
+import java.util.function.Consumer;
+import net.kyori.adventure.text.Component;
+import org.bukkit.JukeboxSong;
+import org.bukkit.Sound;
+import org.checkerframework.checker.index.qual.Positive;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.Range;
+
+/**
+ * A data-centric version-specific registry entry for the {@link JukeboxSong} type.
+ */
+@ApiStatus.Experimental
+@ApiStatus.NonExtendable
+public interface JukeboxSongRegistryEntry {
+
+    /**
+     * Gets the sound event for this song.
+     *
+     * @return the sound event
+     */
+    @Contract(pure = true)
+    Either<TypedKey<Sound>, SoundEventRegistryEntry> soundEvent();
+
+    /**
+     * Gets the description for this song.
+     *
+     * @return the description
+     */
+    @Contract(pure = true)
+    Component description();
+
+    /**
+     * Gets the length in seconds for this song.
+     *
+     * @return the length in seconds
+     */
+    @Contract(pure = true)
+    @Positive float lengthInSeconds();
+
+    /**
+     * Gets the comparator output for this song.
+     *
+     * @return the comparator output
+     */
+    @Contract(pure = true)
+    @Range(from = 0, to = 15) int comparatorOutput();
+
+    /**
+     * A mutable builder for the {@link JukeboxSongRegistryEntry} plugins may change in applicable registry events.
+     * <p>
+     * The following values are required for each builder:
+     * <ul>
+     *     <li>
+     *         {@link #soundEvent(TypedKey)} or {@link #soundEvent(Consumer)}
+     *     </li>
+     *     <li>{@link #description(Component)}</li>
+     *     <li>{@link #lengthInSeconds(float)}</li>
+     *     <li>{@link #comparatorOutput(int)}</li>
+     * </ul>
+     */
+    @ApiStatus.Experimental
+    @ApiStatus.NonExtendable
+    interface Builder extends JukeboxSongRegistryEntry, RegistryBuilder<JukeboxSong> {
+
+        /**
+         * Sets the sound event for this song to a sound event present
+         * in the {@link io.papermc.paper.registry.RegistryKey#SOUND_EVENT} registry.
+         * <p>This will override {@link #soundEvent(Consumer)}</p>
+         *
+         * @param soundEvent the sound event
+         * @return this builder
+         * @see #soundEvent(Consumer)
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder soundEvent(TypedKey<Sound> soundEvent);
+
+        /**
+         * Sets the sound event for this song to a new sound event.
+         * <p>This will override {@link #soundEvent(TypedKey)}</p>
+         *
+         * @param soundEvent the sound event
+         * @return this builder
+         * @see #soundEvent(TypedKey)
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder soundEvent(Consumer<? super SoundEventRegistryEntry.Builder> soundEvent);
+
+        /**
+         * Sets the description for this song.
+         *
+         * @param description the description
+         * @return this builder
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder description(Component description);
+
+        /**
+         * Sets the length in seconds for this song.
+         *
+         * @param lengthInSeconds the length in seconds (positive)
+         * @return this builder
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder lengthInSeconds(@Positive float lengthInSeconds);
+
+        /**
+         * Sets the comparator output for this song.
+         *
+         * @param comparatorOutput the comparator output [0-15]
+         * @return this builder
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder comparatorOutput(@Range(from = 0, to = 15) int comparatorOutput);
+    }
+}

paper-api/src/main/java/io/papermc/paper/registry/data/SoundEventRegistryEntry.java

@@ -0,0 +1,63 @@
+package io.papermc.paper.registry.data;
+
+import io.papermc.paper.registry.RegistryBuilder;
+import net.kyori.adventure.key.Key;
+import org.bukkit.Sound;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * A data-centric version-specific registry entry for the {@link Sound} type.
+ */
+@ApiStatus.Experimental
+@ApiStatus.NonExtendable
+public interface SoundEventRegistryEntry {
+
+    /**
+     * Gets the resource pack location for this sound event.
+     *
+     * @return the location
+     */
+    @Contract(pure = true)
+    Key location();
+
+    /**
+     * Gets the fixed range for this sound event, if present.
+     *
+     * @return the fixed range, or {@code null} if not present
+     */
+    @Contract(pure = true)
+    @Nullable Float fixedRange();
+
+    /**
+     * A mutable builder for the {@link SoundEventRegistryEntry} plugins may change in applicable registry events.
+     * <p>
+     * The following values are required for each builder:
+     * <ul>
+     *     <li>{@link #location(Key)}</li>
+     * </ul>
+     */
+    @ApiStatus.Experimental
+    @ApiStatus.NonExtendable
+    interface Builder extends SoundEventRegistryEntry, RegistryBuilder<Sound> {
+
+        /**
+         * Sets the resource pack location for this sound event.
+         *
+         * @param location the location
+         * @return this builder
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder location(Key location);
+
+        /**
+         * Sets the fixed range for this sound event.
+         *
+         * @param fixedRange the fixed range
+         * @return this builder
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder fixedRange(@Nullable Float fixedRange);
+    }
+}

paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEvents.java

@@ -3,9 +3,11 @@
 import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.data.EnchantmentRegistryEntry;
 import io.papermc.paper.registry.data.GameEventRegistryEntry;
+import io.papermc.paper.registry.data.JukeboxSongRegistryEntry;
 import io.papermc.paper.registry.data.PaintingVariantRegistryEntry;
 import org.bukkit.Art;
 import org.bukkit.GameEvent;
+import org.bukkit.JukeboxSong;
 import org.bukkit.enchantments.Enchantment;
 import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
@@ -23,6 +25,7 @@ public final class RegistryEvents {
     public static final RegistryEventProvider<GameEvent, GameEventRegistryEntry.Builder> GAME_EVENT = create(RegistryKey.GAME_EVENT);
     public static final RegistryEventProvider<Enchantment, EnchantmentRegistryEntry.Builder> ENCHANTMENT = create(RegistryKey.ENCHANTMENT);
     public static final RegistryEventProvider<Art, PaintingVariantRegistryEntry.Builder> PAINTING_VARIANT = create(RegistryKey.PAINTING_VARIANT);
+    public static final RegistryEventProvider<JukeboxSong, JukeboxSongRegistryEntry.Builder> JUKEBOX_SONG = create(RegistryKey.JUKEBOX_SONG);
 
     private RegistryEvents() {
     }

paper-api/src/main/java/io/papermc/paper/util/Either.java

@@ -0,0 +1,51 @@
+package io.papermc.paper.util;
+
+import java.util.Optional;
+import org.jetbrains.annotations.Contract;
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+public sealed interface Either<L, R> permits Either.Left, Either.Right {
+
+    @Contract(value = "_ -> new", pure = true)
+    static <L, R> Either.Left<L, R> left(final L value) {
+        return new EitherLeft<>(value);
+    }
+
+    @Contract(value = "_ -> new", pure = true)
+    static <L, R> Either.Right<L, R> right(final R value) {
+        return new EitherRight<>(value);
+    }
+
+    Optional<L> left();
+
+    Optional<R> right();
+
+    sealed interface Left<L, R> extends Either<L, R> permits EitherLeft {
+        L value();
+
+        @Override
+        default Optional<L> left() {
+            return Optional.of(this.value());
+        }
+
+        @Override
+        default Optional<R> right() {
+            return Optional.empty();
+        }
+    }
+
+    sealed interface Right<L, R> extends Either<L, R> permits EitherRight {
+        R value();
+
+        @Override
+        default Optional<L> left() {
+            return Optional.empty();
+        }
+
+        @Override
+        default Optional<R> right() {
+            return Optional.of(this.value());
+        }
+    }
+}

paper-api/src/main/java/io/papermc/paper/util/EitherLeft.java

@@ -0,0 +1,9 @@
+package io.papermc.paper.util;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+@ApiStatus.Internal
+@NullMarked
+record EitherLeft<L, R>(L value) implements Either.Left<L, R> {
+}

paper-api/src/main/java/io/papermc/paper/util/EitherRight.java

@@ -0,0 +1,9 @@
+package io.papermc.paper.util;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+@ApiStatus.Internal
+public record EitherRight<L, R>(R value) implements Either.Right<L, R> {
+}

paper-server/src/main/java/io/papermc/paper/registry/PaperRegistries.java

@@ -6,6 +6,7 @@
 import io.papermc.paper.datacomponent.PaperDataComponentType;
 import io.papermc.paper.registry.data.PaperEnchantmentRegistryEntry;
 import io.papermc.paper.registry.data.PaperGameEventRegistryEntry;
+import io.papermc.paper.registry.data.PaperJukeboxSongRegistryEntry;
 import io.papermc.paper.registry.data.PaperPaintingVariantRegistryEntry;
 import io.papermc.paper.registry.entry.RegistryEntry;
 import io.papermc.paper.registry.tag.TagKey;
@@ -105,7 +106,7 @@ public final class PaperRegistries {
             start(Registries.DAMAGE_TYPE, RegistryKey.DAMAGE_TYPE).craft(DamageType.class, CraftDamageType::new).build().delayed(),
             start(Registries.WOLF_VARIANT, RegistryKey.WOLF_VARIANT).craft(Wolf.Variant.class, CraftWolf.CraftVariant::new).build().delayed(),
             start(Registries.ENCHANTMENT, RegistryKey.ENCHANTMENT).craft(Enchantment.class, CraftEnchantment::new).serializationUpdater(FieldRename.ENCHANTMENT_RENAME).writable(PaperEnchantmentRegistryEntry.PaperBuilder::new).delayed(),
-            start(Registries.JUKEBOX_SONG, RegistryKey.JUKEBOX_SONG).craft(JukeboxSong.class, CraftJukeboxSong::new).build().delayed(),
+            start(Registries.JUKEBOX_SONG, RegistryKey.JUKEBOX_SONG).craft(JukeboxSong.class, CraftJukeboxSong::new).writable(PaperJukeboxSongRegistryEntry.Builder::new).delayed(),
             start(Registries.BANNER_PATTERN, RegistryKey.BANNER_PATTERN).craft(PatternType.class, CraftPatternType::new).build().delayed(),
             start(Registries.PAINTING_VARIANT, RegistryKey.PAINTING_VARIANT).craft(Art.class, CraftArt::new).writable(PaperPaintingVariantRegistryEntry.PaperBuilder::new).delayed(),
             start(Registries.INSTRUMENT, RegistryKey.INSTRUMENT).craft(MusicInstrument.class, CraftMusicInstrument::new).build().delayed(),