From 6c2b780c7d862eb05d2cbf652202c086c44ed011 Mon Sep 17 00:00:00 2001
From: Xavier Niochaut <jglrxavpok@gmail.com>
Date: Fri, 11 Sep 2020 21:28:44 +0200
Subject: [PATCH] Created Extensions (markdown)

---
 Extensions.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 Extensions.md

diff --git a/Extensions.md b/Extensions.md
new file mode 100644
index 0000000..da2db43
--- /dev/null
+++ b/Extensions.md
@@ -0,0 +1,67 @@
+# Writing your own extension for Minestom
+*To test in a dev environnement, see last section.*
+
+Start by creating a new extension class:
+```java
+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:
+```json
+{
+  "entrypoint": "testextension.TestExtension",
+  "name": "Test extension",
+  "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
+* `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:
+```java
+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);
+    }
+}
+```
\ No newline at end of file