feat: support MiniPlaceholders v3 and v2

Figured migration might be slow for plugin authors, MiniPlaceholders also limits its version compatibility scope significantly (compared to ColorParser) which may cause issues for some authors, stuck on older MiniPlaceholders versions.

Since I already use reflection for this exact reason, we simple extended the logic significantly while also making a quite nice cleanup.

This commit ensures ColorParser works with both 2.X.X and 3.X.X versions of MiniPlaceholders, without making API changes in ColorParser (Hooray).

Author: darksaid98

common/src/main/java/io/github/milkdrinkers/colorparser/common/ComponentBuilder.java

@@ -4,6 +4,8 @@
 import io.github.milkdrinkers.colorparser.common.placeholder.PlaceholderContext;
 import io.github.milkdrinkers.colorparser.common.placeholder.PlatformPlayer;
 import io.github.milkdrinkers.colorparser.common.tag.CustomTags;
+import net.kyori.adventure.audience.Audience;
+import net.kyori.adventure.audience.ForwardingAudience;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.ComponentLike;
 import net.kyori.adventure.text.minimessage.tag.TagPattern;
@@ -12,6 +14,7 @@
 import org.intellij.lang.annotations.Subst;
 import org.jetbrains.annotations.NotNull;
 
+import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
@@ -39,6 +42,33 @@ public abstract class ComponentBuilder<ColorParser extends ComponentBuilder<Colo
     private final List<TagResolver> placeholders = new ArrayList<>(8);
     private final List<TagResolver> miscTagResolvers = new ArrayList<>(4);
 
+    // Used by adventure (and MiniPlaceholders) when deserialising to add context for who the target is
+    protected Audience audienceTarget = null;
+    protected Audience audienceRelation = null;
+
+    private static volatile boolean miniPlaceholdersInitialized = false; // Tracks whether we have tried and failed to load MiniPlaceholders 3.X (prevents us from doing it again)
+    private static volatile Method MINIPLACEHOLDERS_METHOD_RELATIONAL; // Used to send relational placeholders using MiniPlaceholders
+
+    /**
+     * Lazy loads the miniplaceholders method required for using relational placeholders.
+     */
+    private void lazyloadMiniPlaceholders() {
+        if (miniPlaceholdersInitialized)
+            return;
+
+        synchronized (ComponentBuilder.class) {
+            Method tempMethod = null;
+            try {
+                final Class<?> tempClass = Class.forName("io.github.miniplaceholders.api.types.RelationalAudience");
+                tempMethod = tempClass.getMethod("from", Audience.class, Audience.class);
+            } catch (Exception ignored) {
+            } finally {
+                MINIPLACEHOLDERS_METHOD_RELATIONAL = tempMethod;
+                miniPlaceholdersInitialized = true;
+            }
+        }
+    }
+
     /**
      * Creates a new ComponentBuilder with the given engine and content.
      *
@@ -299,7 +329,23 @@ public Component build() {
         System.arraycopy(placeholders.toArray(new TagResolver[0]), 0, resolvers, 0, placeholders.size());
         System.arraycopy(miscTagResolvers.toArray(new TagResolver[0]), 0, resolvers, placeholders.size(), miscTagResolvers.size());
 
-        return getEngine().getMiniMessage().deserialize(text, resolvers); // Parse the final string to a Component
+        // Parse the final string to a Component
+        if (audienceTarget != null) {
+
+            // MiniPlaceholders 3.X relational placeholder support
+            if (audienceRelation != null) {
+                lazyloadMiniPlaceholders();
+                if (MINIPLACEHOLDERS_METHOD_RELATIONAL != null) {
+                    try {
+                        final ForwardingAudience.Single relationalAudience = (ForwardingAudience.Single) MINIPLACEHOLDERS_METHOD_RELATIONAL.invoke(null, audienceTarget, audienceRelation);
+                        return getEngine().getMiniMessage().deserialize(text, relationalAudience, resolvers);
+                    } catch (Exception ignored) {
+                    }
+                }
+            }
+            return getEngine().getMiniMessage().deserialize(text, audienceTarget, resolvers);
+        }
+        return getEngine().getMiniMessage().deserialize(text, resolvers);
     }
 
     /**

common/src/main/java/io/github/milkdrinkers/colorparser/common/placeholder/provider/MiniPlaceholdersReflectionImpl.java

@@ -0,0 +1,182 @@
+package io.github.milkdrinkers.colorparser.common.placeholder.provider;
+
+import net.kyori.adventure.audience.Audience;
+import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;
+import org.jetbrains.annotations.Nullable;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.util.Optional;
+
+/**
+ * Used by MiniPlaceholders Placeholder Providers to handle reflection and multi-version support.
+ */
+public abstract class MiniPlaceholdersReflectionImpl {
+    private enum Version {
+        V3,
+        V2V1,
+        UNKNOWN
+    }
+
+    private volatile boolean initialized = false;
+    private volatile Version version = Version.UNKNOWN;
+    private volatile @Nullable Method global = null;
+    private volatile @Nullable Method audience = null;
+    private volatile @Nullable Method placeholders = null;
+
+    /**
+     * Lazily initializes fields for MiniPlaceholders usage.
+     * This also implements code to make usage of MiniPlaceholders version agnostic between V2 and V3.
+     */
+    protected void lazyLoad() {
+        // Lazily do reflection
+        if (!initialized) {
+            synchronized (MiniPlaceholdersReflectionImpl.class) {
+                try {
+                    final ClassLoader classLoader = this.getClass().getClassLoader();
+
+                    // Figure out what version of mini placeholders is running based on present classes
+                    try {
+                        final Class<?> miniPlaceholdersClass = classLoader.loadClass("io.github.miniplaceholders.api.MiniPlaceholders");
+                        miniPlaceholdersClass.getMethod("getGlobalPlaceholders");
+                        version = Version.V2V1;
+                    } catch (ClassNotFoundException | NoSuchMethodException | RuntimeException e) {
+                        try {
+                            final Class<?> miniPlaceholdersClass = classLoader.loadClass("io.github.miniplaceholders.api.MiniPlaceholders");
+                            miniPlaceholdersClass.getMethod("globalPlaceholders");
+                            version = Version.V3;
+                        } catch (ClassNotFoundException | NoSuchMethodException | RuntimeException e2) {
+                            version = Version.UNKNOWN;
+                        }
+                    }
+
+                    // Lazy initialize fields depending on running version
+                    if (!version.equals(Version.UNKNOWN) && classLoader != null) {
+                        final Class<?> miniPlaceholdersClass = classLoader.loadClass("io.github.miniplaceholders.api.MiniPlaceholders");
+                        global = isV3() ? miniPlaceholdersClass.getMethod("globalPlaceholders") : miniPlaceholdersClass.getMethod("getGlobalPlaceholders");
+                        audience = isV3() ? miniPlaceholdersClass.getMethod("audiencePlaceholders") : miniPlaceholdersClass.getMethod("getAudiencePlaceholders", Audience.class);
+                        placeholders = isV3() ? miniPlaceholdersClass.getMethod("relationalPlaceholders") : miniPlaceholdersClass.getMethod("getRelationalPlaceholders", Audience.class, Audience.class);
+                    }
+                } catch (Exception ignored) {
+                } finally {
+                    initialized = true;
+                }
+            }
+        }
+    }
+
+    /**
+     * Whether the running version of MiniPlaceholders is version 3.X.X.
+     * @return boolean
+     */
+    protected boolean isV3() {
+        return version.equals(Version.V3);
+    }
+
+    /**
+     * Whether the running version of MiniPlaceholders is version 2.X.X.
+     * @return boolean
+     */
+    protected boolean isV2() {
+        return version.equals(Version.V2V1);
+    }
+
+    /**
+     * Whether the running version of MiniPlaceholders is version unknown.
+     * @return boolean
+     */
+    protected boolean isUnknown() {
+        return version.equals(Version.UNKNOWN);
+    }
+
+    /**
+     * Get the global tag resolver method as an optional.
+     * @return optional method
+     */
+    private Optional<Method> getGlobal() {
+        return Optional.ofNullable(global);
+    }
+
+    /**
+     * Get the audience tag resolver method as an optional.
+     * @return optional method
+     */
+    private Optional<Method> getAudience() {
+        return Optional.ofNullable(audience);
+    }
+
+    /**
+     * Get the relational tag resolver method as an optional.
+     * @return optional method
+     */
+    private Optional<Method> getRelational() {
+        return Optional.ofNullable(placeholders);
+    }
+
+    /**
+     * Get a global tag resolver from MiniPlaceholders.
+     * @return the tag resolver or an empty tag resolver as fallback
+     */
+    protected TagResolver resolveGlobal() {
+        return getGlobal()
+            .map(method -> {
+                try {
+                    return (TagResolver) method.invoke(null);
+                } catch (IllegalAccessException | InvocationTargetException e) {
+                    return TagResolver.empty();
+                }
+            })
+            .orElse(TagResolver.empty());
+    }
+
+    /**
+     * Get an audience tag resolver from MiniPlaceholders.
+     * @param audience1 the audience to resolve tags for (or null if using MiniPlaceholders v3.X.X)
+     * @return the tag resolver or an empty tag resolver as fallback
+     */
+    protected TagResolver resolveAudience(final @Nullable Audience audience1) {
+        if (audience1 == null)
+            return resolveGlobal();
+
+        return getAudience()
+            .map(method -> {
+                try {
+                    return TagResolver.resolver(
+                        resolveGlobal(),
+                        isV3() ?
+                            (TagResolver) method.invoke(null) :
+                            (TagResolver) method.invoke(null, audience1)
+                    );
+                } catch (IllegalAccessException | InvocationTargetException e) {
+                    return TagResolver.empty();
+                }
+            })
+            .orElse(TagResolver.empty());
+    }
+
+    /**
+     * Get a relational tag resolver from MiniPlaceholders.
+     * @param audience1 the audience to resolve tags for (or null if using MiniPlaceholders v3.X.X)
+     * @param audience2 the audience to resolve tags for (or null if using MiniPlaceholders v3.X.X)
+     * @return the tag resolver or an empty tag resolver as fallback
+     */
+    protected TagResolver resolveRelational(final @Nullable Audience audience1, final @Nullable Audience audience2) {
+        if (audience1 == null || audience2 == null)
+            return resolveAudience(audience1);
+
+        return getRelational()
+            .map(method -> {
+                try {
+                    return TagResolver.resolver(
+                        resolveAudience(audience1),
+                        isV3() ?
+                            (TagResolver) method.invoke(null) :
+                            (TagResolver) method.invoke(null, audience1, audience2)
+                    );
+                } catch (IllegalAccessException | InvocationTargetException e) {
+                    return TagResolver.empty();
+                }
+            })
+            .orElse(TagResolver.empty());
+    }
+}

paper/src/main/java/io/github/milkdrinkers/colorparser/paper/PaperComponentBuilder.java

@@ -12,6 +12,8 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.Objects;
+
 /**
  * Platform-specific {@link ComponentBuilder} for creating Adventure {@link Component}'s.
  * <p>
@@ -121,6 +123,7 @@ public PaperComponentBuilder mini() {
      */
     @NotNull
     public PaperComponentBuilder mini(@NotNull Player player) {
+        audienceTarget = player.filterAudience(a -> true);
         miniPlaceholdersContext = new PaperPlaceholderContext(PlaceholderContext.Type.PLAYER, new PaperPlayer(player), null);
         miniPlaceholdersEnabled = true;
         return this;
@@ -135,6 +138,8 @@ public PaperComponentBuilder mini(@NotNull Player player) {
      */
     @NotNull
     public PaperComponentBuilder mini(@NotNull OfflinePlayer player) {
+        if (player.isOnline())
+            audienceTarget = Objects.requireNonNull(player.getPlayer()).filterAudience(a -> true);
         miniPlaceholdersContext = new PaperPlaceholderContext(PlaceholderContext.Type.PLAYER, new PaperPlayer(player), null);
         miniPlaceholdersEnabled = true;
         return this;
@@ -149,6 +154,8 @@ public PaperComponentBuilder mini(@NotNull OfflinePlayer player) {
      */
     @NotNull
     public PaperComponentBuilder mini(@NotNull Player player1, @NotNull Player player2) {
+        audienceTarget = player1.filterAudience(a -> true);
+        audienceRelation = player2.filterAudience(a -> true);
         miniPlaceholdersContext = new PaperPlaceholderContext(PlaceholderContext.Type.RELATIONAL, new PaperPlayer(player1), new PaperPlayer(player2));
         miniPlaceholdersEnabled = true;
         return this;