Skip to content
Aithor Dev

Data Files

On this page

Data Files

NationCore stores all game state as JSON in plugins/NationCore/data/.

Do not edit these files while the server is running. The plugin keeps state in memory and overwrites the files on its next save, so your edits would be lost β€” or worse, produce inconsistent data.

The files

File Contents
nations.json The important one. Every nation and everything inside it: members, NPCs, territory, capital, treasury, government, orders, decisions, election, recall petition, arena session, research, shared storage, diplomacy, welcome message, map colour
players.json Per-player records: playtime, last seen, nation id and role, election history, arena statistics, punishments, pending rewards
tax_record.json Tax profiles, every invoice, payment history and national debt
land_permits.json The land-use permit queue, including settled permits kept for auditing
government.json Legacy server-wide government (pre-multi-nation data)
election.json Legacy server-wide election
treasury.json Legacy server-wide treasury
orders.json Legacy server-wide active executive orders
decisions.json Legacy server-wide active cabinet decisions
arena.json Legacy server-wide arena session
recall.json Legacy server-wide recall petition
misc.json Miscellaneous counters, such as the last executive-order timestamp

The "legacy" files exist so data from very old single-government versions is not lost. On a modern server all meaningful state lives in nations.json, players.json, tax_record.json and land_permits.json.

When data is saved

Trigger What is saved
Every 5 minutes Everything, asynchronously
Server shutdown Everything
After a nation action nations.json (and players.json for membership changes)
After a permit decision land_permits.json
After a tax payment tax_record.json

Important actions save immediately rather than waiting for the timer, so a crash loses at most a few minutes of low-value state.

Format

Files are written with Gson using pretty printing, so they are readable:

JSON
[
  {
    "id": "0f9a...",
    "name": "Avalon",
    "tag": "AVA",
    "type": "MONARCHY",
    "leaderUUID": "3c1d...",
    "members": { ... },
    "territory": [ "world;12;-5", "world;13;-5" ],
    "treasury": { "balance": 425000.0, "transactions": [ ... ] }
  }
]

Territory entries use the chunk key format world;chunkX;chunkZ.

Resilience

The loaders are defensive:

  • A missing file is treated as "no data yet", not an error.
  • A malformed file logs a warning and falls back to empty data rather than crashing the plugin.
  • Collections added by newer versions are created on demand when an older file does not have them.
  • Shared storage lists that are short or malformed are padded back to the correct size.
  • Land permits are re-expired as they load, so an approval cannot silently outlive the window the leader granted it.

Backups

Back up the whole data/ folder:

  • Before any plugin upgrade.
  • Before editing configuration that changes balance significantly.
  • On your normal world-backup schedule.

To restore, stop the server, replace the folder, and start again.

Moving a server

The data/ folder is fully portable. Copy it along with the configuration files and the nations move with it. Player UUIDs are what tie records together, so an online-mode server keeps every membership intact.

Manual edits

If you genuinely must edit by hand:

  1. Stop the server.
  2. Make a copy of the file first.
  3. Edit carefully β€” valid JSON, correct types.
  4. Start the server and check the console for load warnings.

For most purposes the admin commands are safer:

Text
/nc admin treasury set <nation> <amount>
/nc admin set leader <nation> <player>
/nc admin research reset <nation>
/nc admin invoice remove <player>
/nc admin npc kick <nation> <name>

Search documentation

    Type to start searching.