Jak napisać własny plugin do Minecrafta — przewodnik dla początkujących

Własny plugin to najszybsza droga do tego, żeby Twój serwer Minecraft odróżniał się od konkurencji. Każdy serwer ma EssentialsX i LuckPerms — ale tylko Ty możesz mieć plugin, który robi dokładnie to, czego potrzebują Twoi gracze.

Jak napisać własny plugin do Minecrafta – snapshot Minecrafta na serwerze Minecraft

To także świetne wprowadzenie do Javy. Środowisko jest niskoprogowe (działa lokalnie, łatwo testować), a efekty widać natychmiast w grze. W tym wpisie przejdziemy od pustego komputera do uruchomionego pluginu w godzinę.

Co Ci będzie potrzebne

JDK 21 — np. Adoptium Temurin.
IDE — IntelliJ IDEA Community (darmowe, najlepsze do Javy).
Maven lub Gradle — narzędzia budowania (Maven prostszy na start).
Lokalny serwer Paper do testów.

Maven jest zwykle wbudowany w IntelliJ. Java 21 jest wymagana dla Minecrafta 1.20+.

Nowy projekt Mavena

W IntelliJ: File → New → Project → Maven Archetype. Albo z linii poleceń:

mvn archetype:generate \
  -DgroupId=pl.mojserwer.plugin \
  -DartifactId=helloplugin \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

Otrzymasz strukturę:

helloplugin/
  pom.xml
  src/main/java/pl/mojserwer/plugin/App.java

pom.xml — zależności

Edytuj pom.xml, dodaj repozytorium PaperMC i zależność:

<repositories>
  <repository>
    <id>papermc</id>
    <url>https://repo.papermc.io/repository/maven-public/</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>io.papermc.paper</groupId>
    <artifactId>paper-api</artifactId>
    <version>1.21.4-R0.1-SNAPSHOT</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <configuration>
        <source>21</source>
        <target>21</target>
      </configuration>
    </plugin>
  </plugins>
</build>

Pierwsza klasa pluginu

Stwórz src/main/java/pl/mojserwer/plugin/HelloPlugin.java:

package pl.mojserwer.plugin;

import org.bukkit.plugin.java.JavaPlugin;

public final class HelloPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        getLogger().info("HelloPlugin uruchomiony!");
    }

    @Override
    public void onDisable() {
        getLogger().info("HelloPlugin zatrzymany.");
    }
}

onEnable() jest wywoływane przy starcie serwera, onDisable() przy wyłączeniu.

plugin.yml — manifest

Plik src/main/resources/plugin.yml:

name: HelloPlugin
version: 1.0.0
main: pl.mojserwer.plugin.HelloPlugin
api-version: 1.21
author: Mariusz
description: Mój pierwszy plugin do Minecrafta.

commands:
  hello:
    description: Pozdrawia gracza
    usage: /hello

main to pełna ścieżka klasy głównej. api-version musi pasować do wersji Papera.

Pierwsza komenda

Rozszerz klasę o obsługę /hello:

package pl.mojserwer.plugin;

import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.plugin.java.JavaPlugin;

public final class HelloPlugin extends JavaPlugin {

    @Override
    public boolean onCommand(CommandSender sender, Command cmd,
                             String label, String[] args) {
        if (cmd.getName().equalsIgnoreCase("hello")) {
            if (sender instanceof Player player) {
                player.sendMessage("Hej, " + player.getName() + "!");
                return true;
            }
            sender.sendMessage("Tylko gracze mogą używać /hello.");
            return true;
        }
        return false;
    }
}

Jak napisać własny plugin do Minecrafta – nowa wersja Minecrafta na serwerze Minecraft

Reagowanie na eventy

Powitanie nowych graczy. Stwórz osobną klasę JoinListener.java:

package pl.mojserwer.plugin;

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;

public final class JoinListener implements Listener {

    @EventHandler
    public void onJoin(PlayerJoinEvent event) {
        event.getPlayer().sendMessage("Witamy na serwerze!");
    }
}

Zarejestruj listener w onEnable():

getServer().getPluginManager()
    .registerEvents(new JoinListener(), this);

Budowanie i testowanie

W terminalu:

mvn clean package

Powstanie target/helloplugin-1.0.0.jar. Wrzuć go do plugins/ swojego serwera Paper i zrestartuj. Po wejściu zobaczysz powitanie i możesz wpisać /hello.

Konfiguracja w config.yml

Dodaj src/main/resources/config.yml:

welcome-message: "Witamy na serwerze!"

I wczytaj w pluginie:

@Override
public void onEnable() {
    saveDefaultConfig();
    String message = getConfig().getString("welcome-message");
    getLogger().info("Welcome: " + message);
}

Po pierwszym uruchomieniu config zostanie skopiowany do plugins/HelloPlugin/config.yml — gracze mogą go edytować bez ruszania kodu.

Dobre praktyki

Trzymaj logikę poza klasą główną — używaj osobnych klas dla komend, listenerów, serwisów.
Zawsze sprawdzaj null i typ sender w komendach.
Nie używaj System.out — używaj getLogger().
Async dla operacji I/O (DB, HTTP) — Bukkit.getScheduler().runTaskAsynchronously(...).
Loguj błędy z kontekstem — łatwiejsze debugowanie.

Dalsze kroki

Oficjalna dokumentacja Papera — najlepszy punkt wyjścia.
API: Player, World, Block, ItemStack, Inventory.
Schedulery: BukkitRunnable dla zadań cyklicznych.
Persystencja: prosty YAML, SQLite (HikariCP) lub MySQL przy większych projektach.
Plugin Messaging dla Velocity/BungeeCord.

Podsumowanie

W godzinę masz działający plugin: komendę /hello, powitanie nowych graczy i konfigurację. To fundament, na którym możesz zbudować każdy bardziej skomplikowany pomysł — własną ekonomię, system rang, custom mob arenę.

Najlepszy sposób na naukę to czytanie kodu istniejących pluginów open source (CoreProtect, EssentialsX, GriefPrevention). Większość z nich jest na GitHubie, a styl kodu jest zwykle wzorcowy.