API

A API fornece uma interface pública para desenvolvedores integrarem seus plugins ao sistema de venda automática do yVender, permitindo monitorar vendas, modificar valores e integrar com sistemas econômicos customizados.

Obtendo a instância da API

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

Exemplo:

VenderAPIHolder venderAPI;

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

Eventos

VenderSellEvent

Disparado quando um jogador vende itens através do sistema de venda automática do yVender.

@EventHandler
public void onVenderSell(VenderSellEvent event) {
    Player player = event.getPlayer();
    double amount = event.getAmount();
    HashMap<String, Double> values = event.getValues();
}

Propriedades disponíveis:

getPlayer() - Retorna a instância do Player que realizou a venda
getAmount() - Retorna o valor total da venda em dinheiro (double)
getValues() - Retorna um HashMap<String, Double> com os valores por tipo de economia
setAmount(double amount) - Modifica o valor total da venda (permite modificar a recompensa)
setValues(HashMap<String, Double> values) - Modifica os valores por economia (permite customizar distribuição)

Estrutura de dados

HashMap de Valores

A estrutura usada para armazenar valores de venda por economia é:

HashMap<String, Double> valores = event.getValues();
// Exemplo:
// "dinheiro" -> 1500.50
// "tokens" -> 25.0
// "experiencia" -> 500.0

Características:

Chave: Identificador da economia (ex: "dinheiro", "tokens", "gems")
Valor: Número (double) representando a quantidade a ser creditada
Pode ser modificado durante o evento antes da finalização

Melhores práticas

Sempre valide o jogador - Verificar se o jogador ainda está online antes de agir
Não cancele o evento diretamente - Considere usar setAmount(0) se quiser bloquear a venda
Modifique valores com cuidado - Validar se as modificações não causam valores negativos
Use try-catch ao obter a API - O plugin pode não estar instalado
Sincronize modificações - Certifique-se que todas as economias são atualizadas juntas
Respeite as configurações - Não sobrescreva configurações do yVender sem motivo
Implemente logs - Registre todas as modificações realizadas pela sua API
Valide HashMap - Sempre verifique se a HashMap contém as chaves esperadas antes de acessar
Considere performance - Evite operações pesadas durante evento de venda
Documente modificações - Se seu plugin modifica eventos, mantenha registro das alterações

Exemplos de uso

Monitorar todas as vendas

@EventHandler
public void onVenderSell(VenderSellEvent event) {
    Player player = event.getPlayer();
    double amount = event.getAmount();
    
    System.out.println("§e[yVender] " + player.getName() + " vendeu itens por §6$" + amount);
}

Aumentar valor de venda com bônus

@EventHandler
public void onVenderSell(VenderSellEvent event) {
    Player player = event.getPlayer();
    double amount = event.getAmount();
    
    // Aumentar venda em 10%
    double bonus = amount * 0.10;
    event.setAmount(amount + bonus);
    
    player.sendMessage("§aVenda realizada com bônus de 10%!");
}

Modificar distribuição de economias

@EventHandler
public void onVenderSell(VenderSellEvent event) {
    Player player = event.getPlayer();
    HashMap<String, Double> valores = event.getValues();
    
    // Se o jogador tem um multiplicador especial
    if (player.hasPermission("yvender.bonus.2x")) {
        // Dobrar todos os valores
        for (String economia : valores.keySet()) {
            double valor = valores.get(economia);
            valores.put(economia, valor * 2);
        }
        
        // Atualizar a HashMap
        event.setValues(valores);
        
        player.sendMessage("§aVenda dobrada com seu bônus especial!");
    }
}

Redirecionar valor para economia customizada

@EventHandler
public void onVenderSell(VenderSellEvent event) {
    Player player = event.getPlayer();
    double amount = event.getAmount();
    HashMap<String, Double> valores = event.getValues();
    
    // Se o jogador tem VIP
    if (player.hasPermission("yvender.vip")) {
        // Aumentar valor base em 25%
        double bonusVip = amount * 0.25;
        
        // Adicionar bônus VIP customizado
        valores.put("vip_points", valores.getOrDefault("vip_points", 0.0) + bonusVip);
        event.setValues(valores);
    }
}

Bloquear venda em certas condições

@EventHandler
public void onVenderSell(VenderSellEvent event) {
    Player player = event.getPlayer();
    
    // Não permitir venda se estiver em evento
    if (eventoManager.isPlayerInEvent(player)) {
        // Setar valor para 0
        event.setAmount(0);
        player.sendMessage("§cNão é possível vender durante um evento!");
    }
}

Integrar com sistema de taxas/impostos

@EventHandler
public void onVenderSell(VenderSellEvent event) {
    Player player = event.getPlayer();
    double amount = event.getAmount();
    
    // Calcular imposto de 5%
    double taxa = amount * 0.05;
    double valorLiquido = amount - taxa;
    
    // Registrar taxa no banco de dados
    meuBancoDados.registrarTaxa(player.getUniqueId(), taxa);
    
    // Aplicar valor líquido
    event.setAmount(valorLiquido);
    
    player.sendMessage(String.format("§cTaxa de §6$%.2f §capplicada", taxa));
}

Rastrear estatísticas de vendas

public class VendaStatisticsListener implements Listener {
    private Map<UUID, Double> totalVendas = new HashMap<>();
    
    @EventHandler
    public void onVenderSell(VenderSellEvent event) {
        UUID playerUUID = event.getPlayer().getUniqueId();
        double amount = event.getAmount();
        
        // Atualizar total de vendas
        double totalAtual = totalVendas.getOrDefault(playerUUID, 0.0);
        totalVendas.put(playerUUID, totalAtual + amount);
        
        // A cada 10,000 moedas vendidas, dar prêmio
        if (totalAtual + amount >= 10000 && totalAtual < 10000) {
            event.getPlayer().sendMessage("§a§lRECOMPENSA DESBLOQUEADA!");
        }
    }
    
    public double getTotalVendas(UUID uuid) {
        return totalVendas.getOrDefault(uuid, 0.0);
    }
}

Multiplicador baseado em ranking

@EventHandler
public void onVenderSell(VenderSellEvent event) {
    Player player = event.getPlayer();
    double amount = event.getAmount();
    
    // Obter multiplicador do ranking do jogador
    int rank = obterRank(player);
    double multiplicador = 1.0 + (rank * 0.05); // 5% por nível
    
    // Aplicar multiplicador
    event.setAmount(amount * multiplicador);
    
    player.sendMessage(String.format("§aMultiplicador aplicado: §6x%.2f", multiplicador));
}

private int obterRank(Player player) {
    // Lógica para obter rank do jogador
    return 5;
}

Sistema de bônus por hora/dia

@EventHandler
public void onVenderSell(VenderSellEvent event) {
    Player player = event.getPlayer();
    double amount = event.getAmount();
    
    // Verificar hora do servidor
    long hora = System.currentTimeMillis() / 3600000;
    
    // Entre 19h-21h, 50% de bônus
    if (estaNoHorarioPico(hora)) {
        double bonus = amount * 0.50;
        event.setAmount(amount + bonus);
        
        player.sendMessage("§6⭐ §eBônus horário aplicado! +50%");
    }
}

private boolean estaNoHorarioPico(long hora) {
    // Implementar lógica para verificar horários
    return true;
}

Auditar e registrar todas as transações

public class VendaAuditListener implements Listener {
    private AuditLogger auditLogger;
    
    public VendaAuditListener(AuditLogger auditLogger) {
        this.auditLogger = auditLogger;
    }
    
    @EventHandler
    public void onVenderSell(VenderSellEvent event) {
        Player player = event.getPlayer();
        double originalAmount = event.getAmount();
        
        // Registrar após o evento ser processado
        Bukkit.getScheduler().runTaskLater(plugin, () -> {
            double finalAmount = event.getAmount();
            HashMap<String, Double> values = event.getValues();
            
            auditLogger.log(String.format(
                "VENDA | Player: %s | Original: %.2f | Final: %.2f | Economias: %s",
                player.getName(), originalAmount, finalAmount, values.toString()
            ));
        }, 1L);
    }
}

Validar acesso à API

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

Nesta página