comparator) {
+ this.comparator = comparator;
+ }
+
+
+ @Override
+ public final int compare(final CloudExpansion expansion1, final CloudExpansion expansion2) {
+ return comparator.compare(expansion1, expansion2);
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/configuration/PlaceholderAPIConfig.java b/src/main/java/at/helpch/placeholderapi/configuration/PlaceholderAPIConfig.java
new file mode 100644
index 0000000..a4b9199
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/configuration/PlaceholderAPIConfig.java
@@ -0,0 +1,29 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.configuration;
+
+import com.google.gson.annotations.JsonAdapter;
+import org.jetbrains.annotations.NotNull;
+
+public record PlaceholderAPIConfig(boolean cloudEnabled, boolean debugMode, @NotNull ExpansionSort cloudSorting,
+ @NotNull BooleanValue booleanValue, @NotNull String dateFormat) {
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/events/ExpansionRegisterEvent.java b/src/main/java/at/helpch/placeholderapi/events/ExpansionRegisterEvent.java
new file mode 100644
index 0000000..c5d0505
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/events/ExpansionRegisterEvent.java
@@ -0,0 +1,89 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.events;
+
+import at.helpch.placeholderapi.expansion.PlaceholderExpansion;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.Event;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This event indicates that a single {@link PlaceholderExpansion PlaceholderExpansion} has
+ * been registered in PlaceholderAPI.
+ *
+ * To know when all Expansions have been registered, use the
+ * {@link at.helpch.placeholderapi.events.ExpansionsLoadedEvent ExpansionsLoadedEvent} instead.
+ */
+public final class ExpansionRegisterEvent extends Event implements Cancellable {
+
+ @NotNull
+ private static final HandlerList HANDLERS = new HandlerList();
+ @NotNull
+ private final PlaceholderExpansion expansion;
+ private boolean cancelled;
+
+ public ExpansionRegisterEvent(@NotNull final PlaceholderExpansion expansion) {
+ this.expansion = expansion;
+ }
+
+ @NotNull
+ public static HandlerList getHandlerList() {
+ return HANDLERS;
+ }
+
+ /**
+ * The {@link PlaceholderExpansion PlaceholderExpansion} that was registered in PlaceholderAPI.
+ *
The PlaceholderExpansion will be available for use when the event
+ * {@link #isCancelled() was not cancelled}!
+ *
+ * @return Current instance of the registered {@link PlaceholderExpansion PlaceholderExpansion}
+ */
+ @NotNull
+ public PlaceholderExpansion getExpansion() {
+ return expansion;
+ }
+
+ /**
+ * Indicates if this event was cancelled or not.
+ *
A cancelled Event will result in the {@link #getExpansion() PlaceholderExpansion} NOT
+ * being added to PlaceholderAPI's internal list and will therefore be considered not registered
+ * anymore.
+ *
+ * @return Whether the event has been cancelled or not.
+ */
+ @Override
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ @Override
+ public void setCancelled(boolean cancelled) {
+ this.cancelled = cancelled;
+ }
+
+ @NotNull
+ @Override
+ public HandlerList getHandlers() {
+ return HANDLERS;
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/events/ExpansionUnregisterEvent.java b/src/main/java/at/helpch/placeholderapi/events/ExpansionUnregisterEvent.java
new file mode 100644
index 0000000..92aea32
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/events/ExpansionUnregisterEvent.java
@@ -0,0 +1,70 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.events;
+
+import at.helpch.placeholderapi.expansion.PlaceholderExpansion;
+import org.bukkit.event.Event;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This event indicates that a {@link PlaceholderExpansion PlaceholderExpansion} has been
+ * unregistered by PlaceholderAPI.
+ *
+ *
Note that this event is triggered before the PlaceholderExpansion is completely
+ * removed.
+ *
This includes removing any Listeners, stopping active tasks and clearing the cache of
+ * the PlaceholderExpansion.
+ */
+public final class ExpansionUnregisterEvent extends Event {
+
+ @NotNull
+ private static final HandlerList HANDLERS = new HandlerList();
+
+ @NotNull
+ private final PlaceholderExpansion expansion;
+
+ public ExpansionUnregisterEvent(@NotNull final PlaceholderExpansion expansion) {
+ this.expansion = expansion;
+ }
+
+ @NotNull
+ public static HandlerList getHandlerList() {
+ return HANDLERS;
+ }
+
+ /**
+ * The {@link PlaceholderExpansion PlaceholderExpansion} that was unregistered.
+ *
+ * @return The {@link PlaceholderExpansion PlaceholderExpansion} instance.
+ */
+ @NotNull
+ public PlaceholderExpansion getExpansion() {
+ return expansion;
+ }
+
+ @NotNull
+ @Override
+ public HandlerList getHandlers() {
+ return HANDLERS;
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/events/ExpansionsLoadedEvent.java b/src/main/java/at/helpch/placeholderapi/events/ExpansionsLoadedEvent.java
new file mode 100644
index 0000000..a63e2c5
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/events/ExpansionsLoadedEvent.java
@@ -0,0 +1,74 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.events;
+
+
+import java.util.Collections;
+import java.util.List;
+
+import at.helpch.placeholderapi.expansion.PlaceholderExpansion;
+import org.bukkit.event.Event;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This event indicated that all {@link PlaceholderExpansion PlaceholderExpansions} have
+ * been registered in PlaceholderAPI and can now be used.
+ *
This even will also be triggered whenever PlaceholderAPI gets reloaded.
+ *
+ *
All PlaceholderExpansions, except for those loaded by plugins, are loaded
+ * after Spigot triggered its ServerLoadEvent (1.13+), or after PlaceholderAPI has been enabled.
+ */
+public class ExpansionsLoadedEvent extends Event {
+
+ private final List expansions;
+
+ public ExpansionsLoadedEvent(List expansions) {
+ this.expansions = Collections.unmodifiableList(expansions);
+ }
+
+ /**
+ * Returns a unmodifiable list of {@link PlaceholderExpansion PlaceholderExpansions} that
+ * have been registered by PlaceholderAPI.
+ *
+ * This list does not include manually registered PlaceholderExpansions.
+ *
+ * @return List of {@link PlaceholderExpansion registered PlaceholderExpansions}.
+ */
+ @NotNull
+ public final List getExpansions() {
+ return expansions;
+ }
+
+ @NotNull
+ private static final HandlerList HANDLERS = new HandlerList();
+
+ @NotNull
+ @Override
+ public HandlerList getHandlers() {
+ return HANDLERS;
+ }
+
+ @NotNull
+ public static HandlerList getHandlerList() {
+ return HANDLERS;
+ }
+}
diff --git a/src/main/java/at/helpch/placeholderapi/events/PlaceholderHookUnloadEvent.java b/src/main/java/at/helpch/placeholderapi/events/PlaceholderHookUnloadEvent.java
new file mode 100644
index 0000000..5a86703
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/events/PlaceholderHookUnloadEvent.java
@@ -0,0 +1,70 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.events;
+
+import at.helpch.placeholderapi.PlaceholderHook;
+import org.bukkit.event.Event;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * @deprecated This event is no longer used.
+ */
+@Deprecated
+public final class PlaceholderHookUnloadEvent extends Event {
+
+ @NotNull
+ private static final HandlerList HANDLERS = new HandlerList();
+
+
+ @NotNull
+ private final String plugin;
+ @NotNull
+ private final PlaceholderHook placeholderHook;
+
+ public PlaceholderHookUnloadEvent(@NotNull final String plugin,
+ @NotNull final PlaceholderHook placeholderHook) {
+ this.plugin = plugin;
+ this.placeholderHook = placeholderHook;
+ }
+
+ @NotNull
+ public static HandlerList getHandlerList() {
+ return HANDLERS;
+ }
+
+ @NotNull
+ public String getHookName() {
+ return plugin;
+ }
+
+ @NotNull
+ public PlaceholderHook getHook() {
+ return placeholderHook;
+ }
+
+ @NotNull
+ @Override
+ public HandlerList getHandlers() {
+ return HANDLERS;
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/exceptions/NoDefaultCommandException.java b/src/main/java/at/helpch/placeholderapi/exceptions/NoDefaultCommandException.java
new file mode 100644
index 0000000..dc608e8
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/exceptions/NoDefaultCommandException.java
@@ -0,0 +1,29 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.exceptions;
+
+public final class NoDefaultCommandException extends RuntimeException {
+
+ public NoDefaultCommandException(final String message) {
+ super(message);
+ }
+}
+
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/Cacheable.java b/src/main/java/at/helpch/placeholderapi/expansion/Cacheable.java
new file mode 100644
index 0000000..26e8d0f
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/Cacheable.java
@@ -0,0 +1,38 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion;
+
+/**
+ * Classes implementing this interface will have a {@link #clear() clear void} that is called
+ * by PlaceholderAPI whenever the {@link at.helpch.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}
+ * is unregistered.
+ *
+ * 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
+ */
+ void clear();
+}
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/Cleanable.java b/src/main/java/at/helpch/placeholderapi/expansion/Cleanable.java
new file mode 100644
index 0000000..4311e20
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/Cleanable.java
@@ -0,0 +1,42 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion;
+
+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.
+ *
+ *
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.
+ *
+ * @author Ryan McCarthy
+ */
+public interface Cleanable {
+
+ /**
+ * Called when a player leaves the server
+ *
+ * @param p (@link Player} who left the server
+ */
+ void cleanup(Player p);
+}
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/Configurable.java b/src/main/java/at/helpch/placeholderapi/expansion/Configurable.java
new file mode 100644
index 0000000..5cec0b6
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/Configurable.java
@@ -0,0 +1,57 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion;
+
+import java.util.Map;
+
+/**
+ * Implementing this interface allows {@link at.helpch.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.
+ *
+ *
The entries will be added under {@code expansions} as their own section.
+ *
Example:
+ * returning a Map with key {@code foo} and value {@code bar} will result in the following config entry:
+ *
+ *
+ * expansions:
+ * myexpansion:
+ * foo: "bar"
+ *
+ *
+ * The configuration is set before the PlaceholderExpansion is registered!
+ *
+ * @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 key and value pairs are set under a section named after your
+ * {@link at.helpch.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion} in the
+ * {@code expansions} section of the config.
+ *
+ * @return Map of config path / values which need to be added / removed from the PlaceholderAPI
+ * config.yml file
+ */
+ Map getDefaults();
+}
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/NMSVersion.java b/src/main/java/at/helpch/placeholderapi/expansion/NMSVersion.java
new file mode 100644
index 0000000..944c352
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/NMSVersion.java
@@ -0,0 +1,81 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion;
+
+public enum NMSVersion {
+
+ UNKNOWN("unknown"),
+ SPIGOT_1_7_R1("v1_7_R1"),
+ SPIGOT_1_7_R2("v1_7_R2"),
+ SPIGOT_1_7_R3("v1_7_R3"),
+ SPIGOT_1_7_R4("v1_7_R4"),
+ SPIGOT_1_8_R1("v1_8_R1"),
+ SPIGOT_1_8_R2("v1_8_R2"),
+ SPIGOT_1_8_R3("v1_8_R3"),
+ SPIGOT_1_9_R1("v1_9_R1"),
+ SPIGOT_1_9_R2("v1_9_R2"),
+ SPIGOT_1_10_R1("v1_10_R1"),
+ SPIGOT_1_11_R1("v1_11_R1"),
+ SPIGOT_1_12_R1("v1_12_R1"),
+ SPIGOT_1_13_R1("v1_13_R1"),
+ SPIGOT_1_13_R2("v1_13_R2"),
+ SPIGOT_1_14_R1("v1_14_R1"),
+ SPIGOT_1_15_R1("v1_15_R1"),
+ SPIGOT_1_16_R1("v1_16_R1"),
+ SPIGOT_1_16_R2("v1_16_R2"),
+ SPIGOT_1_16_R3("v1_16_R3"),
+ SPIGOT_1_17_R1("v1_17_R1"),
+ SPIGOT_1_18_R1("v1_18_R1"),
+ SPIGOT_1_19_R1("v1_19_R1"),
+ SPIGOT_1_19_R2("v1_19_R2"),
+ SPIGOT_1_19_R3("v1_19_R3"),
+ SPIGOT_1_20_R1("v1_20_R1"),
+ SPIGOT_1_20_R2("v1_20_R2"),
+ SPIGOT_1_20_R3("v1_20_R3"),
+ SPIGOT_1_20_R4("v1_20_R4"),
+ SPIGOT_1_21_R1("v1_21_R1"),
+ SPIGOT_1_21_R2("V1_21_R2"),
+ SPIGOT_1_21_R3("V1_21_R3"),
+ SPIGOT_1_21_R4("V1_21_R4"),
+ SPIGOT_1_21_R5("V1_21_R5"),
+ SPIGOT_1_21_R6("V1_21_R6");
+
+ private final String version;
+
+ NMSVersion(String 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 String getVersion() {
+ return version;
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/PlaceholderExpansion.java b/src/main/java/at/helpch/placeholderapi/expansion/PlaceholderExpansion.java
new file mode 100644
index 0000000..ba04f97
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/PlaceholderExpansion.java
@@ -0,0 +1,479 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.logging.Level;
+
+import at.helpch.placeholderapi.PlaceholderAPIPlugin;
+import at.helpch.placeholderapi.PlaceholderHook;
+import org.bukkit.Bukkit;
+import org.bukkit.configuration.ConfigurationSection;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Any class extending this will be able to get registered as a PlaceholderExpansion.
+ *
The registration either happens automatically when the jar file containing a
+ * class extending this one is located under the {@code PlaceholderAPI/expansions}
+ * directory or when the {@link #register()} method is called by said class.
+ */
+public abstract class PlaceholderExpansion extends PlaceholderHook {
+
+ /**
+ * The type is {@link Type#INTERNAL} by default.
+ * For external expansions, the type is updated on {@link at.helpch.placeholderapi.expansion.manager.LocalExpansionManager#register(Class) register}.
+ *
+ * @since 2.11.4
+ */
+ @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 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.
+ *
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 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.
+ *
The message will be prefixed with {@link #getName() [<expansion name>]}
+ *
+ * @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.
+ *
The message will be prefixed with {@link #getName() [<expansion name>]}
+ *
+ * @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".
+ *
The message will be prefixed with {@link #getName() [<expansion name>]}
+ *
+ * @param msg The message to log
+ */
+ public void info(String msg) {
+ log(Level.INFO, msg);
+ }
+
+ /**
+ * Logs the provided message with Level "warning".
+ *
The message will be prefixed with {@link #getName() [<expansion name>]}
+ *
+ * @param msg The message to log
+ */
+ public void warning(String msg) {
+ log(Level.WARNING, msg);
+ }
+
+ /**
+ * Logs the provided message with Level "severe" (error).
+ *
The message will be prefixed with {@link #getName() [<expansion name>]}
+ *
+ * @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).
+ *
The message will be prefixed with {@link #getName() [<expansion name>]}
+ *
+ * @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.
+ *
This method will perform the following checks in order:
+ *
+ * - Checks if Object equals the class. Returns true when equal and continues otherwise
+ * - Checks if the Object is an instance of a PlaceholderExpansion. Returns false if not
+ * - Checks if the Object's Identifier, Author and version equal the one of this class
+ *
+ *
+ * @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
+
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/Relational.java b/src/main/java/at/helpch/placeholderapi/expansion/Relational.java
new file mode 100644
index 0000000..a28d059
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/Relational.java
@@ -0,0 +1,43 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion;
+
+import org.bukkit.entity.Player;
+
+/**
+ * Implementing this interface allows your {@link at.helpch.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}
+ * to be used as a relational placeholder expansion.
+ *
+ * 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.
+ *
+ * @param one The first 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_identifier%)
+ * @return Parsed String from the expansion.
+ */
+ String onPlaceholderRequest(Player one, Player two, String identifier);
+}
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/Taskable.java b/src/main/java/at/helpch/placeholderapi/expansion/Taskable.java
new file mode 100644
index 0000000..ed2f815
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/Taskable.java
@@ -0,0 +1,43 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion;
+
+/**
+ * Implementing this interface adds the {@link #start() start} and {@link #stop() stop} void
+ * methods to your {@link at.helpch.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}.
+ *
+ *
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.
+ *
Tasks that need to be performed when this expansion is registered should go here
+ */
+ void start();
+
+ /**
+ * Called when the implementing class has been unregistered from PlaceholderAPI.
+ *
Tasks that need to be performed when this expansion has unregistered should go here
+ */
+ void stop();
+}
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/cloud/CloudExpansion.java b/src/main/java/at/helpch/placeholderapi/expansion/cloud/CloudExpansion.java
new file mode 100644
index 0000000..d0c51ae
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/cloud/CloudExpansion.java
@@ -0,0 +1,207 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion.cloud;
+
+import java.util.List;
+import java.util.concurrent.TimeUnit;
+import java.util.stream.Collectors;
+
+import at.helpch.placeholderapi.util.TimeUtil;
+
+
+public class CloudExpansion {
+
+ private String name,
+ author,
+ latest_version,
+ description,
+ source_url,
+ dependency_url;
+
+ private boolean hasExpansion,
+ shouldUpdate;
+
+ private long last_update,
+ ratings_count;
+
+ private double average_rating;
+
+ private List placeholders;
+
+ private List versions;
+
+ public CloudExpansion() {
+ }
+
+ public String getTimeSinceLastUpdate() {
+ int time = (int) TimeUnit.MILLISECONDS.toSeconds(System.currentTimeMillis() - getLastUpdate());
+ return TimeUtil.getTime(time);
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public String getAuthor() {
+ return author;
+ }
+
+ public void setAuthor(String author) {
+ this.author = author;
+ }
+
+ public Version getVersion() {
+ return getLatestVersion() == null ? null : getVersion(getLatestVersion());
+ }
+
+ public Version getVersion(String version) {
+ return versions == null ? null : versions.stream()
+ .filter(v -> v.getVersion().equals(version))
+ .findFirst()
+ .orElse(null);
+ }
+
+ public List getAvailableVersions() {
+ return versions.stream().map(Version::getVersion).collect(Collectors.toList());
+ }
+
+ public String getLatestVersion() {
+ return latest_version;
+ }
+
+ public void setLatestVersion(String latest_version) {
+ this.latest_version = latest_version;
+ }
+
+ public String getDescription() {
+ return description;
+ }
+
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ public String getSourceUrl() {
+ return source_url;
+ }
+
+ public void setSourceUrl(String source_url) {
+ this.source_url = source_url;
+ }
+
+ public String getDependencyUrl() {
+ return dependency_url;
+ }
+
+ public void setDependencyUrl(String dependency_url) {
+ this.dependency_url = dependency_url;
+ }
+
+ public boolean hasExpansion() {
+ return hasExpansion;
+ }
+
+ public void setHasExpansion(boolean hasExpansion) {
+ this.hasExpansion = hasExpansion;
+ }
+
+ public boolean shouldUpdate() {
+ return shouldUpdate;
+ }
+
+ public void setShouldUpdate(boolean shouldUpdate) {
+ this.shouldUpdate = shouldUpdate;
+ }
+
+ public long getLastUpdate() {
+ return last_update;
+ }
+
+ public void setLastUpdate(long last_update) {
+ this.last_update = last_update;
+ }
+
+ public long getRatingsCount() {
+ return ratings_count;
+ }
+
+ public double getAverage_rating() {
+ return average_rating;
+ }
+
+ public List getPlaceholders() {
+ return placeholders;
+ }
+
+ public void setPlaceholders(List placeholders) {
+ this.placeholders = placeholders;
+ }
+
+ public List getVersions() {
+ return versions;
+ }
+
+ public void setVersions(List versions) {
+ this.versions = versions;
+ }
+
+ public static class Version {
+
+ private String url, version, release_notes;
+ private boolean verified;
+
+ public String getUrl() {
+ return url;
+ }
+
+ public void setUrl(String url) {
+ this.url = url;
+ }
+
+ public String getVersion() {
+ return version;
+ }
+
+ public void setVersion(String version) {
+ this.version = version;
+ }
+
+ public String getReleaseNotes() {
+ return release_notes;
+ }
+
+ public void setReleaseNotes(String release_notes) {
+ this.release_notes = release_notes;
+ }
+
+ public boolean isVerified() {
+ return verified;
+ }
+
+ public void setVerified(boolean verified) {
+ this.verified = verified;
+ }
+ }
+}
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/manager/CloudExpansionManager.java b/src/main/java/at/helpch/placeholderapi/expansion/manager/CloudExpansionManager.java
new file mode 100644
index 0000000..f462662
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/manager/CloudExpansionManager.java
@@ -0,0 +1,278 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion.manager;
+
+import com.google.common.collect.ImmutableMap;
+import com.google.common.io.Resources;
+import com.google.common.util.concurrent.ThreadFactoryBuilder;
+import com.google.gson.Gson;
+import com.google.gson.reflect.TypeToken;
+
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.lang.reflect.Type;
+import java.net.URL;
+import java.nio.channels.Channels;
+import java.nio.channels.ReadableByteChannel;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionException;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.function.Function;
+import java.util.logging.Level;
+import java.util.stream.Collector;
+import java.util.stream.Collectors;
+
+import at.helpch.placeholderapi.PlaceholderAPIPlugin;
+import at.helpch.placeholderapi.expansion.PlaceholderExpansion;
+import at.helpch.placeholderapi.expansion.cloud.CloudExpansion;
+import at.helpch.placeholderapi.util.Msg;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Unmodifiable;
+
+public final class CloudExpansionManager {
+
+ @NotNull
+ private static final String API_URL = "https://ecloud.placeholderapi.com/api/v3/";
+
+ @NotNull
+ private static final Gson GSON = new Gson();
+ @NotNull
+ private static final Type TYPE = new TypeToken>() {}.getType();
+
+ @NotNull
+ private final Collector> INDEXED_NAME_COLLECTOR = Collectors
+ .toMap(CloudExpansionManager::toIndexName, Function.identity());
+
+
+ @NotNull
+ private final PlaceholderAPIPlugin plugin;
+
+ @NotNull
+ private final Map cache = new HashMap<>();
+ @NotNull
+ private final Map> await = new ConcurrentHashMap<>();
+
+ private final ExecutorService ASYNC_EXECUTOR =
+ Executors.newCachedThreadPool(
+ new ThreadFactoryBuilder().setNameFormat("placeholderapi-io-#%1$d").build());
+
+ public CloudExpansionManager(@NotNull final PlaceholderAPIPlugin plugin) {
+ this.plugin = plugin;
+ }
+
+ @NotNull
+ private static String toIndexName(@NotNull final String name) {
+ return name.toLowerCase(Locale.ROOT).replace(' ', '_');
+ }
+
+ @NotNull
+ private static String toIndexName(@NotNull final CloudExpansion expansion) {
+ return toIndexName(expansion.getName());
+ }
+
+ public void load() {
+ clean();
+ fetch();
+ }
+
+ public void kill() {
+ clean();
+ }
+
+ @NotNull
+ @Unmodifiable
+ public Map getCloudExpansions() {
+ return ImmutableMap.copyOf(cache);
+ }
+
+ @NotNull
+ @Unmodifiable
+ public Map getCloudExpansionsInstalled() {
+ if (cache.isEmpty()) {
+ return Collections.emptyMap();
+ }
+
+ return cache.values()
+ .stream()
+ .filter(CloudExpansion::hasExpansion)
+ .collect(INDEXED_NAME_COLLECTOR);
+ }
+
+ @NotNull
+ @Unmodifiable
+ public Map getCloudExpansionsByAuthor(@NotNull final String author) {
+ if (cache.isEmpty()) {
+ return Collections.emptyMap();
+ }
+
+ return cache.values()
+ .stream()
+ .filter(expansion -> author.equalsIgnoreCase(expansion.getAuthor()))
+ .collect(INDEXED_NAME_COLLECTOR);
+ }
+
+ @NotNull
+ @Unmodifiable
+ public Set getCloudExpansionAuthors() {
+ return cache.values().stream().map(CloudExpansion::getAuthor).collect(Collectors.toSet());
+ }
+
+ public int getCloudExpansionAuthorCount() {
+ return getCloudExpansionAuthors().size();
+ }
+
+ public int getCloudUpdateCount() {
+ return ((int) plugin.getLocalExpansionManager()
+ .getExpansions()
+ .stream()
+ .filter(expansion -> findCloudExpansionByName(expansion.getName())
+ .map(CloudExpansion::shouldUpdate).orElse(false))
+ .count());
+ }
+
+ @NotNull
+ public Optional findCloudExpansionByName(@NotNull final String name) {
+ return Optional.ofNullable(cache.get(toIndexName(name)));
+ }
+
+ public void clean() {
+ cache.clear();
+
+ await.values().forEach(future -> future.cancel(true));
+ await.clear();
+ }
+
+ public void fetch() {
+ plugin.getLogger().info("Fetching available expansion information...");
+
+ ASYNC_EXECUTOR.submit(
+ () -> {
+ // a defence tactic! use ConcurrentHashMap instead of normal HashMap
+ Map values = new ConcurrentHashMap<>();
+ try {
+ //noinspection UnstableApiUsage
+ String json = Resources.toString(new URL(API_URL), StandardCharsets.UTF_8);
+ values.putAll(GSON.fromJson(json, TYPE));
+
+ List toRemove = new ArrayList<>();
+
+ for (Map.Entry entry : values.entrySet()) {
+ CloudExpansion expansion = entry.getValue();
+ if (expansion.getLatestVersion() == null
+ || expansion.getVersion(expansion.getLatestVersion()) == null) {
+ toRemove.add(entry.getKey());
+ }
+ }
+
+ for (String name : toRemove) {
+ values.remove(name);
+ }
+ } 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);
+ }
+
+ // loop through what's left on the main thread
+ plugin
+ .getScheduler()
+ .runTask(
+ () -> {
+ try {
+ for (Map.Entry entry : values.entrySet()) {
+ String name = entry.getKey();
+ CloudExpansion expansion = entry.getValue();
+
+ expansion.setName(name);
+
+ Optional localOpt =
+ plugin.getLocalExpansionManager().findExpansionByName(name);
+ if (localOpt.isPresent()) {
+ PlaceholderExpansion local = localOpt.get();
+ if (local.isRegistered()) {
+ expansion.setHasExpansion(true);
+ expansion.setShouldUpdate(
+ !local.getVersion().equalsIgnoreCase(expansion.getLatestVersion()));
+ }
+ }
+
+ cache.put(toIndexName(expansion), expansion);
+ }
+ } 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);
+ }
+ });
+ });
+ }
+
+ public boolean isDownloading(@NotNull final CloudExpansion expansion) {
+ return await.containsKey(toIndexName(expansion));
+ }
+
+ @NotNull
+ public CompletableFuture downloadExpansion(@NotNull final CloudExpansion expansion,
+ @NotNull final CloudExpansion.Version version) {
+ final CompletableFuture previous = await.get(toIndexName(expansion));
+ if (previous != null) {
+ return previous;
+ }
+
+ final File file = new File(plugin.getLocalExpansionManager().getExpansionsFolder(),
+ "Expansion-" + toIndexName(expansion) + ".jar");
+
+ final CompletableFuture download = CompletableFuture.supplyAsync(() -> {
+ try (final ReadableByteChannel source = Channels.newChannel(new URL(version.getUrl())
+ .openStream()); final FileOutputStream target = new FileOutputStream(file)) {
+ target.getChannel().transferFrom(source, 0, Long.MAX_VALUE);
+ } catch (final IOException ex) {
+ throw new CompletionException(ex);
+ }
+ return file;
+ }, ASYNC_EXECUTOR);
+
+ download.whenCompleteAsync((value, exception) -> {
+ await.remove(toIndexName(expansion));
+
+ if (exception != null) {
+ Msg.severe("Failed to download %s:%s", exception, expansion.getName(), expansion.getVersion());
+ }
+ }, ASYNC_EXECUTOR);
+
+ await.put(toIndexName(expansion), download);
+
+ return download;
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/manager/LocalExpansionManager.java b/src/main/java/at/helpch/placeholderapi/expansion/manager/LocalExpansionManager.java
new file mode 100644
index 0000000..e536ec6
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/manager/LocalExpansionManager.java
@@ -0,0 +1,498 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion.manager;
+
+import at.helpch.placeholderapi.PlaceholderAPIBootstrap;
+import com.google.common.collect.ImmutableSet;
+import com.google.common.collect.Sets;
+
+import java.io.File;
+import java.lang.reflect.Modifier;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.locks.ReentrantLock;
+import java.util.logging.Level;
+import java.util.stream.Collectors;
+
+import at.helpch.placeholderapi.PlaceholderAPIPlugin;
+import at.helpch.placeholderapi.events.ExpansionRegisterEvent;
+import at.helpch.placeholderapi.events.ExpansionUnregisterEvent;
+import at.helpch.placeholderapi.events.ExpansionsLoadedEvent;
+import at.helpch.placeholderapi.expansion.Cacheable;
+import at.helpch.placeholderapi.expansion.Cleanable;
+import at.helpch.placeholderapi.expansion.Configurable;
+import at.helpch.placeholderapi.expansion.PlaceholderExpansion;
+import at.helpch.placeholderapi.expansion.Taskable;
+import at.helpch.placeholderapi.expansion.cloud.CloudExpansion;
+import at.helpch.placeholderapi.util.FileUtil;
+import at.helpch.placeholderapi.util.Futures;
+import at.helpch.placeholderapi.util.Msg;
+import org.bukkit.Bukkit;
+import org.bukkit.command.CommandSender;
+import org.bukkit.configuration.file.FileConfiguration;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.EventPriority;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.Listener;
+import org.bukkit.event.player.PlayerQuitEvent;
+import org.bukkit.event.server.PluginDisableEvent;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
+
+public final class LocalExpansionManager /*implements Listener*/ {
+
+ @NotNull
+ private static final String EXPANSIONS_FOLDER_NAME = "expansions";
+
+ @NotNull
+ private static final Set ABSTRACT_EXPANSION_METHODS = Arrays.stream(PlaceholderExpansion.class.getDeclaredMethods())
+ .filter(method -> Modifier.isAbstract(method.getModifiers()))
+ .map(method -> new MethodSignature(method.getName(), method.getParameterTypes()))
+ .collect(Collectors.toSet());
+
+ @NotNull
+ private final File folder;
+ @NotNull
+ private final PlaceholderAPIPlugin plugin;
+
+ @NotNull
+ private final Map expansions = new ConcurrentHashMap<>();
+ private final ReentrantLock expansionsLock = new ReentrantLock();
+
+
+ public LocalExpansionManager(@NotNull final PlaceholderAPIBootstrap plugin) {
+ this.plugin = plugin;
+ this.folder = new File(plugin., EXPANSIONS_FOLDER_NAME);
+
+ if (!this.folder.exists() && !folder.mkdirs()) {
+ Msg.warn("Failed to create expansions folder!");
+ }
+ }
+
+ public void load(@NotNull final CommandSender sender) {
+ registerAll(sender);
+ }
+
+ public void kill() {
+ unregisterAll();
+ }
+
+
+ @NotNull
+ public File getExpansionsFolder() {
+ return folder;
+ }
+
+ @NotNull
+ @Unmodifiable
+ public Collection getIdentifiers() {
+ expansionsLock.lock();
+ try {
+ return Set.copyOf(expansions.keySet());
+ } finally {
+ expansionsLock.unlock();
+ }
+ }
+
+ @NotNull
+ @Unmodifiable
+ public Collection getExpansions() {
+ expansionsLock.lock();
+ try {
+ return Set.copyOf(expansions.values());
+ } finally {
+ expansionsLock.unlock();
+ }
+ }
+
+ @Nullable
+ public PlaceholderExpansion getExpansion(@NotNull final String identifier) {
+ expansionsLock.lock();
+ try {
+ return expansions.get(identifier.toLowerCase(Locale.ROOT));
+ } finally {
+ expansionsLock.unlock();
+ }
+ }
+
+ @NotNull
+ public Optional findExpansionByName(@NotNull final String name) {
+ expansionsLock.lock();
+ try {
+ PlaceholderExpansion bestMatch = null;
+ for (Map.Entry entry : expansions.entrySet()) {
+ PlaceholderExpansion expansion = entry.getValue();
+ if (expansion.getName().equalsIgnoreCase(name)) {
+ bestMatch = expansion;
+ break;
+ }
+ }
+ return Optional.ofNullable(bestMatch);
+ } finally {
+ expansionsLock.unlock();
+ }
+ }
+
+ @NotNull
+ public Optional findExpansionByIdentifier(
+ @NotNull final String identifier) {
+ return Optional.ofNullable(getExpansion(identifier));
+ }
+
+
+ public Optional register(
+ @NotNull final Class clazz) {
+ try {
+ final PlaceholderExpansion expansion = createExpansionInstance(clazz);
+
+ if (expansion == null) {
+ return Optional.empty();
+ }
+
+ Objects.requireNonNull(expansion.getAuthor(), "The expansion author is null!");
+ Objects.requireNonNull(expansion.getIdentifier(), "The expansion identifier is null!");
+ Objects.requireNonNull(expansion.getVersion(), "The expansion version is null!");
+
+ if (expansion.getRequiredPlugin() != null && !expansion.getRequiredPlugin().isEmpty()) {
+ if (!Bukkit.getPluginManager().isPluginEnabled(expansion.getRequiredPlugin())) {
+ Msg.warn("Cannot load expansion %s due to a missing plugin: %s", expansion.getIdentifier(),
+ expansion.getRequiredPlugin());
+ return Optional.empty();
+ }
+ }
+
+ expansion.setExpansionType(PlaceholderExpansion.Type.EXTERNAL);
+
+ if (!expansion.register()) {
+ Msg.warn("Cannot load expansion %s due to an unknown issue.", expansion.getIdentifier());
+ return Optional.empty();
+ }
+
+ return Optional.of(expansion);
+ } catch (LinkageError | NullPointerException ex) {
+ final String reason;
+
+ if (ex instanceof LinkageError) {
+ reason = " (Is a dependency missing?)";
+ } else {
+ reason = " - One of its properties is null which is not allowed!";
+ }
+
+ Msg.severe("Failed to load expansion class %s%s", ex, clazz.getSimpleName(), reason);
+ }
+
+ return Optional.empty();
+ }
+
+ /**
+ * Attempt to register a {@link PlaceholderExpansion}
+ *
+ * @param expansion the expansion to register
+ * @return if the expansion was registered
+ */
+ @ApiStatus.Internal
+ public boolean register(@NotNull final PlaceholderExpansion expansion) {
+ final String identifier = expansion.getIdentifier().toLowerCase(Locale.ROOT);
+
+ if (!expansion.canRegister()) {
+ return false;
+ }
+
+ // Avoid loading two external expansions with the same identifier
+ if (expansion.getExpansionType() == PlaceholderExpansion.Type.EXTERNAL && expansions.containsKey(identifier)) {
+ Msg.warn("Failed to load external expansion %s. Identifier is already in use.", expansion.getIdentifier());
+ return false;
+ }
+
+ if (expansion instanceof Configurable) {
+ Map defaults = ((Configurable) expansion).getDefaults();
+ String pre = "expansions." + identifier + ".";
+ FileConfiguration cfg = plugin.getConfig();
+ boolean save = false;
+
+ if (defaults != null) {
+ for (Map.Entry entries : defaults.entrySet()) {
+ if (entries.getKey() == null || entries.getKey().isEmpty()) {
+ continue;
+ }
+
+ if (entries.getValue() == null) {
+ if (cfg.contains(pre + entries.getKey())) {
+ save = true;
+ cfg.set(pre + entries.getKey(), null);
+ }
+ } else {
+ if (!cfg.contains(pre + entries.getKey())) {
+ save = true;
+ cfg.set(pre + entries.getKey(), entries.getValue());
+ }
+ }
+ }
+ }
+
+ if (save) {
+ plugin.saveConfig();
+ plugin.reloadConfig();
+ }
+ }
+
+ if (expansion instanceof VersionSpecific) {
+ VersionSpecific nms = (VersionSpecific) expansion;
+ if (!nms.isCompatibleWith(PlaceholderAPIPlugin.getServerVersion())) {
+ Msg.warn("Your server version is incompatible with expansion %s %s",
+ expansion.getIdentifier(), expansion.getVersion());
+ return false;
+ }
+ }
+
+ final PlaceholderExpansion removed = getExpansion(identifier);
+ if (removed != null && !removed.unregister()) {
+ return false;
+ }
+
+ final ExpansionRegisterEvent event = new ExpansionRegisterEvent(expansion);
+ Bukkit.getPluginManager().callEvent(event);
+
+ if (event.isCancelled()) {
+ return false;
+ }
+
+ expansionsLock.lock();
+ try {
+ expansions.put(identifier, expansion);
+ } finally {
+ expansionsLock.unlock();
+ }
+
+ if (expansion instanceof Listener) {
+ Bukkit.getPluginManager().registerEvents(((Listener) expansion), plugin);
+ }
+
+ Msg.info(
+ "Successfully registered %s expansion: %s [%s]",
+ expansion.getExpansionType().name().toLowerCase(),
+ expansion.getIdentifier(),
+ expansion.getVersion()
+ );
+
+ if (expansion instanceof Taskable) {
+ ((Taskable) expansion).start();
+ }
+
+ // Check eCloud for updates only if the expansion is external
+ if (plugin.getPlaceholderAPIConfig().isCloudEnabled() && expansion.getExpansionType() == PlaceholderExpansion.Type.EXTERNAL) {
+ final Optional cloudExpansionOptional = plugin.getCloudExpansionManager().findCloudExpansionByName(identifier);
+ if (cloudExpansionOptional.isPresent()) {
+ CloudExpansion cloudExpansion = cloudExpansionOptional.get();
+ cloudExpansion.setHasExpansion(true);
+ cloudExpansion.setShouldUpdate(!cloudExpansion.getLatestVersion().equals(expansion.getVersion()));
+ }
+ }
+
+ return true;
+ }
+
+ @ApiStatus.Internal
+ public boolean unregister(@NotNull final PlaceholderExpansion expansion) {
+ if (expansions.remove(expansion.getIdentifier().toLowerCase(Locale.ROOT)) == null) {
+ return false;
+ }
+
+ Bukkit.getPluginManager().callEvent(new ExpansionUnregisterEvent(expansion));
+
+ if (expansion instanceof Listener) {
+ HandlerList.unregisterAll((Listener) expansion);
+ }
+
+ if (expansion instanceof Taskable) {
+ ((Taskable) expansion).stop();
+ }
+
+ if (expansion instanceof Cacheable) {
+ ((Cacheable) expansion).clear();
+ }
+
+ if (plugin.getPlaceholderAPIConfig().isCloudEnabled()) {
+ plugin.getCloudExpansionManager().findCloudExpansionByName(expansion.getName())
+ .ifPresent(cloud -> {
+ cloud.setHasExpansion(false);
+ cloud.setShouldUpdate(false);
+ });
+ }
+
+ return true;
+ }
+
+ private void registerAll(@NotNull final CommandSender sender) {
+ Msg.info("Placeholder expansion registration initializing...");
+
+ Futures.onMainThread(plugin, findExpansionsOnDisk(), (classes, exception) -> {
+ if (exception != null) {
+ Msg.severe("Failed to load class files of expansion.", exception);
+ return;
+ }
+
+ final List registered = classes.stream()
+ .filter(Objects::nonNull)
+ .map(this::register)
+ .filter(Optional::isPresent)
+ .map(Optional::get)
+ .collect(Collectors.toList());
+
+ final long needsUpdate = registered.stream()
+ .map(expansion -> plugin.getCloudExpansionManager().findCloudExpansionByName(expansion.getName()).orElse(null))
+ .filter(Objects::nonNull)
+ .filter(CloudExpansion::shouldUpdate)
+ .count();
+
+ StringBuilder message = new StringBuilder(registered.size() == 0 ? "&6" : "&a")
+ .append(registered.size())
+ .append(' ')
+ .append("placeholder hook(s) registered!");
+
+ if (needsUpdate > 0) {
+ message.append(' ')
+ .append("&6")
+ .append(needsUpdate)
+ .append(' ')
+ .append("placeholder hook(s) have an update available.");
+ }
+
+
+ Msg.msg(sender, message.toString());
+
+ Bukkit.getPluginManager().callEvent(new ExpansionsLoadedEvent(registered));
+ });
+ }
+
+ private void unregisterAll() {
+ for (final PlaceholderExpansion expansion : Sets.newHashSet(expansions.values())) {
+ if (expansion.persist()) {
+ continue;
+ }
+
+ expansion.unregister();
+ }
+ }
+
+ @NotNull
+ public CompletableFuture<@NotNull List<@Nullable Class>> findExpansionsOnDisk() {
+ File[] files = folder.listFiles((dir, name) -> name.endsWith(".jar"));
+ if (files == null) {
+ return CompletableFuture.completedFuture(Collections.emptyList());
+ }
+
+ return Arrays.stream(files)
+ .map(this::findExpansionInFile)
+ .collect(Futures.collector());
+ }
+
+ @NotNull
+ public CompletableFuture<@Nullable Class> findExpansionInFile(
+ @NotNull final File file) {
+ return CompletableFuture.supplyAsync(() -> {
+ try {
+ final Class expansionClass = FileUtil.findClass(file, PlaceholderExpansion.class);
+
+ if (expansionClass == null) {
+ Msg.severe("Failed to load expansion %s, as it does not have a class which"
+ + " extends PlaceholderExpansion", file.getName());
+ return null;
+ }
+
+ Set expansionMethods = Arrays.stream(expansionClass.getDeclaredMethods())
+ .map(method -> new MethodSignature(method.getName(), method.getParameterTypes()))
+ .collect(Collectors.toSet());
+ if (!expansionMethods.containsAll(ABSTRACT_EXPANSION_METHODS)) {
+ Msg.severe("Failed to load expansion %s, as it does not have the required"
+ + " methods declared for a PlaceholderExpansion.", file.getName());
+ return null;
+ }
+
+ return expansionClass;
+ } catch (VerifyError | NoClassDefFoundError e) {
+ Msg.severe("Failed to load expansion %s (is a dependency missing?)", e, file.getName());
+ return null;
+ } catch (Exception e) {
+ plugin.getLogger().log(Level.SEVERE, "Failed to load expansion file: " + file.getAbsolutePath(), e);
+ return null;
+ }
+ });
+ }
+
+
+ @Nullable
+ public PlaceholderExpansion createExpansionInstance(
+ @NotNull final Class clazz) throws LinkageError {
+ try {
+ return clazz.getDeclaredConstructor().newInstance();
+ } catch (final Exception ex) {
+ if (ex.getCause() instanceof LinkageError) {
+ throw ((LinkageError) ex.getCause());
+ }
+
+ Msg.warn("There was an issue with loading an expansion.");
+ return null;
+ }
+ }
+
+
+ @EventHandler
+ public void onQuit(@NotNull final PlayerQuitEvent event) {
+ for (final PlaceholderExpansion expansion : getExpansions()) {
+ if (!(expansion instanceof Cleanable)) {
+ continue;
+ }
+
+ ((Cleanable) expansion).cleanup(event.getPlayer());
+ }
+ }
+
+ @EventHandler(priority = EventPriority.HIGH)
+ public void onPluginDisable(@NotNull final PluginDisableEvent event) {
+ final String name = event.getPlugin().getName();
+ if (name.equals(plugin.getName())) {
+ return;
+ }
+
+ for (final PlaceholderExpansion expansion : getExpansions()) {
+ if (!name.equalsIgnoreCase(expansion.getRequiredPlugin())) {
+ continue;
+ }
+
+ expansion.unregister();
+ Msg.info("Unregistered placeholder expansion %s", expansion.getIdentifier());
+ Msg.info("Reason: required plugin %s was disabled.", name);
+ }
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/expansion/manager/MethodSignature.java b/src/main/java/at/helpch/placeholderapi/expansion/manager/MethodSignature.java
new file mode 100644
index 0000000..e74027d
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/expansion/manager/MethodSignature.java
@@ -0,0 +1,57 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.expansion.manager;
+
+import java.util.Arrays;
+import java.util.Objects;
+
+public final class MethodSignature {
+ private final String name;
+ private final Class[] params;
+
+ protected MethodSignature(String name, Class[] params) {
+ this.name = name;
+ this.params = params;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public Class[] getParams() {
+ return params;
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o) return true;
+ if (o == null || getClass() != o.getClass()) return false;
+ MethodSignature that = (MethodSignature) o;
+ return Objects.equals(name, that.name) && Arrays.equals(params, that.params);
+ }
+
+ @Override
+ public int hashCode() {
+ int result = Objects.hash(name);
+ result = 31 * result + Arrays.hashCode(params);
+ return result;
+ }
+}
diff --git a/src/main/java/at/helpch/placeholderapi/listeners/ServerLoadEventListener.java b/src/main/java/at/helpch/placeholderapi/listeners/ServerLoadEventListener.java
new file mode 100644
index 0000000..70950f2
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/listeners/ServerLoadEventListener.java
@@ -0,0 +1,48 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.listeners;
+
+import at.helpch.placeholderapi.PlaceholderAPIPlugin;
+import org.bukkit.Bukkit;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.Listener;
+import org.bukkit.event.server.ServerLoadEvent;
+import org.jetbrains.annotations.NotNull;
+
+public final class ServerLoadEventListener implements Listener {
+
+ @NotNull
+ private final PlaceholderAPIPlugin plugin;
+
+ public ServerLoadEventListener(@NotNull final PlaceholderAPIPlugin plugin) {
+ this.plugin = plugin;
+
+ Bukkit.getPluginManager().registerEvents(this, plugin);
+ }
+
+ @EventHandler
+ public void onServerLoad(@NotNull final ServerLoadEvent event) {
+ HandlerList.unregisterAll(this);
+ plugin.getLocalExpansionManager().load(Bukkit.getConsoleSender());
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/replacer/CharsReplacer.java b/src/main/java/at/helpch/placeholderapi/replacer/CharsReplacer.java
new file mode 100644
index 0000000..cd89760
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/replacer/CharsReplacer.java
@@ -0,0 +1,138 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.replacer;
+
+import java.util.Locale;
+import java.util.function.Function;
+
+import at.helpch.placeholderapi.expansion.PlaceholderExpansion;
+import org.bukkit.ChatColor;
+import org.bukkit.OfflinePlayer;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+public final class CharsReplacer implements Replacer {
+
+ @NotNull
+ private final Closure closure;
+
+ public CharsReplacer(@NotNull final Closure closure) {
+ this.closure = closure;
+ }
+
+
+ @NotNull
+ @Override
+ public String apply(@NotNull final String text, @Nullable final OfflinePlayer player,
+ @NotNull final Function lookup) {
+ final char[] chars = text.toCharArray();
+ final StringBuilder builder = new StringBuilder(text.length());
+
+ 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 != closure.head || i + 1 >= chars.length) {
+ builder.append(l);
+ continue;
+ }
+
+ boolean identified = false;
+ boolean invalid = true;
+ boolean hadSpace = false;
+
+ while (++i < chars.length) {
+ final char p = chars[i];
+
+ if (p == ' ' && !identified) {
+ hadSpace = true;
+ break;
+ }
+ if (p == closure.tail) {
+ 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) {
+ builder.append(closure.head).append(identifierString);
+
+ if (identified) {
+ builder.append('_').append(parametersString);
+ }
+
+ if (hadSpace) {
+ builder.append(' ');
+ }
+ continue;
+ }
+
+ final PlaceholderExpansion placeholder = lookup.apply(lowercaseIdentifierString);
+ if (placeholder == null) {
+ builder.append(closure.head).append(identifierString);
+
+ if (identified) {
+ builder.append('_');
+ }
+
+ builder.append(parametersString).append(closure.tail);
+ continue;
+ }
+
+ final String replacement = placeholder.onRequest(player, parametersString);
+ if (replacement == null) {
+ builder.append(closure.head).append(identifierString);
+
+ if (identified) {
+ builder.append('_');
+ }
+
+ builder.append(parametersString).append(closure.tail);
+ continue;
+ }
+
+ builder.append(replacement);
+ }
+
+ return builder.toString();
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/replacer/Replacer.java b/src/main/java/at/helpch/placeholderapi/replacer/Replacer.java
new file mode 100644
index 0000000..66cef7b
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/replacer/Replacer.java
@@ -0,0 +1,50 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.replacer;
+
+import java.util.function.Function;
+
+import at.helpch.placeholderapi.expansion.PlaceholderExpansion;
+import org.bukkit.OfflinePlayer;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+public interface Replacer {
+
+ @NotNull
+ String apply(@NotNull final String text, @Nullable final OfflinePlayer player,
+ @NotNull final Function lookup);
+
+
+ enum Closure {
+ BRACKET('{', '}'),
+ PERCENT('%', '%');
+
+
+ public final char head, tail;
+
+ Closure(final char head, final char tail) {
+ this.head = head;
+ this.tail = tail;
+ }
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/util/ExpansionSafetyCheck.java b/src/main/java/at/helpch/placeholderapi/util/ExpansionSafetyCheck.java
new file mode 100644
index 0000000..2a008e9
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/util/ExpansionSafetyCheck.java
@@ -0,0 +1,80 @@
+package at.helpch.placeholderapi.util;
+
+import com.google.common.hash.Hashing;
+import com.google.common.io.Files;
+import com.google.common.io.Resources;
+import at.helpch.placeholderapi.PlaceholderAPIPlugin;
+import org.jetbrains.annotations.NotNull;
+
+import java.io.File;
+import java.net.URL;
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.logging.Level;
+import java.util.stream.Collectors;
+
+public final class ExpansionSafetyCheck {
+ private static final String MESSAGE =
+ "\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" +
+ "%s" +
+ "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 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" +
+ "###############################################";
+
+ private final PlaceholderAPIPlugin main;
+
+ public ExpansionSafetyCheck(@NotNull final PlaceholderAPIPlugin main) {
+ this.main = main;
+ }
+
+ public boolean runChecks() {
+ if (!main.getPlaceholderAPIConfig().detectMaliciousExpansions()) {
+ return false;
+ }
+
+ final File expansionsFolder = new File(main.getDataFolder(), "expansions");
+
+ if (!expansionsFolder.exists()) {
+ return false;
+ }
+
+ final Set knownMaliciousExpansions;
+
+ try {
+ final String hashes = Resources.toString(new URL("https://check.placeholderapi.com"), StandardCharsets.UTF_8);
+ knownMaliciousExpansions = Arrays.stream(hashes.split("\n")).collect(Collectors.toSet());
+ } catch (Exception e) {
+ main.getLogger().log(Level.SEVERE, "Failed to download anti malware hash check list from https://check.placeholderapi.com", e);
+ return false;
+ }
+
+ final Set maliciousPaths = new HashSet<>();
+
+ for (File file : expansionsFolder.listFiles()) {
+ try {
+ final String hash = Hashing.sha256().hashBytes(Files.asByteSource(file).read()).toString();
+
+ if (knownMaliciousExpansions.contains(hash)) {
+ maliciousPaths.add(file.getAbsolutePath());
+ }
+ } catch (Exception e) {
+ main.getLogger().log(Level.SEVERE, "Error occurred while trying to read " + file.getAbsolutePath(), e);
+ }
+ }
+
+ if (maliciousPaths.isEmpty()) {
+ return false;
+ }
+
+ main.getLogger().severe(String.format(MESSAGE, maliciousPaths.stream().map(p -> "HASH OF " + p + " MATCHES KNOWN MALICIOUS EXPANSION DELETE IMMEDIATELY\n").collect(Collectors.joining())));
+
+ main.getServer().shutdown();
+ return true;
+ }
+}
diff --git a/src/main/java/at/helpch/placeholderapi/util/FileUtil.java b/src/main/java/at/helpch/placeholderapi/util/FileUtil.java
new file mode 100644
index 0000000..6f43ea2
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/util/FileUtil.java
@@ -0,0 +1,77 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.util;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.io.File;
+import java.io.IOException;
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.jar.JarEntry;
+import java.util.jar.JarInputStream;
+
+public class FileUtil {
+
+ @Nullable
+ public static Class findClass(@NotNull final File file,
+ @NotNull final Class clazz) throws IOException, ClassNotFoundException {
+ if (!file.exists()) {
+ return null;
+ }
+
+ final URL jar = file.toURI().toURL();
+ final URLClassLoader loader = new URLClassLoader(new URL[]{jar}, clazz.getClassLoader());
+ final List matches = new ArrayList<>();
+ final List> classes = new ArrayList<>();
+
+ try (final JarInputStream stream = new JarInputStream(jar.openStream())) {
+ JarEntry entry;
+ while ((entry = stream.getNextJarEntry()) != null) {
+ final String name = entry.getName();
+ if (name.isEmpty() || !name.endsWith(".class")) {
+ continue;
+ }
+
+ matches.add(name.substring(0, name.lastIndexOf('.')).replace('/', '.'));
+ }
+
+ for (final String match : matches) {
+ try {
+ final Class loaded = loader.loadClass(match);
+ if (clazz.isAssignableFrom(loaded)) {
+ classes.add(loaded.asSubclass(clazz));
+ }
+ } catch (final NoClassDefFoundError ignored) {
+ }
+ }
+ }
+ if (classes.isEmpty()) {
+ loader.close();
+ return null;
+ }
+ return classes.get(0);
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/util/Format.java b/src/main/java/at/helpch/placeholderapi/util/Format.java
new file mode 100644
index 0000000..4596c56
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/util/Format.java
@@ -0,0 +1,71 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.util;
+
+import static java.lang.Math.max;
+import static java.lang.Math.min;
+import static java.util.Arrays.stream;
+import static java.util.stream.Collectors.joining;
+import static java.util.stream.Collectors.toList;
+import static java.util.stream.IntStream.range;
+
+import java.util.List;
+import java.util.Optional;
+
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * For the record, I am not sorry.
+ */
+public final class Format {
+
+ private Format() {}
+
+ @NotNull
+ public static Optional> tablify(@NotNull final Align align,
+ @NotNull final List> rows) {
+ return findSpacing(rows)
+ .map(spacing -> buildFormat(align, spacing))
+ .map(format -> rows.stream()
+ .map(
+ row -> String.format(format, row.toArray()).substring(align == Align.RIGHT ? 2 : 0))
+ .collect(toList()));
+ }
+
+ @NotNull
+ private static String buildFormat(@NotNull final Align align, final int[] spacing) {
+ return stream(spacing)
+ .mapToObj(space -> "%" + (align == Align.LEFT ? "-" : "") + (space + 2) + "s")
+ .collect(joining());
+ }
+
+ @NotNull
+ private static Optional findSpacing(@NotNull final List> rows) {
+ return rows.stream()
+ .map(row -> row.stream().mapToInt(String::length).toArray())
+ .reduce((l, r) -> range(0, min(l.length, r.length)).map(i -> max(l[i], r[i])).toArray());
+ }
+
+ public enum Align {
+ LEFT, RIGHT
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/util/Futures.java b/src/main/java/at/helpch/placeholderapi/util/Futures.java
new file mode 100644
index 0000000..903f696
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/util/Futures.java
@@ -0,0 +1,79 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.util;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.function.BiConsumer;
+import java.util.stream.Collector;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import at.helpch.placeholderapi.PlaceholderAPIPlugin;
+import org.bukkit.Bukkit;
+import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;
+
+public final class Futures {
+
+ private Futures() {}
+
+
+ public static void onMainThread(@NotNull final PlaceholderAPIPlugin plugin,
+ @NotNull final CompletableFuture future,
+ @NotNull final BiConsumer consumer) {
+ future.whenComplete((value, exception) -> {
+ if (Bukkit.isPrimaryThread()) {
+ consumer.accept(value, exception);
+ } else {
+ plugin.getScheduler().runTask(() -> consumer.accept(value, exception));
+ }
+ });
+ }
+
+
+ @NotNull
+ public static Collector, ?, CompletableFuture>> collector() {
+ return Collectors.collectingAndThen(Collectors.toList(), Futures::of);
+ }
+
+
+ @NotNull
+ public static CompletableFuture> of(
+ @NotNull final Stream> futures) {
+ return of(futures.collect(Collectors.toList()));
+ }
+
+ @NotNull
+ public static CompletableFuture> of(
+ @NotNull final Collection> futures) {
+ return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
+ .thenApplyAsync($ -> awaitCompletion(futures));
+ }
+
+ @NotNull
+ private static List awaitCompletion(
+ @NotNull final Collection> futures) {
+ return futures.stream().map(CompletableFuture::join).collect(Collectors.toList());
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/util/Msg.java b/src/main/java/at/helpch/placeholderapi/util/Msg.java
new file mode 100644
index 0000000..5976d17
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/util/Msg.java
@@ -0,0 +1,80 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.util;
+
+import java.util.Arrays;
+import java.util.logging.Level;
+import java.util.stream.Collectors;
+
+import at.helpch.placeholderapi.PlaceholderAPIPlugin;
+import org.bukkit.Bukkit;
+import org.bukkit.ChatColor;
+import org.bukkit.command.CommandSender;
+import org.jetbrains.annotations.NotNull;
+
+public final class Msg {
+
+ public static void log(Level level, String msg, Object... args) {
+ PlaceholderAPIPlugin.getInstance().getLogger().log(level, String.format(msg, args));
+ }
+
+ public static void info(String msg, Object... args) {
+ log(Level.INFO, msg, args);
+ }
+
+ public static void warn(String msg, Object... args) {
+ log(Level.WARNING, msg, args);
+ }
+
+ public static void warn(String msg, Throwable throwable, Object... args) {
+ PlaceholderAPIPlugin.getInstance().getLogger().log(Level.WARNING, String.format(msg, args), throwable);
+ }
+
+ public static void severe(String msg, Object... args) {
+ log(Level.SEVERE, msg, args);
+ }
+
+ public static void severe(String msg, Throwable throwable, Object... args) {
+ PlaceholderAPIPlugin.getInstance().getLogger().log(Level.SEVERE, String.format(msg, args), throwable);
+ }
+
+ public static void msg(@NotNull final CommandSender sender, @NotNull final String... messages) {
+ if (messages.length == 0) {
+ return;
+ }
+
+ sender.sendMessage(Arrays.stream(messages).map(Msg::color).collect(Collectors.joining("\n")));
+ }
+
+ public static void broadcast(@NotNull final String... messages) {
+ if (messages.length == 0) {
+ return;
+ }
+
+ Bukkit.broadcastMessage(
+ Arrays.stream(messages).map(Msg::color).collect(Collectors.joining("\n")));
+ }
+
+ public static String color(@NotNull final String text) {
+ return ChatColor.translateAlternateColorCodes('&', text);
+ }
+
+}
diff --git a/src/main/java/at/helpch/placeholderapi/util/TimeFormat.java b/src/main/java/at/helpch/placeholderapi/util/TimeFormat.java
new file mode 100644
index 0000000..9bb0765
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/util/TimeFormat.java
@@ -0,0 +1,28 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.util;
+
+public enum TimeFormat {
+ DAYS,
+ HOURS,
+ MINUTES,
+ SECONDS
+}
diff --git a/src/main/java/at/helpch/placeholderapi/util/TimeUtil.java b/src/main/java/at/helpch/placeholderapi/util/TimeUtil.java
new file mode 100644
index 0000000..2191ff8
--- /dev/null
+++ b/src/main/java/at/helpch/placeholderapi/util/TimeUtil.java
@@ -0,0 +1,96 @@
+/*
+ * 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 .
+ */
+
+package at.helpch.placeholderapi.util;
+
+import java.time.Duration;
+import java.time.temporal.ChronoUnit;
+import java.util.StringJoiner;
+
+public class TimeUtil {
+
+ public static String getRemaining(final int seconds, final TimeFormat type) {
+ return getRemaining((long) seconds, type);
+ }
+
+ public static String getRemaining(final long seconds, final TimeFormat type) {
+ switch (type) {
+ default:
+ return String.valueOf(seconds);
+
+ case SECONDS:
+ return String.valueOf(seconds % 60);
+
+ case MINUTES:
+ return String.valueOf((seconds / 60) % 60);
+
+ case HOURS:
+ return String.valueOf((seconds / 3600) % 24);
+
+ case DAYS:
+ return String.valueOf(seconds / 86400);
+ }
+ }
+
+ /**
+ * Format the given value with s, m, h and d (seconds, minutes, hours and days)
+ *
+ * @param duration {@link Duration} (eg, Duration.of(20, {@link ChronoUnit#SECONDS}) for 20
+ * seconds)
+ * @return formatted time
+ */
+ public static String getTime(final Duration duration) {
+ return getTime(duration.getSeconds());
+ }
+
+ public static String getTime(final int seconds) {
+ return getTime((long) seconds);
+ }
+
+ public static String getTime(long seconds) {
+ final StringJoiner joiner = new StringJoiner(" ");
+
+ long minutes = seconds / 60;
+ long hours = minutes / 60;
+ final long days = hours / 24;
+
+ seconds %= 60;
+ minutes %= 60;
+ hours %= 24;
+
+ if (days > 0) {
+ joiner.add(days + "d");
+ }
+
+ if (hours > 0) {
+ joiner.add(hours + "h");
+ }
+
+ if (minutes > 0) {
+ joiner.add(minutes + "m");
+ }
+
+ if (seconds > 0) {
+ joiner.add(seconds + "s");
+ }
+
+ return joiner.toString();
+ }
+}
diff --git a/src/main/resources/config.yml b/src/main/resources/config.yml
index 0fe9cda..3096a76 100644
--- a/src/main/resources/config.yml
+++ b/src/main/resources/config.yml
@@ -11,9 +11,8 @@
check_updates: true
cloud_enabled: true
cloud_sorting: "name"
-boolean:
- 'true': 'yes'
- 'false': 'no'
+boolean_value:
+ true_value: 'yes'
+ false_value: 'no'
date_format: MM/dd/yy HH:mm:ss
-detect_malicious_expansions: true
debug: false
diff --git a/src/paper/java/me/clip/placeholderapi/PAPIComponents.java b/src/paper/java/me/clip/placeholderapi/PAPIComponents.java
deleted file mode 100644
index d35a78d..0000000
--- a/src/paper/java/me/clip/placeholderapi/PAPIComponents.java
+++ /dev/null
@@ -1,180 +0,0 @@
-/*
- * 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 .
- */
-
-package me.clip.placeholderapi;
-
-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.
- *
The pattern of a valid placeholder is {@literal %_