Oxygen Meter

An oxygen meter is a bar that empties while the character's head is under water and refills quickly in the air. A short grace time lets a quick dip cost nothing. When the bar is empty, drowning hurts the character on a steady beat until they come up for air.

Also called: Breath meter, Air meter, Underwater breath, Drowning timer.

A small octopus diver in a brass helmet swims up toward the bright surface, trailing a few tiny bubbles, next to a glass bulb holding only a thin line of pink glow. — Quillhollow Deep, an invented underwater storybook adventure. 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 "Oxygen Meter" to my game.

What it should do: Oxygen puts a clock on every dive. The player weighs how much farther to swim against how much air is left, so deep water feels risky without a sudden death.

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

```mermaid
stateDiagram-v2
  [*] --> air
  air: In the air
  dive: Holding breath
  low: Running low
  drown: Drowning
  air --> dive: head goes under
  dive --> low: meter hits warning
  low --> drown: meter is empty
  dive --> air: head breaks surface
  low --> air: head breaks surface
  drown --> air: head breaks surface
  air --> low: dives with little air
  dive --> drown: meter runs dry fast
  air --> drown: dives with no air
```

Use these starting values:
- maxOxygen: 100 units
- drainRate: 5 units/s
- refillRate: 50 units/s
- warnFraction: 0.25 share of full
- diveGrace: 0.5 s
- hurtInterval: 1 s
- hurtDamage: 10 health

Watch out for these common mistakes:
- Waves flicker the meter: Tell your AI: wait a short grace time with the head under before the meter starts to drain, and count a breath of air as a clean reset.
- Damage depends on the frame rate: Tell your AI: run drowning on a timer in seconds, and when one slow frame covers several beats, deal every hit that is due.
- Drowning comes with no warning: Tell your AI: switch to a low state at about a quarter of the meter, and show it with a sound or a flashing bar, so the player can still turn around.
- Feet in the water count as diving: Tell your AI: check the position of the head only. Head in the air means breathing, even when the rest of the body is deep in the water.
- A smaller meter than the air held: Tell your AI: cut the held air back to the current maximum at the start of every tick.

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

Oxygen puts a clock on every dive. The player weighs how much farther to swim against how much air is left, so deep water feels risky without a sudden death.

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

In the air → Holding breath: head goes under
Holding breath → Running low: meter hits warning
Running low → Drowning: meter is empty
Holding breath → In the air: head breaks surface
Running low → In the air: head breaks surface
Drowning → In the air: head breaks surface
In the air → Running low: dives with little air
Holding breath → Drowning: meter runs dry fast
In the air → Drowning: dives with no air

Good starting values

Value	Start with	What it changes
maxOxygen	100 units	How big the full meter is. Together with the drain speed it sets how long a dive can last. At the starting values that is 20 seconds, a length that lets a player cross a small lake in one breath.
drainRate	5 units/s	How fast the meter empties under water. It is never zero, because a meter that does not empty would make the whole feature pointless.
refillRate	50 units/s	How fast the meter fills in the air. Filling much faster than draining keeps swimming back and forth to the surface fun instead of a chore. It is never zero, because the player could be trapped at a low level for good.
warnFraction	0.25 share of full	The share of the meter at which the warning starts. A quarter gives the player about five seconds of notice to turn around.
diveGrace	0.5 s	How long the head can stay under before the meter starts to drain. It keeps waves, wading and quick dips from costing air.
hurtInterval	1 s	The time between two drowning hits. A full second gives the player a real chance to escape after the air runs out.
hurtDamage	10 health	How much one drowning hit takes. Ten out of a hundred means ten seconds of drowning at the starting values before a full health bar is gone.

What usually goes wrong

Waves flicker the meter

At the water line, waves push the head in and out many times a second. The meter jumps up and down, and a warning sound stutters.

Fix: Tell your AI: wait a short grace time with the head under before the meter starts to drain, and count a breath of air as a clean reset.

Damage depends on the frame rate

Damage is dealt once per frame or once per counted second on a slow computer, so a fast machine drowns the player twice as fast.

Fix: Tell your AI: run drowning on a timer in seconds, and when one slow frame covers several beats, deal every hit that is due.

Drowning comes with no warning

The bar looks fine and then the player is suddenly hurt. They cannot tell how long they had.

Fix: Tell your AI: switch to a low state at about a quarter of the meter, and show it with a sound or a flashing bar, so the player can still turn around.

Feet in the water count as diving

Wading through shallow water drains air, or a head resting in an air pocket of a cave keeps draining, because the check used the feet or the middle of the body.

Fix: Tell your AI: check the position of the head only. Head in the air means breathing, even when the rest of the body is deep in the water.

A smaller meter than the air held

A power-up that made the meter bigger wears off, and the player holds more air than the meter can show. The bar draws past its end.

Fix: Tell your AI: cut the held air back to the current maximum at the start of every tick.

How to check it works

A full meter of 100 and a grace of half a second. the head stays under water for 3 seconds: the meter shows 87.5, because only 2.5 seconds of it drained, at 5 per second.
A full meter. the head goes under for half a second, comes up, and goes under for half a second again: the meter is still at 100.
A meter at 40. the head stays in the air for 1 second: the meter shows 90, because it fills 50 per second.
A meter at 90. the head stays in the air for a bit more than a fifth of a second: the meter stops at exactly 100.
A meter just above 25, with the head under water. the meter drains to 25 or lower: the low warning turns on, and it stays off while the meter is higher.
A meter at 1, with the head under water. a tick would drain more than what is left: the meter stops at exactly zero and the character is drowning.
A meter that has just reached zero under water. the next second passes: no damage is dealt until the full second is over, and then the first hit lands.
An empty meter and a head under water. 3 seconds pass: the character is hurt exactly three times, for 10 each, 30 in all.
A drowning character a quarter of a second before the next hit. the head reaches the air: no hit lands, the meter starts to fill, and going back under starts a fresh full second.
A drowning character. one slow tick of 2.5 seconds goes by: two hits land together, 20 in all, with half a second left until the next one.

Works well with

Stamina System: Swimming hard can use up stamina and air together, so the player has two clocks to read. Keep the warnings apart so they are not mixed up. Let the water decide first how fast each one drains.

Common questions

how does an oxygen meter work in a game

A bar drains while the head is under water and refills in the air. When it is empty, the character is hurt on a regular beat until they come up for air.

how long should the player be able to hold their breath

Start with about 20 seconds, with a warning at the last five. Shorter makes every dive a rush, longer makes the meter a formality.

how much damage should drowning do

Start with one hit a second that takes a tenth of full health. That leaves about ten seconds to escape, which feels tense and fair.

what do i tell my ai to add an oxygen meter

Paste this: Add an oxygen meter. It drains only while the head is under water, after half a second of grace. It fills quickly in the air. At a quarter left, show a warning. When empty, hurt the player once a second until they reach the air.

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

19 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