# Rest points and respawn (checkpoint.rest)

## What it is for

Rest points as data (a bonfire, a shrine, an incense burner). Resting heals the player, refills its stamina, lights the point,
makes it the checkpoint and brings every non-boss enemy back to its post. A dead player comes back at the last lit point after a
delay, leaving its money where it fell; walking back there recovers it, dying again loses it. Every step is a decision a game or a
mod can bend.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "checkpoint.rest" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "checkpoint.rest",
                              config: { "respawnDelay": 3, "dropRatio": 1 } }
```

Only `game.engine` is required. Optional companions: `combat.core` (healing), `interaction.system` (a prompt on each point),
`spawn.system` and `enemy.ai` (enemies that come back), `economy.money` (the dropped money), `combat.stamina` (stamina refill).
Points come from the `rest_points` collection of the project, from the `rest_points` of the current scene, or from instances with
the `rest_point` component:

```json
{ "id": "camp", "name": "Camp", "at": [5, 0, 0], "yaw": 1.5, "radius": 3, "lit": false }
```

## First example

<!-- test: kits/checkpoint_rest/tests/checkpoint_rest.rs::dying_drops_the_money_and_the_player_comes_back_at_the_checkpoint -->
The player rests at `camp`, walks away and dies with 100 money: the money is left where it fell, and after `respawnDelay` the
player is back at the camp.

```text
checkpoint.rest.rest("camp")      -> true     (rest.lit, rest.used; rest.checkpoint = "camp")
player.died                       -> rest.dropped { amount: 100 }; lost() = { amount: 100, x, y, z }
(after the delay)                 -> rest.respawned { point: "camp" }
```

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `restRadius` | 2.5 | metres around a point where the player may rest (a document can give its own `radius`) |
| `heal` | `true` | resting heals to full health |
| `respawnEnemies` | `true` | resting and coming back from death bring tracked non-boss enemies back |
| `track` | `placed` | which enemies come back: `placed` (the level's) or `all` |
| `enemyTags` | `["enemy"]` | tags that mark an entity as an enemy |
| `bossTag` | `boss` | enemies with this tag are never brought back |
| `respawnDelay` | 3 | seconds between the death and the return |
| `dropMoney` / `dropRatio` | `true` / 1 | the share of the balance left where the player fell |
| `recoverRadius` | 1.5 | metres around the dropped money where it is recovered |
| `label` | `Rest` | the prompt of a rest point |

## Services, events, variables

- `checkpoint.rest` (service): `points()`, `current()`, `isLit(id)`, `rest(id?)` (no id: the nearest point within reach),
  `nearest()`, `respawn()`, `lost()`, `resetEnemies(point?)`, `enemies()`.
- Events: `rest.lit`, `rest.used`, `rest.refused` (reason `cancelled`, `dead`, `far`, `unknown`), `rest.enemies_reset`,
  `rest.respawned`, `rest.dropped`, `rest.recovered`, `rest.lost`.
- Variables: `rest.checkpoint`, `rest.lost`. Input action: `rest`. Content verbs: `rest_at`, `rest_respawn` (actions) and
  `rest_lit` (condition).

## Hooks and modding

| Hook | Mutable | Asked |
|---|---|---|
| `rest.use` | `heal`, `respawnEnemies` | before a rest; cancelling refuses it (`rest.refused`) |
| `rest.enemy_reset` | - | for each tracked enemy about to come back; cancelling leaves it as it is |
| `rest.respawn` | `x`, `y`, `z`, `delay` | after a death; cancelling leaves the player dead for another kit to handle |
| `rest.drop` | `amount` | before the money is left; 0 drops nothing |

Moddable: all the settings and the `rest_points` collection.

## Limits

Without `combat.core` the kit only places the points and moves the player. Enemies come back only at a rest (the respawn of
`spawn.system` is held). It draws no HUD of its own. Runs on the web and in the native player.

## Versions

Kit 1.0.0 and service `checkpoint.rest` 1.0.0.