API

Documentação completa da API do plugin ySpawners, incluindo métodos para gerenciar entidades de spawner empilhadas e manipulação de eventos relacionados a spawner.

Obtendo a Instância da API

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

import br.com.ystoreplugins.product.yspawnersv2.SpawnerV2APIHolder;
import org.bukkit.Bukkit;

SpawnerV2APIHolder spawnerAPI = (SpawnerV2APIHolder) Bukkit.getServicesManager()
    .load(SpawnerV2APIHolder.class);

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

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

import com.ystoreplugins.yspawnersv2.api.SpawnerAPI;

SpawnerAPI spawnerAPI = new SpawnerAPI();

Métodos Disponíveis

getPlayer()

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

Parâmetros:

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

Retorna:

PlayerSpawnerHolder - Objeto contendo todos os dados de spawner do jogador, ou nulo se o jogador não for encontrado

Observações:

Os dados são recuperados do mapa de jogadores em cache
Retorna nulo se o jogador nunca fez login ou seus dados não estão em cache
Use isto para acessar informações de spawner específicas do jogador
Contém inventário de spawner e dados de gerenciamento

PlayerSpawnerHolder playerData = spawnerAPI.getPlayer("PlayerName");
if (playerData != null) {
    // Acessar dados de spawner do jogador
}

getEntityStackAmount()

Recupera a quantidade de pilha de mobs em uma entidade empilhada (quantos mobs estão empilhados).

Parâmetros:

entity (Entity) - A entidade a verificar

Retorna:

double - O número de mobs empilhados na entidade, ou 0 se não for uma entidade empilhada

Observações:

Retorna a contagem total de mobs representada por uma única entidade
Útil para determinar valor da entidade ou eficiência de processamento
Retorna 0 se a entidade não faz parte de uma pilha de spawner
Funciona com qualquer entidade que tenha sido empilhada pelo plugin

Entity entity = // obter entidade
double stackAmount = spawnerAPI.getEntityStackAmount(entity);
System.out.println("Esta entidade representa " + stackAmount + " mobs");

setEntityStackAmount()

Modifica a quantidade de pilha de mobs em uma entidade empilhada.

Parâmetros:

entity (Entity) - A entidade a modificar
amount (double) - A nova quantidade de pilha

Observações:

Atualiza a contagem de pilha interna da entidade
Usa SpawnerUtil para manipular a modificação
Requer chave de spawner válida para funcionar
Use com cuidado pois afeta diretamente as contagens de mob

spawnerAPI.setEntityStackAmount(entity, 100);

Estruturas de Dados

PlayerSpawnerHolder

Contém todos os dados relacionados a spawner de um jogador. Contém:

Inventário de spawners colocados
Estatísticas de coleta de spawner
Upgrades e bônus de spawner
Histórico de gerenciamento de spawner

Eventos

SpawnerPlaceEvent

Acionado quando um jogador coloca um bloco de spawner.

Métodos Disponíveis:

getPlacer() - Retorna o Player que colocou o spawner
getOwner() - Retorna o nome de usuário do proprietário (String)
getBlock() - Retorna o Block onde o spawner foi colocado
getAmount() - Retorna a quantidade/contagem do spawner colocado

Observações:

Dispara após o spawner ser colocado com sucesso
Este evento NÃO é cancelável
Proprietário pode diferir do colocador (por exemplo, propriedade compartilhada)
Quantidade representa quantos mobs o spawner gera

Exemplo:

@EventHandler
public void onSpawnerPlace(SpawnerPlaceEvent event) {
    Player placer = event.getPlacer();
    String owner = event.getOwner();
    Block block = event.getBlock();
    
    System.out.println(placer.getName() + " colocou spawner para " + owner + 
        " em " + block.getLocation());
}

SpawnerBreakEvent

Acionado quando um jogador quebra um bloco de spawner.

Métodos Disponíveis:

getBreaker() - Retorna o Player que quebrou o spawner
getOwner() - Retorna o nome de usuário do proprietário (String)
getBlock() - Retorna o Block que foi quebrado
getAmount() - Retorna a quantidade/contagem do spawner quebrado

Observações:

Dispara quando bloco de spawner é destruído
Este evento NÃO é cancelável
Quebrador pode não ser o proprietário
Quantidade representa contagem de mob no spawner quebrado

Exemplo:

@EventHandler
public void onSpawnerBreak(SpawnerBreakEvent event) {
    Player breaker = event.getBreaker();
    String owner = event.getOwner();
    
    System.out.println(breaker.getName() + " quebrou spawner de propriedade de " + owner);
}

SpawnerAddEvent

Acionado quando um jogador adiciona/upgrade um spawner com quantidade adicional.

Métodos Disponíveis:

getAdder() - Retorna o Player que adicionou ao spawner
getOwner() - Retorna o nome de usuário do proprietário (String)
getBlock() - Retorna o Block do spawner
getOldAmount() - Retorna a quantidade do spawner antes da adição
getNewAmount() - Retorna a quantidade do spawner após adição

Observações:

Dispara quando quantidade de spawner é aumentada
Este evento NÃO é cancelável
Útil para rastrear upgrades de spawner
Diferença entre antigo e novo mostra quanto foi adicionado

Exemplo:

@EventHandler
public void onSpawnerAdd(SpawnerAddEvent event) {
    Player adder = event.getAdder();
    double oldAmount = event.getOldAmount();
    double newAmount = event.getNewAmount();
    double addedAmount = newAmount - oldAmount;
    
    System.out.println(adder.getName() + " adicionou " + addedAmount + 
        " a um spawner");
}

SpawnerSellEvent

Acionado quando um jogador vende spawners ou itens de spawner.

Métodos Disponíveis:

getPlayer() - Retorna o Player vendendo
getAmount() - Retorna a quantidade sendo vendida
setAmount(double) - Modifique a quantidade sendo vendida
getValues() - Retorna HashMap com valores de moeda (moeda -> quantidade)
setValues(HashMap<String, Double>) - Modifique as recompensas econômicas

Observações:

Dispara quando spawner é vendido por moeda
Este evento NÃO é cancelável
O HashMap de valores contém múltiplas moedas e suas quantidades
Quantidade pode ser modificada antes da venda ser concluída

Exemplo:

@EventHandler
public void onSpawnerSell(SpawnerSellEvent event) {
    Player player = event.getPlayer();
    double amount = event.getAmount();
    HashMap<String, Double> values = event.getValues();
    
    System.out.println(player.getName() + " vendeu " + amount + " spawners");
}

SpawnerV2KillEvent

Acionado quando um mob de spawner empilhado é morto.

Métodos Disponíveis:

getPlayer() - Retorna o Player que matou o mob
getEntity() - Retorna a Entity que foi morta
getEntityAmount() - Retorna quantos mobs estavam na pilha
setEntityAmount(double) - Modifique a quantidade de pilha
getDrops() - Retorna a quantidade de quedas da morte
setDrops(double) - Modifique a quantidade de queda
getMiniaturePetsIdentifier() - Retorna o identificador de estimação se aplicável

Observações:

Dispara quando um mob de uma pilha de spawner é morto
Quantidade de entidade representa pilha inteira, não mob individual
Quedas podem ser modificadas para ajustar recompensas
Integração MiniaturePets se aplicável
Este evento NÃO é cancelável

Exemplo:

@EventHandler
public void onSpawnerKill(SpawnerV2KillEvent event) {
    Player player = event.getPlayer();
    double entityAmount = event.getEntityAmount();
    double drops = event.getDrops();
    
    System.out.println(player.getName() + " matou uma pilha de " + 
        entityAmount + " mobs, ganhando " + drops + " quedas");
}

Melhores Práticas

Sempre verifique null ao recuperar dados de spawner do jogador
Valide pilhas de entidades antes de modificar quantidades
Ouça eventos para rastrear operações de spawner
Cache dados do jogador se acessar múltiplas vezes rapidamente
Trate quantidades de pilha com cuidado pois afetam contagens de mob
Use eventos para logging de transações de spawner
Valide propriedade antes de permitir modificações de spawner

Exemplos de Uso

Exemplo 1: Obtendo Dados de Spawner do Jogador

SpawnerV2APIHolder spawnerAPI = (SpawnerV2APIHolder) Bukkit.getServicesManager()
    .load(SpawnerV2APIHolder.class);

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

Exemplo 2: Verificando Quantidade de Pilha de Entidade

SpawnerV2APIHolder spawnerAPI = (SpawnerV2APIHolder) Bukkit.getServicesManager()
    .load(SpawnerV2APIHolder.class);

double stackAmount = spawnerAPI.getEntityStackAmount(entity);
if (stackAmount > 0) {
    System.out.println("Entidade é uma pilha de " + stackAmount + " mobs");
}

Exemplo 3: Rastreando Colocação de Spawner

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.yspawnersv2.event.SpawnerPlaceEvent;

public class SpawnerPlacementTracker implements Listener {
    
    @EventHandler
    public void onSpawnerPlace(SpawnerPlaceEvent event) {
        Player placer = event.getPlacer();
        double amount = event.getAmount();
        
        System.out.println("[SPAWNER] " + placer.getName() + 
            " colocou spawner com quantidade: " + amount);
    }
}

Exemplo 4: Rastreando Quebra de Spawner

@EventHandler
public void onSpawnerBreak(SpawnerBreakEvent event) {
    Player breaker = event.getBreaker();
    String owner = event.getOwner();
    double amount = event.getAmount();
    
    System.out.println("[QUEBRA] " + breaker.getName() + 
        " quebrou spawner (" + amount + ") de propriedade de " + owner);
}

Exemplo 5: Logging de Upgrades de Spawner

@EventHandler
public void onSpawnerAdd(SpawnerAddEvent event) {
    double oldAmount = event.getOldAmount();
    double newAmount = event.getNewAmount();
    double addedAmount = newAmount - oldAmount;
    
    System.out.println("[UPGRADE] Spawner atualizado por " + addedAmount + 
        " (de " + oldAmount + " para " + newAmount + ")");
}

Exemplo 6: Monitorando Vendas de Spawner

@EventHandler
public void onSpawnerSell(SpawnerSellEvent event) {
    Player player = event.getPlayer();
    HashMap<String, Double> values = event.getValues();
    
    System.out.println("[VENDA] Detalhes de venda de " + player.getName() + ":");
    values.forEach((currency, value) -> {
        System.out.println("  " + currency + ": " + value);
    });
}

Exemplo 7: Aplicando Bônus de Morte

@EventHandler
public void onSpawnerKill(SpawnerV2KillEvent event) {
    Player player = event.getPlayer();
    double drops = event.getDrops();
    
    // Aplicar bônus VIP
    if (player.hasPermission("spawner.vip")) {
        event.setDrops(drops * 1.5);
    }
}

Exemplo 8: Modificação de Quantidade de Pilha

SpawnerV2APIHolder spawnerAPI = (SpawnerV2APIHolder) Bukkit.getServicesManager()
    .load(SpawnerV2APIHolder.class);

double currentAmount = spawnerAPI.getEntityStackAmount(entity);
double newAmount = currentAmount - 10; // Remover 10 da pilha

if (newAmount > 0) {
    spawnerAPI.setEntityStackAmount(entity, newAmount);
}

Exemplo 9: Logger Abrangente de Eventos de Spawner

public class SpawnerEventLogger implements Listener {
    
    private final JavaPlugin plugin;
    
    public SpawnerEventLogger(JavaPlugin plugin) {
        this.plugin = plugin;
    }
    
    @EventHandler
    public void onSpawnerPlace(SpawnerPlaceEvent event) {
        String log = String.format("[COLOCAÇÃO] %s colocou spawner em %s (quantidade: %d)",
            event.getPlacer().getName(),
            event.getBlock().getLocation(),
            (int) event.getAmount());
        plugin.getLogger().info(log);
    }
    
    @EventHandler
    public void onSpawnerBreak(SpawnerBreakEvent event) {
        String log = String.format("[QUEBRA] %s quebrou spawner em %s",
            event.getBreaker().getName(),
            event.getBlock().getLocation());
        plugin.getLogger().info(log);
    }
    
    @EventHandler
    public void onSpawnerAdd(SpawnerAddEvent event) {
        double added = event.getNewAmount() - event.getOldAmount();
        String log = String.format("[ADIÇÃO] %s adicionou %.0f ao spawner",
            event.getAdder().getName(),
            added);
        plugin.getLogger().info(log);
    }
    
    @EventHandler
    public void onSpawnerKill(SpawnerV2KillEvent event) {
        String log = String.format("[MORTE] %s matou pilha de %.0f mobs (quedas: %.0f)",
            event.getPlayer().getName(),
            event.getEntityAmount(),
            event.getDrops());
        plugin.getLogger().info(log);
    }
}

Exemplo 10: Economia Multi-Moeda de Spawner

public class SpawnerEconomicsHandler implements Listener {
    
    @EventHandler
    public void onSpawnerSell(SpawnerSellEvent event) {
        Player player = event.getPlayer();
        HashMap<String, Double> values = event.getValues();
        double amount = event.getAmount();
        
        System.out.println("[ECONOMIA] " + player.getName() + 
            " vendeu " + amount + " spawners");
        
        // Processar cada tipo de moeda
        values.forEach((currency, value) -> {
            System.out.println("  Moeda: " + currency);
            System.out.println("  Valor: " + value);
            
            // Aplicar impostos ou bônus
            if (player.hasPermission("spawner.premium")) {
                double bonusValue = value * 1.25; // Bônus de 25%
                values.put(currency, bonusValue);
            }
        });
        
        event.setValues(values);
    }
}

Nesta página