From 43c5c75b3335179d5aa6d6f18279b75d3e859795 Mon Sep 17 00:00:00 2001 From: KartoffelChipss Date: Sun, 24 May 2026 10:17:53 +0200 Subject: [PATCH] Add README --- .idea/workspace.xml | 26 ++++++----- README.md | 109 ++++++++++++++++++++++++++++++++++++++++++++ pom.xml | 2 +- 3 files changed, 124 insertions(+), 13 deletions(-) create mode 100644 README.md diff --git a/.idea/workspace.xml b/.idea/workspace.xml index aa7bfc0..bb7dcde 100644 --- a/.idea/workspace.xml +++ b/.idea/workspace.xml @@ -5,8 +5,9 @@ - + + - { - "keyToString": { - "ModuleVcsDetector.initialDetectionPerformed": "true", - "RunOnceActivity.ShowReadmeOnStart": "true", - "RunOnceActivity.git.unshallow": "true", - "RunOnceActivity.typescript.service.memoryLimit.init": "true", - "codeWithMe.voiceChat.enabledByDefault": "false", - "git-widget-placeholder": "main", - "kotlin-language-version-configured": "true", - "vue.rearranger.settings.migration": "true" + +}]]> diff --git a/README.md b/README.md new file mode 100644 index 0000000..22c58cb --- /dev/null +++ b/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 `` block (create it if it doesn't exist): + +```xml + + + strassburger + https://maven.strassburger.org + + +``` + +### 2. Add the plugin to your build + +Add the following inside the `` section of your `pom.xml`: + +```xml + + + + org.strassburger + mcrun-maven-plugin + LATEST + + 1.21.4 + true + + + + +``` + +> **Note:** Replace `LATEST` with the actual latest version, and set `` 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 `` 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 + + 1.21.4 + paper + true + 4G + 25565 + true + 5005 + + -XX:+UseG1GC + -XX:+ParallelRefProcEnabled + + +``` + +--- + +## 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 `true`, 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. \ No newline at end of file diff --git a/pom.xml b/pom.xml index 7702399..49cb129 100644 --- a/pom.xml +++ b/pom.xml @@ -7,7 +7,7 @@ org.strassburger mcrun-maven-plugin - 0.0.10 + 0.0.12 maven-plugin MCRun Maven Plugin