API

Documentação completa da API do plugin yRankup, incluindo métodos para gerenciar ranks de jogador, prestígios, moeda fragmentos e manipulação de eventos de progressão de rank.

Obtendo a Instância da API

Para acessar a API yRankup, recupere a instância do serviço Bukkit:

import br.com.ystoreplugins.product.yrankup.RankupAPIHolder;
import org.bukkit.Bukkit;

RankupAPIHolder rankupAPI = (RankupAPIHolder) Bukkit.getServicesManager()
    .load(RankupAPIHolder.class);

if (rankupAPI != null) {
    // API está pronta para usar
}

Alternatively, if you're using Maven and have the plugin as a dependency:

import com.ystoreplugins.yrankup.api.RankupAPI;

RankupAPI rankupAPI = new RankupAPI();

Métodos Disponíveis

getPlayer() (Player overload)

Recupera o detentor de dados de rank para um objeto de jogador.

Parameters:

p (Player) - A instância do Player

Returns:

PlayerRank - Objeto contendo todos os dados de rank do jogador, ou null se não encontrado

Observations:

Recupera de dados de jogador em cache
Retorna null se dados do jogador não estão carregados
Use isto para acesso direto ao objeto Player

PlayerRank playerRank = rankupAPI.getPlayer(player);
if (playerRank != null) {
    // Acessar dados de rank do jogador
}

getPlayer() (String overload)

Recupera o detentor de dados de rank para um jogador pelo nome de usuário.

Parameters:

p (String) - O nome de usuário do jogador

Returns:

PlayerRank - Objeto contendo todos os dados de rank do jogador, ou null se não encontrado

Observations:

Recupera de dados de jogador em cache
Retorna null se o jogador nunca fez login
Útil para pesquisas de jogadores offline

PlayerRank playerRank = rankupAPI.getPlayer("PlayerName");
if (playerRank != null) {
    // Acessar dados de rank do jogador
}

getRank()

Recupera o rank atual de um jogador.

Parameters:

p (Player) - A instância do Player

Returns:

Rank - The player's current rank

Observations:

Obtém o rank "real" que o jogador atualmente tem
Retorna null se o jogador não tem rank

Rank currentRank = rankupAPI.getRank(player);
if (currentRank != null) {
    System.out.println("Rank atual: " + currentRank);
}

getNextRank()

Recupera o próximo rank disponível para um jogador avançar.

Parameters:

p (Player) - A instância do Player

Returns:

Rank - The next rank in progression, or null if no next rank exists

Observations:

Mostra que rank o jogador pode subir para
Retorna null se o jogador está no rank máximo

Rank nextRank = rankupAPI.getNextRank(player);
if (nextRank != null) {
    System.out.println("Próximo rank: " + nextRank);
}

getPrestigio()

Recupera o detentor do nível de prestígio para um jogador.

Parameters:

p (Player) - A instância do Player

Returns:

PrestigioHolder - Prestige data, or null if not available

Observations:

Retorna null se o sistema de prestígio não está ativado
Representa o nível de prestígio atual do jogador
Prestígios são recompensas após atingir o rank máximo

PrestigioHolder prestigio = rankupAPI.getPrestigio(player);
if (prestigio != null) {
    // Acessar dados de prestígio
}

getNextPrestigio()

Recupera o próximo nível de prestígio disponível para um jogador.

Parameters:

p (Player) - A instância do Player

Returns:

PrestigioHolder - Next prestige data, or null if not available

Observations:

Retorna null se o sistema de prestígio não está ativado
Mostra qual prestígio o jogador pode avançar para
Null se o jogador está no prestígio máximo

PrestigioHolder nextPrestigio = rankupAPI.getNextPrestigio(player);
if (nextPrestigio != null) {
    System.out.println("Próximo prestígio: " + nextPrestigio);
}

getFragmentos()

Recupera a quantidade de Fragmentos (moeda) que um jogador tem.

Parameters:

p (Player) - A instância do Player

Returns:

double - The amount of Fragmentos

Observations:

Fragmentos é a moeda de rankup
Retorna 0 se o jogador não tem fragmentos
Seguro chamar várias vezes

double fragments = rankupAPI.getFragmentos(player);
System.out.println("O jogador tem " + fragments + " fragmentos");

hasRank()

Verifica se um jogador tem um rank.

Parameters:

p (Player) - A instância do Player

Returns:

boolean - true if player has a rank, false otherwise

Observations:

Retorna false para jogadores sem rank
Útil para verificar o estado inicial de progressão

if (rankupAPI.hasRank(player)) {
    System.out.println("O jogador tem a rank");
}

hasPrestigio()

Verifica se um jogador tem um nível de prestígio.

Parameters:

p (Player) - A instância do Player

Returns:

boolean - true if player has prestige, false otherwise

Observations:

Respeita a configuração de prestígio MÁXIMO
Retorna false se o sistema de prestígio está desativado
Retorna false se a contagem de prestígio é 0

if (rankupAPI.hasPrestigio(player)) {
    System.out.println("O jogador tem prestige!");
}

hasNextRank()

Verifica se um jogador tem um próximo rank para subir.

Parameters:

p (Player) - A instância do Player

Returns:

boolean - true if next rank exists, false if at max rank

Observations:

Retorna false se o jogador está no rank máximo
Útil para verificações de disponibilidade de rankup

if (rankupAPI.hasNextRank(player)) {
    System.out.println("O jogador pode rankup");
}

hasNextPrestigio()

Verifica se um jogador tem um próximo prestígio para avançar.

Parameters:

p (Player) - A instância do Player

Returns:

boolean - true if next prestige exists, false if at max prestige

Observations:

Respeita a configuração de prestígio MÁXIMO
Retorna false se o sistema de prestígio está desativado
Retorna false se o jogador está no prestígio máximo

if (rankupAPI.hasNextPrestigio(player)) {
    System.out.println("O jogador pode alcançar o próximo prestígio");
}

canRankup()

Verifica se um jogador tem moeda suficiente para rankup.

Parameters:

p (Player) - A instância do Player

Returns:

boolean - true if player can rankup, false otherwise

Observations:

Verifica o saldo de fragmentos e disponibilidade do próximo rank
Retorna false se o jogador não tem moeda
Retorna false se nenhum próximo rank existe

if (rankupAPI.canRankup(player)) {
    System.out.println("O jogador pode rankup now!");
}

setFragmentos()

Define a quantidade exata de Fragmentos que um jogador tem.

Parameters:

p (Player) - A instância do Player
value (double) - The amount to set

Observations:

Substitui a quantidade atual completamente
Pode ser usado para ajustes ou correções

rankupAPI.setFragmentos(player, 1000);

removeFragmentos()

Remove uma quantidade específica de Fragmentos de um jogador.

Parameters:

p (Player) - A instância do Player
value (double) - The amount to remove

Observations:

Subtrai do saldo atual
Não impede valores negativos (use verificações se necessário)

rankupAPI.removeFragmentos(player, 500);

addFragmentos()

Adiciona uma quantidade específica de Fragmentos a um jogador.

Parameters:

p (Player) - A instância do Player
value (double) - The amount to add

Observations:

Adiciona ao saldo atual
Aciona FragmentosGainEvent

rankupAPI.addFragmentos(player, 250);

getHeadItem()

Cria um ItemStack de uma cabeça com lore de quantidade personalizada.

Parameters:

head (String) - The head identifier
amount (double) - The amount to display in lore

Returns:

ItemStack - Formatted head item with amount in lore

Observations:

Clona o item de cabeça base
Substitui placeholder {amount} em lore
Define tag NBT com dados de quantidade
Útil para exibir cabeças colecionáveis

ItemStack headItem = rankupAPI.getHeadItem("legendary_head", 5);
player.getInventory().addItem(headItem);

Estruturas de Dados

PlayerRank

Contém todos os dados relacionados a rank para um jogador. Holds:

Informações de rank atual
Próximo rank para subir
Fragmentos (currency) balance
Prestige level
Histórico de progressão de rank

Rank

Representa um nível de rank no sistema. Contains:

Identificador e nome de rank
Cor de exibição e prefixo
Custo em Fragmentos
Nível de rank/posição

RankHolder

Contém informações de rank para eventos. Similar a Rank com:

Rank identifier
Rank position
Requisitos de desbloqueio

PrestigioHolder

Representa um nível de prestígio. Contains:

Nível de prestígio/camada
Recompensas de prestígio
Requisitos de prestígio

Eventos

FragmentosGainEvent

Acionado quando um jogador ganha Fragmentos. Este evento é cancelável*.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getQuantia() - Retorna a quantidade de Fragmentos sendo ganha
setQuantia(double) - Modifique a quantidade de ganho
getBonus() - Retorna qualquer multiplicador de bônus
setBonus(double) - Modifique o bônus
isCancelled() - Verifique se o evento foi cancelado
setCancelled(boolean) - Cancele o ganho

Observations:

Dispara quando Fragmentos são adicionados ao saldo do jogador
Bônus representa multiplicadores ou bônus aplicados
Cancelar impede ganho de moeda

Example:

@EventHandler
public void onFragmentosGain(FragmentosGainEvent event) {
    if (event.isCancelled()) return;
    
    Player player = event.getPlayer();
    double amount = event.getQuantia();
    
    System.out.println(player.getName() + " gained " + amount + " fragmentos");
}

HeadGainEvent

Triggered when a player obtains a collectible head. Este evento é cancelável*.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getHeadType() - Returns the head identifier
getQuantia() - Returns the quantity obtained
setQuantia(double) - Modify the quantity
getEntity() - Returns the entity that dropped the head
isCancelled() - Verifique se o evento foi cancelado
setCancelled(boolean) - Cancel the head gain

Observations:

Fires when a head item is obtained (usually from entity death)
Entity reference shows what killed/dropped the head
Cancelling prevents head addition to inventory

Example:

@EventHandler
public void onHeadGain(HeadGainEvent event) {
    if (event.isCancelled()) return;
    
    Player player = event.getPlayer();
    String headType = event.getHeadType();
    
    System.out.println(player.getName() + " obtained head: " + headType);
}

RankUpEvent

Triggered when a player rankups. Este evento é cancelável*.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getRank() - Returns the RankHolder of the new rank
setRank(RankHolder) - Modify the rank being advanced to
getDesconto() - Returns any discount applied to the cost
setDesconto(double) - Modify the discount amount
isCancelled() - Verifique se o evento foi cancelado
setCancelled(boolean) - Cancel the rankup

Observations:

Fires when player successfully rankups
Desconto represents cost reduction/discount
Cancelling prevents rank advancement
Rank can be modified before advancement

Example:

@EventHandler
public void onRankUp(RankUpEvent event) {
    if (event.isCancelled()) return;
    
    Player player = event.getPlayer();
    RankHolder rank = event.getRank();
    
    System.out.println(player.getName() + " rankuped to " + rank);
}

Melhores Práticas

Always check for null when retrieving player data
Validate rank availability using hasNextRank() before rankup attempts
Listen to events for tracking rank progression
Handle currency operations carefully to prevent balancing issues
Cache player data if accessing multiple times rapidly
Validate prestige configuration before prestige checks
Use FragmentosGainEvent for economy integrations

Exemplos de Uso

Example 1: Getting Player Rank Information

RankupAPIHolder rankupAPI = (RankupAPIHolder) Bukkit.getServicesManager()
    .load(RankupAPIHolder.class);

PlayerRank playerRank = rankupAPI.getPlayer(player);
if (playerRank != null) {
    Rank current = rankupAPI.getRank(player);
    Rank next = rankupAPI.getNextRank(player);
    
    System.out.println("Current: " + current + ", Next: " + next);
}

Example 2: Checking Rankup Eligibility

RankupAPIHolder rankupAPI = (RankupAPIHolder) Bukkit.getServicesManager()
    .load(RankupAPIHolder.class);

if (rankupAPI.hasNextRank(player) && rankupAPI.canRankup(player)) {
    player.sendMessage("§aYou can rankup!");
} else {
    player.sendMessage("§cYou need more fragmentos");
}

Example 3: Tracking Fragmentos Gains

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.yrankup.event.FragmentosGainEvent;

public class FragmentosTracker implements Listener {
    
    @EventHandler
    public void onFragmentosGain(FragmentosGainEvent event) {
        Player player = event.getPlayer();
        double amount = event.getQuantia();
        
        System.out.println("[FRAGMENTOS] " + player.getName() + 
            " gained " + amount);
    }
}

Example 4: Modifying Fragmentos Gain with Bonus

@EventHandler
public void onFragmentosGain(FragmentosGainEvent event) {
    Player player = event.getPlayer();
    double bonus = event.getBonus();
    
    // Apply VIP bonus
    if (player.hasPermission("rankup.vip")) {
        double newAmount = event.getQuantia() * 1.5;
        event.setQuantia(newAmount);
        event.setBonus(1.5);
    }
}

Example 5: Head Collection Tracking

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.yrankup.event.HeadGainEvent;

public class HeadCollector implements Listener {
    
    @EventHandler
    public void onHeadGain(HeadGainEvent event) {
        Player player = event.getPlayer();
        String headType = event.getHeadType();
        
        System.out.println("[HEAD] " + player.getName() + 
            " collected: " + headType);
    }
}

Example 6: Rankup Celebration

@EventHandler
public void onRankUp(RankUpEvent event) {
    if (event.isCancelled()) return;
    
    Player player = event.getPlayer();
    RankHolder rank = event.getRank();
    
    player.sendMessage("§a§l✓ RANKUP! You are now: " + rank);
    player.playSound(player.getLocation(), 
        org.bukkit.Sound.UI_TOAST_CHALLENGE_COMPLETE, 1.0f, 1.0f);
    
    // Notify online players
    org.bukkit.Bukkit.broadcastMessage("§6" + player.getName() + 
        " §ahas rankuped to §6" + rank);
}

Example 7: Economy Integration - Fragmentos Tax

@EventHandler
public void onFragmentosGain(FragmentosGainEvent event) {
    if (event.isCancelled()) return;
    
    double amount = event.getQuantia();
    double tax = amount * 0.1; // 10% tax
    
    event.setQuantia(amount - tax);
    System.out.println("Tax applied: " + tax);
}

Example 8: Prestige Status Display

RankupAPIHolder rankupAPI = (RankupAPIHolder) Bukkit.getServicesManager()
    .load(RankupAPIHolder.class);

if (rankupAPI.hasPrestigio(player)) {
    player.sendMessage("§6Prestige Status: " + 
        rankupAPI.getPrestigio(player));
} else {
    player.sendMessage("§cNo prestige yet");
}

Example 9: Custom Rankup Command

public class CustomRankupCommand implements CommandExecutor {
    
    private final RankupAPIHolder rankupAPI;
    
    public CustomRankupCommand(RankupAPIHolder rankupAPI) {
        this.rankupAPI = rankupAPI;
    }
    
    @Override
    public boolean onCommand(CommandSender sender, Command cmd, 
                            String label, String[] args) {
        if (!(sender instanceof Player)) return false;
        
        Player player = (Player) sender;
        
        if (!rankupAPI.canRankup(player)) {
            player.sendMessage("§cYou cannot rankup right now");
            return true;
        }
        
        Rank nextRank = rankupAPI.getNextRank(player);
        player.sendMessage("§aYou rankuped to: " + nextRank);
        
        return true;
    }
}

Example 10: Comprehensive Rankup Statistics

public class RankupStatistics implements Listener {
    
    private final JavaPlugin plugin;
    private final Map<String, Integer> rankupsPerPlayer = new HashMap<>();
    private final Map<String, Double> fragmentsPerPlayer = new HashMap<>();
    
    public RankupStatistics(JavaPlugin plugin) {
        this.plugin = plugin;
    }
    
    @EventHandler
    public void onRankUp(RankUpEvent event) {
        if (event.isCancelled()) return;
        
        String playerName = event.getPlayer().getName();
        int rankups = rankupsPerPlayer.getOrDefault(playerName, 0) + 1;
        rankupsPerPlayer.put(playerName, rankups);
        
        plugin.getLogger().info("[STATS] " + playerName + 
            " - Total rankups: " + rankups);
    }
    
    @EventHandler
    public void onFragmentosGain(FragmentosGainEvent event) {
        if (event.isCancelled()) return;
        
        String playerName = event.getPlayer().getName();
        double total = fragmentsPerPlayer.getOrDefault(playerName, 0.0) + 
            event.getQuantia();
        fragmentsPerPlayer.put(playerName, total);
    }
    
    public void printStatistics() {
        System.out.println("=== Rankup Statistics ===");
        rankupsPerPlayer.forEach((player, count) -> {
            System.out.println(player + ": " + count + " rankups");
        });
    }
}

Nesta página