BKCommonLib - 通用功能库

通用工具库，添加独特新功能和API接口

Bukkit / Spigot 作者 bergerkiller 支持版本 1.8 - 1.21

访问 Spigot 访问 Modrinth 下载插件

服务器使用量

2,441

服务玩家数

3,112

下载量

213,953

插件详细介绍

BKCommonLib 是一个面向 Paper/Spigot/Bukkit 服务器的插件与核心库，它汇集了大量实用工具、API、框架和高性能关键代码。其核心目标是让插件自身完全摆脱对 Minecraft 服务端代码（即 NMS）的直接依赖，从而大幅提升插件稳定性。当 Minecraft 更新时，通常只需更新此库，而依赖它的插件则无需改动，实现了跨版本的兼容性。

链接

兼容性

支持的服务器核心

Spigot, PaperMC, Pufferfish, Purpur, Tuinity, TacoSpigot
上述核心的大部分衍生版本均可正常运行。

混合核心支持（有限制）

Mohist (1.12.2, 1.16.5)
Magma (1.12.2)
Arclight (1.12.2, 1.15.2, 1.16.5, 1.18.2)
CatServer (1.12.2)

向后兼容性

最新版本的 BKCommonLib 兼容 Minecraft 1.8 及以上的所有版本。这意味着 BKCommonLib 1.19 版可以在 Spigot 1.12.2、Paper 1.16.5、Pufferfish 1.18.2 等服务器上运行。

请勿为旧版 Minecraft 安装旧版的 BKCommonLib，始终使用最新版本。

支持与帮助

如果 Minecraft 刚更新或 Paper 有重大优化导致 BKCommonLib 无法工作，开发者通常已在处理。你可以尝试以下途径：

开发构建：访问 Jenkins 构建服务器获取可能已修复问题的版本。
问题反馈：在 GitHub Issue Tracker 提交问题报告，旧版本服务器的问题也欢迎反馈。
社区协助：加入我们的 Discord 服务器获取帮助。虽然教程和示例项目有限，但可以在 Discord 上咨询 API 使用问题。

核心特性

Mountiplex 通用 Java 反射库

这是 BKCommonLib 能够同时支持众多不同 Minecraft 服务端版本乃至 Forge 混合核心的关键。它结合了 ASM、Javassist 和 Objenesis 的优势，并通过模板引擎在运行时生成兼容代码。

无需为 Paper/Spigot/Forge/版本及其无数衍生版的每种组合编译不同类文件。
使用 #if - #endif 模板块即可适配代码变更。
支持运行时类生成、反射处理、模板引擎。
支持动态类型/名称重映射，以适配 Forge、多版本及 Mojang 映射。
可检测类型、方法、字段的存在性，并生成相应的兼容实现。
通过 #require 访问私有成员，并在代码中通过 #name 调用。

类型转换

通过类型 <> 类型注册表自动进行值类型转换。
示例：在 API 中使用 Bukkit Entity，在生成代码中转换为 net.minecraft Entity。
兼容 NBT / YAML，可自动存储和转换任何自定义类型。
支持在模板中内联声明转换。

Cloud 命令框架

BKCommonLib 内置了 Cloud Command Framework。你可以使用注解或构建器模式编写清晰的命令，并享受完整的建议、权限处理和本地化功能。BKCommonLib 还额外添加了一些针对 Paper/Spigot 服务器的默认工具，以便更快地搭建命令系统。

PluginBase 框架

这是一个插件可以继承的基础类（替代 JavaPlugin），提供了大量便捷功能：

原生支持插件预加载器。
提供其他插件启用时的回调，以处理软依赖逻辑的动态加载/卸载。
读取 plugin.yml 以存储自定义元数据。
验证插件的所有依赖是否已启用。
提供注册（数据包）监听器的辅助方法。
支持 plugin.yml 的 classdepend 特性：无需等待依赖插件先加载，即可从其加载类。
提供读取插件版本和构建号的默认命令处理器。

权限 API

允许用户在未安装权限管理插件的情况下，通过简单的 OP 规则进行配置。
提供非常基础的基于枚举/静态常量的权限 API 来存储权限常量。
无论使用何种权限管理器（或未使用），都支持 * 通配符。
通过 PermissionDefaults.yml 使默认权限（op/not_op/false/true）可由用户配置。
当玩家缺少权限时，可抛出/处理异常。

本地化 API

提供非常基础的基于枚举/静态常量的本地化 API。
自动生成可供用户自定义的 Localization.yml 文件。
支持使用 %0%、%1% 等占位符。

SoftDependency 库

这是一个简化第三方软依赖延迟处理（启用和禁用）的轻量级库。它已默认包含在 BKCommonLib 中，无需进行重定位或打包。

依赖管理无需在 onEnable() 中调用任何方法。
示例代码展示了如何声明和初始化一个软依赖。

服务器事件

如果使用 Paper 服务器，则默认使用 Paper 的事件实现；同时也使这些事件在非 Paper 服务器上可用。
包含区块加载/卸载实体事件、生物预生成事件、实体加入/移除（从世界）/从服务器移除事件、多方块更改事件（与 WorldEdit 集成）等。

YAML 配置

BKCommonLib 的 YAML 库解决了 Bukkit 配置 API 速度慢、使用不便的问题：

仅使用 SnakeYAML 进行数据与文本的序列化。
高效的内存存储模型。
get 方法带有默认值时，行为类似于 Python 的 setdefault，便于设置默认配置。
支持为每个键添加注释头，包括文件本身的全局注释头。
默认禁用 SnakeYAML 的文档大小限制。
自动将旧版 Minecraft 聊天样式字符与 & 符号相互转换。
完全禁用锚点，并放宽了一些格式解析限制。
支持以用户可读的字符串形式干净地获取和设置枚举值。
高效的节点列表、节点克隆和迭代。
支持多版本的 ItemStack 反序列化。
可注册变更监听器：当节点或嵌套节点被修改时触发回调。
快速的自动保存功能：通过缓存过去的文本表示来最小化序列化开销。
保存时异步写入文件。
适合大型文件存储或类似 NoSQL 数据库的访问方式。

NBT - CommonTag API

提供了对服务器内部 NBT 标签库 的接口封装，广泛用于与 Minecraft 服务端 API 交互。

简单易用的 NBT 包装器。
直接操作服务器实际的内部 NBT 库，交互时无需复制数据。
支持从/向（压缩的）字节数据序列化/反序列化——可读取服务器 .dat 文件。
读取和修改物品的 NBT。
读取和修改玩家档案、level.dat 或像生物药水效果等深奥的数据。

ForcedChunk - 区块加载票证 / 区块加载器

轻松实现异步加载区块并保持其加载状态，对于需要区块持续加载以处理内部实体或方块数据的场景至关重要。

异步区块加载。
保持一个区块区域处于加载状态。
支持同一区块的多个加载票证。
使用对象跟踪加载票证，支持 RAII 风格的 AutoCloseable。
可以从其他线程创建/关闭票证。
可指定加载半径。半径 ≥2 时允许实体被刷新。

Chunk Future Provider

通过 Java CompletableFuture API 提供区块加载和卸载（实体）事件。无需编写自己的事件处理器和处理队列，即可在特定区块加载或卸载时执行逻辑。

当区块加载后再次卸载时，可执行清理工作。
可在某个区块的所有相邻区块都加载后，在该区块内执行工作。
旨在避免同步加载区块，从而提升服务器性能。
如果前提条件结束（例如中心区块被卸载），相关的 Future 会自动取消。
建议用例：发现多方块结构、读取告示牌的红石状态、生成自定义实体或启动世界事件。

方块工具

离线方块/世界：在插件中存储方块/世界信息，避免内存泄漏风险。通过 UUID 跟踪世界，无需 HashMap 查找即可访问已加载的世界。高效地将离线方块转换为已加载的 Bukkit 方块。
SignChangeTracker：定期调用 update() 即可知道告示牌是否有任何更改。无需昂贵的方块实体/方块数据查找即可知晓变化。能检测到告示牌是否被移除/卸载。可检测来自（告示牌编辑）插件和 /data 命令的更改。与区块 Future 提供器结合，可实现强大的全服务器告示牌跟踪。
BlockData：替代 Bukkit 的 BlockData API 以提供跨版本支持。在 World 中快速获取/设置 BlockData。访问方块属性，如不透明度、发光、不透明面、渲染选项（地图显示）和 Bukkit 类型。提供对旧版 Material Bukkit API 的访问，并添加对新方块类型的支持。

交互式 Minecraft 地图与地图显示

地图显示 API 极大地改进了 Bukkit 简陋的地图 API。

将 2D/3D 内容绘制到 Minecraft 地图或纹理缓冲区上。
每个地图显示都有自己的事件循环/事件回调（如 onTick()）。
使用物品元数据自动加载。创建一个物品即可完成！
自动为你分配地图 ID。
原生支持物品展示框平铺——用于创建大型图像显示。
采用科学支持的 RGB -> 地图颜色转换算法。
支持渲染 Minecraft 资源（方块、物品）和资源包。
颜色混合、深度缓冲、256 个画布层。
处理物品展示框的左/右键点击，并提供被点击的像素坐标。

控件组件

使用载具操控控制（W/A/S/D/空格/潜行）进行控制。
内置菜单导航/焦点/激活逻辑。
自动跟踪需要重绘的剪辑区域。
内置按钮、文本、标签视图等多种控件组件和菜单。

实体控制器

通过在运行时扩展服务端实体类，此 API 使得完全改变服务器上实体的行为成为可能。这是 TrainCarts 等插件运作的核心。

可以重写实体的 onTick() 以运行自定义例程。
运行实体的 onMove() 或忽略它，处理方块和实体碰撞。
在运行时热交换现有实体，赋予其自定义行为，同时保持数据一致。
重写实体网络同步（数据包）。

协议 API

提供了一个相当完整、多版本兼容的数据包 API，特别侧重于创建假实体。

如果已安装，会自动使用 ProtocolLib。
数据包监听器和监视器。可修改或取消数据包。
发送数据包，并可选择绕过监听器。
使用 EntityUtil.getUniqueEntityId() 生成假实体。
许多数据包都有完整的 API 来修改内部字段，且跨版本兼容。
实体移动数据包包含 x/y/z/偏航角/俯仰角的协议转换。
DataWatcher：可以完全检查、修改、创建实体元数据数据包。
生成盔甲架，控制其姿态和外观。
VehicleMountController：将一个实体设为另一个实体的乘客，或实现旁观。处理乱序的生成/销毁数据包。

Java 工具类

集合：提供对 FastUtil 的 Int/LongHashMap 集合的访问。隐式共享集合（写时复制）。不可变的缓存集合（可安全处理数百万玩家集合）。八叉树 / 双八叉树——将数据映射到 3D 空间，高效查询立方体区域。FastTrackedUpdateSet。SortedIdentityCache。BlockFaceSet。
数学：3D 变换——四元数和 Matrix4x4，支持偏航角/俯仰角/翻滚角转换。3D 可旋转包围盒，带碰撞检测。IntVector2（区块坐标）和 IntVector3（方块坐标）。BlockFace 逻辑/旋转/数学运算。向量数学运算。快速三角函数。
LogicUtil：支持抛出异常的函数式接口（消费者/供应者）。Java 8 Stream API 的辅助方法。处理 CompletableFuture 的辅助方法。克隆集合，运行时解析类型的克隆。synchronizeCopyOnWrite——更新不可变映射/性能缓存。
通用 I/O：Hastebin 上传/下载客户端。ByteArrayIOStream——字节数组 <> 流 API。Bit Packet/IO 流——编码/解码比特流。AsyncTextWriter——被 YAML 使用，异步编码文本并写入文件，支持 Future。
LibraryComponent：跟踪插件的逻辑，并按正确顺序启用/禁用它们。根据条件（如服务器版本）启用不同的组件。错误处理。

其他杂项功能

高效迭代世界/区块内的（方块）实体，无需创建垃圾数组或列表副本。
ChatText：简单的聊天组件 API。
HumanHand：以跨版本兼容的方式支持副手和手持物品。
库存工具。
将输入文本解析为数字、材料等。
注销事件监听器。
读取当前服务器刻值。
主线程任务委托和同步。
开发者工具：DebugUtil，可在运行时修改行为/参数。
检查已连接玩家的游戏版本（支持 ViaVersion / ProtocolSupport）。
SignEditDialog：向玩家弹出一个对话框，用于输入告示牌的 4 行文本。可指定告示牌的初始文本。无需实际的告示牌方块。

依赖信息

如果你想在自己的项目中使用 BKCommonLib，请使用以下仓库和依赖信息。记得根据需要更新版本号。

Maven

<repositories>
    <repository>
        <id>MG-Dev Jenkins CI Maven Repository</id>
        <url>https://ci.mg-dev.eu/plugin/repository/everything</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>com.bergerkiller.bukkit</groupId>
        <artifactId>BKCommonLib</artifactId>
        <version>1.20.2-v1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle (实验性支持)

repositories {
    maven {
        url = 'https://ci.mg-dev.eu/plugin/repository/everything'
    }
}
dependencies {
    compileOnly 'com.bergerkiller.bukkit:BKCommonLib:1.20.2-v1'
}

注意：如果你想使用内置的 Cloud Command Framework，请遵循相关说明来正确重定位你的导入。

自行构建

要自行构建 BKCommonLib，你需要先运行 Build Tools。否则测试会失败，Maven 也会报错。编译时并未链接实际的服务器代码，因此该依赖属于测试类型。

将 BKCommonLib 作为依赖使用时，你不需要构建 Spigot。
但如果你要运行单元测试，则可能需要构建 Spigot。

许可证

项目所有者 Bergerkiller 通常允许人们从该库中复制代码并在自己的插件中使用。但请不要复制复杂框架（如地图显示 API），这很可能失败，并且最终结果可能导致与 BKCommonLib 本身不兼容。如有疑问，请在我们的 Discord 服务器中咨询。

BKCommonLib 打包或使用了以下库，可能适用进一步的许可证条件：

Cloud Command Framework (定制分支)
ASM
Javassist
Objenesis
SnakeYAML
Google GSON

MIT 许可证

MIT License

捐赠

如果你非常喜欢我的工作并想给予一些回报，欢迎通过下方的 PayPal 按钮向我捐赠一小笔资金。非常感谢！

测试支持版本

1.8 1.9 1.10 1.11 1.12 1.13 1.14 1.15 1.16 1.17 1.18 1.19 1.20 1.20.6 1.21

版本分布

基本信息

插件名称 BKCommonLib

作者 bergerkiller

平台 Bukkit / Spigot

支持版本 1.8 - 1.21

点赞数 44

Modrinth 下载 17,317