feat(papi): 提供便捷的PlaceholderAPI变量实现类。

2024-09-19 19:25:45 +00:00 · 2023-02-19 02:59:05 +08:00 · 2023-02-19 02:59:05 +08:00 · 3019216801
commit 3019216801
parent 01250a65d1
11 changed files with 588 additions and 36 deletions
--- a/README.md
+++ b/README.md
@ -37,44 +37,50 @@
 ### 主要部分 (`/base`)

 - Utils  [`easyplugin-utils`](base/utils)
-  - 通用工具类模块，该模块中的内容支持在Bungee、Bukkit使用。
-  - 本模块提供 
-    - `ColorParser` 支持RGB颜色与RGB渐变色的颜色解析器。
-    - `EasyCooldown` 快速创造一个冷却时间的管理器。
-    - `JarResourceUtils` 快速读取Jar包内容的工具类。
+    - 通用工具类模块，该模块中的内容支持在Bungee、Bukkit使用。
+    - 本模块提供
+        - `ColorParser` 支持RGB颜色与RGB渐变色的颜色解析器。
+        - `EasyCooldown` 快速创造一个冷却时间的管理器。
+        - `JarResourceUtils` 快速读取Jar包内容的工具类。
 - Main [`easyplugin-main`](base/main)
-  - 主要接口模块，提供了方便的插件入口类与相关工具类。
+    - 主要接口模块，提供了方便的插件入口类与相关工具类。
 - Command [`easyplugin-command`](base/command)
-  - 指令接口模块，便于快速进行子指令的实现，并提供单独的TabComplete方法。
-  - 随本项目提供了 `SimpleCompleter` 类，用于快速创建补全的内容列表。
+    - 指令接口模块，便于快速进行子指令的实现，并提供单独的TabComplete方法。
+    - 随本项目提供了 `SimpleCompleter` 类，用于快速创建补全的内容列表。
 - GUI [`easyplugin-gui`](base/main)
-  - 简单便捷的箱子GUI接口，可以快速实现GUI中不同图标的点击功能。
-  - 随本项目提供了 `AutoPagedGUI` 等翻页GUI抽象类。
+    - 简单便捷的箱子GUI接口，可以快速实现GUI中不同图标的点击功能。
+    - 随本项目提供了 `AutoPagedGUI` 等翻页GUI抽象类。
 - Storage [`easyplugin-storage`](base/storage)
-  - 抽象存储管理器，便于实现不同的存储类型。 
-  - 随本项目提供了 `FileBasedStorage`、`FolderBasedStorage` 等常用存储抽象方法。
+    - 抽象存储管理器，便于实现不同的存储类型。
+    - 随本项目提供了 `FileBasedStorage`、`FolderBasedStorage` 等常用存储抽象方法。
+- Messages [`easyplugin-message`](base/messages)
+    - 随本项目提供了基于 MineConfiguration 实现的 `EasyMessages` 类。
+    - 支持多种消息配置，包括文本消息、ActionBar消息、Title消息、声音、粒子效果播放等。
+    - 支持消息间的延迟发送。

 > 以下项目均已独立出单独项目，仅仅是按照包名规则打包到EasyPlugin的子项目中。
-> 
+>
 > 如需使用，**强烈建议自行引用对应的项目**，以支持完整的Javadoc并获取源码内容！

 - _Listener_ [`easyplugin-listener`](base/listener) (打包自 [**EasyListener**](https://github.com/CarmJos/EasyListener))
- _Configuration_ [`easyplugin-conf`](base/conf) (打包自 [**MineConfiguration**](https://github.com/CarmJos/MineConfiguration))
+- _Configuration_ [`easyplugin-conf`](base/conf) (打包自 [**MineConfiguration
+  **](https://github.com/CarmJos/MineConfiguration))
 - _Database_ [`easyplugin-database`](base/database)  (打包自 [**EasySQL**](https://github.com/CarmJos/EasySQL))
- _Messages*_ [`easyplugin-message`](base/message) (打包自 [**EasyMessages**](https://github.com/CarmJos/EasyMessages))

 ### 附属部分 (`/extension`)

- [PlaceholderAPI](https://www.spigotmc.org/resources/6245/)* [`easyplugin-placeholderapi`](extension/papi)
+- [PlaceholderAPI](https://www.spigotmc.org/resources/6245/) [`easyplugin-placeholderapi`](extension/papi)
 - [Vault](https://github.com/MilkBowl/VaultAPI)* [`easyplugin-vault`](extension/vault)

 ## 开发

-详细开发介绍请 [点击这里](.documentation/README.md) , JavaDoc(最新Release) 请 [点击这里](https://carmjos.github.io/EasyPlugin) 。
+详细开发介绍请 [点击这里](.documentation/README.md) , JavaDoc(最新Release)
+请 [点击这里](https://carmjos.github.io/EasyPlugin) 。

 ### 示例代码

-您可以 [点击这里](https://github.com/CarmJos/UltraDepository) 查看实例项目演示，更多演示详见 [开发介绍](.documentation/README.md) 。
+您可以 [点击这里](https://github.com/CarmJos/UltraDepository)
+查看实例项目演示，更多演示详见 [开发介绍](.documentation/README.md) 。

 ### 依赖方式

@ -181,7 +187,8 @@ dependencies {

 > MIT 协议可能是几大开源协议中最宽松的一个，核心条款是：
 >
-> 该软件及其相关文档对所有人免费，可以任意处置，包括使用，复制，修改，合并，发表，分发，再授权，或者销售。唯一的限制是，软件中必须包含上述版 权和许可提示。
+> 该软件及其相关文档对所有人免费，可以任意处置，包括使用，复制，修改，合并，发表，分发，再授权，或者销售。唯一的限制是，软件中必须包含上述版
+> 权和许可提示。
 >
 > 这意味着：
 > - 你可以自由使用，复制，修改，可以用于自己的项目。
--- a/base/command/src/main/java/cc/carm/lib/easyplugin/command/CommandHandler.java
+++ b/base/command/src/main/java/cc/carm/lib/easyplugin/command/CommandHandler.java
@ -46,7 +46,8 @@ public abstract class CommandHandler implements TabExecutor, NamedExecutor {
    public abstract Void noPermission(CommandSender sender);

    public Void onException(CommandSender sender, SubCommand<?> cmd, Exception ex) {
-        sender.sendMessage("Error occurred when executing " + cmd.getName() + ": " + ex.getLocalizedMessage());
+        sender.sendMessage("Error occurred when executing " + cmd.getIdentifier() + ": " + ex.getLocalizedMessage());
+        ex.printStackTrace();
        return null;
    }

@ -56,18 +57,18 @@ public abstract class CommandHandler implements TabExecutor, NamedExecutor {
    }

    @Override
-    public String getName() {
+    public @NotNull String getIdentifier() {
        return this.cmd;
    }

    public void registerSubCommand(SubCommand<?> command) {
-        String name = command.getName().toLowerCase();
+        String name = command.getIdentifier().toLowerCase();
        this.registeredCommands.put(name, command);
        command.getAliases().forEach(alias -> this.aliasesMap.put(alias.toLowerCase(), name));
    }

    public void registerHandler(CommandHandler handler) {
-        String name = handler.getName().toLowerCase();
+        String name = handler.getIdentifier().toLowerCase();
        this.registeredHandlers.put(name, handler);
        handler.getAliases().forEach(alias -> this.aliasesMap.put(alias.toLowerCase(), name));
    }
@ -106,7 +107,6 @@ public abstract class CommandHandler implements TabExecutor, NamedExecutor {
                sub.execute(this.plugin, sender, this.shortenArgs(args));
            } catch (Exception ex) {
                this.onException(sender, sub, ex);
-                ex.printStackTrace();
            }
        }

@ -121,7 +121,7 @@ public abstract class CommandHandler implements TabExecutor, NamedExecutor {
        if (args.length == 1) {
            return getExecutors().stream()
                    .filter(e -> e.hasPermission(sender))
-                    .map(NamedExecutor::getName)
+                    .map(NamedExecutor::getIdentifier)
                    .filter(s -> StringUtil.startsWithIgnoreCase(s, input))
                    .collect(Collectors.toList());
        } else {
@ -145,7 +145,7 @@ public abstract class CommandHandler implements TabExecutor, NamedExecutor {
        executors.addAll(this.registeredHandlers.values());
        executors.addAll(this.registeredCommands.values());
        List<NamedExecutor> sortedExecutors = new ArrayList<>(executors);
-        sortedExecutors.sort(Comparator.comparing(NamedExecutor::getName));
+        sortedExecutors.sort(Comparator.comparing(NamedExecutor::getIdentifier));
        return sortedExecutors;
    }

--- a/base/command/src/main/java/cc/carm/lib/easyplugin/command/NamedExecutor.java
+++ b/base/command/src/main/java/cc/carm/lib/easyplugin/command/NamedExecutor.java
@ -11,16 +11,16 @@ import java.util.function.Function;

 public interface NamedExecutor {

-    String getName();
+    @NotNull String getIdentifier();

-    List<String> getAliases();
+    @NotNull List<String> getAliases();

-    default boolean hasPermission(CommandSender sender) {
+    default boolean hasPermission(@NotNull CommandSender sender) {
        return true;
    }

    default Void sendMessage(@NotNull CommandSender sender, @NotNull String... messages) {
-        return sendMessage(sender, (Function<String, String>) null, messages);
+        return sendMessage(sender, Function.identity(), messages);
    }

    default Void sendMessage(@NotNull CommandSender sender,
--- a/base/command/src/main/java/cc/carm/lib/easyplugin/command/SubCommand.java
+++ b/base/command/src/main/java/cc/carm/lib/easyplugin/command/SubCommand.java
@ -14,12 +14,12 @@ public abstract class SubCommand<C extends CommandHandler> implements NamedExecu

    private final @NotNull C parent;

-    private final String name;
+    private final String identifier;
    private final List<String> aliases;

-    public SubCommand(@NotNull C parent, String name, String... aliases) {
+    public SubCommand(@NotNull C parent, String identifier, String... aliases) {
        this.parent = parent;
-        this.name = name;
+        this.identifier = identifier;
        this.aliases = Arrays.asList(aliases);
    }

@ -28,13 +28,13 @@ public abstract class SubCommand<C extends CommandHandler> implements NamedExecu
    }

    @Override
-    public String getName() {
-        return this.name;
+    public @NotNull String getIdentifier() {
+        return this.identifier;
    }

    @Override
    @Unmodifiable
-    public List<String> getAliases() {
+    public @NotNull List<String> getAliases() {
        return this.aliases;
    }

--- a/extension/papi/src/main/java/cc/carm/lib/easyplugin/papi/EasyPlaceholder.java
+++ b/extension/papi/src/main/java/cc/carm/lib/easyplugin/papi/EasyPlaceholder.java
@ -0,0 +1,183 @@
+package cc.carm.lib.easyplugin.papi;
+
+import cc.carm.lib.easyplugin.papi.expansion.SectionExpansion;
+import cc.carm.lib.easyplugin.papi.expansion.SubExpansion;
+import cc.carm.lib.easyplugin.papi.handler.PlaceholderHandler;
+import me.clip.placeholderapi.expansion.PlaceholderExpansion;
+import org.bukkit.OfflinePlayer;
+import org.bukkit.plugin.java.JavaPlugin;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.List;
+import java.util.function.Consumer;
+
+public class EasyPlaceholder extends PlaceholderExpansion {
+
+    protected final @NotNull String plugin;
+    protected final @NotNull SectionExpansion rootExpansion;
+
+    protected final @NotNull String name;
+    protected final @NotNull String author;
+    protected final @NotNull String version;
+
+    protected final boolean persistent;
+
+    public EasyPlaceholder(@NotNull JavaPlugin plugin, @NotNull String rootIdentifier) {
+        this(
+                plugin.getName(), true, rootIdentifier,
+                plugin.getName(), plugin.getDescription().getVersion(),
+                String.join(", ", plugin.getDescription().getAuthors())
+        );
+    }
+
+    public EasyPlaceholder(@NotNull JavaPlugin plugin, @NotNull SectionExpansion rootExpansion) {
+        this(
+                plugin.getName(), true, rootExpansion,
+                plugin.getName(), plugin.getDescription().getVersion(),
+                String.join(", ", plugin.getDescription().getAuthors())
+        );
+    }
+
+    public EasyPlaceholder(@NotNull String plugin, boolean persistent, @NotNull String rootIdentifier,
+                           @NotNull String name, @NotNull String version, @NotNull String author) {
+        super();
+        this.plugin = plugin;
+        this.name = name;
+        this.author = author;
+        this.version = version;
+        this.persistent = persistent;
+        this.rootExpansion = new SectionExpansion(this, rootIdentifier);
+    }
+
+    public EasyPlaceholder(@NotNull String plugin, boolean persistent,
+                           @NotNull SectionExpansion rootExpansion,
+                           @NotNull String name, @NotNull String version, @NotNull String author) {
+        super();
+        this.plugin = plugin;
+        this.name = name;
+        this.author = author;
+        this.version = version;
+        this.persistent = persistent;
+        this.rootExpansion = rootExpansion;
+    }
+
+    /**
+     * 得到根变量解析器
+     *
+     * @return 根变量解析器
+     */
+    public @NotNull SectionExpansion getRootExpansion() {
+        return rootExpansion;
+    }
+
+    /**
+     * 当未找到对应变量处理器时调用
+     *
+     * @param player 变量解析时的目标玩家，可能为空或不在线。
+     * @return 返回给玩家的内容
+     */
+    public String onErrorParams(@Nullable OfflinePlayer player) {
+        return "Wrong params";
+    }
+
+    /**
+     * 当变量处理器返回 NULL 值时调用
+     *
+     * @param player 变量解析时的目标玩家，可能为空或不在线。
+     * @return 返回给玩家的内容
+     */
+    public String onNullResponse(@Nullable OfflinePlayer player) {
+        return "";
+    }
+
+    /**
+     * 当变量处理器抛出异常时调用
+     *
+     * @param player    变量解析时的目标玩家，可能为空或不在线。
+     * @param expansion 抛出异常的变量处理器
+     * @param exception 异常内容
+     * @return 返回给玩家的内容
+     */
+    public String onException(@Nullable OfflinePlayer player, @NotNull SubExpansion<?> expansion, @NotNull Exception exception) {
+        exception.printStackTrace();
+        return "Error \"" + expansion.getIdentifier() + "\"";
+    }
+
+    /**
+     * 处理变量并返回对应内容。
+     *
+     * @param identifier 该变量的标识符
+     * @param handler    该组变量的处理器，返回值将会被转换为字符串。
+     * @param aliases    该变量的别称
+     * @return {@link  EasyPlaceholder}
+     */
+    public final EasyPlaceholder handle(String identifier, @NotNull PlaceholderHandler handler, @NotNull String... aliases) {
+        this.rootExpansion.handle(identifier, handler, aliases);
+        return this;
+    }
+
+    /**
+     * 处理一组变量。
+     *
+     * @param section  该组变量的标识符
+     * @param consumer 该组变量的处理器
+     *                 <br> 在其中可调用 {@link SectionExpansion#handle(String, PlaceholderHandler, String...)} 方法处理子变量,
+     *                 <br> 或者调用 {@link SectionExpansion#handleSection(String, Consumer, String...)} 方法处理下一层组变量
+     * @param aliases  该变量的别称
+     * @return {@link  EasyPlaceholder}
+     */
+    public final EasyPlaceholder handleSection(@NotNull String section,
+                                               @NotNull Consumer<SectionExpansion> consumer,
+                                               @NotNull String... aliases) {
+        this.rootExpansion.handleSection(section, consumer, aliases);
+        return this;
+    }
+
+    @Override
+    public String onRequest(@Nullable OfflinePlayer player, @NotNull String params) {
+        String[] args = params.split("_");
+        if (args.length == 0) return onErrorParams(player);
+
+        Object response = rootExpansion.handleRequest(player, args);
+        if (response == null) return onNullResponse(player);
+        else return response.toString();
+    }
+
+    @Override
+    public @Nullable String getRequiredPlugin() {
+        return this.plugin;
+    }
+
+    @Override
+    public @NotNull String getIdentifier() {
+        return this.rootExpansion.getIdentifier();
+    }
+
+    @Override
+    public @NotNull String getAuthor() {
+        return this.author;
+    }
+
+    @Override
+    public @NotNull String getVersion() {
+        return this.version;
+    }
+
+    @Override
+    public @NotNull String getName() {
+        return this.name;
+    }
+
+    @Override
+    public @NotNull List<String> getPlaceholders() {
+        return this.rootExpansion.listPlaceholders();
+    }
+
+    @Override
+    public boolean persist() {
+        return this.persistent;
+    }
+
+
+}
--- a/extension/papi/src/main/java/cc/carm/lib/easyplugin/papi/expansion/EasyExpansion.java
+++ b/extension/papi/src/main/java/cc/carm/lib/easyplugin/papi/expansion/EasyExpansion.java
@ -0,0 +1,13 @@
+package cc.carm.lib.easyplugin.papi.expansion;
+
+import org.jetbrains.annotations.NotNull;
+
+import java.util.List;
+
+public interface EasyExpansion {
+    
+    @NotNull String getIdentifier();
+
+    @NotNull List<String> getAliases();
+
+}
--- a/extension/papi/src/main/java/cc/carm/lib/easyplugin/papi/expansion/SectionExpansion.java
+++ b/extension/papi/src/main/java/cc/carm/lib/easyplugin/papi/expansion/SectionExpansion.java
@ -0,0 +1,179 @@
+package cc.carm.lib.easyplugin.papi.expansion;
+
+import cc.carm.lib.easyplugin.papi.EasyPlaceholder;
+import cc.carm.lib.easyplugin.papi.handler.PlaceholderHandler;
+import org.bukkit.OfflinePlayer;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.*;
+import java.util.function.Consumer;
+import java.util.function.Supplier;
+
+public class SectionExpansion implements EasyExpansion {
+
+    protected final EasyPlaceholder root;
+
+    protected final @NotNull String identifier;
+    protected final @NotNull List<String> aliases;
+
+    protected final @NotNull Map<String, SectionExpansion> registeredSections = new HashMap<>();
+    protected final @NotNull Map<String, SubExpansion<?>> registeredExpansions = new HashMap<>();
+
+    protected final @NotNull Map<String, String> aliasesMap = new HashMap<>();
+
+    public SectionExpansion(@NotNull EasyPlaceholder root,
+                            @NotNull String identifier, @NotNull String... aliases) {
+        this(root, identifier, Arrays.asList(aliases));
+    }
+
+    public SectionExpansion(@NotNull EasyPlaceholder root,
+                            @NotNull String identifier, @NotNull List<String> aliases) {
+        this.root = root;
+        this.identifier = identifier;
+        this.aliases = aliases;
+    }
+
+    public EasyPlaceholder getRoot() {
+        return root;
+    }
+
+    @NotNull
+    @Override
+    public String getIdentifier() {
+        return identifier;
+    }
+
+    @Override
+    public @NotNull List<String> getAliases() {
+        return this.aliases;
+    }
+
+    public void register(@NotNull SubExpansion<?> placeholder) {
+        String name = placeholder.getIdentifier().toLowerCase();
+        this.registeredExpansions.put(name, placeholder);
+        placeholder.getAliases().forEach(alias -> this.aliasesMap.put(alias.toLowerCase(), name));
+    }
+
+    public final void register(@NotNull SectionExpansion placeholder) {
+        String name = placeholder.getIdentifier().toLowerCase();
+        this.registeredSections.put(name, placeholder);
+        placeholder.getAliases().forEach(alias -> this.aliasesMap.put(alias.toLowerCase(), name));
+    }
+
+    public final void handle(@NotNull String identifier, @NotNull PlaceholderHandler handler,
+                             @NotNull String... aliases) {
+        handle(identifier, handler, Collections.emptyList(), aliases);
+    }
+
+    public final void handle(@NotNull String identifier, @NotNull PlaceholderHandler handler,
+                             @NotNull Consumer<ArrayList<String>> paramsConsumer, @NotNull String... aliases) {
+        handle(identifier, handler, () -> {
+            ArrayList<String> params = new ArrayList<>();
+            paramsConsumer.accept(params);
+            return params;
+        }, aliases);
+    }
+
+    public final void handle(@NotNull String identifier, @NotNull PlaceholderHandler handler,
+                             @NotNull List<String> availableParams, @NotNull String... aliases) {
+        handle(identifier, handler, () -> availableParams, aliases);
+    }
+
+    public final void handle(@NotNull String identifier, @NotNull PlaceholderHandler handler,
+                             @NotNull Supplier<List<String>> availableParams, @NotNull String... aliases) {
+        register(new SubExpansion<SectionExpansion>(this, identifier, aliases) {
+            @Override
+            public Object handle(@Nullable OfflinePlayer player, @NotNull String[] args) throws Exception {
+                return handler.handle(player, args);
+            }
+
+            @Override
+            public List<String> listAvailableParams() {
+                return availableParams.get();
+            }
+        });
+    }
+
+    public final void handleSection(@NotNull String section, @NotNull Consumer<SectionExpansion> consumer,
+                                    @NotNull String... aliases) {
+        SectionExpansion sectionExpansion = new SectionExpansion(getRoot(), section, aliases);
+        consumer.accept(sectionExpansion);
+        register(sectionExpansion);
+    }
+
+    public final @Nullable Object handleRequest(@Nullable OfflinePlayer player, @NotNull String[] args) {
+        if (args.length == 0) return getRoot().onErrorParams(player);
+        String input = args[0].toLowerCase();
+
+        SectionExpansion group = getHandler(input);
+        if (group != null) return group.handleRequest(player, this.shortenArgs(args));
+
+        SubExpansion<?> sub = getSubPlaceholder(input);
+        if (sub == null) return getRoot().onErrorParams(player);
+
+        try {
+            return sub.handle(player, this.shortenArgs(args));
+        } catch (Exception ex) {
+            return getRoot().onException(player, sub, ex);
+        }
+    }
+
+    public List<String> listPlaceholders() {
+        List<String> placeholders = new ArrayList<>();
+
+        String currentID = getIdentifier();
+
+        for (SectionExpansion section : this.registeredSections.values()) {
+            for (String groupID : section.listPlaceholders()) {
+                placeholders.add(currentID + "_" + groupID);
+            }
+        }
+
+        for (SubExpansion<?> placeholder : this.registeredExpansions.values()) {
+            String identifier = placeholder.getIdentifier();
+
+            List<String> params = placeholder.listAvailableParams();
+            if (params.isEmpty()) {
+                placeholders.add(currentID + "_" + identifier);
+                continue;
+            }
+
+            for (String param : params) {
+                placeholders.add(currentID + "_" + identifier + "_" + param);
+            }
+
+        }
+
+        return placeholders;
+    }
+
+
+    protected @Nullable SectionExpansion getHandler(@NotNull String name) {
+        SectionExpansion fromName = this.registeredSections.get(name);
+        if (fromName != null) return fromName;
+
+        String nameFromAlias = this.aliasesMap.get(name);
+        if (nameFromAlias == null) return null;
+        else return this.registeredSections.get(nameFromAlias);
+    }
+
+    protected @Nullable SubExpansion<?> getSubPlaceholder(@NotNull String name) {
+        SubExpansion<?> fromName = this.registeredExpansions.get(name);
+        if (fromName != null) return fromName;
+
+        String nameFromAlias = this.aliasesMap.get(name);
+        if (nameFromAlias == null) return null;
+        else return this.registeredExpansions.get(nameFromAlias);
+    }
+
+    protected String[] shortenArgs(String[] args) {
+        if (args.length == 0) {
+            return args;
+        } else {
+            List<String> argList = new ArrayList<>(Arrays.asList(args).subList(1, args.length));
+            return argList.toArray(new String[0]);
+        }
+    }
+
+}
--- a/extension/papi/src/main/java/cc/carm/lib/easyplugin/papi/expansion/SubExpansion.java
+++ b/extension/papi/src/main/java/cc/carm/lib/easyplugin/papi/expansion/SubExpansion.java
@ -0,0 +1,44 @@
+package cc.carm.lib.easyplugin.papi.expansion;
+
+import org.bukkit.OfflinePlayer;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+public abstract class SubExpansion<PARENT extends SectionExpansion> implements EasyExpansion {
+
+    protected final @NotNull PARENT parent;
+    protected final @NotNull String identifier;
+    protected final @NotNull List<String> aliases;
+
+    public SubExpansion(@NotNull PARENT parent,
+                        @NotNull String identifier, @NotNull String... aliases) {
+        this.parent = parent;
+        this.identifier = identifier;
+        this.aliases = Arrays.asList(aliases);
+    }
+
+    public abstract Object handle(@Nullable OfflinePlayer player, @NotNull String[] args) throws Exception;
+
+    /**
+     * 用于提示此子变量的全部可用参数
+     *
+     * @return 该子变量的全部可用参数
+     */
+    public List<String> listAvailableParams() {
+        return Collections.emptyList();
+    }
+
+    @Override
+    public @NotNull String getIdentifier() {
+        return this.identifier;
+    }
+
+    @Override
+    public @NotNull List<String> getAliases() {
+        return this.aliases;
+    }
+}
--- a/extension/papi/src/main/java/cc/carm/lib/easyplugin/papi/handler/PlaceholderHandler.java
+++ b/extension/papi/src/main/java/cc/carm/lib/easyplugin/papi/handler/PlaceholderHandler.java
@ -0,0 +1,12 @@
+package cc.carm.lib.easyplugin.papi.handler;
+
+import org.bukkit.OfflinePlayer;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+@FunctionalInterface
+public interface PlaceholderHandler {
+
+    @Nullable Object handle(@Nullable OfflinePlayer player, @NotNull String[] args) throws Exception;
+
+}
--- a/extension/papi/src/test/java/cc/carm/tests/easyplugin/papi/DemoPlaceholder.java
+++ b/extension/papi/src/test/java/cc/carm/tests/easyplugin/papi/DemoPlaceholder.java
@ -0,0 +1,77 @@
+package cc.carm.tests.easyplugin.papi;
+
+import cc.carm.lib.easyplugin.papi.EasyPlaceholder;
+import cc.carm.lib.easyplugin.papi.expansion.SubExpansion;
+import org.bukkit.OfflinePlayer;
+import org.bukkit.entity.Player;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.Arrays;
+import java.util.Objects;
+
+public class DemoPlaceholder extends EasyPlaceholder {
+
+    public DemoPlaceholder() {
+        super(
+                "TestPlugin", true, "TestPlaceholder",
+                "TestPlugin", "1.0.0", "Carm"
+        );
+
+        handle("version", (player, args) -> "1.0.0", "ver", "v");
+        handleSection("game", (section) -> {
+
+            // 即处理 %TestPlaceholder_game_items%
+            section.handle("items", ((player, args) -> {
+                if (player == null || !player.isOnline() || !(player instanceof Player)) return -1;
+                PlayerInventory inv = ((Player) player).getInventory();
+                return Arrays.stream(inv.getContents())
+                        .filter(Objects::nonNull)
+                        .mapToInt(ItemStack::getAmount)
+                        .count();
+            }));
+
+            // 即处理 %TestPlaceholder_game_location% 或 %TestPlaceholder_game_loc%
+            section.handle("location", (player, args) -> {
+                if (player == null || !player.isOnline() || !(player instanceof Player)) return "Unknown";
+                return ((Player) player).getLocation();
+            }, "loc" /* 声明此变量的别称*/);
+
+            // 即处理 %TestPlaceholder_game_time%
+            section.handle("time", (player, args) -> System.currentTimeMillis());
+
+            section.handle("random",
+                    (player, args) -> {
+                        if (args.length == 0) return Math.random();
+                        else if (args.length == 1) return Math.random() * Double.parseDouble(args[0]);
+                        else if (args.length == 2) {
+                            return Math.random() * (Double.parseDouble(args[1]) - Double.parseDouble(args[0])) + Double.parseDouble(args[0]);
+                        } else return onErrorParams(player);
+                    },
+                    (params) -> {
+                        params.add("<最小值>_<最大值>");
+                        params.add("<基础值(乘随机数)>");
+                    });
+
+        }, "g");
+
+    }
+
+    @Override
+    public String onErrorParams(@Nullable OfflinePlayer player) {
+        return super.onErrorParams(player);
+    }
+
+    @Override
+    public String onNullResponse(@Nullable OfflinePlayer player) {
+        return super.onNullResponse(player);
+    }
+
+    @Override
+    public String onException(@Nullable OfflinePlayer player, @NotNull SubExpansion<?> expansion, @NotNull Exception exception) {
+        return super.onException(player, expansion, exception);
+    }
+
+}
--- a/extension/papi/src/test/java/cc/carm/tests/easyplugin/papi/PlaceholderTest.java
+++ b/extension/papi/src/test/java/cc/carm/tests/easyplugin/papi/PlaceholderTest.java
@ -0,0 +1,37 @@
+package cc.carm.tests.easyplugin.papi;
+
+import cc.carm.lib.easyplugin.papi.EasyPlaceholder;
+import org.junit.Test;
+
+public class PlaceholderTest {
+
+
+    @Test
+    public void onTest() {
+        DemoPlaceholder placeholder = new DemoPlaceholder();
+
+        System.out.println("# Placeholders");
+        placeholder.getPlaceholders().forEach(s -> System.out.println(" -> " + s));
+
+        System.out.println();
+        System.out.println("# Request tests");
+
+        test(placeholder, "game_items");
+        test(placeholder, "g_time");
+        test(placeholder, "game_loc");
+        test(placeholder, "ver");
+
+        test(placeholder, "game_random");
+        test(placeholder, "game_random_0_5");
+        test(placeholder, "game_random_100");
+
+        System.out.println("# Error tests");
+        test(placeholder, "game_random_try");
+    }
+
+    private void test(EasyPlaceholder placeholder, String input) {
+        System.out.println(" " + input + " -> " + placeholder.onRequest(null, input));
+    }
+
+
+}