LeavesAntiIllegal 开发者文档

兼容契约

代码以 Spigot Bukkit API 1.20.1 为发布基线。线上产物不调用任何核心私有实现，只依赖 Bukkit/Paper 公开类型和 Bukkit 调度器，因此可运行于 1.20 至 26.2 的兼容服务端。

总体架构

NbtItemChecker 是离线格式适配器。它与 ItemChecker 读取同一份配置，但不在异步线程调用 Bukkit 实体/世界 API；构造时在主线程把材料与附魔注册表快照成普通集合。

线程所有权

启动、重载与关闭

reloadPluginConfig() 若从非主线程进入，会先调度回主线程。真正重载按“取消旧任务 → reloadConfig → 重建规则与保护时长 → 重启扫描器”顺序执行。

• onDisable() 取消全部 BukkitTask、注销容器监听器并清空正在等待的离线文件。
• ItemChecker 通过 volatile 引用整体替换，事件处理始终看见完整快照。
• 离线扫描器停止后会把 active 和 sweepRunning 复位，正在处理的单文件依靠 finally 清理临时文件。

在线检测链

PlayerListener 与 InventoryListener 提供低延迟阻断，周期任务提供最终一致性。两者都委托给同一个 ItemChecker，因此不会出现两套判定标准。

shouldSkip() 的顺序是 antiillegal.bypass、OP、UUID 白名单。容器扫描不绑定玩家，因此不会应用玩家 bypass；离线扫描显式排除 OP 和 UUID 白名单。

已加载容器扫描

LoadedContainerScanner 在启动时快照所有已加载区块，此后通过 ChunkLoadEvent / ChunkUnloadEvent 维护 ChunkRef 集合。每个周期从游标位置抽取最多 chunks-per-run 个区块。

1. 检查区块仍加载已卸载引用立即从集合移除。
2. 读取 tile entities只处理实现 InventoryHolder 的方块状态。
3. 读取已加载实体要求 chunk.isEntitiesLoaded()，跳过玩家。
4. 按对象身份去重使用 IdentityHashMap 支持双箱等共享库存对象。
5. 委托 ItemChecker同步移除、通知并累加统计。

离线数据流水线

并发保护协议

只有完整扫完队列才调用 saveLastSuccessfulDate()。窗口结束、禁用插件或枚举异常都以失败收尾，不推进运行日期。

NBT 兼容层

NbtItemChecker 同时接受现代 data components 与旧版 tag 结构，主入口只修改 Inventory 和 EnderItems 两个 Compound 列表。

规则快照与判定顺序

在线与离线适配器遵循相同的早返回顺序，第一条违规原因决定处置日志。规则不是修复器：一旦判违，整个物品栈从所在列表移除。

1. 材料黑名单标准化为不含命名空间的小写 ID。
2. 附魔等级自定义上限优先，其次注册表最大等级乘倍率。
3. 耐久拒绝负 damage 与超过材料最大耐久 + 10 的值。
4. 堆叠拒绝负数和超过材料原版最大堆叠的数量。
5. 属性七类属性按 modifier amount 绝对值比较。
6. 不可破坏配置启用时，存在对应标记即判违。

属性检查不依赖核心私有实现，通过 Bukkit 属性键映射阈值，同时接受 generic.attack_damage 等旧键形式。

源码索引

dev.leavesantiillegal
├── LeavesAntiIllegalPlugin
├── ItemChecker
├── Metrics
├── command.AntiIllegalCommand
├── listener.InventoryListener
├── listener.PlayerListener
└── scanner
    ├── LoadedContainerScanner
    ├── NbtItemChecker
    └── OfflinePlayerDataScanner

构建与依赖

Maven 默认解析 Spigot Bukkit API 1.20.1，使用 Java 17 编译。运行时由 1.20 至 26.2 的兼容服务端提供 Bukkit API，不将服务端 API 打包进插件。

# 发布基线
mvn clean package
# => plugin/target/LeavesAntiIllegal-3.1.1.jar

# 兼容 1.20 - 26.2 的统一产物
mvn clean package
# => plugin/target/LeavesAntiIllegal-3.1.1.jar

构建使用 Spigot 官方快照仓库。版本实现位于 versions/v1_20_1、versions/v1_21 和 versions/v26_2，CI 应分别编译这些模块并重新组装统一 JAR。

扩展时必须保留的约束

增加一种在线判定

• 把阈值读入 ItemChecker 的构造快照，不要在每件物品上反复查 YAML。
• 在 checkItem() 返回可审计的中文原因，不要直接在规则函数中删除物品。
• 若离线也应生效，在 NbtItemChecker 增加等价格式解析和合成 NBT 测试。

增加一种扫描来源

• Bukkit 活对象必须在主线程获取和修改。
• 批次必须有上限与配置开关，不能一次遍历全服所有对象。
• 复用 ItemChecker.scanContainer() 或 checkItem()，保持通知和统计一致。

修改离线写回

• 保留“按 UUID 加锁 → 再检查保护 → 备份 → 临时文件 → 原子替换”的顺序。
• 任何异常都必须清理临时文件，且不能推进成功日期。
• 不得异步调用玩家、世界、注册表或插件管理器的活状态。

bStats上报

按照bStats要求添加相关内容

• 根据bStats提供的指示，添加了类Metrics.java。来源：https://github.com/Bastian/bstats-metrics/blob/single-file/bukkit/Metrics.java
• 在 LeavesAntiIllegalPlugin（主类）的onEnable()添加上报相关代码
LeavesAntiIllegalPlugin.java复制

import org.bukkit.plugin.java.JavaPlugin;

public class ExamplePlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // You can find the plugin id of your plugins on
        // the page https://bstats.org/what-is-my-plugin-id
        int pluginId = 33374;
        Metrics metrics = new Metrics(this, pluginId);

        // Optional: Add custom charts
        metrics.addCustomChart(
            new Metrics.SimplePie("chart_id", () -> "My value")
        );
    }

}

验证与发布

• 默认构建通过 Spigot Bukkit API 1.20.1 编译。
• 同一份 Java 17 字节码面向 1.20 至 26.2 的 Bukkit API 兼容服务端运行。
• JAR 内 plugin.yml 的 name、version、main 与 Maven 坐标一致。
• JAR 不包含 Bukkit API，但包含已重定位的 Querz NBT 类和版本实现。
• 默认 config.yml 能被 SnakeYAML 解析，且关键扫描器默认开启。
• 合成 NBT 覆盖材料黑名单、32K 附魔、堆叠、属性、现代/旧版嵌套容器。
• 静态文档在桌面与移动视口无横向正文溢出，搜索、目录和复制按钮可用。
• 在隔离的 1.20、1.21 和 26.2 测试服完成启动、重载、玩家扫描、容器扫描和离线备份恢复。

jar tf plugin/target/LeavesAntiIllegal-3.1.1.jar
unzip -p plugin/target/LeavesAntiIllegal-3.1.1.jar plugin.yml
unzip -p plugin/target/LeavesAntiIllegal-3.1.1.jar config.yml
sha256sum plugin/target/LeavesAntiIllegal-3.1.1.jar