# ❤️ Health

**`#bs.health:help`**

Efficiently manage the lifecycle and vital aspects of an entity.

```{epigraph}
"He who has a why to live can bear almost any how."

-- Friedrich Nietzsche
```

```{admonition} About NBTs
:class: warning

When using the module, you cannot rely on NBTs to get health information. Use the `get_health` function instead. This is because NBTs may not consistently reflect actual values. This choice was made to enhance performance, reliability, and to work around some limitations.
```

```{admonition} Effects Incompatibility
:class: warning

This system uses the `health_boost` effect to force an update to the player's `max_health`. As a result, this effect is not compatible with certain commands. Additionally, while effects like `instant_damage` and `instant_health` are supported, some amplifiers may cause issues. Specifically, `instant_damage` with amplifier 255 and `instant_health` with amplifiers greater than 28.
```

---

## 🔧 Functions

You can find below all functions available in this module.

---

### Add / Remove

:::::{tab-set}
::::{tab-item} Health

```{function} #bs.health:add_health {points:<value>}

Add or remove health points from players.

:Inputs:
  **Execution `as <players>`**: Players whose health will be updated.

  **Function macro**:
  :::{treeview}
  - {nbt}`compound` Arguments
    - {nbt}`number` **points**: Health points to add to players.
  :::

:Outputs:
  **State**: Health is scheduled for update.
```

*Example: Heal yourself by 5 HP:*

```mcfunction
# Once (execute on you)
function #bs.health:add_health {points:5.0}
```

```{admonition} How to Remove?
:class: tip

You can use negative numbers to remove health points from the player.
```

::::
::::{tab-item} Max Health

```{function} #bs.health:add_max_health {points:<value>}

Add or remove base maximum health points from players.

:Inputs:
  **Execution `as <players>`**: Players whose max health will be updated.

  **Function macro**:
  :::{treeview}
  - {nbt}`compound` Arguments
    - {nbt}`number` **points**: Max health points to add to players.
  :::

:Outputs:
  **State**: Max health is scheduled for update.
```

*Example: Increase your max HP by 5:*

```mcfunction
# Add 5 maximum health points to the executing player
function #bs.health:add_max_health {points:5.0}
```

```{admonition} How to Remove?
:class: tip

You can use negative numbers to remove max health from the player.
```

::::
:::::

> **Credits**: Aksiome

---

### Get

:::::{tab-set}
::::{tab-item} Health

```{function} #bs.health:get_health {scale:<scaling>}

Get a player's health points.

:Inputs:
  **Execution `as <players>`**: Players from which you want to get health points.

  **Function macro**:
  :::{treeview}
  - {nbt}`compound` Arguments
    - {nbt}`number` **scale**: Scalar for the function's returned value.
  :::

:Outputs:
  **Return | Storage `bs:out health.get_health`**: {nbt}`double` Player's health points.
```

*Example: Get your current HP (scaled by 1000):*

```mcfunction
# Get and display the current health of the executing player
function #bs.health:get_health {scale:1000}
```

::::
::::{tab-item} Max Health

```{function} #bs.health:get_max_health {scale:<scaling>}

Get a player's base maximum health points.

:Inputs:
  **Execution `as <players>`**: Players from which you want to get max health points.

  **Function macro**:
  :::{treeview}
  - {nbt}`compound` Arguments
    - {nbt}`number` **scale**: Scalar for the function's returned value.
  :::

:Outputs:
  **Return | Storage `bs:out health.get_max_health`**: {nbt}`double` Player's max health points.
```

*Example: Get your maximum HP (scaled by 1000):*

```mcfunction
# See the returned value (execute on you)
function #bs.health:get_max_health {scale:1000}
```

::::
:::::

> **Credits**: Aksiome

---

### Set

:::::{tab-set}
::::{tab-item} Health

```{function} #bs.health:set_health {points:<value>}

Set players' health points.

:Inputs:
  **Execution `as <players>`**: Players whose health will be updated.

  **Function macro**:
  :::{treeview}
  - {nbt}`compound` Arguments
    - {nbt}`number` **points**: Health points.
  :::

:Outputs:
  **State**: Health is scheduled for update.
```

*Example: Set your HP to 10:*

```mcfunction
# Once (execute on you)
function #bs.health:set_health {points:5.0}
```

::::
::::{tab-item} Max Health

```{function} #bs.health:set_max_health {points:<value>}

Set players' base maximum health points.

:Inputs:
  **Execution `as <players>`**: Players whose max health will be updated.

  **Function macro**:
  :::{treeview}
  - {nbt}`compound` Arguments
    - {nbt}`number` **points**: Max health points.
  :::

:Outputs:
  **State**: Max health is scheduled for update.
```

*Example: Set your max HP to 10:*

```mcfunction
# Once (execute on you)
function #bs.health:set_max_health {points:5.0}
```

::::
:::::

> **Credits**: Aksiome

---

### Time to Live

```{function} #bs.health:time_to_live {with:{}}

Set the lifetime of entities.

:Inputs:
  **Execution `as <entities>`**: Entities to add a lifetime to.

  **Function macro**:
  :::{treeview}
  - {nbt}`compound` Arguments
    - {nbt}`compound` **with**: Lifetime data.
      - {nbt}`int` **time**: Time to live. In ticks by default if unit is not defined.
      - {nbt}`string` **unit**: Unit of the specified time (tick, second, minute, hour, t, s, m, h).
      - {nbt}`string` **on_death**: Command that will be run as the entity on its death.
  :::

:Outputs:
  **State**: The entity now has a finite lifetime.
```

*Example: Give creepers a 10-second lifetime:*

```mcfunction
# Set a 10-second lifetime for all creepers
execute as @e[type=minecraft:creeper] run function #bs.health:time_to_live {with:{time:10,unit:"s"}}
```

*Example: Give an explosion effect to creepers at the end of their life:*

```mcfunction
# Set a lifetime with explosion effect for all creepers
execute as @e[type=minecraft:creeper] run function #bs.health:time_to_live {with:{time:10,on_death:"execute at @s run particle minecraft:explosion_emitter ~ ~ ~"}}
```

*Example: Update the on_death callback at any given time:*

```mcfunction
# Set initial lifetime with explosion effect
execute as @e[type=minecraft:creeper] run function #bs.health:time_to_live {with:{time:100,on_death:"execute at @s run particle minecraft:explosion_emitter ~ ~ ~"}}

# At any time before the entity's death
execute as @e[type=minecraft:creeper,limit=1] run function #bs.health:time_to_live {with:{on_death:"say GOTCHA"}}
```

> **Credits**: Aksiome, Leirof

---

```{include} ../_templates/comments.md
```