Joey's Wayfinder

Author: JoeyBadManners
Version: 1.1.1

Joey's Wayfinder is a client-side map, discovery, and navigation overhaul for Valheim. It keeps the vanilla world intact while giving you a persistent, searchable Wayfinder layer for things you actually discover: resources, structures, spawners, traders, portals, vehicles, runestones, enemy sightings, graves, and your own custom pins.

The goal is to make Valheim's map dramatically more useful without turning it into a global reveal or requiring a server-side mod.

What's new in 1.1.1

Version 1.1.1 fixes a recurring 0.5-1.0 second frametime hitch reported on Valheim 1.0.12 and prevents Pin Manager text entry from leaking controls into gameplay.

• High-frequency input patches no longer request an allocated argument array on every Valheim input poll.
• Closed-map UI discovery no longer performs global Unity UI searches every 0.75 seconds.
• Boat, cart, and portal updates now consume lifecycle-fed registries instead of repeatedly searching the entire loaded scene.
• Structure/runestone registry snapshots no longer resynchronize every loaded location during each scan.
• The global Enabled=false setting now suspends all recurring Wayfinder runtime and UI work.
• The open Pin Manager now acts as a modal interface: search, rename, icon/type search, and boss-name fields receive typing without also moving the character, triggering actions, changing hotbar slots, or closing the map.

These changes do not alter Wayfinder's .wfd schema, saved marker identities, client-only networking model, or Valheim world saves.

The frametime correction was confirmed with a controlled A/B retest using the same server, world, and mod stack that reproduced the hitch in 1.1.0. The Pin Manager input correction was also confirmed in-game on Valheim 1.0.12.

Previous 1.1.0 fix

Version 1.1.0 updates Wayfinder for Valheim 1.0.7 and fixes the persistent random/duplicate portal-marker bug.

• A portal must now be a loaded, enabled TeleportWorld with a valid vanilla ZNetView and ZDO before Wayfinder will record it.
• The ZDO position is authoritative and must agree with the loaded scene object, preventing half-initialized or recycled objects from writing bogus coordinates.
• A stable ZDO identity is paired with a precise position alias, so repeated scans, relogs, portal renames, and link-state changes update one record.
• Destroyed portals are removed by their network identity, with a conservative position fallback.
• Old position-only portal records are preserved but hidden until a real portal confirms them. This prevents corrupt markers from returning while allowing legitimate legacy records to recover in place with their user metadata intact.
• Portal diagnostics are available through DebugLogging; they are disabled by default.
• Valheim 1.0's renamed map right-click path is handled without making the Harmony patch set fail at startup.

The previous 1.0.1 trader-position correction remains included.

Previous 1.0.1 fix

Version 1.0.1 fixes confirmed trader marker positioning. In 1.0.0, a confirmed Haldor, Hildir, or Bog Witch marker could end up at the generated trader-camp origin instead of the position used by Valheim's native trader pin.

• Confirmed trader markers now use Valheim's native trader pin position as the authoritative location when available.
• If the native pin is not available yet, the loaded trader's actual world position is used as the fallback.
• Generated trader-camp centers are used only for possible/candidate trader camp markers before a trader is confirmed.
• Existing 1.0.0 confirmed trader records automatically self-correct in place when the proper native trader pin is observed.
• The correction preserves the existing Wayfinder record, including favorites, tracking state, custom names, icon overrides, notes, and other user-owned metadata. No database reset or manual pin recreation is required.

Highlights

• Client-side only. No dedicated-server installation is required.
• Per-world persistent Wayfinder database with safety backup/recovery and world isolation.
• Searchable Pin Manager built into the large map.
• Create, rename, favorite, delete, filter, and edit pins without relying on Valheim's old persistent-pin strip.
• Full visual icon picker for new and existing pins, including persistent user icon overrides and a real Default reset.
• Up to 5 tracked targets with a custom horizontal compass and optional world-space beacon beams.
• Custom Wayfinder art for supported map pins while preserving the underlying vanilla pin data where appropriate.
• Resource clustering with connected same-resource groups and optional cluster counts.
• Generated structure / POI / dungeon remembrance after legitimate discovery.
• Physical spawner remembrance, including dedicated spawner art and sighting suppression around known spawners.
• Optional ordinary enemy-sighting hotspots with enemy-specific trophy art when available.
• Runestone, Vegvisir, boss-guidance, and trader handling with special-case cleanup to avoid noisy or misleading pins. Confirmed trader markers align to Valheim's native trader-pin positions; generated camp centers remain candidate-only locations.
• Portal remembrance with tag/name syncing and deliberate deletion protection from accidental map right-clicks.
• Boat and cart remembrance using stable network identities, live position updates while loaded, and clear last-known state when unloaded.
• Gravestone visual replacement that keeps the native death-pin persistence underneath and removes the marker only when the physical grave is actually gone.
• Optional expanded map-exploration multipliers.
• Budgeted discovery work and lifecycle-fed registries designed to avoid repeated scene-wide scans in normal play.

Multiplayer behavior

Wayfinder does not add its own networking layer. It observes Valheim's normal networked objects locally and stores Wayfinder data on each player's machine.

That means:

• The server does not need Joey's Wayfinder installed.
• Other players do not need the mod for you to use it.
• Wayfinder pins, filters, favorites, tracking state, and icon overrides are local to each player.
• Wayfinder does not automatically share discoveries between players.
• Moving boats/carts are updated while that same networked object is loaded on your client. If it leaves your loaded range, Wayfinder keeps its last known position until your client observes it again.

Discovery philosophy

Wayfinder is intentionally conservative by default. It remembers things you legitimately interact with or encounter instead of revealing an entire world from nowhere.

Automatic surrounding-area resource scanning is off by default, enemy sightings are off by default, unexplored-fog scanning is off by default, and buried Silver remains interaction-only even if area scanning is enabled.

Pin Manager

Open the large map and use the Wayfinder controls to manage your pins. The default fallback shortcut is F7 while the large map is open.

The manager supports:

• Search and category filters
• Manual pin creation at your position or by placing on the map
• Favorites
• Rename / delete
• Full searchable icon selection
• Default-icon reset
• Tracking slots T1-T5
• Category visibility controls
• Boss-label overrides
• Modal gameplay-input suppression while the manager is open, so all editable fields can be used without controls passing through to Valheim

Compass and tracking

The Wayfinder compass is enabled by default. Explicitly tracked pins remain available at practical world-scale distances and can be shown with live distance, optional names, offscreen edge clamping, and world-space beacon beams.

Tracking is separate from deletion and from Valheim's normal middle-mouse map ping.

Configuration

The generated config file is:

BepInEx/config/com.joeybadmanners.wayfinder.cfg

Most players can leave the defaults alone and use the in-map Pin Manager for ordinary map behavior. Important config groups include:

• 00 - General — enable/disable, debug logging
• 10 - Map — visual replacement, map removal behavior, boss pin scale
• 11 - Pin Manager — F7 fallback key, compact map controls, hidden categories, boss labels
• 20 - Discovery — clustering, interaction discovery, optional area scanning, sightings, dungeon-content scanning
• 21 - Resource Filters — intentionally noisy basic resources such as Stone/Branches/Flint/Dandelions
• 22 - Structures — generated structure discovery
• 23 - Spawners — physical spawners and sighting suppression
• 24 - Portals — portal discovery, tag syncing, names, destruction cleanup
• 30 - Compass — compass display and tracked-pin limit
• 40 - Waypoint — tracked-target beacon behavior
• 50 - Vehicles — boats/carts, live updates, last-known state
• 60 - Exploration — optional exploration-radius multipliers
• 90 - Performance — scan intervals, persistence batching, and visual refresh timing

Debug logging is off by default. VerboseRuntimeLogging only has an effect when DebugLogging is also enabled.

Installation

Mod manager

Install Joey's Wayfinder through Thunderstore/r2modman. BepInExPack Valheim should install automatically as its required dependency.

Manual

1. Install BepInExPack Valheim.
2. Put JoeyBadManners.Wayfinder.dll in a folder under BepInEx/plugins/.
3. Launch Valheim once to generate the config and Wayfinder data folders.

No server-side installation is required.

Required dependency

• denikson-BepInExPack_Valheim-5.4.2350

Data and backups

Wayfinder keeps per-world data under your BepInEx config area in a JoeysWayfinder/worlds folder. World databases use .wfd files and maintain a .bak safety copy for recovery.

Removing the mod does not alter or delete your Valheim world. Wayfinder's remembered data is separate from the world save.

Compatibility / design notes

Joey's Wayfinder is designed to coexist with normal Valheim networking by reading locally available game state rather than introducing a custom server protocol. Vanilla map data is preserved where Wayfinder is only replacing presentation, such as supported native boss/death-pin visuals.

If another map mod heavily replaces the same Minimap UI, pin lifecycle, or map input methods, visual or interaction conflicts are possible.

Support

If you enjoy my mods and want to support what I make, you can find me on Ko-fi:

https://ko-fi.com/joeybadmanners

Developed by JoeyBadManners with assistance from ChatGPT by OpenAI.

Verification status

Version 1.1.1 was compiled against the installed Valheim 1.0.12 Windows assemblies and BepInExPack Valheim 5.4.2350. Harmony targets and client-only dependencies were statically audited. A controlled same-environment A/B retest confirmed that the recurring hitch from 1.1.0 is eliminated, and local in-game testing confirmed Pin Manager input suppression. Continued regression testing and the multiplayer/vanilla-client checks in TEST_PLAN.md are still recommended.

License

MIT License. See LICENSE.