---
title: "PlaceholderAPI: como configurar no servidor Minecraft"
description: "Instale o PlaceholderAPI, baixe expansões pelo eCloud, teste com /papi parse e leve placeholders para TAB, menus, scoreboard e chat do servidor."
url: "https://streethosting.com.br/guias/minecraft/configurar-placeholderapi-minecraft"
category: "minecraft"
slug: "configurar-placeholderapi-minecraft"
datePublished: "2026-09-28"
dateModified: "2026-09-28"
author: "Equipe StreetHosting"
difficulty: "iniciante"
language: "pt-BR"
keywords:
  - "configurar placeholderapi minecraft"
  - "papi ecloud download"
  - "placeholderapi expansoes"
  - "placeholder tab minecraft"
  - "placeholder nao funciona minecraft"
---

# Como instalar o PlaceholderAPI e usar placeholders nos seus plugins

O PlaceholderAPI é a ponte que leva saldo, grupo, ping e TPS de um plugin para outro. Veja como instalar, quais expansões baixar primeiro e como descobrir por que um placeholder aparece cru na tela.

> **Resposta rápida**
>
> Para **configurar o PlaceholderAPI**, coloque o jar na pasta `plugins` do Paper, reinicie e baixe as expansões que você precisa com `/papi ecloud download`, começando por Player, Server e Vault. Rode `/papi reload` e teste com `/papi parse me %player_name%`. Se o seu nick aparecer, qualquer plugin compatível já pode usar aquele placeholder no TAB, em menus, no scoreboard e no chat.

## O que é o PlaceholderAPI

Placeholder é um texto entre sinais de porcentagem, como `%player_name%`, que o plugin troca por um valor na hora de mostrar. O PlaceholderAPI é o intermediário dessa troca: ele busca a informação em um plugin, como o saldo no Vault ou o grupo no LuckPerms, e entrega para outro plugin que quer exibir essa informação, como o TAB ou um menu.

Sem essa ponte, cada plugin de exibição teria que conhecer cada plugin de dados, e nada conversaria com nada. Por isso ele aparece na lista de [plugins mais usados em servidores Paper](https://streethosting.com.br/guias/minecraft/plugins-minecraft-mais-usados) e costuma ser instalado cedo, antes de TAB e scoreboard.

- **PlaceholderAPI:** o núcleo, que traz os comandos `/papi` e faz a troca dos textos.
- **Expansões:** pacotes que ensinam o PlaceholderAPI a ler um assunto: jogador, servidor, Vault, LuckPerms. Algumas vêm embutidas no plugin de origem, outras são baixadas do eCloud, o repositório oficial de expansões.
- **Plugins que exibem:** TAB, DeluxeMenus, scoreboards, hologramas e plugins de chat que aceitam placeholders nos seus arquivos de configuração.

> **Dica**
>
> O PlaceholderAPI é plugin de Paper e Spigot. No Fabric ele não existe; há um projeto separado de placeholders para mods, com sintaxe própria. Se você está decidindo a base do servidor, veja o guia de [servidor Minecraft com mods Fabric](https://streethosting.com.br/guias/minecraft/servidor-minecraft-fabric-mods) para entender o que muda.

## Instalação

1. Baixe o PlaceholderAPI da página oficial no Hangar, no Modrinth ou no SpigotMC, na versão compatível com o seu Paper.
2. Pare o servidor pelo painel.
3. Envie o jar para a pasta `plugins` pelo gerenciador de arquivos ou por SFTP.
4. Ligue o servidor. Ele cria a pasta `plugins/PlaceholderAPI`, com o `config.yml` e a subpasta `expansions`.
5. Rode `/papi list` para ver as expansões ativas. No começo a lista pode estar vazia ou mostrar só as que outros plugins registraram sozinhos.

Os comandos `/papi` são ferramenta de staff. Deixe com operadores ou com o grupo de administração no [LuckPerms](https://streethosting.com.br/guias/minecraft/configurar-luckperms-servidor-minecraft), porque o parse lê informações de outros jogadores e o download do eCloud coloca código novo dentro do servidor.

## Expansões e o eCloud

O eCloud é o repositório oficial de expansões, acessado direto pelo chat ou pelo console. O download cai na pasta `expansions`, e a expansão só passa a funcionar depois do reload.

```
/papi ecloud download Player
/papi ecloud download Server
/papi ecloud download Vault
/papi reload
/papi list
```

| Expansão | Exemplos de placeholder | O que mostra |
| --- | --- | --- |
| Player | %player_name%, %player_ping%, %player_world% | Nome, ping e mundo do jogador |
| Server | %server_online%, %server_max_players%, %server_tps% | Jogadores online, capacidade e TPS |
| Vault | %vault_eco_balance%, %vault_prefix% | Saldo e prefixo lidos pelo Vault |
| LuckPerms | %luckperms_prefix% | Prefixo definido no grupo do LuckPerms |

A expansão do Vault só lê o que o Vault fornece. Sem um plugin de economia ativo por trás, o saldo volta vazio. A montagem dessa base está em [Vault no Minecraft para economia e permissões](https://streethosting.com.br/guias/minecraft/configurar-vault-economia-permissoes-minecraft). A do LuckPerms também é baixada pelo eCloud, com `/papi ecloud download LuckPerms`.

Vários plugins registram a própria expansão ao iniciar, sem download nenhum. A página do plugin costuma avisar; na dúvida, instale o plugin, rode `/papi list` e veja se o nome dele apareceu. Para ver versão e detalhes de uma expansão, use `/papi info Vault`, trocando pelo nome que quiser.

> **Atenção**
>
> Expansão é código rodando dentro do servidor. Por padrão o eCloud só entrega expansões verificadas. Se a sua política é controlar tudo o que entra, desligue a nuvem e instale os jars manualmente na pasta `expansions`, sempre de fonte oficial, seguidos de `/papi reload`.

```
# plugins/PlaceholderAPI/config.yml
cloud_enabled: false
```

### Manter as expansões em dia

Expansão desatualizada é a causa mais comum de erro no console depois de atualizar o Paper ou o plugin de origem. Inclua o PlaceholderAPI na rotina de toda atualização do servidor, descrita em [como atualizar a versão do servidor com segurança](https://streethosting.com.br/guias/minecraft/atualizar-versao-minecraft-servidor-guia):

1. Rode `/papi ecloud refresh` para atualizar a lista do eCloud.
2. Rode `/papi ecloud list installed` para ver o que foi instalado pela nuvem e compare com a versão disponível.
3. Baixe de novo as que mudaram e finalize com `/papi reload`.
4. Apague da pasta `expansions` o que ninguém usa mais. Menos código carregado significa menos erro no boot e menos coisa para revisar na próxima atualização.

## Testar com /papi parse

Antes de colar um placeholder em qualquer configuração, teste. O parse mostra no chat o texto já trocado, do jeito que o outro plugin vai receber.

```
/papi parse me %player_name% está com %player_ping% ms
/papi parse me Saldo: %vault_eco_balance%
/papi parse Steve %luckperms_prefix%
/papi parse --null Online agora: %server_online%
```

- **`me`:** usa você como jogador de referência.
- **Um nick:** testa na visão daquele jogador, ótimo para conferir se o prefixo de um VIP está saindo certo.
- **`--null`:** para placeholders que não dependem de jogador, como os de servidor. É também o jeito de testar pelo console.

Essa etapa separa o problema em dois. Se o parse devolve o texto cru, com as porcentagens, a falha está no PlaceholderAPI: expansão faltando ou nome errado. Se o parse funciona e o TAB mostra cru, a falha está no plugin que exibe. Existe também o `/papi bcparse`, que manda o resultado para todos os jogadores online; guarde para quando realmente quiser anunciar algo.

## TAB, menus, scoreboard e chat

Com o placeholder testado, basta colocar o mesmo texto em qualquer opção de configuração que aceite PlaceholderAPI. Estes são os usos que mais aparecem em servidor brasileiro.

- **TAB:** o plugin TAB aceita placeholders no cabeçalho, no rodapé da lista de jogadores e no prefixo de cada nome. É onde o `%luckperms_prefix%` costuma aparecer, e o guia de [rank VIP com tag colorida](https://streethosting.com.br/guias/minecraft/configurar-rank-vip-tag-servidor-minecraft) mostra a montagem completa.
- **DeluxeMenus:** menus em forma de baú em que nome, descrição e requisitos de cada item podem usar placeholders. Um botão de perfil com saldo e ping é o exemplo clássico.
- **Scoreboards:** o placar na lateral da tela atualiza os valores em intervalos. TPS, jogadores online e saldo ficam bem aqui.
- **Chat:** plugins de formatação de chat que declaram suporte ao PlaceholderAPI mostram grupo, clã ou nível antes da mensagem. Confira na página do plugin, porque nem todo plugin de chat aceita.

Um item de menu do DeluxeMenus com placeholders fica assim. O arquivo do menu vive na pasta do DeluxeMenus e é registrado no config dele:

```
menu_title: '&8Seu perfil'
open_command: perfil
size: 27
items:
  'saldo':
    material: GOLD_INGOT
    slot: 13
    display_name: '&6Seu saldo'
    lore:
      - '&7Você tem &f%vault_eco_balance% &7moedas'
      - '&7Ping: &f%player_ping% ms'
```

> **Dica**
>
> TAB e scoreboard releem os placeholders o tempo todo. Intervalo curto demais com dezenas de placeholders pesados, principalmente os que consultam banco de dados, pesa no TPS. Mantenha o padrão do plugin e só encurte onde precisa de tempo real. Se o tick cair depois de montar o HUD, comece aumentando o intervalo justamente desses placeholders mais pesados.

## Quando o placeholder não funciona

Quase todo problema com PlaceholderAPI cai em uma das linhas abaixo. Comece sempre pelo parse, porque ele diz de que lado está a falha.

| Sintoma | Causa provável | O que fazer |
| --- | --- | --- |
| Texto cru até no /papi parse | Expansão não instalada ou não registrada | Baixe pelo eCloud e rode /papi reload |
| Parse funciona, TAB ou menu mostra cru | Plugin sem suporte ao PlaceholderAPI ou recurso desligado | Confira na documentação do plugin se o suporte existe e está ativo |
| Saldo do Vault vazio | Vault sem plugin de economia por trás | Instale e configure o provedor de economia |
| Download do eCloud falha | Nuvem desligada, conexão bloqueada ou expansão não verificada | Revise cloud_enabled ou instale o jar manualmente |
| NoClassDefFoundError no console | Expansão desatualizada ou dependência ausente | Atualize a expansão e o plugin de que ela depende |

Erro de digitação também deixa o texto cru: `%player_nome%` não existe. Copie os nomes da lista oficial da expansão em vez de digitar de memória, e lembre que expansão que depende de outro plugin só funciona com esse plugin instalado e ligado.

## Onde hospedar

O PlaceholderAPI em si é leve. Quem consome recursos são os plugins que ele conecta: TAB, scoreboard, economia, LuckPerms com banco de dados e menus. Um survival com essa pilha e algumas dezenas de jogadores costuma pedir de 6 a 8 GB de RAM, e os plugins de banco agradecem CPU com clock alto e NVMe.

Na [hospedagem Minecraft da StreetHosting](https://streethosting.com.br/minecraft), em São Paulo, a linha Budget com DDR4 começa em R$ 34,00 por mês com 4 GB, e a linha [Minecraft Pro](https://streethosting.com.br/minecraft-pro), com Ryzen e DDR5, vai de R$ 44,00 com 4 GB a R$ 66,00 com 6 GB e R$ 88,00 com 8 GB, 500% de CPU e 60 GB NVMe. Todos os planos incluem banco de dados, a partir de um no plano de 4 GB, o que resolve o LuckPerms e a economia em MySQL sem contratar nada à parte.

- [ ] PlaceholderAPI instalado antes de TAB e scoreboard
- [ ] Expansões Player, Server e Vault baixadas e registradas
- [ ] Cada placeholder testado com /papi parse antes de ir para a configuração
- [ ] Comandos /papi restritos à staff
- [ ] Intervalos de atualização do HUD no padrão do plugin
- [ ] eCloud desligado se a política for instalação manual

## Perguntas frequentes

### Para que serve o PlaceholderAPI?

Ele leva informações de um plugin para outro. O saldo do Vault, o prefixo do LuckPerms ou o TPS do servidor viram textos como %vault_eco_balance%, e plugins de TAB, menu, scoreboard e chat trocam esse texto pelo valor na hora de mostrar para o jogador.

### Como baixar expansões do PlaceholderAPI?

Use /papi ecloud download seguido do nome da expansão, por exemplo Player, Server ou Vault, e depois rode /papi reload para registrar. Algumas expansões já vêm dentro do próprio plugin e não precisam de download. Confira o resultado com /papi list.

### Por que o placeholder aparece com as porcentagens em vez do valor?

Teste primeiro com /papi parse me. Se aparecer cru ali, falta a expansão, o nome está digitado errado ou o plugin de que ela depende não está ativo. Se o parse funcionar e o texto cru aparecer só no TAB ou no menu, o problema está no plugin que exibe.

### Dá para usar o PlaceholderAPI sem o eCloud?

Dá. Coloque cloud_enabled como false no config.yml do PlaceholderAPI e instale as expansões manualmente, copiando os jars para a pasta expansions e rodando /papi reload. É a escolha de quem prefere controlar tudo o que entra no servidor.

### O PlaceholderAPI funciona em servidor Fabric?

Não. Ele é um plugin para Paper e Spigot. No Fabric existe um projeto de placeholders separado, feito para mods, com sintaxe e lista de placeholders próprias. Se a sua configuração depende muito do PlaceholderAPI, o caminho natural é continuar no Paper.

## Guias relacionados

- [Plugins Minecraft mais usados em servidores Paper: lista prática para começar bem](https://streethosting.com.br/guias/minecraft/plugins-minecraft-mais-usados.md)
- [Como configurar LuckPerms no servidor Minecraft (Paper)](https://streethosting.com.br/guias/minecraft/configurar-luckperms-servidor-minecraft.md)
- [Vault no Minecraft: ligar economia e permissões dos plugins](https://streethosting.com.br/guias/minecraft/configurar-vault-economia-permissoes-minecraft.md)
- [Como criar rank VIP com tag colorida no servidor Minecraft](https://streethosting.com.br/guias/minecraft/configurar-rank-vip-tag-servidor-minecraft.md)

## Produtos citados

- https://streethosting.com.br/minecraft
- https://streethosting.com.br/minecraft-pro

## Dados estruturados

```json
[
  {
    "@context": "https://schema.org",
    "@type": [
      "Article",
      "TechArticle"
    ],
    "headline": "Como instalar o PlaceholderAPI e usar placeholders nos seus plugins",
    "name": "PlaceholderAPI: como configurar no servidor Minecraft",
    "abstract": "O PlaceholderAPI é a ponte que leva saldo, grupo, ping e TPS de um plugin para outro. Veja como instalar, quais expansões baixar primeiro e como descobrir por que um placeholder aparece cru na tela.",
    "description": "Instale o PlaceholderAPI, baixe expansões pelo eCloud, teste com /papi parse e leve placeholders para TAB, menus, scoreboard e chat do servidor.",
    "datePublished": "2026-09-28",
    "dateModified": "2026-09-28",
    "author": {
      "@type": "Organization",
      "name": "Equipe StreetHosting"
    },
    "publisher": {
      "@type": "Organization",
      "name": "StreetHosting",
      "url": "https://streethosting.com.br"
    },
    "inLanguage": "pt-BR",
    "mainEntityOfPage": {
      "@type": "WebPage",
      "@id": "https://streethosting.com.br/guias/minecraft/configurar-placeholderapi-minecraft"
    }
  },
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "Para que serve o PlaceholderAPI?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Ele leva informações de um plugin para outro. O saldo do Vault, o prefixo do LuckPerms ou o TPS do servidor viram textos como %vault_eco_balance%, e plugins de TAB, menu, scoreboard e chat trocam esse texto pelo valor na hora de mostrar para o jogador."
        }
      },
      {
        "@type": "Question",
        "name": "Como baixar expansões do PlaceholderAPI?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Use /papi ecloud download seguido do nome da expansão, por exemplo Player, Server ou Vault, e depois rode /papi reload para registrar. Algumas expansões já vêm dentro do próprio plugin e não precisam de download. Confira o resultado com /papi list."
        }
      },
      {
        "@type": "Question",
        "name": "Por que o placeholder aparece com as porcentagens em vez do valor?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Teste primeiro com /papi parse me. Se aparecer cru ali, falta a expansão, o nome está digitado errado ou o plugin de que ela depende não está ativo. Se o parse funcionar e o texto cru aparecer só no TAB ou no menu, o problema está no plugin que exibe."
        }
      },
      {
        "@type": "Question",
        "name": "Dá para usar o PlaceholderAPI sem o eCloud?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Dá. Coloque cloud_enabled como false no config.yml do PlaceholderAPI e instale as expansões manualmente, copiando os jars para a pasta expansions e rodando /papi reload. É a escolha de quem prefere controlar tudo o que entra no servidor."
        }
      },
      {
        "@type": "Question",
        "name": "O PlaceholderAPI funciona em servidor Fabric?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Não. Ele é um plugin para Paper e Spigot. No Fabric existe um projeto de placeholders separado, feito para mods, com sintaxe e lista de placeholders próprias. Se a sua configuração depende muito do PlaceholderAPI, o caminho natural é continuar no Paper."
        }
      }
    ]
  }
]
```