Performance
On this page
NationCore is built to stay cheap on the main thread, but on a large server a few systems are worth knowing about.
| System | Scales with | Notes |
|---|---|---|
| Tax billing cycle | Player count | Runs once per 24 hours. Players offline for more than 3 days are skipped |
| Border particles | Nations with borders toggled on, near players | Throttled to ~2 renders per second, culled by distance |
| Live map | Nation count and territory size | The main thread only fingerprints; rendering happens off-thread |
| Data saving | Total data size | Runs asynchronously |
| Land permits | Footprint size of each request | Hard-capped by max-area-chunks |
| Territory lookups | Constant | A hash-set lookup on a chunk key |
Everything else is a one-minute "is it time yet?" check that returns immediately.
The single most impactful block on a big server.
integration:
squaremap:
refresh:
interval-seconds: 10
instant-territory-updates: true| Symptom | Change |
|---|---|
| Map updates feel heavy | Raise interval-seconds to 30 or 60 |
| You do not need sub-second claim feedback | Set instant-territory-updates: false |
| Popups feel large | Trim nation-popup.html, lower max-listed-relations |
| Online counts churn the map | Raise popup.online-refresh-seconds |
| Too many worlds drawn | Use worlds.mode: whitelist with only the worlds that matter |
Check your numbers with:
/nc admin map statusThat report includes the last render duration and the average scan time. If scan time is fine but render time is high, the cost is in polygon tracing β reduce the number of mapped worlds or hide very large nations.
- The main thread only fingerprints each nation (a territory hash plus the few fields the popup shows).
- Only nations whose fingerprint changed are copied into immutable snapshots.
- Outline tracing, HTML building and marker construction all run on a single background worker.
- A new scan never starts while a render is still running, so work cannot pile up.
- Each nation becomes one merged polygon per world instead of one square per chunk, which also keeps squaremap's own per-update work small.
The particle border is opt-in per nation, so the cost is self-limiting: if nobody has it on, the task does almost nothing.
Built-in limits:
- Re-drawn every 10 ticks (~2Γ per second).
- Only chunks within a Chebyshev chunk-distance of an online player are drawn.
- Unloaded chunks are never touched.
- Only the outer perimeter is drawn β shared internal edges are skipped.
If borders are still costing you on a very large server, ask leaders to toggle them off when not needed, or rely on the live map instead.
integration:
land-permit:
max-area-chunks: 1024
max-pending-per-player: 3
max-pending-per-nation: 50
request-cooldown-seconds: 60max-area-chunks caps the cost of a territory lookup: a footprint bigger than
this is refused outright rather than scanned. Raise it only if you genuinely use
huge apartment regions.
The pending caps and cooldown exist as much for the head of state's sanity as for performance.
The daily billing cycle is the heaviest recurring job. It is bounded by:
- Running only once per 24 hours.
- Skipping players offline for more than 3 days.
- Doing one invoice per player, not per nation membership.
A nation can opt out entirely from its Settings menu, which removes its members from the cycle.
nations.json grows with:
- Number of nations
- Territory size (one string per chunk)
- Transaction log length
- Shared storage contents (Base64 item data)
If the file becomes unwieldy, the usual culprits are very large territories and long transaction logs. Disbanding abandoned nations reclaims the space on the next save.
All state is held in memory. Rough guidance:
- A nation object is small β members, a chunk-key set, a treasury with its log.
- Shared storage is the largest per-nation item (up to 45 serialised item stacks).
- Player records are small and bounded by your player base.
For a server with a few hundred nations:
integration:
squaremap:
refresh:
interval-seconds: 30
instant-territory-updates: true
popup:
online-refresh-seconds: 120
max-listed-relations: 3
land-permit:
max-area-chunks: 512
max-pending-per-nation: 25