Minecraft-Plugin programmieren: das erste eigene Plugin mit Paper

Plugin oder Mod?

Mods verändern das Spiel selbst und müssen meist auf Server und Client installiert sein. Plugins laufen dagegen nur auf dem Server und nutzen eine feste Schnittstelle. Diese Schnittstelle stammt ursprünglich vom Projekt Bukkit; heute sind Spigot und vor allem Paper die verbreiteten Server, die sie weiterführen. Wie es dazu kam, erzählt der Beitrag Aus mit Bukkit?

Was du brauchst

• ein Java Development Kit (JDK) in der Version, die dein Server verlangt – für aktuelle Versionen Java 21,
• eine Entwicklungsumgebung wie IntelliJ IDEA Community, Eclipse oder VS Code mit Java-Erweiterung,
• das Build-Werkzeug Gradle oder Maven,
• einen lokalen Testserver mit Paper.

Den Testserver betreibst du am besten getrennt vom „richtigen“ Server. Wie du eine Java-Laufzeit auf Linux installierst, steht in den Linux-Server-Grundlagen.

Das Projekt anlegen

Lege ein neues Gradle-Projekt an und trage die Paper-API als Abhängigkeit ein. Die Versionsnummer muss zu deinem Server passen; die aktuelle findest du in der Paper-Dokumentation.

plugins {
    java
}

repositories {
    maven("https://repo.papermc.io/repository/maven-public/")
}

dependencies {
    // Version an deinen Server anpassen
    compileOnly("io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT")
}

java {
    toolchain.languageVersion.set(JavaLanguageVersion.of(21))
}

Die plugin.yml

Jedes Plugin braucht im Ordner src/main/resources eine Beschreibungsdatei. Sie verrät dem Server Namen, Version, Hauptklasse und Befehle:

name: Begruessung
version: 1.0.0
main: de.beispiel.begruessung.BegruessungPlugin
api-version: '1.21'
commands:
  hallo:
    description: Sagt Hallo

Die Hauptklasse

Die Hauptklasse erbt von JavaPlugin. Die Methoden onEnable() und onDisable() ruft der Server beim Laden und Beenden auf:

public class BegruessungPlugin extends JavaPlugin implements Listener {

    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(this, this);
        getLogger().info("Begruessung ist bereit.");
    }

    @EventHandler
    public void beimBetreten(PlayerJoinEvent event) {
        event.getPlayer().sendMessage("Willkommen auf dem Server!");
    }
}

Einen Befehl hinzufügen

Befehle aus der plugin.yml verarbeitest du mit einem CommandExecutor oder direkt in der Hauptklasse, indem du onCommand überschreibst. Prüfe dort immer, wer den Befehl ausführt – ein Spieler, die Konsole oder ein Befehlsblock – und ob die nötige Berechtigung vorhanden ist. Paper bietet inzwischen zusätzlich eine eigene, moderne Befehls-Schnittstelle mit automatischer Vervollständigung; für den Anfang reicht der klassische Weg.

Konfiguration und Daten

Einstellungen gehören in eine config.yml. Mit saveDefaultConfig() legt das Plugin beim ersten Start eine Vorlage an, mit getConfig() liest es Werte aus. Für größere Datenmengen, etwa Kontostände oder Statistiken, lohnt eine Datenbank. Wer Daten mit einer Webseite teilen möchte, findet Möglichkeiten im Beitrag Bukkit Connect.

Typische Anfängerfehler

• Die api-version fehlt oder passt nicht zum Server.
• Die Paper-API wird mit in die JAR gepackt, statt nur als compileOnly eingebunden.
• Lange Aufgaben wie Datenbankabfragen laufen im Haupt-Thread und lassen den Server ruckeln – dafür gibt es den Scheduler mit asynchronen Aufgaben.
• Fehlende Prüfung auf null, etwa wenn ein Spieler den Server bereits verlassen hat.

Wenn dein Plugin reif für andere ist, hilft ein Blick auf die Entwicklungsphasen von Software: Eine ehrliche Kennzeichnung als Alpha oder Beta erspart Ärger mit Serverbetreibern.