NexaClaims Documentation

Recommended order#

1. Choose the storage provider and table prefix.
2. Set the claim world policy and capacity rules.
3. Enable chunk claims, selection claims and protection.
4. Configure roles, member actions and trusted players.
5. Add economy pricing, upkeep, sale or rent only if needed.
6. Test with a non-admin account in wilderness and inside a claim.

Minimal policy#

modules:
  territory.chunk-claim: true
  territory.selection: true
  protection: true
  economy: false
  nations: false
  warfare: false

claim:
  default-capacity: 16
  allow-auto-claim: false

Claim creation#

• /claim here for the current chunk.
• /claim radius <n> for an area around the player.
• /claim wand and /claim selection claim for cuboid selection.
• Claim map and preview GUI show capacity, cost and wilderness state before confirmation.

Ownership model#

• Owner, trusted members and role thresholds are stored independently.
• Per-claim action overrides live in permissions.yml.
• Adjacent owned claims can be merged.
• Unlimited capacity is permission-gated, not silently enabled.

Quality-of-life#

• Auto-claim can claim wilderness as a player enters it.
• Border particles and temporary client-side fallback visualize boundaries.
• Starter chest, trapped rescue, claim chat, favorites and top lists are available.
• Claim core, public state, warps, fly and vaults are separate controls.

Supported flows#

• Optional creation pricing: base, per-chunk and progressive existing-chunk cost.
• Claim bank deposits, withdrawals and upkeep processing.
• Sale marketplace with commission, listing, purchase and cancellation.
• Rent offers with accept, leave, expiration and owner/tenant notifications.
• Private/public warps with optional teleport fees.
• Vault inventory persistence and trusted access.

Lifecycle controls#

• Renewal windows and one/seven/thirty-day actions.
• Temporary camps with expiration events.
• Audit entries for economy, warp, rent and lifecycle actions.
• Migration commands create timestamped YAML backups before import.

/claim renew 30
/claim rent offer 250 7
/claim bank
/claim audit 25

Nation operations#

• Create, list and inspect nations.
• Add land to a nation and manage capital land.
• Store diplomacy state in diplomacy.yml.
• Use nation bank operations through the active economy provider.

/nation create Ember
/nation addland Ember
/nation diplomacy list
/nation deposit 500 Ember

War safety baseline#

war:
  enabled: true
  overlay:
    allow-block-break: false
    allow-block-place: false
    allow-entity-damage: false

Declare land-vs-land, land-vs-nation or nation-vs-nation conflicts, then inspect score, capture, surrender and end operations from the admin workflow.

Data surfaces#

• Lands and chunks
• Members, roles and permission overrides
• Vaults, warps, lifecycle, rent and camps
• Nations, diplomacy and wars
• Economy ledger and audit entries
• Favorites and migration state

Safe migration#

1. Run /nclaims storage and /nclaims migration adapters.
2. Review /nclaims migration preview.
3. Create an external backup.
4. Run the import during a maintenance window.
5. Verify counts, ownership and protection before enabling players.

Economy & permissions#

Vault/VaultUnlocked, LuckPerms and PlaceholderAPI can provide currency, context, metadata, claim capacity and scoreboard values.

Maps & presentation#

dynmap, BlueMap, Pl3xMap and squaremap marker adapters; DecentHolograms, HolographicDisplays, CMI and ArmorStand fallback for marketplace displays.

Network & gameplay#

Redis publish/locks, Discord webhooks, Geyser/Floodgate forms, ItemsAdder/Oraxen/Nexo materials and QuickShop-Hikari protection bridges.

Service access#

NexaClaimsApi api = Bukkit.getServicesManager()
    .load(NexaClaimsApi.class);

if (api != null && api.claims().isClaimed(location)) {
    // Read the public territory state.
}

Services cover claims, territory, memberships, permissions, environment rules, economy, vaults, lifecycle, rent, nations, wars and audit queries. Always handle a missing service during reload or disabled-module states.

Events#

Listen for land create/delete, chunk claim/unclaim, member add/remove, permission changes, sub-area creation, vault transactions, rent lease create/expire, camp expire, nation create, war declare/start/end and admin actions.

Cancel or validate before mutating external state, and never assume an optional integration is present.

Owner flow#

1. Preview capacity, price and boundary.
2. Create and inspect before setting a home.
3. Add members with the smallest role.
4. Test containers, doors, redstone and animals.
5. Confirm /claim info and manage menu.

Economy lifecycle#

1. Test /claim deposit/withdraw on disposable claim.
2. Enable renewal notices.
3. Test sale/rent with two accounts.
4. Back up before storage changes.

Go-live#

• Use explicit world/region rules.
• Keep economy errors visible.
• Test expiration, unclaim, transfer and restart.
• Document trust and war policies.

Baseline#

storage: type: sqlite claims: prevent-overlap: true notify-before-expire: true economy: require-vault: true

Player claim workflow#

1. Use /claim preview in wilderness to inspect capacity and price.
2. Confirm with /claim here, or use /claim wand followed by /claim selection claim for a selected area.
3. Open /claim manage, add members with /claim trust <player> [role] and verify role actions.
4. Test a protected block, container and pet with a non-member account.
5. Set a home/warp only after ownership and permission checks pass.

Economy and lifecycle workflow#

1. Confirm Vault/economy status with /nclaims hooks.
2. Test /claim deposit, /claim withdraw and upkeep on a disposable claim.
3. Create a low-value sale or rent listing, accept it from another player and verify audit entries.
4. Renew lifecycle-managed claims before enabling expiration notifications.
5. Back up YAML/database data before migration or table-prefix changes.

Nation and war rollout#

Create nations and diplomacy records first. Declare a test war while all destructive overlay flags are disabled, verify score/capture/surrender/end, then enable only the world actions your rules and rollback process support.

/nation create Ember
/nation addland Ember
/war declare land 12
/war info <id>
/war surrender <id>

Menu editor checklist#

Open /nclaims menu-editor, move one item, save, reload and reopen the same menu. If an item disappears, validate its material, action, module visibility and permission before changing slots again.

Include#

• Plugin, Paper and Java versions
• Storage type and enabled modules
• /nclaims status, modules and hooks output
• Relevant YAML section with secrets removed
• Full error and exact reproduction steps

Never include#

License keys, database passwords, webhook tokens, Redis credentials or private player data. Replace them with REDACTED before sharing logs.