Skip to content
Aithor Dev

Performance

On this page

Performance and Tuning

NationCore is built to stay cheap on the main thread, but on a large server a few systems are worth knowing about.

Where the cost is

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.

Live map tuning

The single most impactful block on a big server.

YAML
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:

Text
/nc admin map status

That 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.

Why the map stays cheap

  • 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.

Border particle tuning

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.

Land permit tuning

YAML
integration:
  land-permit:
    max-area-chunks: 1024
    max-pending-per-player: 3
    max-pending-per-nation: 50
    request-cooldown-seconds: 60

max-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.

Tax tuning

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.

Data size

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.

Memory

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.

A good baseline

For a server with a few hundred nations:

YAML
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

Search documentation

    Type to start searching.