Eigenes Minecraft-Item erstellen: Name, Lore, Effekte und Rezept

Ein einzigartiges Item mit eigenem Namen, eigener Geschichte in der Lore, eigenem Schadenswert und eigenem Rezept: das ist der häufigste Wunsch auf jedem Server, der sich von den anderen abheben will. Das sind rund fünfzig Zeilen Code. Was kaputtgeht, ist fast nie die Logik, sondern die Version. Und 2026 liegt die Bruchstelle genau in der ersten Zeile, die du schreibst: beim Anzeigenamen.

Diese Anleitung deckt Name und Lore ab, Verzauberungen, Attribute, das Wiedererkennen des Items später in deinem Code und die Rezepte. Und sie zieht Zeile für Zeile die Grenze zwischen dem, was der Server allein schafft, und dem, was ein Ressourcenpaket auf jedem Rechner braucht.

Minecraft nutzt inzwischen eine Kalender-Versionierung. Die neueste Version ist 26.2, erschienen am 16. Juni 2026. Die öffentliche Erhebung von bStats über 62.948 Server erzählt allerdings eine ganz andere Geschichte als die Download-Seite:

• 1.21.11: 36,4 % aller Server, mit deutlichem Abstand die Nummer eins.
• 26.1.2: 14,9 %.
• 26.2: 7,4 %, also fünfmal weniger als 1.21.11 allein.
• 1.21.4: 7,2 %.

Die 1.21-Familie ist weiterhin in der Mehrheit, und Paper 26.2 hat nicht einmal ein stabiles Build. Das vernünftige Produktionsziel auf der Kalender-Seite heißt also 26.1.2. Diese Verteilung ist keine Randnotiz, sie entscheidet über deinen Code. Ein Schnipsel aus einem 1.21-Tutorial und ein Schnipsel aus einem 26.x-Tutorial können nicht beide richtig sein, und die Zahlen sagen dir, in welcher der beiden Welten deine Spieler wohnen.

Noch eine grundlegende Änderung: Minecraft ist seit 26.1 nicht mehr obfuskiert, und der Remapper von Paper ist verschwunden. Allgemein gute Nachricht, für Items aber vor allem eine praktische: du hast keinen Grund mehr, in die Server-Interna abzutauchen. Alles in diesem Artikel läuft über die öffentliche API, dokumentiert auf docs.papermc.io und jd.papermc.io.

Paper 26.x bringt Adventure 5 mit, und Adventure 5 hat API entfernt, die vorher nur als veraltet markiert war. Die Entfernungen betreffen vor allem Nachrichten und Text, den Spieler zu sehen bekommen. Anzeigename und Lore eines Items sind genau das: Text, den Spieler sehen. Deshalb fällt dieses scheinbar banale Thema als Erstes um. Code, der für 1.21 geschrieben wurde, kompiliert unter Umständen schon in Zeile drei nicht mehr.

// Der alte Weg: Zeichenketten und Legacy-Farbcodes.
// Das liefern dir die meisten Tutorials, die noch online stehen.
meta.setDisplayName(ChatColor.GOLD + "Klinge der Leere");
meta.setLore(Arrays.asList(ChatColor.GRAY + "In einer Luftblase geschmiedet"));

// Der Weg, der auf der 1.21-API UND auf Paper 26.x kompiliert: Component.
meta.displayName(Component.text("Klinge der Leere", NamedTextColor.GOLD)
        .decoration(TextDecoration.ITALIC, false));
meta.lore(List.of(
        Component.text("In einer Luftblase geschmiedet", NamedTextColor.GRAY)
                .decoration(TextDecoration.ITALIC, false)));

Der Teil, den alle vergessen, ist decoration(TextDecoration.ITALIC, false). Der Client stellt jeden eigenen Namen und jede Lore-Zeile standardmäßig kursiv dar. Ohne diesen Aufruf sieht deine legendäre Waffe aus wie ein am Amboss umbenanntes Standard-Item, und das fällt sofort auf. Es ist außerdem der einzige echte Vorteil des Component-Wegs gegenüber den alten Zeichenketten: mit einer Zeichenkette lässt sich Kursiv nicht abschalten.

Adventure steckt bereits in Paper, du musst also nichts mitliefern und nichts deklarieren. Und weil MiniMessage mitkommt, ist ein Farbverlauf eine Zeile statt einer Schleife über Farbcodes.

package fun.minax.artefakte;

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;
import net.kyori.adventure.text.format.TextDecoration;
import net.kyori.adventure.text.minimessage.MiniMessage;
import org.bukkit.Material;
import org.bukkit.NamespacedKey;
import org.bukkit.attribute.Attribute;
import org.bukkit.attribute.AttributeModifier;
import org.bukkit.enchantments.Enchantment;
import org.bukkit.inventory.EquipmentSlotGroup;
import org.bukkit.inventory.ItemFlag;
import org.bukkit.inventory.ItemStack;
import org.bukkit.inventory.meta.ItemMeta;
import org.bukkit.persistence.PersistentDataType;
import org.bukkit.plugin.Plugin;

import java.util.List;

public final class KlingeDerLeere {

    /** Schema-Version des Items. Bei jedem Balancing hochzaehlen. */
    public static final int SCHEMA = 2;
    public static final String ITEM_ID = "klinge_der_leere";

    private static final MiniMessage MM = MiniMessage.miniMessage();

    private final NamespacedKey idKey;
    private final NamespacedKey schemaKey;
    private final NamespacedKey schadenKey;

    public KlingeDerLeere(Plugin plugin) {
        this.idKey = new NamespacedKey(plugin, "item_id");
        this.schemaKey = new NamespacedKey(plugin, "item_schema");
        this.schadenKey = new NamespacedKey(plugin, "klinge_schaden");
    }

    public ItemStack erstellen() {
        ItemStack item = new ItemStack(Material.NETHERITE_SWORD);
        ItemMeta meta = item.getItemMeta();

        meta.displayName(MM.deserialize("<gradient:#8f5bff:#25d0ff>Klinge der Leere</gradient>")
                .decoration(TextDecoration.ITALIC, false));

        meta.lore(List.of(
                Component.text("In einer Luftblase geschmiedet.", NamedTextColor.GRAY)
                        .decoration(TextDecoration.ITALIC, false),
                Component.empty(),
                Component.text("Schaden  +12", NamedTextColor.DARK_AQUA)
                        .decoration(TextDecoration.ITALIC, false)));

        meta.addEnchant(Enchantment.SHARPNESS, 5, true);
        meta.setEnchantmentGlintOverride(Boolean.TRUE);

        meta.addAttributeModifier(
                Attribute.ATTACK_DAMAGE,
                new AttributeModifier(schadenKey, 12.0,
                        AttributeModifier.Operation.ADD_NUMBER,
                        EquipmentSlotGroup.MAINHAND));
        meta.addItemFlags(ItemFlag.HIDE_ATTRIBUTES);

        meta.getPersistentDataContainer().set(idKey, PersistentDataType.STRING, ITEM_ID);
        meta.getPersistentDataContainer().set(schemaKey, PersistentDataType.INTEGER, SCHEMA);

        item.setItemMeta(meta);
        return item;
    }
}

Eine Verzauberung über dem normalen Maximum setzt du mit addEnchant(enchantment, level, true), wobei das dritte Argument die Erlaubnis ist, die Grenzen des Spiels zu überschreiten. Nichts Schweres daran, bis auf den Namen der Konstante.

Verzauberungen sind zu Registry-Einträgen geworden, und die Konstanten der API sind den Kennungen aus dem Spiel gefolgt. Ein alter Schnipsel mit Enchantment.DAMAGE_ALL kompiliert auf einer aktuellen API nicht mehr, dort heißt der Eintrag Enchantment.SHARPNESS. Prüfe die Konstante immer im Javadoc deiner Zielversion, auf jd.papermc.io oder hub.spigotmc.org. Und wenn dein Code die nächste Umbenennung überleben soll, hole die Verzauberung über ihren Schlüssel statt über ein statisches Feld:

// Robust gegen Umbenennungen: der Vanilla-Schluessel selbst bleibt gleich.
Enchantment schaerfe = Registry.ENCHANTMENT.get(NamespacedKey.minecraft("sharpness"));
if (schaerfe != null) {
    meta.addEnchant(schaerfe, 5, true);
}

Für den Glanz allein, ohne echte Verzauberung, reicht setEnchantmentGlintOverride(true). Das ist deutlich sauberer als der alte Trick mit einer Dummy-Verzauberung hinter einem ItemFlag, und es hat keine Nebenwirkung. Umgekehrt: wenn du die echte Verzauberung behalten, aber ihre Zeile im Tooltip verstecken willst, um den Text selbst zu formulieren, bleibt ItemFlag.HIDE_ENCHANTS die richtige Antwort. In beiden Fällen ohne Ressourcenpaket.

Ein Attribut ist ein Wert, den das Spiel schon kennt: Angriffsschaden, Bewegungsgeschwindigkeit, Rüstung, Reichweite. Du änderst ihn mit einem AttributeModifier, der an eine Slot-Gruppe gebunden ist. Das verhindert den Klassiker, dass ein Schwert seine Boni auch noch aus dem Rucksack heraus verteilt.

Zwei Fallen. Die erste ist dieselbe wie bei den Verzauberungen: die Attribut-Konstanten haben beim Umzug in eine Registry ihr historisches Präfix verloren, ein Schnipsel mit Attribute.GENERIC_ATTACK_DAMAGE kompiliert also dort nicht, wo die API Attribute.ATTACK_DAMAGE erwartet. Die zweite ist der Konstruktor: die alte Form mit UUID und freiem Namen gilt als veraltet, aktuell sind ein NamespacedKey und eine EquipmentSlotGroup. Gib jedem Modifikator einen eigenen Schlüssel, sonst bekommst du ihn beim nächsten Balancing nicht mehr sauber heraus.

Fast alle Hobby-Plugins für eigene Items haben denselben Fehler: sie erkennen das Item am Anzeigenamen. Das ist doppelt fragil. Spieler können jedes Schwert am Amboss umbenennen, und noch wichtiger: sobald du selbst einen Tippfehler im Namen behebst, wird kein bereits vorhandenes Exemplar mehr erkannt. Du hast gerade mit einer Textkorrektur die Inventare deiner Spieler zerlegt.

Die richtige Antwort ist der PersistentDataContainer des ItemMeta: typisierte Schlüssel mit dem Namensraum deines Plugins, gespeichert am Item selbst. Sie überleben Kisten, Shulker-Kisten, das Fallenlassen und den Neustart des Servers, und kein Spieler sieht sie.

package fun.minax.artefakte;

import org.bukkit.NamespacedKey;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerInteractEvent;
import org.bukkit.inventory.ItemStack;
import org.bukkit.persistence.PersistentDataContainer;
import org.bukkit.persistence.PersistentDataType;
import org.bukkit.plugin.Plugin;

public final class KlingeListener implements Listener {

    private final NamespacedKey idKey;
    private final NamespacedKey schemaKey;

    public KlingeListener(Plugin plugin) {
        this.idKey = new NamespacedKey(plugin, "item_id");
        this.schemaKey = new NamespacedKey(plugin, "item_schema");
    }

    @EventHandler
    public void onInteract(PlayerInteractEvent event) {
        ItemStack item = event.getItem();
        if (item == null || !item.hasItemMeta()) {
            return;
        }

        PersistentDataContainer pdc = item.getItemMeta().getPersistentDataContainer();
        if (!KlingeDerLeere.ITEM_ID.equals(pdc.get(idKey, PersistentDataType.STRING))) {
            return;
        }

        Integer schema = pdc.get(schemaKey, PersistentDataType.INTEGER);
        if (schema == null || schema < KlingeDerLeere.SCHEMA) {
            // Exemplar aus einer aelteren Generation: direkt hochziehen, statt zwei
            // verschiedene Balancing-Staende auf demselben Server laufen zu lassen.
            migrieren(item);
            return;
        }

        effektAusloesen(event);
    }

    private void migrieren(ItemStack alt) {
        // Lore, Attribute und aktuelles Schema auf das vorhandene Exemplar schreiben.
    }

    private void effektAusloesen(PlayerInteractEvent event) {
        // Der Effekt, der nur zu diesem Item gehoert.
    }
}

Der Schlüssel item_schema ist das Detail, das fast niemand schreibt, und genau das wird dich retten. Ein halbes Jahr nach dem Start willst du den Schaden senken. Die längst hergestellten Exemplare schlafen in Kisten, mit dem alten Modifikator festgeschrieben. Ohne Versionsnummer am Item kannst du sie nicht von den neuen unterscheiden, und dein Balancing greift nur bei neuen Spielern. Mit Versionsnummer ziehst du sie beim ersten Klick hoch.

Meine Position dazu ist klar. Solange deine Frage lautet „ist das mein Item, und in welcher Version“, reicht der Container und du brauchst überhaupt keine Datenbank. Eine Datenbank ist genau ab dem Moment das bessere Werkzeug, in dem sich die Frage dreht: „wer hält die drei einzigartigen Exemplare, die ich verteilt habe“. Dafür brauchst du einen Index. Der JDBC-Treiber für SQLite ist bereits bei Paper dabei, kostet dich also keine mitgelieferte Abhängigkeit. HikariCP ist nicht dabei: wenn du einen Verbindungspool willst, deklariere ihn im Block libraries: deiner plugin.yml und lass ihn vom Server herunterladen, statt ihn in dein .jar zu packen. Und in jedem Fall: niemals Datenbankzugriffe auf dem Haupt-Thread, sonst bricht dir der TPS weg.

Wenn du auch Folia bedienen willst, denk daran, dass die Regionen der Welt auf mehreren Threads laufen: ein Plugin, das von einem einzigen Haupt-Thread ausgeht, verursacht Abstürze. Alles, was du rund um das Item planst, läuft über den RegionScheduler und nicht über einen globalen Scheduler.

Ein geformtes Rezept registrierst du beim Start, unter einem Schlüssel, der zu deinem Plugin gehört. Der Ergebnis-Stapel, den du übergibst, behält sein ItemMeta. Das Item, das ein Spieler herstellt, trägt also deine gespeicherten Daten, deine Lore und deine Attribute.

NamespacedKey rezeptKey = new NamespacedKey(this, "klinge_der_leere");

ShapedRecipe rezept = new ShapedRecipe(rezeptKey, new KlingeDerLeere(this).erstellen());
rezept.shape(" B ", " B ", " S ");
rezept.setIngredient('B', Material.NETHERITE_INGOT);
rezept.setIngredient('S', Material.BREEZE_ROD);

// Idempotent: ohne das Entfernen scheitert das zweite Registrieren desselben Schluessels.
Bukkit.removeRecipe(rezeptKey);
Bukkit.addRecipe(rezept);

Drei Punkte, die in der Dokumentation zu kurz kommen. Erstens das Entfernen vor dem Hinzufügen: ohne das ist eine zweite Registrierung desselben Schlüssels ein Problem, und genau das passiert, wenn jemand /reload statt eines Neustarts benutzt. Zweitens die Freischaltung: das Rezept funktioniert für jeden, der die Form kennt, im Rezeptbuch erscheint es aber erst nach einem discoverRecipe auf dem Spieler. Drittens die eigentliche Grenze.

Eine ShapedRecipe denkt in Material, nicht in deinen gespeicherten Daten. Sie allein kann also nicht verlangen, dass eine Zutat dein eigenes Item ist. Der verlässliche Weg: das Rezept auf dem Grundmaterial registrieren und die Markierung beim Herstellen prüfen.

@EventHandler
public void onPrepare(PrepareItemCraftEvent event) {
    Recipe rezept = event.getRecipe();
    if (!(rezept instanceof Keyed keyed) || !rezeptKey.equals(keyed.getKey())) {
        return;
    }

    boolean fragmentVorhanden = false;
    for (ItemStack slot : event.getInventory().getMatrix()) {
        if (slot == null || !slot.hasItemMeta()) {
            continue;
        }
        String id = slot.getItemMeta().getPersistentDataContainer()
                .get(idKey, PersistentDataType.STRING);
        if ("fragment_der_leere".equals(id)) {
            fragmentVorhanden = true;
        }
    }

    if (!fragmentVorhanden) {
        event.getInventory().setResult(null);
    }
}

Das ist die häufigste Frage überhaupt, und die Antwort ist freundlicher als die meisten denken. Fast alles läuft auf dem Server.

Bei einer Textur besteht der Mechanismus aus zwei Hälften, und du kontrollierst nur eine. Auf dem Server setzt du einen Wert für eigene Modelldaten am Item. Auf dem Client muss ein Ressourcenpaket diesen Wert einem Modell zuordnen. Der harte Teil: du kannst den Wert setzen, ohne Paket passiert damit überhaupt nichts. Wer den Download ablehnt, sieht ein normales Netherit-Schwert mit deinem Namen und deiner Lore darauf. Das Format der Item-Komponenten ist auf minecraft.wiki beschrieben, die Auslieferung des Pakets stellst du in server.properties oder pro Spieler aus deinem Plugin ein.

• Kursive Lore. Du hast den Aufruf vergessen, der die Dekoration abschaltet. In drei Sekunden erkannt, in einer Zeile behoben.
• Der Schnipsel aus einem alten Tutorial. Attribut-Konstanten mit Präfix, Verzauberungsnamen von vor der Registry, Text-Aufrufe, die Adventure 5 entfernt hat. Drei Familien von Kompilierfehlern, ein Gegenmittel: das Javadoc deiner Zielversion.
• Erkennung über den Namen. Hält eine Woche, dann benennt ein Spieler ein Schwert am Amboss um oder du behebst einen Tippfehler.
• Eine Tabelle mit der Spieler-UUID als Schlüssel. Im Offline-Modus, also auf 75,1 % der Server, wird diese UUID aus dem Namen abgeleitet. Eine Umbenennung und deine Zeilen sind verwaist.
• Das doppelt registrierte Rezept. Ein /reload und der Schlüssel existiert schon. Erst entfernen, dann hinzufügen, und neu starten statt neu laden.
• Die Textur, die nur bei dir funktioniert. Dein Paket ist lokal installiert, und du vergisst, dass es niemand anderem ausgeliefert wird.
• Datenbankarbeit auf dem Haupt-Thread oder ein globaler Scheduler auf Folia. Das Erste drückt den TPS, das Zweite lässt den Server abstürzen.

Unter 50 gleichzeitigen Spielern: ein Plugin, alles im PersistentDataContainer, keine Datenbank, kein Pflicht-Ressourcenpaket. Gebaut gegen die Paper-1.21.11-API mit Ziel Java 21, sämtlicher Text über Adventure Component. Dieses .jar läuft auf den 36,4 % des Bestands mit 1.21.11 genauso wie auf den 14,9 % mit 26.1.2, und du musst es lange nicht neu bauen.

Darüber, oder sobald einzigartige Items Wert haben: nimm einen SQLite-Index dazu, dessen Treiber schon in Paper steckt, mit einem Schlüssel, der vom Item kommt und nie vom Spieler, und mit allen Zugriffen weg vom Haupt-Thread. In dieser Größe kannst du das Ressourcenpaket auch zur Pflicht machen: Spieler eines etablierten Servers akzeptieren den Download, Spieler eines unbekannten nicht.

Ziel 26.2 exklusiv nur dann, wenn: der Server dir gehört, du bereit bist, bei jedem Build neu zu kompilieren, und du das .jar nicht verteilst. Paper 26.2 hat kein stabiles Build, und 26.2 sind 7,4 % des Bestands. Das ist kein Verteilungsziel, das ist ein Spielplatz.

Weiterlesen: wenn dein Plugin nicht startet, hilft die Fehlersuche, und wenn du noch zwischen einem Skript und einem echten .jar schwankst, lies Skript oder kompiliertes Plugin.

Ähnliche Artikel

Fehlersuche

Mein Plugin lädt nicht: die Fehlersuche

Lesen

Vergleich

Skript oder kompiliertes Plugin?

Lesen

Ideen

Plugin-Ideen für Minecraft

Lesen