PlayerPoints API 知识库

本文档用于整理 PlayerPoints 插件在插件二次开发中的 API 初始化方式、核心类结构以及常见用法示例，适用于 Spigot / Paper / Bukkit 服务端环境。

一、核心类与包结构

1️⃣ 插件主类

org.black_ixx.playerpoints.PlayerPoints

• PlayerPoints 插件的 Bukkit 主类
• 用于获取 API 实例

---

2️⃣ API 类

org.black_ixx.playerpoints.PlayerPointsAPI

• 所有点数相关操作的入口
• 包含查询、增加、扣除、设置、转账等方法

---

3️⃣ 包名总览

org.black_ixx.playerpoints

---

二、API 初始化方式

✅ 标准初始化流程（推荐）

在你自己的插件 onEnable() 中获取 PlayerPoints 实例：

import org.black_ixx.playerpoints.PlayerPoints;
import org.black_ixx.playerpoints.PlayerPointsAPI;
import org.bukkit.plugin.Plugin;

public class MyPlugin extends JavaPlugin {

    private PlayerPoints playerPoints;
    private PlayerPointsAPI pointsAPI;

    @Override
    public void onEnable() {
        Plugin plugin = getServer().getPluginManager().getPlugin("PlayerPoints");
        if (plugin instanceof PlayerPoints) {
            this.playerPoints = (PlayerPoints) plugin;
            this.pointsAPI = playerPoints.getAPI();
        } else {
            getLogger().severe("未找到 PlayerPoints 插件，功能将被禁用");
        }
    }
}

说明

• 不要自行 new PlayerPointsAPI
• API 必须从已启用的 PlayerPoints 插件实例中获取
• 如果插件不存在，应禁用依赖功能而不是抛异常

---

三、常用 API 方法

🎯 查询玩家点数

int points = pointsAPI.look(player.getName());

• 返回玩家当前点数
• 玩家不存在时通常返回 0

---

➕ 给予玩家点数

boolean success = pointsAPI.give(player.getName(), 100);

• 返回是否操作成功
• 一般不会因为负数而自动校验，请自行控制参数

---

➖ 扣除玩家点数

boolean success = pointsAPI.take(player.getName(), 50);

• 当余额不足时返回 false
• 不会自动扣成负数

---

✏️ 设置玩家点数

boolean success = pointsAPI.set(player.getName(), 1000);

• 直接覆盖原有点数

---

🔄 重置 / 删除玩家数据

boolean success = pointsAPI.reset(player.getName());

• 通常将点数重置为 0

---

💸 玩家间转账

boolean success = pointsAPI.pay("Alice", "Bob", 200);

• 从 Alice 扣除点数并给予 Bob
• 任意一方失败都会返回 false

---

四、常见使用场景示例

示例：判断点数是否足够并消费

int cost = 300;
int balance = pointsAPI.look(player.getName());

if (balance >= cost) {
    pointsAPI.take(player.getName(), cost);
    // 发放奖励
} else {
    // 点数不足提示
}

---

示例：给予在线玩家奖励点数

for (Player p : Bukkit.getOnlinePlayers()) {
    pointsAPI.give(p.getName(), 10);
}

---

五、开发注意事项

⚠️ 玩家标识问题

• PlayerPoints 主要基于玩家名 而非 UUID
• 在离线模式或改名环境下要注意数据一致性

---

⚠️ 线程安全

• API 应在主线程调用
• 不要在异步线程中直接操作 PlayerPoints

---

⚠️ 不要假设返回值一定成功

• 所有写操作均返回 boolean
• 必须检查返回值再进行后续逻辑

---

六、文档定位说明

本文档适用于：

• 插件中集成 PlayerPoints 点数系统
• 替代 Vault 以实现轻量级点数逻辑
• AI / 自动生成插件代码的参考上下文

不适用于：

• PlayerPoints 插件使用教学
• 指令、GUI 或 Placeholder 配置

---

📌 目标：

让你在代码层面对 PlayerPoints 的使用始终“简单、明确、可控”。