Anleitung

So erstellst du ein Folia-Plugin

Aktualisiert am 18. Oktober 2026

Folia ist ein Fork von Paper, der die Welt in Regionen aufteilt und sie auf verschiedenen Threads tickt, damit große Server viele CPU-Kerne nutzen können. Es gibt keinen einzelnen Hauptthread mehr, und das bricht den üblichen Bukkit-Scheduler. Ein Folia-Plugin ist ein Paper-Plugin, das für dieses Modell geschrieben ist, und es muss das in seiner plugin.yml angeben.

Ein Beispiel mit den Timing-Details, die Folia braucht.

Mit Codexe erstellen

Schritt für Schritt

  1. 1.Prüfe, ob du Folia brauchst

    Folia hilft Servern mit vielen Spielern, die über die Welt verteilt sind. Die meisten Server laufen mit Paper; viele beliebte Plugins unterstützen Folia nicht, also prüfe zuerst die, auf die du angewiesen bist.

  2. 2.Gegen die Folia-API bauen

    Nutze die Abhängigkeit folia-api für deine Version aus dem PaperMC-Repository mit dem Scope provided, in einem Maven- oder Gradle-Projekt.

  3. 3.Ersetze den Bukkit-Scheduler

    Bukkit.getScheduler() funktioniert auf Folia nicht. Nutze den Region-Scheduler für Arbeit an einem Ort, den Entity-Scheduler für Arbeit an einem Spieler oder Mob, den Global-Region-Scheduler für weltweite Tasks und den Async-Scheduler für I/O.

  4. 4.Ändere Dinge nur aus ihrer eigenen Region

    Ändere einen Block oder eine Entity nur auf dem Thread, dem sie gehört. Nutze teleportAsync statt teleport und plane die Arbeit in der Region des Ziels ein, bevor du es änderst.

  5. 5.Folia-Unterstützung angeben

    Füge folia-supported: true zur plugin.yml hinzu. Ohne diese Angabe weigert sich Folia, das Plugin zu laden.

  6. 6.Auf einem Folia-Server testen

    Das Kompilieren beweist, dass der Code gegen die Folia-API baut, nicht dass er threadsicher ist. Lass ihn auf einem Folia-Testserver mit mehreren Spielern an verschiedenen Orten laufen.

Die vier Scheduler

SchedulerAbrufen mitWofür
RegionBukkit.getRegionScheduler()Arbeit an einem Ort in der Welt: Blöcke setzen, Spawnen
Entityentity.getScheduler()Arbeit an einem Spieler oder Mob, folgt ihm über Regionen hinweg
Global RegionBukkit.getGlobalRegionScheduler()Weltzeit, Wetter, Dinge, die an keinen Ort gebunden sind
AsyncBukkit.getAsyncScheduler()Datenbank, Dateien, Webanfragen, nie die Welt

Was meistens kaputtgeht

  • Wiederholte Tasks für alle Spieler: Eine einzige Schleife über alle Spieler online funktioniert nicht mehr; plane stattdessen einen Task im Entity-Scheduler jedes Spielers ein.
  • Teleports und Aufwärmzeiten: „Teleport nach 3 Sekunden“ braucht den Entity-Scheduler und teleportAsync.
  • Gemeinsame Daten: Maps und Zähler, die aus mehreren Regionen genutzt werden, müssen threadsicher sein, zum Beispiel Concurrent Collections.
  • Abhängigkeiten: Eine Bibliothek, die den Bukkit-Scheduler aufruft, wirft auf Folia eine UnsupportedOperationException.

Ein Plugin für Paper und Folia

Die Region-, Entity-, Global- und Async-Scheduler gehören in aktuellen Versionen auch zur Paper-API. Ein Plugin, das nur sie nutzt und folia-supported: true angibt, läuft daher auf Paper und Folia. Das ist oft das beste Ziel: eine .jar für jeden Server.

Mit Codexe

Wähle den Typ Folia. Das generierte Plugin plant Arbeit mit den Region-, Entity-, Global-Region- und Async-Schedulern ein, gibt folia-supported: true an und baut mit Maven gegen die Folia-API. Es wird kompiliert und geprüft, bevor es als Ready gilt.

Schreib Details zum Timing in die Anfrage („jede Minute für jeden Spieler online“, „Teleport nach 3 Sekunden“): Genau dort unterscheidet sich Folia-Code am stärksten. Jetzt testen startet noch keine Folia-Server, also teste die .jar auf deinem eigenen Folia-Server.

Fragen

Laufen Paper-Plugins auf Folia?

Nur wenn sie dafür geschrieben sind und folia-supported: true angeben. Ein normales Paper-Plugin, das den Bukkit-Scheduler nutzt, wird abgelehnt oder schlägt fehl.

Läuft ein Folia-Plugin auf Paper?

Ja, wenn es nur APIs nutzt, die Paper auch hat, und dazu gehören in aktuellen Paper-Versionen die Folia-Scheduler.

Mein Folia-Plugin wirft eine Exception zum Scheduler

Irgendein Code, oft aus einer Bibliothek, nutzt noch den Bukkit-Scheduler. Bitte im Projekt-Chat darum, ihn auf den Region- oder Entity-Scheduler umzustellen.

Erstelle ein Folia-Plugin

Dieser Prompt öffnet sich versandfertig:

“Ein Folia-1.21.4-Plugin namens RTP: /rtp teleportiert den Spieler nach einer Aufwärmzeit von 3 Sekunden, die bei Bewegung abbricht, an einen zufälligen sicheren Ort im Umkreis von 5000 Blöcken, mit dem Entity-Scheduler und teleportAsync, 10 Minuten Cooldown pro Spieler in SQLite gespeichert, folia-supported: true, Radius, Cooldown und Nachrichten in der config.yml.”

Mit Codexe erstellen
So erstellst du ein Folia-Plugin (Region-Scheduler) | Codexe