原创 经济 [1.13.x~1.21.x]墨积分-MoPoints 1.0.0

[MD] ### 🎮 插件交流群 [/MD]
点击加入【墨系列插件交流群】

[MD] # 墨积分 (MoPoints) **墨积分** 是一款高性能、可扩展的 Minecraft 积分管理插件，亦可作为经济插件使用。支持多种数据源存储、自定义积分项、排行榜系统，并完整对接 PlaceholderAPI，让积分管理与经济系统变得灵活而简单。 *** ## 功能特性 ### 核心功能 - **多积分项支持** — 在配置文件中自由定义多种积分类型（金币、点券、经验、声望等） - **双数据源** — 支持 SQLite（本地存储）和 MySQL（远程数据库），通过配置文件一键切换 - **异步操作** — 所有数据库操作均异步执行，绝不阻塞服务器主线程，保障 TPS 稳定 - **完整 CRUD** — 支持查询、设置、增加、扣除积分等完整操作 ### 命令系统 - **玩家命令** — 普通玩家可查询自己的积分和排行榜 - **管理员命令** — 可管理任意玩家的积分，支持在线补全 - **Tab 补全** — 所有命令均支持友好的 Tab 自动补全 ### 排行榜系统 - 支持分页查看各积分项的排行榜 - 每页显示数量可在配置文件中自定义 ### PlaceholderAPI 支持 - 完整对接 PlaceholderAPI，可在任何支持 PAPI 的插件中使用 - 支持显示玩家积分值、排行名称、排行分值 - 占位符格式简洁直观 ### 开发者友好 - 提供完备的公共 API，其他插件可通过 `MoPointsAPI` 轻松调用 - 通过 Bukkit ServicesManager 注册，获取方式灵活 - API 方法全部返回 `CompletableFuture`，方便异步编排 *** ## 配置文件 文件位置：`plugins/MoPoints/config.yml` ```yaml # 数据源设置 database: type: sqlite # sqlite 或 mysql sqlite: file: points.db # 数据库文件名 mysql: host: localhost port: 3306 database: minecraft username: root password: password pool: maximum-pool-size: 10 minimum-idle: 5 connection-timeout: 5000 # 积分项定义 points: coins: 金币 # coins 为积分标识，金币为显示名称 points: 积分 experience: 经验 prestige: 声望 # 排行榜设置 leaderboard: entries-per-page: 10 # 每页显示条数 ``` ### 如何添加新的积分项 在 `points:` 下新增一行即可： ```yaml points: coins: 金币 points: 积分 experience: 经验 prestige: 声望 vote: 投票点 # 新增积分项 reward: 奖励点 # 新增积分项 ``` 保存后执行 `/points reload` 即可生效，无需重启服务器。 *** ## 命令与权限 ### 玩家命令 | 命令 | 说明 | 权限 | | ------------------------ | --------- | -------------- | | `/points <积分项>` | 查询自己的某项积分 | `mopoints.use` | | `/points top <积分项> [页数]` | 查看积分排行榜 | `mopoints.use` | | `/points list` | 列出所有积分项 | `mopoints.use` | | `/points help` | 显示帮助信息 | `mopoints.use` | **命令别名：** `/jf`、`/points` ### 管理员命令 | 命令 | 说明 | 权限 | | ------------------------------ | --------- | ----------------- | | `/points <积分项> <玩家>` | 查询指定玩家的积分 | `mopoints.others` | | `/points set <玩家> <积分项> <数值>` | 设置积分 | `mopoints.admin` | | `/points add <玩家> <积分项> <数值>` | 增加积分 | `mopoints.admin` | | `/points take <玩家> <积分项> <数值>` | 扣除积分 | `mopoints.admin` | | `/points reload` | 重载配置文件 | `mopoints.reload` | ### 权限节点 | 权限 | 默认 | 说明 | | ----------------- | --- | --------- | | `mopoints.use` | 所有人 | 使用基础查询命令 | | `mopoints.others` | OP | 查询其他玩家积分 | | `mopoints.admin` | OP | 管理积分（增删改） | | `mopoints.reload` | OP | 重载配置 | ### 使用示例 ``` # 玩家查询自己的金币 /points coins # 查询玩家的积分 /points coins Steve # 查看金币排行榜 /points top coins # 查看金币排行榜第2页 /points top coins 2 # 管理员：设置 Steve 的金币为 1000 /points set Steve coins 1000 # 管理员：给 Steve 增加 50 点声望 /points add Steve prestige 50 # 管理员：扣除 Steve 100 积分 /points take Steve points 100 # 列出所有积分项 /points list # 重载配置 /points reload ``` *** ## PlaceholderAPI 占位符 需要前置安装 [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) 插件。 ### 玩家积分占位符 | 占位符 | 说明 | | ------------------------- | ---------- | | `%MoPoints_<积分项>_player%` | 当前玩家的某项积分值 | **示例：** - `%MoPoints_coins_player%` — 显示当前玩家的金币数 - `%MoPoints_points_player%` — 显示当前玩家的积分值 ### 排行榜占位符 | 占位符 | 说明 | | ----------------------------- | ----------- | | `%MoPoints_<积分项>_<排名>_name%` | 指定排行位置的玩家名称 | | `%MoPoints_<积分项>_<排名>_value%` | 指定排行位置的积分值 | **示例：** - `%MoPoints_coins_1_name%` — 金币排行榜第1名的玩家名 - `%MoPoints_coins_1_value%` — 金币排行榜第1名的数值 - `%MoPoints_coins_5_name%` — 金币排行榜第5名的玩家名 - `%MoPoints_coins_10_value%` — 金币排行榜第10名的数值 ### 综合使用示例 在计分板插件中： ``` # 使用 Skript 或 Scoreboard 插件配置 line1: "&6金币榜 Top1: %MoPoints_coins_1_name%" line2: "&e- %MoPoints_coins_1_value%" line3: "&6我的金币: %MoPoints_coins_player%" ``` 在聊天格式中（需配合支持 PAPI 的聊天插件）： ``` %MoPoints_points_player% 点积分 ``` *** ## 开发者 API 墨积分提供了完整的公共 API，方便其他插件开发者进行集成。 ### 获取 API 实例 ```java // 方式一：通过 ServicesManager 获取（推荐） MoPointsAPI api = Bukkit.getServicesManager() .load(MoPointsAPI.class); // 方式二：通过静态方法获取 MoPointsAPI api = MoPointsAPI.getInstance(); ``` ### API 方法说明 ```java public class MoPointsAPI { // 获取玩家某项积分的值 CompletableFuture<Double> getPoints(OfflinePlayer player, String pointType); // 设置玩家某项积分的值 CompletableFuture<Void> setPoints(OfflinePlayer player, String pointType, double value); // 增加玩家某项积分 CompletableFuture<Void> addPoints(OfflinePlayer player, String pointType, double value); // 扣除玩家某项积分 CompletableFuture<Void> takePoints(OfflinePlayer player, String pointType, double value); // 获取排行榜（分页） CompletableFuture<List<Map.Entry<String, Double>>> getLeaderboard( String pointType, int page, int pageSize); // 检查积分项是否存在 boolean isPointTypeExists(String pointType); // 获取所有积分项（Map<标识, 显示名称>） Map<String, String> getPointTypes(); } ``` ### 完整使用示例 ```java import com.example.mopoints.api.MoPointsAPI; import org.bukkit.entity.Player; import java.util.Map; import java.util.List; import java.util.concurrent.CompletableFuture; public class MyPlugin { private MoPointsAPI pointsAPI; public void onEnable() { pointsAPI = MoPointsAPI.getInstance(); } // 给玩家发放奖励 public void rewardPlayer(Player player, String type, double amount) { pointsAPI.addPoints(player, type, amount).thenRun(() -> { player.sendMessage("§a你获得了 " + (int)amount + " 点 " + type); }); } // 检查玩家是否有足够积分消费 public boolean tryPurchase(Player player, String type, double cost) { try { double balance = pointsAPI.getPoints(player, type).get(); if (balance >= cost) { pointsAPI.takePoints(player, type, cost); return true; } } catch (Exception e) { e.printStackTrace(); } return false; } // 展示排行榜 public void showTop(Player player, String type) { pointsAPI.getLeaderboard(type, 1, 5).thenAccept(entries -> { player.sendMessage("§6=== " + type + " 排行榜 ==="); int rank = 1; for (Map.Entry<String, Double> entry : entries) { player.sendMessage("§e#" + rank + " §7" + entry.getKey() + " §f- §6" + entry.getValue().intValue()); rank++; } }); } } ``` ### Maven 依赖 在你的插件 `pom.xml` 中添加： ```xml <repositories> <repository> <id>mo-points-repo</id> <url>你的仓库地址（如有）</url> </repository> </repositories> <dependencies> <dependency> <groupId>com.example</groupId> <artifactId>MoPointsPlugin</artifactId> <version>1.0.0</version> <scope>provided</scope> </dependency> </dependencies> ``` 或者将墨积分插件 jar 放入你项目的 `libs` 目录作为本地依赖引用。 *** ## 常见问题 ### Q: 插件加载后提示 "未检测到 PlaceholderAPI"？ A: 这是正常提示，不影响核心功能。如需使用占位符功能，请安装 [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)。 ### Q: 如何迁移数据从 SQLite 到 MySQL？ A: 目前需要手动操作： 1. 先配置 MySQL 并启动插件，让插件自动创建表结构 2. 使用数据库工具（如 DBeaver、Navicat）将 SQLite 中的数据导出并导入到 MySQL ### Q: 积分值支持小数吗？ A: 支持。积分值使用 `double` 类型存储，整数显示时自动省略小数位，小数显示两位精度。 ### Q: 命令补全不生效？ A: 请确保使用的是 Paper 1.13+ 服务端（推荐 Paper 1.21+），部分旧版本 Spigot 对 Tab 补全的支持有限。 ### Q: 如何重置某个玩家的积分？ A: 使用管理员命令： ``` /points set <玩家名> <积分项> 0 ``` *** **墨积分 — 让积分管理变得简单而强大** [/MD]