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

Fleet

Recall

Map

UI

Persistence

Compatibility

Debug

Experimental

Compatibility

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.

Changelog

All notable changes to WindheimShips are documented here.

[0.1.0] — 2026-06-29

Initial public release.

Added

• Fleet system — per-player Flagship and Boat slots, stored in ZDOs and persisted across sessions.
• Ship recall — configurable hotkey (default K) opens the Fleet panel. One click teleports the selected ship to a valid water position near the player.
• Unloaded zone recall — when a ship is in an unloaded zone, recall nudges its ZDO toward the player without requiring the chunk to be loaded first.
• Stale ZDO recovery — two-pass recovery system: exact ZDOID match first, then nearest ship of the same type within 50 m. Full ZDOMan scan as fallback.
• Boat slot — persistent secondary vessel (default Raft). Indestructible. Stores to virtual inventory when not deployed; spawns on demand with no resource cost.
• Minimap pins — Flagship (hammer icon) and Boat (pin icon) tracked on both minimap and large map. Colors and labels configurable.
• Pin restoration — ship pins are restored after Valheim's ClearPins wipes the minimap (e.g., on map reopen).
• Occupied ship protection — configurable behavior (block / force-recall) when another player is aboard the target ship.
• OdinShip support — all Ship-component vessels, including OdinShip's 7 custom prefabs, register automatically via the Ship.Awake postfix patch.
• Dual helm patch — patches both ShipControlls.Interact and ShipControlls.TryInteract with HarmonyPrepare guards so the correct method is patched regardless of Valheim build version.
• Modular config system — nine static config classes: General, Fleet, Recall, Map, UI, Persistence, Compatibility, Debug, Experimental. Generates com.TAIJI.windheim.cfg on first launch.
• Plugin GUID — com.TAIJI.windheim
• Dependencies — BepInExPack_Valheim 5.4.2333, Jotunn 2.29.1