Oxygen Configuration

Configure the reusable oxygen block for entities that can drown or suffocate.

Oxygen is a reusable oxygen: block for entities that can drown or suffocate — mobs and the player’s base stats. It works alongside health: running out of oxygen deals damage through the same health system, not a separate death mechanic.

Where It’s Used

Mobs (mob-config.yaml), nested under a mob entry:

mobs:
  - name: my_mob
    oxygen:
      max: 20.0
      regen-per-second: 1.0
      consumption-rate-per-second: 2.0
      takes-damage: true
      damage-per-second: 0.5

Player base stats (player-config.yaml), as a top-level oxygen: key (no player: wrapper — same block name mobs use):

oxygen:
  max: 30
  consumption-rate-per-second: 20.0
  regen-per-second: 1.0
  takes-damage: true

If the oxygen: block is omitted entirely, the entity gets full defaults (see below) — including not taking suffocation damage. It’s always optional.

Fields

takes-damage defaults to false. If you only want to change, say, max for a mob and don’t mention takes-damage at all, that mob still won’t take suffocation damage — you have to opt in explicitly. This is intentionally different from health’s takes-damage, which defaults to true; suffocation is an opt-in mechanic, ordinary damage isn’t.

Notes

• Oxygen drains/regenerates continuously (scaled by elapsed time), not in discrete ticks.
• There’s no invincibility window for suffocation damage — as long as oxygen stays at 0 and takes-damage is true, damage keeps applying every frame.
• Oxygen can never exceed max or go below 0.

Complete Example

mobs:
  - name: land_animal
    # No oxygen block — never drowns, uses full defaults.

  - name: fish
    oxygen:
      max: 50.0
      regen-per-second: 0.0
      consumption-rate-per-second: 0.0
      takes-damage: false
      # A fish that's always "submerged" in its own logic never needs to lose oxygen at all.

  - name: land_predator
    oxygen:
      max: 15.0
      consumption-rate-per-second: 3.0
      takes-damage: true
      damage-per-second: 1.0
      # Can be lured underwater and will actually drown there.