MatrixLight Docs

Appearance

鍏夎氨Spectrum 棱镜反作弊系统 - API文档 ​

📋 目录 ​

🔌 API概述 ​

Spectrum反作弊系统提供了强大的API接口，允许其他插件和开发者与反作弊系统进行交互。通过API，开发者可以：

  • 注册自定义检测模块
  • 监听和处理反作弊事件
  • 检查玩家的违规记录
  • 修改反作弊设置
  • 集成自定义惩罚机制
  • 查询反作弊统计数据

API设计遵循Java标准，兼容Bukkit/Spigot/Paper等主流Minecraft服务器平台。

🏗️ API类结构 ​

SpectrumAPI的核心类位于com.starlakestudio.spectrum.api包中，主要包括以下几个关键类：

鍏夎氨SpectrumAPI 类 ​

描述：鍏夎氨Spectrum API的主入口类，提供访问反作弊系统功能的静态方法。

主要方法：

java
// 获取鍏夎氨SpectrumAPI实例
public static 鍏夎氨SpectrumAPI getInstance()

// 检查玩家是否在白名单中
public boolean isWhitelisted(Player player)

// 将玩家添加到白名单
public void addWhitelisted(Player player)

// 从白名单中移除玩家
public void removeWhitelisted(Player player)

// 获取玩家的违规记录
public List<Violation> getViolations(Player player)

// 重置玩家的违规记录
public void resetViolations(Player player)

// 触发一个自定义违规
public void flagViolation(Player player, String checkName, double severity)

// 获取当前的反作弊设置
public Settings getSettings()

// 重新加载配置文件
public void reloadConfig()

鍏夎氨SpectrumPlayer 类（现SpectrumPlayer） ​

描述：表示一个玩家的反作弊数据和状态。

主要方法：

java
// 获取玩家对象
public Player getPlayer()

// 获取玩家的唯一标识符
public UUID getUniqueId()

// 获取玩家的违规等级
public int getViolationLevel()

// 获取玩家的详细违规记录
public Map<String, List<Violation>> getViolationsByCheck()

// 获取玩家的检测数据
public Map<String, Object> getDetectionData()

// 检查玩家是否绕过特定检测
public boolean hasBypass(String checkName)

// 设置玩家的检测数据
public void setDetectionData(String key, Object value)

// 获取玩家的历史数据
public PlayerHistory getHistory()

DetectionModule 类 ​

描述：所有检测模块的基类，可以扩展创建自定义检测模块。

主要方法：

java
// 获取检测模块的名称
public String getName()

// 获取检测模块的描述
public String getDescription()

// 检查检测模块是否启用
public boolean isEnabled()

// 启用或禁用检测模块
public void setEnabled(boolean enabled)

// 获取检测模块的设置
public ModuleSettings getSettings()

// 处理玩家的移动数据
public void onMove(PlayerMoveEvent event, SpectrumPlayer spectrumPlayer)

// 处理玩家的交互数据
public void onInteract(PlayerInteractEvent event, SpectrumPlayer spectrumPlayer)

// 处理玩家的攻击数据
public void onAttack(EntityDamageByEntityEvent event, SpectrumPlayer spectrumPlayer)

// 处理玩家的数据包
public void onPacket(PacketEvent event, SpectrumPlayer spectrumPlayer)

// 触发违规
protected void flag(SpectrumPlayer player, double severity, String details)

Punishment 类 ​

描述：表示一个惩罚措施。

主要方法：

java
// 获取惩罚的玩家
public Player getPlayer()

// 获取惩罚的类型
public PunishmentType getType()

// 获取惩罚的原因
public String getReason()

// 获取惩罚的持续时间（秒），永久惩罚为-1
public long getDuration()

// 获取惩罚的执行者
public String getExecutor()

// 获取惩罚的时间戳
public long getTimestamp()

// 执行惩罚
public boolean execute()

// 撤销惩罚
public boolean undo()

DatabaseManager 类 ​

描述：管理反作弊系统的数据库操作。

主要方法：

java
// 保存玩家数据到数据库
public void savePlayerData(SpectrumPlayer player) // 原参数: 鍏夎氨SpectrumPlayer player

// 从数据库加载玩家数据
public SpectrumPlayer loadPlayerData(Player player) // 原返回类型: 鍏夎氨SpectrumPlayer

// 保存违规记录到数据库
public void saveViolation(Violation violation)

// 查询玩家的违规记录
public List<Violation> getPlayerViolations(UUID playerId, int limit)

// 查询服务器的违规统计
public Map<String, Integer> getViolationStats(long timeFrame)

// 清理过期数据
public void cleanupOldData(long retentionPeriod)

📡 事件系统 ​

Spectrum反作弊系统提供了一套完整的事件系统，允许其他插件监听和处理反作弊相关的事件。所有事件都继承自org.bukkit.event.Event类。

主要事件 ​

SpectrumViolationEvent ​

描述：当玩家触发一个违规时触发的事件。

主要方法：

java
// 获取触发违规的玩家
public Player getPlayer()

// 获取违规的检测名称
public String getCheckName()

// 获取违规的严重程度
public double getSeverity()

// 获取违规的详细信息
public String getDetails()

// 取消违规的处理
public void setCancelled(boolean cancelled)

鍏夎氨SpectrumPunishmentEvent（现SpectrumPunishmentEvent） ​

描述：当玩家受到惩罚时触发的事件。

主要方法：

java
// 获取受到惩罚的玩家
public Player getPlayer()

// 获取惩罚的类型
public PunishmentType getPunishmentType()

// 获取惩罚的原因
public String getReason()

// 获取惩罚的持续时间（秒）
public long getDuration()

// 取消惩罚的执行
public void setCancelled(boolean cancelled)

鍏夎氨SpectrumDetectionEvent（现SpectrumDetectionEvent） ​

描述：当反作弊系统进行检测时触发的事件。

主要方法：

java
// 获取被检测的玩家
public Player getPlayer()

// 获取检测的类型
public String getDetectionType()

// 获取检测的数据
public Map<String, Object> getDetectionData()

// 取消检测的处理
public void setCancelled(boolean cancelled)

鍏夎氨SpectrumAlertEvent（现SpectrumAlertEvent） ​

描述：当反作弊系统生成警报时触发的事件。

主要方法：

java
// 获取触发警报的玩家
public Player getPlayer()

// 获取警报的类型
public String getAlertType()

// 获取警报的消息
public String getAlertMessage()

// 获取警报的接收者列表
public List<Player> getRecipients()

// 添加警报的接收者
public void addRecipient(Player recipient)

// 移除警报的接收者
public void removeRecipient(Player recipient)

// 取消警报的发送
public void setCancelled(boolean cancelled)

📝 API使用示例 ​

以下是一些使用SpectrumAPI的示例代码：

注册监听器 ​

java
import org.bukkit.plugin.java.JavaPlugin;
import com.starlakestudio.spectrum.api.SpectrumAPI; // 原包路径: com.starlakestudio.鍏夎氨Spectrum.api.鍏夎氨SpectrumAPI
import com.starlakestudio.spectrum.event.SpectrumViolationEvent; // 原包路径: com.starlakestudio.鍏夎氨Spectrum.event.鍏夎氨SpectrumViolationEvent

public class MyPlugin extends JavaPlugin {
    
    private SpectrumAPI spectrumAPI; // 原变量名: 鍏夎氨SpectrumAPI
    
    @Override
    public void onEnable() {
        // 获取SpectrumAPI实例
        spectrumAPI = SpectrumAPI.getInstance();
        
        // 注册事件监听器
        getServer().getPluginManager().registerEvents(new 鍏夎氨SpectrumListener(), this);
    }
    
    public class 鍏夎氨SpectrumListener implements org.bukkit.event.Listener {
        
        @org.bukkit.event.EventHandler
        public void onViolation(SpectrumViolationEvent event) {
            // 处理玩家违规事件
            getLogger().info("玩家 " + event.getPlayer().getName() + 
                            " 触发了违规: " + event.getCheckName() + 
                            " 严重程度: " + event.getSeverity());
        }
    }
}

检查和修改白名单 ​

java
import com.starlakestudio.spectrum.api.SpectrumAPI; // 原包路径: com.starlakestudio.鍏夎氨Spectrum.api.鍏夎氨SpectrumAPI

public class WhitelistManager {
    
    private SpectrumAPI spectrumAPI; // 原变量名: 鍏夎氨SpectrumAPI
    
    public WhitelistManager() {
        spectrumAPI = SpectrumAPI.getInstance();
    }
    
    // 检查玩家是否在白名单中
    public boolean isPlayerWhitelisted(Player player) {
        return spectrumAPI.isWhitelisted(player);
    }
    
    // 添加玩家到白名单
    public void addPlayerToWhitelist(Player player) {
        if (!spectrumAPI.isWhitelisted(player)) {
            spectrumAPI.addWhitelisted(player);
            player.sendMessage("你已被添加到反作弊白名单！");
        }
    }
    
    // 从白名单中移除玩家
    public void removePlayerFromWhitelist(Player player) {
        if (spectrumAPI.isWhitelisted(player)) {
            spectrumAPI.removeWhitelisted(player);
            player.sendMessage("你已从反作弊白名单中移除！");
        }
    }
}

查询玩家违规记录 ​

java
import com.starlakestudio.spectrum.api.SpectrumAPI; // 原包路径: com.starlakestudio.鍏夎氨Spectrum.api.鍏夎氨SpectrumAPI
import com.starlakestudio.spectrum.data.Violation; // 原包路径: com.starlakestudio.鍏夎氨Spectrum.data.Violation

public class ViolationChecker {
    
    private SpectrumAPI spectrumAPI; // 原变量名: 鍏夎氨SpectrumAPI
    
    public ViolationChecker() {
        spectrumAPI = SpectrumAPI.getInstance();
    }
    
    // 获取玩家的违规记录
    public void checkPlayerViolations(Player staff, Player target) {
        List<Violation> violations = spectrumAPI.getViolations(target);
        
        staff.sendMessage("===== " + target.getName() + " 的违规记录 =====");
        
        if (violations.isEmpty()) {
            staff.sendMessage("该玩家暂无违规记录。");
        } else {
            for (Violation violation : violations) {
                Date date = new Date(violation.getTimestamp());
                SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
                
                staff.sendMessage("[" + sdf.format(date) + "] " + 
                                "检测: " + violation.getCheckName() + ", " +
                                "严重程度: " + violation.getSeverity() + ", " +
                                "详情: " + violation.getDetails());
            }
        }
        
        staff.sendMessage("=============================");
    }
}

创建自定义检测模块 ​

java
import com.starlakestudio.spectrum.api.module.DetectionModule; // 原包路径: com.starlakestudio.鍏夎氨Spectrum.api.module.DetectionModule
import com.starlakestudio.spectrum.player.SpectrumPlayer; // 原包路径: com.starlakestudio.鍏夎氨Spectrum.player.鍏夎氨SpectrumPlayer
import org.bukkit.event.player.PlayerMoveEvent;

public class CustomFlyDetection extends DetectionModule {
    
    public CustomFlyDetection() {
        super("CustomFly", "自定义飞行检测");
    }
    
    @Override
    public void onMove(PlayerMoveEvent event, SpectrumPlayer spectrumPlayer) { // 原参数: 鍏夎氨SpectrumPlayer 鍏夎氨SpectrumPlayer
        if (!isEnabled() || spectrumPlayer.hasBypass("movement")) {
            return;
        }
        
        Player player = event.getPlayer();
        
        // 检查玩家是否在飞行
        if (!player.isFlying() && !player.hasPermission("spectrum.bypass.movement.fly") && // 原权限节点: 鍏夎氨Spectrum.bypass.movement.fly
            isPlayerFlyingAbnormally(player)) {
            
            // 触发违规
            flag(spectrumPlayer, 1.0, "异常的飞行行为");
            
            // 可选：纠正玩家的位置
            player.teleport(event.getFrom());
        }
    }
    
    private boolean isPlayerFlyingAbnormally(Player player) {
        // 实现自定义的飞行检测逻辑
        // 这里只是一个简化的示例
        Location loc = player.getLocation();
        World world = player.getWorld();
        
        // 检查玩家是否在空中且没有任何支撑
        if (!player.isOnGround() && !player.isInsideVehicle() && 
            !hasNearbySupportBlock(loc) && !isFallingWithProtection(player)) {
            
            // 检查玩家的垂直移动
            Vector velocity = player.getVelocity();
            if (velocity.getY() > 0.01 && !player.hasPotionEffect(PotionEffectType.JUMP) &&
                !player.hasPotionEffect(PotionEffectType.LEVITATION)) {
                return true;
            }
        }
        
        return false;
    }
    
    private boolean hasNearbySupportBlock(Location loc) {
        // 检查玩家附近是否有支撑方块
        // 实际实现中需要更复杂的碰撞检测
        return false;
    }
    
    private boolean isFallingWithProtection(Player player) {
        // 检查玩家是否有降落伞、鞘翅等保护措施
        // 实际实现中需要检查玩家装备和状态
        return false;
    }
}

注册自定义检测模块 ​

java
import com.starlakestudio.spectrum.api.SpectrumAPI; // 原包路径: com.starlakestudio.鍏夎氨Spectrum.api.鍏夎氨SpectrumAPI
import com.starlakestudio.spectrum.api.module.DetectionModuleManager; // 原包路径: com.starlakestudio.鍏夎氨Spectrum.api.module.DetectionModuleManager

public class CustomModuleRegistrar {
    
    public static void registerCustomModules() {
        // 获取检测模块管理器
        DetectionModuleManager moduleManager = SpectrumAPI.getInstance().getDetectionModuleManager();
        
        // 创建并注册自定义检测模块
        CustomFlyDetection customFly = new CustomFlyDetection();
        moduleManager.registerModule(customFly);
        
        // 可以注册多个自定义模块
        // moduleManager.registerModule(new AnotherCustomModule());
    }
}

🔧 集成指南 ​

前置条件 ​

  • 确保服务器上已安装Spectrum反作弊插件
  • 在您的插件的plugin.yml中添加Spectrum作为依赖或软依赖：
```yaml
# 作为硬依赖
depend: [Spectrum]
# 或作为软依赖（推荐）
softdepend: [Spectrum]

获取SpectrumAPI实例 ​

在您的插件启用时，获取SpectrumAPI的实例：

java
@Override
public void onEnable() {
    Plugin spectrumPlugin = getServer().getPluginManager().getPlugin("Spectrum"); // 原插件名称: 鍏夎氨Spectrum
    if (spectrumPlugin != null && spectrumPlugin.isEnabled()) {
        // Spectrum已安装并启用
        spectrumAPI = SpectrumAPI.getInstance();
        getLogger().info("成功集成Spectrum反作弊系统！");
    } else {
        // Spectrum未安装或未启用
        getLogger().warning("未找到Spectrum反作弊系统，某些功能将不可用。");
    }
}

错误处理和兼容性 ​

在使用Spectrum API时，应该注意处理可能的异常和兼容性问题：

java
public void useSpectrumAPI(Player player) {
    if (spectrumAPI == null) {
        getLogger().warning("Spectrum API不可用。");
        return;
    }
    
    try {
        // 使用Spectrum API
        boolean isWhitelisted = spectrumAPI.isWhitelisted(player);
        getLogger().info("玩家 " + player.getName() + " 白名单状态: " + isWhitelisted);
    } catch (Exception e) {
        getLogger().severe("使用Spectrum API时发生错误: " + e.getMessage());
        e.printStackTrace();
    }
}

## ⚡ 性能注意事项

在使用Spectrum API时，应该注意以下性能问题：

1. **避免频繁调用API**：尽量减少对API的调用频率，特别是在高频事件（如`PlayerMoveEvent`）中。

2. **使用异步处理**：对于耗时的操作（如查询大量违规记录），应该使用异步任务处理。

3. **缓存API结果**：对于频繁使用的相同查询结果，可以考虑进行缓存。

4. **优化事件监听**：在注册事件监听器时，使用`EventPriority`和`ignoreCancelled`参数来优化性能。

5. **注意线程安全**：Spectrum API的大部分方法都不是线程安全的，应该在主线程中调用。

## 📌 API版本兼容性

SpectrumAPI的版本兼容性策略：

SpectrumAPI遵循语义化版本控制，主要版本号的变更可能会导致不兼容的API更改。以下是API版本与Spectrum插件版本的对应关系：

| Spectrum版本 | API版本 | 兼容性说明 |
|----------|---------|-----------|
| 1.0.x | 1.0 | 基础API，包含核心功能 |
| 1.1.x | 1.1 | 添加了更多事件和检测模块API |
| 1.2.x | 1.2 | 优化了API性能，增加了自定义惩罚API |
| 1.3.x | 1.3 | 添加了数据库API和高级统计API |
| 1.4.x | 1.4 | 重构了部分API，提升了扩展性 |

在集成SpectrumAPI时，应该考虑版本兼容性，并在插件中添加适当的版本检查。

## ❓ 常见问题

**Q: 如何检查服务器上是否安装了Spectrum插件？**
A: 可以使用Bukkit的`PluginManager`来检查：
```java
PluginManager pm = Bukkit.getPluginManager();
boolean hasSpectrum = pm.isPluginEnabled("Spectrum"); // 原插件名称: 鍏夎氨Spectrum

Q: SpectrumAPI是否支持异步调用？ A: 大部分SpectrumAPI方法都应该在主线程中调用。对于需要异步处理的操作，API提供了特定的异步方法或建议使用Bukkit的异步任务系统。

Q: 如何获取特定检测模块的实例？ A: 可以使用DetectionModuleManager来获取：

java
DetectionModuleManager moduleManager = SpectrumAPI.getInstance().getDetectionModuleManager(); // 原代码: 鍏夎氨SpectrumAPI.getInstance()
DetectionModule flyModule = moduleManager.getModule("Flight");

Q: 如何自定义反作弊的惩罚行为？ A: 可以通过监听SpectrumPunishmentEvent事件并取消默认惩罚，然后应用自定义惩罚：

java
@EventHandler
public void onPunishment(SpectrumPunishmentEvent event) { // 原事件: 鍏夎氨SpectrumPunishmentEvent
    // 取消默认惩罚
    event.setCancelled(true);
    
    // 应用自定义惩罚
    Player player = event.getPlayer();
    String reason = event.getReason();
    // ... 自定义惩罚逻辑
}

Q: SpectrumAPI的性能开销如何？ A: SpectrumAPI设计时充分考虑了性能问题，大多数操作的性能开销很小。但作为最佳实践，应该避免在高频事件中频繁调用API，特别是涉及数据库操作的方法。

最后更新时间：2025年10月2日

Copyright © 2025-Shanghai MatrixLight Technology Co., Ltd. All rights reserved.