API

A API fornece uma interface pública para desenvolvedores integrarem seus plugins ao sistema de facções do yFactions, permitindo consultar dados de facções, gerenciar territórios, controlar poder e monitorar eventos de facção.

Obtendo a instância da API

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

Exemplo:

FactionAPIHolder factionAPI;

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

Métodos disponíveis

Consultas de Facção

containsFaction(String tag)

Verifica se uma facção existe pelo seu tag.

if (factionAPI.containsFaction("ALPHA")) {
    System.out.println("Facção ALPHA existe!");
}

Parâmetros:

tag - Tag único da facção

Retorno:

boolean - true se a facção existe

getFaction(String tag)

Obtém os dados completos de uma facção pelo tag.

Faction faction = factionAPI.getFaction("ALPHA");
if (faction != null) {
    System.out.println("Facção: " + faction.getName());
}

Parâmetros:

tag - Tag único da facção

Retorno:

Faction ou null se não existir

getFactions()

Obtém a lista de todas as facções do servidor.

List<FactionHolder> factions = factionAPI.getFactions();
factions.forEach(f -> System.out.println(f.getTag()));

Retorno:

List<FactionHolder> com todas as facções

Consultas de Jogador

getPlayer(Player p)

Obtém os dados de um jogador em facção a partir de uma instância Player.

FactionPlayerHolder player = factionAPI.getPlayer(bukkit_player);
if (player != null) {
    System.out.println("Facção: " + player.getFactionTag());
}

Parâmetros:

p - Instância do Player Bukkit

Retorno:

FactionPlayerHolder ou null

getPlayer(String p)

Obtém os dados de um jogador em facção pelo nome.

FactionPlayerHolder player = factionAPI.getPlayer("Player1");

Parâmetros:

p - Nome do jogador

Retorno:

FactionPlayerHolder ou null

getFactionPlayers()

Obtém a lista de todos os jogadores em facções.

List<FactionPlayerHolder> players = factionAPI.getFactionPlayers();

Retorno:

List<FactionPlayerHolder> com todos os jogadores

Consultas de Território

getTerritoryAt(Location location)

Obtém o território em uma localização.

Territory territory = factionAPI.getTerritoryAt(player.getLocation());
if (territory != null) {
    System.out.println("Território encontrado!");
}

Parâmetros:

location - Localização a verificar

Retorno:

Territory ou null

getFactionAt(Location location)

Obtém a facção que controla aquela localização.

Faction faction = factionAPI.getFactionAt(location);

Retorno:

Faction ou null se for wilderness

getTerritoryCount(String factionTag)

Obtém o número de territórios que a facção controla.

int count = factionAPI.getTerritoryCount("ALPHA");
System.out.println("ALPHA controla " + count + " territórios");

Retorno:

int - Número de territórios

getFactionTerritories(String factionTag)

Obtém o conjunto de todas as coordenadas de territórios da facção.

Set<String> territories = factionAPI.getFactionTerritories("ALPHA");

Retorno:

Set<String> com coordenadas dos territórios

Verificações de Zona

isWilderness(Location location)

Verifica se a localização é wilderness (terra selvagem).

if (factionAPI.isWilderness(location)) {
    System.out.println("Está em wilderness!");
}

Retorno:

boolean - true se é wilderness

isSafezone(Location location)

Verifica se a localização é safezone (zona segura - sem PvP).

if (factionAPI.isSafezone(location)) {
    System.out.println("Está em zona segura!");
}

Retorno:

boolean - true se é safezone

isWarzone(Location location)

Verifica se a localização é warzone (zona de guerra).

if (factionAPI.isWarzone(location)) {
    System.out.println("Está em zona de guerra!");
}

Retorno:

boolean - true se é warzone

isVipZone(Location location)

Verifica se a localização é VIP zone (zona VIP).

if (factionAPI.isVipZone(location)) {
    System.out.println("Está em zona VIP!");
}

Retorno:

boolean - true se é VIP zone

Verificações de Permissão

canPlayerBuildAt(Player player, Location location)

Verifica se um jogador pode construir naquele local.

if (factionAPI.canPlayerBuildAt(player, location)) {
    // Permitir construção
}

Retorno:

boolean - true se pode construir

canPlayerPvPAt(Player attacker, Player defender, Location location)

Verifica se um jogador pode atacar outro naquele local.

if (factionAPI.canPlayerPvPAt(attacker, defender, location)) {
    // Permitir PvP
}

Retorno:

boolean - true se PvP é permitido

Sistema de Poder de Facção

getFactionPower(String factionTag)

Obtém o poder atual da facção.

double power = factionAPI.getFactionPower("ALPHA");
System.out.println("Poder: " + power);

Retorno:

double - Poder atual (0.0 se não existir)

getFactionMaxPower(String factionTag)

Obtém o poder máximo da facção.

double maxPower = factionAPI.getFactionMaxPower("ALPHA");

Retorno:

double - Poder máximo

getFactionPowerPercentage(String factionTag)

Obtém o percentual de poder (0-100).

double percentage = factionAPI.getFactionPowerPercentage("ALPHA");
System.out.println("Poder: " + percentage + "%");

Retorno:

double - Percentual de poder

getFactionMaxClaimableLand(String factionTag)

Obtém o número máximo de territórios que a facção pode reivindicar.

int maxClaims = factionAPI.getFactionMaxClaimableLand("ALPHA");

Retorno:

int - Número máximo de claims

canFactionClaimMoreLand(String factionTag)

Verifica se a facção pode reivindicar mais territórios.

if (factionAPI.canFactionClaimMoreLand("ALPHA")) {
    System.out.println("Pode reivindicar mais território!");
}

Retorno:

boolean - true se pode expandir

Sistema de Poder de Jogador

getPlayerPower(String playerName)

Obtém o poder atual do jogador.

double power = factionAPI.getPlayerPower("Player1");

Retorno:

double - Poder do jogador

getPlayerMaxPower(String playerName)

Obtém o poder máximo do jogador.

double maxPower = factionAPI.getPlayerMaxPower("Player1");

Retorno:

double - Poder máximo

getPlayerPowerPercentage(String playerName)

Obtém o percentual de poder do jogador.

double percentage = factionAPI.getPlayerPowerPercentage("Player1");

Retorno:

double - Percentual de poder

addPlayerPower(String playerName, double amount)

Adiciona poder ao jogador.

factionAPI.addPlayerPower("Player1", 10.0);

Parâmetros:

playerName - Nome do jogador
amount - Quantidade de poder a adicionar

removePlayerPower(String playerName, double amount)

Remove poder do jogador.

factionAPI.removePlayerPower("Player1", 5.0);

Parâmetros:

playerName - Nome do jogador
amount - Quantidade de poder a remover

setPlayerPower(String playerName, double power)

Define o poder do jogador para um valor específico.

factionAPI.setPlayerPower("Player1", 100.0);

Parâmetros:

playerName - Nome do jogador
power - Novo valor de poder

Sistema de Relações

areFactionsAllied(String faction1Tag, String faction2Tag)

Verifica se duas facções são aliadas.

if (factionAPI.areFactionsAllied("ALPHA", "BETA")) {
    System.out.println("São aliadas!");
}

Retorno:

boolean - true se são aliadas

areFactionsEnemies(String faction1Tag, String faction2Tag)

Verifica se duas facções são inimigas.

if (factionAPI.areFactionsEnemies("ALPHA", "GAMMA")) {
    System.out.println("São inimigas!");
}

Retorno:

boolean - true se são inimigas

getFactionRelation(String faction1Tag, String faction2Tag)

Obtém a relação entre duas facções.

String relation = factionAPI.getFactionRelation("ALPHA", "BETA");
System.out.println("Relação: " + relation); // ALLY, ENEMY, NEUTRAL, TRUCE

Retorno:

String - Tipo de relação (ALLY, ENEMY, NEUTRAL, TRUCE)

Métodos Utilitários

getFactionTagAt(Location location)

Obtém o tag da facção em uma localização.

String tag = factionAPI.getFactionTagAt(location);
System.out.println("Facção: " + tag);

Retorno:

String - Tag da facção

isFactionPeaceful(String factionTag)

Verifica se uma facção está em modo pacífico.

if (factionAPI.isFactionPeaceful("ALPHA")) {
    System.out.println("Facção está pacífica!");
}

Retorno:

boolean - true se está pacífica

getFactionMembers(String factionTag)

Obtém a lista de todos os membros (online e offline) da facção.

List<String> members = factionAPI.getFactionMembers("ALPHA");
System.out.println("Membros: " + members.size());

Retorno:

List<String> - Nomes dos membros

getOnlineFactionMembers(String factionTag)

Obtém a lista de membros online da facção.

List<String> onlineMembers = factionAPI.getOnlineFactionMembers("ALPHA");

Retorno:

List<String> - Nomes dos membros online

getFactionMemberCount(String factionTag)

Obtém o número total de membros da facção.

int count = factionAPI.getFactionMemberCount("ALPHA");
System.out.println("Total de membros: " + count);

Retorno:

int - Número de membros

getOnlineFactionMemberCount(String factionTag)

Obtém o número de membros online da facção.

int online = factionAPI.getOnlineFactionMemberCount("ALPHA");
System.out.println("Membros online: " + online);

Retorno:

int - Número de membros online

Eventos

FactionCreateEvent

Disparado quando uma nova facção é criada.

@EventHandler
public void onFactionCreate(FactionCreateEvent event) {
    FactionHolder faction = event.getFaction();
    System.out.println("Facção criada: " + faction.getTag());
}

FactionDisbandEvent

Disparado quando uma facção é dissolvida.

@EventHandler
public void onFactionDisband(FactionDisbandEvent event) {
    FactionHolder faction = event.getFaction();
    String disbander = event.getDisbander();
    System.out.println(disbander + " dissolveu " + faction.getTag());
}

FactionJoinEvent

Disparado quando um jogador entra em uma facção.

@EventHandler
public void onFactionJoin(FactionJoinEvent event) {
    FactionHolder faction = event.getFaction();
    FactionPlayerHolder player = event.getFactionPlayerHolder();
    System.out.println(player.getKey() + " entrou em " + faction.getTag());
}

FactionLeaveEvent

Disparado quando um jogador sai de uma facção.

@EventHandler
public void onFactionLeave(FactionLeaveEvent event) {
    FactionHolder faction = event.getFaction();
    FactionPlayerHolder player = event.getFactionPlayerHolder();
}

FactionKickedEvent

Disparado quando um jogador é expulso de uma facção.

@EventHandler
public void onFactionKicked(FactionKickedEvent event) {
    FactionPlayerHolder kicker = event.getKicker();
    FactionPlayerHolder kicked = event.getKicked();
    System.out.println(kicker.getKey() + " expulsou " + kicked.getKey());
}

BankDepositEvent (Cancelável)

Disparado quando um jogador faz depósito no banco da facção.

@EventHandler
public void onBankDeposit(BankDepositEvent event) {
    if (event.getAmount() > 1000000) {
        event.setCancelled(true); // Bloquear depósito grande
    }
}

Propriedades:

getFaction() - Facção do banco
getFactionPlayer() - Jogador que fez depósito
getAmount() - Valor depositado
setAmount(double) - Modificar valor

BankWithdrawEvent (Cancelável)

Disparado quando um jogador faz saque no banco da facção.

@EventHandler
public void onBankWithdraw(BankWithdrawEvent event) {
    double amount = event.getAmount();
    event.setAmount(amount * 0.95); // Aplicar taxa de 5%
}

ChestOpenEvent (Cancelável)

Disparado quando um jogador abre o baú de facção.

@EventHandler
public void onChestOpen(ChestOpenEvent event) {
    FactionHolder faction = event.getFaction();
    System.out.println("Baú de " + faction.getTag() + " aberto!");
}

HomeSetEvent (Cancelável)

Disparado quando um jogador define home de facção.

@EventHandler
public void onHomeSet(HomeSetEvent event) {
    Location loc = event.getLoc();
    System.out.println("Home definida em: " + loc.getX() + ", " + loc.getY() + ", " + loc.getZ());
}

HomeGoEvent (Cancelável)

Disparado quando um jogador vai para home de facção.

@EventHandler
public void onHomeGo(HomeGoEvent event) {
    FactionPlayerHolder player = event.getFactionPlayerHolder();
    System.out.println(player.getKey() + " foi para home!");
}

HomeDeleteEvent (Cancelável)

Disparado quando uma home de facção é deletada.

@EventHandler
public void onHomeDelete(HomeDeleteEvent event) {
    event.setCancelled(true); // Bloquear deleção
}

ModTagEvent

Disparado quando uma facção modifica seu tag.

@EventHandler
public void onModTag(ModTagEvent event) {
    FactionHolder faction = event.getFaction();
    System.out.println("Tag modificado: " + faction.getTag());
}

ToggleMemberFriendlyFireEvent (Cancelável)

Disparado quando amigável fogo entre membros é alterado.

@EventHandler
public void onToggleMemberFF(ToggleMemberFriendlyFireEvent event) {
    boolean state = event.getState();
    System.out.println("FF entre membros: " + (state ? "ligado" : "desligado"));
}

ToggleAllyFriendlyFireEvent (Cancelável)

Disparado quando amigável fogo entre aliados é alterado.

@EventHandler
public void onToggleAllyFF(ToggleAllyFriendlyFireEvent event) {
    boolean state = event.getState();
    System.out.println("FF entre aliados: " + (state ? "ligado" : "desligado"));
}

Estrutura de Dados

Enums

FactionRelation

Tipos de relações entre facções:

ALLY (Aliado) - §a
TRUCE (Trégua) - §e
NEUTRAL (Neutro) - §f
ENEMY (Inimigo) - §c

Roles

Papéis de membros em facção:

NOTHING (Peso: 0)
MEMBER (Peso: 1)
TRUSTED (Peso: 2)
CAPTAIN (Peso: 3)
LEADER (Peso: 4)

EntryType

Tipo de entrada em facção:

PUBLIC - Entrada pública
REQUEST - Requer solicitação
PRIVATE - Privada

Permission

Permissões em facção (24 tipos):

KICK_PLAYERS - Expulsar jogadores
ACCESS_CHEST - Acessar baú
DEPOSIT_MONEY - Depositar dinheiro
WITHDRAW_MONEY - Sacar dinheiro
HOME_* - Gerenciar home
CLAIM / UNCLAIM - Reivindicar/desreivindicar
FLY - Voar em facção
BREAK_BLOCKS / PLACE_BLOCKS - Construir
INTERACT_BLOCKS - Interagir com blocos
E muitas outras...

Melhores práticas

Sempre valide null - Facções ou jogadores podem não existir
Verifique permissões antes de agir - Respeite o sistema de permissões
Use eventos para sincronização - Implemente listeners para eventos importantes
Cache dados quando apropriado - Para operações frequentes
Valide poder antes de modificar - Certifique-se que o valor é válido
Implemente logs - Registre todas as modificações
Considere relações de facção - Aliados podem ter permissões especiais
Verifique zona antes de agir - Safezone, warzone e wilderness têm regras diferentes
Respeite modo pacífico - Facções pacíficas têm restrições especiais
Use try-catch ao obter API - O plugin pode não estar instalado

Exemplos de uso

Verificar informações de facção

String tag = "ALPHA";
if (factionAPI.containsFaction(tag)) {
    Faction faction = factionAPI.getFaction(tag);
    System.out.println("Facção: " + faction.getName());
    System.out.println("Poder: " + factionAPI.getFactionPower(tag));
    System.out.println("Membros: " + factionAPI.getFactionMemberCount(tag));
    System.out.println("Online: " + factionAPI.getOnlineFactionMemberCount(tag));
}

Verificar permissão de construção

if (factionAPI.canPlayerBuildAt(player, location)) {
    player.sendMessage("§aVocê pode construir aqui!");
} else {
    player.sendMessage("§cVocê não pode construir aqui!");
}

Gerenciar poder de jogador

String playerName = "Player1";
double currentPower = factionAPI.getPlayerPower(playerName);
double maxPower = factionAPI.getPlayerMaxPower(playerName);
double percentage = factionAPI.getPlayerPowerPercentage(playerName);

System.out.println("Poder: " + currentPower + "/" + maxPower);
System.out.println("Percentual: " + percentage + "%");

// Adicionar poder por vitória
factionAPI.addPlayerPower(playerName, 10.0);

Monitorar criação de facção

@EventHandler
public void onFactionCreate(FactionCreateEvent event) {
    FactionHolder faction = event.getFaction();
    Bukkit.broadcastMessage("§aNova facção criada: " + faction.getTag());
    
    // Registrar em banco de dados externo
    minhaAPI.registrarFaccao(faction.getTag());
}

Sistema de bônus baseado em relação

public double obterBonusVenda(String factionTag) {
    String playerFaction = obterFaccaoDoJogador();
    
    if (factionAPI.areFactionsAllied(factionTag, playerFaction)) {
        return 1.15; // 15% de bônus para aliados
    } else if (factionAPI.areFactionsEnemies(factionTag, playerFaction)) {
        return 0.85; // 15% de redução para inimigos
    }
    
    return 1.0; // Normal para neutros
}

Verificar acesso à área

public boolean temAcesso(Player player, Location location) {
    if (factionAPI.isSafezone(location)) {
        return true; // Todos têm acesso em safezone
    }
    
    if (factionAPI.isWarzone(location)) {
        return true; // Todos têm acesso em warzone
    }
    
    if (factionAPI.isWilderness(location)) {
        return true; // Todos têm acesso em wilderness
    }
    
    // Em território de facção, verificar permissão
    return factionAPI.canPlayerBuildAt(player, location);
}

Rastrear membros online

public void notificarMembros(String factionTag, String mensagem) {
    List<String> onlineMembers = factionAPI.getOnlineFactionMembers(factionTag);
    
    for (String memberName : onlineMembers) {
        Player member = Bukkit.getPlayer(memberName);
        if (member != null) {
            member.sendMessage(mensagem);
        }
    }
}

Bloquear depósito em banco se muito grande

@EventHandler
public void onBankDeposit(BankDepositEvent event) {
    double maxDeposit = 500000;
    
    if (event.getAmount() > maxDeposit) {
        event.setCancelled(true);
        event.getFactionPlayer().getKey();
        Bukkit.getPlayer(event.getFactionPlayer().getKey())
            .sendMessage("§cNão pode depositar mais de §6$" + maxDeposit);
    }
}

Validar acesso à API

public FactionAPIHolder obterFactionAPI() {
    try {
        RegisteredServiceProvider<FactionAPIHolder> rsp = 
            Bukkit.getServer().getServicesManager()
                  .getRegistration(FactionAPIHolder.class);
        
        if (rsp == null) {
            Bukkit.getLogger().warning("yFactions não está instalado!");
            return null;
        }
        
        return rsp.getProvider();
    } catch (Throwable t) {
        Bukkit.getLogger().severe("Erro ao obter FactionAPI: " + t.getMessage());
        return null;
    }
}

Nesta página