API

Documentação completa da API do plugin yMinas, incluindo métodos para acessar dados de minas, informações de minas do jogador e manipulação de eventos relacionados a minas.

Obtendo a Instância da API

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

import br.com.ystoreplugins.product.yminas.MinaAPIHolder;
import org.bukkit.Bukkit;

MinaAPIHolder minaAPI = (MinaAPIHolder) Bukkit.getServicesManager()
    .load(MinaAPIHolder.class);

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

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

import com.ystoreplugins.yminas.api.MinaAPI;

MinaAPI minaAPI = new MinaAPI();

Métodos Disponíveis

retrieveMina()

Recupera uma mina específica pelo seu identificador.

Parâmetros:

mina (String) - O identificador único da mina

Retorna:

MinaHolder - Objeto contendo dados da mina, ou null se a mina não for 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

MinaHolder mine = minaAPI.retrieveMina("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:

PlayerMineHolder - 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 mapa de jogadores em cache
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 específicas do jogador

PlayerMineHolder playerData = minaAPI.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

MinaHolder

Representa uma mina no plugin. Contém:

Identificador e nome da mina
Configuração da mina
Recompensas de blocos e taxas de queda
Configuração de recompensas econômicas
Informações de picareta personalizada

PlayerMineHolder

Contém todos os dados relacionados a minas 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

EconomyTypeHolder

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

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

RecompensaHolder

Representa uma recompensa/compensação de mina. Contém:

Tipo e quantidade de recompensa
Método de entrega
Condições associadas

Eventos

MineBreakBlockEvent

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

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getMina() - Retorna o MinaHolder representando a mina
getBloco() - Retorna o Block que foi quebrado
getMaterial() - Retorna o tipo de Material do bloco quebrado
getValor() - Retorna um HashMap com valores de economia (moeda -> quantidade)
setValor(HashMap<EconomyTypeHolder, Double>) - Modifica as recompensas econômicas
isCancelled() - Verifica se o evento foi cancelado
setCancelled(boolean) - Cancela a quebra do bloco

Exemplo:

@EventHandler
public void onMineBreakBlock(MineBreakBlockEvent event) {
    if (event.isCancelled()) return;
    
    Player player = event.getPlayer();
    MinaHolder mine = event.getMina();
    Material material = event.getMaterial();
    
    System.out.println(player.getName() + " quebrou " + material + " em " + mine);
}

MineJoinEvent

Acionado quando um jogador entra em uma mina.

Métodos Disponíveis:

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

Exemplo:

@EventHandler
public void onMineJoin(MineJoinEvent event) {
    Player player = event.getPlayer();
    MinaHolder mine = event.getMina();
    boolean hasCustomPickaxe = event.isCustomPickaxe();
    
    System.out.println(player.getName() + " entrou na mina: " + mine);
    if (hasCustomPickaxe) {
        System.out.println("O jogador está usando uma picareta personalizada");
    }
}

MineQuitEvent

Acionado quando um jogador sai de uma mina.

Métodos Disponíveis:

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

Exemplo:

@EventHandler
public void onMineQuit(MineQuitEvent event) {
    Player player = event.getPlayer();
    MinaHolder mine = event.getMina();
    
    System.out.println(player.getName() + " saiu da mina: " + mine);
}

MineRewardEvent

Acionado quando um jogador recebe uma recompensa por mineração. Este evento é cancelável.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getMina() - Retorna o MinaHolder onde a recompensa foi obtida
getRecompensa() - Retorna o RecompensaHolder com detalhes da recompensa
isCancelled() - Verifica se o evento foi cancelado
setCancelled(boolean) - Cancela a recompensa

Exemplo:

@EventHandler
public void onMineReward(MineRewardEvent event) {
    if (event.isCancelled()) return;
    
    Player player = event.getPlayer();
    RecompensaHolder reward = event.getRecompensa();
    
    System.out.println(player.getName() + " recebeu uma recompensa");
}

Melhores Práticas

Sempre verifique null ao recuperar dados de mina ou jogador
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 MineBreakBlockEvent usando setters
Cache dados de mina se acessar frequentemente as mesmas informações
Use verificações de picareta personalizada para aplicar lógica de bônus especial
Cancele eventos com responsabilidade para não quebrar o sistema de mineração

Exemplos de Uso

Exemplo 1: Obtendo Informações da Mina

MinaAPIHolder minaAPI = (MinaAPIHolder) Bukkit.getServicesManager()
    .load(MinaAPIHolder.class);

MinaHolder mine = minaAPI.retrieveMina("vip_mine");
if (mine != null) {
    System.out.println("Mina recuperada com sucesso");
} else {
    System.out.println("Mina não encontrada");
}

Exemplo 2: Obtendo Dados de Mina do Jogador

MinaAPIHolder minaAPI = (MinaAPIHolder) Bukkit.getServicesManager()
    .load(MinaAPIHolder.class);

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

Exemplo 3: Rastreando Quebras de Blocos em Minas

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.yminas.event.MineBreakBlockEvent;

public class MineBlockTracker implements Listener {
    
    @EventHandler
    public void onMineBreakBlock(MineBreakBlockEvent event) {
        Player player = event.getPlayer();
        MinaHolder mine = event.getMina();
        
        System.out.println("[MINA] " + player.getName() + 
            " - Blocos quebrados em: " + mine);
    }
}

Exemplo 4: Modificando Recompensas de Mina

@EventHandler
public void onMineBreakBlock(MineBreakBlockEvent event) {
    HashMap<EconomyTypeHolder, Double> valor = event.getValor();
    
    // Aumentar todas as recompensas em 25%
    valor.forEach((economy, amount) -> {
        valor.put(economy, amount * 1.25);
    });
    
    event.setValor(valor);
}

Exemplo 5: Bônus para Picareta Personalizada

@EventHandler
public void onMineJoin(MineJoinEvent event) {
    Player player = event.getPlayer();
    
    if (event.isCustomPickaxe()) {
        player.sendMessage("§aVocê está usando uma picareta personalizada!");
        player.sendMessage("§eGanhe +50% de recompensas!");
    }
}

Exemplo 6: Prevenindo Recompensa de Mina Específica

@EventHandler
public void onMineReward(MineRewardEvent event) {
    MinaHolder mine = event.getMina();
    
    // Cancelar recompensas de uma mina específica
    if (mine.equals("restricted_mine")) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("§cRecompensas desativadas nesta mina");
    }
}

Exemplo 7: Registro de Sessão de Mineração

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

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

@EventHandler
public void onMineBreakBlock(MineBreakBlockEvent event) {
    Player player = event.getPlayer();
    HashMap<EconomyTypeHolder, Double> valor = event.getValor();
    
    System.out.println("[RECOMPENSAS] " + player.getName());
    valor.forEach((economy, amount) -> {
        System.out.println("  - " + economy + ": " + amount);
    });
}

Exemplo 9: Multiplicador de Recompensa por Nível

@EventHandler
public void onMineBreakBlock(MineBreakBlockEvent event) {
    MinaHolder mine = event.getMina();
    HashMap<EconomyTypeHolder, Double> valor = event.getValor();
    
    // Aplicar multiplicador baseado no nível da mina
    double multiplier = 1.0;
    
    if (mine.toString().contains("vip")) {
        multiplier = 1.5;
    } else if (mine.toString().contains("elite")) {
        multiplier = 2.0;
    }
    
    valor.forEach((economy, amount) -> {
        valor.put(economy, amount * multiplier);
    });
    
    event.setValor(valor);
}

Exemplo 10: Detecção Anti-Cheat em Mineração

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

Nesta página