Skip to content
Aithor Dev

Land Permit API

On this page

Land Permit Integration

This page is for plugin developers implementing the partner side of the land-use permit workflow β€” the side that wants to build something on ground a nation may own.

For the player-facing and operator-facing view, read Land-Use Permits.

When to call

Call NationCore immediately before you carve out a new protected region β€” and critically, before you charge the player anything.

The call

Java
Map<String, String> reply = NationCoreAPI.requestLandUse(
        worldName,      // String
        minX, minZ,     // int, inclusive minimum block coordinates
        maxX, maxZ,     // int, inclusive maximum block coordinates
        anchorY,        // int, a representative Y inside the region
        applicantUuid,  // UUID of the player who initiated the build
        "FACTORY",      // or "APARTMENT"
        "smelter-04");  // a short label, sanitised before display

For a single-block footprint:

Java
Map<String, String> reply = NationCoreAPI.requestLandUseAt(location, applicantUuid, "APARTMENT", label);

The reply is a Map<String, String> so it can cross a reflective boundary without a shared class. It is never null and the call never throws.

Reply keys

Key Meaning
allowed "true" / "false". The only field you must obey.
code Machine-readable reason (see the table below)
message Ready-to-send text with section-sign colours, localised from NationCore's language.yml. Empty when allowed
notified "true" when NationCore already delivered that message to the applicant β€” do not repeat it
permitId Present only with PERMIT_GRANTED. Pass it to consumeLandPermit once the build succeeds
nation Name of the nation that owns the land, when known

Reason codes

Allowed

Code Meaning
INTEGRATION_DISABLED NationCore is not policing land
KIND_DISABLED This build kind is exempt
NO_NATION The land is unclaimed
BYPASS The applicant has the bypass permission
LEADER / OFFICER / CITIZEN The applicant is exempt by role
PERMIT_GRANTED A valid approval is already in hand β€” use permitId

Refused

Code Meaning
PENDING An application has just been filed; the leader must decide
LEADER_OFFLINE The head of state is offline and cannot be asked
NO_LEADER The nation has no leader
ALREADY_PENDING The same plot is already awaiting a decision
DENIED_RECENTLY A refusal for this plot is still within its cooldown
COOLDOWN The applicant is applying too quickly
PLAYER_LIMIT The applicant already has the maximum pending applications
NATION_LIMIT The nation's pending queue is full
MULTI_NATION The footprint straddles more than one nation
AREA_TOO_LARGE The footprint exceeds max-area-chunks
APPLICANT_OFFLINE The applicant could not be verified as an online player
APPLICANT_TOO_FAR Location verification is on and the applicant is not nearby
INVALID Bad input β€” unknown world, null applicant
ASYNC The call arrived off the main server thread
ERROR Something went wrong; the claim is refused rather than waved through

Burning the approval

Approvals are single use. Once your build has actually been created:

Java
boolean consumed = NationCoreAPI.consumeLandPermit(permitId, applicantUuid);

Forgetting this means the player has to ask again next time. Calling it twice, or with someone else's id, simply returns false.

Reference flow

Java
// 1. Ask
Map<String, String> reply = NationCoreAPI.requestLandUse(
        world, minX, minZ, maxX, maxZ, y, uuid, "FACTORY", label);

if (!Boolean.parseBoolean(reply.get("allowed"))) {
    // 2. Refused β€” show the message unless NationCore already did
    if (!Boolean.parseBoolean(reply.getOrDefault("notified", "false"))) {
        String message = reply.get("message");
        if (message != null && !message.isEmpty()) {
            player.sendMessage(message);
        }
    }
    return;   // do NOT charge the player, do NOT create the region
}

// 3. Allowed β€” charge the player and create the region
createRegion();

// 4. Burn the approval if there was one
String permitId = reply.get("permitId");
if (permitId != null) {
    NationCoreAPI.consumeLandPermit(permitId, uuid);
}

Your side of the two-key switch

Give your plugin its own switch, conventionally:

YAML
integration:
  nation-land-permit:
    enabled: true

Both switches must be on before the gate applies.

Requirements

  • Add NationCore to your softdepend list in plugin.yml.
  • Call on the main server thread β€” off-thread calls are refused with ASYNC.
  • Treat allowed: false as final. Do not retry in a loop.

Search documentation

    Type to start searching.