Dynamic Water Physics 2
Search Results for

    Show / Hide Table of Contents

    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 WaterObject component and Rigidbody (follow the Ship Controller guide first)
    • AdvancedShipController component on the ship (for input handling)
    • Input bindings set up (see the Input guide)

    Setting Up Wind Generation

    1. Create an empty GameObject in your scene and name it WindGenerator.
    2. Add the WindGenerator component to it.
    3. 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 speed
      • Min/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

    1. Right-click in the Project window and select Create > NWH > DWP2 > SailPreset.
    2. Name the preset (e.g., "SquareSail" or "LateenSail").
    3. Configure the aerodynamic curves:
      • Lift Coefficient Vs AoA Curve - How lift varies with angle of attack
      • Drag Coefficient Vs AoA Curve - How drag varies with angle of attack
      • Lift Scale and Drag 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:

    1. 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)
    2. 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
    3. Add the SailController component to a child GameObject of your ship (the one with the Rigidbody).

    4. Assign the corner transforms to the SailController:

      • Drag Corner_A to field a
      • Drag Corner_B to field b
      • Drag Corner_C to field c
      • Drag Corner_D to field d
    5. Assign the Sail Preset you created earlier.

    6. Adjust Air Density if 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:

    1. Create a GameObject as a child of your ship (e.g., "SailBoom").

    2. Parent the sail corner transforms that should rotate with the boom (typically the rear corners C and D).

    3. Add the SailRotator component to the boom GameObject.

    4. Configure:

      • Rotation Axis - Local axis to rotate around (default: Y-axis)
      • Rotation Speed - Rotation speed in degrees per second
    5. Add one of the current scene-global ship providers described in Input. InputSystemShipInputProvider ships with RotateSail bound to keyboard 1/3 and the gamepad left/right shoulder buttons. With InputManagerShipInputProvider, define the exact legacy RotateSail axis or merge the shipped InputBindings.txt template.

    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

    1. Press play. If the scene uses the optional VehicleChanger workflow plus a matching NWH Common scene-input provider, select the ship with that provider's Change Vehicle binding (V in the shipped keyboard binding).
    2. The sail should now generate force based on wind conditions.
    3. 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:

    1. 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
    2. 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 applied
    • Sail Area - Total sail surface area in m²
    • Sail Forward - Forward direction vector of the sail
    • Sail Up - Up direction vector of the sail
    • Sail Right - Right direction vector (perpendicular to sail plane)

    Wind & Forces:

    • True Wind - Environmental wind from WindGenerator
    • Ship Velocity - Current vessel velocity
    • Apparent Wind - Wind relative to the moving ship (True Wind - Ship Velocity)
    • Angle Of Attack - Angle between sail forward and apparent wind
    • Sail Force - Total aerodynamic force vector applied to the ship

    Notes and Tips

    Multi-Sail Setups

    • Add multiple SailController components 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:

    1. Attach top corners to one parent GameObject
    2. Attach bottom corners to another parent GameObject
    3. Animate the distance between these parent objects
    4. As corners move closer together, sail area automatically reduces
    5. 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 WindGenerator exists in scene
    • Verify SailPreset is 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 SailForward points in the expected direction

    Sail rotating incorrectly:

    • Check SailRotator rotation axis direction
    • Use negative axis values to reverse rotation
    • Verify the Input System RotateSail action or the legacy RotateSail axis for the selected ship provider
    In this article
    Back to top Copyright © NWH - Vehicle Physics, Aerodynamics, Dynamic Water Physics