API

A API fornece uma interface pública para desenvolvedores integrarem seus plugins ao sistema de kills do yKillSystem, permitindo consultar dados de kills e monitorar mudanças de XP.

Obtendo a instância da API

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

Exemplo:

KillSystemAPIHolder killSystemAPI;

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

Métodos disponíveis

getPlayer(String playerName)

Recupera os dados de kills de um jogador.

PlayerKillHolder playerKills = killSystemAPI.getPlayer("Steve");

Parâmetros:

playerName - Nome do jogador

Retorno:

PlayerKillHolder contendo dados de kills do jogador ou null se não encontrado

Observações:

Recupera dados em cache do sistema principal
Retorna null se o jogador não possuir dados de kills registrados
O resultado é recuperado diretamente do cache, não do banco de dados

Eventos disponíveis

PlayerXpChangedEvent

Disparado quando a XP de um jogador muda.

@EventHandler
public void onPlayerXpChanged(PlayerXpChangedEvent event) {
    Player player = event.getPlayer();
    double oldXp = event.getOldAmount();
    double newXp = event.getNewAmount();
    double difference = newXp - oldXp;
    
    if (difference > 0) {
        player.sendMessage("Você ganhou " + difference + " XP!");
    }
}

Propriedades:

Player player - Jogador cuja XP mudou
double oldAmount - Valor anterior de XP
double newAmount - Novo valor de XP

Métodos:

getPlayer() - Obtém o jogador
getOldAmount() - Obtém XP anterior
getNewAmount() - Obtém novo valor de XP
getHandlers() - Obtém lista de handlers
getHandlerList() - Obtém lista estática de handlers

Observações:

Evento não cancelável (mudança já foi processada)
Disparado após qualquer mudança de XP
Útil para notificações e reações em tempo real

Estrutura de dados

PlayerKillHolder

Representa os dados de kills de um jogador.

Propriedades principais:

Total de kills
Total de deaths
Nível de kill
XP acumulada
Razão kill/death
Histórico de kills
Streak de kills

Boas práticas

Sempre verifique null ao recuperar dados de um jogador
Use eventos para notificações em tempo real
Evite chamadas excessivas em eventos de alta frequência
Armazene dados consultados quando possível
Calcule diferenças de XP para mensagens significativas

Exemplos de uso

Verificar dados de kills do jogador

PlayerKillHolder playerKills = killSystemAPI.getPlayer("Steve");
if (playerKills != null) {
    // Dados de kills encontrados
    System.out.println("Total de kills: " + playerKills.getTotalKills());
}

Notificar ganho de XP

@EventHandler
public void onPlayerXpChanged(PlayerXpChangedEvent event) {
    Player player = event.getPlayer();
    double oldXp = event.getOldAmount();
    double newXp = event.getNewAmount();
    
    if (newXp > oldXp) {
        double xpGained = newXp - oldXp;
        player.sendMessage("§a+§f" + xpGained + " XP");
    }
}

Sistema de level up

@EventHandler
public void onPlayerXpChanged(PlayerXpChangedEvent event) {
    Player player = event.getPlayer();
    double oldXp = event.getOldAmount();
    double newXp = event.getNewAmount();
    
    int oldLevel = getLevel(oldXp);
    int newLevel = getLevel(newXp);
    
    if (newLevel > oldLevel) {
        player.sendMessage("§6§l★ LEVEL UP! Nível " + newLevel + "!");
        Bukkit.broadcastMessage("§6" + player.getName() + " atingiu o nível " + newLevel);
    }
}

private int getLevel(double xp) {
    return (int) Math.floor(Math.sqrt(xp / 100));
}

Rastrear progresso de XP

@EventHandler
public void onPlayerXpChanged(PlayerXpChangedEvent event) {
    Player player = event.getPlayer();
    double newXp = event.getNewAmount();
    
    // XP para próximo milestone (1000, 2000, etc)
    long nextMilestone = ((long)(newXp / 1000) + 1) * 1000;
    long remaining = nextMilestone - (long)newXp;
    
    if (remaining < 100) { // Aviso quando perto
        player.sendMessage("§eVocê está a " + remaining + " XP do próximo milestone!");
    }
}

Dashboard de kills

public void showKillsDashboard(Player player) {
    PlayerKillHolder kills = killSystemAPI.getPlayer(player.getName());
    
    player.sendMessage("═══════════════════════════");
    player.sendMessage("ESTATÍSTICAS DE KILLS");
    player.sendMessage("═══════════════════════════");
    
    if (kills != null) {
        player.sendMessage("Total de Kills: " + kills.getTotalKills());
        player.sendMessage("Total de Deaths: " + kills.getTotalDeaths());
        player.sendMessage("K/D Ratio: " + String.format("%.2f", 
            kills.getTotalKills() / (double) Math.max(1, kills.getTotalDeaths())));
    } else {
        player.sendMessage("Nenhum dado registrado");
    }
    
    player.sendMessage("═══════════════════════════");
}

Recompensa por ganho de XP

@EventHandler
public void onPlayerXpChanged(PlayerXpChangedEvent event) {
    Player player = event.getPlayer();
    double oldXp = event.getOldAmount();
    double newXp = event.getNewAmount();
    
    double xpGained = newXp - oldXp;
    if (xpGained > 0) {
        // Dar recompensa baseado em XP
        double reward = xpGained * 10; // 10 moedas por XP
        addBalance(player.getName(), reward);
    }
}

Verificação de ranking

public void checkPlayerRank(Player player) {
    PlayerKillHolder kills = killSystemAPI.getPlayer(player.getName());
    
    if (kills == null) {
        player.sendMessage("Você ainda não tem dados de kills registrados.");
        return;
    }
    
    long totalKills = kills.getTotalKills();
    String rank = "Iniciante";
    
    if (totalKills >= 100) rank = "Veterano";
    if (totalKills >= 500) rank = "Lendário";
    if (totalKills >= 1000) rank = "Imortal";
    
    player.sendMessage("Seu rank: §b" + rank);
}

Sistema de streaks

@EventHandler
public void onPlayerXpChanged(PlayerXpChangedEvent event) {
    Player player = event.getPlayer();
    PlayerKillHolder kills = killSystemAPI.getPlayer(player.getName());
    
    if (kills != null && kills.getKillStreak() > 0) {
        if (kills.getKillStreak() % 5 == 0) {
            player.sendMessage("§c§l⚡ STREAK: " + kills.getKillStreak() + " kills!");
        }
    }
}

Notificação de progresso

@EventHandler
public void onPlayerXpChanged(PlayerXpChangedEvent event) {
    Player player = event.getPlayer();
    double progression = event.getNewAmount();
    
    // Mostrar barra de progresso a cada 500 XP
    if ((long)progression % 500 == 0) {
        player.sendMessage("═══════════════════════════");
        player.sendMessage("XP ATUAL: " + (long)progression);
        player.sendMessage("═══════════════════════════");
    }
}

Integração com título de jogador

@EventHandler
public void onPlayerXpChanged(PlayerXpChangedEvent event) {
    Player player = event.getPlayer();
    double newXp = event.getNewAmount();
    
    int level = (int) Math.floor(Math.sqrt(newXp / 100));
    
    player.sendTitle(
        "§6Level " + level,
        "§f" + String.format("%.0f", newXp) + " XP",
        10, 70, 20
    );
}

Nesta página