BKCommonLib

Spigot/Paper实用程序库和Minecraft服务器API

资源图片
![Logo](https://github.com/bergerhealer/BKCommonLib/blob/master/misc/BKCommonLib_logo.png?raw=true) 〚 [⤓ Modrinth](https://modrinth.com/plugin/bkcommonlib) / [⤓ Spigot](https://www.spigotmc.org/resources/bkcommonlib.39590/) / [⤓ Jenkins Dev Builds](https://ci.mg-dev.eu/job/BKCommonLib/) / [Source on GitHub](https://github.com/bergerhealer/BKCommonLib) / [Javadocs](https://ci.mg-dev.eu/javadocs/BKCommonLib/) / [Discord](https://discord.gg/wvU2rFgSnw) 〛 ## 关于 BKCommonLib **BKCommonLib** 是一个 Paper/Spigot/Bukkit 服务器插件和库，包含大量实用程序、API、框架和性能关键代码。 它的设计目的是消除插件本身对 Minecraft 服务器代码（即 NMS）的所有使用，从而提高其稳定性。 它使得当 Minecraft 更新时，只有这个库需要更新。 使用它的插件通常不需要更新，除非需要与 BKCommonLib 本身保持兼容。 ### 兼容的服务器 - **Spigot**, PaperMC, Pufferfish, Purpur, Tuinity, TacoSpigot - 大多数上述分支都应该可以正常工作 - **Forge Paper 混合体**, 具有局限性： - 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 刚刚更新或 Spottedleaf 在 Paper 中进行了一些突破性优化，您可能会发现 BKCommonLib 停止工作。 Bergerkiller 可能会对此进行处理，并且可能在我们构建服务器上已经有开发构建可以解决您的问题： **开发构建:** [https://ci.mg-dev.eu/job/BKCommonLib/](https://ci.mg-dev.eu/job/BKCommonLib/) 向我们报告任何问题到 [GitHub 问题跟踪器](https://github.com/bergerhealer/BKCommonLib/issues) 或加入我们的 [Discord 服务器](https://discord.gg/wvU2rFgSnw) 寻求帮助。 对于旧服务器版本的错误报告也欢迎。 教程和示例项目有点缺乏，但您可以在 Discord 上询问 API 帮助。我们会提供帮助。 ## 功能
包含 Mountiplex 通用目的 Java 反射库 ##### [**Mountiplex**](https://github.com/bergerhealer/Mountiplex) 是 BKCommonLib 能够支持如此多种不同的 Minecraft 服务器版本甚至 Forge 的核心。它结合了 [ASM](https://github.com/llbit/ow2-asm)、[Javassist](https://github.com/jboss-javassist/javassist) 和 [Objenesis](http://objenesis.org/) 的优势，并使用 _模板引擎_ 在运行时生成兼容代码。 为了实现这一点，它支持宏、反射和重映射的模板声明，并将此塑造成运行时生成的接口。 这意味着您不需要为 paper/spigot/forge/版本以及人们创建的数百万分支编译不同的类。 如果有人更改了一些东西，添加一个 _#if - #endif_ 块，您就设置好了！ [以下是一个模板示例，用于演示这种方法的各种包的力量](https://github.com/bergerhealer/BKCommonLib/blob/master/src/main/templates/com/bergerkiller/templates/net/minecraft/network/protocol_packets_other.txt) - 具有 Handles、反射、模板引擎的运行时类生成 - 动态类型/名称重映射以支持 forge/多版本/Mojang 映射 - 解析字符串版本，进行比较。 也在模板内部。 - 检测类型、方法和字段的存在，并生成适当的兼容实现 - 使用 _#require_ 在代码中的任何地方访问私有成员并使用 _#name_ 调用它们 - Maven Mojo 任务生成接口或将块注释转换为字符串（jdk8 多行字符串支持） - 类型转换 - 使用类型 <> 类型注册表自动将一种值类型转换为另一种类型 - 示例：在 API 中使用 Bukkit 实体，对于生成的代码使用 net.minecraft 实体 - 与 NBT / YAML 兼容，以存储任何自定义类型并自动转换 - 在您的模板中声明转换： ```java // 字段 public final (IntVector3) BlockPosition position; // 实例方法 public (List) List findEntities() { // 代码 } ``` ******
包含 Cloud Command Framework ##### BKCommonLib 包含 [**Cloud Command Framework**](https://github.com/bergerhealer/cloud)。使用注释或构建器模式编写干净的命令，并提供建议、权限处理和本地化。 BKCommonLib 添加了一些默认实用程序，以便更快地设置 Paper/Spigot 服务器。 ******
PluginBase 框架 ##### **PluginBase** 是插件可以实现的基类，而不是 _JavaPlugin_，它提供了对许多便捷功能的访问： - 原生支持此 [Plugin Preloader](https://github.com/bergerhealer/PluginPreloader) - 其他插件启用时的回调，用于处理软依赖逻辑的动态加载/卸载 - 读取 plugin.yml 以存储自定义元数据 - 验证插件的所有依赖项是否实际已启用 - 简单的辅助方法来注册（包）侦听器 - Plugin.yml _classdepend_ 功能：无需在您的插件之前加载即可加载来自其他插件的类 - 读取插件版本和构建号的默认命令处理程序 - 权限 API - 允许人们在不需要权限管理器的情况下设置插件，并使用简单的 OP 规则 - 非常基本的枚举/静态基于的权限 API 以存储你的权限常量 - 添加对 * 通配符的支持，无论使用什么权限管理器（或没有） - 使用 PermissionDefaults.yml 配置默认（op/not_op/false/true）用户 - 在玩家缺乏权限时抛出/处理异常 - 本地化 API - 非常基本的枚举/静态基于的本地化 API - 自动生成一个用户可以自定义的 Localization.yml - 支持使用 %0% %1% 等占位符 ******
SoftDependency 库 ##### [SoftDependency](https://github.com/bergerhealer/SoftDependency) 是一个简单的库，可以更轻松地懒处理第三方软依赖项的启用和禁用。 有关更多信息，请参阅 Project GitHub 页面。 此库默认包含在 BKCommonLib 中，无需内联或重新定位。 依赖项管理是在 _onEnable()_ 中不需要调用任何方法的情况下处理的。 ##### 示例 ```java public class MyPlugin extends JavaPlugin { private final SoftDependency myDependency = new SoftDependency(this, "my_dependency") { @Override protected MyDependencyPlugin initialize(Plugin plugin) { return MyDependencyPlugin.class.cast(plugin); } @Override protected void onEnable() { getLogger().info("MyDependency 支持已启用！"); } @Override protected void onDisable() { getLogger().info("MyDependency 支持已禁用！"); } }; // 可以在任何地方使用 myDependency.get()，如果启用则返回非空值。 } ``` ******
服务器事件 ##### 如果使用 Paper 服务器，则默认为 Paper 实现。 还为非 Paper 服务器提供事件。 - Chunk 加载/卸载实体事件 - CreaturePreSpawnEvent - 实体添加/从世界移除/从服务器移除事件 - MultiBlockChangeEvent（WorldEdit 集成） ******
YAML 配置 ##### Bukkit 的配置 API 很糟糕。 速度慢，默认值需要内联资源，以及使用节点和列表进行操作都很繁琐。 BKCommonLib 的 YAML 库改变了所有这些： - 仅使用 SnakeYAML 用于数据<>文本序列化 - 高效的内存存储模型 - 带有默认值的获取就像 python 的 **setdefault** 一样。 轻松默认配置！ - 对于每个键，包括文件本身的全局标头，支持标题注释 - 禁用 SnakeYAML 的默认文档大小限制 - 使用干净的方式获取和设置实体，存储为用户可读的字符串 - 支持变化侦听器：在修改节点或嵌套节点时调用回调 - 高效的自动保存功能 - 通过缓存过去的文本表示来最大限度地减少序列化开销 - 当保存时异步写入文件 - 对文件块进行全局锁定，如果仍有保存() 挂起，则禁止未来 load() - 适用于大型文件存储/类数据库访问 ##### 示例 ```java FileConfiguration config = new FileConfiguration(myPlugin, "file.yml"); config.load(); config.setHeader("This is the header at the top of the file"); config.addHeader("This adds a new line"); String coolName = config.get("coolName", "DefaultCoolName"); config.setHeader("stuff", "\nThis is some stuff"); ConfigurationNode stuff = config.getNode("stuff"); boolean stuffEnabled = stuff.get("enabled", false); int stuffCount = stuff.get("count", 0); // 克隆 stuff 设置，修改，显示 yaml ConfigurationNode stuffCopy = stuff.clone(); stuffCopy.set("count", 20); System.out.println(stuffCopy.toString()); config.save(); // 非阻塞！ ``` ******
NBT - CommonTag API ##### 提供对服务器内部 **NBT 标记** 库的接口。 当与 Minecraft 服务器 API 交互时广泛使用。 - 简单友好的 NBT 包装器 - 运行在服务器的实际内部 NBT 库上，因此在与服务器交互时无需复制 - 从/到 (压缩) 字节数据序列化/反序列化 - 读取和修改项目 NBT - 读取和修改玩家配置文件、level.dat 或 Mob Potion Effects 等隐秘的东西 ******
ForcedChunk - Chunk 加载票 / Chunk 加载器 ##### 可以轻松加载块，而无需挂起主线程，**并保持其加载状态**。 当块必须保持加载状态以对内部实体进行滴答或加载块以处理块数据时，这一点很重要。 用途非常简单。 - 异步块加载 - 保持块区域已加载 - 支持相同的块的多个加载票 - 使用对象跟踪加载票，RAII AutoCloseable - 可以从其他线程创建/关闭票 - 可以指定半径。 半径为 2+ 将允许实体滴答。 ##### 示例 ```java final ForcedChunk chunk = ForcedChunk.load(world, chunk_x, chunk_z); chunk.getChunkAsync().thenAccept(chunk -> { // 与块一起工作 for (BlockState state : chunk.getBlockStates()) { System.out.println(state); } // 释放块票。 可以保留它，并保持块加载。 chunk.close(); }); ``` ******
Chunk Future Provider ##### 通过 **Java CompletableFuture API** 提供 **Chunk Load 和 Unload (Entities) Bukkit Events**。 在特定块加载或卸载时执行逻辑，而无需编写自己的 EventHandler 处理队列。 在块刚刚卸载时清理工作，或者在中心块卸载的情况下执行其他邻块加载后工作。 旨在防止同步加载块，这会对服务器性能产生负面影响。 当前提条件结束时，将来会自动取消。 例如，如果中心块卸载，则等待所有相邻块加载的未来将取消。 **建议用途**: 发现多方块结构，读取符号石状态，生成自定义实体或启动世界事件 ##### 示例 ```java private ChunkFutureProvider provider; // = ChunkFutureProvider.of(myPlugin); @EventHandler public void onChunkLoad(ChunkLoadEvent event) { // 当块及其所有 8 个相邻块加载时，在块中执行工作 // 如果输入块卸载，此未来将被取消。 provider.whenAllNeighboursLoaded(event.getChunk(), ChunkNeighbourList.neighboursOf(event.getChunk(), 1)) .thenAccept(this::doWorkInChunk); } public void doWorkInChunk(Chunk chunk) { // 检查块状态，可能进入相邻块 // 我们知道相邻块也被加载了，所以没有同步块加载！ 耶！ } ``` ******
块实用程序 #### 离线块/世界 - 在您的插件中存储块/世界而不冒内存泄漏的风险 - 通过 UUID 跟踪世界并访问加载的 Bukkit 块，无需 HashMap 查找 - 跟踪离线块，高效地将其转换为加载的 Bukkit 块 - OfflineWorld 与身份 hashmaps 兼容 - OfflineBlock 可以安全地用作 hashmap 的键 #### SignChangeTracker - routinely call update()，您知道符号的任何更改 - 知道符号是否更改，无需进行昂贵的块实体/块数据查找 - 知道符号是否被移除/卸载 - 将检测来自（符号编辑）插件和 /data 命令的更改 - 如果与块未来提供程序相结合，可以对服务器进行纵向符号跟踪 #### BlockData - 替换跨版本支持的 Bukkit BlockData API - 以 World 为中心快速获取/设置 BlockData - 访问块属性，例如不透明度、发射、不透明面、渲染选项 (Map 显示) - 提供对 legacy Material Bukkit API 的访问。 添加对新块类型的支持（ legacy 支持） - 访问常规服务器值 - 适用于快速比较和从默认值恢复的代理服务器 ******
交互式 Minecraft 地图与 Map 显示 #### [**Map Display API**](https://wiki.traincarts.net/p/Map_Display)     #### Bukkit 的 Map API 很糟糕。 BKCommonLib 做得更好。 - 在 Minecraft 地图或纹理缓冲区上绘制 2D/3D 内容 - 每个地图显示都有自己的事件循环/事件回调，例如 onTick() - 使用 Item Metadata 自动加载 - 自动为您分配 Map Ids - 原生支持 ItemFrame 瓷砖 - 大型图像显示 - 基于科学的 RGB -> Map 颜色转换 - 支持渲染 Minecraft 资产 (块、物品) 和资源包 - 颜色混合、深度缓冲区、256 层画布 - 处理物品帧的左键/右键单击，提供已单击的像素坐标 - 小部件 - 使用车辆转向控制 (W/A/S/D/Space/Sneak) 控制 - 内置菜单导航/焦点/激活逻辑 - 自动跟踪需要重绘的剪切区域 - 内置按钮、文本、选项卡视图和其他内置小部件和菜单 ******
实体控制器 ##### 通过在运行时扩展服务器实体类，此 API 使能够完全更改服务器上实体的行为成为可能。 这是 [TrainCarts](https://github.com/bergerhealer/TrainCarts) 如何运作的核心。 - 覆盖实体 _onTick()_ 以运行您自己的例程 - 运行实体 _onMove()_ 或省略它，处理块和实体碰撞 - 在保持数据一致的同时在运行时用自定义行为替换现有实体 - 覆盖实体网络同步（包） ******
协议 API ##### 提供相当完整的 Multi-Version 兼容的 **Packet API**，特别是为了创建 * fake 实体* 而设计的。 - 如果安装，则自动使用 ProtocolLib - 包侦听器和监控器。 修改包，取消包。 - 发送包，可以选择绕过侦听器 - EntityUtil.getUniqueEntityId() 以生成 fake 实体 - 许多包都具有完整的 API 来修改字段，跨版本兼容 - 实体移动包包括 x/y/z/偏航/皮托管协议转换 - DataWatcher：Entity 元数据包可以被完全检查/修改/创建 - 生成 armorstand，控制姿势和外观 - _VehicleMountController_ 将一个实体作为另一个的乘客，或作为观察者。 处理乱序的 spawn/destroy 包。 ******
Java 实用程序 #### 集合 - 访问 FastUtil 的 Int/LongHashMap 集合 - 隐式共享集合（并发写入时复制） - 不可变缓存集合（安全地使用数百万玩家集合） - Octree / DoubleOctree - 将数据映射到 3D 空间，高效查询立方体 - FastTrackedUpdateSet - 高效地请求或取消对接收者的更新 - 高效地迭代需要更新的元素（例如，从任务） - SortedIdentityCache - 将一种集合类型映射到另一种，并缓存映射结果 - 跟踪从第三方集合中添加或删除时元素 - 针对迭代/元素顺序进行高度优化，以便同步 - BlockFaceSet - 存储 BlockFace 值、在一个集合中 #### 数学 - 3D 变换 - 使用偏航/皮托管/滚转旋转的 Quaternion 和 Matrix4x4 - 具有命中测试的 3D 可旋转边界框 - IntVector2 (块坐标) 和 IntVector3 (块坐标) - BlockFace 逻辑/旋转/数学 - 矢量数学 - 快速三角函数 #### LogicUtil - 用于消费者/提供程序的函数式接口，这些函数可以抛出 - Java 8 Stream API 的辅助方法 - 用于处理 CompletableFutures 的辅助方法 - 克隆集合，在运行时解析类型进行克隆 - synchronizeCopyOnWrite - 更新不可变映射/性能缓存 #### 一般 I/O - Hastebin 上传器/下载器客户端 - ByteArrayIOStream - 字节数组 <> 流 API - 位包/IO-流 - 编码/解码位流 - AsyncTextWriter - 用于 yaml，异步编码文本并写入文件，具有未来 #### LibraryComponent - 跟踪您插件的逻辑并以正确的顺序启用/禁用它们 - 根据条件启用不同的组件，例如服务器版本 - 错误处理 ******
其他 ##### 许多其他功能隐藏在实用程序类中。 看看吧。 - 在不创建垃圾数组或列表副本的情况下迭代世界/块实体 - ChatText：简单的 Chat Component API - HumanHand：以跨版本兼容的方式支持 off-hand 和 held 物品 - 物品栏实用程序 - 解析输入文本为数字、材质等 - 取消注册事件侦听器 - 读取服务器当前滴答值 - 主线程任务委派和同步 - 对于开发人员：DebugUtil 以运行时修改行为/参数 - 检查连接玩家的游戏版本（ViaVersion / ProtocolSupport） - SignEditDialog - 向玩家显示一个弹出窗口，以输入符号的 4 行文本 - 指定符号上的初始文本 - 不需要实际符号块 ******
## 依赖信息 想在您自己的项目中用到 BKCommonLib 吗？ 使用以下仓库和依赖信息。 请记住，根据需要更新版本。 想使用包含的 [Cloud Command Framework](https://github.com/bergerhealer/cloud) 吗？ 请按照 [这些说明](https://github.com/bergerhealer/BKCommonLib/blob/master/CLOUD_HOWTO.md) 正确地重新定位您的导入。
Maven ```xml MG-Dev Jenkins CI Maven Repository https://ci.mg-dev.eu/plugin/repository/everything com.bergerkiller.bukkit BKCommonLib 1.20.2-v1 provided ```
Gradle (实验性) ```groovy repositories { maven { url = 'https://ci.mg-dev.eu/plugin/repository/everything' } } dependencies { compileOnly 'com.bergerkiller.bukkit:BKCommonLib:1.20.2-v1' } ```
#### 构建 BKCommonLib 要自己构建 BKCommonLib，首先需要运行 [Build Tools](https://www.spigotmc.org/wiki/buildtools/)。 否则，测试将失败，Maven 将报错。 编译时无需链接 Minecraft 服务器代码，因此依赖项类型为测试。 如果您运行 **单元测试**，则不需要构建 Spigot 使用 BKCommonLib 作为依赖项。 ## 许可 Bergerkiller，项目所有者，通常允许人们复制库中的代码并在自己的插件中使用。 如果不确定，请在我们的 Discord 服务器上询问。 BKCommonLib 内联/使用以下库，可能适用进一步的许可条件： - [Cloud Command Framework](https://github.com/bergerhealer/cloud) （自定义分支） - [ASM](https://github.com/llbit/ow2-asm) - [Javassist](https://github.com/jboss-javassist/javassist) - [Objenesis](http://objenesis.org/) - [SnakeYAML](https://github.com/snakeyaml/snakeyaml) - [Google GSON](https://github.com/google/gson)
MIT 许可证，此处仅提供一些乏味的事情以免被起诉 
MIT 许可证

版权所有 (C) 2013-2015 bergerkiller 版权所有 (C) 2016-2022 Berger Healer

在此授予任何获得本软件和相关文档文件（“软件”）副本的人，免费许可，允许其在软件中处理，
包括但不限于使用、复制、修改、合并、发布、分发和/或再许可软件的权利，以及允许向本软件提供者的人行事，
遵守以下条件：

上述版权声明和此许可声明应包含在软件的所有副本或重要部分中。

软件按“现况”提供，不提供任何明示或暗示的担保，包括但不限于适销性、适合特定用途和非侵权的担保。 在任何
合同、侵权或其它行为引起的索赔、损害或其他责任中，作者或版权所有者概不负责，无论是否存在
软件的使用或其它交易。
## 捐赠 如果您非常喜欢我的作品并想以某种方式回报，请随时通过以下按钮向我通过 PayPal 捐赠少许资金。 谢谢！ :) [![Hello](https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif)](https://www.paypal.me/teambergerhealer)