API

Documentação completa da API do plugin yPesca, incluindo métodos para acessar dados de pesca do jogador e manipulação de eventos relacionados a pesca.

Obtendo a Instância da API

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

import br.com.ystoreplugins.product.ypesca.PescaAPIHolder;
import org.bukkit.Bukkit;

PescaAPIHolder pescaAPI = (PescaAPIHolder) Bukkit.getServicesManager()
    .load(PescaAPIHolder.class);

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

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

import com.ystoreplugins.ypesca.api.PescaAPI;

PescaAPI pescaAPI = new PescaAPI();

Métodos Disponíveis

getPlayer()

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

Parâmetros:

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

Retorna:

PlayerFishHolder - Objeto contendo todos os dados de pesca 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 pesca específicas do jogador
Contém estatísticas de pesca e dados de peixes capturados

PlayerFishHolder playerData = pescaAPI.getPlayer("PlayerName");
if (playerData != null) {
    // Acessar dados de pesca do jogador
}

run()

Método interno para manipular sincronização de dados de jogador entre servidores (suporte Bungee). Não use em plugins externos.

Parâmetros:

array (String[]) - Array contendo UUID (array[0])

Observações:

Reservado apenas para uso interno do plugin
Manipula coordenação de servidor Bungee
Gerencia carregamento de dados de jogador pendente com atrasos configuráveis

Estruturas de Dados

PlayerFishHolder

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

Lista de peixes capturados
Experiência e nível de pesca
Estatísticas de coleta de peixes
Melhores capturas e registros
Inventário de equipamento de pesca

FishHolder

Representa um tipo específico de peixe. Contém:

Identificador e nome do peixe
Propriedades de exibição do peixe
Descrição e lore
Dados de modelo se aplicável

RarityHolder

Representa o nível de raridade de um peixe capturado. Contém:

Identificador e nome da raridade
Codificação de cor
Taxa de queda/chance de aparição
Multiplicadores de valor
Formatação de exibição

Eventos

PescaFishEvent

Acionado quando um jogador captura com sucesso um peixe. Este evento é cancelável.

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player
getFish() - Retorna o FishHolder representando o peixe capturado
getRarity() - Retorna o RarityHolder indicando raridade do peixe
getWeight() - Retorna o peso do peixe capturado (double)
isCancelled() - Verifica se o evento foi cancelado
setCancelled(boolean) - Cancela a captura do peixe

Observações:

Dispara quando um jogador captura com sucesso um peixe
Raridade determina valor do peixe e propriedades cosméticas
Peso pode ser usado em sistemas de pontuação
Cancelar impede que o peixe seja adicionado ao inventário

Exemplo:

@EventHandler
public void onPescaFish(PescaFishEvent event) {
    if (event.isCancelled()) return;
    
    Player player = event.getPlayer();
    FishHolder fish = event.getFish();
    RarityHolder rarity = event.getRarity();
    double weight = event.getWeight();
    
    System.out.println(player.getName() + " capturou um " + rarity + " " + fish + 
        " pesando " + weight + " unidades");
}

PescaJoinEvent

Acionado quando um jogador entra no sistema de pesca (carrega seus dados).

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player

Exemplo:

@EventHandler
public void onPescaJoin(PescaJoinEvent event) {
    Player player = event.getPlayer();
    System.out.println(player.getName() + " começou a pescar");
}

PescaQuitEvent

Acionado quando um jogador sai do sistema de pesca (descarrega seus dados).

Métodos Disponíveis:

getPlayer() - Retorna a instância do Player

Exemplo:

@EventHandler
public void onPescaQuit(PescaQuitEvent event) {
    Player player = event.getPlayer();
    System.out.println(player.getName() + " parou de pescar");
}

Melhores Práticas

Sempre verifique null ao recuperar dados de pesca do jogador
Valide a configuração Bungee se usar sincronização de pesca entre servidores
Ouça eventos para rastrear capturas em vez de modificar dados diretamente
Cancele eventos com responsabilidade para não quebrar o sistema de pesca
Cache dados do jogador se acessar frequentemente as informações do mesmo jogador
Use valores de peso para sistemas de pontuação ou conquistas
Verifique raridade para aplicar bônus especiais ou efeitos cosméticos

Exemplos de Uso

Exemplo 1: Obtendo Dados de Pesca do Jogador

PescaAPIHolder pescaAPI = (PescaAPIHolder) Bukkit.getServicesManager()
    .load(PescaAPIHolder.class);

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

Exemplo 2: Rastreando Capturas de Peixes

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.ypesca.event.PescaFishEvent;

public class FishCatchTracker implements Listener {
    
    @EventHandler
    public void onPescaFish(PescaFishEvent event) {
        Player player = event.getPlayer();
        FishHolder fish = event.getFish();
        
        System.out.println("[PEIXE] " + player.getName() + " capturou: " + fish);
    }
}

Exemplo 3: Bônus de Peixe Raro

@EventHandler
public void onPescaFish(PescaFishEvent event) {
    if (event.isCancelled()) return;
    
    RarityHolder rarity = event.getRarity();
    
    // Verificar se é um peixe raro ou lendário
    if (rarity.toString().contains("Legendary")) {
        event.getPlayer().sendMessage("§6§l✯ CAPTURA LENDÁRIA! ✯");
        event.getPlayer().playSound(event.getPlayer().getLocation(), 
            org.bukkit.Sound.UI_TOAST_CHALLENGE_COMPLETE, 1.0f, 1.0f);
    } else if (rarity.toString().contains("Rare")) {
        event.getPlayer().sendMessage("§5Peixe raro capturado!");
    }
}

Exemplo 4: Recompensas Baseadas em Peso

@EventHandler
public void onPescaFish(PescaFishEvent event) {
    if (event.isCancelled()) return;
    
    double weight = event.getWeight();
    
    // Recompensa baseada em peso
    if (weight > 100) {
        event.getPlayer().sendMessage("§aCaptura gigante! +" + (weight / 10) + " pontos");
    } else if (weight > 50) {
        event.getPlayer().sendMessage("§eCaptura grande! +" + (weight / 10) + " pontos");
    }
}

Exemplo 5: Prevenindo Captura de Certos Peixes

@EventHandler
public void onPescaFish(PescaFishEvent event) {
    FishHolder fish = event.getFish();
    
    // Impedir captura de tipos específicos de peixes
    if (fish.toString().contains("toxic")) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("§cEste peixe é muito tóxico para capturar!");
    }
}

Exemplo 6: Registro de Sessão de Pesca

public class FishingSessionLogger implements Listener {
    
    private final JavaPlugin plugin;
    
    public FishingSessionLogger(JavaPlugin plugin) {
        this.plugin = plugin;
    }
    
    @EventHandler
    public void onPescaJoin(PescaJoinEvent event) {
        String log = String.format(
            "[ENTRADA] %s começou a sessão de pesca em %s",
            event.getPlayer().getName(),
            System.currentTimeMillis()
        );
        plugin.getLogger().info(log);
    }
    
    @EventHandler
    public void onPescaQuit(PescaQuitEvent event) {
        String log = String.format(
            "[SAÍDA] %s encerrou a sessão de pesca em %s",
            event.getPlayer().getName(),
            System.currentTimeMillis()
        );
        plugin.getLogger().info(log);
    }
}

Exemplo 7: Efeitos Cosméticos Baseados em Raridade

@EventHandler
public void onPescaFish(PescaFishEvent event) {
    if (event.isCancelled()) return;
    
    Player player = event.getPlayer();
    RarityHolder rarity = event.getRarity();
    
    // Aplicar efeitos de partícula baseado em raridade
    if (rarity.toString().contains("Legendary")) {
        player.getWorld().spawnParticle(
            org.bukkit.Particle.DRAGON_BREATH,
            player.getLocation(),
            20,
            0.5, 0.5, 0.5,
            0.1
        );
    } else if (rarity.toString().contains("Epic")) {
        player.getWorld().spawnParticle(
            org.bukkit.Particle.END_ROD,
            player.getLocation(),
            15,
            0.3, 0.3, 0.3,
            0.1
        );
    }
}

Exemplo 8: Rastreamento de Peso Total

public class WeightTracker implements Listener {
    
    private final Map<Player, Double> sessionWeights = new HashMap<>();
    
    @EventHandler
    public void onPescaFish(PescaFishEvent event) {
        if (event.isCancelled()) return;
        
        Player player = event.getPlayer();
        double weight = event.getWeight();
        
        double totalWeight = sessionWeights.getOrDefault(player, 0.0) + weight;
        sessionWeights.put(player, totalWeight);
        
        player.sendMessage("§ePeso da sessão: " + String.format("%.2f", totalWeight));
    }
    
    @EventHandler
    public void onPescaQuit(PescaQuitEvent event) {
        sessionWeights.remove(event.getPlayer());
    }
}

Exemplo 9: Marco de Coleta de Peixes

@EventHandler
public void onPescaFish(PescaFishEvent event) {
    if (event.isCancelled()) return;
    
    Player player = event.getPlayer();
    PescaAPIHolder api = (PescaAPIHolder) Bukkit.getServicesManager()
        .load(PescaAPIHolder.class);
    
    PlayerFishHolder data = api.getPlayer(player.getName());
    if (data != null) {
        // Verificar se marco foi alcançado (exemplo: 100 capturas)
        int catchCount = getCatchCount(data); // Implementação necessária
        
        if (catchCount == 100) {
            player.sendMessage("§a§l✓ Marco: 100 Peixes Capturados!");
        } else if (catchCount % 50 == 0) {
            player.sendMessage("§e" + catchCount + " peixes capturados!");
        }
    }
}

private int getCatchCount(PlayerFishHolder data) {
    // Implementação para contar total de capturas
    return 0;
}

Exemplo 10: Sistema de Conquistas de Pesca

public class FishingAchievements implements Listener {
    
    private final Set<String> achievements = new HashSet<>();
    
    @EventHandler
    public void onPescaFish(PescaFishEvent event) {
        if (event.isCancelled()) return;
        
        Player player = event.getPlayer();
        FishHolder fish = event.getFish();
        double weight = event.getWeight();
        
        String playerKey = player.getUniqueId().toString();
        
        // Primeira captura
        if (!achievements.contains(playerKey + "_first")) {
            achievements.add(playerKey + "_first");
            player.sendMessage("§a§l✓ Conquista Desbloqueada: Primeira Captura!");
        }
        
        // Captura pesada
        if (weight > 100 && !achievements.contains(playerKey + "_heavy")) {
            achievements.add(playerKey + "_heavy");
            player.sendMessage("§a§l✓ Conquista Desbloqueada: Peso Pesado!");
        }
        
        // Captura lendária
        if (event.getRarity().toString().contains("Legendary") && 
            !achievements.contains(playerKey + "_legendary")) {
            achievements.add(playerKey + "_legendary");
            player.sendMessage("§a§l✓ Conquista Desbloqueada: Pescador Lendário!");
        }
    }
}

Nesta página