Boats
Module PulseWaterBoat. A boat floats on the same waves the ocean shows, carries players who walk on its deck and is steered from its helm or from a driver seat. Its movement is predicted on the driving client and simulated by the server, like the movement of a character.
Parts
| Class | Purpose |
|---|---|
UPulseWaterBoatDefinition | Data asset: mass, hull size, pontoons, drag, propulsion, rudder and control speeds. |
APulseWaterBoat | The boat pawn. The root Hull is the collision characters walk on, meshes go below VisualRoot. |
UPulseWaterBoatMovementComponent | Physics and networking of the boat. |
UPulseWaterBoatSeatComponent | A seat (driver or passenger), placed in the boat Blueprint. The driver seat is also the helm. |
UPulseWaterBoatControllerComponent | On the player controller: steering from the helm without possessing the boat. |
UPulseWaterBoatSailComponent | Visual pivot of a sail at the mast: turns the sail meshes to the boom angle and shows how far the sail is set. |
UPulseWaterHullComponent | On every boat (HullState): health, leaks and the water in the hull. |
UPulseWaterBoatModifier | Data asset: an upgrade that changes values of the definition. |
FPulseAdjustment_BoatHull | Adjustment of a tuning source: a weaker or sturdier hull for a difficulty or the server rules. |
Physics
The boat is a rigid body moved by the plugin, not by the physics engine:
- Buoyancy: every pontoon is a sphere. The part below the water surface pushes up with the weight of the displaced liquid (the density of the liquid at the pontoon;
WaterDensityof the definition only weighs the water in the hull). The pontoons together must be able to carry more thanMass, or the boat sinks; the data validation of the definition checks this. - Drag: water drag acts at each pontoon against the moving water, separately along the boat’s forward, side and up axes (
LinearDrag,QuadraticDrag). Low forward and high side drag let the boat go straight instead of drifting. - Propulsion pushes at
ThrustLocationwhile that point is under water. - Rudder: a torque around the up axis that grows with the forward speed (
SteeringReferenceSpeed,SteeringAtRestfor turning on the spot) and lets the boat lean into turns (TurnLean). - Collision with the world is a box sweep of
HullSizethat ignores pawns, so the crew never stops the boat.
The water is queried with the water time of each move (UPulseWaterSubsystem::QueryWaterBatchAtTime), so the server and the client compute a move with exactly the same waves.
Controls
The throttle and the rudder are part of the boat’s state and replicated with it. ControlMode on the movement component decides how input drives them:
- Lever (default): the input moves the throttle lever (
ThrottleChangeSpeed) and turns the wheel (RudderChangeSpeed). When the input stops, both stay where they are and the boat keeps going, also when nobody is at the helm.RudderCenteringSpeed> 0 lets the rudder return to the center on its own. - Direct: the input is the throttle and the rudder position, like walking: releasing the input takes the throttle away and lets the rudder return.
SetControls sets both positions directly on the server, e.g. for a “full stop” button or AI.
Sailing
A definition with SailArea > 0 has a sail. The wind comes from the environment at the sail; the sail sees the apparent wind, the wind minus the boat’s own motion.
- Sail state:
SailTrim(0 = sheeted in, the boom on the centerline; 1 = eased out toMaxSailAngle) andSailRaise(0 = lowered, 1 = fully set) are part of the boat’s state, like throttle and rudder. - Input: the sail inputs (
SetSailTrimInput,SetSailRaiseInput, also on the controller component) move the sail atSailTrimSpeed/SailRaiseSpeedin both control modes. Like ropes, the sail stays where it is when the input stops.SetSailsets both directly on the server;InitialSailRaise/InitialSailTrimon the movement component set them when the boat spawns. - Force: a flat plate model. The boom swings to the side the wind blows to, as far as the trim lets it; the sheet is a rope, so with the wind further ahead than that the boom follows the wind and the sail luffs. Lift (
SailLift, strongest at an angle of attack of 45 degrees) acts across the wind, drag (SailMinDragtoSailMaxDrag) along it. The force acts atSailCenter, so a side wind heels the boat; the side drag of the pontoons works as the keel and turns the rest into forward motion. Head to wind the sail gives no forward force, before the wind it pushes with its drag. - Trimming: on a beam reach a trim around 0.5 works best, close to the wind sheet in, before the wind ease out.
GetSailAngleandGetApparentWindhelp to build a wind vane or trim hints.
The plugin ships DA_PulseWater_SailBoat and BP_PulseWater_SailBoat (the test boat with a mast and a 20 m^2 sail).
Hull, damage and sinking
Every boat has a UPulseWaterHullComponent (GetHullState). The server runs it; health, water and leaks replicate.
- Damage:
ApplyHullDamage(Damage, WorldLocation, Instigator)costs health (reduced byArmor) and makes a hole at the hit,LeakAreaPerDamagecm^2 per point of damage (at mostMaxLeakArea). Hits withinLeakMergeDistanceof a hole make that hole bigger. Holes lie within the hull: the hull box together with the pontoons (GetHullBounds). - Flooding: water runs in through every hole below the outside water surface:
LeakDischarge * area * sqrt(2 g depth), slower as the hull fills up. The bilge pump takesBilgePumpRatekg/s out. A hole above the waterline lets nothing in, until the boat lies deeper. - Weight: the water weighs where it ran in (at the bottom, below the holes): the boat lies deeper and lists towards the damaged side. When the hull holds more water than the pontoons can carry (
GetFloodCapacity), it sinks. - Repair:
RepairLeaks(WorldLocation, Radius, Area, Instigator)closes holes near a location,PumpOut(Mass)takes water out (a bucket),RepairHull(Amount, Instigator)restores health; the instigator is optional and reaches the events.FindNearestLeak(WorldLocation, MaxDistance)finds the hole nearest to a player on every machine, for the prompt of a repair interaction. With PulseGameplay, the bridge PulseWaterGameplayBridge makes patching leaks and repairing the hull an interaction that costs items: see Shipyard and repairs. - Events:
OnDamaged,OnLeaksChanged,OnLeaksRepaired(server: area, location and who repaired),OnWrecked(health 0, the game decides what happens),OnSunk(the whole top of the hull under water forSinkTime) andOnCapsized(upside down forCapsizeTime). C++ and bridges bind the native versions with the same names plusNative(OnDamagedNative,OnSunkNative, …).
The movement uses the replicated water mass, so the predicting client and the server simulate the same weight. Damage sources (weapons, rocks, monsters) and their numbers belong to the game; they only call ApplyHullDamage.
The tuning knob Pulse.Tuning.Water.HullDamage of PulseFoundation multiplies every damage before the armor, and with it the size of the holes, so a difficulty or the server rules make boats sturdier or weaker. The boat is the target of the context, its definition the source, the attacker the instigator.
Damage of PulseGameplay combat reaches the hull through the attribute contract and is tuned twice: once by the damage tuning of combat, then again by Pulse.Tuning.Water.HullDamage. Leave one of the two knobs at 1 for boats, or give the hull knob a filter, when both should not apply.
Health for every Pulse plugin
The hull is also the attribute source of its boat (IPulseAttributeSource of PulseFoundation). Combat, AI, quests, conditions, costs and health bars read and change the health of a boat through it, the same way as the health of a character, without knowing boats. The hull keeps its own rules; the attributes only show them:
| Attribute | Kind | Read | Change |
|---|---|---|---|
Pulse.Stat.Health | Pool from 0 to the MaxHealth of the definition | The hull health on every machine; Depleted while wrecked | See below |
Pulse.Stat.MaxHealth | Stat | MaxHealth of the definition with its upgrades and hull adjustments | Refused: change the definition or add an upgrade |
- Add (and AddPercentOfMax) goes through the hull rules. A loss is damage like
ApplyHullDamage: the tuning knob, the armor, and a hole atContext.Locationwhen the change has a location (damage of PulseGameplay combat has one). A gain is a repair likeRepairHull, up to the maximum. The context (instigator, causer, damage tags) reaches the tuning and the attribute events. - Set, SetPercentOfMax and Reset (to
MaxHealth) put the health there directly, without armor or holes: cheats, respawns and scripted scenes. - Modifiers are refused; armor and upgrades stay in the definition.
Every change of the health, also through ApplyHullDamage, RepairHull and SetHullState, is an attribute event:
Pulse.Message.Attribute.Changedon the server, and on clients when the replicated health arrives.Pulse.Message.Attribute.Depletedwhen the hull is wrecked, thenOnWreckedandPulse.Message.Water.BoatWrecked; the hole, the instigator and the hit of the damage are already there when the events come.Pulse.Message.Attribute.Restoredwhen a repair brings it back above 0. On clients, watches and wait nodes get theDepletedandRestoredevents too when the replicated health crosses 0 (withCatchUp = Replication); thereOnWreckedfires first, when the health arrives, and thenChangedandDepleted. The messages come from the server through the message relay.- An upgrade or a hull adjustment that changes
MaxHealthsendsChangedforPulse.Stat.MaxHealthand forPulse.Stat.Healthwith the newMax, on every machine, so health bars show the new maximum at once. A health above a lower maximum comes down to it on the server. - A loaded state (
ApplySaveState,SetHullState, a loaded save) sends them withCatchUp = Load: the maximum of the saved upgrades first, without a clamp, then the saved health. A boat saved as a wreck isDepletedagain, butOnWreckedand the wrecked message do not fire again.
So Pulse::Combat::IsAlive is false for a wrecked boat, a health bar or a wait node shows the hull, and a condition “Health below 30 %” works on boats. The attribute debugger lists the hull as source Boat Hull.
The hull answers only for its boat (bOwnActorOnly in its capabilities): the controller and the player state of the driver do not reach it. While someone drives, their controller reaches only attributes on their player state (none when they live on the character, which the controller does not possess while it drives). So a wrecked boat does not kill its driver: a HUD that watches the controller never sees the hull, and the respawn of PulseGameplay treats the possessed boat as a vehicle, not as the body of the player, so boarding a wreck or the wreck of the boat while driving is no death (with both death sources).
Pulse Water sends no other attributes (no stamina, no hunger). An actor has one attribute source: a boat Blueprint that gets another one (a Pulse Attributes component) logs a warning, and the first source answers.
Upgrades
A UPulseWaterBoatModifier changes values of the definition: mass, buoyancy, thrust, steering, drag, sail area, health, armor, leak size and bilge pump. APulseWaterBoat::SetModifiers / AddModifier (server) apply them in order to a copy of the definition (GetEffectiveDefinition); the list replicates, so every machine simulates the same upgraded boat. For upgrades the fields do not cover, derive from UPulseWaterBoatModifier in C++ and override Apply.
Building boats in a game is: a boat type (a Blueprint with its definition) plus a list of upgrades. Which upgrades exist, what they cost and when they unlock is up to the game. With PulseGameplay, PulseWaterGameplayBridge builds boats at a shipyard through crafting (a boat item with its upgrades as the output of a recipe): see Shipyard and repairs. The plugin ships two examples: DA_PulseWater_Upgrade_Engine and DA_PulseWater_Upgrade_ArmoredHull.
Hull adjustments and swaps
A difficulty, the server rules or an event change boats through the adjustments of a tuning source of PulseFoundation, without a bridge and without changing the assets:
- Boat Hull (
FPulseAdjustment_BoatHull) changes the hull of one boat type (Boat) or, withBoatempty, of every boat:MaxHealthFactor(health),ArmorBonus(added to the armor),LeakFactor(size of the holes damage makes,LeakAreaPerDamage) andBilgePumpFactor(bilge pump rate). Several adjustments multiply their factors and add their armor bonuses; then the armor is clamped to 0..1 and the health kept at 1 or more, so their order does not matter. - Swap Asset (
FPulseAdjustment_Swapof PulseFoundation) with a boat definition asOriginalmakes every boat that names it use theReplacementinstead (a heavier hull on a hard level). Make the replacement a variant of the original, so it keeps everything that is not changed.Definitionof the boat stays the asset it names; the hull adjustments count for the boat type that is used, the replacement.
The boat builds its effective definition (GetEffectiveDefinition) in this order: the definition or its swap, then a copy of it with the upgrades in their order, then the hull adjustments. Without upgrades and hull adjustments there is no copy (with only a swap the boat uses the replacement itself). When a source changes adjustments or the difficulty (Pulse.Message.Tuning.Changed), every boat builds it again on every machine: the tuning replicates, so the server and the clients get the same definition. A new maximum health sends the attribute events above; a health above a lower maximum comes down to it, a higher maximum keeps the health. The context of the adjustments has the boat as the target and its definition as the source and names no player: personal sources do not change boats, because a boat has to be the same on every machine. For the same reason give boat adjustments tags or conditions that every machine decides the same way (a condition a client cannot decide counts as not passed there).
Pulse.Tuning.Water.HullDamage stays a knob: it scales the damage, the hull adjustments scale the hull.
In the editor, the before and after panel of a tuning source or preset shows what a Boat Hull adjustment with a boat type makes of that definition (health, armor, holes, pump).
C++ (PulseWaterBoatAdjustments.h, namespace Pulse::Water::Boat) | What it does |
|---|---|
ReadHullValues(Definition) | The hull values of a definition as an FPulseWaterHullValues (MaxHealth, Armor, LeakAreaPerDamage, MaxLeakArea, BilgePumpRate). |
WriteHullValues(Values, Copy) | Writes them into a transient copy. |
AdjustHullValues(Values, Adjustments) | Applies Boat Hull adjustments to values (pure). |
CollectHullAdjustments(Data, Boat, Context) | The Boat Hull adjustments of the tuning for a boat type and those for every boat, in order. |
GetHullValues(Data, Boat, Context) | The hull values of a boat type as the tuning wants them, without upgrades (menus, a shipyard). |
ApplyHullAdjustments(Data, Boat, Copy, Context) | Applies the hull adjustments of a boat type to a copy of its definition; true if a value changed. |
Saving and loading
APulseWaterBoat::GetSaveState returns an FPulseWaterBoatSaveState: boat class, transform, upgrades, hull health, water and leaks, the positions of throttle, rudder and sail, and the extras of other systems (cargo, fuel). Its properties are marked SaveGame, so any save system can store it. ApplySaveState restores it on an existing boat, SpawnBoatFromSaveState spawns a boat from it (server).
Boats also save themselves as bytes (IPulseByteSaveable of PulseFoundation), so PulseSave and other byte save systems keep them without a bridge: placed boats by their level and name, boats spawned at runtime through UPulseWaterBoatSaveSubsystem. See Saving with PulseSave.
Cheats
| Cheat | Meaning |
|---|---|
PulseWaterBoatDamage [damage] [all] | Damages the boat nearest to the view (or every boat with all) at the lowest point of its left side (default 200). |
PulseWaterBoatInfo | Prints health, water, inflow and leaks of the boat nearest to the view. |
PulseWaterBoatRepair | Repairs the boat nearest to the view and pumps it dry. |
They run on the server for the player who typed them: in Play In Editor in the game console of a player window (a client types EnableCheats first), or with Pulse.PIE.Exec <instance> <cheat> in the editor console.
Steering from the helm
A player stands at the driver seat (within HelmRange) and keeps walking as their character. Add a UPulseWaterBoatControllerComponent to the player controller (or turn on Boat Controller Component in Project Settings > Pulse > Water Boats, which adds it to every player controller) and call its SetThrottleInput / SetRudderInput from your input bindings while the player is at the helm. Only changes are sent to the server, which checks APulseWaterBoat::CanUseHelm and releases the helm when the player walks away. Other clients see the boat through the replicated state; because the controls move smoothly, the delay of the server is hardly visible.
Driving from the driver seat
EnterSeat with the driver seat attaches the pawn and lets its controller possess the boat. Bind input on the boat (SetThrottleInput, SetRudderInput of the movement component) and call ServerExitDriverSeat to leave. The driving client predicts the boat:
- It simulates every frame with its input and sends the newest unconfirmed moves to the server (unreliable, with redundancy).
- The server simulates the moves with their water time and compares the result. If the client is off by more than
CorrectionThreshold, it sends its state back; the client resets to it and replays the moves the server has not seen yet. Otherwise it confirms the moves. - If the driver’s moves stop for
ServerForceUpdateTime, the server keeps the boat going on its own.
The server never trusts the timing of the moves (Pulse::Water::Boat::PlanServerMoves):
- It looks at the newest 16 moves of an update only and drops moves that are shorter than 4 ms, longer than 0.1 s, not finite or more than a second ahead of its water time. The driving client gathers frames shorter than 4 ms into one move.
- A move that overlaps water time the server has already simulated (resent moves, the time the server kept the boat going on its own) is shortened: it starts where the server stopped. No water time is simulated twice.
- A time budget fills with the water time that passes on the server, up to
MoveTimeTolerance(0.25 s): a driver cannot send more simulated time than the server’s time plus the tolerance. Moves beyond it are not simulated; the driver is corrected. Together this keeps a modified client from moving its boat faster than time goes on.
Corrections should stay at 0: stat PulseWater counts them (Boat Corrections), and the Water page of the Pulse Debugger lists them per boat with the size of the last one and the moves the driver replayed; the timeline has an event for each (Correction).
Other clients get the state and keep simulating it locally with the last input; corrections are smoothed out on VisualRoot over SmoothingTime. Beyond the boat simulation distance of the quality level they only move on with the velocity of the last update (see Quality and performance).
Walking on deck
Characters stand on the Hull collision and ride along through the character movement’s based movement; the boat moves before the characters in the frame (TG_PrePhysics). Passengers can also sit: EnterSeat with a passenger seat attaches them and turns off their movement and collision (bDisableOccupantCollision); ExitSeat places them at the seat’s ExitLocation. Seat changes are replicated and announced with OnSeatChanged (OnSeatChangedNative in C++).
Setting up a boat
- Create a Pulse Water Boat Definition and adjust mass, hull size and pontoons to the hull.
- Create a Blueprint of
APulseWaterBoat, set its Definition, give theHulla collision mesh and put the visible meshes belowVisualRoot. - Add a Pulse Water Boat Seat component with role Driver at the helm and passenger seats as needed.
- Spawn the boat on the server; it replicates.
The same definition must be used on the server and all clients.