Guía

Cómo crear un plugin para Folia

Actualizado el 18 de octubre de 2026

Folia es un fork de Paper que divide el mundo en regiones y procesa sus ticks en hilos distintos, para que los servidores grandes puedan usar muchos núcleos de CPU. Ya no existe un único hilo principal, y eso rompe el scheduler habitual de Bukkit. Un plugin para Folia es un plugin de Paper escrito para ese modelo, y debe indicarlo en su plugin.yml.

Un ejemplo con los detalles de tiempos que Folia necesita.

Genera esto con Codexe

Paso a paso

  1. 1.Comprueba que necesitas Folia

    Folia ayuda a los servidores con muchos jugadores repartidos por el mundo. La mayoría de los servidores usan Paper; muchos plugins populares no son compatibles con Folia, así que revisa primero los que necesitas.

  2. 2.Compila con la API de Folia

    Usa la dependencia folia-api de tu versión desde el repositorio de PaperMC, con scope provided, en un proyecto Maven o Gradle.

  3. 3.Sustituye el scheduler de Bukkit

    Bukkit.getScheduler() no funciona en Folia. Usa el scheduler de región para trabajo en una ubicación, el scheduler de entidad para trabajo sobre un jugador o un mob, el scheduler de región global para tareas de todo el mundo y el scheduler asíncrono para E/S.

  4. 4.Toca cada cosa solo desde su propia región

    Cambia un bloque o una entidad solo en el hilo al que pertenece. Usa teleportAsync en lugar de teleport y programa la tarea en la región del destino antes de cambiarlo.

  5. 5.Declara la compatibilidad con Folia

    Añade folia-supported: true a plugin.yml. Sin eso, Folia se niega a cargar el plugin.

  6. 6.Pruébalo en un servidor Folia

    Que compile demuestra que el código se construye con la API de Folia, no que sea seguro entre hilos. Ejecútalo en un servidor Folia de prueba con varios jugadores en sitios distintos.

Los cuatro schedulers

SchedulerCómo obtenerloPara qué usarlo
RegiónBukkit.getRegionScheduler()Trabajo en una ubicación del mundo: colocar bloques, generar entidades
Entidadentity.getScheduler()Trabajo sobre un jugador o un mob; lo sigue entre regiones
Región globalBukkit.getGlobalRegionScheduler()Hora del mundo, clima, cosas no ligadas a una ubicación
AsíncronoBukkit.getAsyncScheduler()Base de datos, archivos, peticiones web; nunca el mundo

Qué suele romperse

  • Tareas repetidas para todos los jugadores: un único bucle sobre todos los jugadores conectados ya no funciona; programa en su lugar una tarea en el scheduler de entidad de cada jugador.
  • Teletransportes y esperas: «teletransportar tras 3 segundos» necesita el scheduler de entidad y teleportAsync.
  • Datos compartidos: los mapas y contadores usados desde varias regiones deben ser seguros entre hilos, por ejemplo colecciones concurrentes.
  • Dependencias: una librería que llama al scheduler de Bukkit lanza UnsupportedOperationException en Folia.

Un solo plugin para Paper y Folia

Los schedulers de región, de entidad, global y asíncrono también forman parte de la API de Paper en las versiones actuales, así que un plugin que use solo esos y declare folia-supported: true puede funcionar tanto en Paper como en Folia. Suele ser el mejor objetivo: un solo .jar para todos los servidores.

Con Codexe

Elige el tipo Folia. El plugin generado programa el trabajo con los schedulers de región, de entidad, de región global y asíncrono, declara folia-supported: true y se compila con la API de Folia usando Maven. Se compila y se comprueba antes de estar Listo.

Pon los detalles de tiempos en la petición («cada minuto para cada jugador conectado», «teletransportar tras 3 segundos»): es donde más se diferencia el código de Folia. Pruébalo ahora todavía no ejecuta servidores Folia, así que prueba el .jar en tu propio servidor Folia.

Preguntas

¿Los plugins de Paper funcionan en Folia?

Solo si están escritos para Folia y declaran folia-supported: true. Un plugin normal de Paper que usa el scheduler de Bukkit se rechaza o falla.

¿Un plugin para Folia funciona en Paper?

Sí, cuando usa solo APIs que Paper también tiene, lo que incluye los schedulers de Folia en las versiones actuales de Paper.

Mi plugin para Folia lanza una excepción sobre el scheduler

Alguna parte del código, a menudo de una librería, sigue usando el scheduler de Bukkit. Pide en el chat del proyecto que lo pase al scheduler de región o de entidad.

Crea un plugin para Folia

Este prompt se abre listo para enviar:

“Un plugin para Folia 1.21.4 llamado RTP: /rtp teletransporta al jugador a una ubicación segura aleatoria a menos de 5000 bloques tras una espera de 3 segundos que se cancela al moverse, usando el scheduler de entidad y teleportAsync, un tiempo de espera de 10 minutos por jugador guardado en SQLite, folia-supported: true, radio, tiempo de espera y mensajes en config.yml.”

Genera esto con Codexe
Cómo crear un plugin para Folia (schedulers de región) | Codexe