Plugin ASM

模组

· 作者 laolizhennui

Plugin ASM 是一个轻量级的 Mixin 风格字节码注入框架,专为 Paper/Bukkit 服务器设计,允许通过 ASM 以声明式方式修改方法,无需手动编写字节码。

0 本站下载 0 关注 更新于 8 个月前

最新 0.1.0-alpha3 · 1.21.11 · Java Agent

一键开服(送7天)

中文

Plugin ASM

PASM 是一个轻量级、Mixin 风格的字节码注入框架,专为 Paper / Folia 服务端设计。 它允许你通过简单的注解,在运行时修改任意类的字节码——无需反射,无需继承,无性能损耗。

? 目标:让 Bukkit/Paper 插件开发者能像写普通 Java 一样实现热修补、API 增强、事件拦截等操作,而不触碰复杂的 ASM 细节。


✨ 核心特性

特性 说明
? Mixin 式注入 @Pasm + @Inject 定义目标类与方法,框架自动合并字节码
?全注入类型 BEFORE / AFTER / REPLACE / HEAD / TAIL(AROUND 降级为 REPLACE)
?️ 构造函数注入 支持 <init>,自动插入 super() 之后
?异常处理兼容 try-catch-finally 完整复制,标签映射正确
?宽类型自动偏移 long / double 参数自动处理双槽位,无需手动计算 this 偏移
⚔️ REPLACE 独占 同一方法若存在 REPLACE,自动忽略其他注入(符合 Mixin 规范)
? ASM 处理器钩子 在 pasm.json 中声明 asms 数组,实现 PasmAsmProcessor 接口,可在 premain 前后执行自定义字节码操作
?插件式扫描 将 pasm.json 放入插件 Jar 根目录,PASM 自动扫描所有注入点

? 环境要求

  • Java 8 - 21

  • Minecraft 1.0+

  • Maven 或 Gradle(仅编译插件时需要)


? 使用方法

  1. 去Github或Modrinth下载最新的Plugin ASM

  2. 添加到服务器根目录,添加后,结构应该如下:

server
| -> paper-1.xx.x-xx.jar
| -> pasm-x.x.x.jar
| -> plugins
    | -> 一些插件.jar
  1. 修改你的启动命令,修改后,应该如下:
java -javaagent:pasm-x.x.x.jar -jar paper-1.xx.x-xx.jar

使用Plugin ASM来字节码注入

参考Wiki


? 测试与兼容性

PASM 已在以下场景通过完整测试:

  • ✅ BEFORE、AFTER、REPLACE、HEAD、TAIL全类型覆盖

  • ✅ 构造函数 <init> 注入

  • ✅ 包含 try-catch-finally 的复杂方法

  • ✅ 参数含 long / double 的宽类型方法(静态→非静态、静态→静态)

  • ✅ 同一方法的多个 REPLACE 冲突检测(仅执行优先级最高者)

  • ✅ 无 pasms 仅有 asms 的配置

  • ✅ Paper 1.21.11 / Java 21

已知限制(将在后续版本改进):

  • AROUND 注入暂未实现,使用时会降级为 REPLACE 并输出警告。

  • 热加载功能尚不稳定,不建议生产环境使用。

  • 不支持修改 native 方法或抽象方法。


? 如何构建 PASM 本体(仅框架维护者)

git clone https://github.com/laolizhennui/Plugin-ASM.git
cd Plugin-ASM
mvn clean package

生成产物:target/pasm-x.x.x.jar(这就是 Java Agent)


? 参与贡献

PASM 还是一个年轻的项目,欢迎任何形式的贡献! 你可以:

  • 提交 Issue:报告 Bug 或提议新功能

  • Pull Request:修复代码、完善文档

  • 分享你的使用案例

期待你的 Star ⭐ 和 Fork ?!


? 许可证

LGPL License

Copyright © 2026 laolizhennui


最后——PASM 并不是要取代 Mixin,而是为 Paper 开发者提供一个更简单、更符合直觉的字节码注入选择。 如果你喜欢它,请告诉你的朋友;如果你遇到问题,请告诉我们。 Happy Coding! ??


English

Plugin ASM

PASM is a lightweight, Mixin‑style bytecode injection framework designed specifically for Paper / Folia server environments. It allows you to modify the bytecode of arbitrary classes at runtime using simple annotations—no reflection, no inheritance, zero performance penalty.

? Goal: Let Bukkit/Paper plugin developers implement hot‑patches, API enhancements, event interceptors, and more—* just by writing plain Java, without touching complex ASM internals*.


✨ Core Features

Feature Description
? Mixin‑style injection @Pasm + @Inject define target class & method; the framework merges bytecode automatically.
? Full injection types BEFORE / AFTER / REPLACE / HEAD / TAIL (AROUND falls back to REPLACE with a warning).
?️ Constructor injection Supports <init>; automatically inserted after super() call.
? Exception‑handler compatibility Full replication of try‑catch‑finally blocks; correct label mapping.
? Automatic wide‑type offset long / double parameters are handled as double‑slots; no manual calculation of this offset.
⚔️ Exclusive REPLACE If a method has multiple REPLACE injections, only the one with highest priority is applied.
? ASM processor hooks Declare asms array in pasm.json; implement PasmAsmProcessor interface to run custom bytecode operations before/after premain.
? Plugin‑style scanning Place pasm.json in your plugin JAR root; PASM automatically discovers all injection points.

? Environment Requirements

  • Java 8–21

  • Minecraft 1.0+

  • Maven or Gradle(only needed when compiling your plugin)


? Installation & Setup

  1. Download the latest Plugin ASM from GitHub or Modrinth

  2. Place it in your server root directory. The structure should look like this:

server
| -> paper-1.xx.x-xx.jar
| -> pasm-x.x.x.jar
| -> plugins
    | -> some-plugin.jar
  1. Modify your startup command accordingly:
java -javaagent:pasm-x.x.x.jar -jar paper-1.xx.x-xx.jar

?️ Using Plugin ASM for Bytecode Injection

Refer to the Wiki for detailed usage and examples.

? Testing & Compatibility

PASM has been fully tested in the following scenarios:

  • ✅ BEFORE, AFTER, REPLACE, HEAD, TAIL–all types covered

  • ✅ Constructor(<init>) injection

  • ✅ Methods containing try‑catch‑finally blocks

  • ✅ Methods with long / double parameters(static → non‑static, static → static)

  • ✅ Conflict detection for multiple REPLACE injectors on the same method(only the highest priority runs)

  • ✅ Configuration with asms only(no pasms)

  • ✅ Paper 1.21.11 / Java 21

Known limitations(to be improved in future versions):

  • AROUND 注入尚未实现;使用它将回退到 REPLACE 并发出警告。

  • 热重载是实验性功能,不建议用于生产环境。

  • 原生方法和抽象方法无法被修改。


? 如何构建 PASM 本身(仅限框架维护者)

git clone https://github.com/laolizhennui/Plugin-ASM.git
cd Plugin-ASM
mvn clean package

输出产物:target/pasm-x.x.x.jar——这是 Java Agent。


? 贡献指南

PASM 仍然是一个年轻的项目,欢迎任何形式的贡献! 你可以:

  • 提交 Issue:报告错误或建议新功能

  • Pull Request:修复代码、改进文档

  • 分享你的用例

期待你的 Star ⭐ 和 Fork ?!


? 许可证

LGPL 许可证

版权所有 © 2026 laolizhennui


最后说明——PASM 旨在替代 Mixin,为 Paper 开发者提供更简单、更直观的选择用于字节码注入。 如果你喜欢它,请告诉你的朋友;如果遇到任何问题,请告诉我们。 祝你编码愉快! ??

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源