Heeling

[MarkoBarthel]

The Ship Editor lets you configure the handling of an imported ship without editing its 3D model or writing C++ code. Adjust propulsion, rudder response, turn-induced heeling and water resistance to suit your vessel. Handling settings are stored in the ship's boat.json file and applied when the next voyage starts.

Use the Heeling section to choose whether the vessel leans into a turn, leans away from it, or has no additional turn heel. The effect responds to the ship's actual forward speed and rate of turn. Adjustable strength, an angle limit and separate response and return times let you create a quick banking motion or a slower, more restrained response.

The additional turn heel is combined with the existing wave-induced roll. Turning it off does not stop the ship from rolling in waves. The maximum turn
heel setting limits this additional contribution, not the vessel's total roll.

 

Ship Editor Workflow

1. Open the imported ship in the Ship Editor.
2. Select Heeling in the left-hand list.
3. Enter the required values. Press Enter or leave the numeric field to commit it.
4. Select Save JSON to save the changes.
5. Start a new voyage with that ship to test the result.

Use Default next to an individual field to remove its saved override. The
editor then uses the native default for that setting.

 

Heeling Parameters
Configure the additional turn-induced roll described below.

Editor label                              JSON key                                 Default  Range
Turn heel direction             TurnHeelMode                             None     See modes
Turn heel strength              TurnHeelStrength                             1.0      0 to 4
Maximum turn heel (deg)   MaximumTurnHeelDegrees             6.0      0 to 30
Heel response time (s)        TurnHeelResponseTime                   1.0      0.01 to 60
Heel return time (s)             TurnHeelReturnTime                        1.5      0.01 to 60
Minimum heel speed (kn)   MinimumTurnHeelSpeedKnots        2.0      0 to 200

 

TurnHeelMode
None: disable additional turn-induced heel.
Inward: lean towards the inside of the turn.
Outward: lean towards the outside of the turn.
JSON mode strings are case-sensitive. Use the names, not numeric enum values.

TurnHeelStrength
Multiplies the calculated target angle. Higher values produce more heel for 
the same speed and rate of turn, subject to MaximumTurnHeelDegrees.

MaximumTurnHeelDegrees
Caps the absolute target angle of the additional turn heel. It is a limit,
not a fixed angle that the vessel will reach in every turn. A value of zero
produces a zero turn-heel target.

TurnHeelResponseTime
Controls smoothing when heel builds in the same direction. A larger value
gives a slower response. It is an exponential time constant, not an exact
delay or the time required to reach the final angle completely.

TurnHeelReturnTime
Controls smoothing when heel decreases, returns towards zero or changes
direction. Larger values make the motion settle more slowly.

MinimumTurnHeelSpeedKnots
Below this absolute forward-speed threshold, the turn-heel target becomes
zero and the additional heel fades using the return time. This uses forward
speed through the vessel's heading, not the total sideways velocity.

 

JSON EXAMPLES

These are partial configuration objects, not complete ship manifests. Merge the fields into the existing root-level handling object in boat.json. Preserve
other handling fields and the rest of the ship configuration. Do not create two handling objects or replace the complete boat.json with a snippet.

 

Example A — slower outward heel:

{
  "handling": {
    "TurnHeelMode": "Outward",
    "TurnHeelStrength": 0.65,
    "MaximumTurnHeelDegrees": 4.0,
    "TurnHeelResponseTime": 3.0,
    "TurnHeelReturnTime": 5.0,
    "MinimumTurnHeelSpeedKnots": 1.5
  }
}

Example B — quicker inward banking:

{
  "handling": {
    "TurnHeelMode": "Inward",
    "TurnHeelStrength": 1.0,
    "MaximumTurnHeelDegrees": 8.0,
    "TurnHeelResponseTime": 0.8,
    "TurnHeelReturnTime": 1.5,
    "MinimumTurnHeelSpeedKnots": 3.0
  }
}

Example C — disable additional turn heel:

{
  "handling": {
    "TurnHeelMode": "None"
  }
}