Doc ID: SIRC-053

CoreProtect API 文档

CoreProtect API 接口文档

Overview

CoreProtect API 文档 (v7-v10)

包名

  • net.coreprotect.CoreProtect
  • net.coreprotect.CoreProtectAPI

API v10 (插件版本 v22.4+)

新增方法

  1. logPlacement(String user, BlockState blockState) – 记录方块放置（线程安全）
  2. logRemoval(String user, BlockState blockState) – 记录方块破坏（线程安全）

核心方法

初始化 API

import net.coreprotect.CoreProtect;
import net.coreprotect.CoreProtectAPI;

private CoreProtectAPI getCoreProtect() {
    Plugin plugin = getServer().getPluginManager().getPlugin("CoreProtect");
    if (plugin == null || !(plugin instanceof CoreProtect)) {
        return null;
    }
    CoreProtectAPI CoreProtect = ((CoreProtect) plugin).getAPI();
    if (CoreProtect.isEnabled() == false) {
        return null;
    }
    if (CoreProtect.APIVersion() < 10) {
        return null;
    }
    return CoreProtect;
}

可用方法列表

  • boolean isEnabled() – 检查API是否启用
  • void testAPI() – 测试API连接
  • List<String[]> performLookup(...) – 执行查询
  • List<String[]> performRollback(...) – 执行回滚（必须异步调用）
  • List<String[]> performRestore(...) – 执行存储
  • List<String[]> blockLookup(Block block, int time) – 单个方块查询
  • List<String[]> sessionLookup(String user, int time) – 玩家会话查询
  • List<String[]> queueLookup(Block block) – 查询未存储的队列改动
  • ParseResult parseResult(String[] result) – 解析查询结果
  • boolean logChat(Player player, String message) – 记录聊天
  • boolean logCommand(Player player, String command) – 记录命令
  • boolean logPlacement(String user, BlockState blockState) – 记录方块放置（线程安全）
  • boolean logPlacement(String user, Location location, Material type, BlockData blockData) – 记录方块放置
  • boolean logRemoval(String user, BlockState blockState) – 记录方块破坏（线程安全）
  • boolean logRemoval(String user, Location location, Material type, BlockData blockData) – 记录方块破坏
  • boolean logContainerTransaction(String user, Location location) – 记录容器交易
  • boolean logInteraction(String user, Location location) – 记录方块交互
  • boolean hasPlaced(String user, Block block, int time, int offset) – 检查玩家是否放置方块
  • boolean hasRemoved(String user, Block block, int time, int offset) – 检查玩家是否破坏方块
  • void performPurge(int time) – 清理数据库

ParseResult 方法

  • getX() – X坐标
  • getY() – Y坐标
  • getZ() – Z坐标
  • getType() – 方块材料名
  • getBlockData() – BlockData
  • getPlayer() – 玩家名称
  • getTimestamp() – 时间戳
  • getActionId() – 行为ID (0=破坏,1=放置,2=交互)
  • getActionString() – 行为字符串
  • isRolledBack() – 是否已回滚
  • worldName() – 世界名称

可用事件

  • CoreProtectPreLogEvent – 记录前触发，可取消

API v9 (插件版本 v21.0+)

新增方法

  1. sessionLookup(String user, int time) – 玩家会话查询
  2. queueLookup(Block block) – 查询未存储的队列改动

与v8的区别

  • 新增上述两个方法
  • 其他方法与v8相同

API v8 (插件版本 v20.2+)

新增功能

  • 新增事件：CoreProtectPreLogEvent

与v7的区别

  • 新增事件系统
  • 其他方法与v7相同

API v7 (插件版本 v20.0+)

主要变化

  • 新增：parseResult(String[] result).getTimestamp()
  • 弃用：parseResult(String[] result).getTime()
  • 移除：parseResult(String[] result).getTypeId()

方法列表（v7基础）

  • boolean isEnabled()
  • void testAPI()
  • List<String[]> performLookup(...)
  • List<String[]> performRollback(...)
  • List<String[]> performRestore(...)
  • List<String[]> blockLookup(Block block, int time)
  • ParseResult parseResult(String[] result)
  • boolean logChat(Player player, String message)
  • boolean logCommand(Player player, String command)
  • boolean logPlacement(String user, Location location, Material type, BlockData blockData)
  • boolean logRemoval(String user, Location location, Material type, BlockData blockData)
  • boolean logContainerTransaction(String user, Location location)
  • boolean logInteraction(String user, Location location)
  • boolean hasPlaced(String user, Block block, int time, int offset)
  • boolean hasRemoved(String user, Block block, int time, int offset)
  • void performPurge(int time)

通用参数说明

performLookup/Rollback/Restore 参数

  • time – 时间长度（秒），"5"表示5秒前
  • restrict_users – 限制的玩家列表，可为null
  • exclude_users – 排除的玩家列表，可为null
  • restrict_blocks – 限制的方块类型，可为null
  • exclude_blocks – 排除的方块类型，可为null
  • action_list – 行为类型列表，可为null
  • radius – 半径，0=禁用
  • radius_location – 中心位置

hasPlaced/hasRemoved 参数

  • user – 玩家名称
  • block – 方块
  • time – 时间范围（秒）
  • offset – 时间偏移（秒），忽略最近offset秒的记录

使用示例

查询玩家最近60秒的方块数据

CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect != null) {
    List<String[]> lookup = CoreProtect.performLookup(60, Arrays.asList("Notch"), null, null, null, null, 0, null);
    if (lookup != null) {
        for (String[] result : lookup) {
            ParseResult parseResult = CoreProtect.parseResult(result);
            int x = parseResult.getX();
            int y = parseResult.getY();
            int z = parseResult.getZ();
            // 处理数据
        }
    }
}

排除特定方块查询

List<Object> exclude = Arrays.asList(Material.DIRT, Material.GRASS);
List<String[]> lookup = CoreProtect.performLookup(60, Arrays.asList("Notch"), null, null, exclude, null, 0, null);

半径查询

List<String[]> lookup = CoreProtect.performLookup(60, null, null, null, null, null, 5, location);

回滚操作（必须异步）

class BasicThread implements Runnable {
    @Override
    public void run() {
        try {
            CoreProtectAPI CoreProtect = getCoreProtect();
            if (CoreProtect != null) {
                List<String[]> lookup = CoreProtect.performRollback(60, Arrays.asList("Notch"), null, null, null, null, 0, null);
                // 处理结果
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

检查玩家是否放置方块

boolean hasPlaced = CoreProtect.hasPlaced("Notch", block, 60, 0);
if (!hasPlaced) {
    List<String[]> lookup = CoreProtect.queueLookup(block);
    for (String[] result : lookup) {
        ParseResult parseResult = CoreProtect.parseResult(result);
        if (parseResult.getActionId() == 1 && parseResult.getPlayer().equals("Notch")) {
            hasPlaced = true;
            break;
        }
    }
}

记录方块放置

boolean success = CoreProtect.logPlacement("Notch", block.getLocation(), block.getType(), block.getData());

记录容器交易

boolean success = CoreProtect.logContainerTransaction("Notch", inventory.getLocation());
// 立即修改容器内容

玩家会话查询

List<String[]> lookup = CoreProtect.sessionLookup("Notch", (24 * 60 * 60));
if (lookup != null) {
    for (String[] result : lookup) {
        ParseResult parseResult = CoreProtect.parseResult(result);
        int action = parseResult.getActionId(); // 0=登出, 1=登入
    }
}

版本兼容性说明

  1. v10：新增线程安全的logPlacement/logRemoval方法
  2. v9：新增sessionLookup和queueLookup方法
  3. v8：新增CoreProtectPreLogEvent事件
  4. v7：引入getTimestamp()替代getTime()，移除getTypeId()

注意事项

  1. performRollback 必须异步调用
  2. 使用API前必须检查 isEnabled() 和 APIVersion()
  3. logContainerTransaction 调用后应立即修改容器内容
  4. hasPlaced/hasRemoved 的offset参数可用于排除最近记录
  5. 所有查询方法返回 List<String[]>，需要使用 parseResult 解析

文档来自SnowCutieOwO – wiki