Rooms, runs and maps in your game (world.rooms) #

What it is for #

world.rooms builds hand-made rooms with floors, walls, pillars, braziers and decor, and plays them in one of two layouts. In run (default), rooms are played one at a time and chained by a runs document: doors unlock when the room is cleared and preview the next reward. In map, every room of a maps document is laid out at once, with corridors, doors opened by clearing, by use or by a key, and an exit. It suits dungeons, crypts, houses, stations and castles. Enemies come from the encounter kits, and a bound level model or modular kit can replace the stone boxes.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "world.rooms" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "world.rooms",
                              config: { "layout": "map", "map": "keep", "ceiling": true } }

It requires physics.rigidbody, physics.port and game.engine. A project without rooms plays the shipped Underworld run.

First example #

<!-- test: kits/game_engine/host/tests/world_rooms.rs::the_underworld_run_starts_in_the_vestibule --> In a project without room documents, the run starts in the vestibule:

{ "op": "call", "service": "world.rooms", "method": "run", "args": [] }

It answers { id: "run_descent", index: 1, count: 5 }. The room is 16 by 16 m, with four walls and a start reward; the door stays locked until the reward is picked up, then exit("north") enters room 2. A saved game restarts at room 1.

Settings and defaults #

Also windowNodes and skylightNodes. Nearly all settings are moddable.

Services, events, verbs, variables and data #

• world.rooms (service): run(), current(), rooms(), doors(), enter(id, reward), exit(door), clear(), dropReward(reward, at), end(result), and for maps openDoor(id), closeDoor(id), doorOpen(id), roomCleared(id).
• world.ready, run.started, room.entered, room.cleared, door.unlocked, reward.dropped, reward.collected, run.ended (events). run.ended carries result victory or death.
• door.refused, exit.refused and hud.notify (events): a map door or exit stayed shut, with a message for the HUD.
• open_door, close_door (actions) and door_open, room_cleared (conditions): script verbs.
• room.name, room.index, room.count, room.cleared, run.money, run.result (variables).
• rooms, runs, maps, module_kits (collections). A map has rooms (room, at), links (from and to as room.door, open among cleared, interact, always, closed, key, when, consume, frame), start and exit (room, at, requires among enemies, rooms, none).

Hooks and modding #

All are cancellable. The rooms registry lets a document extend another to make a variant.

{ "id": "gold_rush", "hook": "room.reward", "priority": 0, "match": { "type": "money" }, "mul": { "amount": 2 } }

When it does not do what you expect #

• A door never opens: the room is not cleared, the player lacks the key or condition, or a room.door tap cancelled it.
• A refusal shows no message: read door.refused or hud.notify in your HUD.
• A run ends at once: endOnDeath is on, or a boss room was cleared. Use ending: none for a hub.
• Walls are plain boxes: no level model or module is bound to the slots.

Limits #

A run or map holds at most 64 rooms; a map at most 128 links. Enemies and rewards come from other kits.

Versions #

Kit 1.19.1. 1.19.0 added per-room height, 1.18.0 polygon rooms, 1.8.0 the map layout, 1.6.0 the hooks.