Spectrum反作弊系统 - API详细文档

📋 目录

API概述
API版本
基础API
检测API
惩罚API
数据API
配置API
事件API
开发示例
最佳实践
常见问题

🔍 API概述

Spectrum反作弊插件提供了一套完整的API接口，允许开发者与插件进行交互、扩展插件功能或与其他插件集成。API支持Java开发，主要分为基础API、检测API、惩罚API、数据API、配置API和事件API等几个部分。

🔢 API版本

Spectrum反作弊插件的API版本与插件版本保持一致，当前版本为v2.5.0。API版本格式遵循语义化版本控制（SemVer），具体格式为major.minor.patch：

major：重大版本更新，包含不兼容的API变更
minor：次要版本更新，添加新功能，但保持向后兼容
patch：补丁版本更新，修复bug，保持向后兼容

在使用API时，建议指定具体的版本依赖，以避免因版本更新导致的兼容性问题。

🚀 基础API

基础API提供了与Spectrum反作弊插件进行基本交互的方法，包括获取插件实例、检查插件状态等。

获取插件实例

java

import com.starlakestudio.spectrum.Spectrum;
import org.bukkit.Bukkit;
import org.bukkit.plugin.Plugin;

// 获取Spectrum插件实例
Plugin plugin = Bukkit.getPluginManager().getPlugin("Spectrum");
if (plugin != null && plugin instanceof Spectrum) {
    Spectrum spectrum = (Spectrum) plugin;
    // 使用spectrum实例进行操作
}

检查插件状态

java

// 检查插件是否已启用
if (plugin != null && plugin.isEnabled()) {
    // 插件已启用，可以使用
} else {
    // 插件未启用或未找到
}

// 获取插件版本
String version = plugin.getDescription().getVersion();

// 检查插件是否处于调试模式
boolean isDebugMode = spectrum.isDebugMode();

白名单管理

java

// 检查玩家是否在白名单中
boolean isWhitelisted = spectrum.getWhitelistManager().isWhitelisted(player);

// 将玩家添加到白名单
if (!isWhitelisted) {
    spectrum.getWhitelistManager().addWhitelisted(player);
}

// 从白名单中移除玩家
if (isWhitelisted) {
    spectrum.getWhitelistManager().removeWhitelisted(player);
}

// 检查玩家是否有特定检测的绕过权限
boolean canBypass = spectrum.getBypassManager().canBypass(player, "movement.fly");

🎯 检测API

检测API允许开发者创建自定义检测模块、注册检测、修改检测设置等。

检测模块结构

每个检测模块都需要实现CheckModule接口：

java

import com.starlakestudio.spectrum.api.check.CheckModule;
import com.starlakestudio.spectrum.api.check.CheckResult;
import org.bukkit.entity.Player;

public class MyCustomCheck implements CheckModule {
    
    @Override
    public String getName() {
        return "mycustom.check";
    }
    
    @Override
    public String getCategory() {
        return "custom";
    }
    
    @Override
    public CheckResult check(Player player) {
        // 实现检测逻辑
        // 返回CheckResult.PASS、CheckResult.FAIL或带有详细信息的CheckResult对象
        return CheckResult.PASS;
    }
    
    @Override
    public double getDefaultViolationWeight() {
        return 1.0;
    }
    
    @Override
    public void onEnable() {
        // 模块启用时执行的代码
    }
    
    @Override
    public void onDisable() {
        // 模块禁用时执行的代码
    }
}

注册自定义检测模块

java

// 创建自定义检测实例
MyCustomCheck myCheck = new MyCustomCheck();

// 注册检测模块
spectrum.getCheckManager().registerCheck(myCheck);

// 启用检测模块
spectrum.getCheckManager().enableCheck(myCheck.getName());

// 禁用检测模块
spectrum.getCheckManager().disableCheck(myCheck.getName());

修改检测设置

java

// 获取检测设置
CheckSettings settings = spectrum.getCheckManager().getCheckSettings("movement.fly");

// 修改检测灵敏度
settings.setSensitivity(2.5);

// 修改检测惩罚阈值
settings.setViolationThreshold(10.0);

// 保存修改后的设置
spectrum.getConfigManager().saveCheckSettings();

⚖️ 惩罚API

惩罚API允许开发者自定义惩罚行为、执行惩罚、修改惩罚设置等。

惩罚类型

Spectrum支持多种惩罚类型，包括：

警告（Warning）
踢出（Kick）
临时封禁（TempBan）
永久封禁（Ban）
降低速度（SpeedReduce）
虚弱效果（Weakness）
自定义命令（CustomCommand）

执行惩罚

java

import com.starlakestudio.spectrum.api.punish.PunishmentType;

// 执行警告惩罚
spectrum.getPunishmentManager().punish(player, "movement.fly", PunishmentType.WARNING);

// 执行踢出惩罚
spectrum.getPunishmentManager().punish(player, "combat.killaura", PunishmentType.KICK, "检测到 Kill Aura 作弊");

// 执行临时封禁惩罚（7天）
spectrum.getPunishmentManager().punish(player, "movement.speed", PunishmentType.TEMP_BAN, 7 * 24 * 60 * 60, "检测到 Speed 作弊");

// 执行永久封禁惩罚
spectrum.getPunishmentManager().punish(player, "visual.xray", PunishmentType.BAN, "检测到 X-Ray 作弊");

自定义惩罚处理程序

java

import com.starlakestudio.spectrum.api.punish.PunishmentHandler;
import org.bukkit.entity.Player;

public class MyCustomPunishmentHandler implements PunishmentHandler {
    
    @Override
    public void handlePunishment(Player player, String checkName, double violationLevel, String reason) {
        // 实现自定义惩罚逻辑
        player.sendMessage("§c你因违规行为受到警告！");
        // 可以执行其他操作，如记录到数据库、通知管理员等
    }
    
    @Override
    public String getIdentifier() {
        return "mycustom.punishment";
    }
}

// 注册自定义惩罚处理程序
MyCustomPunishmentHandler handler = new MyCustomPunishmentHandler();
spectrum.getPunishmentManager().registerPunishmentHandler(handler);

📊 数据API

数据API允许开发者访问和操作反作弊系统收集的数据，包括玩家数据、违规记录、统计信息等。

玩家数据管理

java

// 获取玩家数据
SpectrumPlayer spectrumPlayer = spectrum.getPlayerManager().getPlayer(player.getUniqueId());

// 获取玩家的违规等级
int violationLevel = spectrumPlayer.getViolationLevel();

// 获取玩家的详细违规记录
List<Violation> violations = spectrumPlayer.getViolations();

// 获取特定检测的违规记录
List<Violation> movementViolations = spectrumPlayer.getViolationsByCheckCategory("movement");

// 重置玩家的违规记录
spectrumPlayer.resetViolations();

// 获取玩家的历史数据
PlayerHistory history = spectrumPlayer.getHistory();
List<Violation> historicalViolations = history.getViolationsInTimeRange(System.currentTimeMillis() - 24 * 60 * 60 * 1000, System.currentTimeMillis());

统计数据访问

java

// 获取全局统计数据
GlobalStatistics stats = spectrum.getStatisticsManager().getGlobalStatistics();

// 获取总检测次数
long totalChecks = stats.getTotalChecks();

// 获取总违规次数
long totalViolations = stats.getTotalViolations();

// 获取特定检测的统计数据
CheckStatistics checkStats = stats.getCheckStatistics("movement.fly");
long flyViolations = checkStats.getViolationCount();

// 获取作弊类型分布
Map<String, Long> cheatDistribution = stats.getCheatTypeDistribution();

数据导出

java

// 导出玩家数据到JSON
String jsonData = spectrum.getDataManager().exportPlayerData(player.getUniqueId());

// 导出统计数据到CSV
File csvFile = spectrum.getDataManager().exportStatisticsToCSV(new File("stats.csv"));

// 导出违规日志到文件
spectrum.getDataManager().exportViolationLogs(new File("violations.log"), System.currentTimeMillis() - 7 * 24 * 60 * 60 * 1000);

⚙️ 配置API

配置API允许开发者通过代码修改和读取反作弊系统的配置。

配置读取

java

// 读取主配置
Configuration config = spectrum.getConfigManager().getMainConfig();

// 获取配置值
boolean debugMode = config.getBoolean("debug-mode", false);
int checkInterval = config.getInt("check-interval", 50);
String prefix = config.getString("messages.prefix", "§6[光谱]§r");

// 读取检测配置
CheckConfiguration checkConfig = spectrum.getConfigManager().getCheckConfig();
boolean flyEnabled = checkConfig.isCheckEnabled("movement.fly");

配置修改

java

// 修改主配置
config.set("debug-mode", true);
config.set("check-interval", 40);

// 修改检测配置
checkConfig.setEnabled("movement.speed", false);
checkConfig.setSensitivity("combat.killaura", 3.0);

// 保存配置
config.save();
checkConfig.save();

// 重新加载配置
spectrum.getConfigManager().reloadAllConfigs();

📡 事件API

事件API允许开发者监听和响应反作弊系统触发的各种事件。

注册事件监听器

java

import org.bukkit.plugin.PluginManager;
import com.starlakestudio.spectrum.api.event.SpectrumViolationEvent;
import com.starlakestudio.spectrum.api.event.SpectrumPunishmentEvent;
import com.starlakestudio.spectrum.api.event.SpectrumDebugEvent;

// 注册事件监听器
PluginManager pm = Bukkit.getPluginManager();
YourEventListener listener = new YourEventListener();
pm.registerEvents(listener, yourPlugin);

事件处理示例

java

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import com.starlakestudio.spectrum.api.event.SpectrumViolationEvent;
import com.starlakestudio.spectrum.api.event.SpectrumPunishmentEvent;
import com.starlakestudio.spectrum.api.event.SpectrumCheckToggleEvent;

public class YourEventListener implements Listener {
    
    @EventHandler
    public void onViolation(SpectrumViolationEvent event) {
        // 获取违规玩家
        Player player = event.getPlayer();
        
        // 获取违规信息
        String checkName = event.getCheckName();
        double violationLevel = event.getViolationLevel();
        String violationMessage = event.getMessage();
        
        // 处理违规事件
        System.out.println("玩家 " + player.getName() + " 触发了 " + checkName + " 检测，违规等级: " + violationLevel);
        
        // 可以取消事件的默认处理
        // event.setCancelled(true);
    }
    
    @EventHandler
    public void onPunishment(SpectrumPunishmentEvent event) {
        // 获取被惩罚的玩家
        Player player = event.getPlayer();
        
        // 获取惩罚信息
        String checkName = event.getCheckName();
        String punishmentType = event.getPunishmentType().name();
        String reason = event.getReason();
        
        // 处理惩罚事件
        System.out.println("玩家 " + player.getName() + " 因 " + checkName + " 被处以 " + punishmentType + " 惩罚，原因: " + reason);
    }
    
    @EventHandler
    public void onCheckToggle(SpectrumCheckToggleEvent event) {
        // 获取检测信息
        String checkName = event.getCheckName();
        boolean enabled = event.isEnabled();
        
        // 处理检测开关事件
        System.out.println("检测 " + checkName + " 已被" + (enabled ? "启用" : "禁用"));
    }
}

自定义事件触发

java

import com.starlakestudio.spectrum.api.event.SpectrumCustomEvent;
import org.bukkit.Bukkit;
import org.bukkit.event.Event;
import org.bukkit.event.EventPriority;

// 创建并触发自定义事件
SpectrumCustomEvent customEvent = new SpectrumCustomEvent(player, "custom.action", dataMap);
Bukkit.getPluginManager().callEvent(customEvent);

// 检查事件是否被取消
if (!customEvent.isCancelled()) {
    // 执行事件相关的操作
}

📝 开发示例

示例1：创建自定义检测模块

java

import com.starlakestudio.spectrum.api.check.CheckModule;
import com.starlakestudio.spectrum.api.check.CheckResult;
import org.bukkit.entity.Player;
import org.bukkit.potion.PotionEffectType;

public class NoSlowdownCheck implements CheckModule {
    
    @Override
    public String getName() {
        return "movement.noslowdown";
    }
    
    @Override
    public String getCategory() {
        return "movement";
    }
    
    @Override
    public CheckResult check(Player player) {
        // 检查玩家是否在食用物品
        boolean isEating = player.isBlocking() || player.isHandRaised();
        
        // 检查玩家是否有速度效果
        boolean hasSpeedEffect = player.hasPotionEffect(PotionEffectType.SPEED);
        
        // 获取玩家的移动速度
        double currentSpeed = player.getVelocity().length();
        
        // 检查是否存在不减速作弊
        if (isEating && !hasSpeedEffect && currentSpeed > 0.25) {
            return new CheckResult(CheckResult.FAIL, "检测到 NoSlowdown 作弊，速度: " + currentSpeed);
        }
        
        return CheckResult.PASS;
    }
    
    @Override
    public double getDefaultViolationWeight() {
        return 2.0;
    }
    
    @Override
    public void onEnable() {
        System.out.println("NoSlowdown 检测已启用");
    }
    
    @Override
    public void onDisable() {
        System.out.println("NoSlowdown 检测已禁用");
    }
}

// 注册检测模块
NoSlowdownCheck noSlowdownCheck = new NoSlowdownCheck();
spectrum.getCheckManager().registerCheck(noSlowdownCheck);

示例2：创建自定义惩罚处理程序

java

import com.starlakestudio.spectrum.api.punish.PunishmentHandler;
import org.bukkit.Bukkit;
import org.bukkit.entity.Player;

public class NotificationPunishmentHandler implements PunishmentHandler {
    
    @Override
    public void handlePunishment(Player player, String checkName, double violationLevel, String reason) {
        // 通知所有在线管理员
        String message = "§c[光谱警报] §6玩家 " + player.getName() + " §c因 §e" + checkName + " §c违规，等级: §e" + violationLevel;
        for (Player onlinePlayer : Bukkit.getOnlinePlayers()) {
            if (onlinePlayer.hasPermission("spectrum.admin")) {
                onlinePlayer.sendMessage(message);
            }
        }
        
        // 记录到日志
        System.out.println("[光谱] " + player.getName() + " 触发 " + checkName + " 检测，违规等级: " + violationLevel + ", 原因: " + reason);
    }
    
    @Override
    public String getIdentifier() {
        return "notification.punishment";
    }
}

// 注册惩罚处理程序
NotificationPunishmentHandler handler = new NotificationPunishmentHandler();
spectrum.getPunishmentManager().registerPunishmentHandler(handler);

🔝 最佳实践

在使用Spectrum API时，请遵循以下最佳实践：

1. 依赖管理

始终使用provided或compileOnly作用域添加Spectrum依赖，避免插件打包时包含Spectrum类
在使用API前检查Spectrum插件是否已加载
处理好版本兼容性问题，避免因API变更导致插件失效

2. 性能考虑

避免在高频调用的方法中使用API进行复杂操作
合理使用缓存，减少重复查询
注意异步操作，避免在主线程中执行耗时操作

3. 安全考虑

验证所有输入参数，避免注入攻击
限制API使用权限，防止未授权访问
保护敏感数据，避免信息泄露

4. 错误处理

捕获并处理所有可能的异常
提供详细的错误日志，便于调试
实现优雅降级，在API不可用时提供替代方案

❓ 常见问题

Q: 如何处理Spectrum插件未加载的情况？

A: 在使用API前，始终检查Spectrum插件是否已加载：

java

Plugin spectrumPlugin = getServer().getPluginManager().getPlugin("Spectrum");
if (spectrumPlugin != null && spectrumPlugin.isEnabled()) {
    // Spectrum已加载，可以使用API
} else {
    // Spectrum未加载，提供替代方案或禁用相关功能
    getLogger().warning("Spectrum未加载，相关功能将不可用。");
}

Q: 如何避免API版本兼容性问题？

A: 可以使用反射机制或版本检查来处理不同版本的API差异：

java

// 检查API版本
String version = spectrumPlugin.getDescription().getVersion();
if (versionCompare(version, "2.5.0") >= 0) {
    // 使用新版本API
} else {
    // 使用旧版本API或提供替代方案
}

// 版本比较方法
private int versionCompare(String version1, String version2) {
    String[] parts1 = version1.split("\\.");
    String[] parts2 = version2.split("\\.");
    
    int length = Math.max(parts1.length, parts2.length);
    for (int i = 0; i < length; i++) {
        int v1 = i < parts1.length ? Integer.parseInt(parts1[i]) : 0;
        int v2 = i < parts2.length ? Integer.parseInt(parts2[i]) : 0;
        if (v1 != v2) {
            return v1 - v2;
        }
    }
    return 0;
}

Q: 如何报告API使用中的问题？

A: 如有API使用问题或建议，请通过以下方式报告：

GitHub Issues：在Spectrum的GitHub仓库提交Issue
Discord：加入Spectrum的Discord社区寻求帮助
邮件：发送邮件至support@starlakestudio.com

在报告问题时，请提供详细的错误信息、使用环境、复现步骤以及相关代码片段，以便更快地解决问题。

Spectrum反作弊系统 - API详细文档 ​

📋 目录 ​

🔍 API概述 ​

🔢 API版本 ​

🚀 基础API ​

获取插件实例 ​

检查插件状态 ​

白名单管理 ​

🎯 检测API ​

检测模块结构 ​

注册自定义检测模块 ​

修改检测设置 ​

⚖️ 惩罚API ​

惩罚类型 ​

执行惩罚 ​

自定义惩罚处理程序 ​

📊 数据API ​

玩家数据管理 ​

统计数据访问 ​

数据导出 ​

⚙️ 配置API ​

配置读取 ​

配置修改 ​

📡 事件API ​

注册事件监听器 ​

事件处理示例 ​

自定义事件触发 ​

📝 开发示例 ​

示例1：创建自定义检测模块 ​

示例2：创建自定义惩罚处理程序 ​

🔝 最佳实践 ​

1. 依赖管理 ​

2. 性能考虑 ​

3. 安全考虑 ​

4. 错误处理 ​

❓ 常见问题 ​

Q: 如何处理Spectrum插件未加载的情况？ ​

Q: 如何避免API版本兼容性问题？ ​

Q: 如何报告API使用中的问题？ ​

Spectrum反作弊系统 - API详细文档

📋 目录

🔍 API概述

🔢 API版本

🚀 基础API

获取插件实例

检查插件状态

白名单管理

🎯 检测API

检测模块结构

注册自定义检测模块

修改检测设置

⚖️ 惩罚API

惩罚类型

执行惩罚

自定义惩罚处理程序

📊 数据API

玩家数据管理

统计数据访问

数据导出

⚙️ 配置API

配置读取

配置修改

📡 事件API

注册事件监听器

事件处理示例

自定义事件触发

📝 开发示例

示例1：创建自定义检测模块

示例2：创建自定义惩罚处理程序

🔝 最佳实践

1. 依赖管理

2. 性能考虑

3. 安全考虑

4. 错误处理

❓ 常见问题

Q: 如何处理Spectrum插件未加载的情况？

Q: 如何避免API版本兼容性问题？

Q: 如何报告API使用中的问题？