2.12.2-dev

Let's have component support finally :D

.github/workflows/pr_build_jars.yml

@@ -5,8 +5,10 @@ on:
     branches:
     - development
     paths:
-    - "src/**"
+    - "../../spigot/**"
-    - "build.gradle"
+    - "../../paper/**"
+    - "build.gradle.kts"
+    - "settings.gradle.kts"
 
 jobs:
   testBuilds:

README.md

@@ -32,7 +32,7 @@
 
 Support for specific plugins are provided either by the plugin itself or through expansions. The expansions may be downloaded in-game through the PAPI Expansion Cloud. There are currently over 240+ expansions that support a wide variety of plugins, such as Essentials, Factions, LuckPerms, and Vault. 
 
-PlaceholderAPI has been downloaded over 1,700,000 times on Spigot and has been used concurrently on over 45,000 servers, which makes it a must-have for a server of any type or scale.
+PlaceholderAPI has been downloaded over 2,000,000 times on Spigot and has been used concurrently on over 50,000 servers, which makes it a must-have for a server of any type or scale.
 
 ## Contribute
 If you would like to contribute towards PlaceholderAPI should you take a look at our [Contributing file][contributing] for the ins and outs on how you can do that and what you need to keep in mind.

build.gradle.kts

@@ -3,15 +3,23 @@ import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
 plugins {
     `java-library`
     `maven-publish`
-    id("com.github.hierynomus.license") version "0.16.1"
+//    id("com.github.hierynomus.license") version "0.16.1"
     id("io.github.goooler.shadow") version "8.1.7"
 }
 
 group = "me.clip"
-version = "2.11.8-DEV-${System.getProperty("BUILD_NUMBER")}"
+version = "2.12.2-DEV-${System.getProperty("BUILD_NUMBER")}"
 
 description = "An awesome placeholder provider!"
 
+val paper by sourceSets.creating {
+    java.srcDir("src/paper/java")
+
+    // paper can see main code
+    compileClasspath += sourceSets.main.get().output
+    runtimeClasspath += output + compileClasspath
+}
+
 repositories {
     maven("https://oss.sonatype.org/content/repositories/snapshots/")
 
@@ -24,17 +32,17 @@ repositories {
 }
 
 dependencies {
-    implementation("org.bstats:bstats-bukkit:3.0.1")
+    implementation("org.bstats:bstats-bukkit:3.1.0")
     implementation("net.kyori:adventure-platform-bukkit:4.4.1")
 
-    //compileOnly("org.spigotmc:spigot-api:1.21-R0.1-SNAPSHOT")
+    add(paper.compileOnlyConfigurationName, "net.kyori:adventure-platform-bukkit:4.4.1")
-    compileOnly("io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT")
+    add(paper.compileOnlyConfigurationName, "dev.folia:folia-api:1.21.11-R0.1-SNAPSHOT")
-    compileOnly("dev.folia:folia-api:1.20.1-R0.1-SNAPSHOT")
+
+    compileOnly("dev.folia:folia-api:1.21.11-R0.1-SNAPSHOT")
     compileOnlyApi("org.jetbrains:annotations:23.0.0")
 
     testImplementation("org.openjdk.jmh:jmh-core:1.32")
     testImplementation("org.openjdk.jmh:jmh-generator-annprocess:1.32")
-
     testImplementation("org.junit.jupiter:junit-jupiter-engine:5.8.2")
     testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.8.1")
 }
@@ -50,19 +58,6 @@ java {
     disableAutoTargetJvm()
 }
 
-license {
-    header = rootProject.file("config/headers/main.txt")
-
-    include("**/*.java")
-    mapping("java", "JAVADOC_STYLE")
-
-    encoding = "UTF-8"
-
-    ext {
-        set("year", 2024)
-    }
-}
-
 val javaComponent: SoftwareComponent = components["java"]
 
 tasks {
@@ -74,14 +69,36 @@ tasks {
         dependsOn(named("shadowJar"))
     }
 
-    withType<JavaCompile> {
+    register<JavaCompile>("compilePaper") {
+        source = paper.java
+        classpath = paper.compileClasspath
+        destinationDirectory.set(layout.buildDirectory.dir("classes/java/paper"))
         options.encoding = "UTF-8"
         options.release = 8
     }
 
-    withType<Javadoc> {
+    val plainJar by registering(Jar::class) {
+        dependsOn("compilePaper")
+
+        archiveClassifier.set("plain")
+        from(sourceSets.main.get().output)
+        from(paper.output)
+    }
+
+    val combinedSourcesJar by registering(Jar::class) {
+        archiveClassifier.set("sources")
+        from(sourceSets.main.get().allSource)
+        from(paper.allSource)
+
+        duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+    }
+
+    val combinedJavadoc by registering(Javadoc::class) {
         isFailOnError = false
 
+        source = sourceSets.main.get().allJava + paper.allJava
+        classpath = sourceSets.main.get().compileClasspath + paper.compileClasspath
+
         with(options as StandardJavadocDocletOptions) {
             addStringOption("Xdoclint:none", "-quiet")
             addStringOption("encoding", "UTF-8")
@@ -89,18 +106,41 @@ tasks {
         }
     }
 
+    val combinedJavadocJar by registering(Jar::class) {
+        archiveClassifier.set("javadoc")
+        dependsOn(combinedJavadoc)
+        from(combinedJavadoc.get().destinationDir)
+    }
+
+    withType<JavaCompile> {
+        options.encoding = "UTF-8"
+        options.release = 8
+    }
+
     withType<ShadowJar> {
+        configurations = listOf(project.configurations.runtimeClasspath.get())
+
+        from(sourceSets.main.get().output)
+
         archiveClassifier.set("")
 
         relocate("org.bstats", "me.clip.placeholderapi.metrics")
-//        relocate("net.kyori", "me.clip.placeholderapi.libs.kyori") {
+        relocate("net.kyori", "me.clip.placeholderapi.libs.kyori")
-//            exclude("me/clip/placeholderapi/PAPIComponents.java")
-//            exclude("me/clip/placeholderapi/commands/TestCommand.java")
-//        }
-
-        destinationDirectory = file("server/1.21/plugins/")
 
         exclude("META-INF/versions/**")
+
+        dependsOn("compilePaper")
+
+        doLast {
+            val paperDir = layout.buildDirectory.dir("classes/java/paper").get().asFile
+            val jarFile = archiveFile.get().asFile
+
+            ant.invokeMethod("zip", mapOf(
+                "destfile" to jarFile,
+                "update" to "true",
+                "basedir" to paperDir
+            ))
+        }
     }
 
     test {
@@ -111,7 +151,19 @@ tasks {
         publications {
             create<MavenPublication>("maven") {
                 artifactId = "placeholderapi"
-                from(javaComponent)
+
+                artifact(plainJar) {
+                    builtBy(plainJar)
+                    classifier = ""
+                }
+
+                artifact(combinedSourcesJar) {
+                    builtBy(combinedSourcesJar)
+                }
+
+                artifact(combinedJavadocJar) {
+                    builtBy(combinedJavadocJar)
+                }
             }
         }
 
@@ -138,4 +190,4 @@ configurations {
     testImplementation {
         extendsFrom(compileOnly.get())
     }
-}
+}

config/headers/jsonmessage.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2018-2024 Peter Blood
+Copyright (c) 2018-2026 Peter Blood
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

settings.gradle.kts

@@ -1 +1 @@
-rootProject.name = "PlaceholderAPI"
+rootProject.name = "PlaceholderAPI"

src/main/java/me/clip/placeholderapi/PAPIComponents.java

@@ -1,121 +0,0 @@
-package me.clip.placeholderapi;
-
-import me.clip.placeholderapi.expansion.PlaceholderExpansion;
-import me.clip.placeholderapi.expansion.Relational;
-import me.clip.placeholderapi.replacer.ExactReplacer;
-import me.clip.placeholderapi.replacer.Replacer;
-import net.kyori.adventure.text.Component;
-import org.bukkit.OfflinePlayer;
-import org.bukkit.entity.Player;
-import org.checkerframework.checker.units.qual.N;
-import org.jetbrains.annotations.NotNull;
-
-import java.util.List;
-import java.util.Locale;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
-import java.util.stream.Collectors;
-
-public final class PAPIComponents {
-    private static final Replacer EXACT_REPLACER = new ExactReplacer();
-
-    @NotNull
-    public static Component setPlaceholders(final OfflinePlayer player, @NotNull final Component component) {
-        // TODO: explore a custom TextReplacementRenderer which doesn't use regex for performance benefits i.e. merge CharsReplacer with kyori TextReplacementRenderer
-        return component.replaceText(config -> config.match(PlaceholderAPI.PLACEHOLDER_PATTERN).replacement((result, builder) ->
-                builder.content(EXACT_REPLACER.apply(result.group(), player, PlaceholderAPIPlugin.getInstance().getLocalExpansionManager()::getExpansion))));
-    }
-
-    @NotNull
-    public static List<Component> setPlaceholders(final OfflinePlayer player, @NotNull final List<Component> components) {
-        return components.stream().map(component -> setPlaceholders(player, component)).collect(Collectors.toList());
-    }
-
-    @NotNull
-    public static Component setPlaceholders(final Player player, @NotNull final Component component) {
-        return setPlaceholders((OfflinePlayer) player, component);
-    }
-
-    @NotNull
-    public static List<Component> setPlaceholders(final Player player, @NotNull final List<Component> components) {
-        return setPlaceholders((OfflinePlayer) player, components);
-    }
-
-    @NotNull
-    public static Component setBracketPlaceholders(final OfflinePlayer player, @NotNull final Component component) {
-        return component.replaceText(config -> config.match(PlaceholderAPI.BRACKET_PLACEHOLDER_PATTERN).replacement((result, builder) ->
-                builder.content(EXACT_REPLACER.apply(result.group(), player, PlaceholderAPIPlugin.getInstance().getLocalExpansionManager()::getExpansion))));
-    }
-
-    @NotNull
-    public static List<Component> setBracketPlaceholders(final OfflinePlayer player, @NotNull final List<Component> components) {
-        return components.stream().map(component -> setBracketPlaceholders(player, component)).collect(Collectors.toList());
-    }
-
-    @NotNull
-    public static Component setBracketPlaceholders(final Player player, @NotNull final Component component) {
-        return setBracketPlaceholders((OfflinePlayer) player, component);
-    }
-
-    @NotNull
-    public static List<Component> setBracketPlaceholders(final Player player, @NotNull final List<Component> components) {
-        return setBracketPlaceholders((OfflinePlayer) player, components);
-    }
-
-//  public static Component setRelationalPlaceholders(Player one, Player two, Component component) {
-//    return component.replaceText(config -> config.match(PlaceholderAPI.RELATIONAL_PLACEHOLDER_PATTERN).replacement((result, builder) -> {
-//
-//      final String format = result.group(2);
-//      final int index = format.indexOf("_");
-//
-//      if (index <= 0 || index >= format.length()) {
-//        continue;
-//      }
-//
-//      String identifier = format.substring(0, index).toLowerCase(Locale.ROOT);
-//      String params = format.substring(index + 1);
-//      final PlaceholderExpansion expansion = PlaceholderAPIPlugin.getInstance()
-//              .getLocalExpansionManager().getExpansion(identifier);
-//
-//      if (!(expansion instanceof Relational)) {
-//        continue;
-//      }
-//
-//      final String value = ((Relational) expansion).onPlaceholderRequest(one, two, params);
-//
-//      if (value != null) {
-//        text = text.replaceAll(Pattern.quote(matcher.group()), Matcher.quoteReplacement(value));
-//      }
-//
-//
-//    }));
-//
-//    final Matcher matcher = PlaceholderAPI.RELATIONAL_PLACEHOLDER_PATTERN.matcher(text);
-//
-//    while (matcher.find()) {
-//      final String format = matcher.group(2);
-//      final int index = format.indexOf("_");
-//
-//      if (index <= 0 || index >= format.length()) {
-//        continue;
-//      }
-//
-//      String identifier = format.substring(0, index).toLowerCase(Locale.ROOT);
-//      String params = format.substring(index + 1);
-//      final PlaceholderExpansion expansion = PlaceholderAPIPlugin.getInstance()
-//              .getLocalExpansionManager().getExpansion(identifier);
-//
-//      if (!(expansion instanceof Relational)) {
-//        continue;
-//      }
-//
-//      final String value = ((Relational) expansion).onPlaceholderRequest(one, two, params);
-//
-//      if (value != null) {
-//        text = text.replaceAll(Pattern.quote(matcher.group()), Matcher.quoteReplacement(value));
-//      }
-//    }
-//
-//    return text;
-//  }
-}

src/main/java/me/clip/placeholderapi/PlaceholderAPI.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -21,6 +21,7 @@
 package me.clip.placeholderapi;
 
 import com.google.common.collect.ImmutableSet;
+
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
@@ -28,13 +29,13 @@ import java.util.Set;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
+
 import me.clip.placeholderapi.expansion.PlaceholderExpansion;
 import me.clip.placeholderapi.expansion.Relational;
 import me.clip.placeholderapi.expansion.manager.LocalExpansionManager;
 import me.clip.placeholderapi.replacer.CharsReplacer;
 import me.clip.placeholderapi.replacer.Replacer;
 import me.clip.placeholderapi.replacer.Replacer.Closure;
-import me.clip.placeholderapi.replacer.ExactReplacer;
 import me.clip.placeholderapi.util.Msg;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.entity.Player;
@@ -52,7 +53,6 @@ public final class PlaceholderAPI {
     static final Pattern RELATIONAL_PLACEHOLDER_PATTERN = Pattern
             .compile("[%](rel_)([^%]+)[%]");
 
-    private static final Replacer TEST = new ExactReplacer();
 
     private PlaceholderAPI() {
     }
@@ -64,7 +64,7 @@ public final class PlaceholderAPI {
      * <br>The pattern of a valid placeholder is {@literal %<identifier>_<params>%}.
      *
      * @param player Player to parse the placeholders against
-     * @param text Text to set the placeholder values in
+     * @param text   Text to set the placeholder values in
      * @return String containing all translated placeholders
      */
     @NotNull
@@ -79,7 +79,7 @@ public final class PlaceholderAPI {
      * <br>The pattern of a valid placeholder is {@literal %<identifier>_<params>%}.
      *
      * @param player Player to parse the placeholders against
-     * @param text List of Strings to set the placeholder values in
+     * @param text   List of Strings to set the placeholder values in
      * @return String containing all translated placeholders
      */
     @NotNull
@@ -93,7 +93,7 @@ public final class PlaceholderAPI {
      * <br>The pattern of a valid placeholder is {@literal %<identifier>_<params>%}.
      *
      * @param player Player to parse the placeholders against
-     * @param text Text to set the placeholder values in
+     * @param text   Text to set the placeholder values in
      * @return String containing all translated placeholders
      */
     @NotNull
@@ -106,7 +106,7 @@ public final class PlaceholderAPI {
      * <br>The pattern of a valid placeholder is {@literal %<identifier>_<params>%}.
      *
      * @param player Player to parse the placeholders against
-     * @param text List of Strings to set the placeholder values in
+     * @param text   List of Strings to set the placeholder values in
      * @return String containing all translated placeholders
      */
     @NotNull
@@ -119,7 +119,7 @@ public final class PlaceholderAPI {
      * <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
      *
      * @param player Player to parse the placeholders against
-     * @param text Text to set the placeholder values in
+     * @param text   Text to set the placeholder values in
      * @return String containing all translated placeholders
      */
     @NotNull
@@ -134,7 +134,7 @@ public final class PlaceholderAPI {
      * <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
      *
      * @param player Player to parse the placeholders against
-     * @param text List of Strings to set the placeholder values in
+     * @param text   List of Strings to set the placeholder values in
      * @return String containing all translated placeholders
      */
     @NotNull
@@ -149,7 +149,7 @@ public final class PlaceholderAPI {
      * <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
      *
      * @param player Player to parse the placeholders against
-     * @param text Text to set the placeholder values in
+     * @param text   Text to set the placeholder values in
      * @return String containing all translated placeholders
      */
     @NotNull
@@ -162,7 +162,7 @@ public final class PlaceholderAPI {
      * <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
      *
      * @param player Player to parse the placeholders against
-     * @param text List of Strings to set the placeholder values in
+     * @param text   List of Strings to set the placeholder values in
      * @return String containing all translated placeholders
      */
     @NotNull
@@ -174,8 +174,8 @@ public final class PlaceholderAPI {
      * set relational placeholders in the text specified placeholders are matched with the pattern
      * {@literal %<rel_(identifier)_(params)>%} when set with this method
      *
-     * @param one First player to compare
+     * @param one  First player to compare
-     * @param two Second player to compare
+     * @param two  Second player to compare
      * @param text Text to parse the placeholders in
      * @return The text containing the parsed relational placeholders
      */
@@ -213,8 +213,8 @@ public final class PlaceholderAPI {
      * Translate placeholders in the provided List based on the relation of the two provided players.
      * <br>The pattern of a valid placeholder is {@literal %rel_<identifier>_<param>%}.
      *
-     * @param one Player to compare
+     * @param one  Player to compare
-     * @param two Player to compare
+     * @param two  Player to compare
      * @param text text to parse the placeholder values to
      * @return The text containing the parsed relational placeholders
      */
@@ -298,24 +298,21 @@ public final class PlaceholderAPI {
 
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
-    public static boolean registerExpansion(PlaceholderExpansion expansion)
+    public static boolean registerExpansion(PlaceholderExpansion expansion) {
-    {
         return expansion.register();
     }
 
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
-    public static boolean unregisterExpansion(PlaceholderExpansion expansion)
+    public static boolean unregisterExpansion(PlaceholderExpansion expansion) {
-    {
         return expansion.unregister();
     }
 
     /**
      * Get map of registered placeholders
      *
-     * @deprecated Use {@link LocalExpansionManager#getExpansions()} instead.
-     *
      * @return Map of registered placeholders
+     * @deprecated Use {@link LocalExpansionManager#getExpansions()} instead.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -326,12 +323,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Please use {@link PlaceholderExpansion} to
+     * @param plugin          The Plugin to register with this {@link PlaceholderHook}
-     * register placeholders instead
-     *
-     * @param plugin The Plugin to register with this {@link PlaceholderHook}
      * @param placeholderHook The {@link PlaceholderHook} to register
      * @return always false
+     * @deprecated Please use {@link PlaceholderExpansion} to
+     * register placeholders instead
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -343,12 +339,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Please use {@link PlaceholderExpansion} to
+     * @param identifier      The identifier to use for the {@link PlaceholderHook}
-     * register placeholders instead
-     *
-     * @param identifier The identifier to use for the {@link PlaceholderHook}
      * @param placeholderHook The {@link PlaceholderHook} to register
      * @return always false
+     * @deprecated Please use {@link PlaceholderExpansion} to
+     * register placeholders instead
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -360,11 +355,10 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Please use {@link PlaceholderExpansion} to
-     * unregister placeholders instead
-     *
      * @param plugin The plugin to unregister
      * @return always false
+     * @deprecated Please use {@link PlaceholderExpansion} to
+     * unregister placeholders instead
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -376,11 +370,10 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Please use {@link PlaceholderExpansion} to
-     * unregister placeholders instead
-     *
      * @param identifier The identifier to unregister
      * @return always false
+     * @deprecated Please use {@link PlaceholderExpansion} to
+     * unregister placeholders instead
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -392,9 +385,8 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Will be removed in a future release.
-     *
      * @return Set of registered identifiers
+     * @deprecated Will be removed in a future release.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -403,9 +395,8 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Will be removed in a future release.
-     *
      * @return always null
+     * @deprecated Will be removed in a future release.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -414,13 +405,12 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Please use {@link #setPlaceholders(OfflinePlayer, String)} instead
+     * @param player   The offline player to parse the placeholders against
-     *
+     * @param text     The text to parse
-     * @param player The offline player to parse the placeholders against
+     * @param pattern  The Pattern to use
-     * @param text The text to parse
-     * @param pattern The Pattern to use
      * @param colorize If PlaceholderAPI should also parse color codes
      * @return String with the parsed placeholders
+     * @deprecated Please use {@link #setPlaceholders(OfflinePlayer, String)} instead
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -430,13 +420,12 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Please use {@link #setPlaceholders(OfflinePlayer, List)} instead
+     * @param player   The offline player to parse the placeholders against
-     *
+     * @param text     The List of text to parse
-     * @param player The offline player to parse the placeholders against
+     * @param pattern  The Pattern to use
-     * @param text The List of text to parse
-     * @param pattern The Pattern to use
      * @param colorize If PlaceholderAPI should also parse color codes
      * @return String with the parsed placeholders
+     * @deprecated Please use {@link #setPlaceholders(OfflinePlayer, List)} instead
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -446,12 +435,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
+     * @param player   The offline player to parse the placeholders against
-     *
+     * @param text     The List of text to parse
-     * @param player The offline player to parse the placeholders against
-     * @param text The List of text to parse
      * @param colorize If PlaceholderAPI should also parse color codes
      * @return String with the parsed placeholders
+     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -461,12 +449,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
+     * @param player  The offline player to parse the placeholders against
-     *
+     * @param text    The List of text to parse
-     * @param player The offline player to parse the placeholders against
-     * @param text The List of text to parse
      * @param pattern The Pattern to use
      * @return String with the parsed placeholders
+     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -474,13 +461,13 @@ public final class PlaceholderAPI {
                                                Pattern pattern) {
         return setPlaceholders(player, text);
     }
+
     /**
-     * @deprecated Will be removed in a future release.
+     * @param player   The offline player to parse the placeholders against
-     *
+     * @param text     The text to parse
-     * @param player The offline player to parse the placeholders against
-     * @param text The text to parse
      * @param colorize If PlaceholderAPI should also parse color codes
      * @return String with the parsed placeholders
+     * @deprecated Will be removed in a future release.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -489,12 +476,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Will be removed in a future release.
+     * @param player   The offline player to parse the placeholders against
-     *
+     * @param text     The List of text to parse
-     * @param player The offline player to parse the placeholders against
-     * @param text The List of text to parse
      * @param colorize If PlaceholderAPI should also parse color codes
      * @return String with the parsed placeholders
+     * @deprecated Will be removed in a future release.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -503,12 +489,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
+     * @param player   The offline player to parse the placeholders against
-     *
+     * @param text     The text to parse
-     * @param player The offline player to parse the placeholders against
-     * @param text The text to parse
      * @param colorize If PlaceholderAPI should also parse color codes
      * @return String with the parsed placeholders
+     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -517,12 +502,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
+     * @param player  The offline player to parse the placeholders against
-     *
+     * @param text    The text to parse
-     * @param player The offline player to parse the placeholders against
-     * @param text The text to parse
      * @param pattern The Pattern to use
      * @return String with the parsed placeholders
+     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -531,12 +515,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
+     * @param player   The offline player to parse the placeholders against
-     *
+     * @param text     The List of text to parse
-     * @param player The offline player to parse the placeholders against
-     * @param text The List of text to parse
      * @param colorize If PlaceholderAPI should also parse color codes
      * @return String with the parsed placeholders
+     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -546,12 +529,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
+     * @param player   The offline player to parse the placeholders against
-     *
+     * @param text     The text to parse
-     * @param player The offline player to parse the placeholders against
-     * @param text The text to parse
      * @param colorize If PlaceholderAPI should also parse color codes
      * @return String with the parsed placeholders
+     * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -560,12 +542,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Will be removed in a future release.
+     * @param player   The offline player to parse the placeholders against
-     *
+     * @param text     The text to parse
-     * @param player The offline player to parse the placeholders against
-     * @param text The text to parse
      * @param colorize If PlaceholderAPI should also parse color codes
      * @return String with the parsed placeholders
+     * @deprecated Will be removed in a future release.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -574,12 +555,11 @@ public final class PlaceholderAPI {
     }
 
     /**
-     * @deprecated Will be removed in a future release.
+     * @param player   The offline player to parse the placeholders against
-     *
+     * @param text     The List of text to parse
-     * @param player The offline player to parse the placeholders against
-     * @param text The List of text to parse
      * @param colorize If PlaceholderAPI should also parse color codes
      * @return String with the parsed placeholders
+     * @deprecated Will be removed in a future release.
      */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
@@ -592,9 +572,9 @@ public final class PlaceholderAPI {
      * set relational placeholders in the text specified placeholders are matched with the pattern
      * {@literal %<rel_(identifier)_(params)>%} when set with this method
      *
-     * @param one Player to compare
+     * @param one      Player to compare
-     * @param two Player to compare
+     * @param two      Player to compare
-     * @param text Text to parse the placeholders in
+     * @param text     Text to parse the placeholders in
      * @param colorize If color codes ({@literal &[0-1a-fk-o]}) should be translated
      * @return The text containing the parsed relational placeholders
      * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
@@ -610,9 +590,9 @@ public final class PlaceholderAPI {
      * Translate placeholders in the provided list based on the relation of the two provided players.
      * <br>The pattern of a valid placeholder is {@literal %rel_<identifier>_<params>%}.
      *
-     * @param one First player to compare
+     * @param one      First player to compare
-     * @param two Second player to compare
+     * @param two      Second player to compare
-     * @param text Text to parse the placeholders in
+     * @param text     Text to parse the placeholders in
      * @param colorize If color codes ({@literal &[0-1a-fk-o]}) should be translated
      * @return The text containing the parsed relational placeholders
      * @deprecated Use {@link #setRelationalPlaceholders(Player, Player, List)} instead.

src/main/java/me/clip/placeholderapi/PlaceholderAPIPlugin.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -23,8 +23,8 @@ package me.clip.placeholderapi;
 import java.text.SimpleDateFormat;
 import java.util.HashMap;
 import java.util.Map;
+
 import me.clip.placeholderapi.commands.PlaceholderCommandRouter;
-import me.clip.placeholderapi.commands.TestCommand;
 import me.clip.placeholderapi.configuration.PlaceholderAPIConfig;
 import me.clip.placeholderapi.expansion.PlaceholderExpansion;
 import me.clip.placeholderapi.expansion.Version;
@@ -44,6 +44,7 @@ import org.bukkit.Bukkit;
 import org.bukkit.command.CommandSender;
 import org.bukkit.command.PluginCommand;
 import org.bukkit.event.HandlerList;
+import org.bukkit.event.Listener;
 import org.bukkit.plugin.java.JavaPlugin;
 import org.jetbrains.annotations.NotNull;
 
@@ -93,9 +94,8 @@ public final class PlaceholderAPIPlugin extends JavaPlugin {
     private final TaskScheduler scheduler = UniversalScheduler.getScheduler(this);
 
     private BukkitAudiences adventure;
+    private boolean safetyCheck = false;
 
-  private BukkitAudiences adventure;
-  private boolean safetyCheck = false;
 
     /**
      * Gets the static instance of the main class for PlaceholderAPI. This class is not the actual API
@@ -153,30 +153,28 @@ public final class PlaceholderAPIPlugin extends JavaPlugin {
 
     @Override
     public void onLoad() {
+        saveDefaultConfig();
+
+        safetyCheck = new ExpansionSafetyCheck(this).runChecks();
+
+        if (safetyCheck) {
+            return;
+        }
+
         instance = this;
-
-  @Override
-  public void onLoad() {
-    saveDefaultConfig();
-
-    safetyCheck = new ExpansionSafetyCheck(this).runChecks();
-
-    if (safetyCheck) {
-      return;
     }
 
-    instance = this;
+    @Override
-  }
+    public void onEnable() {
+        if (safetyCheck) {
+            return;
+        }
 
-  @Override
+        setupCommand();
-  public void onEnable() {
+        setupMetrics();
-    if (safetyCheck) {
+        setupExpansions();
-      return;
-    }
 
-    setupCommand();
+        adventure = BukkitAudiences.create(this);
-    setupMetrics();
-    setupExpansions();
 
         if (config.isCloudEnabled()) {
             getCloudExpansionManager().load();
@@ -189,17 +187,14 @@ public final class PlaceholderAPIPlugin extends JavaPlugin {
 
     @Override
     public void onDisable() {
+        if (safetyCheck) {
+            return;
+        }
+
         getCloudExpansionManager().kill();
         getLocalExpansionManager().kill();
 
-  @Override
+        HandlerList.unregisterAll(this);
-  public void onDisable() {
-    if (safetyCheck) {
-      return;
-    }
-
-    getCloudExpansionManager().kill();
-    getLocalExpansionManager().kill();
 
         scheduler.cancelTasks(this);
 
@@ -235,7 +230,7 @@ public final class PlaceholderAPIPlugin extends JavaPlugin {
 
     @NotNull
     public BukkitAudiences getAdventure() {
-        if(adventure == null) {
+        if (adventure == null) {
             throw new IllegalStateException("Tried to access Adventure when the plugin was disabled!");
         }
 

src/main/java/me/clip/placeholderapi/PlaceholderHook.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -20,26 +20,23 @@
 
 package me.clip.placeholderapi;
 
-import net.kyori.adventure.text.Component;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.entity.Player;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-import java.util.Optional;
-
 public abstract class PlaceholderHook {
-  @Nullable
+    @Nullable
-  public String onRequest(final OfflinePlayer player, @NotNull final String params) {
+    public String onRequest(final OfflinePlayer player, @NotNull final String params) {
-    if (player != null && player.isOnline()) {
+        if (player != null && player.isOnline()) {
-      return onPlaceholderRequest(player.getPlayer(), params);
+            return onPlaceholderRequest(player.getPlayer(), params);
+        }
+
+        return onPlaceholderRequest(null, params);
     }
 
-    return onPlaceholderRequest(null, params);
+    @Nullable
-  }
+    public String onPlaceholderRequest(final Player player, @NotNull final String params) {
-
+        return null;
-  @Nullable
+    }
-  public String onPlaceholderRequest(final Player player, @NotNull final String params) {
-    return null;
-  }
 }

src/main/java/me/clip/placeholderapi/commands/PlaceholderCommand.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/PlaceholderCommandRouter.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -32,6 +32,7 @@ import java.util.Locale;
 import java.util.Map;
 import java.util.stream.Stream;
 
+import com.google.common.collect.Lists;
 import me.clip.placeholderapi.PlaceholderAPIPlugin;
 import me.clip.placeholderapi.commands.impl.cloud.CommandECloud;
 import me.clip.placeholderapi.commands.impl.local.CommandDump;
@@ -119,14 +120,18 @@ public final class PlaceholderCommandRouter implements CommandExecutor, TabCompl
     }
 
     @Override
-    public List<String> onTabComplete(@NotNull final CommandSender sender,
+    public List<String> onTabComplete(@NotNull final CommandSender sender, @NotNull final Command command,
-                                      @NotNull final Command command, @NotNull final String alias, @NotNull final String[] args) {
+                                      @NotNull final String alias, @NotNull final String[] args) {
         final List<String> suggestions = new ArrayList<>();
 
         if (args.length > 1) {
             final PlaceholderCommand target = this.commands.get(args[0].toLowerCase(Locale.ROOT));
 
             if (target != null) {
+                if (target.getPermission() != null && !target.getPermission().isEmpty() && !sender.hasPermission(target.getPermission())) {
+                    return suggestions;
+                }
+
                 target.complete(plugin, sender, args[0].toLowerCase(Locale.ROOT),
                         Arrays.asList(Arrays.copyOfRange(args, 1, args.length)), suggestions);
             }

src/main/java/me/clip/placeholderapi/commands/TestCommand.java

@@ -1,57 +0,0 @@
-package me.clip.placeholderapi.commands;
-
-import io.papermc.paper.command.brigadier.BasicCommand;
-import io.papermc.paper.command.brigadier.CommandSourceStack;
-import me.clip.placeholderapi.PAPIComponents;
-import me.clip.placeholderapi.PlaceholderAPI;
-import net.kyori.adventure.text.Component;
-import net.kyori.adventure.text.event.HoverEvent;
-import net.kyori.adventure.text.event.HoverEventSource;
-import net.kyori.adventure.text.format.TextColor;
-import net.kyori.adventure.text.minimessage.MiniMessage;
-import org.bukkit.OfflinePlayer;
-
-public class TestCommand implements BasicCommand {
-    private static final MiniMessage MINI = MiniMessage.miniMessage();
-
-    @Override
-    public void execute(final CommandSourceStack commandSourceStack, final String[] strings) {
-//        final Component component = Component.text("Woo! Test: %player_name%").color(TextColor.color(50, 168, 82)).hoverEvent(HoverEvent.showText(Component.text("OMG %player_gamemode%")));
-        final Component component = Component.text("Woo! Test: %player_name%");
-
-        String ser = MINI.serialize(component);
-        System.out.println(ser);
-
-        commandSourceStack.getSender().sendMessage(
-                PAPIComponents.setPlaceholders((OfflinePlayer) commandSourceStack.getSender(), component)
-        );
-
-        long tmp = System.currentTimeMillis();
-        for (int i = 0; i < 100000; ++i) {
-            PAPIComponents.setPlaceholders((OfflinePlayer) commandSourceStack.getSender(), component);
-        }
-        commandSourceStack.getSender().sendMessage(String.valueOf(System.currentTimeMillis() - tmp));
-
-        tmp = System.currentTimeMillis();
-        for (int i = 0; i < 100000; ++i) {
-            PlaceholderAPI.setPlaceholders((OfflinePlayer) commandSourceStack.getSender(), "Woo! Test: %player_name%");
-        }
-        commandSourceStack.getSender().sendMessage(String.valueOf(System.currentTimeMillis() - tmp));
-
-        tmp = System.currentTimeMillis();
-        for (int i = 0; i < 100000; ++i) {
-            final String serr = MINI.serialize(component);
-            final String repl = PlaceholderAPI.setPlaceholders((OfflinePlayer) commandSourceStack.getSender(), serr);
-            MINI.deserialize(repl);
-        }
-        commandSourceStack.getSender().sendMessage(String.valueOf(System.currentTimeMillis() - tmp));
-
-
-        Component.text()
-                .append(Component.text().content("yes ").color(TextColor.color(50,50,50)))
-                .append(Component.text("%player_name%"))
-                .append(Component.text(" omg").color(TextColor.color(200,200,200)));
-
-
-    }
-}

src/main/java/me/clip/placeholderapi/commands/impl/cloud/CommandECloud.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -118,6 +118,11 @@ public final class CommandECloud extends PlaceholderCommand {
             return;
         }
 
+        if (!target.getLabel().equalsIgnoreCase("refresh") && plugin.getCloudExpansionManager().isEmpty()) {
+            Msg.msg(sender, "&cThere is no available data from the eCloud. Please try running &f/papi ecloud refresh&c. If this does not resolve the issue, the eCloud may be blocked by your firewall, server host, or service provider.\n&r\n&cMore information: &fhttps://placeholderapi.com/ecloud-blocked");
+            return;
+        }
+
         target.evaluate(plugin, sender, search, params.subList(1, params.size()));
     }
 

src/main/java/me/clip/placeholderapi/commands/impl/cloud/CommandECloudClear.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/cloud/CommandECloudDownload.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -65,42 +65,14 @@ public final class CommandECloudDownload extends PlaceholderCommand {
             return;
         }
 
-    final CloudExpansion.Version version;
+        final CloudExpansion expansion = plugin.getCloudExpansionManager()
-    if (params.size() < 2) {
+                .findCloudExpansionByName(params.get(0)).orElse(null);
-      version = expansion.getVersion(expansion.getLatestVersion());
+        if (expansion == null) {
-      if (version == null) {
-        Msg.msg(sender,
-            "&cCould not find latest version for expansion.");
-        return;
-      }
-    } else {
-      version = expansion.getVersion(params.get(1));
-      if (version == null) {
-        Msg.msg(sender,
-            "&cCould not find specified version: &f" + params.get(1),
-            "&7Available versions: &f" + expansion.getAvailableVersions());
-        return;
-      }
-    }
-
-    if (!version.isVerified()) {
-      Msg.msg(sender, "&cThe expansion '&f" + params.get(0) + "&c' is not verified and can only be downloaded manually from &fhttps://ecloud.placeholderapi.com");
-      return;
-    }
-
-    plugin.getCloudExpansionManager().downloadExpansion(expansion, version)
-        .whenComplete((file, exception) -> {
-          if (exception != null) {
             Msg.msg(sender,
                     "&cFailed to find an expansion named: &f" + params.get(0));
             return;
         }
 
-        if (!expansion.isVerified()) {
-            Msg.msg(sender, "&cThe expansion '&f" + params.get(0) + "&c' is not verified and can only be downloaded manually from &fhttps://placeholderapi.com/ecloud");
-            return;
-        }
-
         final CloudExpansion.Version version;
         if (params.size() < 2) {
             version = expansion.getVersion(expansion.getLatestVersion());
@@ -119,6 +91,11 @@ public final class CommandECloudDownload extends PlaceholderCommand {
             }
         }
 
+        if (!version.isVerified()) {
+            Msg.msg(sender, "&cThe expansion '&f" + params.get(0) + "&c' is not verified and can only be downloaded manually from &fhttps://ecloud.placeholderapi.com");
+            return;
+        }
+
         plugin.getCloudExpansionManager().downloadExpansion(expansion, version)
                 .whenComplete((file, exception) -> {
                     if (exception != null) {

src/main/java/me/clip/placeholderapi/commands/impl/cloud/CommandECloudExpansionInfo.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -56,54 +56,45 @@ public final class CommandECloudExpansionInfo extends PlaceholderCommand {
             return;
         }
 
-    builder.append("&bExpansion: &f")
+        final StringBuilder builder = new StringBuilder();
-        .append(expansion.shouldUpdate() ? "&e" : "&a")
-        .append(expansion.getName())
-        .append('\n')
-        .append("&bAuthor: &f")
-        .append(expansion.getAuthor())
-        .append('\n');
 
-    if (params.size() < 2) {
+        builder.append("&bExpansion: &f")
-      builder.append("&bLatest Version: &f")
+                .append(expansion.shouldUpdate() ? "&e" : "&a")
-          .append(expansion.getLatestVersion())
+                .append(expansion.getName())
-          .append('\n')
+                .append('\n')
-          .append("&bReleased: &f")
+                .append("&bAuthor: &f")
-          .append(expansion.getTimeSinceLastUpdate())
+                .append(expansion.getAuthor())
-          .append(" ago")
+                .append('\n');
-          .append('\n')
-          .append("&bVerified: ")
-          .append(expansion.getVersion().isVerified() ? "&a&l✔" : "&c&l❌")
-          .append('\n')
-          .append("&bRelease Notes: &f")
-          .append(expansion.getVersion().getReleaseNotes())
-          .append('\n');
-    } else {
-      final CloudExpansion.Version version = expansion.getVersion(params.get(1));
-      if (version == null) {
-        Msg.msg(sender,
-            "&cCould not find specified version: &f" + params.get(1),
-            "&aVersions: &f" + expansion.getAvailableVersions());
-        return;
-      }
 
-      builder.append("&bVersion: &f")
+        if (params.size() < 2) {
-          .append(version.getVersion())
+            builder.append("&bLatest Version: &f")
-          .append('\n')
+                    .append(expansion.getLatestVersion())
-          .append("&bVerified: ")
+                    .append('\n')
-          .append(version.isVerified() ? "&a&l✔" : "&c&l❌")
+                    .append("&bReleased: &f")
-          .append('\n')
+                    .append(expansion.getTimeSinceLastUpdate())
-          .append("&bRelease Notes: &f")
+                    .append(" ago")
-          .append(version.getReleaseNotes())
+                    .append('\n')
-          .append('\n')
+                    .append("&bVerified: ")
-          .append("&bDownload URL: &f")
+                    .append(expansion.getVersion().isVerified() ? "&a&l✔" : "&c&l❌")
-          .append(version.getUrl())
+                    .append('\n')
-          .append('\n');
+                    .append("&bRelease Notes: &f")
-    }
+                    .append(expansion.getVersion().getReleaseNotes())
+                    .append('\n');
+        } else {
+            final CloudExpansion.Version version = expansion.getVersion(params.get(1));
+            if (version == null) {
+                Msg.msg(sender,
+                        "&cCould not find specified version: &f" + params.get(1),
+                        "&aVersions: &f" + expansion.getAvailableVersions());
+                return;
+            }
 
             builder.append("&bVersion: &f")
                     .append(version.getVersion())
                     .append('\n')
+                    .append("&bVerified: ")
+                    .append(version.isVerified() ? "&a&l✔" : "&c&l❌")
+                    .append('\n')
                     .append("&bRelease Notes: &f")
                     .append(version.getReleaseNotes())
                     .append('\n')

src/main/java/me/clip/placeholderapi/commands/impl/cloud/CommandECloudExpansionList.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -58,24 +58,24 @@ public final class CommandECloudExpansionList extends PlaceholderCommand {
 
     private static final int PAGE_SIZE = 10;
 
-  @NotNull
+    @NotNull
-  private static final Function<CloudExpansion, Object> EXPANSION_NAME =
+    private static final Function<CloudExpansion, Object> EXPANSION_NAME =
-      expansion -> (expansion.shouldUpdate() ? "&6" : expansion.hasExpansion() ? "&a" : "&7")
+            expansion -> (expansion.shouldUpdate() ? "&6" : expansion.hasExpansion() ? "&a" : "&7")
-          + expansion.getName();
+                    + expansion.getName();
-  @NotNull
+    @NotNull
-  private static final Function<CloudExpansion, Object> EXPANSION_AUTHOR =
+    private static final Function<CloudExpansion, Object> EXPANSION_AUTHOR =
-      expansion -> "&f" + expansion.getAuthor();
+            expansion -> "&f" + expansion.getAuthor();
-  @NotNull
+    @NotNull
-  private static final Function<CloudExpansion, Object> EXPANSION_VERIFIED =
+    private static final Function<CloudExpansion, Object> EXPANSION_VERIFIED =
-      expansion -> expansion.getVersion().isVerified() ? "&aY" : "&cN";
+            expansion -> expansion.getVersion().isVerified() ? "&aY" : "&cN";
-  @NotNull
+    @NotNull
-  private static final Function<CloudExpansion, Object> EXPANSION_LATEST_VERSION =
+    private static final Function<CloudExpansion, Object> EXPANSION_LATEST_VERSION =
-      expansion -> "&f" + expansion.getLatestVersion();
+            expansion -> "&f" + expansion.getLatestVersion();
-  @NotNull
+    @NotNull
-  private static final Function<CloudExpansion, Object> EXPANSION_CURRENT_VERSION =
+    private static final Function<CloudExpansion, Object> EXPANSION_CURRENT_VERSION =
-      expansion -> "&f" + PlaceholderAPIPlugin.getInstance().getLocalExpansionManager()
+            expansion -> "&f" + PlaceholderAPIPlugin.getInstance().getLocalExpansionManager()
-          .findExpansionByName(expansion.getName()).map(PlaceholderExpansion::getVersion)
+                    .findExpansionByName(expansion.getName()).map(PlaceholderExpansion::getVersion)
-          .orElse("Unknown");
+                    .orElse("Unknown");
 
 
     @Unmodifiable
@@ -170,19 +170,18 @@ public final class CommandECloudExpansionList extends PlaceholderCommand {
                     .append(newline()).append(newline())
                     .append(text("Author: ", AQUA)).append(text(expansion.getAuthor(), WHITE))
                     .append(newline())
-                    .append(text("Verified: ", AQUA)).append(text(expansion.isVerified() ? "✔" : "❌", expansion.isVerified() ? GREEN : RED, TextDecoration.BOLD))
+                    .append(text("Version: ", AQUA)).append(text(expansion.getVersion().getVersion(), WHITE))
+                    .append(newline())
+                    .append(text("Verified: ", AQUA)).append(text(expansion.getVersion().isVerified() ? "✔" : "❌", expansion.getVersion().isVerified() ? GREEN : RED, TextDecoration.BOLD))
                     .append(newline())
                     .append(text("Released: ", AQUA)).append(text(format.format(expansion.getLastUpdate()), WHITE))
                     .toBuilder();
 
-      final TextComponent.Builder hoverText = text("Click to download this expansion!", AQUA)
+            Optional.ofNullable(expansion.getDescription())
-              .append(newline()).append(newline())
+                    .filter(description -> !description.isEmpty())
-              .append(text("Author: ", AQUA)).append(text(expansion.getAuthor(), WHITE))
+                    .ifPresent(description -> hoverText.append(newline()).append(newline())
-              .append(newline())
+                            .append(text(description.replace("\r", "").trim(), WHITE))
-              .append(text("Verified: ", AQUA)).append(text(expansion.getVersion().isVerified() ? "✔" : "❌", expansion.getVersion().isVerified() ? GREEN : RED, TextDecoration.BOLD))
+                    );
-              .append(newline())
-              .append(text("Released: ", AQUA)).append(text(format.format(expansion.getLastUpdate()), WHITE))
-              .toBuilder();
 
             line.hoverEvent(HoverEvent.showText(hoverText.build()));
 

src/main/java/me/clip/placeholderapi/commands/impl/cloud/CommandECloudExpansionPlaceholders.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/cloud/CommandECloudRefresh.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/cloud/CommandECloudStatus.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/cloud/CommandECloudUpdate.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/local/CommandDump.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/local/CommandExpansionRegister.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/local/CommandExpansionUnregister.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/local/CommandHelp.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/local/CommandInfo.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/local/CommandList.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/local/CommandParse.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/commands/impl/local/CommandReload.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -35,13 +35,13 @@ public final class CommandReload extends PlaceholderCommand {
         super("reload");
     }
 
-  @Override
+    @Override
-  public void evaluate(@NotNull final PlaceholderAPIPlugin plugin,
+    public void evaluate(@NotNull final PlaceholderAPIPlugin plugin,
-      @NotNull final CommandSender sender, @NotNull final String alias,
+                         @NotNull final CommandSender sender, @NotNull final String alias,
-      @NotNull @Unmodifiable final List<String> params) {
+                         @NotNull @Unmodifiable final List<String> params) {
-    if (!new ExpansionSafetyCheck(plugin).runChecks()) {
+        if (!new ExpansionSafetyCheck(plugin).runChecks()) {
-      plugin.reloadConf(sender);
+            plugin.reloadConf(sender);
+        }
     }
-  }
 
 }

src/main/java/me/clip/placeholderapi/commands/impl/local/CommandVersion.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/configuration/ExpansionSort.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -21,27 +21,28 @@
 package me.clip.placeholderapi.configuration;
 
 import java.util.Comparator;
+
 import me.clip.placeholderapi.expansion.cloud.CloudExpansion;
 import org.jetbrains.annotations.NotNull;
 
 public enum ExpansionSort implements Comparator<CloudExpansion> {
 
-  NAME(Comparator.comparing(CloudExpansion::getName)),
+    NAME(Comparator.comparing(CloudExpansion::getName)),
-  AUTHOR(Comparator.comparing(CloudExpansion::getAuthor)),
+    AUTHOR(Comparator.comparing(CloudExpansion::getAuthor)),
-  LATEST(Comparator.comparing(CloudExpansion::getLastUpdate).reversed());
+    LATEST(Comparator.comparing(CloudExpansion::getLastUpdate).reversed());
 
 
-  @NotNull
+    @NotNull
-  private final Comparator<CloudExpansion> comparator;
+    private final Comparator<CloudExpansion> comparator;
 
-  ExpansionSort(@NotNull final Comparator<CloudExpansion> comparator) {
+    ExpansionSort(@NotNull final Comparator<CloudExpansion> comparator) {
-    this.comparator = comparator;
+        this.comparator = comparator;
-  }
+    }
 
 
-  @Override
+    @Override
-  public final int compare(final CloudExpansion expansion1, final CloudExpansion expansion2) {
+    public final int compare(final CloudExpansion expansion1, final CloudExpansion expansion2) {
-    return comparator.compare(expansion1, expansion2);
+        return comparator.compare(expansion1, expansion2);
-  }
+    }
 
 }

src/main/java/me/clip/placeholderapi/configuration/PlaceholderAPIConfig.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -21,73 +21,81 @@
 package me.clip.placeholderapi.configuration;
 
 import java.util.Optional;
+
 import me.clip.placeholderapi.PlaceholderAPIPlugin;
 import org.jetbrains.annotations.NotNull;
 
 public final class PlaceholderAPIConfig {
 
-  @NotNull
+    @NotNull
-  private final PlaceholderAPIPlugin plugin;
+    private final PlaceholderAPIPlugin plugin;
 
-  public PlaceholderAPIConfig(@NotNull final PlaceholderAPIPlugin plugin) {
+    public PlaceholderAPIConfig(@NotNull final PlaceholderAPIPlugin plugin) {
-    this.plugin = plugin;
+        this.plugin = plugin;
-  }
-
-
-  public boolean checkUpdates() {
-    return plugin.getConfig().getBoolean("check_updates");
-  }
-
-
-  public boolean isCloudEnabled() {
-    return plugin.getConfig().getBoolean("cloud_enabled");
-  }
-
-  public void setCloudEnabled(boolean state) {
-    plugin.getConfig().set("cloud_enabled", state);
-    plugin.saveConfig();
-  }
-
-
-  public boolean isDebugMode() {
-    return plugin.getConfig().getBoolean("debug", false);
-  }
-
-
-  public Optional<ExpansionSort> getExpansionSort() {
-    final String option = plugin.getConfig()
-        .getString("cloud_sorting", ExpansionSort.LATEST.name());
-
-    try {
-      //noinspection ConstantConditions (bad spigot annotation)
-      return Optional.of(ExpansionSort.valueOf(option.toUpperCase()));
-    } catch (final IllegalArgumentException ignored) {
-      return Optional.empty();
     }
-  }
 
 
-  @NotNull
+    public boolean checkUpdates() {
-  public String dateFormat() {
+        return plugin.getConfig().getBoolean("check_updates");
-    //noinspection ConstantConditions (bad spigot annotation)
+    }
-    return plugin.getConfig().getString("date_format", "MM/dd/yy HH:mm:ss");
-  }
 
 
-  @NotNull
+    public boolean isCloudEnabled() {
-  public String booleanTrue() {
+        return plugin.getConfig().getBoolean("cloud_enabled");
-    //noinspection ConstantConditions (bad spigot annotation)
+    }
-    return plugin.getConfig().getString("boolean.true", "true");
-  }
 
-  @NotNull
+    public void setCloudEnabled(boolean state) {
-  public String booleanFalse() {
+        plugin.getConfig().set("cloud_enabled", state);
-    //noinspection ConstantConditions (bad spigot annotation)
+        plugin.saveConfig();
-    return plugin.getConfig().getString("boolean.false", "false");
+    }
-  }
 
-  public boolean detectMaliciousExpansions() {
-    return plugin.getConfig().getBoolean("detect_malicious_expansions", true);
-  }
 
+    public boolean isDebugMode() {
+        return plugin.getConfig().getBoolean("debug", false);
+    }
+
+    public boolean useAdventureReplacer() {
+        return plugin.getConfig().getBoolean("use_adventure_provided_replacer", false);
+    }
+
+
+    public Optional<ExpansionSort> getExpansionSort() {
+        final String option = plugin.getConfig()
+                .getString("cloud_sorting", ExpansionSort.LATEST.name());
+
+        try {
+            //noinspection ConstantConditions (bad spigot annotation)
+            return Optional.of(ExpansionSort.valueOf(option.toUpperCase()));
+        } catch (final IllegalArgumentException ignored) {
+            return Optional.empty();
+        }
+    }
+
+
+    @NotNull
+    public String dateFormat() {
+        //noinspection ConstantConditions (bad spigot annotation)
+        return plugin.getConfig().getString("date_format", "MM/dd/yy HH:mm:ss");
+    }
+
+
+    @NotNull
+    public String booleanTrue() {
+        //noinspection ConstantConditions (bad spigot annotation)
+        return plugin.getConfig().getString("boolean.true", "true");
+    }
+
+    @NotNull
+    public String booleanFalse() {
+        //noinspection ConstantConditions (bad spigot annotation)
+        return plugin.getConfig().getString("boolean.false", "false");
+    }
+
+    public boolean useAdventureProvidedReplacer() {
+        return plugin.getConfig().getBoolean("use_adventure_provided_replacer", false);
+    }
+
+    public boolean detectMaliciousExpansions() {
+        return plugin.getConfig().getBoolean("detect_malicious_expansions", true);
+    }
 }

src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/events/ExpansionUnregisterEvent.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/events/ExpansionsLoadedEvent.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/events/PlaceholderHookUnloadEvent.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/exceptions/NoDefaultCommandException.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -22,8 +22,8 @@ package me.clip.placeholderapi.exceptions;
 
 public final class NoDefaultCommandException extends RuntimeException {
 
-  public NoDefaultCommandException(final String message) {
+    public NoDefaultCommandException(final String message) {
-    super(message);
+        super(message);
-  }
+    }
 }
 

src/main/java/me/clip/placeholderapi/expansion/Cacheable.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -24,15 +24,15 @@ package me.clip.placeholderapi.expansion;
  * Classes implementing this interface will have a {@link #clear() clear void} that is called
  * by PlaceholderAPI whenever the {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}
  * is unregistered.
- * 
+ *
  * <p>This allows you to execute things such as clearing internal caches, saving data to files, etc.
  *
  * @author Ryan McCarthy
  */
 public interface Cacheable {
 
-  /**
+    /**
-   * Called when the implementing class is unregistered from PlaceholderAPI
+     * Called when the implementing class is unregistered from PlaceholderAPI
-   */
+     */
-  void clear();
+    void clear();
 }

src/main/java/me/clip/placeholderapi/expansion/Cleanable.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -25,7 +25,7 @@ import org.bukkit.entity.Player;
 /**
  * Classes implementing this interface will have a {@link #cleanup(Player) cleanup void} that is
  * called by PlaceholderAPI whenever a Player leaves the server.
- * 
+ *
  * <p>This can be useful for cases where you keep data of the player in a cache or similar
  * and want to free up space whenever they leave.
  *
@@ -33,10 +33,10 @@ import org.bukkit.entity.Player;
  */
 public interface Cleanable {
 
-  /**
+    /**
-   * Called when a player leaves the server
+     * Called when a player leaves the server
-   *
+     *
-   * @param p (@link Player} who left the server
+     * @param p (@link Player} who left the server
-   */
+     */
-  void cleanup(Player p);
+    void cleanup(Player p);
 }

src/main/java/me/clip/placeholderapi/expansion/Configurable.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -26,32 +26,32 @@ import java.util.Map;
  * Implementing this interface allows {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansions}
  * to set a list of default configuration values through the {@link #getDefaults() getDefaults method}
  * that should be added to the config.yml of PlaceholderAPI.
- * 
+ *
  * <p>The entries will be added under {@code expansions} as their own section.
  * <h2>Example:</h2>
  * returning a Map with key {@code foo} and value {@code bar} will result in the following config entry:
- * 
+ *
  * <pre><code>
  * expansions:
  *   myexpansion:
  *     foo: "bar"
  * </code></pre>
- * 
+ *
  * <p><b>The configuration is set before the PlaceholderExpansion is registered!</b>
  *
  * @author Ryan McCarthy
  */
 public interface Configurable {
 
-  /**
+    /**
-   * The map returned by this method will be used to set config options in PlaceholderAPI's config.yml.
+     * The map returned by this method will be used to set config options in PlaceholderAPI's config.yml.
-   * 
+     *
-   * <p>The key and value pairs are set under a section named after your
+     * <p>The key and value pairs are set under a section named after your
-   * {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion} in the
+     * {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion} in the
-   * {@code expansions} section of the config.
+     * {@code expansions} section of the config.
-   *
+     *
-   * @return Map of config path / values which need to be added / removed from the PlaceholderAPI
+     * @return Map of config path / values which need to be added / removed from the PlaceholderAPI
-   * config.yml file
+     * config.yml file
-   */
+     */
-  Map<String, Object> getDefaults();
+    Map<String, Object> getDefaults();
 }

src/main/java/me/clip/placeholderapi/expansion/NMSVersion.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -22,60 +22,60 @@ package me.clip.placeholderapi.expansion;
 
 public enum NMSVersion {
 
-  UNKNOWN("unknown"),
+    UNKNOWN("unknown"),
-  SPIGOT_1_7_R1("v1_7_R1"),
+    SPIGOT_1_7_R1("v1_7_R1"),
-  SPIGOT_1_7_R2("v1_7_R2"),
+    SPIGOT_1_7_R2("v1_7_R2"),
-  SPIGOT_1_7_R3("v1_7_R3"),
+    SPIGOT_1_7_R3("v1_7_R3"),
-  SPIGOT_1_7_R4("v1_7_R4"),
+    SPIGOT_1_7_R4("v1_7_R4"),
-  SPIGOT_1_8_R1("v1_8_R1"),
+    SPIGOT_1_8_R1("v1_8_R1"),
-  SPIGOT_1_8_R2("v1_8_R2"),
+    SPIGOT_1_8_R2("v1_8_R2"),
-  SPIGOT_1_8_R3("v1_8_R3"),
+    SPIGOT_1_8_R3("v1_8_R3"),
-  SPIGOT_1_9_R1("v1_9_R1"),
+    SPIGOT_1_9_R1("v1_9_R1"),
-  SPIGOT_1_9_R2("v1_9_R2"),
+    SPIGOT_1_9_R2("v1_9_R2"),
-  SPIGOT_1_10_R1("v1_10_R1"),
+    SPIGOT_1_10_R1("v1_10_R1"),
-  SPIGOT_1_11_R1("v1_11_R1"),
+    SPIGOT_1_11_R1("v1_11_R1"),
-  SPIGOT_1_12_R1("v1_12_R1"),
+    SPIGOT_1_12_R1("v1_12_R1"),
-  SPIGOT_1_13_R1("v1_13_R1"),
+    SPIGOT_1_13_R1("v1_13_R1"),
-  SPIGOT_1_13_R2("v1_13_R2"),
+    SPIGOT_1_13_R2("v1_13_R2"),
-  SPIGOT_1_14_R1("v1_14_R1"),
+    SPIGOT_1_14_R1("v1_14_R1"),
-  SPIGOT_1_15_R1("v1_15_R1"),
+    SPIGOT_1_15_R1("v1_15_R1"),
-  SPIGOT_1_16_R1("v1_16_R1"),
+    SPIGOT_1_16_R1("v1_16_R1"),
-  SPIGOT_1_16_R2("v1_16_R2"),
+    SPIGOT_1_16_R2("v1_16_R2"),
-  SPIGOT_1_16_R3("v1_16_R3"),
+    SPIGOT_1_16_R3("v1_16_R3"),
-  SPIGOT_1_17_R1("v1_17_R1"),
+    SPIGOT_1_17_R1("v1_17_R1"),
-  SPIGOT_1_18_R1("v1_18_R1"),
+    SPIGOT_1_18_R1("v1_18_R1"),
-  SPIGOT_1_19_R1("v1_19_R1"),
+    SPIGOT_1_19_R1("v1_19_R1"),
-  SPIGOT_1_19_R2("v1_19_R2"),
+    SPIGOT_1_19_R2("v1_19_R2"),
-  SPIGOT_1_19_R3("v1_19_R3"),
+    SPIGOT_1_19_R3("v1_19_R3"),
-  SPIGOT_1_20_R1("v1_20_R1"),
+    SPIGOT_1_20_R1("v1_20_R1"),
-  SPIGOT_1_20_R2("v1_20_R2"),
+    SPIGOT_1_20_R2("v1_20_R2"),
-  SPIGOT_1_20_R3("v1_20_R3"),
+    SPIGOT_1_20_R3("v1_20_R3"),
-  SPIGOT_1_20_R4("v1_20_R4"),
+    SPIGOT_1_20_R4("v1_20_R4"),
-  SPIGOT_1_21_R1("v1_21_R1"),
+    SPIGOT_1_21_R1("v1_21_R1"),
-  SPIGOT_1_21_R2("V1_21_R2"),
+    SPIGOT_1_21_R2("V1_21_R2"),
-  SPIGOT_1_21_R3("V1_21_R3"),
+    SPIGOT_1_21_R3("V1_21_R3"),
-  SPIGOT_1_21_R4("V1_21_R4"),
+    SPIGOT_1_21_R4("V1_21_R4"),
-  SPIGOT_1_21_R5("V1_21_R5"),
+    SPIGOT_1_21_R5("V1_21_R5"),
-  SPIGOT_1_21_R6("V1_21_R6");
+    SPIGOT_1_21_R6("V1_21_R6");
 
-  private final String version;
+    private final String version;
 
-  NMSVersion(String version) {
+    NMSVersion(String version) {
-    this.version = version;
+        this.version = version;
-  }
-
-  public static NMSVersion getVersion(String version) {
-    for (NMSVersion v : values()) {
-      if (v.getVersion().equalsIgnoreCase(version)) {
-        return v;
-      }
     }
 
-    return NMSVersion.UNKNOWN;
+    public static NMSVersion getVersion(String version) {
-  }
+        for (NMSVersion v : values()) {
+            if (v.getVersion().equalsIgnoreCase(version)) {
+                return v;
+            }
+        }
 
-  public String getVersion() {
+        return NMSVersion.UNKNOWN;
-    return version;
+    }
-  }
+
+    public String getVersion() {
+        return version;
+    }
 
 }

src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -23,6 +23,7 @@ package me.clip.placeholderapi.expansion;
 import java.util.Collections;
 import java.util.List;
 import java.util.logging.Level;
+
 import me.clip.placeholderapi.PlaceholderAPIPlugin;
 import me.clip.placeholderapi.PlaceholderHook;
 import org.bukkit.Bukkit;
@@ -40,440 +41,439 @@ import org.jetbrains.annotations.Nullable;
  */
 public abstract class PlaceholderExpansion extends PlaceholderHook {
 
-  /**
+    /**
-   * The type is {@link Type#INTERNAL} by default.
+     * The type is {@link Type#INTERNAL} by default.
-   * For external expansions, the type is updated on {@link me.clip.placeholderapi.expansion.manager.LocalExpansionManager#register(Class) register}.
+     * For external expansions, the type is updated on {@link me.clip.placeholderapi.expansion.manager.LocalExpansionManager#register(Class) register}.
-   * @since 2.11.4
+     *
-   */
+     * @since 2.11.4
-  @ApiStatus.Internal
+     */
-  protected Type expansionType = Type.INTERNAL;
+    @ApiStatus.Internal
-
+    protected Type expansionType = Type.INTERNAL;
-  /**
-   * The placeholder identifier of this expansion. May not contain {@literal %},
-   * {@literal {}} or _
-   *
-   * @return placeholder identifier that is associated with this expansion
-   */
-  @NotNull
-  public abstract String getIdentifier();
-
-  /**
-   * The author of this expansion
-   *
-   * @return name of the author for this expansion
-   */
-  @NotNull
-  public abstract String getAuthor();
-
-  /**
-   * The version of this expansion
-   *
-   * @return current version of this expansion
-   */
-  @NotNull
-  public abstract String getVersion();
-
-  /**
-   * The name of this expansion
-   *
-   * @return {@link #getIdentifier()} by default, name of this expansion if specified
-   */
-  @NotNull
-  public String getName() {
-    return getIdentifier();
-  }
-
-  /**
-   * The name of the plugin that this expansion hooks into. by default will null
-   *
-   * @return plugin name that this expansion requires to function
-   */
-  @Nullable
-  public String getRequiredPlugin() {
-    return getPlugin();
-  }
-
-  /**
-   * The placeholders associated with this expansion
-   *
-   * @return placeholder list that this expansion provides
-   */
-  @NotNull
-  public List<String> getPlaceholders() {
-    return Collections.emptyList();
-  }
-
-
-  /**
-   * Expansions that do not use the ecloud and instead register from the dependency should set this
-   * to true to ensure that your placeholder expansion is not unregistered when the papi reload
-   * command is used
-   *
-   * @return if this expansion should persist through placeholder reloads
-   */
-  public boolean persist() {
-    return false;
-  }
-
-
-  /**
-   * Check if this placeholder identifier has already been registered
-   *
-   * @return true if the identifier for this expansion is already registered
-   */
-  public final boolean isRegistered() {
-    return getPlaceholderAPI().getLocalExpansionManager().findExpansionByIdentifier(getIdentifier())
-        .map(it -> it.equals(this)).orElse(false);
-  }
-
-
-  /**
-   * If any requirements need to be checked before this expansion should register, you can check
-   * them here
-   *
-   * @return true if this hook meets all the requirements to register
-   */
-  public boolean canRegister() {
-    return getRequiredPlugin() == null
-        || Bukkit.getPluginManager().getPlugin(getRequiredPlugin()) != null;
-  }
-
-  /**
-   * Attempt to register this PlaceholderExpansion
-   *
-   * @return true if this expansion is now registered with PlaceholderAPI
-   */
-  public boolean register() {
-    return getPlaceholderAPI().getLocalExpansionManager().register(this);
-  }
-
-  /**
-   * Attempt to unregister this PlaceholderExpansion
-   *
-   * @return true if this expansion is now unregistered with PlaceholderAPI
-   */
-  public final boolean unregister() {
-    return getPlaceholderAPI().getLocalExpansionManager().unregister(this);
-  }
-
-
-  /**
-   * Quick getter for the {@link PlaceholderAPIPlugin} instance
-   *
-   * @return {@link PlaceholderAPIPlugin} instance
-   */
-  @NotNull
-  public final PlaceholderAPIPlugin getPlaceholderAPI() {
-    return PlaceholderAPIPlugin.getInstance();
-  }
-
-  /**
-   * Get the type of the expansion
-   *
-   * @return the type of the expansion
-   * @since 2.11.4
-   */
-  @ApiStatus.Internal
-  public Type getExpansionType() {
-    return expansionType;
-  }
-
-  /**
-   * Set the type of the expansion
-   * @param expansionType the new type
-   * @since 2.11.4
-   */
-  @ApiStatus.Internal
-  public void setExpansionType(Type expansionType) {
-    this.expansionType = expansionType;
-  }
-
-  // === Configuration ===
-  
-  /**
-   * Gets the ConfigurationSection of the expansion located in the config.yml of PlaceholderAPI or
-   * null when not specified.
-   * <br>You may use the {@link Configurable} interface to define default values set
-   * 
-   * @return ConfigurationSection that this expansion has.
-   */
-  @Nullable
-  public final ConfigurationSection getConfigSection() {
-    return getPlaceholderAPI().getConfig().getConfigurationSection("expansions." + getIdentifier());
-  }
-  
-  /**
-   * Gets the ConfigurationSection relative to the {@link #getConfigSection() default one} set
-   * by the expansion or null when the default ConfigurationSection is null
-   * 
-   * @param path The path to get the ConfigurationSection from. This is relative to the default section
-   * @return ConfigurationSection relative to the default section
-   */
-  @Nullable
-  public final ConfigurationSection getConfigSection(@NotNull final String path) {
-    final ConfigurationSection section = getConfigSection();
-    return section == null ? null : section.getConfigurationSection(path);
-  }
-  
-  /**
-   * Gets the Object relative to the {@link #getConfigSection() default ConfigurationSection} set
-   * by the expansion or the provided Default Object, when the default ConfigurationSection is null
-   * 
-   * @param path The path to get the Object from. This is relative to the default section
-   * @param def The default Object to return when the ConfigurationSection returns null
-   * @return Object from the provided path or the default one provided
-   */
-  @Nullable
-  @Contract("_, !null -> !null")
-  public final Object get(@NotNull final String path, final Object def) {
-    final ConfigurationSection section = getConfigSection();
-    return section == null ? def : section.get(path, def);
-  }
-  
-  /**
-   * Gets the int relative to the {@link #getConfigSection() default ConfigurationSection} set
-   * by the expansion or the provided Default int, when the default ConfigurationSection is null
-   *
-   * @param path The path to get the int from. This is relative to the default section
-   * @param def The default int to return when the ConfigurationSection returns null
-   * @return int from the provided path or the default one provided
-   */
-  public final int getInt(@NotNull final String path, final int def) {
-    final ConfigurationSection section = getConfigSection();
-    return section == null ? def : section.getInt(path, def);
-  }
-  
-  /**
-   * Gets the long relative to the {@link #getConfigSection() default ConfigurationSection} set
-   * by the expansion or the provided Default long, when the default ConfigurationSection is null
-   *
-   * @param path The path to get the long from. This is relative to the default section
-   * @param def The default long to return when the ConfigurationSection returns null
-   * @return long from the provided path or the default one provided
-   */
-  public final long getLong(@NotNull final String path, final long def) {
-    final ConfigurationSection section = getConfigSection();
-    return section == null ? def : section.getLong(path, def);
-  }
-  
-  /**
-   * Gets the double relative to the {@link #getConfigSection() default ConfigurationSection} set
-   * by the expansion or the provided Default double, when the default ConfigurationSection is null
-   *
-   * @param path The path to get the double from. This is relative to the default section
-   * @param def The default double to return when the ConfigurationSection returns null
-   * @return double from the provided path or the default one provided
-   */
-  public final double getDouble(@NotNull final String path, final double def) {
-    final ConfigurationSection section = getConfigSection();
-    return section == null ? def : section.getDouble(path, def);
-  }
-  
-  /**
-   * Gets the String relative to the {@link #getConfigSection() default ConfigurationSection} set
-   * by the expansion or the provided Default String, when the default ConfigurationSection is null
-   *
-   * @param path The path to get the String from. This is relative to the default section
-   * @param def The default String to return when the ConfigurationSection returns null. Can be null
-   * @return String from the provided path or the default one provided
-   */
-  @Nullable
-  @Contract("_, !null -> !null")
-  public final String getString(@NotNull final String path, @Nullable final String def) {
-    final ConfigurationSection section = getConfigSection();
-    return section == null ? def : section.getString(path, def);
-  }
-  
-  /**
-   * Gets a String List relative to the {@link #getConfigSection() default ConfigurationSection} set
-   * by the expansion or an empty List, when the default ConfigurationSection is null
-   *
-   * @param path The path to get the String list from. This is relative to the default section
-   * @return String list from the provided path or an empty list
-   */
-  @NotNull
-  public final List<String> getStringList(@NotNull final String path) {
-    final ConfigurationSection section = getConfigSection();
-    return section == null ? Collections.emptyList() : section.getStringList(path);
-  }
-  
-  /**
-   * Gets the boolean relative to the {@link #getConfigSection() default ConfigurationSection} set
-   * by the expansion or the default boolean, when the default ConfigurationSection is null
-   *
-   * @param path The path to get the boolean from. This is relative to the default section
-   * @param def The default boolean to return when the ConfigurationSection is null
-   * @return boolean from the provided path or the default one provided
-   */
-  public final boolean getBoolean(@NotNull final String path, final boolean def) {
-    final ConfigurationSection section = getConfigSection();
-    return section == null ? def : section.getBoolean(path, def);
-  }
-
-  /**
-   * Whether the {@link #getConfigSection() default ConfigurationSection} contains the provided path
-   * or not. This will return {@code false} when either the default section is null, or doesn't
-   * contain the provided path
-   *
-   * @param path The path to check
-   * @return true when the default ConfigurationSection is not null and contains the path, false otherwise
-   */
-  public final boolean configurationContains(@NotNull final String path) {
-    final ConfigurationSection section = getConfigSection();
-    return section != null && section.contains(path);
-  }
-
-  /**
-   * Logs the provided message with the provided Level in the console.
-   * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
-   * 
-   * @param level The Level at which the message should be logged with
-   * @param msg The message to log
-   */
-  public void log(Level level, String msg) {
-    getPlaceholderAPI().getLogger().log(level, "[" + getName() + "] " + msg);
-  }
-
-  /**
-   * Logs the provided message and Throwable with the provided Level in the console.
-   * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
-   *
-   * @param level The Level at which the message should be logged with
-   * @param msg The message to log
-   * @param throwable The Throwable to log
-   */
-  public void log(Level level, String msg, Throwable throwable) {
-    getPlaceholderAPI().getLogger().log(level, "[" + getName() + "] " + msg, throwable);
-  }
-
-  /**
-   * Logs the provided message with Level "info".
-   * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
-   *
-   * @param msg The message to log
-   */
-  public void info(String msg) {
-    log(Level.INFO, msg);
-  }
-
-  /**
-   * Logs the provided message with Level "warning".
-   * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
-   *
-   * @param msg The message to log
-   */
-  public void warning(String msg) {
-    log(Level.WARNING, msg);
-  }
-
-  /**
-   * Logs the provided message with Level "severe" (error).
-   * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
-   *
-   * @param msg The message to log
-   */
-  public void severe(String msg) {
-    log(Level.SEVERE, msg);
-  }
-
-  /**
-   * Logs the provided message and Throwable with Level "severe" (error).
-   * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
-   *
-   * @param msg The message to log
-   * @param throwable The Throwable to log
-   */
-  public void severe(String msg, Throwable throwable) {
-    log(Level.SEVERE, msg, throwable);
-  }
-  
-  
-  /**
-   * Whether the provided Object is an instance of this PlaceholderExpansion.
-   * <br>This method will perform the following checks in order:
-   * <br><ul>
-   *     <li>Checks if Object equals the class. Returns true when equal and continues otherwise</li>
-   *     <li>Checks if the Object is an instance of a PlaceholderExpansion. Returns false if not</li>
-   *     <li>Checks if the Object's Identifier, Author and version equal the one of this class</li>
-   * </ul>
-   * 
-   * @param o The Object to check
-   * @return true or false depending on the above mentioned checks
-   */
-  @Override
-  public final boolean equals(final Object o) {
-    if (this == o) {
-      return true;
-    }
-    if (!(o instanceof PlaceholderExpansion)) {
-      return false;
-    }
-
-    final PlaceholderExpansion expansion = (PlaceholderExpansion) o;
-
-    return getIdentifier().equals(expansion.getIdentifier()) &&
-        getAuthor().equals(expansion.getAuthor()) &&
-        getVersion().equals(expansion.getVersion());
-  }
-  
-  /**
-   * Returns a String containing the Expansion's name, author and version
-   * 
-   * @return String containing name, author and version of the expansion
-   */
-  @Override
-  public final String toString() {
-    return String.format("PlaceholderExpansion[name: '%s', author: '%s', version: '%s', type: '%s']", getName(),
-        getAuthor(), getVersion(), getExpansionType());
-  }
-
-  // === Deprecated API ===
-
-  /**
-   * @deprecated As of versions greater than 2.8.7, use {@link #getRequiredPlugin()}
-   *
-   * @return The plugin name.
-   */
-  @Deprecated
-  @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
-  public String getPlugin() {
-    return null;
-  }
-
-  /**
-   * @deprecated As of versions greater than 2.8.7, use the expansion cloud to show a description
-   *
-   * @return The description of the expansion.
-   */
-  @Deprecated
-  @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
-  public String getDescription() {
-    return null;
-  }
-
-  /**
-   * @deprecated As of versions greater than 2.8.7, use the expansion cloud to display a link
-   *
-   * @return The link for the expansion.
-   */
-  @Deprecated
-  @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
-  public String getLink() {
-    return null;
-  }
-
-  public enum Type {
 
     /**
-     * An expansion provided by a plugin is considered internal
+     * The placeholder identifier of this expansion. May not contain {@literal %},
+     * {@literal {}} or _
+     *
+     * @return placeholder identifier that is associated with this expansion
      */
-    INTERNAL,
+    @NotNull
+    public abstract String getIdentifier();
 
     /**
-     * An expansion loaded from the expansions folder is considered external
+     * The author of this expansion
+     *
+     * @return name of the author for this expansion
      */
-    EXTERNAL
+    @NotNull
+    public abstract String getAuthor();
 
-  }
+    /**
+     * The version of this expansion
+     *
+     * @return current version of this expansion
+     */
+    @NotNull
+    public abstract String getVersion();
+
+    /**
+     * The name of this expansion
+     *
+     * @return {@link #getIdentifier()} by default, name of this expansion if specified
+     */
+    @NotNull
+    public String getName() {
+        return getIdentifier();
+    }
+
+    /**
+     * The name of the plugin that this expansion hooks into. by default will null
+     *
+     * @return plugin name that this expansion requires to function
+     */
+    @Nullable
+    public String getRequiredPlugin() {
+        return getPlugin();
+    }
+
+    /**
+     * The placeholders associated with this expansion
+     *
+     * @return placeholder list that this expansion provides
+     */
+    @NotNull
+    public List<String> getPlaceholders() {
+        return Collections.emptyList();
+    }
+
+
+    /**
+     * Expansions that do not use the ecloud and instead register from the dependency should set this
+     * to true to ensure that your placeholder expansion is not unregistered when the papi reload
+     * command is used
+     *
+     * @return if this expansion should persist through placeholder reloads
+     */
+    public boolean persist() {
+        return false;
+    }
+
+
+    /**
+     * Check if this placeholder identifier has already been registered
+     *
+     * @return true if the identifier for this expansion is already registered
+     */
+    public final boolean isRegistered() {
+        return getPlaceholderAPI().getLocalExpansionManager().findExpansionByIdentifier(getIdentifier())
+                .map(it -> it.equals(this)).orElse(false);
+    }
+
+
+    /**
+     * If any requirements need to be checked before this expansion should register, you can check
+     * them here
+     *
+     * @return true if this hook meets all the requirements to register
+     */
+    public boolean canRegister() {
+        return getRequiredPlugin() == null
+                || Bukkit.getPluginManager().getPlugin(getRequiredPlugin()) != null;
+    }
+
+    /**
+     * Attempt to register this PlaceholderExpansion
+     *
+     * @return true if this expansion is now registered with PlaceholderAPI
+     */
+    public boolean register() {
+        return getPlaceholderAPI().getLocalExpansionManager().register(this);
+    }
+
+    /**
+     * Attempt to unregister this PlaceholderExpansion
+     *
+     * @return true if this expansion is now unregistered with PlaceholderAPI
+     */
+    public final boolean unregister() {
+        return getPlaceholderAPI().getLocalExpansionManager().unregister(this);
+    }
+
+
+    /**
+     * Quick getter for the {@link PlaceholderAPIPlugin} instance
+     *
+     * @return {@link PlaceholderAPIPlugin} instance
+     */
+    @NotNull
+    public final PlaceholderAPIPlugin getPlaceholderAPI() {
+        return PlaceholderAPIPlugin.getInstance();
+    }
+
+    /**
+     * Get the type of the expansion
+     *
+     * @return the type of the expansion
+     * @since 2.11.4
+     */
+    @ApiStatus.Internal
+    public Type getExpansionType() {
+        return expansionType;
+    }
+
+    /**
+     * Set the type of the expansion
+     *
+     * @param expansionType the new type
+     * @since 2.11.4
+     */
+    @ApiStatus.Internal
+    public void setExpansionType(Type expansionType) {
+        this.expansionType = expansionType;
+    }
+
+    // === Configuration ===
+
+    /**
+     * Gets the ConfigurationSection of the expansion located in the config.yml of PlaceholderAPI or
+     * null when not specified.
+     * <br>You may use the {@link Configurable} interface to define default values set
+     *
+     * @return ConfigurationSection that this expansion has.
+     */
+    @Nullable
+    public final ConfigurationSection getConfigSection() {
+        return getPlaceholderAPI().getConfig().getConfigurationSection("expansions." + getIdentifier());
+    }
+
+    /**
+     * Gets the ConfigurationSection relative to the {@link #getConfigSection() default one} set
+     * by the expansion or null when the default ConfigurationSection is null
+     *
+     * @param path The path to get the ConfigurationSection from. This is relative to the default section
+     * @return ConfigurationSection relative to the default section
+     */
+    @Nullable
+    public final ConfigurationSection getConfigSection(@NotNull final String path) {
+        final ConfigurationSection section = getConfigSection();
+        return section == null ? null : section.getConfigurationSection(path);
+    }
+
+    /**
+     * Gets the Object relative to the {@link #getConfigSection() default ConfigurationSection} set
+     * by the expansion or the provided Default Object, when the default ConfigurationSection is null
+     *
+     * @param path The path to get the Object from. This is relative to the default section
+     * @param def  The default Object to return when the ConfigurationSection returns null
+     * @return Object from the provided path or the default one provided
+     */
+    @Nullable
+    @Contract("_, !null -> !null")
+    public final Object get(@NotNull final String path, final Object def) {
+        final ConfigurationSection section = getConfigSection();
+        return section == null ? def : section.get(path, def);
+    }
+
+    /**
+     * Gets the int relative to the {@link #getConfigSection() default ConfigurationSection} set
+     * by the expansion or the provided Default int, when the default ConfigurationSection is null
+     *
+     * @param path The path to get the int from. This is relative to the default section
+     * @param def  The default int to return when the ConfigurationSection returns null
+     * @return int from the provided path or the default one provided
+     */
+    public final int getInt(@NotNull final String path, final int def) {
+        final ConfigurationSection section = getConfigSection();
+        return section == null ? def : section.getInt(path, def);
+    }
+
+    /**
+     * Gets the long relative to the {@link #getConfigSection() default ConfigurationSection} set
+     * by the expansion or the provided Default long, when the default ConfigurationSection is null
+     *
+     * @param path The path to get the long from. This is relative to the default section
+     * @param def  The default long to return when the ConfigurationSection returns null
+     * @return long from the provided path or the default one provided
+     */
+    public final long getLong(@NotNull final String path, final long def) {
+        final ConfigurationSection section = getConfigSection();
+        return section == null ? def : section.getLong(path, def);
+    }
+
+    /**
+     * Gets the double relative to the {@link #getConfigSection() default ConfigurationSection} set
+     * by the expansion or the provided Default double, when the default ConfigurationSection is null
+     *
+     * @param path The path to get the double from. This is relative to the default section
+     * @param def  The default double to return when the ConfigurationSection returns null
+     * @return double from the provided path or the default one provided
+     */
+    public final double getDouble(@NotNull final String path, final double def) {
+        final ConfigurationSection section = getConfigSection();
+        return section == null ? def : section.getDouble(path, def);
+    }
+
+    /**
+     * Gets the String relative to the {@link #getConfigSection() default ConfigurationSection} set
+     * by the expansion or the provided Default String, when the default ConfigurationSection is null
+     *
+     * @param path The path to get the String from. This is relative to the default section
+     * @param def  The default String to return when the ConfigurationSection returns null. Can be null
+     * @return String from the provided path or the default one provided
+     */
+    @Nullable
+    @Contract("_, !null -> !null")
+    public final String getString(@NotNull final String path, @Nullable final String def) {
+        final ConfigurationSection section = getConfigSection();
+        return section == null ? def : section.getString(path, def);
+    }
+
+    /**
+     * Gets a String List relative to the {@link #getConfigSection() default ConfigurationSection} set
+     * by the expansion or an empty List, when the default ConfigurationSection is null
+     *
+     * @param path The path to get the String list from. This is relative to the default section
+     * @return String list from the provided path or an empty list
+     */
+    @NotNull
+    public final List<String> getStringList(@NotNull final String path) {
+        final ConfigurationSection section = getConfigSection();
+        return section == null ? Collections.emptyList() : section.getStringList(path);
+    }
+
+    /**
+     * Gets the boolean relative to the {@link #getConfigSection() default ConfigurationSection} set
+     * by the expansion or the default boolean, when the default ConfigurationSection is null
+     *
+     * @param path The path to get the boolean from. This is relative to the default section
+     * @param def  The default boolean to return when the ConfigurationSection is null
+     * @return boolean from the provided path or the default one provided
+     */
+    public final boolean getBoolean(@NotNull final String path, final boolean def) {
+        final ConfigurationSection section = getConfigSection();
+        return section == null ? def : section.getBoolean(path, def);
+    }
+
+    /**
+     * Whether the {@link #getConfigSection() default ConfigurationSection} contains the provided path
+     * or not. This will return {@code false} when either the default section is null, or doesn't
+     * contain the provided path
+     *
+     * @param path The path to check
+     * @return true when the default ConfigurationSection is not null and contains the path, false otherwise
+     */
+    public final boolean configurationContains(@NotNull final String path) {
+        final ConfigurationSection section = getConfigSection();
+        return section != null && section.contains(path);
+    }
+
+    /**
+     * Logs the provided message with the provided Level in the console.
+     * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
+     *
+     * @param level The Level at which the message should be logged with
+     * @param msg   The message to log
+     */
+    public void log(Level level, String msg) {
+        getPlaceholderAPI().getLogger().log(level, "[" + getName() + "] " + msg);
+    }
+
+    /**
+     * Logs the provided message and Throwable with the provided Level in the console.
+     * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
+     *
+     * @param level     The Level at which the message should be logged with
+     * @param msg       The message to log
+     * @param throwable The Throwable to log
+     */
+    public void log(Level level, String msg, Throwable throwable) {
+        getPlaceholderAPI().getLogger().log(level, "[" + getName() + "] " + msg, throwable);
+    }
+
+    /**
+     * Logs the provided message with Level "info".
+     * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
+     *
+     * @param msg The message to log
+     */
+    public void info(String msg) {
+        log(Level.INFO, msg);
+    }
+
+    /**
+     * Logs the provided message with Level "warning".
+     * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
+     *
+     * @param msg The message to log
+     */
+    public void warning(String msg) {
+        log(Level.WARNING, msg);
+    }
+
+    /**
+     * Logs the provided message with Level "severe" (error).
+     * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
+     *
+     * @param msg The message to log
+     */
+    public void severe(String msg) {
+        log(Level.SEVERE, msg);
+    }
+
+    /**
+     * Logs the provided message and Throwable with Level "severe" (error).
+     * <br>The message will be prefixed with {@link #getName() <code>[&lt;expansion name&gt;]</code>}
+     *
+     * @param msg       The message to log
+     * @param throwable The Throwable to log
+     */
+    public void severe(String msg, Throwable throwable) {
+        log(Level.SEVERE, msg, throwable);
+    }
+
+
+    /**
+     * Whether the provided Object is an instance of this PlaceholderExpansion.
+     * <br>This method will perform the following checks in order:
+     * <br><ul>
+     * <li>Checks if Object equals the class. Returns true when equal and continues otherwise</li>
+     * <li>Checks if the Object is an instance of a PlaceholderExpansion. Returns false if not</li>
+     * <li>Checks if the Object's Identifier, Author and version equal the one of this class</li>
+     * </ul>
+     *
+     * @param o The Object to check
+     * @return true or false depending on the above mentioned checks
+     */
+    @Override
+    public final boolean equals(final Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof PlaceholderExpansion)) {
+            return false;
+        }
+
+        final PlaceholderExpansion expansion = (PlaceholderExpansion) o;
+
+        return getIdentifier().equals(expansion.getIdentifier()) &&
+                getAuthor().equals(expansion.getAuthor()) &&
+                getVersion().equals(expansion.getVersion());
+    }
+
+    /**
+     * Returns a String containing the Expansion's name, author and version
+     *
+     * @return String containing name, author and version of the expansion
+     */
+    @Override
+    public final String toString() {
+        return String.format("PlaceholderExpansion[name: '%s', author: '%s', version: '%s', type: '%s']", getName(),
+                getAuthor(), getVersion(), getExpansionType());
+    }
+
+    // === Deprecated API ===
+
+    /**
+     * @return The plugin name.
+     * @deprecated As of versions greater than 2.8.7, use {@link #getRequiredPlugin()}
+     */
+    @Deprecated
+    @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
+    public String getPlugin() {
+        return null;
+    }
+
+    /**
+     * @return The description of the expansion.
+     * @deprecated As of versions greater than 2.8.7, use the expansion cloud to show a description
+     */
+    @Deprecated
+    @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
+    public String getDescription() {
+        return null;
+    }
+
+    /**
+     * @return The link for the expansion.
+     * @deprecated As of versions greater than 2.8.7, use the expansion cloud to display a link
+     */
+    @Deprecated
+    @ApiStatus.ScheduledForRemoval(inVersion = "2.13.0")
+    public String getLink() {
+        return null;
+    }
+
+    public enum Type {
+
+        /**
+         * An expansion provided by a plugin is considered internal
+         */
+        INTERNAL,
+
+        /**
+         * An expansion loaded from the expansions folder is considered external
+         */
+        EXTERNAL
+
+    }
 
 }

src/main/java/me/clip/placeholderapi/expansion/Relational.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -25,19 +25,19 @@ import org.bukkit.entity.Player;
 /**
  * Implementing this interface allows your {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}
  * to be used as a relational placeholder expansion.
- * 
+ *
  * <p>Relational placeholders take two Players as input and are always prefixed with {@code rel_},
  * so {@code %foo_bar%} becomes {@code %rel_foo_bar%}
  */
 public interface Relational {
 
-  /**
+    /**
-   * This method is called whenever a placeholder starting with {@code rel_} is called.
+     * This method is called whenever a placeholder starting with {@code rel_} is called.
-   * 
+     *
-   * @param one The first player used for the placeholder.
+     * @param one        The first player used for the placeholder.
-   * @param two The second player used for the placeholder.
+     * @param two        The second player used for the placeholder.
-   * @param identifier The text right after the expansion's name (%expansion_<b>identifier</b>%)
+     * @param identifier The text right after the expansion's name (%expansion_<b>identifier</b>%)
-   * @return Parsed String from the expansion.
+     * @return Parsed String from the expansion.
-   */
+     */
-  String onPlaceholderRequest(Player one, Player two, String identifier);
+    String onPlaceholderRequest(Player one, Player two, String identifier);
 }

src/main/java/me/clip/placeholderapi/expansion/Taskable.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -23,21 +23,21 @@ package me.clip.placeholderapi.expansion;
 /**
  * Implementing this interface adds the {@link #start() start} and {@link #stop() stop} void
  * methods to your {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}.
- * 
+ *
  * <p>This can be used to execute methods and tasks whenever the PlaceholderExpansion has been
  * successfully (un)registered.
  */
 public interface Taskable {
 
-  /**
+    /**
-   * Called when the implementing class has successfully been registered to the placeholder map.
+     * Called when the implementing class has successfully been registered to the placeholder map.
-   * <br>Tasks that need to be performed when this expansion is registered should go here
+     * <br>Tasks that need to be performed when this expansion is registered should go here
-   */
+     */
-  void start();
+    void start();
 
-  /**
+    /**
-   * Called when the implementing class has been unregistered from PlaceholderAPI.
+     * Called when the implementing class has been unregistered from PlaceholderAPI.
-   * <br>Tasks that need to be performed when this expansion has unregistered should go here
+     * <br>Tasks that need to be performed when this expansion has unregistered should go here
-   */
+     */
-  void stop();
+    void stop();
 }

src/main/java/me/clip/placeholderapi/expansion/Version.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/expansion/VersionSpecific.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -27,19 +27,17 @@ package me.clip.placeholderapi.expansion;
  * with that version.
  *
  * @author Ryan McCarthy
- *
  * @deprecated Will be removed in a future release.
  */
 @Deprecated
 public interface VersionSpecific {
 
-  /**
+    /**
-   * This method is called before the expansion is attempted to be registered The server version
+     * This method is called before the expansion is attempted to be registered The server version
-   * will be passed to this method so you know what version the server is currently running.
+     * will be passed to this method so you know what version the server is currently running.
-   *
+     *
-   * @param v The {@link Version} to check against
+     * @param v The {@link Version} to check against
-   *
+     * @return true if your expansion is compatible with the version the server is running.
-   * @return true if your expansion is compatible with the version the server is running.
+     */
-   */
+    boolean isCompatibleWith(Version v);
-  boolean isCompatibleWith(Version v);
 }

src/main/java/me/clip/placeholderapi/expansion/cloud/CloudExpansion.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -36,8 +36,8 @@ public class CloudExpansion {
             source_url,
             dependency_url;
 
-  private boolean hasExpansion,
+    private boolean hasExpansion,
-      shouldUpdate;
+            shouldUpdate;
 
     private long last_update,
             ratings_count;
@@ -135,9 +135,9 @@ public class CloudExpansion {
         this.shouldUpdate = shouldUpdate;
     }
 
-  public long getLastUpdate() {
+    public long getLastUpdate() {
-    return last_update;
+        return last_update;
-  }
+    }
 
     public void setLastUpdate(long last_update) {
         this.last_update = last_update;
@@ -169,8 +169,8 @@ public class CloudExpansion {
 
     public static class Version {
 
-    private String url, version, release_notes;
+        private String url, version, release_notes;
-    private boolean verified;
+        private boolean verified;
 
         public String getUrl() {
             return url;
@@ -195,14 +195,13 @@ public class CloudExpansion {
         public void setReleaseNotes(String release_notes) {
             this.release_notes = release_notes;
         }
-    }
 
-    public boolean isVerified() {
+        public boolean isVerified() {
-      return verified;
+            return verified;
-    }
+        }
 
-    public void setVerified(boolean verified) {
+        public void setVerified(boolean verified) {
-      this.verified = verified;
+            this.verified = verified;
+        }
     }
-  }
 }

src/main/java/me/clip/placeholderapi/expansion/manager/CloudExpansionManager.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -31,6 +31,7 @@ import java.io.FileOutputStream;
 import java.io.IOException;
 import java.lang.reflect.Type;
 import java.net.URL;
+import java.net.UnknownHostException;
 import java.nio.channels.Channels;
 import java.nio.channels.ReadableByteChannel;
 import java.nio.charset.StandardCharsets;
@@ -61,8 +62,8 @@ import org.jetbrains.annotations.Unmodifiable;
 
 public final class CloudExpansionManager {
 
-  @NotNull
+    @NotNull
-  private static final String API_URL = "https://ecloud.placeholderapi.com/api/v3/";
+    private static final String API_URL = "https://ecloud.placeholderapi.com/api/v3/?platform=bukkit";
 
     @NotNull
     private static final Gson GSON = new Gson();
@@ -115,6 +116,10 @@ public final class CloudExpansionManager {
         return ImmutableMap.copyOf(cache);
     }
 
+    public boolean isEmpty() {
+        return cache.isEmpty();
+    }
+
     @NotNull
     @Unmodifiable
     public Map<String, CloudExpansion> getCloudExpansionsInstalled() {
@@ -197,6 +202,8 @@ public final class CloudExpansionManager {
                         for (String name : toRemove) {
                             values.remove(name);
                         }
+                    } catch (UnknownHostException e) {
+                        plugin.getLogger().log(Level.WARNING, "There is no data available from the eCloud. Please try running /papi refresh. If this does not resolve the issue, the eCloud may be blocked by your firewall, server host, or service provider.\n\nMore information: https://placeholderapi.com/ecloud-blocked", e);
                     } catch (Throwable e) {
                         // ugly swallowing of every throwable, but we have to be defensive
                         plugin.getLogger().log(Level.WARNING, "Failed to download expansion information", e);

src/main/java/me/clip/placeholderapi/expansion/manager/LocalExpansionManager.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/expansion/manager/MethodSignature.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/listeners/ServerLoadEventListener.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -30,19 +30,19 @@ import org.jetbrains.annotations.NotNull;
 
 public final class ServerLoadEventListener implements Listener {
 
-  @NotNull
+    @NotNull
-  private final PlaceholderAPIPlugin plugin;
+    private final PlaceholderAPIPlugin plugin;
 
-  public ServerLoadEventListener(@NotNull final PlaceholderAPIPlugin plugin) {
+    public ServerLoadEventListener(@NotNull final PlaceholderAPIPlugin plugin) {
-    this.plugin = plugin;
+        this.plugin = plugin;
 
-    Bukkit.getPluginManager().registerEvents(this, plugin);
+        Bukkit.getPluginManager().registerEvents(this, plugin);
-  }
+    }
 
-  @EventHandler
+    @EventHandler
-  public void onServerLoad(@NotNull final ServerLoadEvent event) {
+    public void onServerLoad(@NotNull final ServerLoadEvent event) {
-    HandlerList.unregisterAll(this);
+        HandlerList.unregisterAll(this);
-    plugin.getLocalExpansionManager().load(Bukkit.getConsoleSender());
+        plugin.getLocalExpansionManager().load(Bukkit.getConsoleSender());
-  }
+    }
 
 }

src/main/java/me/clip/placeholderapi/replacer/CharsReplacer.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -44,8 +44,6 @@ public final class CharsReplacer implements Replacer {
     public String apply(@NotNull final String text, @Nullable final OfflinePlayer player,
                         @NotNull final Function<String, @Nullable PlaceholderExpansion> lookup) {
         final char[] chars = text.toCharArray();
-        // Woo! Hlello %player_name%
-        // Woo! GHsda PiggyPiglet
         final StringBuilder builder = new StringBuilder(text.length());
 
         final StringBuilder identifier = new StringBuilder();

src/main/java/me/clip/placeholderapi/replacer/ComponentReplacer.java

@@ -1,171 +0,0 @@
-package me.clip.placeholderapi.replacer;
-
-import me.clip.placeholderapi.PlaceholderAPI;
-import me.clip.placeholderapi.expansion.PlaceholderExpansion;
-import net.kyori.adventure.text.*;
-import net.kyori.adventure.text.event.ClickEvent;
-import net.kyori.adventure.text.event.HoverEvent;
-import net.kyori.adventure.text.format.Style;
-import org.bukkit.OfflinePlayer;
-
-import java.util.ArrayList;
-import java.util.List;
-import java.util.Locale;
-import java.util.function.Function;
-
-public final class ComponentReplacer {
-    public Component replace(Component component, OfflinePlayer player, Function<String, PlaceholderExpansion> function) {
-        Component modified = component;
-
-        final List<Component> oldChildren = component.children();
-        final int oldChildrenSize = oldChildren.size();
-        List<Component> children = null;
-
-        if (component instanceof TextComponent) {
-            TextComponent tc = (TextComponent) component;
-            final String content = tc.content();
-
-            final char[] chars = content.toCharArray();
-
-            final StringBuilder identifier = new StringBuilder();
-            final StringBuilder parameters = new StringBuilder();
-
-            for (int i = 0; i < chars.length; i++) {
-                final char l = chars[i];
-
-                if (l != '%' || i + 1 >= chars.length) {
-                    continue;
-                }
-
-                final int start = i;
-
-                boolean identified = false;
-                boolean invalid = true;
-
-                while (++i < chars.length) {
-                    final char p = chars[i];
-
-                    if (p == ' ' && !identified) {
-                        break;
-                    }
-
-                    if (p == '%') {
-                        invalid = false;
-                        break;
-                    }
-
-                    if (p == '_' && !identified) {
-                        identified = true;
-                        continue;
-                    }
-
-                    if (identified) {
-                        parameters.append(p);
-                    } else {
-                        identifier.append(p);
-                    }
-                }
-
-                final String identifierString = identifier.toString();
-                final String lowercaseIdentifierString = identifierString.toLowerCase(Locale.ROOT);
-                final String parametersString = parameters.toString();
-
-                identifier.setLength(0);
-                parameters.setLength(0);
-
-                if (invalid) {
-                    continue;
-                }
-
-                final PlaceholderExpansion expansion = function.apply(lowercaseIdentifierString);
-
-                if (expansion == null) {
-                    continue;
-                }
-
-                final String placeholderValue = expansion.onRequest(player, parametersString);
-
-                if (placeholderValue == null) {
-                    continue;
-                }
-
-                if (start == 0) {
-                    // if we're a full match, modify the component directly
-                    if (i == content.length() - 1) {
-                        final ComponentLike replacement = Component.text(placeholderValue).style(component.style());
-
-                        modified = replacement.asComponent();
-                        Style modStyle = modified.style();
-
-                        if (modStyle.hoverEvent() != null) {
-                            Object hoverValue = modStyle.hoverEvent().value();
-
-                            if (hoverValue instanceof Component) {
-                                final Object replacedValue = replace((Component) hoverValue, player, function);
-
-                                if (replacedValue != hoverValue) {
-                                    ((HoverEvent<Object>) modified.style().hoverEvent()).value(replacedValue);
-                                }
-                            }
-                        }
-
-                        if (modStyle.clickEvent() != null) {
-                            final ClickEvent.Payload payload = modStyle.clickEvent().payload();
-
-                            if (payload instanceof ClickEvent.Payload.Text) {
-                                final ClickEvent.Payload.Text replacedPayload = ClickEvent.Payload.string(PlaceholderAPI.setPlaceholders(player, ((ClickEvent.Payload.Text) payload).value()));
-                                modStyle.clickEvent(ClickEvent.clickEvent(modStyle.clickEvent().action(), replacedPayload));
-                            } else if (payload instanceof ClickEvent.Payload.Dialog) {
-                                final ClickEvent.Payload.Dialog replacedPayload;
-
-//                                ((ClickEvent.Payload.Dialog) payload).dialog()
-                                // apparently adventure doesn't have dialog support yet
-                            }
-                        }
-
-                        if (children == null) {
-                            children = new ArrayList<>(oldChildrenSize + modified.children().size());
-                            children.addAll(modified.children());
-                        }
-                    } else {
-                        modified = Component.text("", component.style());
-//                        final ComponentLike child =
-                    }
-                }
-            }
-
-        } else if (component instanceof TranslatableComponent) {
-            TranslatableComponent tc = (TranslatableComponent) component;
-            final List<TranslationArgument> args = tc.arguments();
-            List<TranslationArgument> newArgs = null;
-            for (int i = 0, size = args.size(); i < size; i++) {
-                final TranslationArgument original = args.get(i);
-                TranslationArgument replacement = original instanceof Component ? TranslationArgument.component(replace((Component) original, player, function)) : original;
-
-                if (original != replacement) {
-                    if (newArgs == null) {
-                        newArgs = new ArrayList<>(size);
-
-                        if (i > 0) {
-                            newArgs.addAll(args.subList(0, i));
-                        }
-                    }
-                }
-
-                if (newArgs != null) {
-                    newArgs.add(replacement);
-                }
-            }
-
-            if (newArgs != null) {
-                modified = ((TranslatableComponent) modified).arguments(newArgs);
-            }
-        }
-
-        return modified;
-    }
-
-    private static <V> void test(HoverEvent<V> event, V value) {
-        event.value(value);
-    }
-}

src/main/java/me/clip/placeholderapi/replacer/Replacer.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/scheduler/UniversalRunnable.java

@@ -27,7 +27,9 @@ import me.clip.placeholderapi.scheduler.scheduling.schedulers.TaskScheduler;
 import me.clip.placeholderapi.scheduler.scheduling.tasks.MyScheduledTask;
 import org.bukkit.plugin.Plugin;
 
-/** Just modified BukkitRunnable */
+/**
+ * Just modified BukkitRunnable
+ */
 public abstract class UniversalRunnable implements Runnable {
     MyScheduledTask task;
 

src/main/java/me/clip/placeholderapi/updatechecker/UpdateChecker.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -25,6 +25,9 @@ import java.io.InputStreamReader;
 import java.net.URL;
 import java.util.Arrays;
 import javax.net.ssl.HttpsURLConnection;
+
+import com.google.gson.JsonElement;
+import com.google.gson.JsonParser;
 import me.clip.placeholderapi.PlaceholderAPIPlugin;
 import me.clip.placeholderapi.scheduler.scheduling.schedulers.TaskScheduler;
 import me.clip.placeholderapi.util.Msg;
@@ -35,93 +38,93 @@ import org.bukkit.event.Listener;
 import org.bukkit.event.player.PlayerJoinEvent;
 
 public class UpdateChecker implements Listener {
+    private static final String MODRINTH_URL = "https://api.modrinth.com/v2/project/lKEzGugV/version";
 
-  private static final int RESOURCE_ID = 6245;
+    private static final int RESOURCE_ID = 6245;
-  private final PlaceholderAPIPlugin plugin;
+    private final PlaceholderAPIPlugin plugin;
-  private final TaskScheduler scheduler;
+    private final TaskScheduler scheduler;
-  private final String pluginVersion;
+    private final String pluginVersion;
-  private String spigotVersion;
+    private String modrinthVersion;
-  private boolean updateAvailable;
+    private boolean updateAvailable;
 
-  public UpdateChecker(PlaceholderAPIPlugin plugin) {
+    public UpdateChecker(PlaceholderAPIPlugin plugin) {
-    this.plugin = plugin;
+        this.plugin = plugin;
-    scheduler = plugin.getScheduler();
+        scheduler = plugin.getScheduler();
-    pluginVersion = plugin.getDescription().getVersion();
+        pluginVersion = plugin.getDescription().getVersion();
-  }
-
-  public boolean hasUpdateAvailable() {
-    return updateAvailable;
-  }
-
-  public String getSpigotVersion() {
-    return spigotVersion;
-  }
-
-  public void fetch() {
-    scheduler.runTaskAsynchronously(() -> {
-      try {
-        HttpsURLConnection con = (HttpsURLConnection) new URL(
-            "https://api.spigotmc.org/legacy/update.php?resource=" + RESOURCE_ID).openConnection();
-        con.setRequestMethod("GET");
-        spigotVersion = new BufferedReader(new InputStreamReader(con.getInputStream())).readLine();
-      } catch (Exception ex) {
-        plugin.getLogger().info("Failed to check for updates on spigot.");
-        return;
-      }
-
-      if (spigotVersion == null || spigotVersion.isEmpty()) {
-        return;
-      }
-
-      updateAvailable = spigotIsNewer();
-
-      if (!updateAvailable) {
-        return;
-      }
-
-      scheduler.runTask(() -> {
-        plugin.getLogger()
-            .info("An update for PlaceholderAPI (v" + getSpigotVersion() + ") is available at:");
-        plugin.getLogger()
-            .info("https://www.spigotmc.org/resources/placeholderapi." + RESOURCE_ID + "/");
-        Bukkit.getPluginManager().registerEvents(this, plugin);
-      });
-    });
-  }
-
-  private boolean spigotIsNewer() {
-    if (spigotVersion == null || spigotVersion.isEmpty()) {
-      return false;
     }
 
-    int[] plV = toReadable(pluginVersion);
+    public boolean hasUpdateAvailable() {
-    int[] spV = toReadable(spigotVersion);
+        return updateAvailable;
-
-    if (plV[0] < spV[0]) {
-      return true;
-    } else if ((plV[1] < spV[1])) {
-      return true;
-    } else {
-      return plV[2] < spV[2];
-    }
-  }
-
-  private int[] toReadable(String version) {
-    if (version.contains("-DEV")) {
-      version = version.split("-DEV")[0];
     }
 
-    return Arrays.stream(version.split("\\.")).mapToInt(Integer::parseInt).toArray();
+    public String getModrinthVersion() {
-  }
+        return modrinthVersion;
-
+    }
-  @EventHandler(priority = EventPriority.MONITOR)
+
-  public void onJoin(PlayerJoinEvent e) {
+    public void fetch() {
-    if (e.getPlayer().hasPermission("placeholderapi.updatenotify")) {
+        scheduler.runTaskAsynchronously(() -> {
-      Msg.msg(e.getPlayer(),
+            try {
-          "&bAn update for &fPlaceholder&7API &e(&fPlaceholder&7API &fv" + getSpigotVersion()
+                HttpsURLConnection con = (HttpsURLConnection) new URL(MODRINTH_URL).openConnection();
-              + "&e)"
+                con.setRequestMethod("GET");
-          , "&bis available at &ehttps://www.spigotmc.org/resources/placeholderapi." + RESOURCE_ID
+                final JsonElement json = JsonParser.parseReader(new BufferedReader(new InputStreamReader(con.getInputStream())));
-              + "/");
+                modrinthVersion = json.getAsJsonArray().get(0).getAsJsonObject().get("version_number").getAsString();
+            } catch (Exception ex) {
+                plugin.getLogger().info("Failed to check for updates on modrinth.");
+                return;
+            }
+
+            if (modrinthVersion == null || modrinthVersion.isEmpty()) {
+                return;
+            }
+
+            updateAvailable = modrinthIsNewer();
+
+            if (!updateAvailable) {
+                return;
+            }
+
+            scheduler.runTask(() -> {
+                plugin.getLogger()
+                        .info("An update for PlaceholderAPI (v" + getModrinthVersion() + ") is available at:");
+                plugin.getLogger()
+                        .info("https://modrinth.com/plugin/placeholderapi");
+                Bukkit.getPluginManager().registerEvents(this, plugin);
+            });
+        });
+    }
+
+    private boolean modrinthIsNewer() {
+        if (modrinthVersion == null || modrinthVersion.isEmpty()) {
+            return false;
+        }
+
+        int[] plV = toReadable(pluginVersion);
+        int[] spV = toReadable(modrinthVersion);
+
+        if (plV[0] < spV[0]) {
+            return true;
+        } else if ((plV[1] < spV[1])) {
+            return true;
+        } else {
+            return plV[2] < spV[2];
+        }
+    }
+
+    private int[] toReadable(String version) {
+        if (version.contains("-DEV")) {
+            version = version.split("-DEV")[0];
+        }
+
+        return Arrays.stream(version.split("\\.")).mapToInt(Integer::parseInt).toArray();
+    }
+
+    @EventHandler(priority = EventPriority.MONITOR)
+    public void onJoin(PlayerJoinEvent e) {
+        if (e.getPlayer().hasPermission("placeholderapi.updatenotify")) {
+            Msg.msg(e.getPlayer(),
+                    "&bAn update for &fPlaceholder&7API &e(&fPlaceholder&7API &fv" + getModrinthVersion()
+                            + "&e)"
+                    , "&bis available at &ehttps://modrinth.com/plugin/placeholderapi");
+        }
     }
-  }
 }

src/main/java/me/clip/placeholderapi/util/ExpansionSafetyCheck.java

@@ -18,14 +18,14 @@ import java.util.stream.Collectors;
 public final class ExpansionSafetyCheck {
     private static final String MESSAGE =
             "\n###############################################\n" +
-            "###############################################\n" +
+                    "###############################################\n" +
-            "PlaceholderAPI performs checks at startup and /papi reload for known malicious expansions. If you're seeing this message, there are the following malicious expansions in plugins/PlaceholderAPI/expansions.\n" +
+                    "PlaceholderAPI performs checks at startup and /papi reload for known malicious expansions. If you're seeing this message, there are the following malicious expansions in plugins/PlaceholderAPI/expansions.\n" +
-            "%s" +
+                    "%s" +
-            "To prevent further infection PlaceholderAPI has stopped the server.\n" +
+                    "To prevent further infection PlaceholderAPI has stopped the server.\n" +
-            "If you're seeing this message after updating PAPI, your server may have been infected for some time, so best practice is a complete system wipe and reinstall of your server software and plugins to be safe.\n" +
+                    "If you're seeing this message after updating PAPI, your server may have been infected for some time, so best practice is a complete system wipe and reinstall of your server software and plugins to be safe.\n" +
-            "If you're seeing this after downloading an expansion however, PAPI hasn't loaded any of the malicious expansions above so you should be safe to simply delete the expansion in question.\n" +
+                    "If you're seeing this after downloading an expansion however, PAPI hasn't loaded any of the malicious expansions above so you should be safe to simply delete the expansion in question.\n" +
-            "###############################################\n" +
+                    "###############################################\n" +
-            "###############################################";
+                    "###############################################";
 
     private final PlaceholderAPIPlugin main;
 

src/main/java/me/clip/placeholderapi/util/FileUtil.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/util/Format.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/util/Futures.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/util/Msg.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/util/TimeFormat.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/java/me/clip/placeholderapi/util/TimeUtil.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

src/main/resources/config.yml

@@ -6,10 +6,10 @@
 # Expansions: https://placeholderapi.com/ecloud
 # Wiki: https://wiki.placeholderapi.com/
 # Discord: https://helpch.at/discord
+# If you're seeing performance issues with plugins that use component replacement, or things don't look quite right,
+# switch to the replacer provided by adventure itself by changing use_adventure_provided_replacer to true
 # No placeholders are provided with this plugin by default.
 # Download placeholders: /papi ecloud
-#
-# CHANGE use_regex_component_replacer to true if you notice new minecraft text features not getting their placeholders replaced properly -- may cause performance issues
 check_updates: true
 cloud_enabled: true
 cloud_sorting: "name"
@@ -17,6 +17,6 @@ boolean:
   'true': 'yes'
   'false': 'no'
 date_format: MM/dd/yy HH:mm:ss
-use_regex_component_replacer: false
 detect_malicious_expansions: true
+use_adventure_provided_replacer: false
 debug: false

src/main/resources/plugin.yml

@@ -12,8 +12,6 @@ commands:
   placeholderapi:
     description: "PlaceholderAPI Command"
     aliases: ["papi"]
-  test:
-    description: "yes"
 
 permissions:
   placeholderapi.*:

src/paper/java/me/clip/placeholderapi/PAPIComponents.java

@@ -0,0 +1,184 @@
+/*
+ * This file is part of PlaceholderAPI
+ *
+ * PlaceholderAPI
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
+ *
+ * PlaceholderAPI free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * PlaceholderAPI is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.clip.placeholderapi;
+
+import me.clip.placeholderapi.replacer.ComponentReplacer;
+import me.clip.placeholderapi.replacer.ExactReplacer;
+import me.clip.placeholderapi.replacer.RelationalExactReplacer;
+import me.clip.placeholderapi.replacer.Replacer;
+import net.kyori.adventure.text.Component;
+import org.bukkit.OfflinePlayer;
+import org.bukkit.entity.Player;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import static me.clip.placeholderapi.PlaceholderAPI.RELATIONAL_PLACEHOLDER_PATTERN;
+
+public final class PAPIComponents {
+    private static final Replacer PERCENT_EXACT_REPLACER = new ExactReplacer('%', '%');
+    private static final Replacer BRACKET_EXACT_REPLACER = new ExactReplacer('{', '}');
+    private static final RelationalExactReplacer RELATIONAL_EXACT_REPLACER = new RelationalExactReplacer();
+
+    /**
+     * Translates all placeholders into their corresponding values.
+     * <br>The pattern of a valid placeholder is {@literal %<identifier>_<params>%}.
+     *
+     * @param player Player to parse the placeholders against
+     * @param component Component to set the placeholder values in
+     * @return Component containing all translated placeholders
+     */
+    @NotNull
+    public static Component setPlaceholders(final OfflinePlayer player, @NotNull final Component component) {
+        if (PlaceholderAPIPlugin.getInstance().getPlaceholderAPIConfig().useAdventureProvidedReplacer()) {
+            return component.replaceText(config -> config.match(PlaceholderAPI.PLACEHOLDER_PATTERN).replacement((result, builder) ->
+                    builder.content(PERCENT_EXACT_REPLACER.apply(result.group(), player, PlaceholderAPIPlugin.getInstance().getLocalExpansionManager()::getExpansion))));
+        }
+
+        return ComponentReplacer.replace(component, str -> PlaceholderAPI.setPlaceholders(player, str));
+    }
+
+    /**
+     * Translates all placeholders into their corresponding values.
+     * <br>The pattern of a valid placeholder is {@literal %<identifier>_<params>%}.
+     *
+     * @param player Player to parse the placeholders against
+     * @param components List of Components to set the placeholder values in
+     * @return List of Components containing all translated placeholders
+     */
+    @NotNull
+    public static List<Component> setPlaceholders(final OfflinePlayer player, @NotNull final List<Component> components) {
+        return components.stream().map(component -> setPlaceholders(player, component)).collect(Collectors.toList());
+    }
+
+    /**
+     * Translates all placeholders into their corresponding values.
+     * <br>The pattern of a valid placeholder is {@literal %<identifier>_<params>%}.
+     *
+     * @param player Player to parse the placeholders against
+     * @param component Component to set the placeholder values in
+     * @return Component containing all translated placeholders
+     */
+    @NotNull
+    public static Component setPlaceholders(final Player player, @NotNull final Component component) {
+        return setPlaceholders((OfflinePlayer) player, component);
+    }
+
+    /**
+     * Translates all placeholders into their corresponding values.
+     * <br>The pattern of a valid placeholder is {@literal %<identifier>_<params>%}.
+     *
+     * @param player Player to parse the placeholders against
+     * @param components List of Components to set the placeholder values in
+     * @return List of components containing all translated placeholders
+     */
+    @NotNull
+    public static List<Component> setPlaceholders(final Player player, @NotNull final List<Component> components) {
+        return setPlaceholders((OfflinePlayer) player, components);
+    }
+
+    /**
+     * Translates all placeholders into their corresponding values.
+     * <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
+     *
+     * @param player Player to parse the placeholders against
+     * @param component Component to set the placeholder values in
+     * @return Component containing all translated placeholders
+     */
+    @NotNull
+    public static Component setBracketPlaceholders(final OfflinePlayer player, @NotNull final Component component) {
+        if (PlaceholderAPIPlugin.getInstance().getPlaceholderAPIConfig().useAdventureReplacer()) {
+            return component.replaceText(config -> config.match(PlaceholderAPI.BRACKET_PLACEHOLDER_PATTERN).replacement((result, builder) ->
+                    builder.content(BRACKET_EXACT_REPLACER.apply(result.group(), player, PlaceholderAPIPlugin.getInstance().getLocalExpansionManager()::getExpansion))));
+        }
+
+        return ComponentReplacer.replace(component, str -> PlaceholderAPI.setBracketPlaceholders(player, str));
+    }
+
+    /**
+     * Translates all placeholders into their corresponding values.
+     * <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
+     *
+     * @param player Player to parse the placeholders against
+     * @param components List of Components to set the placeholder values in
+     * @return List of Components containing all translated placeholders
+     */
+    @NotNull
+    public static List<Component> setBracketPlaceholders(final OfflinePlayer player, @NotNull final List<Component> components) {
+        return components.stream().map(component -> setBracketPlaceholders(player, component)).collect(Collectors.toList());
+    }
+
+    /**
+     * Translates all placeholders into their corresponding values.
+     * <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
+     *
+     * @param player Player to parse the placeholders against
+     * @param component Component to set the placeholder values in
+     * @return Component containing all translated placeholders
+     */
+    @NotNull
+    public static Component setBracketPlaceholders(final Player player, @NotNull final Component component) {
+        return setBracketPlaceholders((OfflinePlayer) player, component);
+    }
+
+    /**
+     * Translates all placeholders into their corresponding values.
+     * <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
+     *
+     * @param player Player to parse the placeholders against
+     * @param components List of Components to set the placeholder values in
+     * @return List of Components containing all translated placeholders
+     */
+    @NotNull
+    public static List<Component> setBracketPlaceholders(final Player player, @NotNull final List<Component> components) {
+        return setBracketPlaceholders((OfflinePlayer) player, components);
+    }
+
+    /**
+     * set relational placeholders in the text specified placeholders are matched with the pattern
+     * {@literal %<rel_(identifier)_(params)>%} when set with this method
+     *
+     * @param one First player to compare
+     * @param two Second player to compare
+     * @param component Component to parse the placeholders in
+     * @return The Component containing the parsed relational placeholders
+     */
+    public static Component setRelationalPlaceholders(Player one, Player two, Component component) {
+        //todo: custom replacer
+        return component.replaceText(config -> config.match(RELATIONAL_PLACEHOLDER_PATTERN).replacement((result, builder) ->
+                builder.content(RELATIONAL_EXACT_REPLACER.apply(result.group(2), one, two, PlaceholderAPIPlugin.getInstance().getLocalExpansionManager()::getExpansion))));
+    }
+
+    /**
+     * Translate placeholders in the provided List based on the relation of the two provided players.
+     * <br>The pattern of a valid placeholder is {@literal %rel_<identifier>_<param>%}.
+     *
+     * @param one Player to compare
+     * @param two Player to compare
+     * @param components List of Components to parse the placeholder values to
+     * @return The List of Components containing the parsed relational placeholders
+     */
+    public static List<Component> setRelationalPlaceholders(Player one, Player two, List<Component> components) {
+        return components.stream().map(line -> setRelationalPlaceholders(one, two, line))
+                .collect(Collectors.toList());
+    }
+}

src/paper/java/me/clip/placeholderapi/replacer/ComponentReplacer.java

@@ -0,0 +1,174 @@
+package me.clip.placeholderapi.replacer;
+
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.nbt.api.BinaryTagHolder;
+import net.kyori.adventure.text.*;
+import net.kyori.adventure.text.event.ClickEvent;
+import net.kyori.adventure.text.event.DataComponentValue;
+import net.kyori.adventure.text.event.HoverEvent;
+import net.kyori.adventure.text.format.Style;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+
+public class ComponentReplacer {
+    @NotNull
+    public static Component replace(@NotNull final Component component, @NotNull final Function<String, String> replacer) {
+        return rebuild(component, replacer);
+    }
+
+    @NotNull
+    private static Component rebuild(@NotNull final Component component, @NotNull final Function<String, String> replacer) {
+        Component rebuilt;
+
+        if (component instanceof TextComponent) {
+            final TextComponent text = (TextComponent) component;
+            final String replaced = replacer.apply(text.content());
+
+            rebuilt = Component.text(replaced);
+        } else if (component instanceof TranslatableComponent) {
+            final TranslatableComponent translatable = (TranslatableComponent) component;
+            final List<Component> arguments = new ArrayList<>();
+
+            for (final ComponentLike arg : translatable.arguments()) {
+                arguments.add(rebuild(arg.asComponent(), replacer));
+            }
+
+            rebuilt = Component.translatable(translatable.key(), arguments);
+        } else if (component instanceof KeybindComponent) {
+            final KeybindComponent keybind = (KeybindComponent) component;
+            rebuilt = Component.keybind(keybind.keybind());
+        } else if (component instanceof ScoreComponent) {
+            final ScoreComponent score = (ScoreComponent) component;
+            rebuilt = Component.score(score.name(), score.objective());
+        } else if (component instanceof SelectorComponent) {
+            final SelectorComponent selector = (SelectorComponent) component;
+            rebuilt = Component.selector(selector.pattern());
+        } else {
+            rebuilt = Component.empty();
+        }
+
+        rebuilt = rebuilt.style(rebuildStyle(component.style(), replacer));
+
+        if (!component.children().isEmpty()) {
+            final List<Component> children = new ArrayList<>();
+            for (Component child : component.children()) {
+                children.add(rebuild(child, replacer));
+            }
+            rebuilt = rebuilt.children(children);
+        }
+
+        return rebuilt;
+    }
+
+    @NotNull
+    private static Style rebuildStyle(@NotNull final Style style, @NotNull final Function<String, String> replacer) {
+        final Style.Builder builder = style.toBuilder();
+        final ClickEvent click = style.clickEvent();
+
+        if (click != null) {
+            builder.clickEvent(rebuildClickEvent(click, replacer));
+        }
+
+        final HoverEvent<?> hover = style.hoverEvent();
+
+        if (hover != null) {
+            builder.hoverEvent(rebuildHoverEvent(hover, replacer));
+        }
+
+        return builder.build();
+    }
+
+    @NotNull
+    private static ClickEvent rebuildClickEvent(@NotNull final ClickEvent click, @NotNull final Function<String, String> replacer) {
+        final ClickEvent.Payload payload = click.payload();
+
+        if (!(payload instanceof ClickEvent.Payload.Text)) {
+            return click;
+        }
+
+        final String original = ((ClickEvent.Payload.Text) payload).value();
+        final String replaced = replacer.apply(original);
+
+        final ClickEvent.Action action = click.action();
+
+        switch (action) {
+            case OPEN_URL:
+                return ClickEvent.openUrl(replaced);
+            case OPEN_FILE:
+                return ClickEvent.openFile(replaced);
+            case RUN_COMMAND:
+                return ClickEvent.runCommand(replaced);
+            case SUGGEST_COMMAND:
+                return ClickEvent.suggestCommand(replaced);
+            case COPY_TO_CLIPBOARD:
+                return ClickEvent.copyToClipboard(replaced);
+            default:
+                return click;
+        }
+    }
+
+    @NotNull
+    private static HoverEvent<?> rebuildHoverEvent(@NotNull final HoverEvent<?> hover, @NotNull final Function<String, String> replacer) {
+        final Object value = hover.value();
+
+        if (value instanceof Component) {
+            final Component rebuilt = rebuild((Component) value, replacer);
+            return HoverEvent.showText(rebuilt);
+        }
+
+        if (value instanceof HoverEvent.ShowItem) {
+            return rebuildShowItem((HoverEvent.ShowItem) value, replacer);
+        }
+
+        if (value instanceof HoverEvent.ShowEntity) {
+            final HoverEvent.ShowEntity entity = (HoverEvent.ShowEntity) value;
+
+            Component rebuiltName = null;
+            if (entity.name() != null) {
+                rebuiltName = rebuild(entity.name(), replacer);
+            }
+
+            return HoverEvent.showEntity(entity.type(), entity.id(), rebuiltName);
+        }
+
+        return hover;
+    }
+
+    @NotNull
+    private static HoverEvent<?> rebuildShowItem(@NotNull final HoverEvent.ShowItem item, @NotNull final Function<String, String> replacer) {
+        final BinaryTagHolder nbt = item.nbt();
+
+        if (nbt != null && !nbt.string().isEmpty()) {
+            final String replaced = replacer.apply(nbt.string());
+
+            return HoverEvent.showItem(item.item(), item.count(), BinaryTagHolder.binaryTagHolder(replaced));
+        }
+
+        //I'm not 100% sure this is how we're meant to support data components but let's give it a go and see if it causes any issues :)
+        final Map<Key, DataComponentValue> components = item.dataComponents();
+
+        if (!components.isEmpty()) {
+            final Map<Key, DataComponentValue> rebuilt = new HashMap<>();
+
+            for (final Map.Entry<Key, DataComponentValue> entry : components.entrySet()) {
+                final DataComponentValue value = entry.getValue();
+
+                if (!(value instanceof BinaryTagHolder)) {
+                    rebuilt.put(entry.getKey(), value);
+                    continue;
+                }
+
+                rebuilt.put(entry.getKey(), BinaryTagHolder.binaryTagHolder(replacer.apply(((BinaryTagHolder) value).string())));
+            }
+
+            return HoverEvent.showItem(item.item(), item.count(), rebuilt);
+        }
+
+        return HoverEvent.showItem(item);
+    }
+}

src/paper/java/me/clip/placeholderapi/replacer/ExactReplacer.java

@@ -1,3 +1,23 @@
+/*
+ * This file is part of PlaceholderAPI
+ *
+ * PlaceholderAPI
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
+ *
+ * PlaceholderAPI free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * PlaceholderAPI is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package me.clip.placeholderapi.replacer;
 
 import me.clip.placeholderapi.expansion.PlaceholderExpansion;
@@ -8,9 +28,17 @@ import org.jetbrains.annotations.Nullable;
 import java.util.function.Function;
 import java.util.regex.Pattern;
 
-public class ExactReplacer implements Replacer {
+public final class ExactReplacer implements Replacer {
     private static final Pattern DELIMITER = Pattern.compile("_");
 
+    private final char start;
+    private final char end;
+
+    public ExactReplacer(final char start, final char end) {
+        this.start = start;
+        this.end = end;
+    }
+
     @NotNull
     @Override
     public String apply(@NotNull String text, @Nullable final OfflinePlayer player,
@@ -26,7 +54,7 @@ public class ExactReplacer implements Replacer {
         }
 
         if (expansion == null) {
-            return text;
+            return start + text + end;
         }
 
         final String params;
@@ -40,7 +68,7 @@ public class ExactReplacer implements Replacer {
         final String result = expansion.onRequest(player, params);
 
         if (result == null) {
-            return text;
+            return start + text + end;
         }
 
         return result;

src/paper/java/me/clip/placeholderapi/replacer/RelationalExactReplacer.java

@@ -0,0 +1,73 @@
+/*
+ * This file is part of PlaceholderAPI
+ *
+ * PlaceholderAPI
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
+ *
+ * PlaceholderAPI free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * PlaceholderAPI is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.clip.placeholderapi.replacer;
+
+import me.clip.placeholderapi.expansion.PlaceholderExpansion;
+import me.clip.placeholderapi.expansion.Relational;
+import org.bukkit.OfflinePlayer;
+import org.bukkit.entity.Player;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.function.Function;
+import java.util.regex.Pattern;
+
+public final class RelationalExactReplacer {
+    private static final Pattern DELIMITER = Pattern.compile("_");
+
+    @NotNull
+    public String apply(@NotNull String text, @Nullable final Player player1,
+                        @Nullable final Player player2, @NotNull final Function<String,
+                        @Nullable PlaceholderExpansion> lookup) {
+        final String[] parts = DELIMITER.split(text);
+        final PlaceholderExpansion expansion;
+
+        if (parts.length == 0) {
+            expansion = lookup.apply(text);
+        } else {
+            expansion = lookup.apply(parts[0]);
+        }
+
+        if (expansion == null) {
+            return "%rel_" + text + '%';
+        }
+
+        if (!(expansion instanceof Relational)) {
+            return "%rel_" + text + '%';
+        }
+
+        final String params;
+
+        if (text.endsWith("_")) {
+            params = "";
+        } else {
+            params = text.substring(text.indexOf('_') + 1);
+        }
+
+        final String result = ((Relational) expansion).onPlaceholderRequest(player1, player2, params);
+
+        if (result == null) {
+            return "%rel_" + text + '%';
+        }
+
+        return result;
+    }
+}

src/test/java/me/clip/placeholderapi/Values.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -30,64 +30,64 @@ import org.jetbrains.annotations.Nullable;
 
 public interface Values {
 
-  String SMALL_TEXT = "My name is %player_name%";
+    String SMALL_TEXT = "My name is %player_name%";
-  String LARGE_TEXT = "My name is %player_name% and my location is (%player_x%, %player_y%, %player_z%), this placeholder is invalid %server_name%";
+    String LARGE_TEXT = "My name is %player_name% and my location is (%player_x%, %player_y%, %player_z%), this placeholder is invalid %server_name%";
 
-  ImmutableMap<String, PlaceholderExpansion> PLACEHOLDERS = ImmutableMap.<String, PlaceholderExpansion>builder()
+    ImmutableMap<String, PlaceholderExpansion> PLACEHOLDERS = ImmutableMap.<String, PlaceholderExpansion>builder()
-      .put("player", new MockPlayerPlaceholderExpansion())
+            .put("player", new MockPlayerPlaceholderExpansion())
-      .build();
+            .build();
 
 
-  Replacer CHARS_REPLACER = new CharsReplacer(Replacer.Closure.PERCENT);
+    Replacer CHARS_REPLACER = new CharsReplacer(Replacer.Closure.PERCENT);
 
 
-  final class MockPlayerPlaceholderExpansion extends PlaceholderExpansion {
+    final class MockPlayerPlaceholderExpansion extends PlaceholderExpansion {
 
-    public static final String PLAYER_X = "10";
+        public static final String PLAYER_X = "10";
-    public static final String PLAYER_Y = "20";
+        public static final String PLAYER_Y = "20";
-    public static final String PLAYER_Z = "30";
+        public static final String PLAYER_Z = "30";
-    public static final String PLAYER_NAME = "Sxtanna";
+        public static final String PLAYER_NAME = "Sxtanna";
 
 
-    @NotNull
+        @NotNull
-    @Override
+        @Override
-    public String getIdentifier() {
+        public String getIdentifier() {
-      return "player";
+            return "player";
+        }
+
+        @NotNull
+        @Override
+        public String getAuthor() {
+            return "Sxtanna";
+        }
+
+        @NotNull
+        @Override
+        public String getVersion() {
+            return "1.0";
+        }
+
+        @Override
+        public String onRequest(@Nullable final OfflinePlayer player, @NotNull final String params) {
+            final String[] parts = params.split("_");
+            if (parts.length == 0) {
+                return null;
+            }
+
+            switch (parts[0]) {
+                case "name":
+                    return PLAYER_NAME;
+                case "x":
+                    return PLAYER_X;
+                case "y":
+                    return PLAYER_Y;
+                case "z":
+                    return PLAYER_Z;
+            }
+
+            return null;
+        }
+
     }
 
-    @NotNull
-    @Override
-    public String getAuthor() {
-      return "Sxtanna";
-    }
-
-    @NotNull
-    @Override
-    public String getVersion() {
-      return "1.0";
-    }
-
-    @Override
-    public String onRequest(@Nullable final OfflinePlayer player, @NotNull final String params) {
-      final String[] parts = params.split("_");
-      if (parts.length == 0) {
-        return null;
-      }
-
-      switch (parts[0]) {
-        case "name":
-          return PLAYER_NAME;
-        case "x":
-          return PLAYER_X;
-        case "y":
-          return PLAYER_Y;
-        case "z":
-          return PLAYER_Z;
-      }
-
-      return null;
-    }
-
-  }
-
 }

src/test/java/me/clip/placeholderapi/replacer/ReplacerBenchmarks.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -25,14 +25,14 @@ import org.openjdk.jmh.annotations.Benchmark;
 
 public class ReplacerBenchmarks {
 
-  @Benchmark
+    @Benchmark
-  public void measureCharsReplacerSmallText() {
+    public void measureCharsReplacerSmallText() {
-    Values.CHARS_REPLACER.apply(Values.SMALL_TEXT, null, Values.PLACEHOLDERS::get);
+        Values.CHARS_REPLACER.apply(Values.SMALL_TEXT, null, Values.PLACEHOLDERS::get);
-  }
+    }
 
-  @Benchmark
+    @Benchmark
-  public void measureCharsReplacerLargeText() {
+    public void measureCharsReplacerLargeText() {
-    Values.CHARS_REPLACER.apply(Values.LARGE_TEXT, null, Values.PLACEHOLDERS::get);
+        Values.CHARS_REPLACER.apply(Values.LARGE_TEXT, null, Values.PLACEHOLDERS::get);
-  }
+    }
 
 }

src/test/java/me/clip/placeholderapi/replacer/ReplacerUnitTester.java

@@ -2,7 +2,7 @@
  * This file is part of PlaceholderAPI
  *
  * PlaceholderAPI
- * Copyright (c) 2015 - 2024 PlaceholderAPI Team
+ * Copyright (c) 2015 - 2026 PlaceholderAPI Team
  *
  * PlaceholderAPI free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -31,33 +31,33 @@ import org.junit.jupiter.api.Test;
 
 public final class ReplacerUnitTester {
 
-  @Test
+    @Test
-  void testCharsReplacerProducesExpectedSingleValue() {
+    void testCharsReplacerProducesExpectedSingleValue() {
-    assertEquals(PLAYER_NAME,
+        assertEquals(PLAYER_NAME,
-        Values.CHARS_REPLACER.apply("%player_name%", null, Values.PLACEHOLDERS::get));
+                Values.CHARS_REPLACER.apply("%player_name%", null, Values.PLACEHOLDERS::get));
-  }
+    }
 
-  @Test
+    @Test
-  void testCharsReplacerProducesExpectedSentence() {
+    void testCharsReplacerProducesExpectedSentence() {
-    assertEquals(String.format(
+        assertEquals(String.format(
-        "My name is %s and my location is (%s, %s, %s), this placeholder is invalid %%server_name%%",
+                        "My name is %s and my location is (%s, %s, %s), this placeholder is invalid %%server_name%%",
-        PLAYER_NAME, PLAYER_X, PLAYER_Y, PLAYER_Z),
+                        PLAYER_NAME, PLAYER_X, PLAYER_Y, PLAYER_Z),
-        Values.CHARS_REPLACER.apply(Values.LARGE_TEXT, null, Values.PLACEHOLDERS::get));
+                Values.CHARS_REPLACER.apply(Values.LARGE_TEXT, null, Values.PLACEHOLDERS::get));
-  }
+    }
 
-  @Test
+    @Test
-  void testResultsAreTheSameAsReplacement() {
+    void testResultsAreTheSameAsReplacement() {
-    final String resultChars = Values.CHARS_REPLACER
+        final String resultChars = Values.CHARS_REPLACER
-        .apply("%player_name%", null, Values.PLACEHOLDERS::get);
+                .apply("%player_name%", null, Values.PLACEHOLDERS::get);
 
-    assertEquals(PLAYER_NAME, resultChars);
+        assertEquals(PLAYER_NAME, resultChars);
-  }
+    }
 
-  @Test
+    @Test
-  void testCharsReplacerIgnoresMalformed() {
+    void testCharsReplacerIgnoresMalformed() {
-    final String text = "10% and %hello world 15%";
+        final String text = "10% and %hello world 15%";
 
-    assertEquals(text, Values.CHARS_REPLACER.apply(text, null, Values.PLACEHOLDERS::get));
+        assertEquals(text, Values.CHARS_REPLACER.apply(text, null, Values.PLACEHOLDERS::get));
-  }
+    }
 
 }