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 #

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.

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

Settings and defaults #

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

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.

{ "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.