Automatic API Remapping via ASM Bytecode Transformation on Plugin Load

[twisti-dev]

Is your feature request related to a problem?

This plugin serves both as a runtime API and as an API provider. When internal changes occur—like method renames or class relocations—it breaks compatibility for dependent plugins. Developers currently have to manually update and recompile their plugins against the new API, which is cumbersome and error-prone.

Describe the solution you'd like.

Implement a runtime API remapping mechanism using ASM-based bytecode transformation.

The system would:

• Hook into Paper’s ClassloaderBytecodeModifier interface
• Inject a custom modifier that applies both the default Paper transformations and custom API remapping logic
• Use ASM to rewrite class/method/field references in plugin bytecode at load time
• Maintain a mapping file (like Mojang/Paper mappings) to guide the remapper

This ensures that plugins using the API remain compatible without requiring updates or recompilation.

Describe alternatives you've considered.

1. Requiring all plugin developers to recompile against each API version – time-consuming and not scalable.
2. Providing adapter shims – limited in scope and still require frequent maintenance.
3. Avoiding breaking changes altogether – restricts development flexibility and long-term maintainability.

Other

1. Custom Modifier Implementation

public class MyCustomBytecodeModifier implements ClassloaderBytecodeModifier {

    private final ClassloaderBytecodeModifier paperModifier = new PaperClassloaderBytecodeModifier();

    @Override
    public byte[] modify(PluginMeta config, byte[] bytecode) {
        // First, apply Paper's internal transformation
        byte[] processed = paperModifier.modify(config, bytecode);

        // Then apply custom API remapping
        return applyMyApiRemapping(config, processed);
    }

    private byte[] applyMyApiRemapping(PluginMeta config, byte[] bytecode) {
        ClassReader reader = new ClassReader(bytecode);
        ClassWriter writer = new ClassWriter(reader, ClassWriter.COMPUTE_MAXS);
        ClassVisitor visitor = new MyRemappingVisitor(writer); // contains mapping logic
        reader.accept(visitor, 0);
        return writer.toByteArray();
    }
}

2. Overriding the Singleton Using Unsafe (Java 21 Compatible)

import sun.misc.Unsafe;
import java.lang.reflect.Field;

public static void injectCustomModifier() {
    try {
        Class<?> providerClass = Class.forName("io.papermc.paper.plugin.entrypoint.classloader.ClassloaderBytecodeModifier$Provider");
        Field instanceField = providerClass.getDeclaredField("INSTANCE");

        Field unsafeField = Unsafe.class.getDeclaredField("theUnsafe");
        unsafeField.setAccessible(true);
        Unsafe unsafe = (Unsafe) unsafeField.get(null);

        Object base = unsafe.staticFieldBase(instanceField);
        long offset = unsafe.staticFieldOffset(instanceField);

        unsafe.putObject(base, offset, new MyCustomBytecodeModifier());

        Bukkit.getLogger().info("Successfully injected custom bytecode modifier.");
    } catch (Throwable t) {
        Bukkit.getLogger().severe("Failed to inject custom bytecode modifier.");
        t.printStackTrace();
    }
}