WindheimShips
Version 0.1.0 | BepInEx mod for Valheim | Requires Jotunn
Per-player ship management. Assign a Flagship and a Boat, recall either from anywhere in the world with a single keypress, and track both on the minimap at all times.
Features
- Flagship slot — take any ship's helm to claim it as your Flagship. Supports Raft, Karve, Longship, Drakkar, and all OdinShip vessels.
- Boat slot — a persistent secondary vessel (default Raft) that is indestructible, costs nothing to recall, and stores itself between sessions so it never clutters the world.
- Recall from anywhere — press the recall key to open the Fleet panel. One click teleports your ship to a valid water position near you, even from unloaded zones.
- Minimap pins — Flagship and Boat are always visible on both the minimap and large map. Flagship uses the hammer icon; Boat uses the pin icon. Colors are configurable.
- Persistent fleet data — ship assignments survive world restarts, character swaps, and server restarts via ZDO storage.
- OdinShip compatible — all seven OdinShip vessels register with WindheimShips automatically.
- Multiplayer ready — per-player ownership tracked by stable profile ID. Each player manages their own fleet independently.
- Occupied ship handling — configurable behavior when another player is aboard: block the recall or force-recall anyway.
- Extensive configuration — nine config sections covering general behavior, fleet slots, recall mechanics, map pins, UI, persistence, compatibility, debug, and experimental features.
- Server-friendly — no client-only patches that break dedicated server sessions.
Installation
Via r2modman / Thunderstore Mod Manager (Recommended)
- Open r2modman and select your Valheim profile.
- Search for WindheimShips in the online package list.
- Click Install. Dependencies (BepInExPack, Jotunn) are installed automatically.
- Launch Valheim through r2modman.
Manual
- Install BepInExPack_Valheim and Jotunn.
- Download
WindheimShips-0.1.0.zip.
- Extract and copy
plugins/WindheimShips/Windheim.dll into BepInEx/plugins/WindheimShips/.
- Launch Valheim.
Server
WindheimShips runs on both client and server. Install the DLL in the server's BepInEx/plugins/ folder. Config sync is handled per-player via ZDO; no additional server-side setup is required.
Configuration
Config file: BepInEx/config/com.TAIJI.windheim.cfg
Generated automatically on first launch. Open in any text editor or use the BepInEx ConfigurationManager in-game.
General
| Setting |
Default |
Description |
| Enabled |
true |
Master switch. Set false to disable all features without uninstalling. |
| LogLevel |
info |
Log verbosity: none / error / info / debug |
| ShowWelcomeMessage |
true |
Print version info to BepInEx log on startup. |
Fleet
| Setting |
Default |
Description |
| EnableFleet |
true |
Enable the fleet system entirely. |
| EnableSecondaryShip |
true |
Enable the Boat slot. |
| DefaultSecondaryType |
Raft |
Prefab used when spawning a new Boat (Raft / Karve / VikingShip / Drakkar). |
| IndestructibleSecondary |
true |
Boat cannot be destroyed. |
| AutoAssignPrimaryOnHelm |
true |
Taking any helm auto-assigns it as Flagship. |
| OccupiedShipMode |
block |
What to do when recalling a ship occupied by another player (block / recall). |
| PersistFleetBetweenSessions |
true |
Save fleet assignments between game sessions. |
Recall
| Setting |
Default |
Description |
| EnableRecall |
true |
Enable the ship recall feature. |
| RecallKey |
K |
Hotkey to open the Fleet recall panel. |
| Cooldown |
3 |
Seconds between recalls. Range: 0–300. |
| RadiusMin |
10 |
Minimum summon radius in meters. Range: 5–50. |
| RadiusMax |
60 |
Maximum summon radius in meters. Range: 20–200. |
| MinDepth |
3 |
Minimum water depth required to place a ship. Range: 0.5–15. |
| ShowCooldownMessage |
true |
Show cooldown timer when recall is on cooldown. |
| ShowRecallMessage |
true |
Show confirmation message when a ship is recalled. |
Map
| Setting |
Default |
Description |
| ShowShipPins |
true |
Show ship pins on the minimap and large map. |
| ShowPinsOnMinimap |
true |
Show pins on the minimap. |
| ShowPinsOnLargeMap |
true |
Show pins on the large map. |
| PrimaryPinLabel |
Flagship |
Label for the Flagship pin. |
| SecondaryPinLabel |
Boat |
Label for the Boat pin. |
| UpdatePinsOnMove |
true |
Update pin positions as ships move. |
| PinUpdateInterval |
5 |
How often (in seconds) to update pin positions. Range: 1–60. |
UI
| Setting |
Default |
Description |
| EnableFleetUI |
true |
Enable the Fleet recall panel UI. |
| UIOpacity |
0.85 |
Panel background opacity. Range: 0.1–1.0. |
| UIScale |
1.0 |
Panel scale multiplier. Range: 0.5–2.0. |
| ShowShipType |
true |
Show ship type in the Fleet panel. |
| ShowShipDistance |
true |
Show distance to each ship in the Fleet panel. |
| AnimateOpen |
true |
Fade-in animation when opening the panel. |
| AnimationDuration |
0.20 |
Fade duration in seconds. Range: 0.05–1.0. |
Persistence
| Setting |
Default |
Description |
| SaveInterval |
30 |
How often (in seconds) fleet data is written to ZDO. Range: 5–300. |
| BackupSaves |
false |
Keep a backup copy of fleet data before overwriting. |
| MigrateOldSaves |
true |
Migrate legacy save data from older versions automatically. |
Compatibility
| Setting |
Default |
Description |
| MoreMapPins.Enabled |
true |
Enable compatibility layer for MoreMapPins. |
| FastTravel.Enabled |
true |
Enable compatibility layer for FastTravel mods. |
| FastTravel.TeleportWithShip |
false |
Teleport ship alongside player when using fast travel. |
| OdinArchitect.Enabled |
true |
Enable compatibility layer for OdinArchitect build pieces. |
| Jotunn.SyncConfigToClients |
true |
Sync server-side config values to connected clients via Jotunn. |
Debug
| Setting |
Default |
Description |
| EnableDiagnosticLogging |
false |
Verbose diagnostic output. Performance impact — development use only. |
| LogShipRegistration |
false |
Log each ship registration event. |
| LogZDOUpdates |
false |
Log every ZDO read and write. |
| LogPinUpdates |
false |
Log minimap pin changes. |
| EnableWorldScan |
true |
Allow world ZDO scan to recover stale ship references. |
| LogSaveLoad |
false |
Log persistence save and load operations. |
Experimental
| Setting |
Default |
Description |
| EnableAutoRecallOnSpawn |
false |
Automatically recall Flagship when player spawns. |
| EnableShipNaming |
false |
Allow players to assign custom names to their ships. |
| EnableShipHealthTracking |
false |
Show ship health percentage in the Fleet panel. |
| EnableExtendedFleet |
false |
Allow more than two fleet slots (requires MaxFleetSize). |
| MaxFleetSize |
2 |
Maximum number of ships in the fleet. Range: 2–10. |
| EnableDeathRecovery |
false |
Attempt to recover fleet data after player death. |
Compatibility
| Mod |
Status |
Notes |
| OdinShip |
✅ Compatible |
All 7 OdinShip vessels register automatically. |
| Sailing (Smoothbrain) |
✅ Compatible |
Speed and health bonuses apply normally. Recall bypasses movement entirely. |
| EpicLoot |
✅ Compatible |
No shared patch targets. |
| BetterUI / BetterUI_ForeverMaintained |
✅ Compatible |
No UI conflicts with Fleet panel. |
| AzuWearNTearPatches |
✅ Compatible |
Boat indestructibility is redundant when AzuWNT disables all boat damage — no conflict. |
| WhereYouAt |
✅ Compatible |
Map position sharing does not interfere with ship pins. |
| ProtectiveWards |
✅ Compatible |
Ships summoned inside a ward are protected by the ward's damage modifiers. |
| MoreMapPins |
⚠️ Planned |
Compatibility layer config exists; full integration not yet implemented. |
| Fast Travel mods |
⚠️ Planned |
Config option present; ship-along-player teleport not yet implemented. |
| BiomeLock |
⚠️ Known limitation |
BiomeLock's interact block may prevent helm interaction in restricted biomes. Ship pin updates from restricted biomes may be blocked. |
Mods not listed here will fall back to vanilla behavior. If WindheimShips cannot locate a Harmony method (e.g., ShipControlls.Interact vs TryInteract), it skips that patch gracefully via HarmonyPrepare.
Multiplayer
WindheimShips is designed for multiplayer from the ground up.
- Per-player ownership — each player's fleet is stored under their unique profile ID. Two players can claim different ships as their Flagship with no conflict.
- ZDO synchronization — ship positions and role flags are written to ZDOs, which Valheim automatically synchronizes across all clients.
- Ownership claim before write — WindheimShips claims ZDO ownership before writing recall positions, ensuring position updates propagate correctly in P2P sessions.
- Occupied ship protection — configure
OccupiedShipMode = block to prevent recalling a ship while another player is aboard.
- Config sync — with
Jotunn.SyncConfigToClients = true, server admins can enforce config values for all players.
FAQ
Q: I pressed K but nothing happened.
A: Make sure you're in-game (not in a menu). Check com.TAIJI.windheim.cfg and verify RecallKey is set to your preferred key. Also confirm EnableRecall = true.
Q: My ship says "not found" when I try to recall.
A: The ship's ZDO may have been invalidated (e.g., the ship was destroyed). For the Boat slot, WindheimShips will automatically spawn a replacement. For the Flagship, you need to assign a new ship by taking its helm.
Q: The Boat spawns inside terrain.
A: Increase RadiusMin slightly or move to an area with more open water before recalling. The water scanner requires MinDepth meters of depth.
Q: Will this work on a dedicated server?
A: Yes. Install the DLL on both the server and all clients. Fleet data is stored in ZDOs and synchronized normally.
Q: Does the Boat cost resources?
A: No. The Boat is a persistent utility vessel. Recalling it is free and instant.
Q: Can two players share a Flagship?
A: No. Each player has their own fleet slot. A ship can only be Flagship for one player at a time (first helm interaction wins).
Known Issues
- BiomeLock may block ship helm interaction and map pin updates in restricted biomes. Workaround: recall ships before entering restricted areas.
- Recalling a Flagship across very large distances (unloaded zone) moves the ZDO but the ship may not visually appear until the chunk loads. Sailing toward the last-known position will trigger the load.
- The
EnableShipNaming, EnableExtendedFleet, and EnableDeathRecovery experimental features are implemented in config but not yet fully functional in gameplay.
Roadmap
- Ship naming via rename panel
- Extended fleet (3+ ships)
- MoreMapPins integration (custom ship icons)
- Fast travel with ship (teleport alongside player)
- Death recovery (re-link fleet after corpse run)
- Ship health display in Fleet panel
- Auto-recall on spawn option
Credits
Built with Jotunn and BepInEx.
