Importing your own watercrafts - Quick Guide

[MarkoBarthel]

Ahoi 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.

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

 

Ship Setup — imported ships only

# 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. No Blueprint boat assets
or their buoyancy settings are changed. 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):