API

A API fornece uma interface pública para desenvolvedores integrarem seus plugins ao sistema de terrenos do yTerrenos, permitindo consultar terrenos, gerenciar permissões, verificar propriedades e monitorar eventos de terrenos.

Obtendo a instância da API

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

Exemplo:

TerrenoAPIHolder terrenoAPI;

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

Métodos disponíveis

getTerrenoAt(Location location)

Obtém o terreno na localização especificada.

TerrenoHolder terreno = terrenoAPI.getTerrenoAt(location);

Retorno:

TerrenoHolder ou null se não houver terreno naquela localização.

getTerrenoByFenceBlock(Location location)

Obtém o terreno através da localização de uma cerca (bloco de cerca que marca a borda).

TerrenoHolder terreno = terrenoAPI.getTerrenoByFenceBlock(location);

Observações:

Útil para detectar quando um jogador toca em uma cerca
Retorna null se o bloco não é uma cerca de terreno

getPlayerTerrenos(Player player)

Retorna a lista de todos os terrenos do jogador.

List<TerrenoHolder> terrenos = terrenoAPI.getPlayerTerrenos(player);

Retorno:

Lista de TerrenoHolder contendo todos os terrenos do jogador
Lista vazia se o jogador não possuir terrenos

getPlayerTerrenos(UUID uuid)

Retorna a lista de todos os terrenos do jogador pelo UUID.

List<TerrenoHolder> terrenos = terrenoAPI.getPlayerTerrenos(uuid);

Observações:

Funciona mesmo com jogadores offline
Retorna a mesma informação que getPlayerTerrenos(Player player)

getTerrenosForSale()

Retorna a lista de todos os terrenos à venda no servidor.

List<TerrenoHolder> terrenos = terrenoAPI.getTerrenosForSale();

Retorno:

Lista de terrenos com status de venda ativo
Lista vazia se nenhum terreno estiver à venda

getTerreno(String key)

Obtém um terreno específico pelo seu identificador único.

TerrenoHolder terreno = terrenoAPI.getTerreno("terreno_001");

Retorno:

TerrenoHolder ou null se o terreno não existir

getAllTerrenos()

Retorna a lista de todos os terrenos do servidor.

List<TerrenoHolder> terrenos = terrenoAPI.getAllTerrenos();

Retorno:

Lista contendo todos os terrenos cadastrados
Inclui terrenos em qualquer estado (próprios, à venda, etc)

getAllTerrenosSelling()

Retorna a lista de todos os terrenos à venda no servidor.

List<TerrenoHolder> terrenos = terrenoAPI.getAllTerrenosSelling();

getAllTerrenosSelling(Player player)

Retorna a lista de terrenos à venda do jogador específico.

List<TerrenoHolder> terrenos = terrenoAPI.getAllTerrenosSelling(player);

getAllTerrenosSelling(UUID uuid)

Retorna a lista de terrenos à venda do jogador pelo UUID.

List<TerrenoHolder> terrenos = terrenoAPI.getAllTerrenosSelling(uuid);

getAllTerrenosIsFriend(Player player)

Retorna a lista de terrenos onde o jogador é amigo.

List<TerrenoHolder> terrenos = terrenoAPI.getAllTerrenosIsFriend(player);

Observações:

Retorna terrenos onde o jogador está na lista de amigos
Permite verificar terrenos nos quais o jogador tem acesso limitado

getAllTerrenosIsFriend(UUID uuid)

Retorna a lista de terrenos onde o jogador é amigo pelo UUID.

List<TerrenoHolder> terrenos = terrenoAPI.getAllTerrenosIsFriend(uuid);

getPlayerTerrenoCount(Player player)

Retorna o número total de terrenos que o jogador possui.

int count = terrenoAPI.getPlayerTerrenoCount(player);

Retorno:

Número inteiro representando a quantidade de terrenos

getPlayerTerrenoCount(UUID uuid)

Retorna o número total de terrenos do jogador pelo UUID.

int count = terrenoAPI.getPlayerTerrenoCount(uuid);

findTerrenoByName(Player player, String name)

Encontra um terreno do jogador pelo nome.

TerrenoHolder terreno = terrenoAPI.findTerrenoByName(player, "Casa");

Retorno:

TerrenoHolder ou null se nenhum terreno com esse nome for encontrado

findTerrenoByName(UUID uuid, String name)

Encontra um terreno do jogador pelo UUID e nome.

TerrenoHolder terreno = terrenoAPI.findTerrenoByName(uuid, "Casa");

canPlayerBuild(Player player, TerrenoHolder terreno)

Verifica se o jogador pode construir naquele terreno.

if (terrenoAPI.canPlayerBuild(player, terreno)) {
    // Jogador pode construir
}

Retorno:

true se o jogador tem permissão para construir
false caso contrário

canPlayerBreak(Player player, TerrenoHolder terreno)

Verifica se o jogador pode quebrar blocos naquele terreno.

if (terrenoAPI.canPlayerBreak(player, terreno)) {
    // Jogador pode quebrar blocos
}

canPlayerOpenContainers(Player player, TerrenoHolder terreno)

Verifica se o jogador pode abrir contêineres (baús, fornos, etc) naquele terreno.

if (terrenoAPI.canPlayerOpenContainers(player, terreno)) {
    // Jogador pode abrir contêineres
}

canPlayerUseItems(Player player, TerrenoHolder terreno)

Verifica se o jogador pode usar itens (camas, botões, alavancas, etc) naquele terreno.

if (terrenoAPI.canPlayerUseItems(player, terreno)) {
    // Jogador pode usar itens
}

canPlayerInteractWithEntities(Player player, TerrenoHolder terreno)

Verifica se o jogador pode interagir com entidades (animais, vilarejos, etc) naquele terreno.

if (terrenoAPI.canPlayerInteractWithEntities(player, terreno)) {
    // Jogador pode interagir com entidades
}

Estrutura de dados

TerrenoHolder

Representa um terreno do servidor.

Principais propriedades:

Chave única do terreno
Dono do terreno
Localização e dimensões
Lista de amigos
Status de venda
Preço (se à venda)
Membros do terreno
Permissões

Eventos

TerrenoCreateEvent

Disparado quando um novo terreno é criado.

@EventHandler
public void onTerrenoCreate(TerrenoCreateEvent event) {
    Player player = event.getPlayer();
    TerrenoHolder terreno = event.getTerreno();
}

Propriedades:

getPlayer() - Jogador que criou o terreno
getTerreno() - Terreno criado

TerrenoDeleteEvent

Disparado quando um terreno é deletado.

@EventHandler
public void onTerrenoDelete(TerrenoDeleteEvent event) {
    Player player = event.getPlayer();
    TerrenoHolder terreno = event.getTerreno();
}

Propriedades:

getPlayer() - Jogador que deletou o terreno
getTerreno() - Terreno deletado

TerrenoJoinEvent

Disparado quando um jogador entra em um terreno.

@EventHandler
public void onTerrenoJoin(TerrenoJoinEvent event) {
    Player player = event.getPlayer();
    TerrenoHolder terreno = event.getTerreno();
}

Propriedades:

getPlayer() - Jogador que entrou
getTerreno() - Terreno que foi entrado

TerrenoLeaveEvent

Disparado quando um jogador sai de um terreno.

@EventHandler
public void onTerrenoLeave(TerrenoLeaveEvent event) {
    Player player = event.getPlayer();
    TerrenoHolder terreno = event.getTerreno();
}

Propriedades:

getPlayer() - Jogador que saiu
getTerreno() - Terreno que foi saído

TerrenoUpgradeEvent

Disparado quando um terreno é expandido/aumentado.

@EventHandler
public void onTerrenoUpgrade(TerrenoUpgradeEvent event) {
    Player player = event.getPlayer();
    TerrenoHolder terreno = event.getTerreno();
    int previousSize = event.getPreviousSize();
    int currentSize = event.getCurrentSize();
}

Propriedades:

getPlayer() - Jogador que fez o upgrade
getTerreno() - Terreno que foi expandido
getPreviousSize() - Tamanho anterior do terreno
getCurrentSize() - Novo tamanho do terreno

Melhores práticas

Sempre verifique null ao obter terrenos - um terreno pode não existir ou não estar carregado
Use UUID para referências persistentes quando possível, pois nomes de jogadores podem mudar
Implemente listeners para eventos para sincronizar dados entre plugins
Cache resultados de API em operações frequentes para melhorar performance
Verifique permissões antes de agir - sempre valide se o jogador tem permissão antes de executar ações
Use try-catch ao obter a instância da API - o plugin pode não estar instalado
Respeite as permissões do terreno - sempre use os métodos canPlayer* antes de permitir ações
Considere o modo offline - alguns métodos funcionam com UUID para jogadores offline
Teste com múltiplos terrenos - jogadores podem possuir vários terrenos
Monitore eventos de upgrade - acompanhe mudanças de tamanho para sincronizar dados

Exemplos de uso

Verificar se jogador pode construir

TerrenoHolder terreno = terrenoAPI.getTerrenoAt(player.getLocation());
if (terreno != null && terrenoAPI.canPlayerBuild(player, terreno)) {
    player.sendMessage("§aVocê pode construir aqui!");
} else {
    player.sendMessage("§cVocê não pode construir neste terreno!");
}

Listar todos os terrenos do jogador

List<TerrenoHolder> terrenos = terrenoAPI.getPlayerTerrenos(player);
player.sendMessage("§eVocê possui " + terrenos.size() + " terreno(s)!");
for (TerrenoHolder terreno : terrenos) {
    player.sendMessage("  - " + terreno.getKey());
}

Encontrar terreno pelo nome

TerrenoHolder terreno = terrenoAPI.findTerrenoByName(player, "Casa");
if (terreno != null) {
    player.sendMessage("§aTerreno 'Casa' encontrado!");
} else {
    player.sendMessage("§cTerreno 'Casa' não encontrado!");
}

Monitorar criação de terrenos

@EventHandler
public void onTerrenoCreate(TerrenoCreateEvent event) {
    Player player = event.getPlayer();
    TerrenoHolder terreno = event.getTerreno();
    Bukkit.broadcastMessage("§e" + player.getName() + " criou um novo terreno!");
}

Verificar acesso múltiplo

TerrenoHolder terreno = terrenoAPI.getTerrenoAt(player.getLocation());
if (terreno != null) {
    boolean canBuild = terrenoAPI.canPlayerBuild(player, terreno);
    boolean canBreak = terrenoAPI.canPlayerBreak(player, terreno);
    boolean canOpenContainers = terrenoAPI.canPlayerOpenContainers(player, terreno);
    
    player.sendMessage("Construir: " + (canBuild ? "✓" : "✗"));
    player.sendMessage("Quebrar: " + (canBreak ? "✓" : "✗"));
    player.sendMessage("Abrir contêineres: " + (canOpenContainers ? "✓" : "✗"));
}

Listar terrenos à venda do jogador

List<TerrenoHolder> vendendo = terrenoAPI.getAllTerrenosSelling(player);
if (!vendendo.isEmpty()) {
    player.sendMessage("§eTerrenos à venda:");
    for (TerrenoHolder terreno : vendendo) {
        player.sendMessage("  - " + terreno.getKey());
    }
}

Rastrear expansão de terreno

@EventHandler
public void onTerrenoUpgrade(TerrenoUpgradeEvent event) {
    Player player = event.getPlayer();
    int expansion = event.getCurrentSize() - event.getPreviousSize();
    player.sendMessage("§aTerreno expandido em " + expansion + " blocos!");
}

Sincronizar dados com banco externo

@EventHandler
public void onTerrenoCreate(TerrenoCreateEvent event) {
    TerrenoHolder terreno = event.getTerreno();
    // Sincronizar com banco de dados externo
    minhaAPI.salvarTerreno(terreno.getKey(), event.getPlayer().getUniqueId());
}

@EventHandler
public void onTerrenoDelete(TerrenoDeleteEvent event) {
    TerrenoHolder terreno = event.getTerreno();
    // Remover do banco de dados externo
    minhaAPI.removerTerreno(terreno.getKey());
}

Verificar propriedade de terreno em região

public boolean isPlayerInOwnTerreno(Player player) {
    TerrenoHolder terreno = terrenoAPI.getTerrenoAt(player.getLocation());
    if (terreno == null) return false;
    
    return terreno.getOwnerUUID().equals(player.getUniqueId());
}

Contar terrenos totais do servidor

List<TerrenoHolder> todos = terrenoAPI.getAllTerrenos();
player.sendMessage("§eTotais de terrenos no servidor: " + todos.size());

Nesta página