Land Permit API
On this page
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.
Call NationCore immediately before you carve out a new protected region β and critically, before you charge the player anything.
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 displayFor a single-block footprint:
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.
| 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 |
| 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 |
| 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 |
Approvals are single use. Once your build has actually been created:
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.
// 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);
}Give your plugin its own switch, conventionally:
integration:
nation-land-permit:
enabled: trueBoth switches must be on before the gate applies.
- Add
NationCoreto yoursoftdependlist inplugin.yml. - Call on the main server thread β off-thread calls are refused with
ASYNC. - Treat
allowed: falseas final. Do not retry in a loop.
- Developer API β the full API surface
- Land-Use Permits β the operator's view