Skip to content
Aithor Dev

Architecture

On this page

How NationCore Works

This page explains the shape of the plugin: what the moving parts are and how they fit together. You do not need this to play, but it helps a lot when configuring or debugging the plugin.

The big picture

Text
Player ──▢ /nc command  ──┐
Player ──▢ GUI menu     ───
Other plugin ──▢ API    ──┼──▢ Managers ──▢ Models ──▢ DataManager ──▢ data/*.json
Bukkit event ──▢ Listener β”˜                    β”‚
Scheduler ──▢ timed task β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  • Managers hold the rules. Each system has one (NationManager, TaxManager, ElectionManager, …).
  • Models are plain data objects (Nation, Treasury, Election, …). They are what actually gets saved.
  • DataManager writes those models to JSON files and reads them back.
  • Listeners react to Bukkit events (join, chat, block break, damage).
  • Schedulers run the clock: elections advance, taxes are billed, research finishes.

One nation, one object

Everything about a nation lives inside a single Nation object:

Inside a nation What it holds
Identity Unique id, name, 3-letter tag, government type, founding time
Members Player members with roles, plus NPC members
Territory The set of owned chunk keys and the capital location
Treasury Balance, income/expense totals and the transaction log
Government A Republic, Communist, Monarchy or Caliphate government object
Activity Active executive orders, office decisions, election, recall petition, arena session
Extras Research progress, shared storage, welcome message, map colour, tax switch

A chunk key looks like world;chunkX;chunkZ. Membership of a chunk is what decides who owns a piece of land.

Legacy versus per-nation state

NationCore grew out of a single-government plugin. A few managers still keep a "global" fallback object (one server-wide government, election and treasury) next to the per-nation ones. That is why you will see method pairs like getTreasury() and getTreasury(nation).

For a modern server all real state is per-nation. The global objects only matter for data carried over from very old versions.

Configuration layers

NationCore reads settings from four places, in this order of specificity:

  1. config.yml β€” server-wide: capital rules, territory prices, integrations, live map.
  2. nations/<type>.yaml β€” per government type: founding cost, salaries, elections, tax phases, which orders each office may issue.
  3. order.yaml β€” one entry per executive order or office decision: enabled, display name, lore, cooldown, cost and tuning attributes.
  4. research.yml β€” one entry per research project.

All four reload with /nc admin reload, plus language.yml.

Some Republic settings (president, presidential-games, approval, leader_salary) are merged from nations/republic.yaml into the main configuration object at load time, which is why the code reads them with plain getConfig() calls.

Persistence

Everything is stored as JSON under plugins/NationCore/data/:

File Contents
nations.json Every nation and everything inside it
players.json Per-player records: playtime, role, stats, election history
tax_record.json Tax profiles, invoices and national debt
land_permits.json Land-use permit queue
government.json, election.json, treasury.json, orders.json, decisions.json, arena.json, recall.json, misc.json Legacy server-wide state

Data is saved every 5 minutes asynchronously, on shutdown, and immediately after important actions such as creating a nation or claiming a chunk.

Threading

  • Almost everything runs on the main server thread, because it touches live world and player state.
  • Saving data runs asynchronously every 5 minutes.
  • Live-map rendering runs on a single background worker. The main thread only fingerprints nations to spot changes; tracing borders and building popups happen off-thread.
  • The land-permit gate refuses any request that arrives off the main thread rather than risking a race.

Messages

All player-facing text comes from language.yml through MessageUtils. Messages support MiniMessage tags (<red>, <gold>, <bold>), legacy & colour codes, a <centered> tag, and {placeholder} substitution. If a key is missing from the operator's file, the English default bundled in the jar is used.

Search documentation

    Type to start searching.