Guia

Como criar um plugin para Folia

Atualizado em 18 de outubro de 2026

O Folia é um fork do Paper que divide o mundo em regiões e processa os ticks delas em threads diferentes, para que servidores grandes possam usar muitos núcleos de CPU. Não existe mais uma única thread principal, e isso quebra o scheduler comum do Bukkit. Um plugin para Folia é um plugin para Paper escrito para esse modelo, e ele precisa declarar isso no plugin.yml.

Um exemplo com os detalhes de tempo de que o Folia precisa.

Gere isto com o Codexe

Passo a passo

  1. 1.Confirme que você precisa do Folia

    O Folia ajuda servidores com muitos jogadores espalhados pelo mundo. A maioria dos servidores roda Paper; muitos plugins populares não suportam o Folia, então confira primeiro os que você usa.

  2. 2.Compile com a API do Folia

    Use a dependência folia-api da sua versão do repositório do PaperMC, com escopo provided, em um projeto Maven ou Gradle.

  3. 3.Substitua o scheduler do Bukkit

    O Bukkit.getScheduler() não funciona no Folia. Use o scheduler de região para tarefas em um local, o scheduler de entidade para tarefas em um jogador ou mob, o scheduler da região global para tarefas do mundo todo e o scheduler assíncrono para I/O.

  4. 4.Mexa nas coisas só a partir da região delas

    Altere um bloco ou uma entidade só na thread que é dona dele. Use teleportAsync em vez de teleport e agende na região do alvo antes de alterá-lo.

  5. 5.Declare o suporte ao Folia

    Adicione folia-supported: true ao plugin.yml. Sem isso, o Folia se recusa a carregar o plugin.

  6. 6.Teste em um servidor Folia

    Compilar prova que o código compila com a API do Folia, não que ele é thread safe. Rode em um servidor Folia de teste com vários jogadores em lugares diferentes.

Os quatro schedulers

SchedulerComo obterUse para
RegiãoBukkit.getRegionScheduler()Tarefas em um local do mundo: colocar blocos, spawnar
Entidadeentity.getScheduler()Tarefas em um jogador ou mob, acompanha ele entre as regiões
Região globalBukkit.getGlobalRegionScheduler()Horário do mundo, clima, coisas não ligadas a um local
AssíncronoBukkit.getAsyncScheduler()Banco de dados, arquivos, requisições web, nunca o mundo

O que costuma quebrar

  • Tarefas repetidas para todos os jogadores: um único loop sobre todos os jogadores online não funciona mais; agende uma tarefa no scheduler de entidade de cada jogador.
  • Teleportes e esperas: "teleportar depois de 3 segundos" precisa do scheduler de entidade e do teleportAsync.
  • Dados compartilhados: mapas e contadores usados por várias regiões precisam ser thread safe, por exemplo coleções concorrentes.
  • Dependências: uma biblioteca que chama o scheduler do Bukkit lança UnsupportedOperationException no Folia.

Um plugin para Paper e Folia

Os schedulers de região, de entidade, global e assíncrono também fazem parte da API do Paper nas versões atuais, então um plugin que usa só eles e declara folia-supported: true pode rodar tanto no Paper quanto no Folia. Muitas vezes esse é o melhor alvo: um .jar para todos os servidores.

Com o Codexe

Escolha o tipo Folia. O plugin gerado agenda as tarefas com os schedulers de região, de entidade, da região global e assíncrono, declara folia-supported: true e compila com a API do Folia usando Maven. Ele é compilado e verificado antes de ficar Pronto.

Coloque os detalhes de tempo no pedido ("a cada minuto para cada jogador online", "teleportar depois de 3 segundos"): é aí que o código para Folia mais muda. O Teste agora ainda não roda servidores Folia, então teste o .jar no seu próprio servidor Folia.

Perguntas

Plugins para Paper rodam no Folia?

Só se forem escritos para ele e declararem folia-supported: true. Um plugin comum para Paper que usa o scheduler do Bukkit é recusado ou falha.

Um plugin para Folia roda no Paper?

Sim, quando usa só APIs que o Paper também tem, o que inclui os schedulers do Folia nas versões atuais do Paper.

O meu plugin para Folia lança uma exceção sobre o scheduler

Algum código, muitas vezes de uma biblioteca, ainda usa o scheduler do Bukkit. Peça no chat do projeto para movê-lo para o scheduler de região ou de entidade.

Crie um plugin para Folia

Este prompt abre pronto para enviar:

“Um plugin para Folia 1.21.4 chamado RTP: /rtp teleporta o jogador para um local seguro aleatório em um raio de 5000 blocos após uma espera de 3 segundos que é cancelada ao se mexer, usando o scheduler de entidade e teleportAsync, cooldown de 10 minutos por jogador salvo em SQLite, folia-supported: true, raio, cooldown e mensagens no config.yml.”

Gere isto com o Codexe
Como criar um plugin para Folia (region schedulers) | Codexe