Swimming

Characters swim in the water of the Pulse Water queries: in the ocean with its waves, in lakes and rivers, in fluid volumes and in water in caves below the sea level. They need no water physics volumes. A character swims once enough of it is under the surface, floats with its head above it, dives with input down, is carried along by the current of a river or a fluid, and floats higher in denser liquids. Liquids that cannot be swum in keep it out.

Class Purpose
UPulseWaterCharacterMovementComponent The character movement component of the engine that swims in Pulse Water, predicted in multiplayer.
APulseWaterCharacter An ACharacter with that component, for Blueprint characters (Pulse Water Character).
UPulseWaterSwimComponent The water at an actor for games with a movement of their own: state, events and messages, no movement.
FPulseWaterSwimSample The water at a body at one moment: how deep it is in, the surface, the current, the head, the liquid.
UPulseWaterWetnessComponent Wet clothes and the waterline of hulls for the materials of an actor.

Set up a character

  • Blueprint characters: make the character a child of Pulse Water Character (APulseWaterCharacter) instead of Character. A Blueprint cannot change the movement component of Character itself.
  • C++ characters: give your character class the component in its constructor:
AMyCharacter::AMyCharacter(const FObjectInitializer& ObjectInitializer)
	: Super(ObjectInitializer.SetDefaultSubobjectClass<UPulseWaterCharacterMovementComponent>(ACharacter::CharacterMovementComponentName))
{
}

The module is PulseWaterCharacter; add it to the dependencies of your module.

How it swims

At the start of every move the component queries the water at the middle of the capsule:

  • In and out: the character swims once Enter Water Immersion (60 %) of its capsule is under the surface and stops below Exit Water Immersion (35 %). The gap keeps it from flickering between swimming and falling at the surface.
  • Floating: the buoyancy (Buoyancy, 1.3 by default) carries it until about 77 % of the capsule is under water: the head is above the surface. With waves the surface moves and the character with it. Surface Damping calms the bobbing at the surface while there is no input up or down.
  • Diving: input with a downward part (moving where the camera looks, or an axis of your own) takes it under; it comes back up on its own. The engine settings of swimming apply: Max Swim Speed, Max Acceleration, braking.
  • Current: the water of rivers and fluid volumes takes the swimmer along: Current Drag (per second) is how fast it reaches the speed of the water; its own swimming adds to that. The friction of the water (Water Friction, in place of the fluid friction of a physics volume) acts relative to the current.
  • Liquids: a liquid type that is not Swimmable (lava) keeps the character out: it falls through it. Denser liquids carry it higher (Buoyancy From Density), thicker ones (Viscosity) slow it more (Viscosity Friction).
  • Head: the eyes are at Head Height (80 % of the half height above the middle). The head is under water when the surface is above them.

The component replaces the swimming of the engine (PhysSwimming) with the same rules on top of the queries. The engine’s own swimming needs a water physics volume and switches to falling after every step without one.

Multiplayer

Every move of a client carries the water time it ran at (FPulseWaterCharacterNetworkMoveData), so the server simulates the move in the same waves as the client; replays after a correction use the water time of their move. Moves at water are not combined, so each keeps its time. A water time further than Max Move Water Time Error (1 s) from the server’s is not trusted: the server uses its own.

In a test with a listen server and a client in the waves of the example map, the client’s swimmer got one correction of 5 cm in 43 seconds of swimming (the engine corrects from 1.7 cm on).

Characters without a controller (AI, a test) get their first movement mode only if Run Physics With No Controller is on when they spawn; set it in the class defaults, or call SetDefaultMovementMode after turning it on.

Events and messages

Event When
On Started Swimming The character starts swimming.
On Stopped Swimming It stops swimming (out of the water, or MOVE_None).
On Head Under Water Its head goes under the surface.
On Head Above Water Its head comes back up, with the seconds it was under (Time Under Water).

The events fire on every machine that has the character (server, owning client, other clients); they are information only, the component deals no damage (for breath and drowning see Breath and drowning). Get Time Under Water gives the seconds of now, e.g. for a rule of your own, Is Head Under Water and Get Swim Sample the rest. On the authority the messages Pulse.Message.Water.StartedSwimming, .StoppedSwimming, .HeadUnderWater and .HeadAboveWater go out with an FPulseWaterSwimMessage.

Breath and drowning

While the character swims it has the tag Pulse.Water.State.Swimming, while its head is under the surface Pulse.Water.State.HeadUnderWater. Both components (UPulseWaterCharacterMovementComponent and UPulseWaterSwimComponent) give them through IGameplayTagAssetInterface, so every system that reads the tags of an actor sees them, and on the authority they call Pulse::Attributes::NotifyOwnerTagsChanged when the state changes. That is all an attribute of Pulse Foundation needs: a rate override with the tag Pulse.Water.State.HeadUnderWater makes a pool fall while the head is under water.

A breath bar. Add a pool to the attribute profile of your character (or register it from C++, see below):

Field Value
Attribute, Kind Pulse.Stat.Breath, Pool
Min, Max, Start 0, 100, full (1, Fraction Of Range)
Rate +20 per second: it refills in 5 s above the surface
RateOverrides Any Tags Pulse.Water.State.HeadUnderWater, Rate -3.33 per second: 30 s of breath
Bands Pulse.Water.Band.LowBreath at or below 0.25 (a warning); Pulse.Water.Band.OutOfBreath at or below 0 with the granted tag Pulse.Water.Debuff.Drowning and a modifier: attribute Pulse.Stat.Health, target Rate, Add -10
Visibility, bSaveGame Owner; off (breath is not worth saving)

Pulse::Water::Breath::MakeBreathDefinition(BreathSeconds, RefillSeconds, DrowningHealthPerSecond) (PulseWaterBreath.h, defaults 30, 5, 10) builds the same definition in C++:

#include "Attributes/PulseAttributeProfile.h"
#include "PulseWaterBreath.h"

void FMyGameModule::StartupModule()
{
	Pulse::Attributes::RegisterDefinitions(TEXT("MyGame"), { Pulse::Water::Breath::MakeBreathDefinition(45.0) }, EPulseAttributeDefinitionTarget::Players);
}

At 0. The band OutOfBreath holds: the owner gets Pulse.Water.Debuff.Drowning and health falls by 10 per second until the head is above the surface and breath comes back. At health 0 the attribute source sends Depleted, as for any other damage; what death means is up to your combat (PulseGameplay combat, your own rule). The health rate needs Pulse.Stat.Health as a pool of the same source (the default player profile has it); the GAS adapter takes the definition like the hunger and thirst of PulseSurvival.

Tuning. The fall is a falling rate, so the tuning knob Pulse.Tuning.Attributes.RateLoss of Pulse Foundation scales it (a factor of 0.5 doubles the breath, e.g. for a diving helmet or an easy difficulty; it scales every falling rate of the owner), and rate modifiers on Pulse.Stat.Breath (Multiply) work as for every pool. Pulse Water adds no knob of its own.

Multiplayer. The server decides: its attribute source reads the tags of the server’s copy of the character, which follows the moves of the client. Breath and health replicate like every attribute (rate and stamp, clients project the value). The tags themselves are not replicated: every machine has them from its own copy of the movement, so they may lag a little on other clients; for gameplay decisions use the server.

A HUD bar. With PulseGameplay, the bridge PulseWaterGameplayBridge registers the breath attribute and a bar of the Status HUD in one switch (see Shipyard and repairs). Without it, add a bar for Pulse.Stat.Breath to your own HUD; the value comes from Pulse::Attributes like any other attribute.

Wet clothes and hulls

A UPulseWaterWetnessComponent on any actor (a character, a boat, a crate) remembers how high the water came on it and how long ago, and gives that to the materials of its meshes. Below the water line of now the meshes are wet; up to the wet line, the highest water of late, they are as wet as Wetness says, which falls from 1 to 0 within Dry Time (30 s) once the water is lower. Dry, the wet line comes down to the water again. Dry makes the actor dry at once (a change of clothes).

The values go to the meshes as custom primitive data, no dynamic material instances: three floats from Custom Primitive Data Index (0 by default): the water line, the wet line (heights in the local space of each mesh) and the wetness. Mesh Tag limits it to meshes with that component tag; Refresh Meshes finds them again after meshes changed. It looks at the water every Update Interval (0.1 s) and sends only changes of 1 cm or 3 % (a change of custom primitive data updates the render state of a mesh). It is looks only: nothing replicates, every machine follows the water itself.

In the material, the function MF_PulseWater_Wetness (/PulseWater/Materials/Functions) takes the base color and roughness of the dry material and the three values, and gives them back darker (Darkening, 0.5) and smoother (Wet Roughness, 0.15) where wet, with soft edges (Edge Width, 3 cm), plus Wet (0..1) for effects of your own. Read the values with three scalar parameters that have Use Custom Primitive Data on, at the index of the component and the two after it.

A movement of your own

Games with their own character movement (or other pawns) put a UPulseWaterSwimComponent on the actor: every tick it samples the water at the owner, keeps Is In Water with the same gap between going in and coming out, the head and the time under water, and fires the same events and messages. The movement reads Get Swim Sample, or samples itself with Sample Water At (a location, the half height and eye height of the body, optionally the water time of a predicted move). The rules are plain C++ in PulseWaterSwimming.h (Pulse::Water::Swim: MakeSample, IsInWater, FSwimTracker).

Get Immersion says how deep the owner is in the water from the last tick, 0 dry to 1 completely under, and Is Touching Water whether it is in at all (also too shallow to swim). Both count every liquid, also one that cannot be swum in (Get Swim Sample says which). Use them for wetness, cold or soaked clothes instead of the swim messages; every machine samples them itself, nothing is replicated.

// Wetness of a survival game: soak while in the water
if (const UPulseWaterSwimComponent* swim = Character->FindComponentByClass<UPulseWaterSwimComponent>())
	Wetness = FMath::Max(Wetness, swim->GetImmersion());
// In the IsInWater of a movement component of your own
const FPulseWaterSwimSample sample = UPulseWaterSwimComponent::SampleWaterAt(this, UpdatedComponent->GetComponentLocation(), HalfHeight, HalfHeight * 0.8f);
bInWater = Pulse::Water::Swim::IsInWater(bInWater, sample, 0.6f, 0.35f);

This site uses Just the Docs, a documentation theme for Jekyll.