patchthebucket
PatchTheBucket 是一个面向 Minecraft Java 1.12.2 的 Bukkit (Spigot + Paper) 插件修补框架。
它通过 Java Agent + ASM 在加载时转换其他插件的字节码,在类完全加载之前将损坏的类替换为修复后的版本。
为什么需要
1.12.2 几乎可以在任何硬件上运行,即使是配置极低的设备也能胜任。部分插件存在轻微缺陷(1.12.2 发布于 2017 年),其源代码未针对现代工具链进行更新,且从源码重新构建非常麻烦。PatchTheBucket 允许你在字节码层面直接修复这些问题,而无需触碰原始 jar 包。
工作原理
- Java Agent (ByteBuddy Agent) 在运行时附加,无需
-javaagent参数 - PatchTheBucket 注册一个
ClassFileTransformer,并通过 Bukkit 的ServicesManager暴露PatchTheBucketAPI - 消费型插件发现该 API,声明它们的修补程序(通过注解或编程式构建器),并进行注册
- 修补程序在类加载时应用;已加载的类会被重新转换
修补程序直接使用 ASM Tree API (MethodNode, InsnList 等),没有抽象层。
设置
服务端
将 patchthebucket-1.0.0.jar 放入 plugins/ 目录。无需配置文件。
如果在 Java 21+ 上收到关于动态 Agent 加载的警告,请在 JVM 启动参数中添加:
-XX:+EnableDynamicAgentLoading
针对修补程序作者
在你的 build.gradle.kts 中添加 JitPack:
repositories {
maven("https://jitpack.io")
mavenLocal() // spigot api from BuildTools
}
dependencies {
compileOnly("com.github.colourlabs.patchthebucket:patchthebucket-api:VERSION")
compileOnly("org.ow2.asm:asm-tree:9.7")
compileOnly("org.spigotmc:spigot-api:1.12.2-R0.1-SNAPSHOT")
}
ASM 和 API 均为 compileOnly——在运行时它们来自 PatchTheBucket 的类加载器。Spigot API 也是 compileOnly,由服务器提供。
将 VERSION 替换为标签(例如 1.0.0)或 main-SNAPSHOT 以获取最新提交。
用法
基于注解
@TargetClass("net.example.BrokenPlugin")
public class MyPatches {
@TransformMethod("brokenMethod")
public static void fixIt(MethodNode method) {
method.instructions.clear();
method.instructions.add(new VarInsnNode(Opcodes.ICONST_0));
method.instructions.add(new InsnNode(Opcodes.IRETURN));
}
@Inject(method = "riskyMethod", at = @At("HEAD"))
public static InsnList guardNull(MethodNode method) {
InsnList insns = new InsnList();
LabelNode skip = new LabelNode();
insns.add(new VarInsnNode(Opcodes.ALOAD, 1));
insns.add(new JumpInsnNode(Opcodes.IFNONNULL, skip));
insns.add(new InsnNode(Opcodes.ICONST_0));
insns.add(new InsnNode(Opcodes.IRETURN));
insns.add(skip);
return insns;
}
}
在你的插件中注册
public class MyPlugin extends JavaPlugin {
@Override
public void onEnable() {
PatchTheBucketAPI api = getServer()
.getServicesManager()
.load(PatchTheBucketAPI.class);
api.registerAnnotated(MyPatches.class);
}
}
在你的 plugin.yml 中添加 depend: [PatchTheBucket]。
编程式 API
ClassPatch patch = ClassPatchBuilder.forClass("net.example.BrokenPlugin")
.transformMethod(MethodSelector.named("brokenMethod"), methodNode -> {
methodNode.instructions.clear();
// ...
})
.build();
api.register(patch);
构建
./gradlew build
输出位于 build/libs/:
| jar | 用途 |
|---|---|
patchthebucket-1.0.0.jar |
框架(已着色,部署到服务器) |
patchthebucket-api-1.0.0.jar |
供消费者编译时依赖使用的 API |
test-plugin-1.0.0.jar |
用于测试的损坏示例插件 |
patchthebucket-demo-1.0.0.jar |
修补 test-plugin 的示例消费者插件 |
设置 BuildTools
你需要安装 Java 8 来为 Spigot 设置库,已在 Linux 7.1.3 上测试。PaperMC Maven 不再托管 1.12.2,令人遗憾。
git clone https://hub.spigotmc.org/stash/scm/spigot/buildtools.git
cd buildtools
java -jar BuildTools.jar --rev 1.12.2 # USE JAVA 8 FOR THIS, it will error due to version checks.
这应该会将 1.12.2 Bukkit 开发所需的库添加到 MavenLocal,从而你可以构建项目 / 制作插件。
要求
- Java 8+
- Spigot / Paper 1.12.2
许可证
MIT
你是这个资源的作者?登录后可认领此资源。
相似资源
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
ExyliaPlugins 的库。
通过对话框或铁砧界面帮助你的 Anthme
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
评论 0
登录后参与评分
还没有评论,来抢沙发吧