API

A API fornece uma interface pública para desenvolvedores integrarem seus plugins ao sistema de guerra do yGuerra, permitindo consultar eventos de guerra, jogadores e clãs participantes.

Obtendo a instância da API

A API é exposta através de um BukkitService assim como feito comumente no Vault.

Exemplo:

GuerraAPIHolder guerraAPI;

try {
  RegisteredServiceProvider<GuerraAPIHolder> rsp = Bukkit.getServer().getServicesManager().getRegistration(GuerraAPIHolder.class);
  return rsp == null ? null : (GuerraAPIHolder)rsp.getProvider();
} catch (Throwable t) {
  return null;
}

Métodos disponíveis

getTipo(String tipoName)

Recupera as configurações de um tipo de guerra.

TipoHolder tipoGuerra = guerraAPI.getTipo("guerra_classica");

Parâmetros:

tipoName - Nome do tipo de guerra (sem extensão .yml)

Retorno:

TipoHolder com configurações do tipo ou null se não encontrado

Observações:

Busca arquivo de configuração .yml
Contém informações sobre regras e recompensas
Retorna null se o tipo não estiver configurado

getPlayer(String playerName)

Recupera os dados de guerra de um jogador.

PlayerGuerraHolder playerGuerra = guerraAPI.getPlayer("Steve");

Parâmetros:

playerName - Nome do jogador

Retorno:

PlayerGuerraHolder com dados do jogador ou null se não encontrado

Observações:

Recupera dados em cache
Contém estatísticas e conquistas do jogador em guerras
Retorna null se jogador não tiver dados registrados

getGuerra()

Recupera os dados gerais da guerra atual.

GuerraHolder guerraData = guerraAPI.getGuerra();

Retorno:

GuerraHolder com dados da guerra ou null

Observações:

Contém informações gerais do sistema de guerra
Status, estatísticas globais, etc.
Sempre busca "data" do cache principal

isParticipatingPlayer(String playerName)

Verifica se um jogador está participando da guerra ativa.

if (guerraAPI.isParticipatingPlayer("Steve")) {
    System.out.println("Jogador está em guerra!");
}

Parâmetros:

playerName - Nome do jogador

Retorno:

true se o jogador está participando de uma guerra, false caso contrário

Observações:

Verifica se há guerra ocorrendo (Iniciar.ativo)
Valida existência do jogador no mapa de participantes
Rápido e eficiente para validação

isParticipatingClan(String clanTag)

Verifica se um clã está participando da guerra ativa.

if (guerraAPI.isParticipatingClan("NOVA")) {
    System.out.println("Clã está em guerra!");
}

Parâmetros:

clanTag - Tag do clã

Retorno:

true se o clã está participando de uma guerra, false caso contrário

Observações:

Verifica se há guerra ocorrendo
Valida existência do clã no mapa de participantes
Útil para integração com sistema de clãs

isOccurring()

Verifica se há uma guerra ocorrendo no momento.

if (guerraAPI.isOccurring()) {
    System.out.println("Guerra em andamento!");
}

Retorno:

true se há guerra ativa, false caso contrário

Observações:

Verifica valor booleano Iniciar.ativo
Muito rápido, útil para validação constante

getOccurring()

Obtém o tipo de guerra que está ocorrendo.

TipoHolder tipo = guerraAPI.getOccurring();
if (tipo != null) {
    System.out.println("Tipo de guerra: " + tipo.getNome());
}

Retorno:

TipoHolder com tipo da guerra ou null se nenhuma guerra ativa

Observações:

Retorna null se não há guerra ocorrendo
Útil para saber qual modo está ativo

getOccurringStatus()

Obtém o status de uma guerra em andamento.

EventStatus status = guerraAPI.getOccurringStatus();

Retorno:

EventStatus ou null se nenhuma guerra ativa

Observações:

Implementação retorna null (pode ser expandida)
Indicado para futuro uso

getPlayers()

Retorna lista de todos os jogadores participando da guerra.

List<String> players = guerraAPI.getPlayers();
for (String player : players) {
    System.out.println("Participante: " + player);
}

Retorno:

List<String> com nomes de todos os jogadores

Observações:

Cópia da lista de chaves do mapa
Lista vazia se nenhuma guerra ativa
Útil para broadcasts

getClans()

Retorna lista de todos os clãs participando da guerra.

List<String> clans = guerraAPI.getClans();
System.out.println("Clãs em guerra: " + clans.size());

Retorno:

List<String> com tags de todos os clãs

Observações:

Cópia da lista de chaves do mapa
Lista vazia se nenhuma guerra ativa
Útil para análise de participação

Eventos disponíveis

EventStartEvent

Disparado quando uma guerra inicia.

@EventHandler
public void onGuerraStart(EventStartEvent event) {
    TipoHolder tipo = event.getTipo();
    Bukkit.broadcastMessage("Guerra iniciada: " + tipo.getNome());
}

Métodos:

getTipo() - Obtém o tipo de guerra iniciada

EventStopEvent

Disparado quando uma guerra termina.

@EventHandler
public void onGuerraStop(EventStopEvent event) {
    TipoHolder tipo = event.getTipo();
    EventStopType reason = event.getEventStopType();
    
    System.out.println("Guerra finalizada: " + reason.name());
}

Métodos:

getTipo() - Obtém o tipo de guerra
getEventStopType() - Obtém razão do término (enum)

PlayerEnterEventEvent

Disparado quando um jogador entra na guerra.

@EventHandler
public void onPlayerEnterGuerra(PlayerEnterEventEvent event) {
    Player player = event.getPlayer();
    TipoHolder tipo = event.gettipo();
    
    player.sendMessage("Você entrou na guerra: " + tipo.getNome());
}

Métodos:

getPlayer() - Obtém o jogador
gettipo() - Obtém o tipo de guerra (nota: método com typo no nome)

PlayerExitEventEvent

Disparado quando um jogador sai da guerra.

@EventHandler
public void onPlayerExitGuerra(PlayerExitEventEvent event) {
    Player player = event.getPlayer();
    TipoHolder tipo = event.getTipo();
    EventExitType reason = event.getEventExitType();
    
    System.out.println(player.getName() + " saiu por: " + reason.name());
}

Métodos:

getPlayer() - Obtém o jogador
getTipo() - Obtém o tipo de guerra
getEventExitType() - Obtém razão da saída (enum)

Boas práticas

Use isOccurring() para verificações rápidas
Valide jogadores com isParticipatingPlayer() antes de aplicar efeitos
Use getPlayers() e getClans() para broadcasts
Escute eventos para reações em tempo real
Cache dados de getTipo() para evitar I/O frequente
Verifique getOccurring() antes de acessar configurações específicas

Exemplos de uso

Bloquear ações durante guerra

@EventHandler
public void onPlayerCommand(PlayerCommandPreprocessEvent event) {
    if (guerraAPI.isOccurring() && 
        guerraAPI.isParticipatingPlayer(event.getPlayer().getName())) {
        
        String[] blocked = {"/spawn", "/home", "/tpa"};
        for (String cmd : blocked) {
            if (event.getMessage().toLowerCase().startsWith(cmd)) {
                event.setCancelled(true);
                event.getPlayer().sendMessage("Você não pode fazer isso durante uma guerra!");
            }
        }
    }
}

Notificar participantes

@EventHandler
public void onGuerraStart(EventStartEvent event) {
    TipoHolder tipo = event.getTipo();
    List<String> players = guerraAPI.getPlayers();
    
    for (String playerName : players) {
        Player player = Bukkit.getPlayer(playerName);
        if (player != null) {
            player.sendMessage("§c§lGUERRA INICIADA: " + tipo.getNome());
        }
    }
}

Dar recompensa ao terminar

@EventHandler
public void onGuerraStop(EventStopEvent event) {
    List<String> players = guerraAPI.getPlayers();
    double reward = 5000;
    
    for (String playerName : players) {
        addBalance(playerName, reward);
    }
    
    Bukkit.broadcastMessage("Todos os participantes ganharam " + reward + " moedas!");
}

Sistema de proteção durante guerra

@EventHandler
public void onPlayerDamage(EntityDamageByEntityEvent event) {
    if (!(event.getEntity() instanceof Player)) return;
    if (!(event.getDamager() instanceof Player)) return;
    
    Player victim = (Player) event.getEntity();
    Player attacker = (Player) event.getDamager();
    
    boolean victimInGuerra = guerraAPI.isParticipatingPlayer(victim.getName());
    boolean attackerInGuerra = guerraAPI.isParticipatingPlayer(attacker.getName());
    
    // Permitir dano apenas se ambos estão em guerra
    if (!guerraAPI.isOccurring() || !victimInGuerra || !attackerInGuerra) {
        event.setCancelled(true);
    }
}

Dashboard de guerra

public void showGuerraDashboard(Player player) {
    player.sendMessage("═══════════════════════════");
    player.sendMessage("STATUS DE GUERRA");
    player.sendMessage("═══════════════════════════");
    
    if (guerraAPI.isOccurring()) {
        TipoHolder tipo = guerraAPI.getOccurring();
        List<String> players = guerraAPI.getPlayers();
        List<String> clans = guerraAPI.getClans();
        
        player.sendMessage("Status: ✓ GUERRA ATIVA");
        player.sendMessage("Tipo: " + tipo.getNome());
        player.sendMessage("Jogadores: " + players.size());
        player.sendMessage("Clãs: " + clans.size());
        
        if (guerraAPI.isParticipatingPlayer(player.getName())) {
            player.sendMessage("Sua participação: ✓ ATIVO");
        }
    } else {
        player.sendMessage("Status: ✗ SEM GUERRA ATIVA");
        player.sendMessage("Aguarde o próximo evento de guerra");
    }
    
    player.sendMessage("═══════════════════════════");
}

Listar clãs em guerra

@EventHandler
public void onGuerraStart(EventStartEvent event) {
    List<String> clans = guerraAPI.getClans();
    
    if (!clans.isEmpty()) {
        StringBuilder message = new StringBuilder("§6Clãs em guerra: ");
        for (int i = 0; i < clans.size(); i++) {
            message.append(clans.get(i));
            if (i < clans.size() - 1) message.append(", ");
        }
        Bukkit.broadcastMessage(message.toString());
    }
}

Verificar participação

public void checkPlayerStatus(Player player) {
    String playerName = player.getName();
    
    if (!guerraAPI.isOccurring()) {
        player.sendMessage("Não há guerra ativa no momento.");
        return;
    }
    
    if (guerraAPI.isParticipatingPlayer(playerName)) {
        player.sendMessage("Você está participando da guerra!");
    } else {
        player.sendMessage("Você não está na guerra ativa.");
    }
}

Monitorar saídas de guerra

@EventHandler
public void onPlayerExitGuerra(PlayerExitEventEvent event) {
    Player player = event.getPlayer();
    EventExitType reason = event.getEventExitType();
    
    switch (reason) {
        case DEAD:
            player.sendMessage("Você foi eliminado da guerra!");
            break;
        case EXIT:
            player.sendMessage("Você saiu da guerra.");
            break;
        // Outros motivos conforme enum
    }
}

Nesta página