Differences

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

--- how_to_build [2026/07/10 04:02] – appledog
+++ how_to_build [2026/07/10 04:20] (current) – external edit 127.0.0.1
@@ Line 109: / Line 109: @@
 == 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