Sail Controller
Quick Start
Calculates lift and drag forces based on wind conditions, sail geometry, and angle of attack.
Prerequisites
To set up a sailing ship, you need:
- A ship with
WaterObjectcomponent andRigidbody(follow the Ship Controller guide first) AdvancedShipControllercomponent on the ship (for input handling)- Input bindings set up (see the Input guide)
Setting Up Wind Generation
- Create an empty GameObject in your scene and name it
WindGenerator. - Add the
WindGeneratorcomponent to it. - Configure the wind parameters:
Base Direction- Primary wind direction in degrees (0 = north/+Z axis)Base Speed- Average wind speed in m/s (typical: 5-20 m/s)Max Direction Variation- Angular deviation during gusts (15-45 degrees)Max Speed Variation- Speed deviation from base speedMin/Max Variation Interval- Time between wind changes
Note: Only one WindGenerator should exist per scene as it uses a singleton pattern.
Creating a Sail Preset
- Right-click in the Project window and select
Create > NWH > DWP2 > SailPreset. - Name the preset (e.g., "SquareSail" or "LateenSail").
- Configure the aerodynamic curves:
Lift Coefficient Vs AoA Curve- How lift varies with angle of attackDrag Coefficient Vs AoA Curve- How drag varies with angle of attackLift ScaleandDrag Scale- Global force multipliers
The preset includes default curves suitable for most sail types. Different sail designs (square, lateen, bermuda) can be represented by adjusting these curves.
Both curves store coefficient magnitudes over -180 to +180 degrees, indexed by the angle of attack described below. The runtime takes the absolute value of lift and clamps drag to zero, so a curve authored either as a magnitude (even about zero) or conventionally (odd about zero, negative lift at negative angles) behaves the same - the apparent wind selects which side the force acts on. Lift should be zero when the sail is edge-on (0 and +/-180 degrees); drag should peak near broadside (+/-90 degrees). Heel is already represented by the live sail geometry, so no separate heel multiplier is applied.
Setting Up the Sail
The sail is defined by four corner transforms arranged in a clockwise pattern:
Create four empty GameObjects as children of your ship to represent sail corners:
Corner_A- Bottom front (bottom left for square sails)Corner_B- Top front (top left for square sails)Corner_C- Top rear (top right for square sails)Corner_D- Bottom rear (bottom right for square sails)
Position these corners to define your sail shape. For a simple square sail:
- Place A and D at the bottom of the mast
- Place B and C at the top of the mast
- Adjust the spacing to create the desired sail width and height
Add the
SailControllercomponent to a child GameObject of your ship (the one with theRigidbody).Assign the corner transforms to the SailController:
- Drag
Corner_Ato fielda - Drag
Corner_Bto fieldb - Drag
Corner_Cto fieldc - Drag
Corner_Dto fieldd
- Drag
Assign the
Sail Presetyou created earlier.Adjust
Air Densityif needed (default 1.225 kg/m³ is standard sea level).
Note: Corner transforms can be attached to different parents to enable sail furling or complex rigging. For example, attach top corners to a rotating boom for realistic sail control.
Adding Sail Rotation (Optional)
To allow player-controlled sail rotation:
Create a GameObject as a child of your ship (e.g., "SailBoom").
Parent the sail corner transforms that should rotate with the boom (typically the rear corners C and D).
Add the
SailRotatorcomponent to the boom GameObject.Configure:
Rotation Axis- Local axis to rotate around (default: Y-axis)Rotation Speed- Rotation speed in degrees per second
Add one of the current scene-global ship providers described in Input.
InputSystemShipInputProviderships withRotateSailbound to keyboard 1/3 and the gamepad left/right shoulder buttons. WithInputManagerShipInputProvider, define the exact legacyRotateSailaxis or merge the shippedInputBindings.txttemplate.
Note: The SailRotator reads input from the parent AdvancedShipController component. Travel is
unlimited unless Limit Rotation is enabled, which confines the boom to the Min Angle/Max Angle
range measured from the pose the transform was authored in - the equivalent of a sheet.
Testing the Setup
- Press play. If the scene uses the optional
VehicleChangerworkflow plus a matching NWH Common scene-input provider, select the ship with that provider's Change Vehicle binding (V in the shipped keyboard binding). - The sail should now generate force based on wind conditions.
- Use the scene view with Gizmos enabled to see:
- Sail corners (white spheres)
- Sail directions (red = right, green = up, blue = forward)
- True wind (green arrow)
- Apparent wind (yellow arrow)
- Sail force (red arrow)
- Ship velocity (magenta arrow)
How It Works
Apparent Wind Calculation
The sail system calculates apparent wind, the wind experienced by the moving vessel, from the true wind and the ship's velocity. This explains why a ship can sail faster than the wind itself and why wind direction changes as the ship moves.
Force Generation
The sail generates two types of forces:
Lift Force - Acts perpendicular to the sail surface, along the sail's right vector
- Always on the leeward side, the side the apparent wind blows towards
- Magnitude based on lift coefficient curve at current angle of attack
- Primary propulsion force
Drag Force - Acts in the direction of apparent wind
- Always opposes relative motion through air
- Magnitude based on drag coefficient curve at current angle of attack
Total force depends on air density, apparent wind speed, and sail area.
Angle of Attack
Measured between the apparent wind and the sail's chord, taken from the leading edge (a/b, at the
mast) to the trailing edge (c/d). This is the same convention published sail coefficient tables
use, so a table can be entered into a preset unchanged. A correctly trimmed close-hauled rig sits
near 15 degrees; the number never approaches 180 in normal sailing.
The angle is measured in the sail's own plane, so heel and heave do not shift the coefficient lookup.
Its sign is the opposite of the lift side: negative means the wind blows towards +SailRight, so
lift acts on +SailRight.
- 0° to ±10° - Sail close to edge-on, little lift, a real sail would be luffing
- ±10° to ±45° - Efficient sailing angles with high lift
- ±45° to ±90° - Stalling, transitioning to drag-dominated
- ±90° to ±180° - Wind on the back of the sail, mostly drag
Field Explanations
Geometry
a,b,c,d- Four corner transforms defining the sail shape. Must be assigned in clockwise order: front-bottom, front-top, rear-top, rear-bottom. Assigning them out of that order produces a bow-tie quad with the wrong area and normal; the component warns once at startup when it detects one. These can be parented to different GameObjects to enable sail furling or complex rigging.
Physics
Sail Preset- ScriptableObject containing lift and drag coefficient curves versus angle of attack. Different sail types (square, lateen, bermuda) require different presets.Air Density- Air density in kg/m³ used in force calculations. Standard sea level is 1.225. Can be used as a global force multiplier to tune overall sail power without modifying the preset curves.
Calculated Properties (Runtime)
The following properties are calculated each frame and visible in the inspector during play mode:
Sail Geometry:
Sail Center- Surface-weighted center point where forces are appliedSail Area- Total sail surface area in m²Sail Forward- Forward direction vector of the sailSail Up- Up direction vector of the sailSail Right- Right direction vector (perpendicular to sail plane)
Wind & Forces:
True Wind- Environmental wind from WindGeneratorShip Velocity- Current vessel velocityApparent Wind- Wind relative to the moving ship (True Wind - Ship Velocity)Angle Of Attack- Angle between sail forward and apparent windSail Force- Total aerodynamic force vector applied to the ship
Notes and Tips
Multi-Sail Setups
- Add multiple
SailControllercomponents to create ships with multiple sails (main sail, jib, mizzen, etc.) - Each sail can have its own preset and corner transforms
- Each sail calculates forces independently
Triangular Sails
For triangular sails (like a lateen or bermuda rig):
- Position one corner at the same location as another (e.g., A and D both at the boom)
- The sail area calculation will still work correctly
- Alternatively, use very short edge length between paired corners
Sail Furling
To implement furling:
- Attach top corners to one parent GameObject
- Attach bottom corners to another parent GameObject
- Animate the distance between these parent objects
- As corners move closer together, sail area automatically reduces
- Forces scale proportionally with area
Performance
- Sail physics run in
FixedUpdate()at physics timestep rate - Gizmo drawing only occurs in editor, not in builds
- Wind generation uses coroutines for smooth transitions
Debugging
Enable Gizmos in the Scene view to visualize:
- Sail shape and corners
- Wind vectors
- Force vectors
- Sail orientation axes
The inspector shows real-time debug info during play mode:
- Current angle of attack
- Force magnitude
- Force vector
Common Issues
Sail not generating force:
- Check that
WindGeneratorexists in scene - Verify
SailPresetis assigned - Ensure all four corner transforms are assigned
- Check that wind speed is non-zero
Incorrect force direction:
- Verify corner assignment order (a, b, c, d clockwise)
- Check sail orientation using gizmo arrows
- Ensure
SailForwardpoints in the expected direction
Sail rotating incorrectly:
- Check
SailRotatorrotation axis direction - Use negative axis values to reverse rotation
- Verify the Input System
RotateSailaction or the legacyRotateSailaxis for the selected ship provider