Differences

This shows you the differences between two versions of the page.

--- how_to_build [2026/06/26 18:27] – appledog
+++ how_to_build [2026/07/10 04:20] (current) – external edit 127.0.0.1
@@ Line 2: / Line 2: @@
 Building is how the world grows: you **dig** new rooms, **describe** them, and
-**commit** them to make them permanent. These commands need the **worldbuilder**
+**open** them to players. These commands need a builder role: **worldbuilder** or
-or **implementor** role; ask an admin to grant it.
+**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.
-== Drafts and committing
+== Closed and open rooms
-When you dig a room it starts as a **draft**: it exists and you can walk into it,
+A newly dug room is born **closed** — under construction. A closed room can't be
-but it's flagged unfinished until you commit it. Its //look// shows a
+entered by players through its exits, and its //look// carries a **[closed]** note.
-**[draft room]** note. Run **room commit** once you're happy with it, and the
+Builders who can edit a room may simply **walk into** it (and reach it with **goto**)
-room, together with its exits and the way back, becomes permanent.
+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 room to the //north/south/east/west// and step into it.
+* **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**).
-When you dig, a **two-way** passage is made automatically: the way back is dug for
+Digging a **new** room makes a **two-way** passage (the way back is dug for you) and
-you, so the exits work in both directions. The new room also inherits the **zone**
+steps you through; the room inherits the **zone** you dug from. Linking to an
-of the room you dug from. It opens with a placeholder name and description. You can set
+**existing** room leaves you put and only adds the exit (the return exit too, if that
-those next.
+room's facing slot is free).
 == Editing the current room
 * **room name //name//** — name the room
-* **room desc //text//** — set the room's description (what players read on //look//)
+* **room desc //text//** — set the description (what players read on //look//)
-* **room info** — show the room's id, zone, exits (with their target room ids), and draft/committed state
+* **room keywords //words//** — alternate names for the room, so **goto //word//** reaches it
-* **room commit** — make the room and its exits permanent
+* **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.
+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 (it tells you the new zone's id)
+* **zone create //name//** — create a new zone (internal name; tells you its id)
-* **zone list** — list every zone and how many rooms it holds
+* **zone list** (or the **zones** command) — list all zones
-* **room zone //id|name//** — move the current room into a zone, by id or by name
+* **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
-=== Example
+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 floor squeaks underfoot.
+room desc A cramped kitchen. A fan turns slowly on the ceiling and the linoleum squeaks underfoot.
+room keywords kitchen cook
 room info
-room commit
+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
 }}}
-You dug a room to the north, named and described it, checked it over, and made it
+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//).
-permanent. Walk **south** to come back; that return exit was created for you.
 == Builder help topics
-* **help room** ... the dig / room commands
+* **help room** — dig / room / exit / goto
-* **help zone** ... the zone commands
+* **help zone** — the zone commands
-* **help worldbuilder** //and// **help implementor** — your role's overview (each gated by that role)
+* **help item** // and // **help mob** — items and creatures
+* **help worldbuilder** // and // **help implementor** — your role's overview