API

Documentação completa da API do plugin yPlantacoes, incluindo métodos para acessar dados de fazenda do jogador e manipulação de eventos de colheita de culturas.

Obtendo a Instância da API

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

import br.com.ystoreplugins.product.yplantacoes.PlantacaoAPIHolder;
import org.bukkit.Bukkit;

PlantacaoAPIHolder plantacaoAPI = (PlantacaoAPIHolder) Bukkit.getServicesManager()
    .load(PlantacaoAPIHolder.class);

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

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

import com.ystoreplugins.yplantacoes.api.PlantacaoAPI;

PlantacaoAPI plantacaoAPI = new PlantacaoAPI();

Métodos Disponíveis

getPlayer()

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

Parâmetros:

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

Retorna:

PlayerFarmHolder - Objeto contendo todos os dados de fazenda 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 agricultura específicas do jogador
Contém inventário de culturas e estatísticas de agricultura

PlayerFarmHolder playerData = plantacaoAPI.getPlayer("PlayerName");
if (playerData != null) {
    // Acessar dados de fazenda do jogador
}

Estruturas de Dados

PlayerFarmHolder

Contém todos os dados relacionados a agricultura para um jogador. Mantém:

Parcelas de fazenda possuídas
Culturas plantadas e estágios de crescimento
Inventário de culturas colhidas
Experiência e nível de agricultura
Configurações de automação de fazenda

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

Eventos

PlantacoesPreBreakEvent

Evento preliminar acionado ANTES que um jogador quebre/colha uma cultura. Este evento é cancelável e permite que você impeça colheitas antes do processamento de recompensas.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getBlock() - Retorna o Block sendo colhido
isCancelled() - Verifica se o evento foi cancelado
setCancelled(boolean) - Cancela a colheita

Observações:

Este evento dispara ANTES que queda e cálculos de moedas sejam feitos
Útil para impedir colheitas em certos locais ou condições
Mais eficiente para cancelamento antecipado que PlantacoesBreakEvent
Referência de bloco permite validação de tipo de cultura

Exemplo:

@EventHandler
public void onPlantacoesPreBreak(PlantacoesPreBreakEvent event) {
    if (event.isCancelled()) return;
    
    Block block = event.getBlock();
    
    // Impedir colheita em regiões específicas
    if (isProtectedArea(block.getLocation())) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("§cNão é possível colher nesta área!");
    }
}

PlantacoesBreakEvent

Acionado quando um jogador colhe uma cultura. Este evento NÃO é cancelável.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getBlock() - Retorna o Block sendo colhido
getDropAmount() - Retorna a quantidade de quedas de cultura
getCoinAmount() - Retorna moedas obtidas da colheita
getValor() - Retorna um HashMap com valores de economia (moeda -> quantidade)
setValor(HashMap<EconomyTypeHolder, Double>) - Modifica as recompensas econômicas
setDropAmount(double) - Modifica a quantidade de queda
setCoinAmount(double) - Modifica a quantidade de moedas

Observações:

Dispara APÓS verificações preliminares (use PlantacoesPreBreakEvent para impedir antes do cálculo)
Quantidade de queda e valores de moeda são determinados neste ponto
Valores de economia podem ser modificados antes das recompensas serem distribuídas
Múltiplas moedas de economia podem estar presentes no HashMap de valor

Exemplo:

@EventHandler
public void onPlantacoesBreak(PlantacoesBreakEvent event) {
    Player player = event.getPlayer();
    Block block = event.getBlock();
    
    System.out.println(player.getName() + " colheu em " + block.getLocation());
}

Melhores Práticas

Sempre verifique null ao recuperar dados de fazenda do jogador
Use PlantacoesPreBreakEvent para cancelamento antecipado (antes do cálculo)
Use PlantacoesBreakEvent para modificar recompensas após cálculo
Modifique valores de economia com segurança no evento usando setters
Cache dados do jogador se acessar frequentemente as informações do mesmo jogador
Manipule múltiplas economias ao modificar HashMap de valor
Valide localizações de bloco antes de aplicar lógica específica de região

Exemplos de Uso

Exemplo 1: Obtendo Dados de Fazenda do Jogador

PlantacaoAPIHolder plantacaoAPI = (PlantacaoAPIHolder) Bukkit.getServicesManager()
    .load(PlantacaoAPIHolder.class);

PlayerFarmHolder playerData = plantacaoAPI.getPlayer(player.getName());
if (playerData != null) {
    System.out.println("Dados de fazenda do jogador carregados com sucesso");
}

Exemplo 2: Prevenindo Colheita em Regiões Protegidas

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.yplantacoes.event.PlantacoesPreBreakEvent;

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

Exemplo 3: Rastreando Colheitas de Culturas

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.yplantacoes.event.PlantacoesBreakEvent;

public class HarvestTracker implements Listener {
    
    @EventHandler
    public void onPlantacoesBreak(PlantacoesBreakEvent event) {
        Player player = event.getPlayer();
        double drops = event.getDropAmount();
        
        System.out.println("[COLHEITA] " + player.getName() + 
            " - Quedas: " + drops);
    }
}

Exemplo 4: Modificando Recompensas de Colheita

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

Exemplo 5: Bônus para Colheita em Massa

@EventHandler
public void onPlantacoesBreak(PlantacoesBreakEvent event) {
    double drops = event.getDropAmount();
    
    // Aplicar bônus por colheita de múltiplas culturas
    if (drops > 10) {
        HashMap<EconomyTypeHolder, Double> valor = event.getValor();
        double bonus = 1.0 + ((drops - 10) * 0.05); // 5% por cultura extra
        
        valor.forEach((economy, amount) -> {
            valor.put(economy, amount * bonus);
        });
        
        event.setValor(valor);
        event.getPlayer().sendMessage("§aBônus de colheita em massa aplicado!");
    }
}

Exemplo 6: Rastreamento de Eficiência de Colheita

public class HarvestEfficiencyTracker implements Listener {
    
    private final JavaPlugin plugin;
    
    public HarvestEfficiencyTracker(JavaPlugin plugin) {
        this.plugin = plugin;
    }
    
    @EventHandler
    public void onPlantacoesBreak(PlantacoesBreakEvent event) {
        String log = String.format(
            "[COLHEITA] %s - Quedas: %.2f | Moedas: %.2f",
            event.getPlayer().getName(),
            event.getDropAmount(),
            event.getCoinAmount()
        );
        plugin.getLogger().info(log);
    }
}

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

@EventHandler
public void onPlantacoesBreak(PlantacoesBreakEvent 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 8: Bônus de Colheita Baseados em Tempo

@EventHandler
public void onPlantacoesBreak(PlantacoesBreakEvent event) {
    int hour = org.bukkit.Bukkit.getServer().getWorldType().
        getWorld().getTime();
    
    double multiplier = 1.0;
    
    // Recompensas maiores à noite (12000-24000)
    if (hour > 12000) {
        multiplier = 1.5;
        event.getPlayer().sendMessage("§6Bônus de colheita noturna!");
    }
    
    event.setDropAmount(event.getDropAmount() * multiplier);
    event.setCoinAmount(event.getCoinAmount() * multiplier);
}

Exemplo 9: Multiplicador de Qualidade de Cultura

@EventHandler
public void onPlantacoesBreak(PlantacoesBreakEvent event) {
    org.bukkit.block.Block block = event.getBlock();
    
    // Exemplo: culturas em altitudes maiores têm melhor qualidade
    if (block.getY() > 100) {
        HashMap<EconomyTypeHolder, Double> valor = event.getValor();
        
        valor.forEach((economy, amount) -> {
            valor.put(economy, amount * 1.25); // Bônus de 25% de altitude
        });
        
        event.setValor(valor);
    }
}

Exemplo 10: Registrador Compreensivo de Agricultura

public class FarmingComprehensiveLogger implements Listener {
    
    private final JavaPlugin plugin;
    private final Map<String, Integer> harvestCount = new HashMap<>();
    private final Map<String, Double> totalEarnings = new HashMap<>();
    
    public FarmingComprehensiveLogger(JavaPlugin plugin) {
        this.plugin = plugin;
    }
    
    @EventHandler
    public void onPlantacoesPreBreak(PlantacoesPreBreakEvent event) {
        plugin.getLogger().info("[PRE-COLHEITA] " + event.getPlayer().getName() + 
            " em " + event.getBlock().getLocation());
    }
    
    @EventHandler
    public void onPlantacoesBreak(PlantacoesBreakEvent event) {
        String playerName = event.getPlayer().getName();
        
        // Rastrear contagem de colheita
        int count = harvestCount.getOrDefault(playerName, 0) + 1;
        harvestCount.put(playerName, count);
        
        // Rastrear ganhos
        double totalCoins = event.getCoinAmount();
        event.getValor().values().forEach(amount -> totalCoins += amount);
        
        double earnings = totalEarnings.getOrDefault(playerName, 0.0) + totalCoins;
        totalEarnings.put(playerName, earnings);
        
        String log = String.format(
            "[COLHEITA] %s (Total: #%d) - Ganhos: %.2f",
            playerName,
            count,
            earnings
        );
        plugin.getLogger().info(log);
    }
}

Nesta página