Skip to content
Aithor Dev

API

On this page

Developer API

id.nationcore.api.NationCoreAPI is the single, stable entry point other plugins use to talk to NationCore.

Design contract

Principle What it means for you
JDK and Bukkit types only Every parameter and return value is a String, int, double, UUID, Location or Map<String, String>. No NationCore classes cross the boundary.
Reflection friendly Because of the above, you can bind to it reflectively β€” a genuine soft dependency with no shared build artifact and no load-order coupling beyond a softdepend entry.
Never throws Every method is wrapped. If NationCore is mid-disable or not yet initialised, calls degrade to "no nation / nothing routed".
Never returns null where a value is expected Permit replies always return a map.
Frozen Keeping this contract stable is what lets the plugins version independently.

Binding reflectively

Java
Class<?> api = Class.forName("id.nationcore.api.NationCoreAPI");
double routed = (double) api
        .getMethod("depositFactoryTax", Location.class, double.class, UUID.class, String.class)
        .invoke(null, location, amount, payerUuid, "factory-id");

Add NationCore to your softdepend in plugin.yml so it loads first when present.

Method reference

Territory

Java
static String getNationNameAt(Location loc)

Returns the name of the nation owning the chunk at loc, or null when the land is unclaimed or NationCore is unavailable.

Factory tax

Java
static boolean isFactoryTaxIntegrationEnabled()

true when integration.factory-tax.enabled is on and the plugin is initialised.

Java
static double depositFactoryTax(Location loc, double amount, UUID payer, String sourceLabel)

Routes a factory tax payment into the treasury of the nation that owns the land at loc.

Parameter Meaning
loc Representative location of the paying factory
amount The gross tax amount the player just paid
payer The paying player's UUID β€” recorded in the ledger, may be null
sourceLabel Short identifier of the paying factory, for the ledger

Returns the amount actually banked, or 0.0 when nothing was routed.

Apartment tax

Java
static boolean isApartmentTaxIntegrationEnabled()
static double  depositApartmentTax(Location loc, double amount, UUID payer, String sourceLabel)

Identical semantics to the factory methods, using the apartment-tax configuration block.

Land permits

Java
static boolean isLandPermitIntegrationEnabled()

static Map<String, String> requestLandUse(
        String worldName, int minX, int minZ, int maxX, int maxZ,
        int anchorY, UUID applicant, String kind, String label)

static Map<String, String> requestLandUseAt(
        Location loc, UUID applicant, String kind, String label)

static boolean consumeLandPermit(String permitId, UUID applicant)

See Land Permit Integration for the reply keys, reason codes and a reference implementation.

Failure behaviour summary

Situation Result
NationCore not loaded Tax methods return 0.0; permit methods return allowed: true (nothing is being policed)
Integration disabled in config.yml Tax methods return 0.0; permit methods return allowed: true with code INTEGRATION_DISABLED
Land unclaimed Tax methods return 0.0; permit methods return allowed: true with code NO_NATION
Unexpected exception inside NationCore Tax methods return 0.0; permit methods return allowed: false β€” an unverifiable claim on national soil is refused, never waved through

What is not in the API

The API is intentionally narrow. It does not expose nation objects, membership lists, treasuries or government state. If you need something that is not here, the supported route is to read the same data through NationCore's own commands, placeholders or data files β€” or to propose an addition that keeps the JDK-and-Bukkit-types-only contract.

Search documentation

    Type to start searching.