BetterMapCleanup 0.5.2

Companion cleanup/lifecycle mod for BetterMap 1.0.x.

0.5.0 changes the multiplayer architecture substantially: normal gameplay no longer runs BetterMapCleanup's own periodic resource-world reconciliation. Resource discovery piggybacks BetterMap's existing AutoPins sweep, while multiplayer depletion/respawn state is authoritative on a BetterMapCleanup-enabled server and distributed as compact event deltas.

Core features

• Remove saved BetterMap auto-pins whose effective rule is disabled.
• Re-apply BetterMap Merge Distance to existing saved pins.
• Same-resource merge labels such as Obsidian x4 and lifecycle count reduction.
• Configurable resource depletion threshold (default 90%).
• Per-resource CrossOff / Remove actions.
• Dedicated-server resource-state synchronization and persistence.
• Portal pin removal when a portal is dismantled/destroyed.
• Conservative orphan portal cleanup in confirmed-loaded areas.
• Conservative BetterMap PinRecord repair.
• Mistlands Soft Tissue BetterMap rule without BetterMapFix.
• Console maintenance/status commands.

0.5.2: server-authoritative configuration

BetterMapCleanup can now mirror BetterMap's server-config behavior without requiring BetterMap on the server. Put the same BetterMapCleanup DLL on the server and clients. The server can then make the synchronized BetterMapCleanup gameplay settings authoritative for every connected BetterMapCleanup client.

Server controls:

[1 - ServerSync]
Enable Server Config Sync = true
Lock Configuration = true

When enabled, a joining client receives the server's active BetterMapCleanup settings. The override is in-memory for the current connection: the client's local .cfg file is not rewritten, and its previous local values are restored after disconnect. With Lock Configuration = true, attempts to change synchronized settings client-side are immediately restored to the server value. Server-side changes are broadcast to already connected BetterMapCleanup clients.

Synchronized settings are the gameplay/cleanup policy: cleanup behavior, merge labels, portal cleanup, PinRecord repair, resource depletion tracking, resource sync enablement, respawn restoration, depletion threshold/action, every per-resource action, Soft Tissue, and Giant Remains. Local diagnostics/maintenance settings (Debug, Cleanup Now, manual reconcile compatibility settings, registry persistence and scan interval) stay client-local.

The config-sync channel is independent of Resource State Sync. A server can therefore still push BetterMapCleanup policy even if Resources > Server Resource Sync is disabled.

0.5.0: event-driven resource architecture

Why this changed

Previous 0.4.x builds attempted to reconcile loaded resources periodically. Even after replacing global Unity searches with a cache, that still meant BetterMapCleanup repeatedly walking resource/member/map state during gameplay.

BetterMap itself does not solve auto-pin discovery that way. Its AutoPins system sweeps the objects Valheim already has loaded and uses its PinRecord history to decide whether to place a pin. BetterMapCleanup now observes that existing discovery path instead of launching another automatic client scan.

Client discovery

On a normal client with BetterMap:

BetterMap AutoPins sweep
    -> BetterMap considers an Ore rule/resource candidate
    -> BetterMapCleanup observes rule + prefab + position
    -> member registry is updated
    -> BetterMap continues its normal pin/PinRecord logic

When a BetterMap sweep learns new same-resource members, BetterMapCleanup can refresh <Resource> xN after that same sweep. There is no scheduled BetterMapCleanup world-object scan.

Server-authoritative multiplayer state

Install the same BetterMapCleanup DLL on the dedicated/listen server. BetterMap itself is not required on the server.

The server patches Valheim's actual Destructible, MineRock5 and MineRock mutation paths. Once a tracked resource crosses the configured depletion threshold, the server stores one state transition and sends a compact delta to connected BetterMapCleanup clients:

canonical prefab + position + depleted true/false

The mining player's client is not trusted as the authoritative source. This means the player causing the depletion does not need BetterMapCleanup for the server to observe the world-state change; BetterMapCleanup only needs to be installed on the server and on clients that want their BetterMap pins synchronized.

A remote client with confirmed server support stops doing its old local damage/ZDO recheck coroutines and applies server deltas instead.

Offline/reconnecting players

The server persists resource transitions per world. On join, a BetterMapCleanup client requests a snapshot. Snapshot application is sliced to a small number of records per frame, and the local registry is written once after the queue drains rather than once per record, reducing reconnect hitch risk.

No BetterMapCleanup on the server

The mod remains usable:

• Singleplayer: local lifecycle hooks handle the local player's actions.
• Multiplayer client on an unmodded server: local lifecycle fallback still handles events the client can actually observe.
• Changes made by distant players while the client is absent cannot be guaranteed without server authority.
• bmc reconcile remains available as an explicit manual repair tool; it never runs automatically in 0.5.0.

OdinEye design lesson

The 0.5.0 split follows the useful architectural principle demonstrated by OdinEye/OdinEyeClient: keep data the server can authoritatively know on the server, and use the client only for client-specific information/UI. BetterMapCleanup does not copy OdinEye's HTTP/WebSocket transport; Valheim's in-game ZRoutedRpc is a better fit for small peer state deltas.

Resource lifecycle

Default threshold:

[Resources]
Track Depletion = true
Depleted At Percent = 90
Depleted Pin Action = CrossOff
Server Resource Sync = true
Persist Resource Registry = true
Restore Respawned Resources = true

Legacy config entries Reconcile Loaded Resources and Reconcile Interval are retained for compatibility/manual repair, but no automatic periodic reconciliation uses them in 0.5.0.

Built-in actions:

[Resources - Actions]
Copper Deposits = CrossOff
Tin Deposits = Remove
Muddy Scrap Piles = Remove
Silver Deposits = CrossOff
Obsidian Deposits = Remove
Giant Remains = CrossOff
Soft Tissue = Remove
Flametal = CrossOff
Unstable Lava Rock = Remove
Leviathans = CrossOff

CrossOff sets the normal Valheim checked state. Remove removes the visible pin while preserving/recreating BetterMap PinRecord suppression so a still-present final <=10% does not immediately recreate the pin.

Large resources that transition from a Destructible wrapper to a fractured MineRock5 continuation are normalized back to the original BetterMap resource. Wrapper destruction itself is not treated as depletion.

Respawn recovery

No guessed background timer is used.

• Server: if a previously depleted tracked resource actually instantiates again and its authoritative health shows it active, the server stores depleted=false and broadcasts it.
• Client: BetterMap's own AutoPins candidate observation can also prove that a known depleted member is alive again and release local suppression before BetterMap completes its normal Place operation.

Vanilla finite ores generally do not respawn; the mechanism mainly supports resources/mods that genuinely recreate the tracked object.

Merge labels

With Cleanup > Show Merge Counts = true, same-resource members inside Merge Distance can be represented as:

Obsidian x4

When one represented node depletes:

Obsidian x4 -> Obsidian x3

Different Ore rules are never combined just because both use the Ore category.

Server installation

See SERVER.md.

Client build/install:

.\build.ps1 -Install

The same built BetterMapCleanup.dll can be copied to the server's BepInEx/plugins/BetterMapCleanup/ folder.

Console commands

bmc status
bmc cleanup
bmc reconcile
bmc repair
bmc sync
bmc registry [N]
bmc help

• bmc status: runtime/server-sync/registry diagnostics.
• bmc cleanup: disabled pins + merge normalization + orphan portals + PinRecord maintenance.
• bmc reconcile: manual-only legacy resource repair pass against the small loaded-resource cache.
• bmc repair: PinRecord repair.
• bmc sync: request a fresh server snapshot.
• bmc registry [N]: inspect local tracked members.

A connected multiplayer client should report roughly:

serverSync=connected, protocol=3
configSync=connected/locked/0.5.2, configProtocol=1
clientReports=disabled
localLifecycle=server-deltas
automaticReconcile=disabled(event-driven)
BetterMapObservation=hooked

Explicit non-goals

• No special lifecycle implementation for Sulfur Arches or Frozen Trolls.
• No continuous full-world or loaded-world scan on clients.
• No HTTP/WebSocket service; synchronization stays inside Valheim networking.

Current testing status (0.5.2)

The current feature scope is implemented and ready for broader gameplay testing. The following areas still need more long-running real-world validation:

• merged resource labels/counts, especially Tin;
• full Remove / CrossOff lifecycle behavior across resource types;
• PinRecord repair with deliberately missing or duplicate records;
• full depletion -> respawn -> restored-pin lifecycle;
• long-running dedicated-server behavior with multiple clients;
• reconnect, world-reload and synchronization timing edge cases.

Please report duplicate pins, pins that fail to disappear or return, incorrect merge counts, sync issues, or relevant BepInEx log errors.