= How to Build

Building is how the world grows: you **dig** new rooms, **describe** them, and
**open** them to players. These commands need a builder role: **worldbuilder** or
**implementor** (build anywhere), or **zonebuilder** (build only in zones you've
been assigned). Ask an admin to grant one.

In-game, the authoritative lists are always **help room** and **help zone** (and
**help topics** shows which topics you can see). This page mirrors them.

== Closed and open rooms

A newly dug room is born **closed** — under construction. A closed room can't be
entered by players through its exits, and its //look// carries a **[closed]** note.
Builders who can edit a room may simply **walk into** it (and reach it with **goto**)
to keep working. When it's ready, **room open** (alias **room commit**) opens it to
players; **room close** (alias **room draft**) closes it again for maintenance.

== Digging rooms

* **dig //dir//** — dig a new, unnamed room to the //north/south/east/west// and step in.
* **dig //dir// //name//** — open a passage to an existing room called //name//, or dig a **new** one with that name and step in.
* **dig //dir// //id//** — open a passage to the existing room with that //id//.
* **dig new //name//** — a room with **no** exits (also: **dig -** / **dig .** / **dig noexit**).

Digging a **new** room makes a **two-way** passage (the way back is dug for you) and
steps you through; the room inherits the **zone** you dug from. Linking to an
**existing** room leaves you put and only adds the exit (the return exit too, if that
room's facing slot is free).

== Editing the current room

* **room name //name//** — name the room
* **room desc //text//** — set the description (what players read on //look//)
* **room keywords //words//** — alternate names for the room, so **goto //word//** reaches it
* **room info** — its id, zone, exits (with target ids), and open/closed state
* **room open** / **room close** — open to players, or close for maintenance
* **room delete //id//** — delete a **closed** room (asks you to confirm; it goes to trash and inbound exits are stripped)

== Editing exits directly

**dig** always makes a //two-way// passage. To set or clear a //single// (one-way)
exit, edit it directly — like every **room** command, on the room you stand in:

* **room exit //dir// //id|name//** — point this room's //dir// exit at a room
* **room noexit //dir//** — remove this room's //dir// exit

These are one-way, so the far room is untouched. To fix the matching exit, **goto**
that room and edit it there.

An exit can also be **unlisted**: a **secret** exit you can still walk if you know to,
or a **hidden** exit sealed until a lever opens it. Both are set with room-data flags --
see **[[Advanced Building]]** (//Hidden exits// and //Secret exits//).

== Getting around

**goto** teleports you straight to a room — handy for editing the far end of a
one-way exit, or any room you can build in.

* **goto //id//** — by number
* **goto //name//** — by name (or a room **keyword**), preferring your current zone
* **goto //name// //zone//** — prefer a given zone (by name or id)

You can only **goto** (and walk into closed) rooms in zones you're allowed to build in.

== Zones

Zones group rooms into areas — a town, a forest, a dungeon. Every room belongs to
exactly one zone. A zone has an **internal name** (used in commands) and optional
**display** info shown to players.

* **zone create //name//** — create a new zone (internal name; tells you its id)
* **zone list** (or the **zones** command) — list all zones
* **rooms //[zone]//** — list rooms in the current zone, or a named/numbered one
* **room zone //id|name//** — move the current room into a zone
* **zone name //display//** — set the zone's display name (shown as //internal - Display//)
* **zone desc //text//** — set the zone's description
* **zone suggested //lo// //hi//** — set the zone's suggested level range

The **zones** list reads: //#id internal - Display name - Description (lo-hi)// — each
part shown only once you've set it.

== Items and creatures

Builders also stock the world with **items** (a sword, a lamp, a sign) and
**mobiles** (creatures and NPCs). Those have their own guides:

* **[[All about Items]]** — create, describe, keyword, equip, and blueprint items (the item factory)
* **[[All about Mobiles]]** — create creatures, give them data, and simple reactions
* **[[Shops]]** — turn a mobile into a shopkeeper that buys and sells

Zones also **reset** about once an hour, repopulating any registered spawns; the
//zone setspawn// (mobiles) and //zone setitem// (items) commands live in those two guides.

== A worked example

{{{
dig north
room name Kitchen
room desc A cramped kitchen. A fan turns slowly on the ceiling and the linoleum squeaks underfoot.
room keywords kitchen cook
room info
room open
}}}

You dug a room north, named, described and keyworded it, checked it over, and opened
it to players. Walk **south** to come back — that return exit was made for you.

== Custom Commands
A very common thing you want to do is add a way to create a custom command; either to show a custom flavortext or to cause something to happen. This section will detail ways that you can create a custom command such as "move painting" or "assemble telescope".

=== A command on the room itself -- **cmd_//slug//**

The simplest custom command needs no item at all -- you hang it on the **room**. A room-data field named **cmd_//slug//** defines a command, where //slug// is exactly what the player types with spaces turned into underscores. Its value is an **action** followed by its text; for now the one action is **exa**, which prints the text just like an **examine** (same colour and all):

{{{
room data cmd_examine_keyhole exa You examine the keyhole. It is unusually small. It must require an unusually small key!
}}}

Now typing **examine keyhole** in that room prints that line. A room command **pre-empts everything** -- it fires even when the word is normally a built-in (//examine//, //look//) or a live exit direction, and //only// the room command runs. It can only ever trigger on a command //you// defined, so nothing else in the room changes.

To print more than one line, add numbered continuations -- **cmd_//slug//_2**, **_3**, ... -- which run in order right after the first:

{{{
room data cmd_examine_keyhole exa The keyhole is unusually small.
room data cmd_examine_keyhole_2 exa It must require an unusually small key!
}}}

//The slug is the whole typed phrase.// "examine keyhole" is **cmd_examine_keyhole**, a bare "listen" is **cmd_listen**, "pull lever" is **cmd_pull_lever**; matching ignores case and extra spaces. A room command only //prints// (the **exa** action) -- when you want a command that actually //does// something (reveal a thing, open a way), reach for an object verb hook next.

=== Verbs on an object -- **do //word// to //thing//**

A custom command can also live on an **item** -- a prop -- and there it can do more than print. Give the prop a **verb hook** and any player who types "//word// //item//" triggers it. For example, a rug that hides a trapdoor:

{{{
item rug data verb_move A trapdoor is revealed beneath the rug!
item rug data verb_move_reveal trapdoor
}}}

Now **move rug** prints that line //and// clears the //invisible// flag on the trapdoor sibling, so it appears in the room. The same shape gives you **verb_//word//_toggle** (flip a thing hidden <-> shown), **verb_//word//_exit //dir//** (slide open a sealed passage out of the room), and more. These hooks -- with locks, keys, openables, object exits, and the complete rug-trapdoor-cellar build -- are covered in full in **[[Advanced Building]]** (//Verb hooks// and //A worked example: a rug, a trapdoor, a cellar//).

=== Commands that reach across a zone -- flags and gates

A verb hook fires in one room. When a custom command should reach //across// an area -- light three braziers scattered through the sewers and a stone door grinds open somewhere else -- the prop raises a flag on the shared **zone blackboard**, and a **gate** room elsewhere watches for the right combination:

{{{
item brazier data verb_light_zoneflag brazier_a
}}}

Lighting each brazier sets its own flag (one-way, and cleared on a zone reset so the puzzle re-arms); the gate room lists the flags it needs and un-seals a hidden exit once they are all raised. The full recipe -- flags, requiring a tool in hand, and building the gate -- is in **[[Advanced Building]]** (//Multi-room puzzles: zone flags and gates//).

== Builder help topics

* **help room** — dig / room / exit / goto
* **help zone** — the zone commands
* **help item** // and // **help mob** — items and creatures
* **help worldbuilder** // and // **help implementor** — your role's overview