feat(color): 修复ColorParser重复的问题

README.md

@@ -36,6 +36,9 @@
 
 ### 主要部分 (`/base`)
 
+- Color  [`easyplugin-color`](base/color)
+    - 颜色工具类模块，提供功能全面的MC颜色解析转换工具。
+    - 支持 `&+颜色代码`(原版颜色)、`§(#XXXXXX)`(RGB颜色) 与 `&<#XXXXXX>`(前后标注RGB颜色渐变)。
 - Utils  [`easyplugin-utils`](base/utils)
     - 通用工具类模块，该模块中的内容支持在Bungee、Bukkit使用。
     - 本模块提供
@@ -69,6 +72,7 @@
 ### 附属部分 (`/extension`)
 
 - [PlaceholderAPI](https://www.spigotmc.org/resources/6245/) [`easyplugin-placeholderapi`](extension/papi)
+  - PlaceholderAPI 扩展模块，提供了方便的 PlaceholderAPI 变量注册方法。
 - [Vault](https://github.com/MilkBowl/VaultAPI)* [`easyplugin-vault`](extension/vault)
 
 ## 开发

base/color/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>cc.carm.lib</groupId>
         <artifactId>easyplugin-parent</artifactId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <properties>

base/color/src/main/java/cc/carm/lib/easyplugin/utils/ColorParser.java

@@ -162,9 +162,14 @@ public class ColorParser {
                 startColor.getBlue() + bStep * i * bDirection
         )).toArray(String[]::new);
 
-        return IntStream.range(0, characters.length)
+        StringBuilder sb = new StringBuilder();
-                .mapToObj(i -> colorText(characters[i], extraFormats.get(i), buildHexColor(hexes[i])))
+        String extra = null;
-                .collect(Collectors.joining());
+        for (int i = 0; i < characters.length; i++) {
+            extra = buildExtraFormat(extra, extraFormats.get(i));
+            String s = colorText(characters[i], extra, buildHexColor(hexes[i]));
+            sb.append(s);
+        }
+        return sb.toString();
     }
 
     protected static String gradientText(@NotNull String text, @Nullable String startHex, @Nullable String endHex) {
@@ -205,4 +210,13 @@ public class ColorParser {
                 .collect(Collectors.joining("", '§' + "x", ""));
     }
 
+    protected static String buildExtraFormat(String current, String extra) {
+        if (extra != null) current = (current == null ? "" : current) + extra;
+        return isResetCode(current) ? null : current;
+    }
+
+    protected static boolean isResetCode(String input) {
+        return input != null && (input.toLowerCase().endsWith("&r") || input.toLowerCase().endsWith("§r"));
+    }
+
 }

base/color/src/test/java/ColorParseTest.java

@@ -15,7 +15,7 @@ public class ColorParseTest {
         System.out.println(parseGradientColor("&<#AAAAAA>我真的&<#BBBBBB>爱死&<#111111>你&<#FFFFFF>！"));
 
         // 测试穿插
-        System.out.println(parse("&<#AAAAAA>&l我&r真&b的&<#BBBBBB>&o爱死&<#111111>你&<#FFFFFF>了&r！"));
+        System.out.println(parse("&<#AAAAAA>&l&m我真的&o尊的&r真的&<#BBBBBB>&o爱死&<#111111>你&<#FFFFFF>了&r！"));
         System.out.println(parse("&<#AAAAAA>&l我&r真&(#666666)的&<#BBBBBB>&o爱死&<#111111>你&<#FFFFFF>了&r！"));
         System.out.println(parse("&r正常的颜色理应&c&l不受影响&r。"));
 

base/command-alias/pom.xml

@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>cc.carm.lib</groupId>
+        <artifactId>easyplugin-parent</artifactId>
+        <version>1.5.9</version>
+        <relativePath>../../pom.xml</relativePath>
+    </parent>
+    <properties>
+        <maven.compiler.source>${project.jdk.version}</maven.compiler.source>
+        <maven.compiler.target>${project.jdk.version}</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
+    </properties>
+    <artifactId>easyplugin-command-alias</artifactId>
+    <packaging>jar</packaging>
+
+    <name>EasyPlugin-Command-Alias</name>
+    <description>轻松插件指令别名映射模块，支持将插件内复杂的子指令简化为一个单独的指令，方便玩家使用。</description>
+    <url>https://github.com/CarmJos/EasyPlugin</url>
+
+    <developers>
+        <developer>
+            <id>CarmJos</id>
+            <name>Carm Jos</name>
+            <email>carm@carm.cc</email>
+            <url>https://www.carm.cc</url>
+        </developer>
+    </developers>
+
+    <licenses>
+        <license>
+            <name>The MIT License</name>
+            <url>https://opensource.org/licenses/MIT</url>
+        </license>
+    </licenses>
+
+    <issueManagement>
+        <system>GitHub Issues</system>
+        <url>https://github.com/CarmJos/EasyPlugin/issues</url>
+    </issueManagement>
+
+    <ciManagement>
+        <system>GitHub Actions</system>
+        <url>https://github.com/CarmJos/EasyPlugin/actions/workflows/maven.yml</url>
+    </ciManagement>
+
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

base/command-alias/src/main/java/cc/carm/lib/easyplugin/command/alias/AliasCommand.java

@@ -0,0 +1,51 @@
+package cc.carm.lib.easyplugin.command.alias;
+
+import org.bukkit.Location;
+import org.bukkit.command.Command;
+import org.bukkit.command.CommandSender;
+import org.bukkit.command.SimpleCommandMap;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Optional;
+
+public class AliasCommand extends Command {
+
+    protected final AliasCommandManager aliasCommandManager;
+    protected final String targetCommand;
+
+    public AliasCommand(String name, AliasCommandManager aliasCommandManager, String targetCommand) {
+        super(name);
+        this.aliasCommandManager = aliasCommandManager;
+        this.targetCommand = targetCommand;
+    }
+
+    protected SimpleCommandMap getCommandMap() {
+        return this.aliasCommandManager.getCommandMap();
+    }
+
+    protected String buildCommand(String[] args) {
+        return this.targetCommand + " " + String.join(" ", args);
+    }
+
+    @Override
+    public boolean execute(@NotNull CommandSender sender, @NotNull String commandLabel, @NotNull String[] args) {
+        return getCommandMap().dispatch(sender, buildCommand(args));
+    }
+
+    @NotNull
+    @Override
+    public List<String> tabComplete(@NotNull CommandSender sender, @NotNull String alias,
+                                    @NotNull String[] args, @Nullable Location location) throws IllegalArgumentException {
+        return Optional.ofNullable(getCommandMap().tabComplete(sender, buildCommand(args))).orElse(Collections.emptyList());
+    }
+
+    @NotNull
+    @Override
+    public List<String> tabComplete(@NotNull CommandSender sender, @NotNull String alias, @NotNull String[] args) throws IllegalArgumentException {
+        return tabComplete(sender, alias, args, null);
+    }
+
+}

base/command-alias/src/main/java/cc/carm/lib/easyplugin/command/alias/AliasCommandManager.java

@@ -0,0 +1,88 @@
+package cc.carm.lib.easyplugin.command.alias;
+
+import org.bukkit.Bukkit;
+import org.bukkit.command.Command;
+import org.bukkit.command.SimpleCommandMap;
+import org.bukkit.plugin.SimplePluginManager;
+import org.bukkit.plugin.java.JavaPlugin;
+import org.jetbrains.annotations.NotNull;
+
+import java.lang.reflect.Field;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * 指令简化别名(简化映射)管理器
+ * <br>支持将插件内复杂的子指令简化为一个单独的指令，方便玩家使用。
+ */
+public class AliasCommandManager {
+
+    protected final @NotNull JavaPlugin plugin;
+    protected final @NotNull String prefix;
+
+    protected final @NotNull SimpleCommandMap commandMap;
+    protected final @NotNull Field knownCommandsFiled;
+
+    protected final @NotNull Map<String, AliasCommand> registeredCommands = new HashMap<>();
+
+    public AliasCommandManager(@NotNull JavaPlugin plugin) throws Exception {
+        this(plugin, plugin.getName());
+    }
+
+    public AliasCommandManager(@NotNull JavaPlugin plugin, @NotNull String prefix) throws Exception {
+        this.plugin = plugin;
+        this.prefix = prefix.trim();
+
+        SimplePluginManager manager = (SimplePluginManager) Bukkit.getPluginManager();
+        Field commandMapField = SimplePluginManager.class.getDeclaredField("commandMap");
+        commandMapField.setAccessible(true);
+        this.commandMap = (SimpleCommandMap) commandMapField.get(manager);
+
+        this.knownCommandsFiled = SimpleCommandMap.class.getDeclaredField("knownCommands");
+        this.knownCommandsFiled.setAccessible(true);
+    }
+
+    @SuppressWarnings("unchecked")
+    protected Map<String, Command> getKnownCommands() {
+        try {
+            return (Map<String, Command>) knownCommandsFiled.get(commandMap);
+        } catch (IllegalAccessException e) {
+            e.printStackTrace();
+        }
+        return new HashMap<>();
+    }
+
+    protected @NotNull SimpleCommandMap getCommandMap() {
+        return commandMap;
+    }
+
+    public String getCommandPrefix() {
+        return this.prefix;
+    }
+
+    public void register(@NotNull String alias, @NotNull String subCommand) {
+        AliasCommand current = this.registeredCommands.get(alias);
+        if (current != null) current.unregister(getCommandMap());
+
+        AliasCommand cmd = new AliasCommand(alias, this, getCommandPrefix() + " " + subCommand);
+        this.registeredCommands.put(alias, cmd);
+        getCommandMap().register(plugin.getName(), cmd);
+    }
+
+    public void unregister(@NotNull String alias) {
+        AliasCommand current = this.registeredCommands.remove(alias);
+        if (current != null) {
+            getKnownCommands().remove(alias);
+            current.unregister(getCommandMap());
+        }
+    }
+
+    public void unregisterAll() {
+        registeredCommands.forEach((k, v) -> {
+            getKnownCommands().remove(k);
+            v.unregister(getCommandMap());
+        });
+        registeredCommands.clear();
+    }
+
+}

base/command/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

base/gui/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

base/gui/src/main/java/cc/carm/lib/easyplugin/gui/GUI.java

@@ -34,7 +34,7 @@ public class GUI {
     }
 
     protected GUIType type;
-    protected String name;
+    protected String title;
     public HashMap<Integer, GUIItem> items;
     public Inventory inv;
 
@@ -57,14 +57,13 @@ public class GUI {
 
     protected GUIListener listener;
 
-    public GUI(GUIType type, String name) {
+    public GUI(GUIType type, String title) {
         this.type = type;
-        this.name = ColorParser.parse(name);
+        this.title = ColorParser.parse(title);
         this.items = new HashMap<>();
     }
 
-
+    public Map<@NotNull Integer, @NotNull GUIItem> getItems() {
-    public HashMap<@NotNull Integer, @NotNull GUIItem> getItems() {
         return new HashMap<>(items);
     }
 
@@ -90,6 +89,7 @@ public class GUI {
      * 更新玩家箱子的视图
      */
     public void updateView() {
+        this.onUpdate();
         if (this.inv != null) {
             List<HumanEntity> viewers = this.inv.getViewers();
             IntStream.range(0, this.inv.getSize()).forEach(index -> inv.setItem(index, new ItemStack(Material.AIR)));
@@ -148,7 +148,7 @@ public class GUI {
             throw new IllegalStateException("被取消或不存在的GUI");
         }
 
-        Inventory inv = Bukkit.createInventory(null, this.type.getSize(), this.name);
+        Inventory inv = Bukkit.createInventory(null, this.type.getSize(), this.title);
         IntStream.range(0, inv.getSize()).forEach(index -> inv.setItem(index, new ItemStack(Material.AIR)));
         getItems().forEach((index, item) -> inv.setItem(index, item.getDisplay()));
 
@@ -181,12 +181,18 @@ public class GUI {
     public void onClose() {
     }
 
+    /**
+     * 当GUI更新时执行的代码
+     */
+    public void onUpdate() {
+    }
+
     public GUIType getGUIType() {
         return type;
     }
 
     public String getGUIName() {
-        return name;
+        return title;
     }
 
     public static void setOpenedGUI(Player player, GUI gui) {

base/gui/src/main/java/cc/carm/lib/easyplugin/gui/paged/CommonPagedGUI.java

@@ -93,10 +93,8 @@ public class CommonPagedGUI extends PagedGUI {
      * 前往第一页
      */
     public void goFirstPage() {
-        if (hasPreviousPage())
+        this.page = 1;
-            this.page = 1;
+        onPageChange(this.page);
-        else
-            throw new IndexOutOfBoundsException();
     }
 
 
@@ -104,10 +102,8 @@ public class CommonPagedGUI extends PagedGUI {
      * 前往最后一页
      */
     public void goLastPage() {
-        if (hasNextPage())
+        this.page = getLastPageNumber();
-            this.page = getLastPageNumber();
+        onPageChange(this.page);
-        else
-            throw new IndexOutOfBoundsException();
     }
 
 
@@ -117,7 +113,7 @@ public class CommonPagedGUI extends PagedGUI {
      * @return 最后一页的页码
      */
     public int getLastPageNumber() {
-        return (this.container.size() / range.length) + 1;
+        return (this.container.size() / range.length) + ((this.container.size() % range.length) == 0 ? 0 : 1);
     }
 
     /**

base/gui/src/main/java/cc/carm/lib/easyplugin/gui/paged/PagedGUI.java

@@ -44,14 +44,20 @@ public abstract class PagedGUI extends GUI {
         return new ArrayList<>(container);
     }
 
+    /**
+     * 当GUI改变页码时执行的代码
+     */
+    public void onPageChange(int pageNum) {
+    }
+
     /**
      * 前往上一页
      */
     public void goPreviousPage() {
-        if (hasPreviousPage())
+        if (hasPreviousPage()) {
             page--;
-        else
+            this.onPageChange(this.page);
-            throw new IndexOutOfBoundsException();
+        } else throw new IndexOutOfBoundsException();
     }
 
 
@@ -59,10 +65,10 @@ public abstract class PagedGUI extends GUI {
      * 前往下一页
      */
     public void goNextPage() {
-        if (hasNextPage())
+        if (hasNextPage()) {
             page++;
-        else
+            this.onPageChange(this.page);
-            throw new IndexOutOfBoundsException();
+        } else throw new IndexOutOfBoundsException();
     }
 
 

base/main/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

base/main/src/main/java/cc/carm/lib/easyplugin/utils/ColorParser.java

@@ -1,208 +0,0 @@
-package cc.carm.lib.easyplugin.utils;
-
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-
-import java.awt.*;
-import java.util.List;
-import java.util.*;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
-import java.util.stream.Collectors;
-import java.util.stream.IntStream;
-
-/**
- * 颜色解析器。
- * <br> 普通颜色 格式 {@code &+颜色代码 }，如 {@literal &c} 、{@literal &a}
- * <br> RGB颜色(版本需要≥1.14) 格式 {@code &(#XXXXXX) }，如 {@literal &(#aaaaaa)}
- * <br> 渐变RBG颜色(版本需要≥1.14) 格式 {@code &<#XXXXXX>FOOBAR&<#XXXXXX> }
- * <p> 注意：当使用渐变RGB颜色时，普通颜色代码与RGB颜色代码将失效。
- */
-public class ColorParser {
-
-    public static final Pattern HEX_PATTERN = Pattern.compile("&\\(&?#([\\da-fA-F]{6})\\)");
-    public static final Pattern GRADIENT_PATTERN = Pattern.compile("&<&?#([\\da-fA-F]{6})>");
-    public static final Pattern COLOR_PATTERN = Pattern.compile("([&§][0-9a-fA-FrRxX])+"); // 会影响颜色的代码
-    public static final Pattern FORMAT_PATTERN = Pattern.compile("([&§][0-9a-fA-Fk-oK-OrRxX])+"); // MC可用的格式化代码
-
-    /**
-     * 清除一条消息中的全部颜色代码 (包括RGB颜色代码与渐变颜色代码)
-     *
-     * @param text 源消息内容
-     * @return 清理颜色后的消息
-     */
-    public static @NotNull String clear(@NotNull String text) {
-        text = HEX_PATTERN.matcher(text).replaceAll("");
-        text = GRADIENT_PATTERN.matcher(text).replaceAll("");
-        text = COLOR_PATTERN.matcher(text).replaceAll("");
-        return text;
-    }
-
-    /**
-     * 对一条消息进行颜色解析，包括普通颜色代码、RGB颜色代码与RBG渐变代码。
-     *
-     * @param text 源消息内容
-     * @return 解析后的消息
-     */
-    public static @NotNull String parse(@NotNull String text) {
-        return parseBaseColor(parseGradientColor(parseHexColor(text)));
-    }
-
-    /**
-     * 对多条消息进行颜色解析，包括普通颜色代码、RGB颜色代码与RBG渐变代码。
-     *
-     * @param texts 源消息内容
-     * @return 解析后的消息
-     */
-    public static @NotNull String[] parse(@NotNull String... texts) {
-        return parse(Arrays.asList(texts)).toArray(new String[0]);
-    }
-
-    /**
-     * 对多条消息进行颜色解析，包括普通颜色代码、RGB颜色代码与RBG渐变代码。
-     *
-     * @param texts 源消息内容
-     * @return 解析后的消息
-     */
-    public static @NotNull List<String> parse(@NotNull Collection<String> texts) {
-        return texts.stream().map(ColorParser::parse).collect(Collectors.toList());
-    }
-
-    /**
-     * 解析消息中的基本颜色代码格式 {@code &+颜色代码 }，如 {@literal &c} 、{@literal &a}
-     *
-     * @param text 消息内容
-     * @return RGB处理后的消息
-     * @see net.md_5.bungee.api.ChatColor
-     */
-    public static String parseBaseColor(final String text) {
-        return text.replaceAll("&", "§").replace("§§", "&");
-    }
-
-    /**
-     * 解析消息中的RGB颜色代码(版本需要≥1.14) 格式 {@code &(#XXXXXX) }，如 {@literal &(#aaaaaa)}
-     *
-     * @param text 消息内容
-     * @return RGB处理后的消息
-     */
-    public static String parseHexColor(String text) {
-        Matcher matcher = HEX_PATTERN.matcher(text);
-        while (matcher.find()) {
-            text = matcher.replaceFirst(buildHexColor(matcher.group(1)).toLowerCase());
-            matcher.reset(text);
-        }
-        return text;
-    }
-
-    /**
-     * 对一条消息进行RGB渐变处理(版本需要≥1.14)，格式 {@code &<#XXXXXX>FOOBAR&<#XXXXXX> }。
-     *
-     * @param text 消息内容
-     * @return RGB渐变处理后的消息
-     */
-    public static @NotNull String parseGradientColor(@NotNull String text) {
-        List<String> colors = new ArrayList<>();
-
-        Matcher matcher = ColorParser.GRADIENT_PATTERN.matcher(text);
-        while (matcher.find()) colors.add(matcher.group(1));
-
-        if (colors.isEmpty()) return text; // 无渐变颜色，直接跳出
-
-        String[] parts = ColorParser.GRADIENT_PATTERN.split(text);
-        StringBuilder builder = new StringBuilder();
-        for (int i = 0; i < parts.length; i++) {
-            String startHex = i - 1 >= 0 && colors.size() > i - 1 ? colors.get(i - 1) : null; // 本条消息的起始颜色
-            String endHex = colors.size() > i ? colors.get(i) : null; // 本条消息的结束颜色
-            builder.append(gradientText(parts[i], startHex, endHex));
-        }
-
-        return builder.toString();
-    }
-
-    public static @NotNull String gradientText(@NotNull String text,
-                                               @Nullable Color startColor, @Nullable Color endColor) {
-        Objects.requireNonNull(text, "Text to be gradient should not be null!");
-        if (startColor == null || endColor == null || text.isEmpty()) {
-            // 起始颜色有任一为空，则不进行渐变上色。
-            // 若有起始颜色，则代表其跟在某个渐变之后，应当添加"&r"阻断前面的渐变。
-            return (startColor != null ? "&r" : "") + text;
-        }
-
-        // 用于记录消息中特殊格式的位置
-        // 在渐变中，允许使用格式字符与颜色字符来改变其中某个字的颜色/格式，以支持更多形式内容。
-        LinkedHashMap<Integer, String> extraFormats = new LinkedHashMap<>();
-        Matcher matcher = ColorParser.FORMAT_PATTERN.matcher(text);
-        while (matcher.find()) {
-            extraFormats.put(matcher.start(), matcher.group());
-            text = matcher.replaceFirst("");
-            matcher.reset(text);
-        }
-
-        if (text.length() == 1) {
-            // 当只有一个实际字符时，无需进行渐变计算，直接返回 中间颜色+起始格式(如果有)+消息 即可。
-            return colorText(text, extraFormats.get(0), buildHexColor(mediumHex(startColor, endColor)));
-        }
-
-        String[] characters = text.split("");
-        int step = characters.length; // 变换次数
-
-        // 决定每种颜色变换的方向
-        int rDirection = startColor.getRed() < endColor.getRed() ? 1 : -1;
-        int gDirection = startColor.getGreen() < endColor.getGreen() ? 1 : -1;
-        int bDirection = startColor.getBlue() < endColor.getBlue() ? 1 : -1;
-
-        // 决定每种颜色每次变换的度
-        int rStep = Math.abs(startColor.getRed() - endColor.getRed()) / (step - 1);
-        int gStep = Math.abs(startColor.getGreen() - endColor.getGreen()) / (step - 1);
-        int bStep = Math.abs(startColor.getBlue() - endColor.getBlue()) / (step - 1);
-
-        String[] hexes = IntStream.range(0, step).mapToObj(i -> colorToHex(
-                startColor.getRed() + rStep * i * rDirection,
-                startColor.getGreen() + gStep * i * gDirection,
-                startColor.getBlue() + bStep * i * bDirection
-        )).toArray(String[]::new);
-
-        return IntStream.range(0, characters.length)
-                .mapToObj(i -> colorText(characters[i], extraFormats.get(i), buildHexColor(hexes[i])))
-                .collect(Collectors.joining());
-    }
-
-    protected static String gradientText(@NotNull String text, @Nullable String startHex, @Nullable String endHex) {
-        return gradientText(text,
-                startHex == null ? null : Color.decode("0x" + startHex),
-                endHex == null ? null : Color.decode("0x" + endHex)
-        );
-    }
-
-    private static String mediumHex(@NotNull Color start, @NotNull Color end) {
-        return colorToHex(
-                Math.abs(start.getRed() - end.getRed()) / 2,
-                Math.abs(start.getGreen() - end.getGreen()) / 2,
-                Math.abs(start.getBlue() - end.getBlue()) / 2
-        );
-    }
-
-    private static String colorText(String message, @Nullable String format, @Nullable String color) {
-        if (format != null && COLOR_PATTERN.matcher(format).find()) {
-            // format中存在影响颜色的内容，则当前消息的颜色会被覆盖。
-            // 为了减少最终消息的长度，故直接返回键入的FORMAT和对应消息的内容。
-            return format + message;
-        }
-        return (color == null ? "" : color) + (format == null ? "" : parseBaseColor(format)) + message;
-    }
-
-    protected static String colorToHex(Color color) {
-        return colorToHex(color.getRed(), color.getGreen(), color.getBlue());
-    }
-
-    protected static String colorToHex(int r, int g, int b) {
-        // 将R、G、B转换为16进制(若非2位则补0)输出
-        return String.format("%02X%02X%02X", r, g, b);
-    }
-
-    protected static String buildHexColor(String hexCode) {
-        return Arrays.stream(hexCode.split("")).map(s -> '§' + s)
-                .collect(Collectors.joining("", '§' + "x", ""));
-    }
-
-}

base/messages/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>cc.carm.lib</groupId>
         <artifactId>easyplugin-parent</artifactId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <properties>

base/storage/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

base/user/pom.xml

@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>cc.carm.lib</groupId>
+        <artifactId>easyplugin-parent</artifactId>
+        <version>1.5.9</version>
+        <relativePath>../../pom.xml</relativePath>
+    </parent>
+    <properties>
+        <maven.compiler.source>${project.jdk.version}</maven.compiler.source>
+        <maven.compiler.target>${project.jdk.version}</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
+    </properties>
+    <artifactId>easyplugin-user</artifactId>
+
+    <developers>
+        <developer>
+            <id>CarmJos</id>
+            <name>Carm Jos</name>
+            <email>carm@carm.cc</email>
+            <url>https://www.carm.cc</url>
+        </developer>
+    </developers>
+
+    <licenses>
+        <license>
+            <name>The MIT License</name>
+            <url>https://opensource.org/licenses/MIT</url>
+        </license>
+    </licenses>
+
+    <issueManagement>
+        <system>GitHub Issues</system>
+        <url>https://github.com/CarmJos/EasyPlugin/issues</url>
+    </issueManagement>
+
+    <ciManagement>
+        <system>GitHub Actions</system>
+        <url>https://github.com/CarmJos/EasyPlugin/actions/workflows/maven.yml</url>
+    </ciManagement>
+
+    <dependencies>
+        <dependency>
+            <groupId>${project.parent.groupId}</groupId>
+            <artifactId>easyplugin-main</artifactId>
+            <version>${project.parent.version}</version>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

base/user/src/main/java/cc/carm/lib/easyplugin/user/UserData.java

@@ -0,0 +1,32 @@
+package cc.carm.lib.easyplugin.user;
+
+import org.jetbrains.annotations.NotNull;
+
+import java.util.Objects;
+
+public abstract class UserData<K> {
+
+    protected final @NotNull K key;
+
+    protected UserData(@NotNull K key) {
+        this.key = key;
+    }
+
+    public @NotNull K getKey() {
+        return key;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        UserData<?> userData = (UserData<?>) o;
+        return key.equals(userData.key);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(key);
+    }
+
+}

base/user/src/main/java/cc/carm/lib/easyplugin/user/UserDataManager.java

@@ -0,0 +1,250 @@
+package cc.carm.lib.easyplugin.user;
+
+import cc.carm.lib.easyplugin.EasyPlugin;
+import com.google.common.collect.ImmutableSet;
+import org.bukkit.Bukkit;
+import org.bukkit.OfflinePlayer;
+import org.bukkit.entity.Player;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.util.*;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import java.util.function.Predicate;
+import java.util.function.Supplier;
+import java.util.logging.Logger;
+import java.util.stream.Collectors;
+
+public abstract class UserDataManager<K, U extends UserData<K>> {
+
+    protected final @NotNull EasyPlugin plugin;
+
+    protected final @NotNull ExecutorService executor;
+    protected final @NotNull Map<K, U> dataCache;
+
+    public UserDataManager(@NotNull EasyPlugin plugin) {
+        this(plugin, Executors.newCachedThreadPool((r) -> {
+            Thread t = new Thread(r);
+            t.setDaemon(true);
+            t.setName(plugin.getName() + "-UserManager");
+            return t;
+        }), new ConcurrentHashMap<>());
+    }
+
+    public UserDataManager(@NotNull EasyPlugin plugin, @NotNull ExecutorService executor) {
+        this(plugin, executor, new ConcurrentHashMap<>());
+    }
+
+    public UserDataManager(@NotNull EasyPlugin plugin, @NotNull ExecutorService executor, @NotNull Map<K, U> cacheMap) {
+        this.plugin = plugin;
+        this.executor = executor;
+        this.dataCache = cacheMap;
+    }
+
+    public void shutdown() {
+        this.executor.shutdown();
+    }
+
+    protected @NotNull EasyPlugin getPlugin() {
+        return plugin;
+    }
+
+    protected @NotNull Logger getLogger() {
+        return getPlugin().getLogger();
+    }
+
+    public String serializeKey(@NotNull K key) {
+        return key.toString();
+    }
+
+    public abstract @NotNull U emptyUser(@NotNull K key);
+
+    public @NotNull U errorUser(@NotNull K key) {
+        return emptyUser(key);
+    }
+
+    protected abstract @Nullable U loadData(@NotNull K key) throws Exception;
+
+    protected abstract void saveData(@NotNull U data) throws Exception;
+
+    public @NotNull CompletableFuture<U> load(@NotNull K key) {
+        return load(key, false);
+    }
+
+    public @NotNull CompletableFuture<U> load(@NotNull K key, boolean cache) {
+        return load(key, () -> cache);
+    }
+
+    public @NotNull Map<K, U> getDataCache() {
+        return dataCache;
+    }
+
+    @Unmodifiable
+    public @NotNull Set<U> list() {
+        return ImmutableSet.copyOf(getDataCache().values());
+    }
+
+    public @NotNull U get(@NotNull K key) {
+        return Optional.ofNullable(getNullable(key)).orElseThrow(() -> new NullPointerException("User " + key + " not found."));
+    }
+
+    public @Nullable U getNullable(@NotNull K key) {
+        return getDataCache().get(key);
+    }
+
+    public @NotNull Optional<@Nullable U> getOptional(@NotNull K key) {
+        return Optional.ofNullable(getNullable(key));
+    }
+
+    public @NotNull CompletableFuture<U> load(@NotNull K key, @NotNull Supplier<Boolean> cacheCondition) {
+        return CompletableFuture.supplyAsync(() -> {
+            String identifier = serializeKey(key);
+
+            try {
+                long s1 = System.currentTimeMillis();
+                getPlugin().debug("开始加载用户 " + identifier + " 的数据...");
+                U data = loadData(key);
+                if (data == null) {
+                    getPlugin().debug("数据库内不存在用户 " + identifier + " 的数据，视作新档案。");
+                    return emptyUser(key);
+                } else {
+                    getPlugin().debug("加载用户 " + identifier + " 的数据完成，耗时 " + (System.currentTimeMillis() - s1) + " ms.");
+                    return data;
+                }
+            } catch (Exception ex) {
+                getPlugin().error("加载用户 " + serializeKey(key) + " 数据失败，请检查相关配置！");
+                ex.printStackTrace();
+                return errorUser(key);
+            }
+
+        }, executor).thenApply((data) -> {
+            if (cacheCondition.get()) dataCache.put(key, data);
+            return data;
+        });
+    }
+
+    public @NotNull CompletableFuture<Boolean> save(@NotNull U user) {
+        return CompletableFuture.supplyAsync(() -> {
+            String identifier = serializeKey(user.getKey());
+
+            try {
+                long s1 = System.currentTimeMillis();
+                getPlugin().debug("开始保存用户 " + identifier + " 的数据...");
+                saveData(user);
+                getPlugin().debug("保存用户 " + identifier + " 的数据完成，耗时 " + (System.currentTimeMillis() - s1) + " ms.");
+                return true;
+            } catch (Exception ex) {
+                getPlugin().error("保存用户 " + identifier + " 数据失败，请检查相关配置！");
+                ex.printStackTrace();
+                return false;
+            }
+
+        }, executor);
+    }
+
+    public @NotNull CompletableFuture<Boolean> unload(@NotNull K key) {
+        return unload(key, true);
+    }
+
+    public @NotNull CompletableFuture<Boolean> unload(@NotNull K key, boolean save) {
+        U data = getNullable(key);
+        if (data == null) return CompletableFuture.completedFuture(false);
+
+        if (save) {
+            return save(data).thenApply(result -> {
+                this.dataCache.remove(key);
+                return result;
+            });
+        } else {
+            this.dataCache.remove(key);
+            return CompletableFuture.completedFuture(true);
+        }
+
+    }
+
+    public @NotNull CompletableFuture<Boolean> modify(@NotNull K key, @NotNull Consumer<U> consumer) {
+        U cached = getNullable(key);
+        if (cached != null) {
+            return CompletableFuture.supplyAsync(() -> {
+                consumer.accept(cached);
+                return true;
+            }, executor);
+        } else {
+            return load(key, false).thenApply((data) -> {
+                consumer.accept(data);
+                return data;
+            }).thenCompose(this::save);
+        }
+    }
+
+    public <V> @NotNull CompletableFuture<V> peek(@NotNull K key, @NotNull Function<U, V> function) {
+        U cached = getNullable(key);
+        if (cached != null) {
+            return CompletableFuture.supplyAsync(() -> function.apply(cached), executor);
+        } else {
+            return load(key, false).thenApply(function);
+        }
+    }
+
+    public @NotNull CompletableFuture<Map<K, U>> loadOnline(@NotNull Function<Player, ? extends K> function) {
+        return loadGroup(Bukkit.getOnlinePlayers(), function, OfflinePlayer::isOnline);
+    }
+
+    public <T> @NotNull CompletableFuture<Map<K, U>> loadGroup(@NotNull Collection<? extends T> users,
+                                                               @NotNull Function<? super T, ? extends K> function,
+                                                               @NotNull Predicate<T> cacheCondition) {
+        CompletableFuture<Map<K, U>> task = CompletableFuture.completedFuture(new ConcurrentHashMap<>());
+        if (users.isEmpty()) return task;
+
+        Map<K, T> usersMap = users.stream().collect(Collectors.toMap(function, Function.identity()));
+        for (Map.Entry<K, T> entry : usersMap.entrySet()) {
+            K key = entry.getKey();
+            T user = entry.getValue();
+            task = task.thenCombine(
+                    load(key, () -> cacheCondition.test(user)),
+                    (map, result) -> {
+                        map.put(key, result);
+                        return map;
+                    }
+            );
+        }
+
+        return task.thenApply(Collections::unmodifiableMap);
+    }
+
+    public @NotNull CompletableFuture<Map<K, U>> loadGroup(@NotNull Collection<K> allKeys,
+                                                           @NotNull Predicate<K> cacheCondition) {
+        return loadGroup(allKeys, Function.identity(), cacheCondition);
+    }
+
+    public @NotNull CompletableFuture<Map<K, U>> loadGroup(@NotNull Collection<K> allKeys) {
+        return loadGroup(allKeys, (v) -> false);
+    }
+
+    public void saveAll() {
+        if (getDataCache().isEmpty()) return;
+        for (U u : getDataCache().values()) {
+            try {
+                saveData(u);
+            } catch (Exception e) {
+                getPlugin().error("保存用户 " + serializeKey(u.getKey()) + " 数据失败，请检查相关配置！");
+                e.printStackTrace();
+            }
+        }
+    }
+
+    public int unloadAll(boolean save) {
+        if (save) saveAll();
+        int size = getDataCache().size();
+        getDataCache().clear();
+        return size;
+    }
+
+
+}

base/utils/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

collection/all/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

collection/bom/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

collection/common/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

extension/gh-checker/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

extension/gh-checker/src/main/java/cc/carm/lib/easyplugin/updatechecker/GHUpdateChecker.java

@@ -1,7 +1,9 @@
 package cc.carm.lib.easyplugin.updatechecker;
 
 import cc.carm.lib.githubreleases4j.GithubReleases4J;
+import org.bukkit.Bukkit;
 import org.bukkit.plugin.Plugin;
+import org.bukkit.scheduler.BukkitTask;
 import org.jetbrains.annotations.NotNull;
 
 import java.util.List;
@@ -31,6 +33,10 @@ public class GHUpdateChecker {
         return of(plugin).createRunner(plugin.getDescription().getVersion());
     }
 
+    public static @NotNull BukkitTask run(@NotNull Plugin plugin) {
+        return Bukkit.getScheduler().runTaskAsynchronously(plugin, runner(plugin));
+    }
+
     protected final @NotNull Logger logger;
     protected final @NotNull String owner;
     protected final @NotNull String repo;

extension/papi/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>
@@ -21,6 +21,7 @@
     <packaging>jar</packaging>
 
     <name>EasyPlugin-PlaceholderAPI</name>
+    <description>EasyPlugin的 PlaceholderAPI 扩展模块，提供了方便的 PlaceholderAPI 变量注册方法。</description>
 
     <dependencies>
 

extension/vault/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easyplugin-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>1.5.2</version>
+        <version>1.5.9</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

extension/vault/src/main/java/cc/carm/lib/easyplugin/vault/EasyVault.java

@@ -0,0 +1,79 @@
+package cc.carm.lib.easyplugin.vault;
+
+import net.milkbowl.vault.economy.Economy;
+import net.milkbowl.vault.economy.EconomyResponse;
+import org.bukkit.Bukkit;
+import org.bukkit.OfflinePlayer;
+import org.bukkit.entity.Player;
+import org.bukkit.plugin.RegisteredServiceProvider;
+import org.jetbrains.annotations.NotNull;
+
+public class EasyVault {
+    public static boolean hasVault() {
+        return Bukkit.getServer().getPluginManager().getPlugin("Vault") != null;
+    }
+
+    public static @NotNull EasyVault create() throws Exception {
+        return new EasyVault();
+    }
+
+    private Economy economy = null;
+
+    public EasyVault() throws Exception {
+        if (!setupEconomy()) throw new Exception("Vault not found!");
+    }
+
+    public boolean setupEconomy() {
+        if (!hasVault()) return false;
+        RegisteredServiceProvider<Economy> rsp = Bukkit.getServer().getServicesManager().getRegistration(Economy.class);
+        if (rsp == null) return false;
+
+        this.economy = rsp.getProvider();
+        return true;
+    }
+
+    public Economy getEconomy() {
+        return economy;
+    }
+
+    public double getMoney(@NotNull Player player) {
+        try {
+            return getEconomy().getBalance(player);
+        } catch (NullPointerException ignore) {
+            return 0L;
+        }
+    }
+
+    public double getMoney(@NotNull OfflinePlayer player) {
+        try {
+            return getEconomy().getBalance(player);
+        } catch (NullPointerException ignore) {
+            return 0L;
+        }
+    }
+
+    public boolean checkMoney(@NotNull OfflinePlayer player, double amount) {
+        return getMoney(player) >= amount;
+    }
+
+    public boolean checkMoney(@NotNull Player player, double amount) {
+        return getMoney(player) >= amount;
+    }
+
+    public EconomyResponse removeMoney(Player player, double amount) {
+        return getEconomy().withdrawPlayer(player, amount);
+    }
+
+    public EconomyResponse removeMoney(OfflinePlayer player, double amount) {
+        return getEconomy().withdrawPlayer(player, amount);
+    }
+
+    public EconomyResponse addMoney(Player player, double amount) {
+        return getEconomy().depositPlayer(player, amount);
+    }
+
+    public EconomyResponse addMoney(OfflinePlayer player, double amount) {
+        return getEconomy().depositPlayer(player, amount);
+    }
+
+}

pom.xml

@@ -15,7 +15,7 @@
     <groupId>cc.carm.lib</groupId>
     <artifactId>easyplugin-parent</artifactId>
     <packaging>pom</packaging>
-    <version>1.5.2</version>
+    <version>1.5.9</version>
     <modules>
         <module>base/color</module>
         <module>base/utils</module>
@@ -24,7 +24,9 @@
         <module>base/messages</module>
         <module>base/gui</module>
         <module>base/command</module>
+        <module>base/command-alias</module>
         <module>base/storage</module>
+        <module>base/user</module>
 
         <module>extension/papi</module>
         <module>extension/vault</module>
@@ -33,7 +35,6 @@
         <module>collection/all</module>
         <module>collection/bom</module>
         <module>collection/common</module>
-
     </modules>
 
     <name>EasyPlugin</name>
@@ -80,13 +81,22 @@
     <repositories>
 
         <repository>
-            <id>central</id>
+            <id>sonatype</id>
-            <url>https://repo1.maven.org/maven2/</url>
+            <name>Sonatype Snapshot Repository</name>
+            <url>https://s01.oss.sonatype.org/content/groups/public/</url>
+            <snapshots>
+                <enabled>true</enabled>
+            </snapshots>
         </repository>
 
         <repository>
-            <id>sonatype</id>
+            <id>minebench-repo</id>
-            <url>https://oss.sonatype.org/content/groups/public</url>
+            <url>https://repo.minebench.de/</url>
+        </repository>
+
+        <repository>
+            <id>codemc-snapshots</id>
+            <url>https://repo.codemc.io/repository/maven-snapshots/</url>
         </repository>
 
         <repository>
@@ -142,22 +152,7 @@
             <dependency>
                 <groupId>cc.carm.lib</groupId>
                 <artifactId>githubreleases4j</artifactId>
-                <version>1.3.1</version>
+                <version>1.3.2</version>
-            </dependency>
-            <dependency>
-                <groupId>cc.carm.lib</groupId>
-                <artifactId>easylistener</artifactId>
-                <version>2.0.1</version>
-            </dependency>
-            <dependency>
-                <groupId>cc.carm.lib</groupId>
-                <artifactId>mineconfiguration-bukkit</artifactId>
-                <version>2.0.2</version>
-            </dependency>
-            <dependency>
-                <groupId>cc.carm.lib</groupId>
-                <artifactId>easysql-beecp</artifactId>
-                <version>0.4.3</version>
             </dependency>
         </dependencies>
     </dependencyManagement>