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)

1. Open r2modman and select your Valheim profile.
2. Search for WindheimShips in the online package list.
3. Click Install. Dependencies (BepInExPack, Jotunn) are installed automatically.
4. Launch Valheim through r2modman.

Manual

1. Install BepInExPack_Valheim and Jotunn.
2. Download WindheimShips-0.1.0.zip.
3. Extract and copy plugins/WindheimShips/Windheim.dll into BepInEx/plugins/WindheimShips/.
4. 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.