SailTrim for Valheim

Manual sail trimming for Valheim 1.0, plus a bronze cleat to tie boats up at the dock. Everyone on the server installs the same SailTrim.dll; the sheet angle and the mooring are synced through the ship so other players see the yard swing and the boat stay put.

Built against Valheim 1.0.12 (Unity 6000.0.75f1) with BepInEx 5.4.x.

Install (every player)

1. Install BepInEx for Valheim if you don't have it yet. The easiest way is the BepInExPack Valheim package from Thunderstore (r2modman / Thunderstore Mod Manager), or the manual zip from https://valheim.thunderstore.io/package/denikson/BepInExPack_Valheim/ extracted into the game folder (...\steamapps\common\Valheim). Launch the game once so BepInEx\config and BepInEx\plugins exist.
2. Drop SailTrim.dll into Valheim\BepInEx\plugins\.
3. Start the game. BepInEx\config\com.maxst.sailtrim.cfg is created on first launch. Edit it with the game closed (or use a config manager) to change keys and physics.

Server (recommended). Put the same SailTrim.dll in the dedicated server's BepInEx\plugins too (or just have it installed if a player hosts). Ship physics always runs on a client, so the server copy does not sail anything; it does two useful things, both configurable in the server's BepInEx\config\com.maxst.sailtrim.cfg under 0. Server:

Without a server copy everything still works, but nothing stops a friend from forgetting to install it. Since 1.1.1 the pilot's client takes over simulating the ship whenever they hold the rudder with manual trim on, so an unmodded passenger sees the boat move exactly as the pilot sails it; they only see the yard drawn at vanilla's angle.

Controls (while holding the rudder)

Gamepad: the left stick forward/back sheets in/eases, the gamepad Use button lets out sail and the gamepad Jump lets go of the helm. There are no default gamepad bindings for taking in sail or rowing, so use a keyboard for those or bind LowerSailKey, RowForwardKey and RowBackKey in the config.

All of these keys, and the sheet-key toggles, can also be changed in game: Settings > SailTrim tab (main menu or pause menu). Click a key to rebind it, Esc cancels, Delete clears it. Physics and server settings are not in the menu.

The vanilla ship HUD gets three additions: a sail icon on the wind circle that rotates with your sheet (belly toward the side the wind fills it; colour = trim state), a speed gauge in knots to its left (scaled to that hull's speed: gold up to hull speed, red past it), and two lines of text below: the trim hint (Trimmed, Sheet in, Ease out, LUFFING, STALLED, ABACK, BOW BURIED) and sheet angle / heel / gust. Wind direction and the no-go zone stay on the vanilla wind icon. The hint is averaged over about 1.5 s (ReadoutSmoothing) with a bit of hysteresis, so wave rocking does not make it flicker; trim for what it says on average, not for every wave. Turn the overlay off with ShowHud = false.

When you take the helm with the sail furled, a gold line under the HUD reminds you that holding E lets out sail, holding Q takes it in, Shift rows and Space lets go. It disappears once you have used the keys.

Sailing as a crew

Any passenger with the mod sees the ship HUD like the pilot does (wind circle, sail icon, speed gauge, trim state). Use the ship's Hold fast spot on the mast (E): you are held at the mast and W/S trim the sail while the pilot steers, exactly as a longship crew would, and a dedicated hand works the sheet 20% faster than a pilot doing two jobs. The pilot can still trim too; whoever pulled last wins and the other follows. Nobody else aboard can touch the sheet. Jump, or take the rudder yourself, to let go.

Opting out

Everyone starts in vanilla mode. The first time you take a rudder with the mod installed, the boat sails exactly like vanilla (W/S step the sail, tap E lets go, auto-trim, no extra heel) and the HUD says "Vanilla sailing · H for manual trim". Press H at the helm to switch to manual trim; the choice is saved per player and remembered between sessions, and H flips it back any time. While a vanilla-mode player holds the rudder the boat sails vanilla for everyone aboard; hand it to a manual-trim player and it switches back.

How to sail it

• Sheet angle 0 = yard hauled fully in along the hull, 90 = fully eased square across the hull.
• It is a square sail, so it likes a big angle of attack: the yard wants to sit at roughly half the apparent wind angle. Close-hauled (wind 60° off the bow) the yard goes to about 30°, on a beam reach about 45–60°, and from a broad reach onward it is simply square (90°). The HUD's Trimmed hint is computed from the actual force curve for the current wind, so trim to the hint rather than to a rule.
• Downwind of about 110° the sail is a drag device: running with the yard square is the right trim, not a stall. Forward of that, hauling in well past the hint stalls it.
• Sail amount: hold E to let sail out and Q to take it in, any amount from furled to full. Less sail means less drive, less heel and a drier bow; reef before the mast strains or the bow buries.
• Rowing (Shift / Ctrl) only works with the sail furled; holding a row key with sail set stows the sail first (about a second, so a slip does nothing).
• The yard follows the sheet even with the sail furled, so you can pre-trim before hoisting.
• Eased too far: the sail luffs: the cloth ripples and there is almost no drive (the yard stays steady). Sheet in.
• Hauled in hard, a drawing sail looks taut with a fair curve; eased out for a run it moves freely.
• Tacking plays as one motion tied to the bow's swing: within about 25° of the wind the sail's tension eases and its foot streams out downwind, the yard sweeps round through square as the bow passes through the wind, and the sail is tensioned again on the new side. It is visual only; the boat tacks exactly as before.
• Wind on the wrong face, for example in irons with the yard square: the sail is aback and pushes you astern. Square-riggers used this to back out of irons; sheet in or bear away to fill it properly.
• Hauled too far: the sail stalls. Drive drops (never to zero, you can still crawl home), and the boat heels hard. Ease out.
• A perfectly trimmed sail is about 50% faster than vanilla's auto-trim on a reach and much faster upwind; 10° off the ideal sheet costs about 15% of the push, a sloppy trim is roughly vanilla speed, and a stalled sail is much slower. Heel scales with the sail's side force, so it grows with wind strength and shrinks as you take in sail; a furled sail or rowing adds no heel at all.
• The no-go zone is vanilla's: lift dies within about 37° of the true wind, exactly where the vanilla wind indicator turns red.

Realism extras (all in the 6. Realism config section, each can be zeroed)

• Gusts and lulls. Rare by design: on average one event every 12 minutes, lasting about 40 s, up to ±40% wind strength. The readout shows GUST / lull while one is on. Between events the wind only has a tiny wobble. Everyone sees the same gusts (they are derived from world time).
• Wind shadow. Land upwind takes wind away: a cliff or forested hill close to windward can cost you up to 40% of the breeze, then it fills in as you clear the point. Deliberately mild (WindShadowMax), so rivers between low banks stay sailable; the readout shows Lee when it bites.
• Downwind rolling. Running within about 30° of dead downwind with the sail up, the boat rolls rhythmically, more in strong wind and at full sail. Head up a few degrees or drop to Half and it settles. Gentle by default (DownwindRolling).
• Weather helm. A heeled boat tries to round up into the wind; hold rudder against it or ease the sheet. It grows with the square of heel, so a little heel barely tugs and a lot really rounds you up. Heel and weather helm both scale with hull beam, so the Karve is tender and the longship stiff.
• Heel and speed. A little heel helps: about 5% faster at 8° (less hull in the water), gone by 16°. Past that, lying over costs speed: 25° is about 18% slower than flat. Ease out in a gust.
• Leeway. A stalled sail or a hard-heeled boat slides sideways instead of tracking straight.
• Mast strain. Heel past 35° for more than about 4 seconds and the rig is straining: the hull takes 0.5% of its health per second until you ease out or reef. A brief knockdown in a gust costs nothing.
• Hull speed. Each hull has a speed it was built for (from its waterline length). Push past it and wave-making drag climbs and the bow digs in much harder, so a Karve driven at longship speeds buries its bow long before the longship would. The gauge turns red and reads "over".
• Bow-down trim. Drive buries the bow, most of all running at full sail in a storm. Past about 12° the readout says BOW BURIED: you lose up to 40% of your drive and ship a little water (0.3% hull per second) until you ease out or drop to Half. Capped at 15°; the mod never pitchpoles the boat.
• Gybes (off by default). A square yard is symmetric and has no boom, so a Viking ship wearing round was undramatic; nothing visibly swings. If you turn GybesEnabled on anyway, letting the wind cross the stern with the sail up gives a "GYBE!" roll kick and hull damage (5% of max health at full sail in strong wind with the sheet fully eased), softened by half sail, light wind, or sheeting in first.

Crew weight (1.7.0)

Bodies on deck move the boat. Stand to windward and she comes upright and sails faster; everyone to leeward and she lies over and slows. Sitting crew, anyone holding fast at the mast and the helmsman are braced, so they do not count. The effect is the boat's own physics, which means a karve answers to one person moving and a longship hardly notices. Crew on deck are told which rail to be on while she is heeling.

The gangway (1.8.0)

Craft a Gangway at the workbench: 10 fine wood and 4 iron nails, so it comes in about when the longship does. Every hull but the raft carries a pair of timber brackets on each rail, near its own boarding ladder; stand at them with a gangway in your pack and press E to fit it, one to a side. It stays with the boat.

It is three boards hinged end to end, planked in the hull's own timber and strapped with iron beams. Stowed, they fold back on one another and stand lashed against the inside of the rail. Press E again to lower it: the boards unfold, the plank swings out over the side and settles on whatever is under it, a dock, the shore, a log, or a beam halfway out, and it keeps resting there as the boat works in the swell. An inboard ramp swings down off the rail at the same time so you can walk up from the deck without jumping, and folds away inside the planking when it is not wanted. Carrying enough metal to be encumbered you cannot jump at all, which is what the whole thing is for.

While it is down the boat holds its spot the way a tied-up boat does, so nothing can shove it out from under you, though unlike a cleat it does not mend the hull. Lowering it within reach of a cleat with no boat on it ties that cleat on as well, so one press does the dock. You work it from on board. Taking the helm raises it after two seconds (GangwayRetractDelay). GangwayEnabled, GangwayLength, GangwayMaxAngle, GangwaySwingTime, GangwayTiesCleat and its costs are in the config.

Rafting up (1.9.0). If the plank comes down on another boat's deck rather than on the shore, it lands on it and the two are lashed alongside: both hold where they lie and both stop, the way a gangway onto a dock holds the one boat. Walk across, load the other hold, raft the fleet up for the night. Taking the helm of either boat raises the plank and frees them both. GangwayLashShips turns it off.

She has to be nearly still to put it down, or to take a line to a cleat: MooringMaxSpeed (3.5 knots). Both stop the boat, and a plank aimed from a boat still making way is aimed at something it will no longer be over.

Arranging the HUD (1.10.0)

Open the SailTrim settings page aboard a boat. The page goes see-through and the HUD keeps drawing behind it, so you can pick a piece from the list, move and size it with the sliders, and watch it move as you do. The first entry on the list is everything, for shifting the lot together. OK keeps it, Back puts it as it was, and Reset returns the whole HUD to stock. Meant for playing beside mods that move or enlarge the ship's own dials. HudLayoutKey can be bound if you would rather nudge things at the helm without opening the menu.

Lashing alongside (1.9.0)

Bring a boat up beside another and lower the gangway onto its deck. Nothing declares that you meant to: if the plank reaches, it lands, the same as it lands on a dock. When it lands on a deck the two boats are lashed alongside and both hold where they lie, so the plank stays put between them and you can walk across, shift cargo, or raft up for the night. Taking the helm of either boat raises the plank after the usual couple of seconds and frees them both, so nobody is ever held alongside by someone else's gangway with no way out. GangwayLashShips turns it off.

The chart (1.11.0)

Open the map and a readout appears in the corner: how she is trimmed, her speed, her sheet and heel, and then the two bearings that matter. Heading is where her bow points. Track is the course she is making good, which is not the same thing: a hard-heeled or badly trimmed hull slides to leeward, and over a long board that puts you well down from where you aimed. The difference is written out as the set and the drift, and drawn as a dotted line running from the boat the way she is really going, fading as it goes further ahead.

Put the cursor on a buoy and press C to steer for it. The panel then gives its distance, the course to steer (the bearing to it with the measured leeway taken out) and how far off it she is running. A mark dead to windward is reported as a beat, with the board she is nearest on, rather than a bearing she cannot hold. Press C away from a buoy to give the mark up. The mark is remembered per world.

The chart states; it does not coach. Nothing here tells you which way to hold the helm or how to trim, on the map or on the sailing HUD. MapHudEnabled, SetMarkKey, TrackMinutes and NoGoAngle are in the config.

Towing (1.11.0)

A boat with a tow bollard at her stern can take another in tow: a rope from her stern to the other's bow, and the boat behind keeps her way instead of being taken by vanilla's rule for an empty hull. Pull too hard and the line parts. TowLength, TowBreak and TowRange are in the config.

The cleat (1.6.0, three sizes in 1.11.0)

Build a Cleat from the hammer's Misc tab (one bronze): a bronze horn cleat that sits on top of planks or a floor. Stand at it with a boat within 10 m and press E to tie the boat up. The rope is made fast round the horn and runs to the hull, and the boat holds its spot and heading the way an empty boat does in vanilla, with or without people aboard. Creatures and waves cannot shove it away. Press E at the cleat again to untie, or just take the helm: after a second at the rudder (CastOffDelay) the boat casts off by itself. If the boat sinks, or the cleat is broken, the other side lets go too. A tied-up boat also mends itself a few percent a minute (MoorRepairPerMinute). CleatRange, CleatCost, CastOffDelay and MooringHold are in the config.

Berths (1.11.0)

Cleats come in three sizes, for a karve's berth, a longship's and a drakkar's. Take out the hammer near one and the berth it marks is drawn on the ground, so a harbour can be laid out to fit the boats that will lie in it.

The buoy (1.6.0)

Build a Buoy from the hammer's Misc tab: 6 wood and 2 resin, no workbench. It is a barrel float with a staff, a banner and a lantern. Aim at open water and place it like a boat. It floats on the waves, holds the spot it was set at, and its lantern glows at night. It stays in the world as far out as the game keeps distant objects (several zones), so a mark shows from far down a channel. Press E at a buoy to change the banner's colour: red and green for a channel, yellow for a race mark, and so on. Every buoy that is loaded shows on the map as a small disc in its colour. A boat that hits one shoves it aside for a moment and it works its way back. BuoyEnabled, BuoyLight and BuoyPins are in the config.

Buoys and cleats cannot be damaged (a ship's ram, weather, the sea floor); remove them with the hammer.

FAQ

Do I have to learn to sail to use this? No. The first time you run it you are sailing vanilla, exactly as before. Press H at the helm to take the sheet yourself, and H again to hand it back. Whichever you chose last is what you get next time. Manual trim is faster if you work at it, so it is worth trying, but nothing forces you.

Is it faster or slower than vanilla? Faster when you trim well, about the same when you do not. A good trim is roughly 50% faster than vanilla's auto-trim on a reach and much faster upwind; 10 degrees off costs about 15% of the drive; a sloppy trim is about vanilla speed. A badly stalled sail is slower, but you can always crawl home. None of the realism features is a straight penalty.

Does everyone on the server need it? Everyone who wants to sail with it, yes, and they all need the same version. The version check is exact: a server on 1.9.0 will not accept a 1.10.0 client. Move the server and the players together.

What happens to a friend who has not installed it? They can still sail. From 1.1.1 the pilot's own machine simulates the boat while they hold the rudder with manual trim on, so an unmodded passenger sees the boat move exactly as the pilot is sailing it. They just see the yard drawn at vanilla's angle rather than yours.

Does the dedicated server need it? Recommended, not required. Ship physics always runs on a client, so the server copy does not sail anything. It does two things, both in the server's config under 0. Server: Enforcement (Off / Warn / Require) decides what happens to players without a matching version, and LockConfig pushes the server's physics, heel, gust and hull-speed settings to every client on connect so everyone sails by the same rules. Keys, HUD, camera tilt and the H opt-in always stay personal.

Where are the settings? Two places. The common ones are in the game's own Settings screen, under a SailTrim tab: keys, the options, and the HUD layout. Everything else is BepInEx\config\com.maxst.sailtrim.cfg, which is created on first launch. Edit it with the game closed, or use a config manager.

The HUD sits on top of another mod's UI. Can I move it? Yes, and you can watch it move while you do. Open Settings, SailTrim tab, aboard a boat: the page turns see-through and the HUD keeps drawing behind it. Pick a piece from the list, or everything to shift the lot together, and move and size it with the sliders. OK keeps it, Back puts it as it was, Reset returns the whole HUD to stock.

How do I get a gangway, and where does it go? Craft one at the workbench: 10 fine wood and 4 iron nails, so it arrives about when the longship does. Every hull but the raft has a pair of timber brackets on each rail, near its own boarding ladder. Stand at them with a gangway in your pack and press E. It stays with the boat from then on, one to a side; press E again to lower or raise it.

Why will my gangway not go down? Two reasons. Either there is nothing within reach for it to rest on, in which case it refuses rather than dangling over the water, or the boat still has way on her. Lowering it holds the boat where she lies, so she has to be under MooringMaxSpeed (3.5 knots) first. The message tells you which.

Can I tie two boats together? Lower a gangway onto another boat's deck. It lands on it and the two are lashed alongside: both hold where they lie and both stop, so you can walk across and load the other hold. Taking the helm of either boat raises the plank and frees them both. GangwayLashShips turns it off if you would rather it never did that.

How do I tie up at a dock? Build a Cleat from the hammer's Misc tab (one bronze). Stand at it with a boat within 10 m and press E. The rope is made fast round the horn and the boat holds her spot and heading, with or without people aboard, and mends herself slowly while she is there. Press E again to untie, or just take the helm and she casts off by herself after a second. She has to be under 3.5 knots to be made fast.

My boat came untied after I logged out. Fixed in 1.10.0. Valheim hands every object a new internal id when a world loads, so the cleat and the boat each lost track of the other. Both ends now keep a marker that survives the reload, and the link is put back from it. Boats lashed alongside keep their raft the same way.

What are the buoys for? Marking water. Build one from the hammer's Misc tab (6 wood, 2 resin, no workbench) and place it on open water like a boat. It floats, holds its spot, lights up at night and shows on the map. Press E to change the banner colour: red and green for a channel, yellow for a race mark. Since 1.11.0 every buoy in the world is on the map whether it is loaded or not, the way a map pin is, and one off the corner map is held against its rim in its own colour. They stay loaded from a long way off, so a mark shows from down the length of a fjord.

Can I turn individual features off? Yes. Everything in the 6. Realism section can be set to zero on its own: gusts, wind shadow, downwind rolling, weather helm, leeway, mast strain, hull speed, bow-down trim. Gybes are off by default. The gangway, cleat and buoy each have an enable switch too.

Does it work with other mods? It should. It patches the ship, the helm and the sailing HUD and leaves the rest of the game alone. The HUD can be moved and resized for anything that rearranges the ship's dials. If you find a mod it argues with, please say which one.

Something is wrong. What is useful to send? BepInEx\LogOutput.log, what you were doing, and which ship. Issues at https://github.com/estovall/SailTrim -- the log usually says more than a screenshot can.

Config highlights (BepInEx\config\com.maxst.sailtrim.cfg)

Everything else is documented inline in the cfg. While connected to a server with LockConfig on, the server's values replace yours for the physics sections (your file is not changed); they come back when you leave.

Building from source

Requirements: .NET SDK (8 or 9) and a Valheim install.

dotnet build SailTrim/SailTrim.csproj -c Release

The dll lands in dist\SailTrim.dll. If Valheim is somewhere else pass -p:ValheimDir="D:\Games\Valheim", and -p:DeployDir="D:\Games\Valheim\BepInEx\plugins" copies it straight into the game.

The game assemblies are publicized at build time (BepInEx.AssemblyPublicizer) so the plugin can reach private Ship fields. On load the plugin verifies every Harmony target by reflection and disables itself with an error in BepInEx\LogOutput.log if a game update changed a signature.

What it patches

• ShipControlls.ApplyControlls — W/S become ease/sheet-in; rudder passes through.
• ZInput.GetButtonDown("Use") — suppressed while piloting so tap-E can't release the helm; the plugin re-implements tap = raise, hold = release.
• Ship.GetSailForce — lift/drag model from sheet angle vs. apparent wind.
• Ship.UpdateSail — yard follows the sheet angle (one bounded angle, always through square); the cloth's own wind settings make it luff, tauten and flog.
• Ship.CustomFixedUpdate (postfix) — heel couple on the ship owner; a second postfix holds a moored boat.
• ZNetScene.Awake, ObjectDB.Awake / CopyOtherDB — the cleat prefab (built from primitives with the bronze material, no asset bundle) into the world's prefab list and the hammer's piece table. SailTrim_Moor RPC to the boat's owner; SailTrim_Boat in the cleat's ZDO, SailTrim_Cleat / SailTrim_MoorPos / SailTrim_MoorYaw in the boat's.
• Ship.Start / Ship.UpdateControlls — SailTrim_Sheet / SailTrim_Mode RPCs (pilot → ship owner) plus sailtrim_sheet (float) and sailtrim_manual (bool) in the ZDO (owner → everyone), mirroring how vanilla syncs the rudder.