Swimming

In water the character moves with its own slower speeds instead of gravity. With no input it floats up to the surface and stops there. Diving goes down at a set speed, the breath runs down under water and refills above it, and an empty breath hurts every tick until the character is back at the surface.

Also called: Water movement, Diving, Underwater movement.

A small otter diver in a scarf and snorkel mask swims just under the water line of a lagoon with a trail of bubbles, above a coral reef and a shoal of orange fish, painted in soft watercolour. — Pearlwhisk Lagoon, an invented underwater exploration game. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Swimming" to my game.

What it should do: Water changes how a character moves and adds a clock to staying down. It gives the player a place that is slower, safer from some enemies and dangerous in its own way, and it has to feel different from walking at once.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> dry
  dry: Out of water
  floating: At the surface
  diving: Under water
  drowning: Drowning
  dry --> floating: slips into the water
  dry --> diving: falls in deep
  floating --> diving: swims down
  diving --> floating: reaches the surface
  floating --> dry: jumps out
  diving --> drowning: breath runs out
  drowning --> floating: reaches the surface
```

Use these starting values:
- walkSpeed: 5 units/s
- swimSpeed: 3 units/s
- diveSpeed: 2.5 units/s
- buoyancy: 1.5 units/s
- gravity: 30 units/s²
- jumpOutSpeed: 9 units/s
- maxBreath: 10 s
- refillRate: 4 s per s
- drownDamage: 10 health/s

Watch out for these common mistakes:
- The fall carries on into the water: Tell your AI: the moment the mouth reaches the water, cut the downward speed to the dive speed.
- Bobbing at the surface: Tell your AI: when swimming up, stop exactly at the surface and stay there. Count the mouth at the surface as above water.
- Diving again with no breath: Tell your AI: refill the breath with time at the surface, not all at once, so a quick dip gives a short dive and a long rest gives a long one.
- Jumping from the deep: Tell your AI: a jump out of the water only works at the surface.
- Water that feels like air: Tell your AI: use a clearly slower sideways speed in water, and change it on the tick the character enters.
- The floor under the water: Tell your AI: stop a downward swim at the floor, and keep the breath running while the character stands there.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

Water changes how a character moves and adds a clock to staying down. It gives the player a place that is slower, safer from some enemies and dangerous in its own way, and it has to feel different from walking at once.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Out of water → At the surface: slips into the water
Out of water → Under water: falls in deep
At the surface → Under water: swims down
Under water → At the surface: reaches the surface
At the surface → Out of water: jumps out
Under water → Drowning: breath runs out
Drowning → At the surface: reaches the surface

Good starting values

Value	Start with	What it changes
walkSpeed	5 units/s	Walking speed on dry ground. Water speeds are chosen against it.
swimSpeed	3 units/s	Sideways speed in water. About 60 percent of walking, so water feels thick and the player notices at once.
diveSpeed	2.5 units/s	Up and down speed when swimming on purpose. A little under the sideways speed, since moving in depth is harder. It also caps how fast a fall is slowed in water.
buoyancy	1.5 units/s	How fast the character rises by itself with no input. Slower than the dive, so going down is the easy way and coming up takes a decision.
gravity	30 units/s²	How fast the character falls out of the water.
jumpOutSpeed	9 units/s	How hard a jump from the surface throws the character out. Enough to clear a normal edge.
maxBreath	10 s	How many seconds the character can stay under. Ten seconds is long enough to explore and short enough to feel the clock.
refillRate	4 s per s	How much breath comes back per second at the surface. Four times the drain, so a quick breath is enough to dive again.
drownDamage	10 health/s	Health lost per second while drowning. It should hurt enough that the player rises at once, but not kill before they can.

What usually goes wrong

The fall carries on into the water

A character that falls fast keeps its speed under water, shoots to the bottom and hits the floor hard, or tunnels through a thin floor.

Fix: Tell your AI: the moment the mouth reaches the water, cut the downward speed to the dive speed.

Bobbing at the surface

A rise that does not stop at the surface overshoots, pops out of the water and falls back, again and again. The breath flickers between draining and filling.

Fix: Tell your AI: when swimming up, stop exactly at the surface and stay there. Count the mouth at the surface as above water.

Diving again with no breath

A player with an empty breath comes up for a moment and dives again. If touching the surface fills the meter at once, drowning costs nothing. If the meter does not move at the surface, the player drowns again with no chance to recover.

Fix: Tell your AI: refill the breath with time at the surface, not all at once, so a quick dip gives a short dive and a long rest gives a long one.

Jumping from the deep

A jump that works anywhere in the water throws the character out of the middle of a lake.

Fix: Tell your AI: a jump out of the water only works at the surface.

Water that feels like air

If the sideways speed and the control are the same in water and on land, the player does not notice they have entered water and the area has no identity.

Fix: Tell your AI: use a clearly slower sideways speed in water, and change it on the tick the character enters.

The floor under the water

A swimmer that can go deeper than the floor sinks into the ground or shows through it.

Fix: Tell your AI: stop a downward swim at the floor, and keep the breath running while the character stands there.

How to check it works

Your character is 1 unit under the surface and the player presses nothing. Wait: It rises by itself and stops exactly at the surface after about 40 ticks.
Your character is a hair under the surface. Swim up: It stops exactly at the surface and stays there.
Your character floats at the surface. Swim down for one second: It is 2.5 units under the surface.
Your character is just above the floor. Keep swimming down: It stops at the floor.
Your character is under water with full breath. One second passes: Nine seconds of breath are left.
Your character floats at the surface with 5 seconds of breath. Half a second passes, and then a few more seconds: Breath is 7 after half a second and it ends full, and it never goes down at the surface.
Your character is under water with almost no breath. Stay down: Drowning starts, and every tick costs one sixth of a health point.
Your character is drowning just under the surface. Swim up, then dive again at once: The drowning stops at the surface, and after diving again it drowns again within a few ticks.
Your character falls into the water at speed 15. It reaches the water: Its downward speed becomes the dive speed, 2.5.
Your character drops into the water at a crawl. It touches the surface: It dips a hair under, comes up by itself within a few ticks and floats, without a real dive.
Your character walks to the right on dry ground, and then swims to the right. One tick passes each time: The speed is 5 on land and 3 in the water.
Your character floats at the surface, and another is 2 units down. Both press jump: The first is thrown out at speed 9 and the second only keeps swimming.
Your character has just jumped out of the water. Wait: It falls back into the water and is slowed at once.
The ground is above the water level. Walk to the left: The character stays dry and walks at 5.

Works well with

Stamina System: Fast swimming can spend stamina while the breath meter runs on its own. Keep the two bars apart, or the player cannot tell why they are drowning.
Double Jump: Give the air jumps back when the character touches the water, and decide if a jump out of the water counts as the first jump.

Clashes with Variable-Height Jump: A jump out of the water that can be cut short by letting go of the button makes the exit height depend on a tap, which is hard to read at the surface. Use the full jump height for a jump out of the water and let the cut apply only after the character is in the air.

Common questions

what do i tell my ai to add swimming

Paste this: Add swimming. In water the character moves slower and ignores gravity, floats up to the surface when nothing is pressed, dives at a set speed, loses breath under water and gets it back at the surface, takes damage every tick with an empty breath, and can jump out only from the surface.

how long should a character be able to hold its breath

Start with ten seconds. Shorter is stressful and makes diving a chore, much longer and the meter is never noticed. Refill it four times faster than it drains so a quick breath is enough.

why does my character bob up and down at the water surface

The rise has no stop at the surface, so it overshoots, falls back and overshoots again. Stop the rise exactly at the surface level and keep the character there.

should falling into water hurt

That is a separate rule. Here the water only slows the fall to the dive speed. If you want a fall to hurt, decide it from the speed on the tick before entering.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

18 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it