API

Documentação completa da API do plugin yMinasPackets, incluindo métodos para acessar dados de minas de pacotes, informações de minas de jogadores e manipulação de eventos de mineração baseados em pacotes.

Obtendo a Instância da API

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

import br.com.ystoreplugins.product.yminaspackets.MinePacketAPIHolder;
import org.bukkit.Bukkit;

MinePacketAPIHolder mineAPI = (MinePacketAPIHolder) Bukkit.getServicesManager()
    .load(MinePacketAPIHolder.class);

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

Alternativamente, se você estiver usando Maven e tiver o plugin como uma dependência:

import com.ystoreplugins.yminaspackets.api.MineAPI;

MineAPI mineAPI = new MineAPI();

Métodos Disponíveis

retrieveMine()

Recupera uma mina específica pelo seu identificador.

Parâmetros:

mine (String) - O identificador único da mina

Retorna:

MinePacketHolder - Objeto contendo dados da mina, ou null se não encontrada

Observações:

Este é o método recomendado para plugins externos
Retorna null se o identificador da mina não existir
Use isto para acessar a configuração da mina e propriedades
Funciona com sistemas de minas baseados em pacotes

MinePacketHolder mine = mineAPI.retrieveMine("mineName");
if (mine != null) {
    // Acessar dados da mina
}

retrievePlayer()

Recupera o detentor de dados da mina para um jogador específico.

Parâmetros:

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

Retorna:

PlayerMinePacketHolder - Objeto contendo todos os dados da mina do jogador, ou null se não encontrado

Observações:

Este é o método recomendado para plugins externos
Os dados são recuperados do cache do jogador
Retorna null se o jogador nunca fez login ou seus dados não estão em cache
Use isto para acessar informações de minas de pacotes específicas do jogador

PlayerMinePacketHolder playerData = mineAPI.retrievePlayer("PlayerName");
if (playerData != null) {
    // Acessar dados da mina do jogador
}

run()

Método interno para manipular atribuições de minas entre servidores (suporte Bungee). Não use em plugins externos.

Parâmetros:

array (String[]) - Array contendo UUID (array[0]) e nome da mina (array[1])

Observações:

Reservado apenas para uso interno do plugin
Manipula coordenação de servidor Bungee
Gerencia atribuições de minas pendentes com atrasos configuráveis

Estruturas de Dados

MinePacketHolder

Representa uma mina baseada em pacotes no plugin. Contém:

Identificador e nome da mina
Configuração da mina
Tipos de blocos e taxas de queda
Configuração de recompensas econômicas
Informações do sistema de encanto
Requisitos de picareta personalizada

PlayerMinePacketHolder

Contém todos os dados de mina de pacotes relacionados para um jogador. Mantém:

Mina atualmente selecionada
Progressão/nível da mina
Recursos coletados
Tempo gasto em minas
Bônus e multiplicadores ativos
Dados de encanto

PacketEconomyTypeHolder

Representa um tipo de moeda no sistema de economia baseado em pacotes. Contém:

Identificador de moeda
Símbolo de moeda
Informações de taxa de câmbio

Eventos

PreMinePacketBreakBlockEvent

Evento preliminar acionado ANTES que um jogador quebre um bloco em uma mina de pacotes. Este evento é cancelável e permite que você impeça quebras de blocos antes do processamento.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getMine() - Retorna o MinePacketHolder representando a mina
getLocation() - Retorna a Location do bloco prestes a ser quebrado
isCancelled() - Verifica se o evento foi cancelado
setCancelled(boolean) - Cancela a quebra do bloco

Observações:

Este evento dispara ANTES que material e recompensas sejam calculados
Útil para impedir que certos locais sejam minerados
Mais eficiente para cancelamento antecipado que MinePacketBreakBlockEvent

Exemplo:

@EventHandler
public void onPreMinePacketBreakBlock(PreMinePacketBreakBlockEvent event) {
    if (event.isCancelled()) return;
    
    Location location = event.getLocation();
    
    // Impedir mineração em regiões específicas
    if (isProtectedArea(location)) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("§cNão é possível minerar nesta área!");
    }
}

MinePacketBreakBlockEvent

Acionado quando um jogador quebra um bloco em uma mina de pacotes. Este evento é cancelável.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getMine() - Retorna o MinePacketHolder representando a mina
getMaterial() - Retorna o tipo de Material do bloco quebrado
getData() - Retorna informações de dados do bloco (para versões antigas)
getLocation() - Retorna a Location do bloco quebrado
getValues() - Retorna um HashMap com valores de economia (moeda -> quantidade)
setValues(HashMap<PacketEconomyTypeHolder, Double>) - Modifica as recompensas econômicas
isEnchants() - Retorna true se esta quebra de bloco acionou recompensas de encanto
setEnchants(boolean) - Marca/desmarca como gatilho de encanto
isCancelled() - Verifica se o evento foi cancelado
setCancelled(boolean) - Cancela a quebra do bloco

Observações:

Dispara APÓS verificações preliminares (use PreMinePacketBreakBlockEvent para impedir antes do cálculo)
Material e dados são determinados neste ponto
Valores de economia podem ser modificados antes das recompensas serem distribuídas
A bandeira de encantos indica quebras especiais acionadas por encantos

Exemplo:

@EventHandler
public void onMinePacketBreakBlock(MinePacketBreakBlockEvent event) {
    if (event.isCancelled()) return;
    
    Player player = event.getPlayer();
    Material material = event.getMaterial();
    Location location = event.getLocation();
    
    System.out.println(player.getName() + " quebrou " + material + 
        " em " + location + " em " + event.getMine());
}

MinePacketJoinEvent

Acionado quando um jogador entra em uma mina de pacotes.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getMine() - Retorna o MinePacketHolder representando a mina
isCustomPickaxe() - Retorna true se o jogador está usando uma picareta personalizada

Exemplo:

@EventHandler
public void onMinePacketJoin(MinePacketJoinEvent event) {
    Player player = event.getPlayer();
    MinePacketHolder mine = event.getMine();
    boolean hasCustomPickaxe = event.isCustomPickaxe();
    
    player.sendMessage("§aVocê entrou em: " + mine);
    if (hasCustomPickaxe) {
        player.sendMessage("§eBônus de picareta personalizada ativo!");
    }
}

MinePacketQuitEvent

Acionado quando um jogador sai de uma mina de pacotes.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getMine() - Retorna o MinePacketHolder representando a mina
isCustomPickaxe() - Retorna true se o jogador estava usando uma picareta personalizada

Exemplo:

@EventHandler
public void onMinePacketQuit(MinePacketQuitEvent event) {
    Player player = event.getPlayer();
    MinePacketHolder mine = event.getMine();
    
    System.out.println(player.getName() + " saiu da mina: " + mine);
}

Melhores Práticas

Sempre verifique null ao recuperar dados de mina ou jogador
Use PreMinePacketBreakBlockEvent para cancelamento antecipado (antes do cálculo)
Use MinePacketBreakBlockEvent para modificar recompensas após cálculo
Valide a configuração Bungee se usar minas entre servidores
Ouça eventos para rastrear atividades de mineração em vez de modificar dados diretamente
Modifique valores de economia com segurança no evento usando setters
Cache dados de mina se acessar frequentemente as mesmas informações
Verifique a bandeira de encantos para aplicar lógica de bônus especial para blocos acionados por encantos
Manipule dados de pacotes com cuidado, pois sistemas baseados em pacotes diferem da quebra de bloco tradicional

Exemplos de Uso

Exemplo 1: Obtendo Informações de Mina

MinePacketAPIHolder mineAPI = (MinePacketAPIHolder) Bukkit.getServicesManager()
    .load(MinePacketAPIHolder.class);

MinePacketHolder mine = mineAPI.retrieveMine("vip_mine");
if (mine != null) {
    System.out.println("Mina de pacotes recuperada com sucesso");
}

Exemplo 2: Obtendo Dados de Mina de Pacotes do Jogador

MinePacketAPIHolder mineAPI = (MinePacketAPIHolder) Bukkit.getServicesManager()
    .load(MinePacketAPIHolder.class);

PlayerMinePacketHolder playerData = mineAPI.retrievePlayer(player.getName());
if (playerData != null) {
    System.out.println("Dados de mina de pacotes do jogador carregados");
}

Exemplo 3: Prevenindo Mineração em Regiões Protegidas

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.yminaspackets.event.PreMinePacketBreakBlockEvent;

public class ProtectedRegionListener implements Listener {
    
    @EventHandler
    public void onPreMinePacketBreakBlock(PreMinePacketBreakBlockEvent event) {
        Location location = event.getLocation();
        
        // Verificar se a localização está em uma região protegida
        if (isInProtectedRegion(location)) {
            event.setCancelled(true);
            event.getPlayer().sendMessage("§cEsta região é protegida!");
        }
    }
    
    private boolean isInProtectedRegion(Location loc) {
        // Implementação aqui
        return false;
    }
}

Exemplo 4: Modificando Recompensas de Mina de Pacotes

@EventHandler
public void onMinePacketBreakBlock(MinePacketBreakBlockEvent event) {
    HashMap<PacketEconomyTypeHolder, Double> values = event.getValues();
    
    // Aumentar todas as recompensas em 30%
    values.forEach((economy, amount) -> {
        values.put(economy, amount * 1.30);
    });
    
    event.setValues(values);
}

Exemplo 5: Bônus para Blocos Acionados por Encanto

@EventHandler
public void onMinePacketBreakBlock(MinePacketBreakBlockEvent event) {
    if (event.isEnchants()) {
        HashMap<PacketEconomyTypeHolder, Double> values = event.getValues();
        
        // Aplicar bônus de encanto (2x recompensas)
        values.forEach((economy, amount) -> {
            values.put(economy, amount * 2.0);
        });
        
        event.setValues(values);
        event.getPlayer().sendMessage("§6Bônus de encanto aplicado!");
    }
}

Exemplo 6: Rastreando Sessões de Mina de Pacotes

public class PacketMineSessionTracker implements Listener {
    
    private final JavaPlugin plugin;
    
    public PacketMineSessionTracker(JavaPlugin plugin) {
        this.plugin = plugin;
    }
    
    @EventHandler
    public void onMinePacketJoin(MinePacketJoinEvent event) {
        String log = String.format(
            "[ENTRADA] %s entrou em %s (Picareta: %s)",
            event.getPlayer().getName(),
            event.getMine(),
            event.isCustomPickaxe() ? "PERSONALIZADA" : "PADRÃO"
        );
        plugin.getLogger().info(log);
    }
    
    @EventHandler
    public void onMinePacketQuit(MinePacketQuitEvent event) {
        String log = String.format(
            "[SAÍDA] %s saiu de %s",
            event.getPlayer().getName(),
            event.getMine()
        );
        plugin.getLogger().info(log);
    }
}

Exemplo 7: Distribuição de Recompensas Econômicas

@EventHandler
public void onMinePacketBreakBlock(MinePacketBreakBlockEvent event) {
    Player player = event.getPlayer();
    HashMap<PacketEconomyTypeHolder, Double> values = event.getValues();
    
    System.out.println("[RECOMPENSAS] " + player.getName());
    values.forEach((economy, amount) -> {
        System.out.println("  - " + economy + ": " + amount);
    });
}

Exemplo 8: Multiplicador de Recompensa Baseado em Material

@EventHandler
public void onMinePacketBreakBlock(MinePacketBreakBlockEvent event) {
    Material material = event.getMaterial();
    HashMap<PacketEconomyTypeHolder, Double> values = event.getValues();
    
    // Aplicar multiplicador baseado na raridade do material
    double multiplier = 1.0;
    
    switch (material) {
        case DIAMOND_ORE:
            multiplier = 2.5;
            break;
        case EMERALD_ORE:
            multiplier = 2.0;
            break;
        case GOLD_ORE:
            multiplier = 1.5;
            break;
    }
    
    final double finalMultiplier = multiplier;
    values.forEach((economy, amount) -> {
        values.put(economy, amount * finalMultiplier);
    });
    
    event.setValues(values);
}

Exemplo 9: Detecção Anti-Cheat em Mineração de Pacotes

public class PacketMineAnticheat implements Listener {
    
    private final Map<Player, Integer> blockBreaks = new HashMap<>();
    private final JavaPlugin plugin;
    
    public PacketMineAnticheat(JavaPlugin plugin) {
        this.plugin = plugin;
    }
    
    @EventHandler
    public void onMinePacketBreakBlock(MinePacketBreakBlockEvent event) {
        Player player = event.getPlayer();
        int breaks = blockBreaks.getOrDefault(player, 0) + 1;
        blockBreaks.put(player, breaks);
        
        // Verificar atividade suspeita (150+ blocos em 1 segundo)
        if (breaks > 150) {
            event.setCancelled(true);
            System.out.println("[ANTICHEAT] Mineração de pacotes suspeita detectada: " + 
                player.getName());
        }
        
        // Resetar após 1 segundo
        Bukkit.getScheduler().scheduleSyncDelayedTask(plugin, () -> 
            blockBreaks.put(player, 0), 20);
    }
}

Exemplo 10: Sistema de Bônus de Picareta Personalizada

public class CustomPickaxeBonus implements Listener {
    
    @EventHandler
    public void onMinePacketJoin(MinePacketJoinEvent event) {
        if (!event.isCustomPickaxe()) return;
        
        Player player = event.getPlayer();
        player.sendMessage("§6§lPICARETA PERSONALIZADA ATIVA!");
        player.sendMessage("§eGanhe 1.5x mais recompensas nesta mina");
    }
    
    @EventHandler
    public void onMinePacketBreakBlock(MinePacketBreakBlockEvent event) {
        if (!event.isCustomPickaxe()) return;
        
        HashMap<PacketEconomyTypeHolder, Double> values = event.getValues();
        
        // Aplicar bônus de picareta personalizada (1.5x)
        values.forEach((economy, amount) -> {
            values.put(economy, amount * 1.5);
        });
        
        event.setValues(values);
    }
}

Nesta página