Configuration: BlueMap

Wiki/Reference/Configuration: BlueMap

Full key-by-key reference for WN BlueMap's server config file, covering every layer toggle, color, opacity, pacing value, and integration setting.

SERVER ADMINSMODPACK DEVS

Config file

config/warring-nations/wn-bluemap-server.toml

All values are read live, no caching layer of its own, so an edit takes effect on the next marker rebuild, no server restart needed. A rebuild fires within debounceMillis of any change trigger, or you can force one immediately by reloading BlueMap.

Upgrading from an older layout. An older flat config/wnbluemap-server.toml (pre-1.x layout) is moved to the path above automatically on first boot after upgrading, settings intact. A few individual keys that were renamed in place for terminology cleanup (features.territory to features.claims, war.territoryTintMix to war.claimsTintMix, labels.territory to labels.claims) are carried over the same way, so an upgrading server never silently loses a customized value to a stale key name.

[features] - layer toggles

Each layer can be switched off independently. Turning a layer off skips its rendering work entirely, not just hiding it in the web app, so a disabled layer costs nothing.

Key

Default

Effect

claims

true

Draw the Nations layer (each nation's claimed territory).

warOverlay

true

Draw the Active Wars layer (contested frontline, plus siege rings/keep/objectives when a war has them).

diplomacyLines

true

Draw the Diplomacy layer's alliance lines.

diplomacyLinesDefaultHidden

true

Diplomacy layer starts hidden in the web app (viewers toggle it on themselves).

rivalryLines

true

Also draw rivalry (standing-enemy) lines in the Diplomacy layer, alongside alliances. Requires diplomacyLines.

villages

true

Draw the Villages layer.

[style] - territory appearance and ground-height sampling

Controls border walls, ground tint, ground-height scanning, and the flat-shape fallback used on maps with no 3D view.

Key

Default

Effect

borderWallHeight

Height in blocks of each terrain-following border wall panel.

borderSampleSpacing

Resample ground height every N blocks along a border; consecutive same-height samples merge into one longer panel.

borderThickness

0.5

Wall panel thickness in blocks, centered on the true chunk boundary.

borderOpacity

0.85

Border wall fill opacity.

tintEnabled

true

Draw the flat, depth-tested ground tint over each nation's whole claimed area.

tintOpacity

0.30

Tint fill opacity. Kept low since, unlike the border walls, it covers the whole claim, not just its edge.

tintHeightOffset

1.0

Blocks of clearance above sampled ground height the tint sits at. Needs real clearance (0.1 measured invisible from directly overhead) to reliably win BlueMap's depth test.

maxSurfaceScanDepth

Cap on how far the ground-height scan walks down looking for the first opaque/fluid block, bounding worst-case per-sample cost instead of scanning the full world column.

depthTest

false

false lets borders show through terrain from an angle; true hides them behind it.

fillOpacity

0.30

Flat-shape fill opacity, used only on a flat-only map as the border-wall/tint fallback.

lineOpacity

0.80

Flat-shape border-line opacity, same flat-only fallback as fillOpacity.

lineWidth

Flat-shape border-line width in pixels, same flat-only fallback.

shapeMinY

Bottom Y of the war-frontline overlay's extruded slab.

shapeMaxY

Base world Y most other non-terrain-hugging layers place themselves at (frontline slab top, siege rings, objective markers, diplomacy lines, village territory, and the flat-only territory fallback).

fullRebuildEvery

500

Force a full, uncached recompute of every nation's territory every this many rebuild passes (not triggers), pure insurance against an unknown cache-invalidation gap.

Flat-only maps. If a BlueMap map has both enable-perspective-view and enable-free-flight-view set to false in its own config (only ever rendering the flat top-down view), this addon detects that and skips terrain-following border walls and ground-height tint sampling for that dimension entirely, drawing one flat shape per region instead, styled by fillOpacity/lineOpacity/lineWidth/shapeMinY/shapeMaxY above. A dimension is only treated as flat-only if every BlueMap map rendering it has both settings disabled; a mix of flat-only and 3D-capable maps still builds the full terrain-following version.

[war] - active-wars layer and diplomacy line color

Colors and opacities for the frontline, alliance lines, and rivalry lines.

Key

Default

Effect

colorRgb

0xFF3030

Frontline color.

lineWidth

Frontline border-line width in pixels.

fillOpacity

0.45

Frontline fill opacity.

lineOpacity

0.90

Frontline border-line opacity, kept separate from fillOpacity so the outline stays bold even while the fill is faint.

claimsTintMix

0.55

How strongly colorRgb blends into an at-war nation's own territory color (walls + tint), 0 = nation keeps its normal color even at war, 1 = fully war-red. At the default, an at-war nation's territory reads as roughly half its own color, half war-red.

allianceColorRgb

0x30FF60

Alliance-line color.

rivalryColorRgb

0xFF9A30

Rivalry-line color, deliberately not the war color, since a rivalry is a standing diplomatic posture that may never come to blows.

allianceLineWidth

Alliance-line width in pixels.

rivalryLineWidth

Rivalry-line width in pixels, thinner than an alliance's by default.

diplomacyLineOpacity

0.85

Opacity shared by both alliance and rivalry lines.

[villages] - village territory styling

Kept fainter than nation territory by default, so a village never reads as visually louder than the land it sits inside or next to.

Key

Default

Effect

fillOpacity

0.22

Village fill opacity.

lineOpacity

0.70

Village border-line opacity.

lineWidth

Village border-line width in pixels.

[siege] - wall rings, keep, and objective site markers

Independently tunable from the generic frontline color, since siege-ring/keep/objective geometry is real per-chunk shape data, not just "contested territory", so it reads better as its own visual family. See war presets for what a siege actually is.

Key

Default

Effect

ringColorRgb

0xFFA030

Color for a standing (not-yet-fallen) wall ring or the keep chunk.

ringFallenColorRgb

0x707070

Color for a fallen wall ring. Fallen rings stay drawn, just visually demoted to this duller color, so overall siege progress is still readable at a glance.

keepColorRgb

0xFFD060

Color for the keep chunk itself, distinct from a wall ring's own color so the attacker's actual win condition always stands out regardless of ring state.

ringFillOpacity

0.35

Fill opacity for a standing ring or the keep.

ringFallenFillOpacity

0.18

Fill opacity for a fallen ring, lower so it visibly recedes without vanishing.

ringLineOpacity

0.85

Border-line opacity shared by standing/fallen rings and the keep.

ringLineWidth

Wall-ring/keep border-line width in pixels.

objectiveColorRgb

0x30C0FF

Color for an objective's site marker.

objectiveFillOpacity

0.40

Objective site marker fill opacity.

objectiveLineOpacity

0.90

Objective site marker border-line opacity.

objectiveLineWidth

Objective site marker border-line width in pixels.

objectiveMarkerRadiusBlocks

Half-width in blocks of the small square drawn at an objective's site chunk center, kept well inside one 16-block chunk so it reads as a point marker, not a whole-chunk fill.

[labels] - marker-set display names

Renames a layer's entry in the BlueMap web app's layer list. Has no effect on the stable internal marker-set id that a bookmarked/embedded ?markers= URL depends on.

Key

Default

claims

"Nations"

war

"Active Wars"

diplomacy

"Diplomacy"

villages

"Villages"

Controls how much roster and relation detail shows before a territory popup collapses the rest.

Key

Default

Effect

rosterDisplayLimit

Member names shown on a nation's territory popup before collapsing the rest into a "+N more" line. Only limits what's displayed; the member count shown alongside is always the real total.

relationDisplayLimit

Allies (and, separately, enemies) named before collapsing into "+N more".

[discord] - optional wndiscord bridge

Has no effect at all if wndiscord isn't installed.

Key

Default

Effect

channelKey

"bluemap"

Logical channel key registered with wndiscord's bridge. Must be routed to a real Discord channel in wndiscord's own config ([channels].extra, e.g. bluemap=<channelId>).

warNotifications

true

Post to that channel when a war starts/ends, a siege ring falls/is relieved, a siege enters keep-hold, a village-conquest siege starts/lifts, or a preset application changes a nation's configuration. One toggle covers every event type above.

[behaviour] - pacing, dimensions, deep links

Controls rebuild pacing per tick, which dimensions get maps drawn, and the public URL used to build Discord deep links.

Key

Default

Effect

debounceMillis

1500

Quiet period (ms) after the last change before a rebuild starts, so a burst of events collapses into one redraw.

nationsPerTick

Nations whose claim geometry is (re)computed and whose regions are queued, per server tick.

wallRegionsPerTick

Border-wall building, paced per connected claimed region (not per nation).

tintCellsPerTick

150

Ground-height tint sampling, paced per claimed chunk.

tintGroupsPerTick

200

Tint polygon building, paced per merged same-height plateau, once sampling for a nation finishes.

villagesPerTick

Village territory, paced per whole village (villages need no ground-height scanning, so one queue is enough).

dimensionMode

"ALL"

ALL, INCLUDE (only dimensionList), or EXCLUDE (all but dimensionList).

dimensionList

"minecraft:the_nether,minecraft:the_end"

Comma-separated dimension ids used by INCLUDE/EXCLUDE.

mapWebRootUrl

Your public BlueMap URL (e.g. https://map.example.com), used to build deep links for Discord notifications. Blank disables deep links.

[metrics] - anonymous usage statistics

Controls bStats reporting for this addon specifically.

Key

Default

Effect

enabled

true

Send anonymous, aggregate bStats metrics (player/server count, OS/Java version, which overlays are enabled). No player names, UUIDs, IPs, or server addresses are ever collected. Independent of bStats' own shared, cross-mod opt-out file, either one off is enough to stop reporting.