# Areas that open with progress (world.access)

## What it is for

`world.access` closes parts of the world until a condition holds: a region opened by progress, a door that waits for a key, the
chapters of a map, or a zone the player must stay in. An area is a disc, a rectangle or a biome. While closed it is a wall the
player slides along, a gentle push back out, or a place that hurts. The player is told once per approach, and an opening is
told once and saved. It suits adventure, survival, terraforming and battle royale games. The kit moves and warns the player;
what the area looks like is up to the game.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "world.access" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "world.access",
                              config: { "message": "This area is closed.", "pushSpeed": 8, "rearm": 2 } }
```

Then add documents to the `access_areas` collection. It requires `game.engine`; a `biome` shape needs `world.biomes`
(without it such an area is left out).

## First example

<!-- test: kits/game_engine/host/tests/world_access.rs::a_closed_area_is_a_wall_until_it_opens -->
A closed disc at `[10, 0]` with radius 3 stops a player walking toward it at its edge and sets the variable `access.message`
to `This area is closed.`. Calling `open("gate")` answers `true` (an unknown id answers `false`) and the player can then walk
in. The opening survives a save and a reload.

```json
[ { "id": "gate", "name": "Gate", "shape": { "center": [10, 0], "radius": 3 } } ]
```

## Settings and defaults

| Setting | Type | Default | Meaning |
|---|---|---|---|
| `message` | string | `This area is closed.` | told when an area without its own message stops the player |
| `pushSpeed` | number 0.5 to 50 | `8` | metres per second a `push` area moves the player back out |
| `maxCorrection` | number 0.1 to 20 | `1.5` | `wall`: deeper than this, the player is pushed out instead of put back at once |
| `rearm` | number 0 to 100 | `2` | metres to go away before the message is told again |
| `notify` | boolean | `true` | also show the message as a HUD notice (`hud.notify`) |

All settings and the `access_areas` collection are moddable. Each document of `access_areas` has:

| Field | Meaning |
|---|---|
| `id`, `name` | required |
| `shape` | `{ "center": [x, z], "radius": r }`, `{ "rect": [minX, minZ, maxX, maxZ] }` or `{ "biome": "<id>" }` |
| `openWhen`, `closeWhen` | trigger conditions; `closeWhen` wins; checked four times a second; without `openWhen` the area stays closed until opened by a call |
| `mode` | `wall` (default), `push` or `hurt` |
| `damagePerSecond` | `hurt` only, default 10 |
| `message` | overrides the `message` setting |
| `keepOut` | `true` (default): the area is forbidden; `false`: the player must stay inside it (shrinking zone, fenced start) |

An area starts closed. Hurt damage goes through `combat.damage` with kind `status`.

## Services, events, variables

- `world.access` (service): `areas()` returns `[{ id, name, open, mode, keepOut }]`; `isOpen(id)`; `open(id)`; `close(id)`;
  `inside(id, [x, z])`. `open` and `close` answer `false` when refused by a hook.
- Actions `open_area` and `close_area` with `{ area }`; condition `area_open` with `{ area }`.
- `access.blocked` (event): `{ area, message }`, once per approach.
- `access.opened` and `access.closed` (events): `{ area }`; the opening is saved, so a load does not tell it again.
- `hud.notify` (event): the message, when `notify` is on.
- `access.message` (variable): the message of the area that stopped the player.

## Hooks and modding

- `access.pass`: `{ area, entity, mode, message, pass }`, mutable `pass` and `message`. Setting `pass` to true lets the player
  through until it is back in an allowed place (no message, no wall).
- `access.open` and `access.close`: `{ area, by }` with `by` `condition` or `call`; cancellable. A refused condition is asked
  again only once the conditions of the area change.

```json
{ "id": "vip", "hook": "access.pass", "match": { "area": "vault" },
  "if": [{ "var": "vip", "op": "==", "value": true }], "set": { "pass": true } }
```

A mod can change the settings and add, patch or remove documents of `access_areas`.

## Engines

The behaviour is one shared implementation for the web and native players; engine wrappers show the notice and the damage
through your HUD and combat kits.

## When it does not do what you expect

- An area never opens: it has no `openWhen` and nobody called `open`, or an `access.open` hook cancels it.
- A biome area does nothing: `world.biomes` is not installed.
- No message appears: `notify` is off, or the player has not moved `rearm` metres away since the last one.

## Limits

Only the player is restricted. A biome has no edge to measure: the player goes back toward where it last stood allowed.

## Versions

Kit `world.access` 1.2.0 (hooks since 1.1.0; continuous opening decisions since 1.2.0), requires `game.engine@^1`.