Health Configuration

Configure the reusable health block used by mobs, mounts, and the player's base stats.

Health is a reusable health: block used anywhere an entity needs hit points — mobs, mounts/mounts, and the player’s own base stats. It’s the same schema in every case.

Where It’s Used

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

mobs:
  - name: my_mob
    health:
      max: 20.0
      regen-per-second: 0
      takes-damage: true

Mounts/mounts (mount-config.yaml), nested the same way under a mount entry:

mounts:
  - name: my_mount
    health:
      max: 100.0
      regen-per-second: 0
      takes-damage: true

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

health:
  max: 20
  regen-per-second: 0.0

If omitted entirely in any of these, the entity gets full defaults (see below) — the health: block is always optional.

Fields

Field	Default	Description
`max`	`100.0`	Maximum (and starting) hit points.
`regen-per-second`	`1.0`	Passive healing rate, applied continuously. Set to `0` for no natural regen.
`takes-damage`	`true`	Set to `false` to make the entity fully immune to damage — `take_damage()` becomes a no-op regardless of source (combat, fall damage, etc).
`global-iframe-ms`	`0`	Post-hit invulnerability window in milliseconds. After any attacker-sourced hit lands, the entity ignores all attacker-sourced damage for this long (classic player hit-flash invulnerability). `0` disables the window. Environmental damage (falling, drowning) is not blocked by it.

Notes

Damage from any source (weapons, fall damage, etc.) goes through the same take_damage() path, so takes-damage: false blocks all of it uniformly — there’s no way to be immune to some damage sources but not others via this config.
Regeneration is continuous, not tick-based — regen-per-second: 0.5 heals half a point every second, smoothly, rather than in discrete steps.
An entity can never regenerate above its own max, and health never goes below 0 (death handling itself lives outside this config).
Independent of global-iframe-ms, every attacker-sourced hit also grants the victim a short per-attacker cooldown (engine default 300 ms; weapons can override it with hit-cooldown-ms in item-config.md’s weapon-info), so overlapping a damage source never deals damage every tick. global-iframe-ms stacks on top of that as a blanket window against all attackers at once.
For mobs and mounts, global-iframe-ms re-applies from config on spawn but is not stored in world saves — an already-spawned entity that gets saved and reloaded falls back to 0 until respawned. Player entities re-apply it from the player-config.yaml health: block on every login.

Complete Example

mobs:
  - name: tough_boss
    health:
      max: 200.0
      regen-per-second: 2.0
      takes-damage: true

  - name: training_dummy
    health:
      max: 1.0
      takes-damage: false