API

A API fornece uma interface pública para desenvolvedores integrarem seus plugins ao sistema de plots do yPlots.

Obtendo a instância da API

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

Exemplo:

PlotsAPIHolder api;

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

Métodos disponíveis

isReady()

Verifica se a API está pronta para uso.

if (!api.isReady()) return;

Retorno:

true se o plugin estiver carregado e o gerenciador de plots disponível

getPlotAt(Location location)

Obtém o plot claimado na localização, incluindo ruas internas de um grupo de merge.

PlotHolder plot = api.getPlotAt(player.getLocation());

Retorno:

PlotHolder ou null se não houver plot claimado

getPlotCellAt(Location location)

Obtém apenas a célula exata do plot (ignora ruas internas de merge).

PlotHolder plot = api.getPlotCellAt(location);

getPlot(String world, int plotX, int plotZ)

Obtém um plot pelas coordenadas de célula no mundo.

PlotHolder plot = api.getPlot("plots", 0, 0);

getPlotById(String id)

Obtém um plot pelo ID.

PlotHolder plot = api.getPlotById(id);

getPlotsByOwner(UUID uuid) / getPlotsByOwner(String ownerUuid)

Retorna a lista de plots do dono.

List<PlotHolder> plots = api.getPlotsByOwner(player.getUniqueId());

getPlotsByOwnerGrouped(UUID uuid)

Retorna os plots do dono com um entry por grupo de merge + plots não mergeados.

List<PlotHolder> plots = api.getPlotsByOwnerGrouped(uuid);

getPlotByOwnerIndex(UUID uuid, int index)

Obtém o plot do dono pelo índice (começa em 1 nos placeholders; na API use o índice interno do plot).

PlotHolder plot = api.getPlotByOwnerIndex(uuid, index);

getPlotsForSale()

Retorna todos os plots à venda.

List<PlotHolder> forSale = api.getPlotsForSale();

getAllPlots()

Retorna todos os plots do servidor.

Collection<PlotHolder> all = api.getAllPlots();

getPlotsWhereFriend(UUID uuid)

Retorna plots onde o jogador é membro/confiável (não dono e não negado).

List<PlotHolder> friends = api.getPlotsWhereFriend(uuid);

getMergeGroup(PlotHolder plot)

Retorna a lista de plots do grupo de merge.

List<PlotHolder> group = api.getMergeGroup(plot);

isPlotWorld(String worldName) / isPlotWorld(World world)

Verifica se o mundo é um mundo de plots.

boolean isPlot = api.isPlotWorld(player.getWorld());

getPlotCoords(Location location)

Retorna as coordenadas da célula {plotX, plotZ}.

int[] coords = api.getPlotCoords(location);
// coords[0] = plotX, coords[1] = plotZ

Retorno:

int[]{plotX, plotZ} ou null se estiver na rua / fora de mundo de plot

isOnRoad(Location location)

Verifica se a localização está na rua.

boolean onRoad = api.isOnRoad(location);

getPlotHome(PlotHolder plot)

Obtém a home/spawn do plot.

Location home = api.getPlotHome(plot);

getDefaultHome(String world, int plotX, int plotZ)

Obtém a home padrão da célula (centro).

Location home = api.getDefaultHome("plots", 0, 0);

getPlotMin / getPlotMax

Obtém os limites do plot (por holder ou por coordenadas).

Location min = api.getPlotMin(plot);
Location max = api.getPlotMax(plot);
Location min2 = api.getPlotMin("plots", 0, 0);
Location max2 = api.getPlotMax("plots", 0, 0);

setHome(PlotHolder plot, Location location)

Define a home do plot.

api.setHome(plot, player.getLocation());

canBuild(Player player, Location location) / canBuild(Player player, PlotHolder plot)

Verifica se o jogador pode construir.

if (api.canBuild(player, location)) {
    // permitido
}

canManage(Player player, PlotHolder plot)

Verifica se o jogador pode gerenciar o plot (membros, flags, etc.).

boolean manage = api.canManage(player, plot);

canInteract(Player player, Location location, PlotFlag flag)

Verifica se o jogador pode interagir respeitando a flag.

boolean ok = api.canInteract(player, location, PlotFlag.USE_CONTAINERS);

hasAccess(Player player, Location location)

Verifica se o jogador tem acesso (dono, confiável, membro ou bypass).

boolean access = api.hasAccess(player, location);

isOwner(Player player, PlotHolder plot)

Verifica se o jogador é o dono.

boolean owner = api.isOwner(player, plot);

isDenied(Player player, PlotHolder plot)

Verifica se o jogador está negado no plot.

boolean denied = api.isDenied(player, plot);

getRole(PlotHolder plot, UUID uuid) / getRole(PlotHolder plot, String name)

Obtém o cargo do jogador no plot.

PlotRole role = api.getRole(plot, player.getUniqueId());

Valores de PlotRole: OWNER, TRUSTED, MEMBER, DENIED

getMaxPlots(Player player)

Retorna o limite máximo de plots do jogador.

int max = api.getMaxPlots(player);

getMaxMergeSize(Player player)

Retorna o limite máximo de merge do jogador.

int maxMerge = api.getMaxMergeSize(player);

getPlotCount(UUID uuid)

Retorna a quantidade de plots do jogador.

int count = api.getPlotCount(uuid);

getPlayerNames(PlotHolder plot)

Retorna os nomes de exibição do dono + membros não negados.

List<String> names = api.getPlayerNames(plot);

getFriendNames(PlotHolder plot)

Retorna os nomes dos amigos/membros do plot.

List<String> friends = api.getFriendNames(plot);

addMember(...)

Adiciona um membro ao plot. Sobrecargas com UUID/String e Player actor opcional.

boolean ok = api.addMember(plot, targetUuid, PlotRole.TRUSTED, actor);
boolean ok2 = api.addMember(plot, "Nick", PlotRole.MEMBER);

Retorno:

true se adicionado com sucesso

removeMember(...)

Remove um membro do plot.

boolean ok = api.removeMember(plot, targetUuid, actor);

clearMembers(PlotHolder plot) / clearMembers(PlotHolder plot, Player actor)

Remove todos os membros do plot.

boolean ok = api.clearMembers(plot, actor);

getFlag(PlotHolder plot, PlotFlag flag)

Obtém o valor de uma flag.

boolean pvp = api.getFlag(plot, PlotFlag.PVP);

setFlag(PlotHolder plot, PlotFlag flag, boolean value) / setFlag(..., Player actor)

Define o valor de uma flag.

boolean ok = api.setFlag(plot, PlotFlag.FLY, true, actor);

claim(Player player, String world, int plotX, int plotZ)

Reivindica um plot livre (cobra economia e dispara PlotClaimEvent).

boolean ok = api.claim(player, "plots", 0, 0);

claimAt(Player player)

Reivindica o plot sob os pés do jogador.

boolean ok = api.claimAt(player);

autoClaim(Player player)

Reivindica o próximo plot livre.

boolean ok = api.autoClaim(player);

deletePlot(PlotHolder plot) / deletePlot(PlotHolder plot, Player actor)

Deleta o plot (limpa terreno, restaura ruas, remove entidade). Dispara PlotDeleteEvent.

boolean ok = api.deletePlot(plot, player);

clearPlot(PlotHolder plot) / clearPlot(PlotHolder plot, Player actor)

Reseta o terreno mantendo a propriedade. Dispara PlotClearEvent.

boolean ok = api.clearPlot(plot, player);

setOwner(PlotHolder plot, UUID newOwnerUuid) / setOwner(..., String newOwnerName, Player actor)

Define ou transfere o dono do plot.

boolean ok = api.setOwner(plot, newOwnerUuid, newOwnerName, actor);

buyPlot(Player buyer, PlotHolder plot)

Compra um plot à venda.

boolean ok = api.buyPlot(buyer, plot);

setForSale(PlotHolder plot, double price, String economy, Player actor)

Coloca o plot à venda.

boolean ok = api.setForSale(plot, 1000.0, "money", actor);

cancelSale(PlotHolder plot, Player actor)

Cancela a venda do plot.

boolean ok = api.cancelSale(plot, actor);

setBiome(PlotHolder plot, String biomeName)

Define o bioma do plot.

boolean ok = api.setBiome(plot, "plains");

setWallKey(PlotHolder plot, String key) / setBorderKey(PlotHolder plot, String key)

Define cosmético de parede/borda pela chave da config.

api.setWallKey(plot, "stone");
api.setBorderKey(plot, "glowstone");

setWalls(PlotHolder plot, Material material, int data) / setBorder(...)

Aplica material bruto como parede/borda (estilo yPlotCore).

api.setWalls(plot, Material.STONE, 0);
api.setBorder(plot, Material.GLOWSTONE, 0);

getWallCosmetics() / getBorderCosmetics()

Retorna o mapa de cosméticos disponíveis.

Map<String, CosmeticBlockHolder> walls = api.getWallCosmetics();
Map<String, CosmeticBlockHolder> borders = api.getBorderCosmetics();

merge(Player player, PlotHolder base)

Agrupa o plot base com vizinhos do mesmo dono.

boolean ok = api.merge(player, plot);

teleport(Player player, PlotHolder plot)

Teleporta o jogador para o plot.

api.teleport(player, plot);

getPlotPlayer(UUID uuid) / getOrCreatePlotPlayer(Player player)

Obtém (ou cria) os dados do PlotPlayer.

PlotPlayerHolder data = api.getOrCreatePlotPlayer(player);

addFavorite(Player player, PlotHolder plot) / removeFavorite(...)

Adiciona ou remove o plot dos favoritos.

api.addFavorite(player, plot);
api.removeFavorite(player, plot);

getPlotIdCompatible(Location location)

Retorna o ID do plot na localização, ou NULL_PLOT.

String id = api.getPlotIdCompatible(location);

getPlotIdCompatible(String permission, Player player, Location location)

Retorna o ID se o jogador tem acesso, NO_PERMISSION se existe mas sem acesso, ou NULL_PLOT se livre.

String id = api.getPlotIdCompatible("alguma.perm", player, location);

getOwnerPlotIdCompatible(Player player, Location location)

Retorna o ID de exibição se o jogador for o dono, senão NULL_PLOT.

String id = api.getOwnerPlotIdCompatible(player, location);

isNoMemberOnline(Location location)

Retorna true se nenhum dono/membro está online neste plot.

boolean empty = api.isNoMemberOnline(location);

Estrutura de dados

PlotHolder

Representa um plot do servidor.

Principais propriedades:

getId() / getDisplayId() — ID da célula / ID de exibição (merge)
getWorld(), getPlotX(), getPlotZ()
getOwnerUuid(), getOwnerName(), getOwnerIndex()
getName(), getDescription(), getBiome()
getMembers(), getFlags()
isSelling(), getSalePrice(), getSaleEconomy()
getWallBlock(), getBorderBlock(), cosméticos desbloqueados
isFlyEnabled(), isFlyUnlocked(), isNightPvp()
getMergeId(), isMerged(), isSameMerge(other)
getCreatedAt(), getModifiedAt()
settings: isShowTitle(), isShowActionbar()

PlotPlayerHolder

Dados do jogador no yPlots.

getUuid(), getName()
getFavorites(), getRecentVisits()
getMergeSlotsBought(), getMemberSlotsBought()
getLastLogin()

PlotRole

Valor	Display	Prioridade
`OWNER`	Dono	100
`TRUSTED`	Confiável	50
`MEMBER`	Membro	25
`DENIED`	Negado	0

Enum com as flags do terreno (PVP, EXPLOSION, FIRE, MOB_SPAWN, ANIMAL_SPAWN, REDSTONE, LIQUID_FLOW, PLANT_GROW, BLOCK_FALL, ITEM_DROP, ITEM_PICKUP, INTERACT, USE_DOORS, USE_BUTTONS, USE_LEVERS, USE_CONTAINERS, FLY, ELYTRA, VEHICLE, PROJECTILE, WEATHER, VILLAGER_TRADE, HANGING_BREAK, ARMOR_STAND, BUCKET).

Use PlotFlag.fromKey("pvp") para obter a flag pela chave da config.

CosmeticBlockHolder

getKey(), getDisplayName(), getMaterial(), getPrices()

Eventos

Pacote: br.com.ystoreplugins.product.yplots.event

PlotClaimEvent

Disparado antes de um jogador reivindicar um plot livre. Cancellable.

@EventHandler
public void onClaim(PlotClaimEvent event) {
    Player player = event.getPlayer();
    PlotHolder plot = event.getPlot();
    String world = event.getWorld();
    int x = event.getPlotX();
    int z = event.getPlotZ();
}

PlotDeleteEvent

Disparado antes de um plot ser deletado. Cancellable.
getPlayer() pode ser null (console/API).

@EventHandler
public void onDelete(PlotDeleteEvent event) {
    PlotHolder plot = event.getPlot();
    Player player = event.getPlayer();
}

PlotClearEvent

Disparado antes do reset do terreno (mantém dono). Cancellable.

@EventHandler
public void onClear(PlotClearEvent event) {
    PlotHolder plot = event.getPlot();
    Player player = event.getPlayer();
}

PlotBuyEvent

Disparado antes da compra de um plot à venda. Cancellable.

@EventHandler
public void onBuy(PlotBuyEvent event) {
    Player buyer = event.getBuyer();
    String seller = event.getSellerName();
    double price = event.getPrice();
    String economy = event.getEconomy();
}

PlotSellEvent

Disparado antes de listar ou cancelar venda. Cancellable.
isListing() — true ao colocar à venda, false ao remover.

@EventHandler
public void onSell(PlotSellEvent event) {
    Player player = event.getPlayer();
    boolean listing = event.isListing();
    double price = event.getPrice();
}

PlotTransferEvent

Disparado antes da transferência de propriedade. Cancellable.

@EventHandler
public void onTransfer(PlotTransferEvent event) {
    String previous = event.getPreviousOwnerName();
    UUID newOwner = event.getNewOwnerUuid();
}

PlotMergeEvent

Disparado antes do merge de plots. Cancellable.

@EventHandler
public void onMerge(PlotMergeEvent event) {
    Player player = event.getPlayer();
    List<PlotHolder> plots = event.getPlots();
    String mergeId = event.getMergeId();
}

PlotFlagChangeEvent

Disparado antes da alteração de uma flag. Cancellable.

@EventHandler
public void onFlag(PlotFlagChangeEvent event) {
    PlotFlag flag = event.getFlag();
    boolean oldValue = event.isOldValue();
    boolean newValue = event.isNewValue();
}

PlotMemberChangeEvent

Disparado ao adicionar, atualizar, remover ou limpar membros. Cancellable.

@EventHandler
public void onMember(PlotMemberChangeEvent event) {
    PlotMemberChangeEvent.Action action = event.getAction(); // ADD, UPDATE, REMOVE, CLEAR
    UUID target = event.getTargetUuid();
    String name = event.getTargetName();
    PlotRole role = event.getRole();
}

PlotEnterEvent

Disparado quando um jogador entra em um plot claimado (ou grupo de merge). Não cancellable.

@EventHandler
public void onEnter(PlotEnterEvent event) {
    Player player = event.getPlayer();
    PlotHolder to = event.getPlot();
    PlotHolder from = event.getFromPlot();
}

PlotExitEvent

Disparado quando um jogador sai de um plot claimado.

@EventHandler
public void onExit(PlotExitEvent event) {
    Player player = event.getPlayer();
    PlotHolder from = event.getPlot();
    PlotHolder to = event.getToPlot();
}

Melhores práticas

Sempre verifique isReady() antes de usar a API
Trate null ao obter plots — a localização pode estar na rua ou fora de mundo de plot
Use UUID para referências persistentes
Escute os eventos cancellable para integrar regras do seu servidor
Use canBuild / canManage / hasAccess antes de permitir ações
Obtenha a API com try-catch — o plugin pode não estar instalado
Prefira getPlotsByOwnerGrouped quando merge deve contar como um terreno

Nesta página