Writing your own extension for Minestom

To test in a dev environnement, see last section.

Start by creating a new extension class:

package testextension;

import net.minestom.server.extensions.Extension;

public class TestExtension extends Extension {
    @Override
    public void initialize() {
        System.out.println("Hello from extension!");
    }

    @Override
    public void terminate() {

    }
}

Then, create a extension.json at the root of the resources folder (src/main/resources for instance) and fill it up:

{
  "entrypoint": "testextension.TestExtension",
  "name": "TestExtension",
  "codeModifiers": [
    "testextension.TestModifier"
  ],
  "mixinConfig": "mixins.testextension.json"
}

entrypoint: Fully qualified name of your extension class
name: Name to use to represent the extension to users. Must match regex [A-Za-z][_A-Za-z0-9]+
codeModifiers (optional): List of code modifier fully qualified-named classes to modify Minestom classes at launch time
mixinConfig (optional): Name of a JSON file for support of Mixin injection

Callback order

During MinecraftServer#start, Minestom calls preInitialize on all extensions, then initialize on all extensions, and finally postInitialize on all extensions. Minestom does NOT guarantee the loading order of extensions, but it should be deterministic.

Testing in a launch environment

The easiest option to ensure your extension is recognized, and that you can register code modifiers, is to wrap your main method inside a special launcher calling Bootstrap#bootstrap:

First argument: mainClass fully qualified name of your main class
Second argument: args program arguments Bootstrap will then setup extensions, modifiable classloader and mixin support, then call your main(String[] args) method.

Finally, when launching your wrapping launcher, add the following VM arguments:

-Dminestom.extension.indevfolder.classes=<folder to compiled classes of your extension> Specifies the folder in which compiled classes of your extension are. With a default Gradle setup, build/classes/java/main/ should work.
-Dminestom.extension.indevfolder.resources=<folder to resources of your extension> Specifies the folder in which resources of your extension are. With a default Gradle setup, build/resources/main/ should work.

Launcher example:

package testextension;

import net.minestom.server.Bootstrap;
import org.spongepowered.asm.launch.MixinBootstrap;
import org.spongepowered.asm.mixin.Mixins;

// To launch with VM arguments:
// -Dminestom.extension.indevfolder.classes=build/classes/java/main/ -Dminestom.extension.indevfolder.resources=build/resources/main/
public class TestExtensionLauncher {

    public static void main(String[] args) {
        Bootstrap.bootstrap("YOUR_MAIN_CLASS", args);
    }
}