PlaceholderAPI permite que plugins compatíveis mostrem dados dinâmicos como nome, economia, mundo e estado do servidor. O plugin principal oferece mecanismo e integrações; muitas variáveis vêm de expansões separadas. Instalar PlaceholderAPI sozinho não garante que o placeholder usado no scoreboard ou chat exista.

Este fluxo identifica o consumidor, a expansão e o contexto antes de alterar produção. Expansões executam código e podem fazer chamadas a outros plugins, então use fontes oficiais, confira requisitos e teste. Não substitua uma variável desconhecida por wildcard ou plugin aleatório.

Descubra qual plugin consome a variável

Liste o plugin que exibe scoreboard, tab list, chat ou holograma, e copie o placeholder exatamente, incluindo delimitadores. Verifique se a integração desse plugin com PlaceholderAPI precisa ser habilitada ou instalada à parte. Algumas integrações exigem reinício, outros recursos têm um comando próprio de expansão.

Separe nome da expansão do identificador do placeholder. A documentação e a lista do eCloud mostram variáveis suportadas, requisitos e sintaxe. Um placeholder que começa com `player` pode depender de expansão Player; dado de economia pode exigir Vault e provedor econômico ativo.

Confira requisitos e versões

Antes de baixar, leia a página da expansão e confirme compatibilidade com sua versão de Paper, Java, PlaceholderAPI e plugin provedor. Extensões comunitárias podem ter requisitos ou suporte diferentes do núcleo. Não conclua que uma variável documentada funciona com toda versão do plugin consumidor.

Instale dependências faltantes primeiro em homologação. Após reiniciar, leia o log de carregamento. Uma expansão pode estar instalada, mas não ativada no contexto atual, ou exigir que API do plugin provedor esteja disponível. Confirme todos os componentes antes de depurar a string final.

Instale pelo eCloud de forma controlada

Quando a expansão está disponível na nuvem oficial, use comandos de instalação documentados, como download de expansão pelo console e recarga do PAPI segundo o guia atual. Confirme o nome exato usado no catálogo. Evite baixar JAR de repositório não verificado só porque o nome coincide com a expansão.

Se a rede do servidor bloqueia eCloud, leia o diagnóstico oficial antes de presumir que o nome da expansão está errado. Verifique conectividade de saída, DNS, proxy e certificados do host com o provedor. Instalação manual deve seguir o procedimento oficial do projeto, e o arquivo precisa vir da fonte reconhecida.

Teste o placeholder em isolamento

Use o comando de parse ou ferramenta disponível na versão instalada para avaliar a expressão sem exibi-la primeiro em scoreboard de produção. Teste com jogador online e confira formato quando valor não está disponível. Um literal que permanece na tela pode indicar variável não registrada, typo ou falta de expansão.

Compare no console e em jogo: placeholders que dependem de jogador podem não ter valor em console. Confirme mundo, grupo e servidor, pois integração pode aceitar contextos. Faça parse em usuário comum e em caso sem dados, como saldo vazio, para evitar output quebrado.

Valide integração no consumidor

Depois de o PAPI resolver a variável, confirme que o plugin consumidor a atualiza na frequência desejada. Uma atualização a cada tick pode realizar trabalho repetido e amplificar consulta a banco ou estatística. Prefira intervalos e cache indicados pelo autor, especialmente em tabelas com muitos jogadores.

Se valor aparece certo no parse e errado no scoreboard, investigue o consumidor, ordenação, cache e limite de caracteres. Se o erro acontece somente após trocar mundo, teste troca e reconexão. Não reescreva todas as placeholders do sistema porque uma expansão específica falhou.

Evite carga e chamadas externas desnecessárias

Dados locais, como nome e vida, costumam ter custo diferente de informação buscada via HTTP ou consulta a banco. Leia a documentação da expansão para saber se faz chamadas externas, coleta identificador ou armazena dado. Use somente as variáveis realmente exibidas e respeite intervalos de atualização.

Em pico, capture log e profile se suspeitar que scoreboard ou placeholders causam custo no tick. Compare com integração desativada numa cópia e uma quantidade parecida de jogadores. Um nome de placeholder não prova que ele tem peso baixo.

Trate placeholders como dados não confiáveis

Plugins recebem nomes, texto e valores de fontes distintas. Não use um placeholder como entrada de comando administrativo sem validação. Cuidado com mensagens que interpretam códigos ou componente JSON: texto de jogador pode produzir formatação inesperada dependendo da integração.

Restrinja comando de parse e administração a staff apropriado, e não exponha resultado que revele dados de outro jogador. Teste símbolos, campos vazios e nomes com caracteres especiais. O output deve continuar seguro e legível em chat e Discord.

Atualize e reverta

Antes de atualizar PlaceholderAPI ou uma expansão, faça backup do arquivo e registre versões. Leia mudanças do projeto e teste placeholders críticos. Se regressão surgir, remova somente a expansão que falhou e volte ao estado conhecido, verificando startup e funções dependentes.

Consulte a documentação do PlaceholderAPI, busque expansão na nuvem oficial e leia a página sobre falha de conexão ao eCloud. Confirme requisitos na ficha atual antes de alterar um servidor de produção.

Use expansão externa com critério

Uma expansão pode acessar APIs e mostrar dado de outro plugin, mas só é útil se esse plugin está instalado e configurado. Faça inventário das dependências e remova expansão que não tem consumidor ativo. Isso reduz arquivo sem uso e facilita localizar qual componente registrou o identificador durante diagnóstico.

Leia versão e licença da expansão, quando informadas, e prefira releases estáveis compatíveis. Se o eCloud oferece revisões ou status, confira antes de atualizar. Não instale vários arquivos de uma vez; assim o log e o teste apontam qual expansão trouxe comportamento novo.

Tenha procedimento de indisponibilidade

Se uma variável deixa scoreboard quebrado, substitua-a temporariamente por texto seguro ou desative apenas o campo em homologação. Corrija a dependência sem reiniciar repetidamente produção. Registre a expressão anterior e restaure após parse com jogador e consumidor reais.

Separe falha de expansão de falha de formatação

Teste placeholder bruto antes de inserir prefixos, cores e condicionais do plugin de scoreboard. Depois adicione formatação em partes e observe se a string fica dentro do limite do consumidor. Isso separa erro de resolução de variável de limite de caracteres, parser ou atualização visual.

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.