KartoffelChipss/MCRun
1
1
Fork 0
Code Issues Pull Requests Actions Releases 2 Activity

Add README

Browse Source
This commit is contained in:
KartoffelChipss
2026-05-24 10:17:53 +02:00
parent d872b6b055
commit 43c5c75b33
3 changed files with 124 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+109
View File
@@ -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.