API

Documentação completa da API do plugin yStackBosses, incluindo métodos para detectar bosses empilhados, gerenciar armas de boss e manipular eventos de combate de boss.

Obtendo a Instância da API

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

import com.ystoreplugins.ystackbosses.api.StackBossAPI;

StackBossAPI stackBossAPI = new StackBossAPI();

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

import com.ystoreplugins.ystackbosses.api.StackBossAPI;

StackBossAPI stackBossAPI = new StackBossAPI();

Métodos Disponíveis

isBoss()

Verifica se uma entidade é um boss empilhado.

Parâmetros:

entity (Entity) - A entidade a verificar

Retorna:

boolean - true se a entidade é um boss empilhado, false caso contrário

Observações:

Retorna false se a entidade não é um boss
Funciona com qualquer entidade marcada como boss empilhado
Útil para filtrar entidades boss de mobs regulares

if (stackBossAPI.isBoss(entity)) {
    System.out.println("Isto é um boss!");
}

getBoss()

Recupera a configuração do boss para uma entidade de boss empilhado.

Parâmetros:

entity (Entity) - A entidade do boss

Retorna:

BossHolder - Dados de configuração do boss, ou null se a entidade não é um boss

Observações:

Retorna null se a entidade não é um boss
Contém estatísticas, recompensas e configuração do boss
Use após confirmar que a entidade é um boss com isBoss()

BossHolder bossData = stackBossAPI.getBoss(entity);
if (bossData != null) {
    System.out.println("Dados do boss recuperados: " + bossData);
}

isUsingSword()

Verifica se um jogador está empunhando uma espada de boss.

Parâmetros:

player (Player) - A instância do Jogador

Retorna:

boolean - true se o jogador está segurando uma espada de boss, false caso contrário

Observações:

Verifica o item atualmente seguro pelo jogador
Retorna false se o jogador não está segurando nenhum item
Útil para validar a prontidão para combate com boss

if (stackBossAPI.isUsingSword(player)) {
    System.out.println("Jogador está pronto para combate com boss!");
}

isSword()

Verifica se um ItemStack é uma espada de boss válida.

Parâmetros:

itemStack (ItemStack) - O ItemStack a verificar

Retorna:

boolean - true se o item é uma espada de boss, false caso contrário

Observações:

Funciona com qualquer ItemStack (seguro, no inventário, no chão, etc.)
Retorna false se itemstack for null
Útil para validação de itens em lógica personalizada

ItemStack item = player.getItemInHand();
if (stackBossAPI.isSword(item)) {
    System.out.println("Esta é uma espada de boss!");
}

getSword()

Recupera a configuração da espada de boss pelo identificador.

Parâmetros:

s (String) - O identificador único da espada

Retorna:

SwordHolder - Dados de configuração da espada, ou null se não encontrado

Observações:

Retorna null se o identificador da espada não existe
Contém estatísticas da espada, dano e efeitos especiais
Use para acessar propriedades e bônus da espada

SwordHolder sword = stackBossAPI.getSword("legendary_boss_sword");
if (sword != null) {
    System.out.println("Espada recuperada: " + sword);
}

Estruturas de Dados

BossHolder

Representa uma configuração de boss empilhado. Contém:

Identificador e nome do boss
Dificuldade/tier do boss
Valores de saúde e dano
Configuração de recompensas e saque
Efeitos especiais e habilidades
Informações de quantidade em pilha

SwordHolder

Representa uma arma de espada de boss. Contém:

Identificador e nome da espada
Dano contra bosses
Encantamentos especiais
Durabilidade e requisitos
Multiplicadores de dano bônus

Eventos

StackBossKillEventEvent

Disparado quando um jogador mata um boss empilhado.

Métodos Disponíveis:

getKiller() - Retorna o Jogador que matou o boss
getEntity() - Retorna a Entity que foi morta
getBoss() - Retorna o BossHolder com a configuração do boss
getStackAmount() - Retorna quantos bosses havia na pilha

Observações:

Dispara quando uma entidade de boss empilhado morre
O valor da pilha representa o total de bosses mortos de uma vez
Este evento NÃO é cancelável
Útil para rastreamento de mortes de boss e aplicação de recompensas

Exemplo:

@EventHandler
public void onStackBossKill(StackBossKillEventEvent event) {
    Player killer = event.getKiller();
    BossHolder boss = event.getBoss();
    double stackAmount = event.getStackAmount();
    
    System.out.println(killer.getName() + " matou " + stackAmount + 
        " boss: " + boss);
}

Melhores Práticas

Sempre validar bosses usando isBoss() antes de processar
Verificar nulo ao recuperar dados de boss ou espada
Validar espadas usando isSword() antes de operações de combate
Usar eventos para rastrear mortes de boss em vez de detecção manual
Armazenar em cache dados de boss/espada se acessando frequentemente
Lidar com quantidades de pilha adequadamente para recompensas em massa
Verificar equipamento do jogador antes de encontros com boss

Exemplos de Uso

Exemplo 1: Detectando Entidades Boss

StackBossAPIHolder stackBossAPI = (StackBossAPIHolder) Bukkit.getServicesManager()
    .load(StackBossAPIHolder.class);

if (stackBossAPI.isBoss(entity)) {
    BossHolder boss = stackBossAPI.getBoss(entity);
    System.out.println("Boss detectado: " + boss);
}

Exemplo 2: Validando Espada de Boss

StackBossAPIHolder stackBossAPI = (StackBossAPIHolder) Bukkit.getServicesManager()
    .load(StackBossAPIHolder.class);

if (stackBossAPI.isUsingSword(player)) {
    player.sendMessage("§aSua espada de boss está equipada!");
}

Exemplo 3: Verificando Inventário para Espada de Boss

StackBossAPIHolder stackBossAPI = (StackBossAPIHolder) Bukkit.getServicesManager()
    .load(StackBossAPIHolder.class);

boolean hasSword = false;
for (ItemStack item : player.getInventory().getContents()) {
    if (item != null && stackBossAPI.isSword(item)) {
        hasSword = true;
        break;
    }
}

if (hasSword) {
    System.out.println("O jogador tem a espada de boss");
}

Exemplo 4: Obtendo Configuração de Espada

StackBossAPIHolder stackBossAPI = (StackBossAPIHolder) Bukkit.getServicesManager()
    .load(StackBossAPIHolder.class);

SwordHolder sword = stackBossAPI.getSword("epic_boss_sword");
if (sword != null) {
    System.out.println("Espada carregada: " + sword);
}

Exemplo 5: Rastreamento de Mortes de Boss

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import br.com.ystoreplugins.product.ystackbosses.event.StackBossKillEventEvent;

public class BossKillTracker implements Listener {
    
    @EventHandler
    public void onStackBossKill(StackBossKillEventEvent event) {
        Player killer = event.getKiller();
        double stackAmount = event.getStackAmount();
        
        System.out.println("[BOSS] " + killer.getName() + 
            " matou " + stackAmount + " bosses empilhados");
    }
}

Exemplo 6: Celebração de Morte de Boss

@EventHandler
public void onStackBossKill(StackBossKillEventEvent event) {
    Player killer = event.getKiller();
    BossHolder boss = event.getBoss();
    double stackAmount = event.getStackAmount();
    
    killer.sendMessage("§a§l✓ BOSS DERROTADO!");
    killer.sendMessage("§eVocê derrotou " + stackAmount + " bosses!");
    killer.playSound(killer.getLocation(), 
        org.bukkit.Sound.UI_TOAST_CHALLENGE_COMPLETE, 1.0f, 1.0f);
    
    // Notificar servidor
    org.bukkit.Bukkit.broadcastMessage("§6" + killer.getName() + 
        " §aderrotou §6" + boss + "§a!");
}

Exemplo 7: Multiplicador de Recompensa Baseado em Pilha

@EventHandler
public void onStackBossKill(StackBossKillEventEvent event) {
    Player killer = event.getKiller();
    double stackAmount = event.getStackAmount();
    
    // Mais bosses = melhor multiplicador de recompensa
    double multiplier = 1.0 + (stackAmount * 0.1); // 10% por boss
    
    System.out.println("[REWARD] " + killer.getName() + 
        " ganhou " + multiplier + "x recompensas");
}

Exemplo 8: Detecção de Dificuldade de Boss

@EventHandler
public void onStackBossKill(StackBossKillEventEvent event) {
    BossHolder boss = event.getBoss();
    Player killer = event.getKiller();
    
    // Aplicar bônus baseado no tipo de boss
    if (boss.toString().contains("Legendary")) {
        killer.addPotionEffect(new org.bukkit.potion.PotionEffect(
            org.bukkit.potion.PotionEffectType.STRENGTH, 200, 2, true, false));
        killer.sendMessage("§6§lBOSS LENDÁRIO DERROTADO!");
    } else if (boss.toString().contains("Epic")) {
        killer.sendMessage("§5Boss épico derrotado!");
    }
}

Exemplo 9: Bônus de Dano Baseado em Espada

@EventHandler
public void onPlayerAttack(EntityDamageByEntityEvent event) {
    if (!(event.getDamager() instanceof Player)) return;
    
    Player player = (Player) event.getDamager();
    StackBossAPIHolder stackBossAPI = (StackBossAPIHolder) 
        Bukkit.getServicesManager().load(StackBossAPIHolder.class);
    
    if (!stackBossAPI.isBoss(event.getEntity())) return;
    
    // Verificar se usando espada de boss
    if (stackBossAPI.isUsingSword(player)) {
        double baseDamage = event.getDamage();
        event.setDamage(baseDamage * 1.5); // Bônus de 50% contra bosses
        player.sendMessage("§e+50% Dano da Espada de Boss!");
    }
}

Exemplo 10: Manipulador Completo de Combate com Boss

public class ComprehensiveBossHandler implements Listener {
    
    private final JavaPlugin plugin;
    private final StackBossAPIHolder stackBossAPI;
    
    public ComprehensiveBossHandler(JavaPlugin plugin, 
                                     StackBossAPIHolder stackBossAPI) {
        this.plugin = plugin;
        this.stackBossAPI = stackBossAPI;
    }
    
    @EventHandler
    public void onStackBossKill(StackBossKillEventEvent event) {
        Player killer = event.getKiller();
        BossHolder boss = event.getBoss();
        double stackAmount = event.getStackAmount();
        
        // Registrar a morte
        logBossKill(killer, boss, stackAmount);
        
        // Aplicar recompensas
        applyRewards(killer, stackAmount);
        
        // Verificar se usando espada de boss
        if (stackBossAPI.isUsingSword(killer)) {
            applyBonusRewards(killer, stackAmount);
        }
        
        // Transmitir para o servidor
        broadcastKill(killer, boss, stackAmount);
    }
    
    private void logBossKill(Player killer, BossHolder boss, double stackAmount) {
        String log = String.format("[BOSS-KILL] %s matou %.0f x %s",
            killer.getName(), stackAmount, boss);
        plugin.getLogger().info(log);
    }
    
    private void applyRewards(Player killer, double stackAmount) {
        double baseReward = stackAmount * 100;
        killer.sendMessage("§aRecompensa: " + baseReward + " moedas");
    }
    
    private void applyBonusRewards(Player killer, double stackAmount) {
        double bonusReward = stackAmount * 150;
        killer.sendMessage("§6Bônus de Espada: " + bonusReward + " moedas!");
    }
    
    private void broadcastKill(Player killer, BossHolder boss, double stackAmount) {
        String message = String.format("§6%s §aderrotou §e%.0f §abosses!",
            killer.getName(), stackAmount);
        org.bukkit.Bukkit.broadcastMessage(message);
    }
}

Nesta página