API

Documentação completa da API do plugin yMinasPv, incluindo métodos para acessar dados de minas PvP, minas de jogadores, picaretas e manipulação de eventos relacionados a minas.

Obtendo a Instância da API

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

import br.com.ystoreplugins.product.yminaspv.MinePvAPIHolder;
import org.bukkit.Bukkit;

MinePvAPIHolder minePvAPI = (MinePvAPIHolder) Bukkit.getServicesManager()
    .load(MinePvAPIHolder.class);

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

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

import com.ystoreplugins.yminaspv.api.MinePvAPI;

MinePvAPI minePvAPI = new MinePvAPI();

Métodos Disponíveis

getMineByLocation()

Recupera uma mina com base na localização de um jogador.

Parâmetros:

location (Location) - A localização a verificar

Retorna:

Mine - O objeto Mine se a localização está dentro de uma mina, null caso contrário

Observações:

Usa detecção de colisão de cubóide para encontrar a mina
Verifica contra todas as minas em cache
Retorna a primeira mina contendo a localização
Útil para detectar quando jogadores entram/saem de minas

Location playerLocation = player.getLocation();
Mine mine = minePvAPI.getMineByLocation(playerLocation);
if (mine != null) {
    System.out.println("O jogador está na mina: " + mine.getId());
}

getMineById()

Recupera uma mina específica pelo seu identificador único.

Parâmetros:

id (String) - O identificador único da mina

Retorna:

Mine - O objeto Mine, ou null se não encontrada

Observações:

Retorna null se o identificador da mina não existir
Recupera das minas em cache para desempenho
Use isto para acessar configuração da mina e propriedades

Mine mine = minePvAPI.getMineById("pvp_mine_1");
if (mine != null) {
    System.out.println("Mina encontrada: " + mine.getId());
}

getPlayerMine()

Recupera o detentor de dados da mina para um jogador específico pelo nome de usuário.

Parâmetros:

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

Retorna:

PlayerMine - Objeto contendo todos os dados de mina do jogador, ou null se 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 isto para acessar informações de mina específicas do jogador

PlayerMine playerData = minePvAPI.getPlayerMine("PlayerName");
if (playerData != null) {
    System.out.println("Dados de mina do jogador carregados");
}

getPlayerMine() (sobrecarga de Player)

Recupera o detentor de dados da mina para um objeto de jogador.

Parâmetros:

player (Player) - A instância do Player

Retorna:

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

Observações:

Método de conveniência que chama getPlayerMine(String) internamente
Mesma funcionalidade que a versão baseada em string
Mais intuitivo ao trabalhar com objetos Player

PlayerMine playerData = minePvAPI.getPlayerMine(player);
if (playerData != null) {
    System.out.println("Dados do jogador recuperados");
}

getByPlayerHand()

Recupera dados de picareta do item que um jogador está segurando.

Parâmetros:

player (Player) - A instância do Player

Retorna:

Pickaxe - Objeto Pickaxe com encantos e estatísticas, ou null se não for uma picareta válida

Observações:

Usa leitura de tag NBT para extrair dados de picareta
Retorna null se o jogador não está segurando um item ou o item não é uma picareta
Picareta deve ter a tag NBT "yMinasPv-Tool"
Útil para validar picaretas durante mineração

Pickaxe pickaxe = minePvAPI.getByPlayerHand(player);
if (pickaxe != null) {
    System.out.println("O jogador está segurando uma picareta válida");
}

getByItem()

Recupera dados de picareta de um ItemStack.

Parâmetros:

itemStack (ItemStack) - O ItemStack a verificar

Retorna:

Pickaxe - Objeto Pickaxe com encantos e estatísticas, ou null se não for uma picareta válida

Observações:

Usa leitura de tag NBT para extrair dados de picareta
Retorna null se itemstack é null ou não é uma picareta
Picareta deve ter a tag NBT "yMinasPv-Tool"
Funciona com itemstacks do inventário ou do chão

ItemStack item = player.getItemInHand();
Pickaxe pickaxe = minePvAPI.getByItem(item);
if (pickaxe != null) {
    System.out.println("O item é uma picareta válida");
}

deserializePickaxe()

Desserializa uma picareta de sua representação de string JSON.

Parâmetros:

pickaxe (String) - Representação de string JSON de uma picareta

Retorna:

Pickaxe - Objeto Pickaxe desserializado

Observações:

Usa Gson para desserialização JSON
Útil para reconstruir picaretas de dados armazenados
Picareta deve estar em formato JSON válido
Operação inversa da serialização de picareta

String pickaxeJson = "{...}"; // Dados JSON de picareta
Pickaxe pickaxe = minePvAPI.deserializePickaxe(pickaxeJson);
System.out.println("Picareta desserializada com sucesso");

Estruturas de Dados

Mine

Representa uma mina PvP no plugin. Contém:

Identificador e nome da mina
Definição de região cubóide (mundo, coordenadas mín/máx)
Configuração de recompensas
Configuração de encantamento
Listas de controle de acesso

PlayerMine

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

Pickaxe

Representa uma picareta de mineração com encantos personalizados. Contém:

Nível de camada/raridade da picareta
Encantos personalizados e níveis
Informações de durabilidade
Efeitos especiais e bônus
Dados de tag NBT

Cuboid

Representa uma região 3D para limites de mina. Contém:

Referência do mundo
Coordenadas mínimas (x, y, z)
Coordenadas máximas (x, y, z)
Métodos de detecção de colisão

Eventos

MineBreakBlockEvent

Acionado quando um jogador quebra blocos em uma mina.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getMine() - Retorna o MineHolder representando a mina
getBlockList() - Retorna uma List<Block> de blocos quebrados
getEconomies() - Retorna um HashMap com valores de economia (moeda -> quantidade)
setEconomies(HashMap<String, Double>) - Modifica as recompensas econômicas

Observações:

Dispara quando múltiplos blocos podem ser quebrados simultaneamente
Valores de economia representam as recompensas totais para todos os blocos
A lista de blocos pode conter múltiplos blocos de uma ação de picareta
Este evento NÃO é cancelável

Exemplo:

@EventHandler
public void onMineBreakBlock(MineBreakBlockEvent event) {
    Player player = event.getPlayer();
    MineHolder mine = event.getMine();
    List<Block> blocks = event.getBlockList();
    
    System.out.println(player.getName() + " quebrou " + blocks.size() + 
        " blocos em " + mine);
}

Melhores Práticas

Sempre verifique null ao recuperar dados de mina ou jogador
Use getMineByLocation() para detectar quando jogadores entram/saem de minas
Valide picaretas usando getByPlayerHand() ou getByItem() antes de processar
Cache dados de mina se acessar frequentemente as mesmas informações
Modifique valores de economia com segurança no evento usando setters
Manipule operações de lista com cuidado ao trabalhar com múltiplos blocos em MineBreakBlockEvent
Use sobrecarga de Player quando já tiver um objeto Player para conveniência

Exemplos de Uso

Exemplo 1: Detectando Entrada/Saída de Mina

@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
    MinePvAPIHolder api = (MinePvAPIHolder) Bukkit.getServicesManager()
        .load(MinePvAPIHolder.class);
    
    Mine toMine = api.getMineByLocation(event.getTo());
    Mine fromMine = api.getMineByLocation(event.getFrom());
    
    // Jogador entrou em uma mina
    if (toMine != null && fromMine == null) {
        event.getPlayer().sendMessage("§aVocê entrou em: " + toMine.getId());
    }
    // Jogador saiu de uma mina
    else if (toMine == null && fromMine != null) {
        event.getPlayer().sendMessage("§cVocê saiu da mina");
    }
}

Exemplo 2: Obtendo Dados de Mina do Jogador

MinePvAPIHolder api = (MinePvAPIHolder) Bukkit.getServicesManager()
    .load(MinePvAPIHolder.class);

PlayerMine playerData = api.getPlayerMine(player);
if (playerData != null) {
    System.out.println("Dados de mina do jogador carregados com sucesso");
}

Exemplo 3: Validando Picareta em Mão

MinePvAPIHolder api = (MinePvAPIHolder) Bukkit.getServicesManager()
    .load(MinePvAPIHolder.class);

Pickaxe pickaxe = api.getByPlayerHand(player);
if (pickaxe != null) {
    player.sendMessage("§aVocê está segurando uma picareta válida!");
} else {
    player.sendMessage("§cVocê precisa de uma picareta válida para minerar aqui");
}

Exemplo 4: Rastreamento de Evento de Mineração

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

public class MineEventTracker implements Listener {
    
    @EventHandler
    public void onMineBreakBlock(MineBreakBlockEvent event) {
        Player player = event.getPlayer();
        int blockCount = event.getBlockList().size();
        
        System.out.println("[MINA] " + player.getName() + 
            " - Blocos quebrados: " + blockCount);
    }
}

Exemplo 5: Modificando Recompensas de Mina

@EventHandler
public void onMineBreakBlock(MineBreakBlockEvent event) {
    HashMap<String, Double> economies = event.getEconomies();
    
    // Aumentar todas as recompensas em 25%
    economies.forEach((currency, amount) -> {
        economies.put(currency, amount * 1.25);
    });
    
    event.setEconomies(economies);
}

Exemplo 6: Distribuição de Recompensas de Múltiplos Blocos

@EventHandler
public void onMineBreakBlock(MineBreakBlockEvent event) {
    Player player = event.getPlayer();
    List<Block> blocks = event.getBlockList();
    HashMap<String, Double> economies = event.getEconomies();
    
    System.out.println("[QUEBRA MINA] " + player.getName());
    System.out.println("  Blocos: " + blocks.size());
    economies.forEach((currency, amount) -> {
        System.out.println("  - " + currency + ": " + amount);
    });
}

Exemplo 7: Rastreamento de Durabilidade de Picareta

MinePvAPIHolder api = (MinePvAPIHolder) Bukkit.getServicesManager()
    .load(MinePvAPIHolder.class);

Pickaxe pickaxe = api.getByPlayerHand(player);
if (pickaxe != null) {
    // Verificar e gerenciar durabilidade da picareta
    System.out.println("Camada de picareta: " + pickaxe);
    
    // Aplicar perda de durabilidade
    if (canBreakBlocks(player)) {
        // Processar mineração...
    }
}

Exemplo 8: Multiplicador de Economia por Mina

@EventHandler
public void onMineBreakBlock(MineBreakBlockEvent event) {
    MineHolder mine = event.getMine();
    HashMap<String, Double> economies = event.getEconomies();
    
    // Aplicar multiplicador baseado no nível da mina
    double multiplier = 1.0;
    
    if (mine.getId().contains("elite")) {
        multiplier = 2.0;
    } else if (mine.getId().contains("vip")) {
        multiplier = 1.5;
    }
    
    final double finalMultiplier = multiplier;
    economies.forEach((currency, amount) -> {
        economies.put(currency, amount * finalMultiplier);
    });
    
    event.setEconomies(economies);
}

Exemplo 9: Bônus Baseado em Contagem de Blocos

@EventHandler
public void onMineBreakBlock(MineBreakBlockEvent event) {
    int blockCount = event.getBlockList().size();
    HashMap<String, Double> economies = event.getEconomies();
    
    // Bônus por quebrar múltiplos blocos
    double bonus = 1.0 + (blockCount * 0.05); // 5% por bloco
    
    economies.forEach((currency, amount) -> {
        economies.put(currency, amount * bonus);
    });
    
    event.setEconomies(economies);
}

Exemplo 10: Controle de Acesso a Mina

@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
    MinePvAPIHolder api = (MinePvAPIHolder) Bukkit.getServicesManager()
        .load(MinePvAPIHolder.class);
    
    Mine toMine = api.getMineByLocation(event.getTo());
    
    if (toMine != null) {
        Player player = event.getPlayer();
        PlayerMine playerMine = api.getPlayerMine(player);
        
        // Verificar nível de acesso ou permissões
        if (playerMine == null) {
            event.setCancelled(true);
            player.sendMessage("§cVocê não tem acesso a esta mina!");
        }
    }
}

Nesta página