Approximating a Hull with Physics Shapes

The accuracy of buoyancy depends on how well your collision shapes approximate the underwater volume of the hull. This is the highest-skill workflow in the plugin and the most common source of “my boat doesn’t float right” issues.

Concepts

• Buoyancy is calculated per shape, not from the visible mesh. The plugin samples wave heights against your Box / Sphere / Capsule shapes on PhysicsBodyComponent: the rendered hull mesh is never sampled. Effective mass = sum of (additive shape volume × density) − (subtractive shape volume × density).
• Material type sets density. Wood = 800 kg/m³, Steel = 7850, HighDensityFoam = 450, Air = 1.225. Water is 1025 kg/m³, so anything denser sinks unless balanced by Subtractive air pockets.
• Subtractive shapes carve out volume for cabin interiors, hollows, and air pockets. A shape with MaterialType = Air is automatically marked Subtractive.

Workflow

1. Decide on overall mass. Pick a target weight from a real-world equivalent: small dinghies 50–150 kg, runabouts 300–1500 kg, sailing yachts 500 kg+. Mass results from your shape volumes × material densities; iterate by adjusting volumes or materials.

2. Approximate the submerged hull with 1–8 shapes. More shapes = better force distribution but more CPU per buoyancy step. Rules of thumb:

   • Test object: 1 box.
   • Dinghy / PWC: 1–3 boxes.
   • Runabout / mid-size powerboat: 3–5 boxes (narrow box at bow, wider midship box, flat box at stern).
   • Sailing yacht: 5–7 shapes (hull + keel as a separate dense ballast shape).
   • Tall ship: 6–10 shapes (hull split forward / midship / aft, plus mast / rigging if you want their mass to influence stability).

3. Place shapes in the editor. Add them to PhysicsBodyComponent → Boxes / Spheres / Capsules. Each shape’s Transform is local to the TargetComponent (typically the hull mesh). Set TargetComponentName to your hull mesh’s component name.

4. Pick the MaterialType per shape. This sets density. If you want a specific density not listed, set MaterialType = None and edit Density directly on the shape.

5. Add Subtractive air pockets for cabin / cockpit / hollow hull interiors. Place a smaller shape inside the main hull shape with MaterialType = Air. Without these, a steel-hulled vessel would weigh as a solid block of steel and sink.

6. Visualize while tuning. Call DebugDrawShapes() (Blueprint-callable on PhysicsBodyComponent) in PIE to see the shape outlines. Adjust until the silhouette matches the hull volume you want submerged at rest.

7. Tune center of mass.

   • With bUseCustomCenterOfMass = false (default), the plugin uses the underlying physics engine’s center of mass and applies CenterOfMassOffset on top.
   • With multiple shape groups or skeletal-bone-attached shapes, the plugin auto-sets bUseCustomCenterOfMass = true and computes a weighted-sum CoM from your shapes’ masses.
   • Lowering the CoM (negative Z offset) increases roll stability; raising it makes the vessel tippier.

8. Validate with simple test actors first. BP_FloatCubeTest / BP_FloatSphereTest (in Content/Blueprints/BuoyantActors/) are minimal targets for sanity-checking water density and damping settings before applying to a complex vessel.

Common pitfalls

Caution

• Shapes must be on the same actor as the BuoyancyComponent. A shape on a child actor will not be picked up.
• For skeletal mesh actors, set TargetBoneName per shape so it follows the bone. Empty bone name attaches to the root.
• The hull mesh’s collision is not used for buoyancy. You can leave it as “No Collision” if you don’t need it for other purposes: the physics shapes handle water interaction.

Reference vessels

Study these to learn the patterns:

• BP_Runabout (Content/Blueprints/Pawn/Vessels/Runabout/): planing powerboat. Hull shapes + engine + rudder + propulsion data. Good general reference.
• BP_Dinghy (.../Dinghy/): small displacement boat. Minimal shape layout.
• BP_TallShip data assets (.../TallShip/): large vessel with sails (multiple PropulsionDataAsset instances) and keel as a separate ControlSurface.
• BP_FloatCube / BP_FloatSphere / BP_MultiBuoyFlotationRig (Content/Blueprints/BuoyantActors/): minimal test objects.