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.

[MarkoBarthel]

Optional text block for bow- stern wake and bow srpay effect.

 

 

[MarkoBarthel]

With version 0.0.23 different light systems like navlights, anchor lights and towing lights are added to the ship editor. Also now possible to add bridge lights, work lights and exterior lights to your watercraft.

 

Add the entries to the existing top-level `bridgeEquipment` array in your ship configuration. Keep all other ship settings and existing equipment. Do not create a second `bridgeEquipment` key.

The combined example below is an equipment section, not a complete ship configuration. Replace its example positions and FBX object names with those for your ship.

- Each entry needs a unique `id`.
- Positions use centimetres in ship-local coordinates: **+X forward, +Y starboard, +Z up**.
- `rotationDeg` is `[pitch, yaw, roll]` in degrees.
- `mesh` identifies an FBX object by name, not a file path or material name. Use unique object names.
- The array supports up to **64 entries in total**, including instruments, controls, lights and antennas.
- Save the configuration and reload the ship to apply changes. The ship editor shows placement markers for lights, rather than a live lighting preview.

 

Merge the entries in this array into your existing `bridgeEquipment` array:

Use `type: "NavigationLight"` and select the light's role with `action`. With `lightRoleDefaults: true`, the existing navigation light system supplies the role's colour and visibility sector.

 

| Role (`action`) | Purpose |
| --- | --- |
| `PortSidelight` | Red port sidelight |
| `StarboardSidelight` | Green starboard sidelight |
| `Sternlight` | White sternlight |
| `ForwardMasthead` | Forward masthead light |
| `AftMasthead` | Aft masthead light |
| `ForwardAnchor` | Forward or single anchor light |
| `AftAnchor` | Aft anchor light |
| `TowingMastheadSecond` | Second light in the towing masthead group |
| `TowingMastheadThird` | Third light in the towing masthead group |
| `TowingYellow` | Yellow towing light |
| `FishingUpper` | Upper fishing light; colour follows fishing mode |
| `FishingLower` | Lower fishing light |
| `FishingAdditionalMasthead` | Additional fishing masthead light |
| `FishingGearDirection` | Fishing gear direction light |

 

Roles are switched by the existing **Off, Navigation, At Anchor, Towing and Fishing** modes. Some roles depend on vessel length and the native towing/fishing settings. Adding a role does not mean it is enabled in every mode. Imported vessel length is taken from the configured hull length

For example, a larger vessel can add `AftMasthead` and `AftAnchor` entries at appropriate positions.

 

Optional lens mesh

Without `mesh`, a navigation light uses a small sphere as its lens. Set its radius with `lightRadiusCm`.

With `mesh`, the selected FBX material slot is replaced by the supplied lamp material, and the sphere is removed. **Use a dedicated lens material slot, not a slot shared by the lamp housing or the entire ship.** Slot numbering starts at **0**. The source FBX file is unchanged.

Missing or ambiguous mesh names, invalid slots and duplicate mesh/slot assignments are skipped and logged. If a navigation lens assignment cannot be made, the fallback sphere remains.

 

Custom colour and sector

Set `lightRoleDefaults` to `false` to use `color`, `lightArcDegrees` and `lightSectorYaw`. Sector yaw is measured relative to the ship's forward axis; rotating the placement marker alone does not rotate the sector. Fishing mode can override fishing-light colours through the existing native logic.

 

Bridge, work and exterior lights

| Equipment type | Lighting group / radial menu entry |
| --- | --- |
| `BridgeLight` | Bridge |
| `DeckLight` | Deck Work |
| `ExteriorLight` | Exterior |

These types create point lights that illuminate nearby surfaces. `lightIntensity` is measured in **lumens**, and `lightRangeCm` controls their reach. Shadow casting is optional and disabled by default.

They also support an optional `mesh` and `lightMaterialSlot` to illuminate a lens using `lightEmissive`. This replaces only the selected material slot, just as for navigation lights. Without a lens assignment, the point light still illuminates its surroundings.

 

Light fields

| Field | Default | Allowed values / meaning |
| --- | --- | --- |
| `color` | `[1, 1, 1]` | RGB components, each 0–1 |
| `lightIntensity` | `500` | 0–100000 lumens; group lights only |
| `lightRangeCm` | `500` | 1–100000 cm; group lights only |
| `lightRadiusCm` | `3` | 0.1–100 cm; fallback navigation lens radius or point-light source radius |
| `lightEmissive` | `25` | 0–1000; lens emission strength |
| `lightCastShadows` | `false` | Point-light shadow casting; group lights only |
| `lightRoleDefaults` | `true` | Automatic navigation colour and sector |
| `lightArcDegrees` | `360` | 0.1–360 degrees; custom navigation sector |
| `lightSectorYaw` | `0` | −180–180 degrees; custom navigation sector centre |
| `lightMaterialSlot` | `0` | Integer 0–63; must also exist on the assigned mesh |

 

Light controls and power

The radial menu continues to work. Its navigation modes and Bridge / Deck Work / Exterior commands control the same systems as assigned bridge switches.

- Battery-powered ships require the battery master to be on and the battery to have charge.
- On ships using the ship power network, navigation and bridge lights use UPS supply by default; deck and exterior lights use the main bus by default.
- Individual imported lamps do not add a separately configured electrical load. Existing electrical-system loads still apply.

[MarkoBarthel]

Also new feature would be to add the radar antenna to your watercrafts.

 

Radar display

`type: "Radar"` adds an interactive 3D radar display. Set its size with `widthCm` and `heightCm`, and its local brightness with `brightness` (0–1).

The display's local **+X faces the viewer**, and **+Z is screen up**. Adjust `rotationDeg` to match the console.

Radar needs electrical supply, an enabled radar circuit and the radar device switched on. The UI and 3D instrument provide the device power control and share its state.

 

Rotating radar antennas

`type: "RadarAntenna"` animates an existing FBX object. It does not create antenna geometry or a separate radar sensor.

| Field | Meaning |
| --- | --- |
| `mesh` | Unique FBX name of the rotating scanner only |
| `positionCm` | Rotation pivot in ship-local centimetres |
| `rotationDeg` | Orientation of the pivot |
| `axis` | Local rotation axis; `[0, 0, 1]` is vertical for an unrotated pivot |
| `rotationDegrees` | Rotation speed in **degrees per second**, despite the field name |

`rotationDegrees` defaults to `45` and accepts −720 to 720. Negative values reverse rotation; `0` stops it. `axis` must be nonzero and is normalized automatically.

Assign only the moving scanner, not its stationary base. The pivot must be positioned at the scanner's rotation shaft. Mesh placement is preserved when it is attached to the pivot.

You can add multiple antenna entries with unique IDs and separate meshes. They can rotate at different speeds and in different directions, but all follow the ship's shared radar power state. They stop when the radar device, circuit or supply is off. Meshes already assigned to another moving control, propeller or rudder cannot be assigned again as an antenna.