P_TopJogadores

Top-player ranking plugin for Paper, with support for PlaceholderAPI, Citizens, and DecentHolograms.

What it does

• Calculates category-based rankings using placeholders.
• Exposes rankings through PlaceholderAPI.
• Creates Citizens NPCs by ranking position.
• Creates DecentHolograms holograms.
• Displays an automatic hologram above the NPC with title and subtitle.
• Supports NPC click commands executed as console or player.
• Supports compact values such as k, m, b, and t.

Requirements

• Paper 1.21+
• PlaceholderAPI
• Citizens
• DecentHolograms

Commands

Main command

/ptop
/ptop reload
/ptop recalcular
/ptop npc criar <category> <position> [npcName]
/ptop npc remover <category> [position]
/ptop holograma criar <category> [height]
/ptop holograma remover <category>

Permissions

• ptop.admin
• ptop.reload
• ptop.recalcular
• ptop.npc
• ptop.holograma

PlaceholderAPI

The expansion identifier is p_topjogadores.

Category ranking

%p_topjogadores_top_<position>_<category>_<field>%

Available fields:

• nome
• valor
• uuid
• posicao

Examples:

%p_topjogadores_top_1_kills_nome%
%p_topjogadores_top_1_kills_valor%
%p_topjogadores_top_1_kills_uuid%
%p_topjogadores_top_1_kills_posicao%

Player data in a category

%p_topjogadores_jogador_<category>_<field>%

Available fields:

• posicao
• valor

Examples:

%p_topjogadores_jogador_kills_posicao%
%p_topjogadores_jogador_kills_valor%

Category data

%p_topjogadores_categoria_<category>_<field>%

Available fields:

• titulo
• placeholder
• limite

Examples:

%p_topjogadores_categoria_kills_titulo%
%p_topjogadores_categoria_kills_placeholder%
%p_topjogadores_categoria_kills_limite%

Category configuration

Each category is defined in categorias.yml.

Example:

categorias:
  kills:
    habilitada: true
    placeholder: '%statistic_player_kills%'
    titulo: '&cTop Kills'
    formato-valor: '#,##0'
    formato-compacto: false
    ordem-decrescente: true
    npc-holograma:
      habilitado: true
      altura: 2.35
      titulo: '&cTop %posicao%'
      subtitulo: '&f%nome% &7- &f%valor%'
    limite: 10
    mundo-especifico: false
    mundos-permitidos: []
    linhas:
      - '&8--------------------'
      - '&f1. &e%top_1_nome% &7- &f%top_1_valor%'
      - '&f2. &e%top_2_nome% &7- &f%top_2_valor%'
      - '&8--------------------'
    comandos-clique:
      esquerdo: []
      direito:
        - '[console] msg %player% &aYou clicked the kills ranking NPC!'

NPC hologram

The automatic hologram above the NPC uses:

• npc-holograma.habilitado
• npc-holograma.altura
• npc-holograma.titulo
• npc-holograma.subtitulo

These values support the plugin placeholders:

• %categoria%
• %posicao%
• %nome%
• %valor%

titulo and subtitulo support \n for line breaks.

Manual ranking hologram

The command /ptop holograma criar <category> [height] creates the ranking hologram at the chosen location.

Global hologram settings:

• holograma.altura-padrao
• holograma.espaco-entre-linhas
• holograma.deslocamento-extra

NPC clicks

In comandos-clique.direito and comandos-clique.esquerdo, each line can start with:

• [console] to run as console
• [jogador] to run as the player who clicked

If no prefix is provided, the default is console.

Example:

comandos-clique:
  direito:
    - '[console] give %player% diamond 1'
    - '[jogador] spawn'

Global configuration

File: config.yml

geral:
  prefixo: '&8[&6P_TopJogadores&8] '
  debug: false
  casas-decimais-padrao: 2
  placeholder-vazio: '&7Ninguem'
  valor-vazio: '0'

atualizacao:
  ranking-segundos: 120
  visual-segundos: 20
  atualizar-ao-entrar: true
  atualizar-no-enable: true
  max-jogadores-por-ciclo: 5000

performance:
  cache-placeholders-segundos: 60
  ignorar-jogadores-sem-dado: true
  ignorar-valor-zero: false

integracoes:
  placeholderapi-obrigatorio-para-rankings: true
  citizens: true
  decentholograms: true

holograma:
  altura-padrao: 2.3
  espaco-entre-linhas: 0.28
  deslocamento-extra: 0.8

Notes

• If placeholderapi-obrigatorio-para-rankings is true, rankings only recalculate when PlaceholderAPI is available.
• If formato-compacto is true, the category value is displayed as k/m/b/t.
• The NPC uses the ranking player's skin when possible.
• If no NPC or hologram exists at the requested position during removal, the plugin reports that instead of pretending it was removed.

P_TopJogadores

Plugin de ranking/top jogadores para Paper, com suporte a PlaceholderAPI, Citizens e DecentHolograms.

O que o plugin faz

• Calcula rankings por categoria usando placeholders.
• Exibe rankings via PlaceholderAPI.
• Cria NPCs do Citizens por posicao do ranking.
• Cria hologramas do DecentHolograms.
• Exibe um holograma automatico acima do NPC com titulo e subtitulo.
• Permite comandos no clique do NPC com execucao como console ou jogador.
• Suporta valores compactos como k, m, b e t.

Dependencias

• Paper 1.21+
• PlaceholderAPI
• Citizens
• DecentHolograms

Comandos

Comando principal

/ptop
/ptop reload
/ptop recalcular
/ptop npc criar <categoria> <posicao> [nomeNpc]
/ptop npc remover <categoria> [posicao]
/ptop holograma criar <categoria> [altura]
/ptop holograma remover <categoria>

Permissoes

• ptop.admin
• ptop.reload
• ptop.recalcular
• ptop.npc
• ptop.holograma

PlaceholderAPI

O identificador da expansion e p_topjogadores.

Ranking da categoria

%p_topjogadores_top_<posicao>_<categoria>_<campo>%

Campos disponiveis:

• nome
• valor
• uuid
• posicao

Exemplos:

%p_topjogadores_top_1_kills_nome%
%p_topjogadores_top_1_kills_valor%
%p_topjogadores_top_1_kills_uuid%
%p_topjogadores_top_1_kills_posicao%

Dados do jogador na categoria

%p_topjogadores_jogador_<categoria>_<campo>%

Campos disponiveis:

• posicao
• valor

Exemplos:

%p_topjogadores_jogador_kills_posicao%
%p_topjogadores_jogador_kills_valor%

Dados da categoria

%p_topjogadores_categoria_<categoria>_<campo>%

Campos disponiveis:

• titulo
• placeholder
• limite

Exemplos:

%p_topjogadores_categoria_kills_titulo%
%p_topjogadores_categoria_kills_placeholder%
%p_topjogadores_categoria_kills_limite%

Configuracao de categorias

Cada categoria fica em categorias.yml.

Exemplo:

categorias:
  kills:
    habilitada: true
    placeholder: '%statistic_player_kills%'
    titulo: '&cTop Kills'
    formato-valor: '#,##0'
    formato-compacto: false
    ordem-decrescente: true
    npc-holograma:
      habilitado: true
      altura: 2.35
      titulo: '&cTop %posicao%'
      subtitulo: '&f%nome% &7- &f%valor%'
    limite: 10
    mundo-especifico: false
    mundos-permitidos: []
    linhas:
      - '&8--------------------'
      - '&f1. &e%top_1_nome% &7- &f%top_1_valor%'
      - '&f2. &e%top_2_nome% &7- &f%top_2_valor%'
      - '&8--------------------'
    comandos-clique:
      esquerdo: []
      direito:
        - '[console] msg %player% &aVoce clicou no NPC do ranking de kills!'

Holograma do NPC

O holograma automatico acima do NPC usa as chaves:

• npc-holograma.habilitado
• npc-holograma.altura
• npc-holograma.titulo
• npc-holograma.subtitulo

Esses textos aceitam placeholders internos do plugin:

• %categoria%
• %posicao%
• %nome%
• %valor%

Os campos titulo e subtitulo aceitam \n para quebrar linha.

Holograma manual do ranking

O comando /ptop holograma criar <categoria> [altura] cria o holograma do ranking na posicao informada.

Configuracao global:

• holograma.altura-padrao
• holograma.espaco-entre-linhas
• holograma.deslocamento-extra

Clique no NPC

Em comandos-clique.direito e comandos-clique.esquerdo, cada linha pode comecar com:

• [console] para executar no console
• [jogador] para executar como o jogador que clicou

Se nenhum prefixo for informado, o padrao atual e console.

Exemplo:

comandos-clique:
  direito:
    - '[console] give %player% diamond 1'
    - '[jogador] spawn'

Configuracao global

Arquivo config.yml:

geral:
  prefixo: '&8[&6P_TopJogadores&8] '
  debug: false
  casas-decimais-padrao: 2
  placeholder-vazio: '&7Ninguem'
  valor-vazio: '0'

atualizacao:
  ranking-segundos: 120
  visual-segundos: 20
  atualizar-ao-entrar: true
  atualizar-no-enable: true
  max-jogadores-por-ciclo: 5000

performance:
  cache-placeholders-segundos: 60
  ignorar-jogadores-sem-dado: true
  ignorar-valor-zero: false

integracoes:
  placeholderapi-obrigatorio-para-rankings: true
  citizens: true
  decentholograms: true

holograma:
  altura-padrao: 2.3
  espaco-entre-linhas: 0.28
  deslocamento-extra: 0.8

Observacoes

• Se placeholderapi-obrigatorio-para-rankings estiver true, os rankings so recalculam com PlaceholderAPI ativo.
• Se formato-compacto estiver true, o valor da categoria sai no formato k/m/b/t.
• O NPC usa a skin do jogador do ranking quando possivel.
• Se nao houver NPC ou holograma spawnado na posicao informada na remocao, o plugin avisa isso em vez de confirmar remocao.