API

A API fornece uma interface pública para desenvolvedores integrarem seus plugins ao sistema de economias múltiplas do yEconomias, permitindo gerenciar várias moedas e saldos de jogadores.

Obtendo a instância da API

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

Exemplo:

EconomiasAPIHolder economiasAPI;

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

Métodos disponíveis

hasAccount(String playerName)

Verifica se uma conta de economia existe para um jogador (assíncrono).

economiasAPI.hasAccount("Steve").thenAccept(exists -> {
    if (exists) {
        System.out.println("Conta encontrada!");
    }
});

Parâmetros:

playerName - Nome do jogador

Retorno:

CompletableFuture<Boolean> - Future que contém true se a conta existe, false caso contrário

Observações:

Operação assíncrona para não bloquear a thread principal
Implementa CompletableFuture para melhor tratamento
Case-insensitive (converte para minúsculas automaticamente)
Use .thenAccept() ou .join() para obter o resultado

getAccount(String playerName)

Recupera a conta de economia de um jogador (assíncrono).

economiasAPI.getAccount("Steve").thenAccept(user -> {
    if (user != null) {
        double balance = user.getCurrencies().get("coins");
    }
});

Parâmetros:

playerName - Nome do jogador

Retorno:

CompletableFuture<UserHolder> - Future contendo dados do usuário ou null

Observações:

Operação assíncrono para não bloquear a thread principal
Retorna null se o jogador não existir
Case-insensitive (converte para minúsculas automaticamente)
Use .join() para obter resultado síncrono (se necessário)

getBalance(UserHolder user, String currency)

Obtém o saldo de uma moeda específica do jogador.

double balance = economiasAPI.getBalance(user, "coins");

Parâmetros:

user - Objeto UserHolder do jogador
currency - Nome da moeda

Retorno:

Valor double do saldo (0.0 se a moeda não existir)

Observações:

Operação síncrona
Retorna 0.0 se a moeda não for encontrada
Seguro contra null (usa getOrDefault)

setBalance(UserHolder user, String currency, double amount)

Define o saldo de uma moeda do jogador.

economiasAPI.setBalance(user, "coins", 1000.0);

Parâmetros:

user - Objeto UserHolder do jogador
currency - Nome da moeda
amount - Novo saldo

Observações:

Sobrescreve o saldo anterior
Cria a moeda se ela não existir
Salva automaticamente no banco de dados
Use com cuidado (prefira addBalance ou removeBalance)

addBalance(UserHolder user, String currency, double amount)

Adiciona uma quantia ao saldo de uma moeda.

economiasAPI.addBalance(user, "coins", 500.0);

Parâmetros:

user - Objeto UserHolder do jogador
currency - Nome da moeda
amount - Quantia a adicionar

Observações:

Método seguro para recompensas
Cria a moeda com o valor se ela não existir
Salva automaticamente no banco de dados
Ideal para receber recompensas e bônus

removeBalance(UserHolder user, String currency, double amount)

Remove uma quantia do saldo de uma moeda.

economiasAPI.removeBalance(user, "coins", 100.0);

Parâmetros:

user - Objeto UserHolder do jogador
currency - Nome da moeda
amount - Quantia a remover

Observações:

Método seguro para cobranças
Pode resultar em saldo negativo se não validado
Salva automaticamente no banco de dados
Ideal para pagamentos e gastos

Estrutura de dados

UserHolder

Representa uma conta de economia de um jogador.

Propriedades principais:

Nome do jogador
Mapa de moedas (currencies)
Cada moeda pode ter um saldo independente
Métodos de persistência (save)

Boas práticas

Sempre use operações assíncronas (CompletableFuture) para hasAccount e getAccount
Valide saldos antes de remover (evite negativos)
Use addBalance() para recompensas e removeBalance() para cobranças
Evite setBalance() exceto em migrações ou ajustes administrativos
Sempre salve dados após modificações
Use nomes de moedas consistentes em toda a aplicação
Considere usar join() com cuidado (pode bloquear a thread)

Exemplos de uso

Verificar existência de conta (assíncrono)

economiasAPI.hasAccount("Steve").thenAccept(exists -> {
    if (exists) {
        System.out.println("Conta existe");
    } else {
        System.out.println("Conta não existe");
    }
}).exceptionally(throwable -> {
    throwable.printStackTrace();
    return null;
});

Obter saldo de um jogador (assíncrono)

economiasAPI.getAccount("Steve").thenAccept(user -> {
    if (user != null) {
        double coinsBalance = economiasAPI.getBalance(user, "coins");
        double diamondsBalance = economiasAPI.getBalance(user, "diamonds");
        
        System.out.println("Coins: " + coinsBalance);
        System.out.println("Diamonds: " + diamondsBalance);
    }
}).exceptionally(throwable -> {
    throwable.printStackTrace();
    return null;
});

Dar recompensa de evento

@EventHandler
public void onPlayerVictory(PlayerVictoryEvent event) {
    Player player = event.getPlayer();
    
    economiasAPI.getAccount(player.getName()).thenAccept(user -> {
        if (user != null) {
            double reward = 1000;
            economiasAPI.addBalance(user, "coins", reward);
            player.sendMessage("Você ganhou " + reward + " coins!");
        }
    });
}

Sistema de pagamento

public boolean payPlayer(String payer, String receiver, double amount, String currency) {
    CompletableFuture<Boolean> payerCheck = economiasAPI.hasAccount(payer);
    CompletableFuture<Boolean> receiverCheck = economiasAPI.hasAccount(receiver);
    
    CompletableFuture<Boolean> result = payerCheck.thenCombine(receiverCheck, (payerExists, receiverExists) -> {
        if (!payerExists || !receiverExists) {
            return false;
        }
        
        try {
            UserHolder payerUser = economiasAPI.getAccount(payer).join();
            UserHolder receiverUser = economiasAPI.getAccount(receiver).join();
            
            double payerBalance = economiasAPI.getBalance(payerUser, currency);
            if (payerBalance < amount) {
                return false;
            }
            
            economiasAPI.removeBalance(payerUser, currency, amount);
            economiasAPI.addBalance(receiverUser, currency, amount);
            
            return true;
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
    });
    
    return result.join();
}

Verificar se pode fazer compra

public boolean canAfford(String playerName, String currency, double price) {
    try {
        UserHolder user = economiasAPI.getAccount(playerName).join();
        if (user == null) return false;
        
        double balance = economiasAPI.getBalance(user, currency);
        return balance >= price;
    } catch (Exception e) {
        return false;
    }
}

Processar compra

@EventHandler
public void onShopPurchase(ShopPurchaseEvent event) {
    String playerName = event.getPlayer().getName();
    double price = event.getPrice();
    String currency = "coins";
    
    if (canAfford(playerName, currency, price)) {
        economiasAPI.getAccount(playerName).thenAccept(user -> {
            economiasAPI.removeBalance(user, currency, price);
            event.getPlayer().sendMessage("Compra realizada!");
        });
    } else {
        event.getPlayer().sendMessage("Saldo insuficiente!");
    }
}

Sincronizar múltiplas moedas

public void syncMultipleCurrencies(String playerName, Map<String, Double> balances) {
    economiasAPI.getAccount(playerName).thenAccept(user -> {
        if (user != null) {
            for (Map.Entry<String, Double> entry : balances.entrySet()) {
                economiasAPI.setBalance(user, entry.getKey(), entry.getValue());
            }
            System.out.println("Saldos sincronizados para " + playerName);
        }
    });
}

Dashboard de saldos

public void showBalanceBoard(Player player) {
    economiasAPI.getAccount(player.getName()).thenAccept(user -> {
        if (user != null) {
            player.sendMessage("═══════════════════════════");
            player.sendMessage("SALDO DE ECONOMIAS");
            player.sendMessage("═══════════════════════════");
            
            user.getCurrencies().forEach((currency, balance) -> {
                player.sendMessage(currency + ": " + balance);
            });
            
            player.sendMessage("═══════════════════════════");
        }
    });
}

Sistema de multa/penalidade

public void applyPenalty(String playerName, String currency, double amount) {
    economiasAPI.getAccount(playerName).thenAccept(user -> {
        if (user != null) {
            double currentBalance = economiasAPI.getBalance(user, currency);
            double newBalance = Math.max(0, currentBalance - amount); // Não permite negativos
            economiasAPI.setBalance(user, currency, newBalance);
            
            Bukkit.getPlayer(playerName).sendMessage("Você recebeu uma multa de " + amount + " " + currency);
        }
    });
}

Nesta página