Chapter 17: Understanding
17.1 Understand
This chapter is about player input. The concept is fundamental, and its basics are covered in earlier chapters.
‘Understand’ sentences, this section teaches, are used to convert typed player commands into computer-understood stuff.
For actions specifically, we usually put one ‘variable’ in our understand statement for each variable declared, as so:
Photographing is an action applying to one visible thing and requiring light.
Understand "photograph [someone]" as photographing.
Understand "photograph [an open door]" as photographing.
What would be bad is not having them match up:
Understand "photograph" as photographing.
Understand "photograph [someone] standing next to [something]" as photographing.
The first is probably bad because it supplies no things at all, the second is certainly because it supplies two: what we want, of course, is just the one. (The reason the first is only probably bad is that it’s possible to tell Inform how to choose the object if the player doesn’t: see the “supplying a missing noun” activity.)
Example 286 is Indirection:
Using colors as directions (in reference to the Mayans).
Understand "white" and "sac" as north. Understand "red" and "chac" as east. Understand "yellow" and "kan" as south. Understand "black" and "chikin" as west.
Example 287 is XYZZY:
Understand "xyzzy" or "say xyzzy" or "cast xyzzy" as casting xyzzy.
Casting xyzzy is an action applying to nothing.
Check casting xyzzy:
if the player does not wear the amulet of elocution, say "You are unable to articulate the second 'z' separately from the first, and the spell fails in a disdainful puff. Must be Parisian magic." instead;
if the player has the plate, say "The plate of cheeses twitches uncomfortably, aware that it should be doing something, but not sure what." instead.
Carry out casting xyzzy:
move the plate to the player.
Report casting xyzzy:
say "Under the influence of the Amulet of Elocution, you pronounce this as Xhi-zee. And lo, from nowhere, a [plate] appears!"
This is intended to show an example of an action requiring no objects/variables.
Example 288 is Xylan:
Understand "hydrolyze [something]" as hydrolyzing. Hydrolyzing is an action applying to one thing.
Carry out hydrolyzing:
say "[The noun] cannot be hydrolyzed."
Instead of hydrolyzing the xylan:
move the xylose to the holder of the xylan;
now the xylan is nowhere;
say "At once the xylan becomes xylose."
There is a xylose sample. The xylan sample is a thing in Plant Cell Wall. The description of the xylan is "A polysaccharide. Totally useless. If only you had some xylose, instead!" The description of the xylose is "Awesome!"
This is given as a ‘bad example’, since it’s kind of a guess the verb situation.
So the suggestion is to add synonyms, alternative spellings, and in-game nudges and full-fledged hints:
Understand "break down [something] with water" or "break [something] down with water" as hydrolyzing.
Understand "hydrolyse [something]" as hydrolyzing.
Instead of examining the player, say “You’re a drop of water, which means that you can break down certain chemicals!”
Understand "break down [something]" or "break [something] down" as hydrolyzing.
Understand "help" or "hint" or "hints" or "instructions" or "info" or "about" as asking for help. Asking for help is an action out of world. Carry out asking for help: say "The following commands are understood, in addition to the standard ones: EVAPORATE, FREEZE, HYDROLYZE, SUBLIME..."
Man, this stuff is very helpful. It’s a shame this chapter is so late in the book; I remember the ‘actions’ chapter seemed like it was missing a lot of key examples, and I guess they’re all here. I get why this chapter is delayed, since it includes complex things like understanding by relations, but I wonder if it could be split up into 'Understanding" and ‘Advanced Understanding’, and the first part moved earlier.
Section 17.2 is New commands for old grammar.
This just says that you can add synonyms to pre-existing inform commands:
Understand "deposit [something] in [an open container]" as inserting it into.
We can also flip the orders of things around:
Understand "fill [an open container] with [something]" as inserting it into (with nouns reversed).
This next part is so revelatory to me that I will quote it in full:
The following example:
Understand "access [something]" as opening.
might look as if it makes “access” behave just like “open” when the player types it, but that’s not so: “open” can also be used in constructions like “open the door with the brass key”, in which case it is understood as the unlocking action. We could add another line to make “access” behave this way too, but if what we really want is to make “access” behave just like “open”, it’s easier simply to say so:
Understand the command "access" as "open".
Example 289 is Alpaca Farm, which shows how one verb can be given many meanings:
Understand "use [an edible thing]" as eating.
Understand "use [a wearable thing]" as wearing.
Understand "use [a closed openable container]" as opening. Understand "use [an open openable container]" as closing.
Understand "use [something preferably held] on [a locked lockable thing]" as unlocking it with (with nouns reversed). Understand "use [something preferably held] on [an unlocked lockable thing]" as locking it with (with nouns reversed).
Understand "use [a switched off device]" as switching on.
Understand "use [something]" as using. Using is an action applying to one thing. Carry out using: say "You will have to be more specific about your intentions."
Understand "use [a door]" as opening. Understand "use [an open door]" as entering.
(Note the ‘something preferably held’ up above, which I think there was a section on earlier but hasn’t been used much so far).
Example 290 is Anchorite:
Understand "get down" as exiting.
Instead of going down when the player is on a supporter:
try exiting.
Example 291 is…Cloak of Darkness! A rare 4-star example. As the documentation says:
“Cloak of Darkness” is a brief example game that has been implemented in nearly every IF system currently used. It hasn’t got much claim to complexity or richness, but it does exemplify many of the standard things one might want an IF language to be able to do: define descriptions and the results of actions, assign synonyms to nouns, create new verbs, handle darkness, track repeated acts, and so on.
Section 17.3 is Overriding existing commands.
This is where Inform already has a certain behavior for a command and you want to eliminate it. For instance, ‘discard’ already means ‘drop’, but maybe you don’t want it to. So you can type this to remove its previous associations:
Understand the command "discard" as something new.
I’d like to give a personal warning here from my own experience and from watching other coders:
So often new players think, like, ‘I want to be able to CLEAN GLASSES’, but ‘CLEAN’ is mapped to RUB! I’ll just disconnect them and make a new ‘clean’ action!
But…the thing is, rub/clean is already a cleaning action! People just don’t like that the in-code name is rubbing. They want to type, ‘instead of cleaning the glasses’.
But if you just leave the command alone and type, ‘instead of rubbing the glasses’, it involves way less work. That’s just my opinion: if you’re doing the ‘something new’ commands to make room for a new command, but never use the old command for anything, you might as well have just used the old command all along.
Anyway, once you say ‘understand…as something new’, you can just use it like any other word:
Understand "discard [something]" as discarding.
You can also say ‘as something new’ for stuff that isn’t actually a command already. That’s on purpose, to make your code still be good even if an extension you are using changes.
You can also, instead of removing meaning from a word, remove all words from a meaning:
Understand nothing as taking.
Then no command will cause the taking action. But for this specific example:
The commands “take” and “get” will still exist, but now they’ll only have their other senses (for taking off clothes, for getting out of boxes).
Example 292 is The Trouble with Printing
This is a classic example that lets you make 'read’ing and 'examin’ing different.
A thing has some text called printing. The printing of a thing is usually “blank”.
Understand the command "read" as something new. Understand "read [something]" as reading. Reading is an action applying to one thing, requiring light. Check reading: if the printing of the noun is "blank", say "Nothing is written on [the noun]." instead. Carry out reading: say "You read: [printing of the noun][line break]". Report reading: do nothing.
Example 293 is Lanista 2 (I don’t really remember Lanista 1):
Understand the commands "attack" and "punch" and "destroy" and "kill" and "murder" and "hit" and "thump" and "break" and "smash" and "torture" and "wreck" as something new.
(couldn’t we just say 'understand nothing as attacking?)
Attacking it with is an action applying to one visible thing and one carried thing. Understand "attack [someone] with [something preferably held]" as attacking it with.
Section 17.4 is Standard tokens of grammar.
This is another essential section. Honestly, this chapter should probably be one of the first a new author reads, after Actions.
Tokens are things like [something] or [someone] that matches patterns.
This section contains the following enigmatic phrase:
“[someone]” matches the same possibilities as “[a person]” would, but the parser handles it a little better in cases of failure.
You can modify tokens like this:
Understand "wear [something preferably held]" as wearing.
This is used to resolve ambiguities. You could also make commands that require you absolutely to be holding something, but doesn’t give an example of how to do so.
If you want to allow multiple things, you can type ‘things’:
Understand "take [things]" as taking.
Understand "drop [things preferably held]" as dropping.
You can use special phrases I’ve never seen to exclude everything in a container or everything not in a container:
Understand "put [other things] in/inside/into [something]" as inserting it into.
Understand "take [things inside] from [something]" as removing.
Finally is the thing that really screw up new authors: [any things]. This can include any object in the entire game, and objects ‘off stage’ and never seen. Typing ‘all’ with it would do your action to every single thing in the game!
Example 294 is Shawn’s Bad Day, which allows Examine All.
Understand "examine [things]" as examining.
Example 295 is The Left Hand of Autumn
Understand "examine [things]" or "look at [things]" as multiply-examining. Multiply-examining is an action applying to one thing.
Carry out multiply-examining:
let L be the list of matched things;
if the number of entries in L is 0, try examining the noun instead;
if the number of entries in L is 1, try examining entry 1 of L instead;
describe L;
say line break;
now group-description-complete is true.
There’s a lot more highly technical code here that gives special code for looking at a group of things that happens to have deep meaning.
Section 17.5 is ‘The text token’.
This is for commands where people should be able to type in stuff like a locker combination, or a question.
The token for “accept any text here” is just “[text]”
For instance:
Getting help about is an action applying to one topic.
Understand "help on [text]" as getting help about.
(Notice we say ‘one topic’ and later say ‘the topic understood’, instead of ‘one text’ or ‘the text understood’. That really tripped me up).
The fact that “[text]” can match anything means that it’s difficult to tell which version of a command was intended if they disagree only from a “[text]” onwards. For example, given:
Yelling specifically is an action applying to one topic. Understand "yell [text]" as yelling specifically. Understand "yell [text] at/to [someone]" as answering it that (with nouns reversed).
Example 296 is Ish.
Understand "help [text]" or "help about [text]" as getting help about. Understand the commands "instructions" or "hint" or "hints" or "menu" or "info" or "about" as "help".
Getting help about is an action applying to one topic.
Carry out getting help about:
if the topic understood is a topic listed in the Table of Standard Help:
say "[explanation entry][paragraph break]";
otherwise:
say "You're out of ideas."
Table of Standard Help
| topic |
title |
summary |
explanation |
| “sushi” |
“sushi” |
“Really it’s just vinegary rice” |
“Popular misconception says that sushi inevitably entails raw fish, but it is in fact just rice with rice vinegar on it. It’s just that the really good kinds have raw fish in.” |
| “cucumber roll” or “cucumber” |
“Cucumber roll” |
“Sushi for people who are afraid of sushi” |
“It is just rice and slivers of cucumber in the middle, and as long as you don’t go too crazy with the wasabi, all should be well.” |
| “california roll” or “california” |
“California roll” |
“Travesty of the sushi concept” |
“It’s. Fake. Crab.” |
| “monkfish liver” |
“monkfish liver” |
“Expert eaters only” |
“The odds of Ichiro’s having this unusual delicacy is near zero.” |
| “microdot” |
“microdot” |
“What you came here to deliver” |
“There’ll be time enough for that later. If Fowler ever turns up. Where is she, anyway?” |
Example 297 is Nameless:
This lets you ask about physical objects (I did this in Grooverland):
A thing can be known or unknown. The Nameless Advisor is known.
Understand "ask [someone] about [any known thing]" as interrogating it about. interrogating it about is an action applying to two visible things.
Instead of asking Nameless Advisor about a topic listed in the Table of Nameless Advisor Topics:
say "[reply entry][paragraph break]".
Table of Nameless Advisor Items
| item |
reply |
| letter |
“‘It is enciphered,’ she remarks[if the advisor can see the letter], glancing over the contents[otherwise], after you have offered a detailed description[end if]. ‘A substitution cipher of some complexity, I believe.’” |
| Advisor |
“She listens to your inquiries about her identity and parentage with a placid smile, but does not answer.” |
Section 17.6 is Actions applying to kinds of value
Most actions apply to things, but they don’t have to. They can apply to specific kinds of values!
Adjusting it to is an action applying to one thing and one number.
Understand "adjust [something] to [a number]" as adjusting it to.
But if you type ‘applying to one number’, you have to put [a number] in the token area.
Example 298 is Safety:
(I have the text for this copied almost word for word in my game. Or, actually, I think I removed it and replaced it with another example from later on in this chapter, though I’ve never read the whole chapter).
In the Safe is a silver florin. The Safe is closed and fixed in place. Understand "dial" as the Safe.
Spinning it to is an action applying to one thing and one number. Check spinning it to: if the noun is not the Safe, say "[The noun] does not spin." instead. Report spinning it to: say "Click! and nothing else happens."
Understand "spin [something] to [a number]" as spinning it to.
After spinning the closed Safe to 1384: now the Safe is open; say "Clonk! and the safe door swings slowly open, revealing [a list of things in the Safe]."
Example 299 is Tom’s Midnight Garden:
Understand "set [clock] to [time]" as setting it by time. Setting it by time is an action applying to one thing and one time.
Instead of setting a clock to something:
say "[The noun] can be set only to a time of day, such as 8:00 AM, or midnight."
Carry out setting a clock by time:
now the current time of the noun is the time understood.
Report setting a clock by time:
say "You set [the noun] to [time understood]."
Every turn:
repeat with item running through switched on clocks:
now the current time of the item is one minute after the current time of the item.
Example 300 (woohoo! We’ve gotten far):
This example, Ibid, shows how to make a footnote system. I won’t reproduce chunks here, but it lets the game say something like [Footnote 3] and then have the player be able to look up that footnote, with only the revealed footnotes being allowed to be looked up, and numbering of footnotes being in order of their being revealed.
Example 17.7 is Understanding any, understanding rooms
The token [something] only matches what is within reach (most of the time) or in sight (if we typed one visible thing).
If we want to be able to ignore scope, we can say:
Understand "manipulate [any door]".
To avoid this perhaps too-strong power, you can restrict it by a description:
Understand "go to [any adjacent visited room]" as going by name.
Going by name is an action applying to one thing.
As might be expected, “[anything]” means the same as “[any thing]”; “[anybody]” and “[anyone]” mean the same as “[any person]”; and “[anywhere]” means the same as “[any room]”.
Example 301 is One of Those Mornings:
Understand “find [any thing]” as finding.
Finding is an action applying to one visible thing.
Carry out finding:
if the player is carrying the noun:
say "You're holding [the noun]!";
otherwise:
say "You left [the noun] [if the noun is on a supporter]on[otherwise]in[end if] [the holder of the noun]."
Example 302 is Actaeon:
A person has a room called last location.
Understand "follow [any person]" as following. Understand the commands "chase" and "pursue" as "follow".
Following is an action applying to one visible thing.
Check following:
if the noun is the player, say "Wherever you go, there you are." instead;
if the noun is visible, say "[The noun] is right here." instead;
if the last location of the noun is not the location, say "It's not clear where [the noun] has gone." instead.
Carry out following:
let the destination be the location of the noun;
if the destination is not a room, say "[The noun] isn't anywhere you can follow." instead;
let aim be the best route from the location to the destination;
say "(heading [aim])[line break]";
try going aim.
To move (pawn - a person) tidily to (target - a room):
now the last location of the pawn is the holder of the pawn;
move the pawn to the target.
Section 17.8 is Understanding names
This mentions that we can use ‘understand’ to name objects, and not just actions.
This…is one of the absolute most fundamental things in Inform. Bizarre that it’s in the middle of a chapter 3/4 of the way through the book.
For instance, writing
The St Bernard is an animal in the Monastery Cages.
makes ST BERNARD refer to the dog, and MONASTERY CAGES refer to the room. But sometimes, as here, that isn’t really enough. Why shouldn’t the player type EXAMINE DOG? One way to allow this is to write:
Understand "dog" as the St Bernard.
If you make a kind and make multiples of a kind, inform automatically makes a plural for it. So if you code in:
The Lake is a room. A duck is a kind of animal. Four ducks are in
the Lake.
then you can type TAKE DUCKS.
In that situation, you can make your own plurals:
Understand "birds" and "ruddy ducks" as the plural of duck.
And you can make a plural for a single item:
The magpie is in the Lake. Understand “birds” as the plural of the magpie.\
Why? So you can do this:
And now TAKE BIRDS tries to take all four ducks and the magpie too.
17.9 is Understanding kinds of value
Given any kind of value you create, you can just put the name of it in brackets and Inform will understand it.
Limb is a kind of value. The limbs are left leg, left arm, right leg and right arm.
Detailing is an action applying to one limb and one visible thing, requiring light. Check detailing: if the camera is not carried then say "You can hardly photograph without a camera, now can you?" instead. Report detailing: say "Click! You take a detail photograph of the [limb understood] of [the second noun]."
Understand "photograph [limb] of [a person]" as detailing.
If you use [a time], inform understands that as Time of Day only. But it won’t understand a duration of time, which needs something like [a time period].
Example 303 is Pages:
Understand "read [number] in/from/of [something]" or "read page [number] in/from/of [something]" or "look up page [number] in/from/of [something]" or "consult page [number] in/from/of [something]" as reading it in. Reading it in is an action applying to one number and one thing, requiring light.
There’s quite a bit of other work in here as well.
Example 304 is Down in Oodville.
This is a way to give numbered options that don’t interrupt regular text.
Understand "[number]" as selecting.
Selecting is an action applying to one number.
Check selecting:
if the number understood is greater than the number of filled rows in the Table of Transport Options or the number understood is less than one:
say "[The number understood] is not a valid option. ";
list the transport options instead.
To list the transport options:
let N be 1;
say "From here you could choose to go to: [line break]";
repeat through the Table of Transport Options:
say " [N]: [transport entry][line break]";
increment N.
Table of Transport Options
transport
an object
with 3 blank rows. [In the current scenario, the number of blank rows need never be greater than the number of rooms in the game, minus the transport room itself.]
After entering the transporter pad:
say "The transporter beeps and glows amber as you step onto its surface. A moment later a hologram displays your options. [run paragraph on]";
empty the transport options;
load the transport options;
list the transport options.
(This reminds me of Hybrid Choices, which was a super popular extension for several years).
Example 305 is Straw to Gold:
R-name is a kind of value. The R-names are dwarf, guy, dude, and man-thing. Rumpelstiltskin has an R-name. Understand "[R-name]" as Rumpelstiltskin.
After reading a command:
if the player's command includes "[R-name]",
now the R-name of Rumpelstiltskin is the R-name understood;
if the player's command includes "Rumpelstiltskin":
now Rumpelstiltskin is identified;
now Rumpelstiltskin is proper-named.
Rule for printing the name of Rumpelstiltskin when Rumpelstiltskin is unidentified:
if the R-name of Rumpelstiltskin is man-thing:
say "man";
otherwise:
say "[R-name]".
I’m guessing at the very end we don’t have to mention which r-name we’re printing because we referred to rumpelstiltskin earlier?
Example 17.10 is Commands consisting only of nouns. I’ve done this before with my conversation system, which models topics as nouns; many people find it desirable to say just the name of the topic to bring it up.
You can do it like this:
Understand "[something]" as examining.
One caveat here is that you can’t use this kind of verb and command other people to use it. Why?
It also has what may be a serious limitation: verbless commands like this work only when typed by the player as actions to follow - they do not work as instructions for other people. So for instance SVEN, BALL would not ask Sven to try examining the ball - instead it would generate the action “answering ball to Sven”. (This is because the Inform parser decides whether PERSON, SOME TEXT is a request or just conversation by looking at the first word after the comma to see if it’s a command.)
Example 306 is Misadventure
Understand "[any room]" as going by name. Understand "go to [any room]" as going by name.
Going by name is an action applying to one thing.
Check going by name:
if the noun is the location, say "You're already in [the location]." instead;
if the noun is not adjacent and the noun is unvisited, say "That noun did not make sense in this context." instead.
Carry out going by name:
let aim be the best route from the location to the noun, using doors;
if aim is not a direction, say "You can't think how to get there from here." instead;
say "(heading [aim])[command clarification break]";
try going aim;
if the location is not the noun, say "You'll have to stop here."
Example 307 is Safari Guide
Understand "go to [any room]" as going by name. Understand "[any room]" as going by name. Understand "[door]" as entering.
Going by name is an action applying to one thing.
Check going by name:
if the noun is the location, say "You're already in [the location]." instead.
Carry out going by name:
while the player is not in the noun:
let heading be the best route from the location to the noun, using even locked doors;
if heading is not a direction, say "You can't think how to get there from here." instead;
let destination be the room heading from the location;
say "(heading [heading])[command clarification break]";
try going heading;
if the player is not in the destination, rule fails.
Section 17.11 is Understanding values.
You can use ‘understand’ to refer to an entire kind of thing at once! So you can make ‘machine’ a synonym of every device like so:
Understand "machine" as a device.
You can write new names for individual values:
Understand "eleventy-one" as 111.
Example 308 is Palette:
Colour is a kind of value. The colours are white, red, blue and green.
The canvas has a colour. The canvas is white. The printed name of the canvas is "largely [colour] canvas".
Painting is an action applying to one thing and one colour. Check painting: if the noun is not the canvas, say "Centuries of tradition suggest that canvas is the natural home of paint." instead. Carry out painting: now the colour of the canvas is the colour understood. Report painting: say "You splash away at the now [canvas]."
Understand "paint [something] [a colour]" as painting.
Understand "calico" as white. Understand "cerulean" or "cerulean blue" as blue.
Example 309 is Baritone, Bass
Gender is a kind of value. The genders are masculine, feminine, and unknown. Understand "male" or "man" or "M" as masculine. Understand "female" or "woman" or "F" as feminine.
A person has a gender. The gender of the player is unknown.
When play begins:
now the command prompt is "Please choose a gender for your character. >".
After reading a command when the gender of the player is unknown:
if the player's command includes "[gender]":
now the gender of the player is the gender understood;
if the gender of the player is unknown:
say "This story requires a selection of male or female. [run paragraph on]";
reject the player's command;
if the gender of the player is masculine, now the player is male;
if the gender of the player is feminine, now the player is female;
say "[line break]Thank you. We now begin...";
now the command prompt is ">";
move the player to Sandy Beach;
reject the player's command;
otherwise:
say "Sorry, we're not ready to go on yet. [run paragraph on]";
reject the player's command.
And I’ll stop there for the day! This is a big chapter, after all. I’ll probably split Activities up into multiple days as well (40 sections!) while most of the rest are fairly short.
