Architecture
On this page
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.
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.
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.
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.
NationCore reads settings from four places, in this order of specificity:
config.ymlβ server-wide: capital rules, territory prices, integrations, live map.nations/<type>.yamlβ per government type: founding cost, salaries, elections, tax phases, which orders each office may issue.order.yamlβ one entry per executive order or office decision: enabled, display name, lore, cooldown, cost and tuning attributes.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.
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.
- 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.
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.