Welcome To Adventure: Lesson 4 (XYZZY!)


This is the fourth in a series of quick-start Inform 7 tutorials using examples from Colossal Cave Adventure. More information about this tutorial series can be found here: A Quick-Start Guide to Inform 7.

XYZZY Overview

It’s not Adventure without XYZZY, so this lesson will cover how to build the XYZZY command in Inform 7.

xyzzy functionality

Making the XYZZY command will involve four things:

1) Making a new action,
2) Teleporting the player,
3) Using if/then statements to teleport the player to the correct room, and
4) Teleporting the player only if the player knows about XYZZY.

To start out, we need two rooms – In Debris Room, and Inside Building. See lesson 1 to review making rooms.

Making a new action

In Inform 7, the parser is responsible for converting player commands into actions.

In essence, everything the player does is an action. The debug command ACTIONS will show you what actions have been created by various text entries, like this:

debugging with actions

As you can see, there is no action listed after asfadf because the parser could not turn it into an action.

To see a list of actions available by default in Inform, go to Index, then Actions. (This tab displays a list of actions available in the current game rather than displaying static text. As a result, the tab will only be available after successfully compiling some code with “run”.)

finding the actions list

Here is the minimum source code for creating a new action:

Xyzzying is an action applying to nothing.
Understand “xyzzy” as xyzzying.
Report xyzzying: say “You have xyzzied.”

Breaking this apart…

Xyzzying is an action applying to nothing. <– This line creates the action. It could be called any number of things in the source code – xyzzy, saying-xyzzy, magic-wording, etc. – as long as it is consistent. Without this line, xyzzying has no meaning.

Understand “xyzzy” as xyzzying. <– This line tells the parser how to recognize if the player wants to xyzzy. Typing “xyzzy” into the parser will now activate the code for xyzzying.

Report xyzzying: say “You have xyzzied.” <– Action processing is broken into check, carry out, and report. The report section is responsible for printing text after an action has been carried out successfully.

We can use ACTIONS again to verify that the new command is working, like so.

xyzzy in debug

A brief aside: actions out of world

Right now, the XYZZY command doesn’t do anything but print some text on the screen. That’s not so great for XYZZY, but most polished parser games do include informational commands such as HELP, ABOUT, CREDITS, and WALKTHROUGH for the player’s benefit. These commands can be created easily with the source code above.

However, every time a player enters a regular command, the turn counter advances, causing “every turn” rules to fire. In the context of Adventure, this covers things like your lamp’s batteries running down or the chance of a threatening little dwarf appearing. (I’ll cover “every turn” later, but if you’d prefer to read ahead, they’re discussed in section §9.5 of the Inform 7 manual.)

To turn this off, use the special syntax action out of world, like this terrible implementation of HELP:

Helping the player is an action out of world.
Understand “help” as helping the player.
Report helping the player: say “Actually, there’s no help for you. You’re on your own.”

Teleporting the player

To teleport the player, we want to use the carry out section of the xyzzying action. Here’s the updated source:

There is a room called Inside Building.
There is a room called In Debris Room.

Xyzzying is an action applying to nothing.
Understand “xyzzy” as xyzzying.

Carry out xyzzying: now the player is in In Debris Room.
Report xyzzying: say “You have xyzzied.”

Adventure doesn’t say “You have xyzzied”, of course, but it’s a good opportunity to see the order of action processing.

carrying out xyzzying

…to the correct room

In order to send the player to the correct room, we need to check the player’s current location. This was covered briefly last time when we were looking at the changing description of the rough stone steps.

Here’s the updated source code, taking the player’s location into account.

Carry out xyzzying:
 if the location is Inside Building:
  now the player is in In Debris Room;
 else if the location is In Debris Room:
  now the player is in Inside Building;
  say “Nothing happens.”

Note that the separations above need to be tabs, not spaces. Failing to use tabs will stop your code from compiling.

If you dislike tabs enough, there is an alternate syntax, as shown here:

Carry out xyzzying:
if the location is Inside Building begin;
now the player is in In Debris Room;
else if the location is In Debris Room;
now the player is in Inside Building;
say “Nothing happens.”;
end if.

The begin/end syntax ignores whitespace entirely. You could write the whole thing on one line and it would still compile.

…only if the player knows about XYZZY

At the beginning of Adventure, typing XYZZY just produces “Nothing happens.”, even if you’re in Inside Building. There are a few ways to handle this, but the easiest is to look at the visited/unvisited property of In Debris Room.

showme rooms

The check part of an action happens before carry out. It’s used to see whether there is something that will stop the action from happening. Here’s an appropriate check for our XYZZY action:

Check xyzzying:
  if In Debris Room is unvisited:
    say “Nothing happens.”;
    stop the action.

Further reading

To expand your understanding of actions, if/then logic, and teleporting the player, see the following parts of the Inform 7 manual:

§8.9 – Moving the player
§11.6 – If
§11.7 – Begin and end
§11.8 – Otherwise (synonymous with “else”)
§12.7 – New actions
§12.9 – Check, carry out, report
§12.15 – Out of world actions

Bookmark the permalink.


  1. Thanks for showing the Inform index! It’s gotten incredibly useful in recent iterations especially for updating default library messages.

  2. Thank you for this, I was really scratching my head how to do doorless navigation.

Leave a Reply

Your email address will not be published. Required fields are marked *