API

Documentação completa da API do yMaquinas, incluindo métodos para acessar dados de máquinas de jogadores e manipular eventos de negociação de máquinas.

Obtendo a Instância da API

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

import com.ystoreplugins.ymaquinas.api.MaquinaAPI;
import org.bukkit.Bukkit;

MaquinaAPI maquinaAPI = (MaquinaAPI) Bukkit.getServicesManager()
    .load(com.ystoreplugins.ymaquinas.api.MaquinaAPIHolder.class);

if (maquinaAPI != null) {
    // API está pronta para uso
}

Alternativamente, se você tiver acesso direto à classe Main:

import com.ystoreplugins.ymaquinas.Main;

MaquinaAPI maquinaAPI = (MaquinaAPI) Main.get().getAPI();

Métodos Disponíveis

getPlayer()

Recupera o detentor de dados da máquina para um jogador específico.

Parâmetros:

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

Retorna:

PlayerMaquinaHolder - Objeto contendo todos os dados de máquinas do jogador, ou null se jogador não encontrado

Observações:

Os dados são recuperados do mapa de jogadores em cache
Retorna null se o jogador nunca fez login ou seus dados não estão em cache
Use este método para acessar informações de máquinas do jogador

PlayerMaquinaHolder playerData = maquinaAPI.getPlayer("NomeDoJogador");
if (playerData != null) {
    // Acessar dados de máquinas do jogador
}

Estruturas de Dados

PlayerMaquinaHolder

Contém todos os dados relacionados a máquinas para um jogador. Este objeto contém:

Máquinas possuídas pelo jogador
Dados de produção das máquinas
Upgrades e níveis das máquinas
Recursos coletados

MaquinaTypeHolder

Representa um tipo de máquina no plugin. Contém:

Identificador da máquina
Nome da máquina
Taxas de produção
Custos base

MaquinaShopHolder

Representa uma máquina disponível na loja. Contém:

Configuração da loja de máquinas
Preço de compra
Referência ao tipo de máquina

Eventos

MaquinaSellEvent

Disparado quando um jogador vende máquinas ou seus produtos.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Jogador
getMaquina() - Retorna o MaquinaTypeHolder sendo vendido
getAmount() - Retorna o valor/quantidade sendo vendido
getEffectiveCosts() - Retorna um HashMap com a divisão de custos em moedas
setAmount(double) - Modificar o valor da venda
setEffectiveCosts(HashMap<String, Double>) - Modificar os custos efetivos

Exemplo:

@EventHandler
public void onMachineSell(MaquinaSellEvent event) {
    Player player = event.getPlayer();
    MaquinaTypeHolder maquina = event.getMaquina();
    double amount = event.getAmount();
    
    System.out.println(player.getName() + " está vendendo " + amount + " do tipo de máquina: " + maquina);
}

MaquinaBuyEvent

Disparado quando um jogador compra máquinas da loja.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Jogador
getMaquinaShop() - Retorna o MaquinaShopHolder sendo comprado
getAmount() - Retorna o valor da compra
getEffectiveCosts() - Retorna um HashMap com a divisão de custos em moedas

Exemplo:

@EventHandler
public void onMachineBuy(MaquinaBuyEvent event) {
    Player player = event.getPlayer();
    MaquinaShopHolder shop = event.getMaquinaShop();
    double amount = event.getAmount();
    
    System.out.println(player.getName() + " comprou " + amount + " máquinas");
}

Melhores Práticas

Sempre verificar nulo ao recuperar dados de jogador usando getPlayer()
Usar eventos para rastreamento de transações de máquinas em vez de modificar dados diretamente
Armazenar em cache dados localmente se você acessar frequentemente as informações do mesmo jogador
Modificar custos com segurança em eventos de compra/venda usando os setters
Manipular operações assíncronas se acessando dados de contextos assíncronos

Exemplos de Uso

Exemplo 1: Obtendo Dados de Máquina do Jogador

MaquinaAPI api = (MaquinaAPI) Bukkit.getServicesManager()
    .load(com.ystoreplugins.ymaquinas.api.MaquinaAPIHolder.class);

PlayerMaquinaHolder playerData = api.getPlayer(player.getName());
if (playerData != null) {
    // Jogador possui dados de máquinas
    System.out.println("Máquinas do jogador carregadas com sucesso");
}

Exemplo 2: Ouvindo Vendas de Máquinas

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.ymaquinas.event.MaquinaSellEvent;

public class MachineTracker implements Listener {
    
    @EventHandler
    public void onMachineSell(MaquinaSellEvent event) {
        Player player = event.getPlayer();
        double sellAmount = event.getAmount();
        
        System.out.println(player.getName() + " ganhou dinheiro vendendo: " + sellAmount);
    }
}

Exemplo 3: Ouvindo Compras de Máquinas

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.ymaquinas.event.MaquinaBuyEvent;

public class MachineShopListener implements Listener {
    
    @EventHandler
    public void onMachineBuy(MaquinaBuyEvent event) {
        Player player = event.getPlayer();
        MaquinaShopHolder shop = event.getMaquinaShop();
        double amount = event.getAmount();
        
        System.out.println(player.getName() + " comprou " + amount + " máquinas");
    }
}

Exemplo 4: Modificando Custos de Venda

@EventHandler
public void onMachineSell(MaquinaSellEvent event) {
    HashMap<String, Double> costs = event.getEffectiveCosts();
    
    // Aumentar preço de venda em 10%
    costs.forEach((currency, value) -> {
        costs.put(currency, value * 1.1);
    });
    
    event.setEffectiveCosts(costs);
}

Exemplo 5: Validação Customizada de Compra

@EventHandler
public void onMachineBuy(MaquinaBuyEvent event) {
    Player player = event.getPlayer();
    
    // Verificar se o jogador pode comprar
    HashMap<String, Double> costs = event.getEffectiveCosts();
    
    for (String currency : costs.keySet()) {
        System.out.println("Custo (" + currency + "): " + costs.get(currency));
    }
}

Exemplo 6: Rastreando Transações de Máquinas

public class MachineTransactionLogger implements Listener {
    
    @EventHandler
    public void onMachineSell(MaquinaSellEvent event) {
        Player player = event.getPlayer();
        double amount = event.getAmount();
        
        // Registrar em banco de dados ou arquivo
        System.out.println("[VENDA] " + player.getName() + " - Qtd: " + amount);
    }
    
    @EventHandler
    public void onMachineBuy(MaquinaBuyEvent event) {
        Player player = event.getPlayer();
        double amount = event.getAmount();
        
        // Registrar em banco de dados ou arquivo
        System.out.println("[COMPRA] " + player.getName() + " - Qtd: " + amount);
    }
}

Exemplo 7: Verificando Propriedade do Jogador

MaquinaAPI api = (MaquinaAPI) Bukkit.getServicesManager()
    .load(com.ystoreplugins.ymaquinas.api.MaquinaAPIHolder.class);

PlayerMaquinaHolder playerData = api.getPlayer("NomeDoJogador");
if (playerData != null) {
    System.out.println("Jogador possui dados de máquinas disponíveis");
    // Proceder com operações de máquinas
} else {
    System.out.println("Jogador não possui dados de máquinas ou não está em cache");
}

Exemplo 8: Ajuste Dinâmico de Preço

@EventHandler
public void onMachineBuy(MaquinaBuyEvent event) {
    double baseAmount = event.getAmount();
    
    // Aplicar desconto para compra em quantidade
    if (baseAmount > 10) {
        HashMap<String, Double> costs = event.getEffectiveCosts();
        costs.forEach((currency, value) -> {
            costs.put(currency, value * 0.9); // Desconto de 10%
        });
        event.setEffectiveCosts(costs);
    }
}

Exemplo 9: Sistema de Registro de Eventos

public class MachineEventLogger implements Listener {
    
    private final JavaPlugin plugin;
    
    public MachineEventLogger(JavaPlugin plugin) {
        this.plugin = plugin;
    }
    
    @EventHandler
    public void onMachineSell(MaquinaSellEvent event) {
        String log = String.format(
            "[%s] %s vendeu %s máquinas por %s",
            System.currentTimeMillis(),
            event.getPlayer().getName(),
            event.getAmount(),
            event.getEffectiveCosts()
        );
        plugin.getLogger().info(log);
    }
}

Exemplo 10: Integração com Economia

@EventHandler
public void onMachineSell(MaquinaSellEvent event) {
    Player player = event.getPlayer();
    HashMap<String, Double> costs = event.getEffectiveCosts();
    
    // Processar pagamentos baseado em moedas
    costs.forEach((currency, amount) -> {
        if (currency.equalsIgnoreCase("COINS")) {
            // Recompensar moedas
            System.out.println("Adicionando " + amount + " moedas a " + player.getName());
        } else if (currency.equalsIgnoreCase("TOKENS")) {
            // Recompensar tokens
            System.out.println("Adicionando " + amount + " tokens a " + player.getName());
        }
    });
}

Nesta página