API

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

Obtendo a instância da API

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

Exemplo:

ClanAPIHolder clanAPI;

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

Métodos da API

getClans()

Retorna a lista de todos os clãs em cache.

List<ClanHolder> allClans = clanAPI.getClans();

Retorno:

List<ClanHolder> contendo todos os clãs registrados

Observações:

Retorna uma cópia da lista de clãs
Apenas clãs em cache são retornados
Útil para operações de relatório

getClanPlayers()

Retorna a lista de todos os jogadores em cache.

List<ClanPlayerHolder> allPlayers = clanAPI.getClanPlayers();

Retorno:

List<ClanPlayerHolder> contendo todos os jogadores

Observações:

Retorna uma cópia da lista de jogadores
Inclui jogadores com e sem clã

containsClan(String tag)

Verifica se um clã com a tag especificada existe em cache.

boolean exists = clanAPI.containsClan("NOVA");

Parâmetros:

tag - Tag do clã a verificar

Retorno:

true se o clã existe em cache, false caso contrário

getPlayer(Player player)

Recupera os dados de clã de um jogador Bukkit.

ClanPlayer clanPlayer = clanAPI.getPlayer(player);

Parâmetros:

player - Objeto Player do Bukkit

Retorno:

ClanPlayer contendo dados do jogador ou null se não encontrado

getPlayer(String playerName)

Recupera os dados de clã de um jogador pelo nome.

ClanPlayer clanPlayer = clanAPI.getPlayer("Steve");

Parâmetros:

playerName - Nome do jogador

Retorno:

ClanPlayer contendo dados do jogador ou null se não encontrado

getClan(String tag)

Recupera um clã específico pela tag.

Clan clan = clanAPI.getClan("NOVA");

Parâmetros:

tag - Tag do clã

Retorno:

Clan contendo dados do clã ou null se não encontrado

Eventos disponíveis

ClanCreateEvent

Disparado quando um novo clã é criado.

@EventHandler
public void onClanCreate(ClanCreateEvent event) {
    ClanHolder clan = event.getClan();
}

Métodos:

getClan() - Obtém o clã criado

ClanDisbandEvent

Disparado quando um clã é dissolvido.

@EventHandler
public void onClanDisband(ClanDisbandEvent event) {
    ClanHolder clan = event.getClan();
    String disbander = event.getDisbander();
}

Métodos:

getClan() - Obtém o clã dissolvido
getDisbander() - Obtém o nome de quem dissolveu o clã

ClanJoinEvent

Disparado quando um jogador entra em um clã.

@EventHandler
public void onClanJoin(ClanJoinEvent event) {
    ClanHolder clan = event.getClan();
    ClanPlayerHolder player = event.getClanPlayer();
}

Métodos:

getClan() - Obtém o clã
getClanPlayer() - Obtém o jogador que entrou

ClanLeaveEvent

Disparado quando um jogador sai de um clã.

@EventHandler
public void onClanLeave(ClanLeaveEvent event) {
    ClanHolder clan = event.getClan();
    ClanPlayerHolder player = event.getClanPlayer();
}

Métodos:

getClan() - Obtém o clã
getClanPlayer() - Obtém o jogador que saiu

ClanKickedEvent

Disparado quando um jogador é expulso de um clã.

@EventHandler
public void onClanKicked(ClanKickedEvent event) {
    ClanHolder clan = event.getClan();
    ClanPlayerHolder kicker = event.getKicker();
    ClanPlayerHolder kicked = event.getKicked();
}

Métodos:

getClan() - Obtém o clã
getKicker() - Obtém quem expulsou
getKicked() - Obtém quem foi expulso

BankDepositEvent

Disparado quando um jogador deposita moeda no banco do clã.

Cancelável: Sim

@EventHandler
public void onBankDeposit(BankDepositEvent event) {
    ClanHolder clan = event.getClan();
    ClanPlayerHolder player = event.getClanPlayer();
    double amount = event.getAmount();
}

Métodos:

getClan() - Obtém o clã
getClanPlayer() - Obtém o jogador
getAmount() - Obtém o valor depositado
setAmount(double) - Define o valor depositado
isCancelled() - Verifica se cancelado
setCancelled(boolean) - Cancela o depósito

BankWithdrawEvent

Disparado quando um jogador saca moeda do banco do clã.

Cancelável: Sim

@EventHandler
public void onBankWithdraw(BankWithdrawEvent event) {
    ClanHolder clan = event.getClan();
    ClanPlayerHolder player = event.getClanPlayer();
    double amount = event.getAmount();
}

Métodos:

getClan() - Obtém o clã
getClanPlayer() - Obtém o jogador
getAmount() - Obtém o valor sacado
setAmount(double) - Define o valor sacado
isCancelled() - Verifica se cancelado
setCancelled(boolean) - Cancela o saque

ChestOpenEvent

Disparado quando um jogador abre o baú do clã.

Cancelável: Sim

@EventHandler
public void onChestOpen(ChestOpenEvent event) {
    ClanHolder clan = event.getClan();
    ClanPlayerHolder player = event.getClanPlayer();
}

Métodos:

getClan() - Obtém o clã
getClanPlayer() - Obtém o jogador
isCancelled() - Verifica se cancelado
setCancelled(boolean) - Cancela abertura do baú

HomeGoEvent

Disparado quando um jogador se teletransporta para a home do clã.

Cancelável: Sim

@EventHandler
public void onHomeGo(HomeGoEvent event) {
    ClanHolder clan = event.getClan();
    ClanPlayerHolder player = event.getClanPlayer();
    Location loc = event.getLoc();
}

Métodos:

getClan() - Obtém o clã
getClanPlayer() - Obtém o jogador
getLoc() - Obtém a localização da home
setLoc(Location) - Define a localização da home
isCancelled() - Verifica se cancelado
setCancelled(boolean) - Cancela teletransporte

HomeDeleteEvent

Disparado quando a home do clã é deletada.

Cancelável: Sim

@EventHandler
public void onHomeDelete(HomeDeleteEvent event) {
    ClanHolder clan = event.getClan();
    ClanPlayerHolder player = event.getClanPlayer();
    Location loc = event.getLoc();
}

Métodos:

getClan() - Obtém o clã
getClanPlayer() - Obtém o jogador que deletou
getLoc() - Obtém a localização deletada
setLoc(Location) - Define a localização
isCancelled() - Verifica se cancelado
setCancelled(boolean) - Cancela deleção

Boas práticas

Sempre verifique null ao recuperar dados
Use cancelamento com moderação em eventos
Evite chamadas excessivas em eventos de alta frequência
Armazene dados consultados quando possível
Valide tags de clã antes de usar

ModTagEvent

Disparado quando a tag de um clã é modificada.

@EventHandler
public void onModTag(ModTagEvent event) {
    ClanHolder clan = event.getClan();
}

Métodos:

getClan() - Obtém o clã com tag modificada

ToggleAllyFriendlyFireEvent

Disparado quando o friendly fire entre aliados é ativado/desativado.

Cancelável: Sim

@EventHandler
public void onToggleAllyFriendlyFire(ToggleAllyFriendlyFireEvent event) {
    ClanHolder clan = event.getClan();
    ClanPlayerHolder player = event.getClanPlayer();
    boolean state = event.getState();
}

Métodos:

getClan() - Obtém o clã
getClanPlayer() - Obtém o jogador que ativou/desativou
getState() - Obtém o novo estado (true = ativado, false = desativado)
setState(boolean) - Define o novo estado
isCancelled() - Verifica se cancelado
setCancelled(boolean) - Cancela a mudança

ToggleMemberFriendlyFireEvent

Disparado quando o friendly fire entre membros é ativado/desativado.

Cancelável: Sim

@EventHandler
public void onToggleMemberFriendlyFire(ToggleMemberFriendlyFireEvent event) {
    ClanHolder clan = event.getClan();
    ClanPlayerHolder player = event.getClanPlayer();
    boolean state = event.getState();
}

Métodos:

getClan() - Obtém o clã
getClanPlayer() - Obtém o jogador que ativou/desativou
getState() - Obtém o novo estado (true = ativado, false = desativado)
setState(boolean) - Define o novo estado
isCancelled() - Verifica se cancelado
setCancelled(boolean) - Cancela a mudança

Exemplos de uso

Verificar se jogador está em clã

ClanPlayer clanPlayer = clanAPI.getPlayer(player.getName());
if (clanPlayer != null && clanPlayer.getClan() != null) {
    player.sendMessage("Você está no clã: " + clanPlayer.getClan());
}

Obter lista de membros de um clã

Clan clan = clanAPI.getClan("NOVA");
if (clan != null) {
    List<ClanPlayerHolder> allPlayers = clanAPI.getClanPlayers();
    List<ClanPlayerHolder> clanMembers = allPlayers.stream()
        .filter(p -> p.getClan().equals("NOVA"))
        .collect(Collectors.toList());
}

Monitorar criação de clãs

@EventHandler
public void onClanCreate(ClanCreateEvent event) {
    ClanHolder clan = event.getClan();
    Bukkit.broadcastMessage("Novo clã criado: " + clan.getTag());
}

Aplicar taxa em depósito bancário

@EventHandler
public void onBankDeposit(BankDepositEvent event) {
    double amount = event.getAmount();
    double tax = amount * 0.05; // 5% de taxa
    event.setAmount(amount - tax);
}

Restringir saque bancário

@EventHandler
public void onBankWithdraw(BankWithdrawEvent event) {
    if (event.getAmount() > 10000) {
        event.setCancelled(true);
        event.getClanPlayer().sendMessage("Limite de saque excedido!");
    }
}

Sistema de log de eventos

@EventHandler
public void onClanJoin(ClanJoinEvent event) {
    String message = event.getClanPlayer().getName() + 
                    " entrou no clã " + event.getClan().getTag();
    logEvent(message);
}

@EventHandler
public void onClanLeave(ClanLeaveEvent event) {
    String message = event.getClanPlayer().getName() + 
                    " saiu do clã " + event.getClan().getTag();
    logEvent(message);
}

private void logEvent(String message) {
    // Salvar em arquivo, banco de dados, etc.
}

Bloquear home em certas áreas

@EventHandler
public void onHomeGo(HomeGoEvent event) {
    Location loc = event.getLoc();
    if (isInRestrictedZone(loc)) {
        event.setCancelled(true);
        event.getClanPlayer().sendMessage("Não é permitido home nesta área!");
    }
}

private boolean isInRestrictedZone(Location loc) {
    // Implementar lógica de verificação
    return false;
}

Controlar friendly fire entre aliados

@EventHandler
public void onToggleAllyFriendlyFire(ToggleAllyFriendlyFireEvent event) {
    ClanHolder clan = event.getClan();
    boolean state = event.getState();
    
    if (!state) {
        Bukkit.broadcastMessage("Clã " + clan.getTag() + " desativou FF com aliados!");
    }
}

Controlar friendly fire entre membros

@EventHandler
public void onToggleMemberFriendlyFire(ToggleMemberFriendlyFireEvent event) {
    if (event.getState()) {
        event.setCancelled(true);
        event.getClanPlayer().sendMessage("FF entre membros não é permitido!");
    }
}

Monitorar modificação de tag de clã

@EventHandler
public void onModTag(ModTagEvent event) {
    ClanHolder clan = event.getClan();
    Bukkit.getLogger().info("Tag do clã " + clan.getTag() + " foi modificada");
}

Nesta página