API
On this page
id.nationcore.api.NationCoreAPI is the single, stable entry point other plugins
use to talk to NationCore.
| 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. |
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.
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.
static boolean isFactoryTaxIntegrationEnabled()true when integration.factory-tax.enabled is on and the plugin is
initialised.
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.
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.
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.
| 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 |
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.