API

A API fornece uma interface pública para desenvolvedores integrarem seus plugins ao sistema de economia do yEconomy, permitindo gerenciar contas, saldos e consultar rankings.

Obtendo a instância da API

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

Exemplo:

EconomyAPIHolder economyAPI;

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

Métodos disponíveis

hasAccount(String playerName)

Verifica se um jogador possui conta na economia.

boolean hasAccount = economyAPI.hasAccount("Steve");

Parâmetros:

playerName - Nome do jogador

Retorno:

true se o jogador possui conta, false caso contrário

Observações:

Verifica se a conta está em cache
Considera configuração de transações offline
Método sobrecarregado (veja abaixo)

hasAccount(String playerName, boolean check)

Verifica se um jogador possui conta com verificação customizável.

boolean hasAccount = economyAPI.hasAccount("Steve", false);

Parâmetros:

playerName - Nome do jogador
check - Se true, verifica se jogador está online (respeitando configurações)

Retorno:

true se o jogador possui conta, false caso contrário

Observações:

Quando check=true, respeita configuração generalOfflineTransactions
Quando check=false, permite transações offline
Use check=false para operações administrativas

getAccount(String playerName)

Recupera a conta de um jogador.

Account account = economyAPI.getAccount("Steve");

Parâmetros:

playerName - Nome do jogador

Retorno:

Objeto Account ou null se não encontrado

Observações:

Retorna null se hasAccount() for false
Acesso direto aos dados da conta

getBalance(String playerName)

Obtém o saldo em moeda de um jogador.

double balance = economyAPI.getBalance("Steve");

Parâmetros:

playerName - Nome do jogador

Retorno:

Valor double do saldo (0.0 se não tiver conta)

Observações:

Retorna 0 se o jogador não tiver conta
Seguro contra null
Rápido para simples consultas de saldo

set(String playerName, double amount)

Define o saldo de um jogador.

economyAPI.set("Steve", 5000.0);

Parâmetros:

playerName - Nome do jogador
amount - Novo saldo

Observações:

Sobrescreve o saldo anterior completamente
Não registra transação (use com cuidado)
Útil para ajustes administrativos e migrações

has(String playerName, double amount)

Verifica se um jogador possui um saldo mínimo.

if (economyAPI.has("Steve", 1000)) {
    // Jogador tem pelo menos 1000
}

Parâmetros:

playerName - Nome do jogador
amount - Quantia a verificar

Retorno:

true se o jogador tem saldo >= amount, false caso contrário

Observações:

Método conveniente para validação
Retorna false se a conta não existir

withdraw(String playerName, double amount, boolean apply)

Remove uma quantia do saldo de um jogador.

EconomyResponse response = economyAPI.withdraw("Steve", 500, true);
if (response.transactionSuccess()) {
    System.out.println("Saque realizado!");
}

Parâmetros:

playerName - Nome do jogador
amount - Quantia a remover
apply - Se true, registra a transação no histórico

Retorno:

EconomyResponse com status da operação

Observações:

Retorna FAILURE se a conta não existir
Registra transação automática se apply=true
Suporta integração com AlphaoGovernment

deposit(String playerName, double amount, boolean apply)

Adiciona uma quantia ao saldo de um jogador.

EconomyResponse response = economyAPI.deposit("Steve", 1000, true);
if (response.transactionSuccess()) {
    System.out.println("Depósito realizado!");
}

Parâmetros:

playerName - Nome do jogador
amount - Quantia a adicionar
apply - Se true, registra a transação no histórico

Retorno:

EconomyResponse com status da operação

Observações:

Retorna FAILURE se a conta não existir
Registra transação automática se apply=true
Aplica imposto automaticamente se integrado com AlphaoGovernment

getTop()

Retorna ranking dos top jogadores por saldo.

HashMap<String, Double> topPlayers = economyAPI.getTop();
topPlayers.forEach((name, balance) -> {
    System.out.println(name + ": " + balance);
});

Retorno:

HashMap<String, Double> ordenado do maior para o menor saldo

Observações:

Retorna dados ordenados em LinkedHashMap
Estrutura é: nome do jogador -> saldo
Útil para criar leaderboards

getPlayerTopPosition(Player player)

Obtém a posição no ranking de um jogador.

int position = economyAPI.getPlayerTopPosition(player);

Parâmetros:

player - Objeto Player do Bukkit

Retorno:

Posição do jogador no ranking (1-indexed)

Observações:

Método sobrecarregado (veja abaixo)
Posição 1 é o mais rico
Retorna -1 se jogador não estiver no ranking

getPlayerTopPosition(String playerName)

Obtém a posição no ranking de um jogador pelo nome.

int position = economyAPI.getPlayerTopPosition("Steve");

Parâmetros:

playerName - Nome do jogador

Retorno:

Posição do jogador no ranking (1-indexed)

Observações:

Case-insensitive
Retorna -1 se jogador não estiver no ranking
Mais eficiente que buscar por Player object

Estrutura de dados

Account

Representa a conta de economia de um jogador.

Propriedades principais:

Nome do jogador
Saldo (money)
Data de criação
Histórico de transações
Métodos: withdraw, deposit, has, setMoney

EconomyResponse

Resposta padrão do Vault para transações.

Propriedades:

transactionSuccess() - Se a transação foi bem-sucedida
amount - Quantia da transação
balance - Saldo após transação
responseType - FAILURE ou SUCCESS
errorMessage - Mensagem de erro (se houver)

Boas práticas

Use hasAccount() antes de fazer operações
Valide com has() antes de chamar withdraw()
Use apply=true em withdraw/deposit para manter histórico
Use set() apenas para ajustes administrativos
Prefer withdraw/deposit em vez de set() para transações normais
Cache posições do ranking (atualiza periodicamente)
Cuidado com transações offline (respeite generalOfflineTransactions)
Sempre verifique EconomyResponse.transactionSuccess()

Exemplos de uso

Verificar e cobrar por serviço

String player = "Steve";
double price = 500;

if (economyAPI.has(player, price)) {
    EconomyResponse response = economyAPI.withdraw(player, price, true);
    if (response.transactionSuccess()) {
        System.out.println("Jogador pagou " + price);
    }
} else {
    System.out.println("Saldo insuficiente!");
}

Dar recompensa com registro

String winner = event.getWinner().getName();
double reward = 2000;

EconomyResponse response = economyAPI.deposit(winner, reward, true);
if (response.transactionSuccess()) {
    event.getWinner().sendMessage("Você ganhou " + reward + " moedas!");
}

Criar leaderboard

public void displayTopPlayers(CommandSender sender) {
    sender.sendMessage("═════════════════════════════");
    sender.sendMessage("TOP 10 JOGADORES");
    sender.sendMessage("═════════════════════════════");
    
    HashMap<String, Double> top = economyAPI.getTop();
    int position = 1;
    
    for (Map.Entry<String, Double> entry : top.entrySet()) {
        if (position > 10) break;
        
        sender.sendMessage(position + "º - " + entry.getKey() + 
                          ": " + entry.getValue());
        position++;
    }
    
    sender.sendMessage("═════════════════════════════");
}

Mostrar posição no ranking

@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
    Player player = event.getPlayer();
    int position = economyAPI.getPlayerTopPosition(player);
    
    if (position > 0) {
        player.sendMessage("Você está na posição " + position + " do ranking!");
    }
}

Sistema de venda com preço dinâmico

public void sellItem(Player player, double basePrice) {
    String playerName = player.getName();
    
    if (!economyAPI.hasAccount(playerName)) {
        player.sendMessage("Erro: conta não encontrada!");
        return;
    }
    
    EconomyResponse response = economyAPI.deposit(playerName, basePrice, true);
    
    if (response.transactionSuccess()) {
        player.sendMessage("Item vendido por " + basePrice + " moedas!");
        player.sendMessage("Saldo atual: " + response.balance);
    }
}

Transação entre jogadores

public boolean transferMoney(String from, String to, double amount) {
    if (!economyAPI.has(from, amount)) {
        return false;
    }
    
    EconomyResponse withdraw = economyAPI.withdraw(from, amount, true);
    if (!withdraw.transactionSuccess()) {
        return false;
    }
    
    EconomyResponse deposit = economyAPI.deposit(to, amount, true);
    return deposit.transactionSuccess();
}

Sistema de imposto/taxa

@EventHandler
public void onPlayerVend(PlayerVendEvent event) {
    double saleAmount = event.getAmount();
    double taxRate = 0.10; // 10%
    double taxAmount = saleAmount * taxRate;
    double netAmount = saleAmount - taxAmount;
    
    EconomyResponse response = economyAPI.deposit(
        event.getPlayer().getName(), 
        netAmount, 
        true
    );
    
    event.getPlayer().sendMessage("Venda: " + saleAmount + 
        " (Taxa: " + taxAmount + ")");
}

Dashboard de economia

public void showEconomyDashboard(Player player) {
    String playerName = player.getName();
    double balance = economyAPI.getBalance(playerName);
    int position = economyAPI.getPlayerTopPosition(playerName);
    
    player.sendMessage("═══════════════════════════");
    player.sendMessage("DASHBOARD ECONÓMICO");
    player.sendMessage("═══════════════════════════");
    player.sendMessage("Saldo: " + balance);
    player.sendMessage("Posição: " + (position > 0 ? position + "º" : "Fora do top"));
    player.sendMessage("═══════════════════════════");
}

Verificação de multa automática

@EventHandler
public void onPlayerDeath(PlayerDeathEvent event) {
    Player player = event.getEntity().getKiller();
    if (player == null) return;
    
    String playerName = player.getName();
    if (economyAPI.hasAccount(playerName)) {
        double balance = economyAPI.getBalance(playerName);
        double penalty = Math.min(balance * 0.05, 500); // Máximo 500
        
        if (economyAPI.has(playerName, penalty)) {
            economyAPI.withdraw(playerName, penalty, true);
            player.sendMessage("Você perdeu " + penalty + " moedas!");
        }
    }
}

Nesta página