A propriedade de JVM Paper.WorkerThreadCount controla o número de threads de trabalho usadas para carregamento de chunks, segundo a referência do Paper. Ela costuma ser confundida com worker threads de geração paralela na configuração global de Paper, mas são controles distintos. Ajustar um não necessariamente muda o outro.

O padrão documentado usa parte dos núcleos físicos disponíveis, com comportamento especial em máquinas pequenas. Isso não é uma recomendação universal para aumentar manualmente. Threads demais podem disputar CPU, disco e locks; threads de menos podem limitar paralelismo se houver trabalho apropriado.

Diferencie IO, geração e worker threads

Chunk loading inclui leitura de dados existentes, descompressão, processamento e, quando necessário, geração de terreno. A configuração avançada do Paper também expõe threads para IO e para geração em paralelo. Cada etapa tem gargalos diferentes, então perfil a atividade antes de editar.

Se a geração paralela é o gargalo, worker thread de carregamento pode não ser a opção central. Se disco está saturado, mais threads de IO podem apenas aumentar fila. Se a CPU tem poucos núcleos ou container limita quota, número baseado no host pode exceder o recurso realmente disponível.

Procure no perfil quando chunks estão carregando lentamente. Observe threads, espera de disco, uso por núcleo, fila e MSPT. O relatório deve ocorrer durante a exploração que causa atraso; um gráfico ocioso não diagnostica a operação.

Confira CPUs e limites do ambiente

Distinga núcleos físicos, threads lógicas e quota de CPU do container. O servidor pode enxergar número de CPUs diferente do que o provedor efetivamente concede. Em host compartilhado, recursos podem ser disputados por outros processos. Confira documentação do painel ou contêiner antes de definir número.

Threads usam stack e estruturas próprias e precisam ser agendadas. Um número maior não implica mais throughput quando todos competem por um núcleo ocupado. Também pode mudar timing e revelar contenção. Não aplique valores retirados de uma máquina de especificação diferente.

Inventarie outras tarefas: proxy, banco, backup, mapas e bots. Se compartilham CPU, ampliar worker count do Paper pode prejudicar todos. Use métricas do host e teste do serviço completo.

Faça benchmark em staging

Duplique servidor e mundo, isole banco e integrações, e reproduza rota de chunks. Anote worker count, configuração de IO, gerador, CPU, armazenamento e versão. Mude somente uma propriedade por execução para comparar resultados.

Meça tempo de entrada em chunk, MSPT, uso total e por núcleo de CPU, latência de disco, quantidade de chunks pendentes e estabilidade. Repita a mesma rota com jogadores distribuídos e agrupados. Geração de chunks novos e leitura de região antiga devem ser testes separados.

Interrompa se o host ficar instável, CPU saturar por período longo ou memória crescer além dos limites. O objetivo é manter jogo responsivo, não maximizar contagem de threads. Restaure o padrão depois do experimento se não houver ganho claro.

Altere a propriedade de JVM corretamente

Propriedades com -D precisam estar no comando de startup antes de -jar, conforme guia de Paper. Em scripts Windows e PowerShell, pontos em argumentos podem exigir aspas dependendo do interpretador; consulte a referência. Painéis podem ter campo separado para flags de Java.

Não coloque a opção depois do nome do JAR como se fosse argumento de Paper: nesse lugar ela pode ser entregue ao programa de forma diferente. Revise o comando real do processo e confirme logs na inicialização. Mantenha cópia do script anterior.

Se o painel bloqueia flags arbitrárias, não use meio não suportado para editar startup. Pergunte ao provedor se a propriedade pode ser configurada e se o valor está dentro dos limites da alocação.

Monitore contenda e problemas de concorrência

Depois de aplicar em staging, verifique comportamento de chunk, plugins, teleporte e geração. Plugins podem carregar dados sincronamente ou manter tarefas próprias. Uma propriedade de worker threads não torna todo acesso à API seguro em paralelo nem corrige código de plugin que bloqueia tick principal.

Se a melhora de carregamento vem com aumento de tick ou jitter, reverta. Compare picos e percentis, não apenas média. A experiência mais lenta de poucos usuários em regiões remotas pode desaparecer na métrica média.

Guarde logs de Paper e perfis junto à versão de teste. Não compartilhe dumps que contenham detalhes de usuários ou caminhos privados sem sanitização. Relatório útil conecta alteração a cenário e medição.

Prepare promoção e retorno

Antes de promover, faça backup dos dados do mundo e das configurações. Altere apenas o startup flag, reinicie em janela, confira a opção e teste login, teleportes, terreno novo e regiões antigas. Mantenha conta de teste e operador disponíveis.

Defina gatilho de rollback, como MSPT regressivo, falha de carregamento ou saturação de CPU. Reverter o argumento deve ser simples: restaure script ou configuração do painel e reinicie de forma controlada. Preserve logs do incidente.

Reavalie após mudanças de hardware, container, Paper, geração ou estrutura de chunk loading. Se o valor foi uma correção para uma condição temporária, remova após resolver a causa. Anote escolha e evidências no runbook.

Quando manter o padrão

Se não há perfil indicando limitação de worker threads, mantenha padrão do Paper. Configurações avançadas aumentam variáveis e custo de suporte quando não há benefício medido. Para chunk lag, o primeiro passo é encontrar se o trabalho está em leitura, geração, plugin, disco ou rede.

Capacidade física, armazenamento rápido e plugins eficientes costumam importar mais que número arbitrário. Uma alteração bem-sucedida precisa demonstrar carregamento melhor sem regressão nos ticks, memória e comportamento do jogo.

Não substitua correção de plugin

Um plugin pode solicitar chunk síncrono de forma repetida, bloquear thread principal ou chamar API externa durante teleporte. Aumentar workers pode não mover esse trabalho para fora do tick e pode aumentar concorrência. Leia stack trace e perfil; peça correção ao autor quando a chamada está na origem.

Em plugins próprios, siga os limites de segurança da API: acessar estado do mundo fora da thread correta pode causar corrupção ou exceção. A existência de threads do Paper não torna toda operação assíncrona segura. Consulte docs de scheduler e API antes de mudar código.

Teste teleporte para chunks descarregados em cópia e veja se a API do plugin usa caminho assíncrono suportado. Não altere propriedade global como workaround para comportamento que o autor precisa corrigir.

Compare resultados com percentis

Registre média e p95/p99 de tick e latência de chunk, além de máximos. Uma thread pool maior pode melhorar média e criar pausas esporádicas por contenda. Compare várias execuções e mantenha a mesma sequência de ações.

Faça benchmark tanto com região já gerada quanto com exploração nova. Inclua discos sob carga e número semelhante de jogadores. Se resultado varia, examine cache do sistema, background tasks e compartilhamento do host antes de fixar o valor.

Guarde relatório original e configuração junto à versão exata de Java e Paper. Isso permite repetir medição depois de atualização e remover tuning que não melhora mais.

Fontes e referências

Documentação consultada em 2026-10-08. Os exemplos precisam ser conferidos na versão instalada; este guia não afirma que a configuração foi testada no seu ambiente.