Importing your own watercrafts - Quick Guide

[MarkoBarthel]

Ahoy Captains,

 

Here is a quick guide for importing you own created watercraft into the sim. I will improve and expand the docs for importing over the dev time. You can you the small car ferry in the Mods/Boats folder as a template.

 

Structure tree of imported models. Propeller and ruder (needs to renamed to rudder, will come with an update) correct naming is needed in your 3d program.

 

Mods/
└── Boats/
    └── MyFishingBoat/
        ├── boat.json
        ├── ship.fbx
        │   ├── Prop1
        │   ├── Prop2
        │   ├── Ruder1
        │   ├── Ruder2 
        ├── preview.png
        ├── Textures/
        │   ├── hull_basecolor.png
        │   ├── hull_normal.png
        │   └── hull_roughness.png
        └── Sounds/
            ├── engine_idle.wav
            ├── engine_running.wav
            └── horn.wav

 

Ship Setup —ingame watercraft editor

If the naming is correct, the imported folder structure would be regcognized by the sim and the boat will be visible in the boat selection menu. For imported ships is the boat editor available in the boat selection menu. Most of the setup can be done in the editor and only a small part is only needed in the json file. 

# Open and edit

1. Open ship selection, choose a custom ship and press **Ship Setup**.
2. Right-drag to orbit; middle-drag to pan; wheel to zoom. Click the preview for keyboard focus,
   then use W/A/S/D and Q/E to move the view. Shift increases the movement step.
3. Select a point in the left list or click its marker. Drag an axis (red X, green Y, blue Z),
   or commit a numerical coordinate on the right with Enter or by leaving the field.
4. **Preview bridge** looks from the configured camera. **Use view as bridge** copies the current
   preview camera position, rotation and FOV to that point. **Frame ship** returns to orbit.
5. **Save JSON** writes setup to this package's `boat.json`. It preserves unrelated top-level fields,
   including the existing physics tuning. Known setup objects/arrays are rewritten. Changes apply
   on the next voyage, not to a boat already running in the world.
6. **Close / discard unsaved** discards unsaved configuration changes. It does not undo earlier saves.

The preview has no boat simulation or collision and is destroyed on close. It is currently a standalone/singleplayer authoring tool.
The source FBX is not changed by this tool.

Before a save, the previous JSON is copied to `Saved/ShipSetupBackups/<id>/boat-<unique-id>.json`.
If the manifest changed since opening, the save is rejected: close and reopen Ship Setup.
Read-only installations cannot be edited until the mod directory is writable. Backups are outside
the Mods directory and therefore are not automatically included in a new package.

 

# Propellers and rudders: one FBX, separate objects

Recommended authoring convention:

- Hull/superstructure: ordinary static objects.
- `Prop1`, optionally `Prop2`: individually selectable propeller mesh objects.
- `Ruder1`, optionally `Ruder2`: individually selectable rudder mesh objects.

Export the objects **together in the main ship FBX**. Do not combine them into one hull mesh. Each name
must be unique. Apply export scale/orientation consistently and triangulate. All vertices should remain
in the ship's assembled positions. Empty helper nodes are not visible propeller/rudder meshes.
The editor dropdown can map other object names; names are matched case-insensitively. Missing,
ambiguous or already-used names skip animation rather than preventing the boat from loading.
Select **None** when no visual model is available. The physical propulsion/rudder points still work.

There is no requirement to supply these meshes immediately. The current ferry can use its existing
FBX until the propeller/rudder objects are modelled. Separate extra FBX files are not imported by this
version. They can be supported later, but would also need explicit transforms, scale and material paths.

Each part has two points:

- **Force**: where the existing boat physics applies propulsion/rudder forces.
- **Pivot**: the rotation centre of the visible object. It need not equal the force point.

`axis` and `direction` control **cosmetic animation**, not an azimuthing thrust direction. The axis is
in boat coordinates, nonzero and normalised on save; +X is typical for shafts, +Z for rudders.
Use +1 or -1 for direction. **Toggle animation** tests the pivot and direction without running physics.
During a voyage, propellers follow engine RPM/drive direction and rudders follow steering input.
The native propeller animation speed scale remains 0.2. Two engines split `thrustKN` equally;
adding the second engine does not double the configured total thrust. The normal two-engine UI is reused.

 

# Mooring and fenders

**+ Mooring point** creates a station that works with the existing O / Ctrl+O mooring interface.
Set position, label, rope diameter, maximum length and breaking load. Up to 32 stations are supported.

**+ Fender** adds a standard small rubber-fender representation (an elongated sphere), plus a separate
**rope top** marker. Position the centre alongside the hull and the rope top on the rail/attachment.
The wire outline in the preview shows the configured size. Port/starboard chooses the control group;
changing the side button also sets yaw to face outboard. Local +X must face away from the hull, +Z up.
The runtime component reuses the existing deployment, contact and cosmetic pendulum logic. Its visible
rope ends at the fixed ship attachment and it adds no separate rigid-body mass. Up to 32 fenders.
Custom fender mesh files and large quay-fender authoring are not part of this ship-setup extension.

 

# Sounds and preview images

Select **Engine sound** or **Horn sound** to edit sound filenames and attenuation. Files are relative
to the boat folder. Use forward slashes, for example `Sounds/engine.wav`; absolute paths, `..` and
backslashes are rejected. Empty fields are allowed. A missing/unsupported WAV is skipped with a warning.

- Supported audio: uncompressed PCM16 WAV, mono/stereo, 8–96 kHz, at most 16 MiB and 120 seconds each.
- Prefer **mono** for spatial localisation. Supply engine start, seamless running loop, engine stop
  and horn as separate files. The two engines have independent playback cursors but share the configured
  engine sound position in this version. No sound assets are supplied/generated by the code.
- Attenuation inner radius and falloff are in centimetres; volume is 0–2.
- Supported selection image: PNG, at most 2048 × 2048 and 8 MiB. When the `preview` field is missing
  or empty, `preview.png` beside `boat.json` is used automatically. Explicit filenames take priority;
  an invalid/missing explicitly selected image does not silently fall back to another file.
  Reopen ship selection after copying an image into the package folder.
- **Create preview PNG** captures the current ship-only view without markers to a unique new PNG in
  the package. Then press **Save JSON** to assign it. Existing images are not overwritten. The generated
  PNG remains on disk even if you close without saving the configuration; remove unused captures manually.

 

# JSON fields (optional extension to schemaVersion 1)

Existing schema-1 manifests still load with one physical propeller and rudder and their legacy points.
Retain the required legacy `cameraCm`, `propellerCm`, `rudderCm` fields. The editor keeps the latter two
in sync with the first array entries. New fields can be added to the existing object; this fragment is
not a complete manifest and its coordinates are examples, not calibrated positions for the ferry

Positions/sizes are boat-local centimetres (+X bow, +Y starboard, +Z up), **after** the presentation
model's scale/offset/rotation. Rotation arrays are pitch, yaw, roll in degrees. These setup settings do
not automatically compute hull collision, displacement or stability. Keep the existing tuned values.

 

# Imported-ship handling settings

Ship Setup now has four English-language sections: **Performance**, **Rudder**, **Heeling**,
and **Resistance**. These expose the existing native BoatPawn controls, not a new physics model
or automatic copying from a Blueprint boat. Save with **Save JSON**, then start a new voyage.
Blueprint boats and the existing imported-ship buoyancy coefficients are unchanged.

- Performance: total/per-shaft thrust, reverse thrust, RPM response, thrust exponent, optional
  low-speed boost, engine-start immersion requirement and speed limiting.
- Rudder: angle, actuator speed, lift/force limits, propeller wash and each rudder's physical area.
  Length and height are full centimetre dimensions; they do not resize the visible mesh.
- Heeling: None, Inward or Outward turn heel, strength, maximum angle, response/return times
  and minimum speed. This is turn-induced heel, not wave damping.
- Resistance: lateral grip, three-point resistance and its yaw contribution/weights, plus
  linear/angular damping. Angular damping affects all rotation, including roll and pitch.

An optional `handling` object uses the exact C++ property names shown below each control.
Only edited overrides are stored. **Default** removes that override and restores the native
default; per-shaft thrust instead falls back to an equal share of root `thrustKN`.
Root `thrustKN`, `linearDamping` and `angularDamping` are saved from their own controls.
Second-shaft/second-rudder settings require two corresponding attachment entries.
Native force values are Unreal force units: **1 kN = 100,000 UE units**.

Example fragment (illustrative values):

 

 

[MarkoBarthel]

JSON parameters that can be used for adjusting the physics for your custom watercrafts.

 

Performance

- Total thrust fallback (kN): Total propulsion force, divided equally between the configured propellers unless individual thrust values are set.
- Max Forward Thrust / Second Max Forward Thrust: Maximum forward force for each propeller. These use Unreal force units: 100,000 units = 1 kN.
- Reverse Thrust Scale: Reverse power relative to forward power. For example, 0.5 provides 50% reverse thrust.
- Engine Idle / Maximum RPM: The engine’s idle and maximum operating speeds.
- RPM Acceleration / Deceleration: How quickly engine speed increases or decreases.
- Use RPM Based Thrust: Makes propulsion depend on engine RPM.
- Propeller Thrust Exponent: Shapes the power curve. Lower values provide more thrust at partial power; higher values make the response gentler.
- Low Speed Thrust Boost: Adds extra thrust at low vessel speeds. The multiplier controls its strength, and the fade-out speed determines when it disappears.
- Safe RPM Direction Change: Requires the engine to slow down before changing between forward and reverse.
- Maximum Speed: Sets the speed limit in knots. The limiter start fraction determines when thrust reduction begins; the hard limit prevents further acceleration beyond the limit.
- Propeller Immersion / Start Requirement: Controls how deeply the propeller must be submerged to permit engine starting.
- Thrust Height Relative to COM: Vertical offset of the thrust application point from the centre of mass. Changing this can affect pitching under power.

 

Rudder
- Maximum Rudder Angle: Maximum steering angle in degrees.
- Rudder Actuator Delay / Movement Speed: Enables gradual rudder movement and sets its turning speed in degrees per second.
- Rudder Length / Height: Defines the physical rudder area. Larger dimensions generally produce stronger steering forces. These values do not resize the visible model.
- Rudder Lift Coefficient: Controls the rudder’s hydrodynamic effectiveness.
- Maximum Rudder Force: Caps the force generated by the rudder.
- Water Density: Density used for rudder-force calculations.
- Propeller Wash: Adds the effect of propeller flow over the rudder, improving steering at low vessel speeds. Its speed and fade-out settings control the strength of this effect.
Second-propeller and second-rudder settings require corresponding attachment points.

Heeling
These settings control leaning during turns, not wave-induced rolling.
- Turn Heel Direction: None disables turn heel, Inward leans into the turn, and Outward leans away from it.
- Turn Heel Strength: Scales the amount of leaning.
- Maximum Turn Heel: Limits the heel angle in degrees.
- Heel Response Time: How quickly the ship leans into a turn. Longer times give a slower response.
- Heel Return Time: How quickly the ship returns upright after turning.
- Minimum Heel Speed: Vessel speed below which turn heel is disabled.

Resistance
- Lateral Grip / High-Speed Lateral Grip: Controls resistance to sideways movement.
- Maximum Lateral Resistance Force: Caps sideways resistance.
- Three-Point Lateral Resistance: Distributes resistance between the bow, midship and stern.
- Longitudinal Coverage: Controls how far apart these resistance points are along the hull.
- Yaw Scale: Controls how strongly distributed resistance opposes turning. Lower values allow the ship to continue turning longer after the rudder returns to neutral.
- Bow / Midship / Stern Weights: Adjust the relative contribution of each resistance point.
- Linear Damping: Reduces movement in all directions, not just sideways.
- Angular Damping: Reduces rotational movement, including turning, rolling and pitching. Excessive values can make the ship feel unnaturally stiff.

Units and defaults
Distances are in centimetres, angles in degrees, times in seconds, and vessel speeds in knots, unless the field specifies otherwise.
Default removes an individual override. It restores the built-in fallback—not your previous custom value. Existing buoyancy settings remain unchanged unless edited separately.