Extensions

Search…
Extensions
Summary:
​Writing your own extension for Minestom​
​How extensions are loaded​
​Dependencies​
​Callback order​
​Testing in a dev environment​
​Dynamically unloading and (re)loading extensions​
Writing your own extension for Minestom
To test in a dev environment, see last section.
Start by creating a new extension class:
1
package testextension;
2
​
3
import net.minestom.server.extensions.Extension;
4
​
5
public class TestExtension extends Extension {
6
    @Override
7
    public void initialize() {
8
        System.out.println("Hello from extension!");
9
    }
10
​
11
    @Override
12
    public void terminate() {
13
​
14
    }
15
}
Copied!
Then, create a extension.json at the root of the resources folder (src/main/resources for instance) and fill it up:
1
{
2
  "entrypoint": "testextension.TestExtension",
3
  "name": "TestExtension",
4
  "version": "1.0.0",
5
  "codeModifiers": [
6
    "testextension.TestModifier"
7
  ],
8
  "mixinConfig": "mixins.testextension.json",
9
  "dependencies": [
10
    "DependentExtension",
11
    "Extension2"
12
  ],
13
  "externalDependencies": {
14
    "repositories": [
15
      {"name": "Central", "url": "https://repo1.maven.org/maven2/"}
16
    ],
17
    "artifacts": [
18
      "com.squareup:javapoet:1.13.0"
19
    ]
20
  }
21
}
Copied!
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]+
version: Version of your extension
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
dependencies (optional): List of extension names required for this extension to work.
externalDependencies (optional): List of external libraries used for this extension (see Dependencies)
How extensions are loaded
This section is purely informational and not required to work on extensions, but it is a good thing to know how extensions are loaded inside Minestom.
1. Discovery
At launch, Minestom inspects the extensions folder (resolved from the current working folder) for jar files. For each file found, it then checks if there is an extension.json file and attempts to parse it. If the file exists, and parsing succeeds, the extension is considered discovered.
Discovery can also be forced when using ExtensionManager#loadDynamicExtension(File) but works the same.
2. Load order generation / Dependency solving
Then, Minestom ensures all required dependencies for the extension are found. For external dependencies, it will download them if necessary. For extension dependencies, it simply checks if they are already loaded, or about to be loaded (because discovered in the current load-cycle).
3. Classloading and code modifiers setup
If the extension survived dependency solving, a new classloader is created for the extension to load its classes, and any potential code modifiers declared inside extension.json (including the Mixin config) are loaded.
4. Instanciation and callbacks
The extension is then instanciated from the class provided inside entrypoint, and the preInitialize, initialize and postInitialize callbacks are called. (see Callback order for more information)
Dependencies
Minestom extensions can have two types of dependencies:
1.Extension dependencies
2.External dependencies
Extension dependencies
Extensions can require other extensions to be present at runtime in order to be loaded. This is done via the dependencies array inside extension.json.
Extensions and their dependencies will be loaded in parent-first order: the root extensions of the dependency graph will always be loaded first, then extensions with one dependency, then extensions with two, and so on. If an extension is a dependency of at least two other, it is guaranteed that it will be loaded only once.
External dependencies
Your extension is free to depend on external libraries. For the moment, only maven-accessible libraries are supported.
To declare external dependencies, use the externalDependencies object inside extension.json:
1
"externalDependencies": {
2
    "repositories": [
3
      {"name": "Central", "url": "https://repo1.maven.org/maven2/"}
4
    ],
5
    "artifacts": [
6
      "com.squareup:javapoet:1.13.0"
7
    ]
8
  }
Copied!
repositories is the list of repositories to contact to get the artifacts
name: Name of the repository, used to recognize the repository inside logs
url: URL of the repository to contact
artifacts is the list of Maven coordinates from the dependencies you want to use
Minestom will download and cache the libraries inside extensions/.libs/, so that it does not require to redownload them at each launch.
Different extensions can depend on the same library (with same coordinates) and will share the code.
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 dev 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:
1
package testextension;
2
​
3
import net.minestom.server.Bootstrap;
4
import org.spongepowered.asm.launch.MixinBootstrap;
5
import org.spongepowered.asm.mixin.Mixins;
6
​
7
// To launch with VM arguments:
8
// -Dminestom.extension.indevfolder.classes=build/classes/java/main/ -Dminestom.extension.indevfolder.resources=build/resources/main/
9
public class TestExtensionLauncher {
10
​
11
    public static void main(String[] args) {
12
        Bootstrap.bootstrap("YOUR_MAIN_CLASS", args);
13
    }
14
}
Copied!
Dynamically unloading and (re)loading extensions
​Unloading​
​Reloading​
​Dynamic load​
​Swapping extension jar at runtime​
Unloading
Under the hood, Minestom registers each extension inside its own classloader. This allows extensions to be reloaded from disk without having to reboot the server.
This feature comes at a cost: because we want to fully reload an extension, all its classes must be reloaded. To do so, their classloader must be garbage-collected. This requires all references to the classloader and its classes to be garbage-collected.
This means that Minestom code cannot have any reference to your extension when reloading/unloading. That includes event callbacks (for ANY type of event), custom biomes, custom blocks, commands, and so on.
To ensure your callbacks and code is unregistered from Minestom, override the terminate method of your extensions, and unregister everything there.
If your extension is depended upon by other extensions, this will unload the dependent extensions too.
Now that you are aware of the requirements, let's see how to unload an extension:
1
// get an ExtensionManager, for instance via MinecraftServer.getExtensionManager();
2
extensionManager.unloadExtension("MyExtensionName"); // MyExtensionName must match the name given inside the extension.json file
Copied!
That's it, this line will unload the extension and all its dependents.
Reloading an extension
See Unloading for more information
If your extension is depended upon by other extensions, this will reload the dependent extensions too.
This allows to reload an extension from the same jar file that it was loaded before.
1
// get an ExtensionManager, for instance via MinecraftServer.getExtensionManager();
2
extensionManager.reload("MyExtensionName"); // MyExtensionName must match the name given inside the extension.json file
Copied!
Dynamic load
Minestom allows dynamic loading of extensions. You do have to be aware that the extension will have its preInitialize, initialize and postInitialize callbacks called immediatly upon load.
This dynamic loading goes through the exact same phases as an extension loaded during server startup.
1
// get an ExtensionManager, for instance via MinecraftServer.getExtensionManager();
2
File extensionJar = ...; // the location of the extension jar to dynamically load
3
extensionManager.loadDynamicExtension(extensionJar);
Copied!
Swapping extension jar at runtime
Now that you know how to dynamically unload and load an extension, the procedure is rather simple:
1.Unload the extension via ExtensionManager#unload(String)
2.Replace the jar
3.(Re-)Load the extension via ExtensionManager#loadDynamicExtension(File)
Feature - Previous
Open to LAN
Next - Expansion
Mixin support
Last modified 3mo ago
Copy link
Contents
Writing your own extension for Minestom
How extensions are loaded
Dependencies
Extension dependencies
External dependencies
Callback order
Testing in a dev environment
Dynamically unloading and (re)loading extensions
Unloading
Reloading an extension
Dynamic load
Swapping extension jar at runtime