API

A API fornece uma interface pública para desenvolvedores integrarem seus plugins ao sistema de rankings/tops do yTops, permitindo consultar valores de rankings, criar rankings customizados e gerenciar dados de tops.

Obtendo a instância da API

A API é exposta através de um BukkitService assim como feito comumente no Vault.

Exemplo:

TopAPIHolder topAPI;

try {
  RegisteredServiceProvider<TopAPIHolder> rsp = Bukkit.getServer().getServicesManager().getRegistration(TopAPIHolder.class);
  return rsp == null ? null : (TopAPIHolder)rsp.getProvider();
} catch (Throwable t) {
  return null;
}

Métodos disponíveis

getTypeList()

Retorna a lista de todos os tipos de rankings disponíveis.

List<String> types = topAPI.getTypeList();

Retorno:

List<String> contendo os nomes de todos os tipos de tops cadastrados
Inclui tipos padrão (KILLS, MONEY, LEVEL, etc) e tops customizados

Exemplo:

List<String> types = topAPI.getTypeList();
types.forEach(type -> System.out.println(type)); // KILLS, MONEY, CUSTOM_TOP, etc

get`(String typeRaw, int index)`

Obtém o valor de um jogador em um ranking específico.

double value = topAPI.get("KILLS", 1);

Parâmetros:

typeRaw - Nome do tipo de ranking (ex: "KILLS", "MONEY")
index - Posição no ranking (começa em 1, não 0)

Retorno:

double representando o valor do jogador naquela posição
Retorna 0.0 se a posição não existir

Observações:

O tipo deve existir e ser válido
O índice deve ser maior que 0
Lança IllegalArgumentException se o tipo não existir

Exemplo:

try {
    double topKills = topAPI.get("KILLS", 1); // Primeiro lugar em kills
    double top10Money = topAPI.get("MONEY", 10); // 10º lugar em money
    System.out.println("Top 1 em kills: " + topKills);
} catch (IllegalArgumentException e) {
    System.out.println("Tipo de ranking inválido!");
}

setup(String name)

Registra um novo tipo de ranking customizado.

topAPI.setup("CUSTOM_FARM");

Parâmetros:

name - Nome único do novo tipo de ranking

Observações:

O nome não pode ser igual a tipos já existentes
Nomes são automaticamente convertidos para maiúsculas
Lança IllegalArgumentException se o nome já existir

Exemplo:

try {
    topAPI.setup("MEUS_PONTOS");
    System.out.println("Novo ranking 'MEUS_PONTOS' criado!");
} catch (IllegalArgumentException e) {
    System.out.println("Ranking com este nome já existe!");
}

update`(String name, HashMap<String, Double> hash)`

Atualiza ou cria um ranking customizado com novos dados.

HashMap<String, Double> dados = new HashMap<>();
dados.put("Player1", 1000.0);
dados.put("Player2", 950.0);
dados.put("Player3", 900.0);
topAPI.update("CUSTOM_FARM", dados);

Parâmetros:

name - Nome do ranking a atualizar
hash - HashMap com <UUID_ou_Nome_Jogador, Valor>

Observações:

Automaticamente ordena os dados em ordem decrescente
Se o ranking não existir, cria um novo
Se existir, sobrescreve os dados
Mantém apenas a ordem mais recente

Exemplo:

HashMap<String, Double> ranking = new HashMap<>();
ranking.put("player1", 5000.0);
ranking.put("player2", 4500.0);
ranking.put("player3", 4000.0);
ranking.put("player4", 3500.0);

// Atualizar ranking
topAPI.update("FARM_POINTS", ranking);

// Dados são automaticamente ordenados por valor (maior para menor)
// player1: 5000
// player2: 4500
// player3: 4000
// player4: 3500

Estrutura de dados

Tipos de Ranking Padrão

O yTops suporta vários tipos de rankings pré-configurados:

KILLS - Ranking de mortes causadas
MONEY - Ranking de dinheiro
LEVEL - Ranking de níveis
DEATHS - Ranking de mortes sofridas
E outros definidos pela configuração

HashMap de Dados

A estrutura usada para armazenar dados de tops é:

HashMap<String, Double> dados = new HashMap<>();
dados.put("player_name_ou_uuid", valor_numerico);

Características:

Chave: Identificador único do jogador (nome ou UUID)
Valor: Número (double) representando o score/valor
Automaticamente mantido em ordem decrescente após update()

Melhores práticas

Sempre valide o tipo de ranking - Use getTypeList() para verificar disponibilidade antes de usar get()
Use try-catch para IllegalArgumentException - Ao usar get() e setup() com nomes de usuários
Crie rankings customizados com nomes únicos - Evite conflitos com tipos padrão
Atualize rankings regularmente - Use update() em intervalos consistentes
Mantenha dados ordenados - A API ordena automaticamente, não altere manualmente
Use UUID quando possível - Para referências persistentes de jogadores
Verifique se a API está disponível - Sempre valide a instância antes de usar
Trate exceções adequadamente - Implemente logs e feedback ao usuário
Sincronize atualizações - Evite race conditions em atualizações simultâneas
Documente rankings customizados - Mantenha registro dos tipos customizados criados

Exemplos de uso

Obter lista de todos os tipos de ranking

List<String> tipos = topAPI.getTypeList();
if (tipos.isEmpty()) {
    System.out.println("Nenhum ranking disponível!");
} else {
    System.out.println("Tipos de ranking disponíveis:");
    tipos.forEach(tipo -> System.out.println("  - " + tipo));
}

Obter valor de um jogador em um ranking

try {
    double topValue = topAPI.get("KILLS", 1);
    double playerPosition = topAPI.get("KILLS", 5);
    
    System.out.println("Valor do 1º lugar: " + topValue);
    System.out.println("Valor do 5º lugar: " + playerPosition);
} catch (IllegalArgumentException e) {
    System.out.println("Ranking não encontrado: " + e.getMessage());
}

Criar um ranking customizado

try {
    topAPI.setup("PONTOS_EVENTOS");
    System.out.println("Novo ranking 'PONTOS_EVENTOS' criado com sucesso!");
} catch (IllegalArgumentException e) {
    System.out.println("Erro ao criar ranking: " + e.getMessage());
}

Atualizar um ranking com dados de jogadores

HashMap<String, Double> pontosEventos = new HashMap<>();
pontosEventos.put("Player1", 5500.0);
pontosEventos.put("Player2", 5200.0);
pontosEventos.put("Player3", 4800.0);
pontosEventos.put("Player4", 4500.0);
pontosEventos.put("Player5", 4200.0);

topAPI.update("PONTOS_EVENTOS", pontosEventos);
System.out.println("Ranking de pontos de eventos atualizado!");

Listar top 10 de um ranking

List<String> tipos = topAPI.getTypeList();

for (String tipo : tipos) {
    System.out.println("Top 10 - " + tipo + ":");
    for (int i = 1; i <= 10; i++) {
        double valor = topAPI.get(tipo, i);
        if (valor > 0) {
            System.out.println(i + "º lugar: " + valor);
        }
    }
}

Integrar evento de morte para atualizar ranking

@EventHandler
public void onPlayerDeath(PlayerDeathEvent event) {
    Player killer = event.getEntity().getKiller();
    
    if (killer != null) {
        // Atualizar ranking de kills
        double killsValue = topAPI.get("KILLS", 1) + 1;
        
        HashMap<String, Double> kills = new HashMap<>();
        kills.put(killer.getName(), killsValue);
        
        topAPI.update("KILLS", kills);
    }
}

Sistema de ranking customizado para eventos

public class EventoManager {
    private TopAPIHolder topAPI;
    private Map<String, Double> pontuacao = new HashMap<>();
    
    public EventoManager(TopAPIHolder topAPI) {
        this.topAPI = topAPI;
        try {
            topAPI.setup("EVENTO_PRIMAVERA");
        } catch (IllegalArgumentException e) {
            // Ranking já existe
        }
    }
    
    public void adicionarPontos(String jogador, double pontos) {
        pontuacao.put(jogador, pontuacao.getOrDefault(jogador, 0.0) + pontos);
        atualizarRanking();
    }
    
    private void atualizarRanking() {
        topAPI.update("EVENTO_PRIMAVERA", new HashMap<>(pontuacao));
    }
    
    public void exibirTop5() {
        System.out.println("Top 5 - Evento Primavera:");
        for (int i = 1; i <= 5; i++) {
            double valor = topAPI.get("EVENTO_PRIMAVERA", i);
            if (valor > 0) {
                System.out.println(i + "º lugar: " + valor + " pontos");
            }
        }
    }
}

Sincronizar ranking com banco de dados

public class RankingSyncTask extends BukkitRunnable {
    private TopAPIHolder topAPI;
    private Database database;
    
    public RankingSyncTask(TopAPIHolder topAPI, Database database) {
        this.topAPI = topAPI;
        this.database = database;
    }
    
    @Override
    public void run() {
        try {
            // Obter dados do banco de dados
            HashMap<String, Double> dadosBanco = database.carregarTodos();
            
            // Atualizar todos os tipos de ranking
            for (String tipo : topAPI.getTypeList()) {
                HashMap<String, Double> dados = database.carregarPorTipo(tipo);
                topAPI.update(tipo, dados);
            }
            
            System.out.println("Rankings sincronizados com sucesso!");
        } catch (Exception e) {
            System.err.println("Erro ao sincronizar rankings: " + e.getMessage());
        }
    }
}

// Executar a cada 5 minutos
new RankingSyncTask(topAPI, database).runTaskTimerAsynchronously(plugin, 0, 6000);

Comando para exibir ranking para jogador

@Command(name = "top")
public void topCommand(Player player, String[] args) {
    if (args.length < 1) {
        player.sendMessage("§cUso: /top <tipo>");
        return;
    }
    
    String tipo = args[0].toUpperCase();
    List<String> tipos = topAPI.getTypeList();
    
    if (!tipos.contains(tipo)) {
        player.sendMessage("§cTipo de ranking não encontrado!");
        player.sendMessage("§eTipos disponíveis: " + String.join(", ", tipos));
        return;
    }
    
    player.sendMessage("§e========== TOP 10 - " + tipo + " ==========");
    for (int i = 1; i <= 10; i++) {
        double valor = topAPI.get(tipo, i);
        if (valor > 0) {
            player.sendMessage(String.format("§e%2d§f. %,.2f", i, valor));
        }
    }
}

Validar acesso à API

public TopAPIHolder obterTopAPI() {
    try {
        RegisteredServiceProvider<TopAPIHolder> rsp = 
            Bukkit.getServer().getServicesManager()
                  .getRegistration(TopAPIHolder.class);
        
        if (rsp == null) {
            Bukkit.getLogger().warning("yTops não está instalado!");
            return null;
        }
        
        return rsp.getProvider();
    } catch (Throwable t) {
        Bukkit.getLogger().severe("Erro ao obter TopAPI: " + t.getMessage());
        return null;
    }
}

Nesta página