Player Map Layers

Player Map Layers keeps one cartography layer per platform account, while always showing the current character name in the interface. Players can preview one or several layers before importing them, isolate one player's map, avoid reapplying the same revision and undo the last import.

Public beta 0.2.13. The same version must be installed on the server and on every participating client.

Current features

• Server-authoritative layer storage, separated by world.
• Stable account identity derived by the server; raw platform identifiers are never sent to other clients.
• Current character name displayed in the UI and previous character names retained only as metadata.
• A successful Record discoveries action uploads only the player's personal exploration mask, never pins or mod markers.
• A successful Read map action is intercepted non-destructively:
  1. the original personal/shared exploration masks and live pin references are captured;
  2. Valheim reads the table normally;
  3. the resulting shared exploration mask is captured independently from personal progress;
  4. the original exploration masks are restored and only pins added by the read are removed through Valheim's normal pin lifecycle;
  5. the player chooses whether to apply the preview.
• Rapid isolation of a single player's layer.
• Multi-layer temporary preview.
• The local player's current personal exploration is represented by their normal account/character row; Shared table exploration remains independently selectable, with a one-click preview of their exact union.
• Explicit Apply / Cancel controls.
• One-level import rollback, also persisted locally for recovery after a restart.
• Revision and SHA-256 fingerprint tracking to avoid reapplying an unchanged layer.
• Player-selected named color and built-in emblem, accepted and synchronized by the server.
• Selecting a player color or emblem synchronizes it immediately; cached previews refresh when the server returns the accepted identity.
• Pins are private by default and can be shared individually from the Shared pins tab.
• Every explicitly shared pin can use its original icon or a compatible BetterMap icon such as pickaxe, chest, portal, forage, dungeon, beehive, tar or sap; its original semantic identity remains unchanged for duplicate protection.
• Temporary pins synchronized through Player Map Layers receive an optional relief halo in their author's server-accepted color without recoloring the icon itself.
• Valheim's native Cartography table switch is the master on/off control for native and Player Map Layers shared pins.
• Player Map Layers remote pins can be filtered locally: all players, selected players, or none. Native, BetterMap and TargetPortal pins remain controlled by their original systems.
• Player Map Layers renders remote pins temporarily and removes semantic duplicates instead of importing them into the local map.
• Active exploration previews use each player's server-accepted color at low opacity.
• Player-color saturation is independently adjustable from 100% to 250%, with a stronger 180% default.
• Player-only areas default to 8% opacity, the shared-table-only background to 3%, and multi-player overlaps to one neutral 1.5% veil; the table never neutralizes a player's color and colors are never alpha-stacked.
• Identity and exploration-color details use collapsible sections, and the identity palette includes purple, turquoise, lime and white in addition to the original color-blind-friendly choices.
• The exploration tint is a temporary local UI layer and never enters fog data, map saves or network payloads.
• Opening the normal large map with Valheim's configured Map action starts the layer session with the full panel collapsed. Use Filter / Filtre to open it; Close / Fermer collapses it again without cancelling the active preview.
• Reading a cartography table still opens the large map and the full panel automatically so the received layer can be reviewed immediately.
• Layer checkboxes update the map immediately. The exact combination—local player, shared table and any remote players—is remembered per world and local character and restored whenever the map reopens.
• The latest shared-table snapshot actually read by the player is persisted locally per world and character, so a remembered table selection survives a game restart without changing the saved map.
• Me + table, All and None are selection presets. Permanent import is kept in a separate advanced section because it is not required for a remembered view.
• French UI when Valheim is in French; English otherwise.
• No separate global keyboard shortcut: the mod follows Valheim's configured Map action, including AZERTY layouts and remapped controls.
• Mouse clicks and wheel input over the mod window are consumed before Valheim's map can create, remove or move pins underneath it.
• The menu adapts to the current resolution and UI scale. On shorter displays, a global vertical scrollbar keeps every control accessible; palettes and pin rows also reflow on narrow windows.
• Existing vanilla, BetterMap and TargetPortal pin objects are never cleared or rebuilt after a cartography read, preventing detached screen-space pin graphics.
• Personal preferences, remembered selections, shared-table snapshots and import recovery files live under Valheim's per-Windows-user LocalLow directory. Gale profile synchronization therefore distributes the mod and server policy file without cloning one player's interface or identity preferences to subscribers.

Compatibility policy

BetterMap

BetterMap remains the owner of its pins and icons. Player Map Layers discovers BetterMap's active icon types at runtime and only references a chosen type for temporary shared-pin rendering; it does not register replacement types, recolor BetterMap pins or duplicate portal markers. Player layers, preview baselines and undo points contain exploration bits only; no full serialized map is restored over the current pin collection.

TargetPortal

Player Map Layers does not patch TeleportWorld, does not use P and does not move portal pins. It auto-opens only when the player uses Valheim's configured Map action, so TargetPortal's programmatic destination map remains independent.

SimpleAccessControl

SimpleAccessControl remains responsible for permission checks on the cartography table. Player Map Layers only reacts when Valheim's original OnRead handler was allowed to run, or after a successful OnWrite, and does not consume Shift + Use, Shift + A or Shift + Q.

Installation

Player Map Layers is distributed as a standard Thunderstore package. BetterMap, TargetPortal and SimpleAccessControl are optional integrations, not required dependencies.

Gale (recommended)

1. Open the Valheim profile that will use the mod.
2. Search for PlayerMapLayers in Gale.
3. Select Download, then keep the mod enabled in the profile.
4. Repeat this for every participating client and install the same package version on the server.
5. Launch the game through Launch modded.

No compiler, development archive or manual installer is required for normal players. Updates are delivered through Gale like any other Thunderstore mod.

Dedicated servers

Install the same Thunderstore package version in the server's Valheim/BepInEx profile. Restart the server after installation or update. Player layers and explicitly shared pins are stored server-side and remain separated by world.

Usage

1. Build a vanilla cartography table.
2. Use Record discoveries to upload or update your personal layer.
3. Use Read map on the cartography table, or open the large map and select Filter / Filtre.
4. Select any combination of your account row, remote players and Shared table exploration. The view updates immediately and the combination is remembered.
5. Use Me + table, All or None for quick selection, or Solo beside a layer.
6. Only open Permanent import when discoveries must be copied into the saved shared map. Use Undo last import if needed.

Selective pin sharing

1. Open the large map and select Shared pins.
2. Check only the personal saved pins that should be shared.
3. Choose the display icon with the arrows beside each pin, then select Synchronize checked pins. Unchecked pins remain private; unchecking a previously shared pin removes it from the server list on the next synchronization.
4. Keep Valheim's native Cartography table switch enabled to see shared pins.
5. Choose All, Players, or None. These filters affect only pins synchronized through Player Map Layers; the Players filter exposes one checkbox per remote account.

System markers and temporary pins are never offered for sharing. If BetterMap or TargetPortal already owns an equivalent marker at the same position, its native marker is retained and Player Map Layers does not draw a duplicate.

Identity

Internally, the server maps the authenticated platform account to a salted UUID. The UI never shows that UUID. It displays the latest character name seen for the account.

Several characters using the same platform account therefore keep the same color, emblem and ownership. Each submitted character name remains available internally for diagnostics and migrations.

Configuration

Server and shared technical settings remain in the Gale/BepInEx profile:

BepInEx/config/zephyrfit.playermaplayers.cfg

These settings include:

• Enabled = true
• AllowIdentityChanges = true
• EnableGroupSharing = false
• MaximumLayerSizeKb = 4096
• DetailedLogging = false

Personal client settings are stored outside Gale's synchronized profile:

%USERPROFILE%/AppData/LocalLow/IronGate/Valheim/PlayerMapLayers/client-preferences.cfg

They include:

• PreviewBeforeImport = true
• UploadOnCartographyWrite = true
• PreferredColor = #56B4E9
• PreferredEmblem = Compass
• RemotePinFilter = All
• AuthorColorHalos = true
• Exploration overlay.Enabled = true
• Exploration overlay.SinglePlayerOpacity = 0.08
• Exploration overlay.SharedTableOpacity = 0.03
• Exploration overlay.OverlapOpacity = 0.015
• Exploration overlay.ColorSaturation = 1.8
• Interface.ParchmentTheme = true

Remembered layer combinations, shared-table snapshots, import ledgers and undo data are stored below the same LocalLow/PlayerMapLayers/client/ root. They are never included in Gale profile sync. When upgrading from 0.2.11, files belonging to the current local character are migrated out of BepInEx/config; the accepted color and emblem are restored from the server-authoritative account profile.

The parchment theme is generated locally, scales with the window and ships without an external UI dependency. Set ParchmentTheme = false to restore the classic Valheim IMGUI theme.

Group sharing is reserved behind EnableGroupSharing = false; no group menu is displayed while it is disabled.

Server data

Server layers are stored per world under:

BepInEx/config/PlayerMapLayers/world_<world UID>/layers/

Explicitly shared pin lists are stored separately under world_<world UID>/pins/. They never enter exploration payloads or local map saves.

Clients still submit their personal exploration, chosen identity and explicitly shared pins through validated RPC messages. The server resolves the authenticated account, stores the accepted data and redistributes the layer and pin indexes to participating clients. Moving client preferences to LocalLow does not change this network workflow.

The server also returns the requesting player's own salted UUID privately in the layer index. This lets the client recognize its account after a character-name change without displaying or transmitting the raw Steam/PlayFab identifier. Existing PML4 layer files remain compatible with 0.2.13.

Writes are atomic and preserve a .bak copy of the previous layer.

Roadmap

• Optional accessibility initials or patterns, disabled by default and designed to avoid map clutter.
• Optional per-category pin filters and a dedicated legacy-table pin category.
• Optional internal group sharing, hidden by default.

Support

Discord: @zephyrfit
User ID: 251341133085540352

When requesting support, attach BepInEx/LogOutput.log and specify the Valheim, Player Map Layers, BetterMap and TargetPortal versions.