Skip to content
Aithor Dev

SquareMap

On this page

squaremap Live Map

With squaremap installed, NationCore draws every nation's territory and capital on the live web map and keeps it current while the server runs β€” claims, releases, capital moves, foundings, disbandings, elections, diplomacy and treasury changes all appear without a restart.

Setup

  1. Install squaremap.
  2. Make sure integration.squaremap.enabled is true in config.yml (it is by default).
  3. Set your public map address so /nc map can give players a clickable link:
YAML
integration:
  squaremap:
    enabled: true
    web:
      public-url: "https://map.example.com"
      link-zoom: 3
  1. Apply changes with /nc admin map reload.

NationCore hooks in automatically, even if squaremap is enabled after NationCore.

NationCore has no squaremap imports in its main code path. The squaremap-dependent bridge is only loaded once squaremap is confirmed present, so the plugin runs unchanged on servers without it.

What gets drawn

Element Description
Territory One merged polygon per nation per world β€” not one square per chunk
Capital icon An emblem badge at the capital, chosen by government type
Capital chunk highlight The capital chunk outlined in gold so the seat of government stands out
Popups A rich info card when a territory or capital is clicked
Tooltips A compact card while hovering

Layers

squaremap's layer control (top right of the map) gets one or two NationCore layers:

YAML
layers:
  territories:
    label: "Nations ({count})"
    show-controls: true
    default-hidden: false
    priority: 20
    z-index: 20
    split-by-government: false
    government-labels:
      republic: "Republics ({count})"
      communist: "Communist States ({count})"
      monarchy: "Kingdoms ({count})"
      caliphate: "Caliphates ({count})"
  capitals:
    enabled: true
    label: "Capitals"
    show-controls: true
    default-hidden: false
    priority: 25
    z-index: 250

Set split-by-government: true to get one toggleable layer per government type instead of a single combined layer.

Colours

YAML
style:
  color-mode: GOVERNMENT     # or NATION
  government-colors:
    republic: "#55AAFF"
    communist: "#FF3C3C"
    monarchy: "#FFAA00"
    caliphate: "#5ADC5A"
  stroke-weight: 2
  stroke-opacity: 0.9
  fill-opacity: 0.22
  allow-leader-colors: true
  overrides: {}
Mode Behaviour
GOVERNMENT Colour by government type β€” matches the in-game particle borders
NATION A unique, stable colour per nation, so neighbours of the same type are easy to tell apart

Priority, highest first: overrides β†’ the leader's chosen colour β†’ the colour mode.

Leader colours

When allow-leader-colors is true, a head of state can pick their nation's map colour:

Text
/nc map color #8E44AD
/nc map color purple
/nc map color reset

Accepted names: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white, orange, pink, purple, teal, navy, crimson, emerald, brown. Hex works with or without the leading #.

Requires the nation.map.color permission.

Capital icons

YAML
capitals:
  icon:
    enabled: true
    size: 28
  highlight-chunk:
    enabled: true
    color: "#FFD700"
    stroke-weight: 3
    fill-opacity: 0.15

By default an emblem is generated automatically per government type (building, star, crown or crescent). To use your own artwork, drop PNG files into plugins/NationCore/squaremap/icons/:

Text
capital-republic.png
capital-communist.png
capital-monarchy.png
capital-caliphate.png
capital.png            # fallback for every government

Popups and tooltips

The HTML lives in plugins/NationCore/squaremap/ and can be restyled freely:

File Shown when
nation-popup.html A visitor clicks a territory or capital
nation-tooltip.html A visitor hovers over a territory
capital-tooltip.html A visitor hovers over a capital icon or highlighted chunk

Delete a file and reload to get the default design back.

Template placeholders

Every value is HTML-escaped, so a player-chosen name can never inject markup.

Group Placeholders
Identity {nation}, {tag}, {nation_id}
Government {government}, {government_symbol}, {government_color}
Colour {color}, {color_text} (black or white, whichever reads best)
Leadership {leader_title}, {leader}
People {members}, {citizens}, {npcs}, {online}
Land {chunks}, {area}
Capital {capital}, {capital_world}, {capital_x}, {capital_y}, {capital_z}
Economy {treasury}, {tax}
History {founded}, {age}
Diplomacy {allies}, {truces}, {wars}, {ally_count}, {truce_count}, {war_count}, {relations}
Other {welcome}, {popup}

Conditional sections

HTML
{?key} shown only when {key} is NOT empty {/key}
{!key} shown only when {key} IS empty {/key}

Values switched off in config.yml become empty, so their sections disappear automatically.

YAML
popup:
  click-popup: true
  hover-tooltip: true
  show-treasury: true
  show-online-members: true
  online-refresh-seconds: 60
  show-diplomacy: true
  show-welcome-message: true
  max-listed-relations: 5
  welcome-max-length: 160
  currency-symbol: "$"
  date-format: "d MMM yyyy"

show-treasury, show-online-members, show-diplomacy and show-welcome-message are privacy switches β€” a hidden value disappears from the popup entirely.

Worlds and hidden nations

YAML
worlds:
  mode: blacklist     # or whitelist
  list: []
hidden-nations: []
  • blacklist draws nations on every squaremap world except those listed.
  • whitelist draws them only on the worlds listed.
  • hidden-nations accepts nation names or ids β€” useful for staff or event nations.

Refresh behaviour

YAML
refresh:
  interval-seconds: 10          # min 2, max 600
  instant-territory-updates: true
  • Every interval-seconds, the map is checked for changes such as elections, new members, diplomacy or treasury movement. Checking is cheap; nothing is redrawn unless something visible actually changed.
  • With instant-territory-updates, claims, releases, capital moves, foundings, disbandings, renames and colour changes appear within about one second.
  • squaremap itself publishes marker changes every 5 seconds by default (map.markers.update-interval-seconds in squaremap's own config).

Performance

The design keeps the main thread almost free:

  • The main thread only fingerprints nations to spot changes.
  • Outline tracing, HTML building and marker construction run on a single background worker.
  • Each nation becomes one merged polygon per world, which also keeps squaremap's own per-update work small.
  • A new scan never starts while a render is still running, so work cannot pile up.

Player commands

Text
/nc map            # open your nation's capital on the live map
/nc map here       # open your current location
/nc map color ...  # set your nation's colour (head of state)
/nc map help       # usage

Requires nation.map (and nation.map.color for colours). If no public-url is configured, the plugin says so rather than sending a broken link.

Admin commands

Text
/nc admin map status     # health and performance numbers
/nc admin map reload     # reload map settings and popup templates
/nc admin map refresh    # force a full redraw

status reports the squaremap version, mapped worlds, active layers, rendered nation/marker/vertex counts, the last render time and duration, average scan time, the scan interval, whether instant updates are on, and the configured public URL.

Search documentation

    Type to start searching.