Add README

.idea/workspace.xml

@@ -5,8 +5,9 @@
   </component>
   <component name="ChangeListManager">
     <list default="true" id="98c311c3-6130-4449-9bcb-07029b56b776" name="Changes" comment="">
-      <change afterPath="$PROJECT_DIR$/LICENSE" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/pom.xml" beforeDir="false" afterPath="$PROJECT_DIR$/pom.xml" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -33,18 +34,19 @@
     <option name="hideEmptyMiddlePackages" value="true" />
     <option name="showLibraryContents" value="true" />
   </component>
-  <component name="PropertiesComponent">{
+  <component name="PropertiesComponent"><![CDATA[{
-  &quot;keyToString&quot;: {
+  "keyToString": {
-    &quot;ModuleVcsDetector.initialDetectionPerformed&quot;: &quot;true&quot;,
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
-    &quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
+    "RunOnceActivity.ShowReadmeOnStart": "true",
-    &quot;RunOnceActivity.git.unshallow&quot;: &quot;true&quot;,
+    "RunOnceActivity.git.unshallow": "true",
-    &quot;RunOnceActivity.typescript.service.memoryLimit.init&quot;: &quot;true&quot;,
+    "RunOnceActivity.typescript.service.memoryLimit.init": "true",
-    &quot;codeWithMe.voiceChat.enabledByDefault&quot;: &quot;false&quot;,
+    "codeWithMe.voiceChat.enabledByDefault": "false",
-    &quot;git-widget-placeholder&quot;: &quot;main&quot;,
+    "git-widget-placeholder": "main",
-    &quot;kotlin-language-version-configured&quot;: &quot;true&quot;,
+    "kotlin-language-version-configured": "true",
-    &quot;vue.rearranger.settings.migration&quot;: &quot;true&quot;
+    "nodejs_package_manager_path": "npm",
+    "vue.rearranger.settings.migration": "true"
   }
-}</component>
+}]]></component>
   <component name="TaskManager">
     <task active="true" id="Default" summary="Default task">
       <changelist id="98c311c3-6130-4449-9bcb-07029b56b776" name="Changes" comment="" />

README.md

@@ -0,0 +1,109 @@
+# MCRun Maven Plugin
+
+A Maven plugin that spins up a local Minecraft server for testing your plugin and automatically copies your built jar into the server's plugins folder, downloads the server software, and launches everything with a single command.
+
+## Requirements
+
+- Java 21+ installed and available on your PATH
+- An existing Minecraft plugin Maven project
+
+## Setup
+
+### 1. Add the plugin repository
+
+Maven needs to know where to download the plugin from. Add the following to your `pom.xml` inside the `<pluginRepositories>` block (create it if it doesn't exist):
+
+```xml
+<pluginRepositories>
+    <pluginRepository>
+        <id>strassburger</id>
+        <url>https://maven.strassburger.org</url>
+    </pluginRepository>
+</pluginRepositories>
+```
+
+### 2. Add the plugin to your build
+
+Add the following inside the `<build><plugins>` section of your `pom.xml`:
+
+```xml
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.strassburger</groupId>
+            <artifactId>mcrun-maven-plugin</artifactId>
+            <version>LATEST</version>
+            <configuration>
+                <mcVersion>1.21.4</mcVersion>
+                <acceptEula>true</acceptEula>
+            </configuration>
+        </plugin>
+    </plugins>
+</build>
+```
+
+> **Note:** Replace `LATEST` with the actual latest version, and set `<mcVersion>` to whichever Minecraft version you want to test against.
+
+### 3. Run the server
+
+```bash
+mvn package mcrun:run
+```
+
+This will:
+1. Build your plugin jar
+2. Download the Minecraft server jar (if not already present)
+3. Copy your plugin into the server's `plugins/` folder
+4. Start the server
+
+---
+
+## Configuration Reference
+
+All options go inside the `<configuration>` block of the plugin declaration.
+
+| Option | Default | Description                                                                                                                     |
+|---|---|---------------------------------------------------------------------------------------------------------------------------------|
+| `mcVersion` | *(required)* | The Minecraft version to run, e.g. `1.21.4`                                                                                     |
+| `acceptEula` | `false` | Automatically accept the [Minecraft EULA](https://aka.ms/MinecraftEULA). By setting this to `true` you confirm your acceptance. |
+| `serverSoftware` | `paper` | Server software to use. Supported values: `paper`, `spigot`                                                                     |
+| `serverDirectory` | `./server` | Folder where the server files will be created                                                                                   |
+| `serverJarName` | `server.jar` | File name for the server jar inside `serverDirectory`                                                                           |
+| `memory` | `2G` | RAM allocated to the server (used for both `-Xmx` and `-Xms`), e.g. `2G`, `512M`                                                |
+| `port` | *(Minecraft default)* | Port the server listens on                                                                                                      |
+| `remoteDebug` | `false` | Enable remote JVM debugging so you can attach your IDE's debugger                                                               |
+| `debugPort` | `5005` | Port used for remote debugging (only relevant if `remoteDebug` is `true`)                                                       |
+| `jvmArgs` | *(none)* | Extra JVM flags passed to the server process (see below)                                                                        |
+| `pluginJar` | *(your built jar)* | Path to the plugin jar to deploy. You rarely need to change this                                                                |
+
+### Full configuration example
+
+```xml
+<configuration>
+    <mcVersion>1.21.4</mcVersion>
+    <serverSoftware>paper</serverSoftware>
+    <acceptEula>true</acceptEula>
+    <memory>4G</memory>
+    <port>25565</port>
+    <remoteDebug>true</remoteDebug>
+    <debugPort>5005</debugPort>
+    <jvmArgs>
+        <arg>-XX:+UseG1GC</arg>
+        <arg>-XX:+ParallelRefProcEnabled</arg>
+    </jvmArgs>
+</configuration>
+```
+
+---
+
+## Tips
+
+**The server folder is reused between runs.** The world, configuration files, and other data persist in `./server` across restarts. Delete that folder if you want a completely fresh server.
+
+**The server jar is only downloaded once.** If `server.jar` already exists in the server directory, it won't be re-downloaded.
+
+**Attaching a debugger.** Enable `<remoteDebug>true</remoteDebug>`, then in your IDE add a "Remote JVM Debug" run configuration pointing to `localhost:5005` (or whichever `debugPort` you set). Start the server first, then attach the debugger.
+
+**Stopping the server.** Use the `stop` command inside the Minecraft server console, or press `Ctrl+C` in the terminal.
+
+**Using Spigot.** When `serverSoftware` is set to `spigot`, the plugin downloads Spigot's BuildTools and compiles the jar locally rather than downloading a pre-built one. This can take several minutes on the first run, and requires Git to be installed on your system.

pom.xml

@@ -7,7 +7,7 @@
 
     <groupId>org.strassburger</groupId>
     <artifactId>mcrun-maven-plugin</artifactId>
-    <version>0.0.10</version>
+    <version>0.0.12</version>
     <packaging>maven-plugin</packaging>
 
     <name>MCRun Maven Plugin</name>