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.RegistryBuilderFactory;
+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<RegistryBuilderFactory<Sound, ? extends 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

@@ -5,9 +5,11 @@
 import io.papermc.paper.registry.data.DamageTypeRegistryEntry;
 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.block.banner.PatternType;
 import org.bukkit.damage.DamageType;
 import org.bukkit.enchantments.Enchantment;
@@ -29,6 +31,7 @@ public final class RegistryEvents {
     public static final RegistryEventProvider<Art, PaintingVariantRegistryEntry.Builder> PAINTING_VARIANT = create(RegistryKey.PAINTING_VARIANT);
     public static final RegistryEventProvider<PatternType, BannerPatternRegistryEntry.Builder> BANNER_PATTERN = create(RegistryKey.BANNER_PATTERN);
     public static final RegistryEventProvider<DamageType, DamageTypeRegistryEntry.Builder> DAMAGE_TYPE = create(RegistryKey.DAMAGE_TYPE);
+    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,109 @@
+package io.papermc.paper.util;
+
+import java.util.Optional;
+import org.jetbrains.annotations.Contract;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A type that can be either a left value or a right value.
+ *
+ * @param <L> the type of the left value
+ * @param <R> the type of the right value
+ */
+@NullMarked
+public sealed interface Either<L, R> permits Either.Left, Either.Right {
+
+    /**
+     * Create a new Either with a left value.
+     *
+     * @param value the left value
+     * @return a new Either with a left value
+     * @param <L> the type of the left value
+     * @param <R> the type of the right value
+     */
+    @Contract(value = "_ -> new", pure = true)
+    static <L, R> Either.Left<L, R> left(final L value) {
+        return new EitherLeft<>(value);
+    }
+
+    /**
+     * Create a new Either with a right value.
+     *
+     * @param value the right value
+     * @return a new Either with a right value
+     * @param <L> the type of the left value
+     * @param <R> the type of the right value
+     */
+    @Contract(value = "_ -> new", pure = true)
+    static <L, R> Either.Right<L, R> right(final R value) {
+        return new EitherRight<>(value);
+    }
+
+    /**
+     * Get an optional of the left value.
+     *
+     * @return an optional of the left value
+     */
+    Optional<L> left();
+
+    /**
+     * Get an optional of the right value.
+     *
+     * @return an optional of the right value
+     */
+    Optional<R> right();
+
+    /**
+     * A left value.
+     *
+     * @param <L> the type of the left value
+     * @param <R> the type of the right value
+     */
+    sealed interface Left<L, R> extends Either<L, R> permits EitherLeft {
+
+        /**
+         * Get the left value.
+         *
+         * @return the left value
+         */
+        @Contract(pure = true)
+        L value();
+
+        @Override
+        default Optional<L> left() {
+            return Optional.of(this.value());
+        }
+
+        @Override
+        default Optional<R> right() {
+            return Optional.empty();
+        }
+    }
+
+    /**
+     * A right value.
+     *
+     * @param <L> the type of the left value
+     * @param <R> the type of the right value
+     */
+    sealed interface Right<L, R> extends Either<L, R> permits EitherRight {
+
+        /**
+         * Get the right value.
+         *
+         * @return the right value
+         */
+        @Contract(pure = true)
+        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
+record EitherRight<L, R>(R value) implements Either.Right<L, R> {
+}

paper-server/patches/features/0016-Rewrite-dataconverter-system.patch

@@ -29346,10 +29346,10 @@ index 0000000000000000000000000000000000000000..62c0f4073aff301bf5b3187e0d4446fd
 +}
 diff --git a/ca/spottedleaf/dataconverter/util/CommandArgumentUpgrader.java b/ca/spottedleaf/dataconverter/util/CommandArgumentUpgrader.java
 new file mode 100644
-index 0000000000000000000000000000000000000000..40da70d5cf584a9730f9fe81c355cf8513fba475
+index 0000000000000000000000000000000000000000..9fab2371790596ab57298fe28b8983d85210c6d9
 --- /dev/null
 +++ b/ca/spottedleaf/dataconverter/util/CommandArgumentUpgrader.java
-@@ -0,0 +1,592 @@
+@@ -0,0 +1,597 @@
 +package ca.spottedleaf.dataconverter.util;
 +
 +import ca.spottedleaf.dataconverter.minecraft.MCDataConverter;
@@ -29908,6 +29908,11 @@ index 0000000000000000000000000000000000000000..40da70d5cf584a9730f9fe81c355cf85
 +                ) {
 +                    return Optional.of(new HolderLookup.RegistryLookup<T>() {
 +                        @Override
++                        public Optional<T> getValueForCopying(final ResourceKey<T> resourceKey) {
++                            return Optional.empty();
++                        }
++
++                        @Override
 +                        public ResourceKey<? extends Registry<? extends T>> key() {
 +                            return registryRef;
 +                        }
@@ -30621,7 +30626,7 @@ index 1110ca4075a1bbaa46b66686435dab91b275c945..c2218630c3074c8b3f82364e37503b12
          return structureTemplate.save(new CompoundTag());
      }
 diff --git a/net/minecraft/server/MinecraftServer.java b/net/minecraft/server/MinecraftServer.java
-index 0d65bf24f515b80701150fdc430f324a533cb478..b92a3da5c325e69f5601416d4205fb33429742b3 100644
+index 4b9df7d4aab3f7dae2d3b8ced4663162334cdbe6..5ef7a016a0c7bc09d5cd24f14124b15b99d5e18d 100644
 --- a/net/minecraft/server/MinecraftServer.java
 +++ b/net/minecraft/server/MinecraftServer.java
 @@ -305,6 +305,7 @@ public abstract class MinecraftServer extends ReentrantBlockableEventLoop<TickTa