Guida

Come creare un plugin Folia

Aggiornato il 18 ottobre 2026

Folia è un fork di Paper che divide il mondo in regioni e le fa avanzare su thread diversi, così i server grandi possono usare molti core della CPU. Non esiste più un unico thread principale, e questo rompe il normale scheduler di Bukkit. Un plugin Folia è un plugin Paper scritto per questo modello, e deve dichiararlo nel suo plugin.yml.

Un esempio con i dettagli sui tempi che servono a Folia.

Generalo con Codexe

Passo per passo

  1. 1.Verifica che Folia ti serva davvero

    Folia aiuta i server con tanti giocatori sparsi per il mondo. La maggior parte dei server usa Paper; molti plugin famosi non supportano Folia, quindi controlla prima quelli su cui fai affidamento.

  2. 2.Compila contro l'API di Folia

    Usa la dipendenza folia-api della tua versione dal repository di PaperMC, con scope provided, in un progetto Maven o Gradle.

  3. 3.Sostituisci lo scheduler di Bukkit

    Bukkit.getScheduler() non funziona su Folia. Usa lo scheduler di regione per il lavoro in un punto del mondo, lo scheduler di entità per il lavoro su un giocatore o un mob, lo scheduler della regione globale per i task che riguardano tutto il mondo e lo scheduler async per l'I/O.

  4. 4.Tocca le cose solo dalla loro regione

    Modifica un blocco o un'entità solo dal thread che li possiede. Usa teleportAsync invece di teleport, e pianifica il lavoro sulla regione di destinazione prima di modificarla.

  5. 5.Dichiara il supporto a Folia

    Aggiungi folia-supported: true a plugin.yml. Senza, Folia si rifiuta di caricare il plugin.

  6. 6.Provalo su un server Folia

    La compilazione dimostra che il codice si compila contro l'API di Folia, non che sia thread-safe. Fallo girare su un server Folia di prova con diversi giocatori in posti diversi.

I quattro scheduler

SchedulerSi ottiene conUsalo per
RegioneBukkit.getRegionScheduler()Lavoro in un punto del mondo: piazzare blocchi, far spawnare
Entitàentity.getScheduler()Lavoro su un giocatore o un mob, lo segue da una regione all'altra
Regione globaleBukkit.getGlobalRegionScheduler()Ora del mondo, meteo, cose non legate a un luogo
AsyncBukkit.getAsyncScheduler()Database, file, richieste web, mai il mondo

Cosa si rompe di solito

  • Task ripetuti per tutti i giocatori: un unico ciclo su tutti i giocatori online non funziona più; pianifica invece un task sullo scheduler di entità di ogni giocatore.
  • Teletrasporti e attese: "teletrasporta dopo 3 secondi" richiede lo scheduler di entità e teleportAsync.
  • Dati condivisi: mappe e contatori usati da più regioni devono essere thread-safe, per esempio collezioni concorrenti.
  • Dipendenze: una libreria che chiama lo scheduler di Bukkit lancia UnsupportedOperationException su Folia.

Un solo plugin per Paper e Folia

Gli scheduler di regione, di entità, globale e async fanno parte anche dell'API di Paper nelle versioni attuali, quindi un plugin che usa solo questi e dichiara folia-supported: true può girare sia su Paper sia su Folia. Spesso è l'obiettivo migliore: un solo .jar per ogni server.

Con Codexe

Scegli il tipo Folia. Il plugin generato pianifica il lavoro con gli scheduler di regione, di entità, della regione globale e async, dichiara folia-supported: true e si compila contro l'API di Folia con Maven. Viene compilato e controllato prima di essere dichiarato pronto.

Metti i dettagli sui tempi nella richiesta ("ogni minuto per ogni giocatore online", "teletrasporta dopo 3 secondi"): è lì che il codice per Folia cambia di più. Provalo subito non avvia ancora server Folia, quindi prova il .jar sul tuo server Folia.

Domande

I plugin Paper girano su Folia?

Solo se sono scritti per Folia e dichiarano folia-supported: true. Un normale plugin Paper che usa lo scheduler di Bukkit viene rifiutato o va in errore.

Un plugin Folia gira su Paper?

Sì, se usa solo API che ha anche Paper, e tra queste ci sono gli scheduler di Folia nelle versioni attuali di Paper.

Il mio plugin Folia lancia un'eccezione sullo scheduler

C'è del codice, spesso di una libreria, che usa ancora lo scheduler di Bukkit. Chiedi nella chat del progetto di spostarlo sullo scheduler di regione o di entità.

Crea un plugin Folia

Questo prompt si apre pronto da inviare:

“Un plugin per Folia 1.21.4 chiamato RTP: /rtp teletrasporta il giocatore in un punto sicuro casuale entro 5000 blocchi dopo un'attesa di 3 secondi che si annulla se si muove, usando lo scheduler di entità e teleportAsync, cooldown di 10 minuti per giocatore salvato in SQLite, folia-supported: true, raggio, cooldown e messaggi in config.yml.”

Generalo con Codexe
Come creare un plugin Folia (scheduler di regione) | Codexe