m
Docs

Developer API

Public API for integrating minePlots with external plugins.

Overview

minePlots provides a public API module (plugin-api) that allows external plugins to interact with plots, members, warps, bans, and profiles. The package root is pl.minecodes.plots.api.

Installation

The API is published to the mineCodes Maven repository.

Gradle (Kotlin DSL)

repositories {
    maven("https://maven.minecodes.pl/releases/")
}

dependencies {
    compileOnly("pl.minecodes.plots:plugin-api:4.6.2")
}

Maven

<repositories>
    <repository>
        <id>minecodes-releases</id>
        <url>https://maven.minecodes.pl/releases/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>pl.minecodes.plots</groupId>
        <artifactId>plugin-api</artifactId>
        <version>4.6.2</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

plugin.yml

Add minePlots as a dependency in your plugin:

depend: [minePlots]

Or as a soft dependency if plot integration is optional:

softdepend: [minePlots]

Accessing Services

minePlots registers its services in the Bukkit ServicesManager:

PlotServiceApi plotService = Bukkit.getServicesManager()
    .load(PlotServiceApi.class);

ProfileServiceApi profileService = Bukkit.getServicesManager()
    .load(ProfileServiceApi.class);

Always null-check the result — the services are available only after minePlots has been enabled.

Core Interfaces

PlotServiceApi

Plot lookups:

interface PlotServiceApi {
    PlotApi getPlot(Location location);
    PlotApi getPlot(UUID owner);
    PlotApi getPlot(int id);
    List<PlotApi> getPlots();
    List<PlotApi> getPlotsByWorld(UUID worldUniqueId);
}

All getPlot(...) lookups return null when no plot matches.

PlotApi

Represents a single plot. The most important methods:

interface PlotApi {
    int getId();
    UUID getOwner();
    String getName();

    Location getCenter();
    Location getHome();
    RegionApi getRegion();

    boolean isClosed();
    long getCreated();
    long getExpireIn();

    Set<MemberApi> getMembers();
    MemberApi getMember(UUID uuid);
    void addMember(UUID uuid);
    void removeMember(UUID uuid);

    Set<FlagType> getFlags();
    void addFlag(FlagType flag);
    void removeFlag(FlagType flag);

    boolean hasMemberPermission(UUID uuid, PermissionType permission);
    boolean hasAccess(Player player);
}

getMember(UUID) returns null when the player is not a member.

ProfileServiceApi

Player profile lookups:

interface ProfileServiceApi {
    @Nullable ProfileApi getProfileByUniqueId(UUID uniqueId);
    @Nullable ProfileApi getProfileByUsername(String nickname);
}

RegionApi

Plot region bounds:

interface RegionApi {
    boolean isInCuboid(Location location);
    int getSize();
    int getX();
    int getZ();
}

MemberApi

interface MemberApi {
    UUID getUuid();
    long getAdded();
    Set<PermissionType> getPermissions();
    boolean hasPermission(PermissionType permissionType);
}

WarpApi & BanApi

The API also exposes warp (WarpApi, WarpServiceApi) and ban (BanApi, BanServiceApi) interfaces in the pl.minecodes.plots.api.warp and pl.minecodes.plots.api.ban packages. Ban and warp data is best consumed through the related events listed below.

Type Enums

FlagType

PVP, BUILD, DESTROY, INTERACT, ITEM_FRAME, CHEST, EXPLOSION, LAVA, WATER, IGNITE, SNOW_MAN, ARMOR_STAND, ENDER_PEARL, SET_HOME, DAMAGE_AGGRESSIVE_MOBS, DAMAGE_PASSIVE_MOBS, POTION, VEHICLE, RECEIVE_DAMAGE_FROM_MOBS, PHANTOM_SPAWN

PermissionType

PANEL_OPEN, RENAME_PLOT, CHANGE_FLAG, INVITE_MEMBER, KICK_MEMBER, EXPIRATION_MANAGE, PERMISSION_MANAGE, MANAGE_VISIBILITY, UPGRADE_MANAGE, BAN_MEMBERS, PLOT_OPEN, PLOT_CLOSE

Events

All events live under pl.minecodes.plots.api.event and are standard Bukkit events.

EventCancellableFired
PlotCreateEvent✅Before plot registration and save
PlotRemoveEvent❌After plot deletion
PlotRenameEvent✅Before rename is applied (mutable via setNewName)
PlotFlagChangeEvent✅Before a flag change is applied (mutable via setNewValue)
PlotFlagCanceledEvent❌When a flag check denies an action
PrePlotEntryEvent✅Before a player enters a plot
PlotEntryEvent✅After the pre-entry check passes
PrePlotLeaveEvent✅Before a player leaves a plot
PlotLeaveEvent✅After the pre-leave check passes
PlotPlayerMoveEvent❌On movement within the same plot
PlotTeleportEvent✅On plot teleport (home, visit, warp, admin)
PlotSetHomeEvent✅Before plot home is updated (mutable via setHomeLocation)
PlotBlockInteractEvent✅On block interaction inside a plot
PlotPermissionChangeEvent✅When member permission is toggled
PlotMemberAddEvent✅Before a member is added
PlotMemberRemoveEvent✅Before a member is removed (kick, leave, admin)
PlotBanEvent✅Before a ban record is persisted
PlotUnbanEvent✅Before a ban is removed
PlotWarpCreateEvent✅Before a warp is created (mutable name and location)
PlotWarpDeleteEvent✅Before a warp is deleted
PlotExpirationWarningEvent❌During the scheduled expiry reminder pass
PlotExpiredEvent✅Before automatic deletion of an expired plot

Event Order

Movement and teleports crossing plot boundaries:

  1. PrePlotEntryEvent / PrePlotLeaveEvent
  2. If not cancelled: PlotEntryEvent / PlotLeaveEvent

Cancelling a pre-event cancels the original player move or teleport event. Movement inside the same plot fires only PlotPlayerMoveEvent.

Examples

Find a Plot at a Location

PlotServiceApi plotService = Bukkit.getServicesManager().load(PlotServiceApi.class);

PlotApi plot = plotService.getPlot(player.getLocation());
if (plot != null) {
    player.sendMessage("You are on plot: " + plot.getName());
}

Check Plot Access

PlotApi plot = plotService.getPlot(location);
if (plot != null && !plot.hasAccess(player)) {
    player.sendMessage("You cannot build here!");
}

Listen for Plot Creation

@EventHandler
public void onPlotCreate(PlotCreateEvent event) {
    Player player = event.getPlayer();
    if (!player.hasPermission("myplugin.plots.create")) {
        event.setCancelled(true);
        player.sendMessage("You are not allowed to create plots.");
    }
}

Block Entry to a Plot

@EventHandler
public void onPlotEntry(PrePlotEntryEvent event) {
    PlotApi plot = event.getPlot();
    Player player = event.getPlayer();
    if (plot.isClosed() && !plot.hasAccess(player)) {
        event.setCancelled(true);
    }
}

Modify a Flag Change

@EventHandler
public void onFlagChange(PlotFlagChangeEvent event) {
    if (event.getFlagType() == FlagType.EXPLOSION && event.getNewValue()) {
        event.setNewValue(false);
    }
}

Integration Notes

  • Always null-check lookup results from plot, warp, and profile services.
  • Prefer pre-events (PrePlotEntryEvent, PrePlotLeaveEvent) when you need to block movement.
  • Use mutable event fields (setNewValue, setWarpName, setWarpLocation, setHomeLocation, setTeleportLocation) to alter behavior where supported.
  • PlotTeleportEvent fires after the teleport is executed in current built-in flows — treat it as a notification hook.
Previous 🏷️ PlaceholderAPI