Servidor Minecraft com lag: encontrar e resolver as causas

"O servidor está com lag" é a mensagem mais frequente no sistema de tickets de qualquer operador de gameservers e, ao mesmo tempo, a mais inútil. Por trás desta única frase escondem-se pelo menos três problemas técnicos completamente diferentes, que nada têm a ver uns com os outros e que se resolvem com meios igualmente distintos. Quem adivinha em vez de medir passa semanas a mexer na view-distance e nas flags do Java, enquanto a verdadeira causa é uma cadeia de hoppers descontrolada na cave de um jogador.

Este artigo segue o caminho pela ordem em que ele funciona: primeiro a distinção, depois a medição, depois a causa e só então a contramedida. E, no fim, a pergunta que a maioria dos guias deixa de fora: como é que sabe, afinal, que o problema está mesmo resolvido.

Dois problemas que se sentem exatamente iguais

Existem dois tipos radicalmente diferentes de engasgos, mais um terceiro caso que nada tem a ver com o servidor.

Lag do servidor significa: o servidor já não consegue cumprir os seus 20 passos de cálculo por segundo. O próprio mundo passa a correr mais devagar. Os mobs ficam parados ou aos saltos, os fornos demoram mais, os blocos partidos voltam a aparecer, os suportes de armadura mexem-se com atraso.

Lag de rede significa: o servidor calcula sem problemas, mas os pacotes entre o jogador e o servidor demoram demasiado tempo ou perdem-se. O jogador é puxado para trás enquanto corre (rubberbanding), os golpes não acertam, o chat chega atrasado, mas os mobs à volta mexem-se com toda a fluidez.

Lag do cliente é o terceiro caso: poucas imagens por segundo no computador do jogador, normalmente por causa de shaders, de uma distância de visualização elevada no cliente ou de pouca memória atribuída. Isso é invisível no servidor e também não é aí que se resolve.

A regra que quase sempre se confirma: se afeta todos ao mesmo tempo, é o servidor. Se afeta apenas alguns, é a ligação. Há um caso especial que quebra esta regra: um servidor completamente sobrecarregado também confirma os pacotes de rede tarde demais e produz, por acréscimo, pings mais altos. É por isso que se medem sempre as duas coisas.

O primeiro teste demora 60 segundos

Ligue-se ao servidor por SSH e abra a consola do servidor. Se ainda não tem o serviço a correr de forma limpa em segundo plano, ajuda o artigo sobre iniciar o servidor Minecraft automaticamente.

Em Paper, Purpur e Folia a partir da 1.21, o profiler Spark já vem incluído no servidor e não é preciso instalar nada. No jogo ou na consola:

spark tps
spark health --memory --network

A saída de spark tps mostra quatro janelas temporais (5 segundos, 1, 5 e 15 minutos), bem como as durações dos ticks em forma de mínimo, mediana, percentil 95 e máximo.

Em Vanilla puro, sem plugins, existe o /tick query. O comando devolve a taxa alvo e o tempo médio de tick. Além disso, F3 mais 2 mostra aos operadores um gráfico de ticks.

A consola costuma denunciar o problema por si própria. Estas são as linhas que os leitores procuram normalmente, tal e qual:

[Server thread/WARN]: Can't keep up! Is the server overloaded? Running 2123ms or 42 ticks behind
[Server thread/WARN]: Can't keep up! Did the system time change, or is the server overloaded? Running 2340ms behind

Esta mensagem significa apenas isto: o servidor precisou de bastante mais do que os 50 milissegundos permitidos para um passo de cálculo e tem de saltar ticks. Uma mensagem isolada depois de um reinício ou de uma geração de mundo é normal. Uma de poucos em poucos minutos é um problema a sério.

Em paralelo, verifique o lado do sistema. O mpstat não faz parte do equipamento de base em nenhum dos sistemas testados: vem do pacote sysstat e tem de ser instalado uma vez:

apt-get install -y sysstat procps
uptime
free -h
mpstat 1 3

Em AlmaLinux, Rocky Linux e Oracle Linux, a primeira linha passa a ser dnf -y install sysstat procps-ng iproute, porque aí o pacote com free, uptime, top e vmstat não se chama procps, mas sim procps-ng.

Na saída de mpstat interessa sobretudo a coluna %steal. Valores permanentemente acima de 5 por cento significam que a máquina virtual está à espera de tempo de CPU que outro convidado está a ocupar. Nesse caso não é um problema do Minecraft, mas sim um problema de capacidade do hardware subjacente.

Uma ressalva sobre estes três comandos: num servidor próprio ou num VPS mostram exatamente aquilo que quer saber. Se, pelo contrário, o seu servidor correr dentro de um container, por exemplo num gamepanel como o Pterodactyl, então free, uptime, vmstat e mpstat reportam os valores do sistema anfitrião e não os da sua instância. Vê carga alheia e memória alheia. Nesse caso, confie na indicação do painel e no spark health.

Ler corretamente os valores de TPS e MSPT

Um servidor Minecraft calcula 20 ticks por segundo, portanto cada tick tem um orçamento de 50 milissegundos. O MSPT (milissegundos por tick) é o valor mais revelador, porque mostra os problemas antes de os TPS sequer começarem a cair. Um servidor com 20,0 TPS e 46 ms de MSPT corre no limite absoluto e cede assim que o próximo jogador entra numa zona nova.

• MSPT abaixo de 30 ms: saudável, com reserva disponível.
• MSPT entre 30 e 45 ms: apertado, mas jogável. É agora que deve agir.
• MSPT acima de 50 ms: os TPS caem inevitavelmente e os jogadores notam.

Mais importante do que a média é a distribuição. Uma mediana de 18 ms com um máximo de 900 ms significa picos: acontecimentos caros e pontuais, como a gravação automática, a geração de chunks ou uma tarefa de plugin ao minuto. Já uma mediana de 60 ms significa carga permanente, ou seja, demasiado conteúdo a ser ticado para a capacidade de cálculo disponível. As contramedidas são completamente diferentes.

Um ponto que os consultores de hardware gostam de ignorar: o tick principal do Minecraft corre numa única thread. O carregamento de chunks e a rede estão separados, a simulação do mundo propriamente dita não. Um servidor com 32 núcleos e fraco desempenho por núcleo é mais lento para Minecraft do que um com 8 núcleos rápidos. Mais núcleos só ajudam quando correm várias instâncias de servidor na mesma máquina.

Spark: da suspeita à prova

O Timings, a ferramenta padrão durante anos, está no Paper em modo inativo desde a série 1.21 e já não fornece dados aproveitáveis. Quem hoje ainda publica links de Timings não está a medir nada. O sucessor chama-se Spark e vem integrado no Paper; para Fabric, Forge e NeoForge existe como mod, e para Velocity e BungeeCord numa variante própria.

O procedimento decisivo: faça o profiling enquanto o problema está a acontecer. Um perfil do servidor vazio às três da manhã não vale nada.

spark profiler start --timeout 300
spark profiler stop

Para os picos que só surgem de vez em quando, filtram-se especificamente os ticks maus:

spark profiler start --only-ticks-over 60 --timeout 600

Assim só são registados os ticks que demoraram mais de 60 milissegundos. São exatamente esses que os jogadores sentem. O resto é ignorado e não vem poluir a imagem.

Ao ler o flame graph, os principiantes cometem quase sempre o mesmo erro: olham para a ramificação mais profunda. O correto é olhar para a largura das barras logo abaixo do tick do servidor. Uma entrada com 3 por cento é irrelevante, mesmo que desça cem níveis. Regra prática: um único plugin com mais de 15 por cento do tempo de tick já é um candidato. Entradas muito largas à volta de entidades de bloco apontam para redstone e hoppers, entradas largas à volta do carregamento de chunks apontam para a geração de mundo.

Uma nota sobre confidencialidade: o relatório carregado fica publicamente acessível através do seu link e contém informações do sistema, caminhos, parâmetros de arranque e a lista completa de plugins. Partilhe o link apenas com pessoas a quem confiaria essas informações. Com --save-to-file, o perfil fica local.

Os culpados do costume

Redstone e farms

Os hoppers são de longe os blocos mais caros do jogo, porque cada um deles verifica em cada tick se há alguma coisa por cima. Um sistema de triagem com 400 hoppers custa mais tempo de cálculo do que cem mobs. A isso juntam-se os relógios de observers, que continuam a trabalhar mesmo quando não está ninguém por perto, desde que o chunk seja simulado. Se o Spark passar um tempo suspeito em entidades de bloco, procure exatamente por instalações destas.

Entidades

No Paper, o comando /paper entity list lista as entidades por mundo e por tipo, com as coordenadas do chunk. É o caminho mais rápido até à zona problemática. Achados típicos: vários milhares de pilhas de itens numa mob farm, um cercado de criação com 300 vacas, uma zona esquecida cheia de flechas caídas no chão.

Contramedidas sensatas em spigot.yml: baixar a entity-activation-range para animais e monstros (por exemplo, animais de 32 para 16, monstros de 32 para 24) e subir ligeiramente o merge-radius para itens e esferas de experiência, para que existam menos objetos isolados. Em paper-world-defaults.yml, o entity-per-chunk-save-limit limita quantos objetos de um tipo chegam sequer a ser gravados por chunk.

Carregamento de chunks

Um jogador de elytra ou num cavalo rápido obriga o servidor a gerar terreno novo de forma permanente. A geração de mundo é a operação isolada mais cara que existe. O mesmo acontece na primeira entrada no Nether ou depois de alargar o limite do mundo. A solução não é um valor de configuração, mas sim a pré-geração, e essa é suficientemente importante para merecer uma secção própria mais abaixo.

Plugins

Se o Spark aponta um plugin, o caso está arrumado. Se não aponta, só ajuda a busca por bisseção: desativar metade dos plugins, medir e, conforme o resultado, voltar a dividir a metade sobrecarregada. Com 32 plugins são cinco reinícios em vez de 32. Antes disso, faça obrigatoriamente um backup, porque os plugins que escrevem dados de mundo podem deixar para trás conteúdos que, sem eles, deixam de funcionar.

Pré-gerar os chunks antes de os jogadores lá chegarem

Esta é a medida isolada mais eficaz de todo este artigo e é também a mais esquecida. A razão está na forma como o Minecraft trabalha: carregar do disco um chunk já criado não custa quase nada. Já criar um chunk novo significa mapa de alturas, biomas, distribuição de minérios, grutas, estruturas e cálculo de luz, e boa parte disso corre na thread principal. Exatamente onde também têm de nascer os 20 ticks por segundo.

Por isso é típico o lag aparecer quando alguém arranca de elytra ou constrói uma linha férrea para o nada: o servidor está a gerar mundo enquanto, ao mesmo tempo, devia estar a calcular o jogo. Quem gera o mundo uma vez, previamente, até ao limite do mundo, transforma trabalho de cálculo caro em leitura barata a partir do disco.

Chunky, a ferramenta indicada

O Chunky é o pré-gerador hoje habitual e corre como plugin em Paper, Spigot e Purpur, bem como em forma de mod em Fabric e Forge. O procedimento é o mesmo em todas as plataformas:

/chunky world world
/chunky center 0 0
/chunky radius 5000
/chunky start

O raio é indicado em blocos e deve corresponder ao limite do mundo. O Chunky comunica sozinho o progresso e a duração restante estimada; com /chunky pause e /chunky continue é possível parar e retomar o processo a qualquer momento, mesmo depois de um reinício.

O Nether e o End são mundos próprios e têm de ser pré-gerados separadamente. Em Paper e Spigot chamam-se, por omissão, assim:

/chunky world world_nether
/chunky radius 1000
/chunky start

Para o Nether basta um raio menor, porque aí um bloco corresponde a oito blocos no mundo normal. Um raio de 1000 no Nether cobre, portanto, 8000 blocos do mundo normal.

O que tem de contar à partida

• Tempo. Um raio de 5000 blocos corresponde a cerca de 78 milhões de blocos de área. Consoante o hardware, o modpack e o gerador de mundo, isso demora de uma hora a vários dias. Os modpacks com geradores de mundo próprios são bastante mais lentos do que o Vanilla.
• Espaço em disco. Um mundo pré-gerado ocupa rapidamente vários gigabytes. Verifique antes quanto espaço tem livre, senão o disco enche-se durante o processo, e isso atinge o servidor com muito mais força do que qualquer lag. Como verificar e limpar está descrito em Disco cheio: encontrar e libertar espaço.
• Momento. Pré-gere com o servidor vazio, não durante o funcionamento normal. Ao longo do processo a taxa de ticks é má, como seria de esperar, e isso não é um erro. O objetivo é precisamente retirar essa carga do tempo de jogo.
• Definir o limite do mundo. Sem limite, mais cedo ou mais tarde alguém sai da zona pré-gerada e tudo recomeça do zero. Defina o limite com o mesmo raio que pré-gerou.

Limpar mais tarde

Se o mundo já cresceu e contém zonas onde ninguém volta a pôr os pés, o Chunky remove os chunks fora do limite do mundo:

/chunky trim

Isso reduz o mundo de forma sensível e, com ele, também os backups. Faça antes obrigatoriamente uma cópia de segurança, porque os chunks apagados voltam a ser gerados na próxima entrada e tudo o que os jogadores tinham construído lá fica perdido.

Quando o Chunky não é opção

Em servidores mais antigos ainda se encontra com frequência o WorldBorder com /wb fill. Cumpre o mesmo objetivo, mas o projeto quase não é mantido há anos e, para as versões de servidor atuais, o Chunky é a escolha mais fiável. Em qualquer dos casos, verifique antes da instalação se a versão oferecida corresponde mesmo à versão do seu servidor.

view-distance e simulation-distance

Estes dois valores em server.properties são constantemente confundidos.

• view-distance determina até que distância os chunks são enviados ao cliente. Custa largura de banda e alguma memória.
• simulation-distance determina até que distância o servidor calcula entidades, redstone e atualizações de blocos. Custa tempo de CPU no tick principal.

Os chunks entre o limite de simulação e o limite de visão continuam a ser mostrados, mas do lado do servidor estão congelados. Os custos crescem de forma quadrática: com view-distance=10 são 21 vezes 21, ou seja, 441 chunks por jogador.

Valores de partida comprovados para uma rede survival com 10 a 30 jogadores:

view-distance=8
simulation-distance=5

Para quem ainda encontra guias com no-tick-view-distance: esta opção do Paper está ultrapassada. A Mojang introduziu na 1.18 o simulation-distance e resolveu oficialmente o mesmo problema. Quem hoje define o valor antigo não consegue efeito nenhum.

O preço dos valores baixos raramente é mencionado: com simulation-distance abaixo de 4, as farms de AFK deixam de funcionar, os spawns de mobs comportam-se de outra maneira, os fornos no chunk vizinho param e os relógios de redstone ficam quietos. Quem tem uma comunidade muito virada para farms está a poupar no sítio errado e troca um problema técnico por um problema com os jogadores. Avance de uma unidade de cada vez e meça depois de cada passo.

Limpar sem destruir o mundo

Qualquer intervenção nos dados do mundo começa por um backup com o servidor parado. Sem compromissos, sem exceções:

tar -czf backup-mundo.tar.gz world world_nether world_the_end

Depois vale a pena olhar para o tamanho dos dados de região:

du -sh world/region

Os mundos que cresceram ao longo de anos contêm muitas vezes centenas de megabytes de terreno que um único jogador sobrevoou uma vez. Esses chunks não custam tempo de tick, mas ocupam espaço em disco e prolongam cada gravação. Se o espaço começar a faltar, ajuda ainda o artigo Limpar um disco cheio em Linux.

Picos regulares na ordem dos segundos, que surgem exatamente de cinco em cinco minutos, são quase sempre a gravação automática. Em bukkit.yml, o ticks-per.autosave controla o intervalo; em paper-world-defaults.yml, o max-auto-save-chunks-per-tick limita quanto é escrito por tick. Um valor mais baixo distribui a carga em vez de a concentrar.

Para servidores privados pequenos existe, desde a série 1.21, a opção pause-when-empty-seconds em server.properties. Se aí estiver um valor maior do que zero, o servidor deixa de ticar o mundo passado esse tempo sem jogadores. Isso poupa tempo de cálculo de forma bem visível num servidor root partilhado.

Quando é a JVM que trava

Se o tempo de tick se mantém baixo em média, mas salta de forma irregular para várias centenas de milissegundos, a culpa é muitas vezes da recolha de lixo do ambiente de execução Java. Isso verifica-se diretamente:

spark gcmonitor
spark heapsummary

Dois equívocos muito espalhados: mais heap não é automaticamente melhor, porque heaps grandes produzem pausas mais longas na recolha. E o heap nunca pode ser escolhido tão grande que empurre o sistema operativo para a memória de swap. Um servidor Minecraft em swap é irremediavelmente lento. Verifique isso com vmstat 1 5: valores permanentes nas colunas si e so são a sentença de morte. Contexto sobre o tema no artigo Configurar swap e evitar Out of Memory.

Esta mensagem é um sintoma, não uma causa:

java.lang.OutOfMemoryError: Java heap space

Aumentar o heap apenas adia a falha, se um plugin tiver uma fuga de memória ou se existirem milhões de entidades.

Na versão de Java, as distribuições diferem bastante, e é precisamente aí que muitas instalações falham. A partir do Minecraft 1.20.5 é exigido o Java 21. O Debian 12 traz no repositório padrão apenas o OpenJDK 17 e não o OpenJDK 21; o Debian 13 traz o 21 e o 25, mas não o 17. O Ubuntu 22.04 e o 24.04 têm o 17 e o 21 no repositório. Quem tiver de ficar no Debian 12 instala o Temurin a partir do repositório Adoptium. Os passos estão em Instalar o Java 21 em Debian e, para versões de servidor mais antigas, em Instalar o Java 17 em Debian.

Não recorra ao cómodo pacote coletivo default-jre-headless. Consoante a release, aponta para uma versão completamente diferente: o Debian 13 e o Ubuntu 24.04 entregam com ele o Java 21, o Debian 12 entrega o Java 17, o Debian 11 e o Ubuntu 22.04 entregam o Java 11. A instalação corre sem erros em todo o lado, mas nos dois últimos casos o servidor não arranca à mesma. Indique por isso a versão de forma explícita, ou seja, openjdk-21-jre-headless.

java -version
java -XX:+PrintFlagsFinal -version 2>/dev/null | grep -w MaxHeapSize

O 2>/dev/null suprime o banner de versão que a JVM escreve na saída de erro e que, de outra forma, ficaria a meio da saída. E o grep -w MaxHeapSize devolve exatamente uma linha, ao passo que a procura difusa encontraria também o SoftMaxHeapSize.

Quando corre mal e como voltar atrás

O servidor aborta com um erro do watchdog. No log fica escrito, em resumo, que um único tick demorou 60 segundos e que o servidor é considerado bloqueado. Não é uma avaria, mas sim uma medida de proteção contra um processo permanentemente pendurado. O stacktrace anexado vale ouro: mostra exatamente onde o servidor ficou preso. O valor max-tick-time em server.properties controla este limiar. Desligá-lo não resolve nada, apenas transforma a falha num servidor congelado em permanência.

Depois de uma alteração de configuração ficou pior. É precisamente por isso que vale a regra mais importante desta análise: uma só alteração por medição, e anote o valor de partida. Quem mexe ao mesmo tempo na view-distance, nos entity ranges e nas flags do Java não fica a saber depois o que é que fez efeito.

O servidor já não arranca depois da falha. Normalmente o level.dat está danificado. Na pasta do mundo está o level.dat_old, que pode copiar por cima depois de guardar uma cópia do estado avariado. Com ficheiros de região danificados só o backup ajuda.

Está tudo otimizado e continua a haver lag. Então verifique a camada de baixo: %steal no mpstat, o uso de swap no vmstat e a latência do disco. Se o tempo de tick continua alto apesar de o Spark não mostrar nenhum causador isolado acima de 10 por cento, é simplesmente demasiado conteúdo para pouca capacidade por núcleo. Aí ajuda repartir por várias instâncias ou ter mais capacidade de cálculo, não o próximo parafuso de configuração.

Só os jogadores têm pings altos e o servidor está calmo. Então o problema é da rede. Uma localização com caminhos curtos até aos jogadores faz aqui a maior diferença. Para servidores em Frankfurt am Main, as latências típicas a partir do espaço de língua alemã ficam na casa das dezenas baixas de milissegundos. Se as falhas surgem de repente e em bloco, também pode estar por trás um ataque, veja Proteger o servidor contra ataques DDoS. Do lado do cliente aparecem então mensagens deste género:

Internal Exception: io.netty.handler.timeout.ReadTimeoutException
Timed out
Connection reset

Como saber que está mesmo resolvido

Uma correção só conta como confirmada quando aguenta exatamente sob a carga em que o problema apareceu. De noite, com dois jogadores, até um servidor avariado corre bem. Verifique na hora de ponta:

• O spark tps mostra 20,0 na janela de 15 minutos e não apenas na de 5 segundos.
• O percentil 95 do tempo de tick fica abaixo de 40 ms e o máximo abaixo de 100 ms.
• 24 horas de log sem uma única linha "Can't keep up!".
• Um perfil novo do Spark já não mostra nenhuma rubrica isolada acima de 15 por cento.
• O spark gcmonitor não reporta pausas acima de 200 ms.
• Os jogadores que se tinham queixado confirmam a melhoria no mesmo sítio e na mesma situação de jogo.

Anote os valores de antes e de depois, idealmente com data e com a alteração feita em cada caso. Na próxima quebra, daqui a três meses, essa lista vale mais do que qualquer guia, porque mostra o que já resultou exatamente no seu servidor. Quem estiver a montar o servidor de raiz encontra as bases certas em Instalar um servidor Minecraft em Debian e na Checklist para um novo servidor root.