Welcome to Adventure: Lesson 9 (Darkness and the Lamp)


This is the ninth and final entry 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.

This lesson will cover the darkness of the cave and Adventure’s iconic lamp.

It is now pitch dark.

Inform 7 has a basic light and darkness system. Rooms can be “dark” or “lighted”, and having an object with the “lit” property will enable the player to see in dark rooms. Without a “lit” object, actions requiring visibility will be blocked with the default message “It is pitch dark, and you can’t see a thing.”

alt text Adventure Tutorial An Interactive Fiction by Carolyn VanEseltine Release 1 / Serial number 150122 / Inform 7 build 6L38 (I6/v6.33 lib 6/12N) SD Darkness It is pitch dark, and you can't see a thing. >x me It is pitch dark, and you can't see a thing. >

Which actions are blocked in darkness? By default, only examine, look under, and search are blocked. You can check the list for your own game by going to the Index tab, then choosing Actions, and then scrolling down to the Alphabetic listing, where the words “requiring light” will appear beside any actions requiring light.

Index showing a list of actions requiring light

Using the “kinds” system (discussed in lesson 7), we can set up caves as a kind of room that is dark by default.

A cave is a kind of room. A cave is usually dark.

There is a cave called Low N/S Passage.

Now every cave in the game will be dark by default.

Customizing the darkness

The regular darkness message in Adventure is different than the regular darkness message in Inform 7.

What we currently see is “It is pitch dark, and you can’t see a thing.” This is perfect for messages relating to examining and searching, but it isn’t the correct room description. What we need there is “It is now pitch dark. If you proceed you will likely fall into a pit.”

…and we need pits.

First things first: in the Inform handbook, §18.18 through §18.22 deal with the standard behavior of the dark/light system. These sections provide the names of five key rules:

  • Rule for printing a refusal to act in the dark
  • Rule for printing the announcement of darkness
  • Rule for printing the announcement of light
  • Rule for printing the name of a dark room
  • Rule for printing the description of a dark room

We can overwrite any of the standard behaviors within our source code by explicitly naming the rule we want to overwrite. For example, we can edit the default description for a dark room like so:

Rule for printing the description of a dark room:
    say “It is now pitch black. If you proceed you will likely fall into a pit.” instead.

The pits in Adventure are not actual objects that can be examined and interacted with. Consequently, we don’t need to create them as things. The appropriate messaging can be constructed with an “after going” rule, like so:

After going when the location is a dark room:
    if a random chance of 1 in 4 succeeds:
        say “You fell into a pit and broke every bone in your body!”;
        end the story saying “Ow.”;
        continue the action.

(Of course, the Adventure death system is more complex than “ow”, but this section has already gotten somewhat off topic.)

Identifying the rules you want to change

The Inform 7 handbook explicitly talks about the dark/light system, which makes it easy to find the rules we need to change. But it is sometimes more difficult to figure out what rules are producing a given result, especially when debugging.

Technique #1 – Debug commands

Inform 7 games run by stepping through a series of prioritized rules. The debugging command RULES ON will show you a step-by-step view of everything your game is doing. For example, here’s the rule-by-rule view for getting the lamp…

rules listing - Inside Building You can see a shiny brass lamp here. >rules on Rules tracing now switched on. Type "rules off" to switch it off again, or "rules all" to include even rules which do not apply. >get lamp [Rule "declare everything initially unmentioned rule" applies.] [Rule "announce items from multiple object lists rule" applies.] [Rule "set pronouns from items from multiple object lists rule" applies.] [Rule "before stage rule" applies.] [Rule "instead stage rule" applies.] [Rule "investigate player's awareness before action rule" applies.] [Rule "player aware of his own actions rule" applies.] [Rule "check stage rule" applies.] [Rule "can't take yourself rule" applies.] [Rule "can't take other people rule" applies.] [Rule "can't take component parts rule" applies.] [Rule "can't take people's possessions rule" applies.] [Rule "can't take items out of play rule" applies.] [Rule "can't take what you're inside rule" applies.] [Rule "can't take what's already taken rule" applies.] [Rule "can't take scenery rule" applies.] [Rule "can only take things rule" applies.] [Rule "can't take what's fixed in place rule" applies.] [Rule "use player's holdall to avoid exceeding carrying capacity rule" applies.] [Rule "can't exceed carrying capacity rule" applies.] [Rule "carry out stage rule" applies.] [Rule "standard taking rule" applies.] [Rule "after stage rule" applies.] [Rule "investigate player's awareness after action rule" applies.] [Rule "report stage rule" applies.] [Rule "standard report taking rule" applies.] Taken. [Rule "last specific action-processing rule" applies.] [Rule "A first turn sequence rule" applies.] [Rule "every turn stage rule" applies.] [Rule "A last turn sequence rule" applies.] [Rule "notify score changes rule" applies.] >

This is a bit overwhelming, but it does show that the “standard report taking rule” is responsible for printing the word “Taken”, and when.

A related technique is ACTIONS ON, which shows every action being executed.

action listing - >actions on Actions listing on. >get lamp [taking the shiny brass lamp] Taken. [taking the shiny brass lamp - succeeded]

Technique #2 – Accessing the IDE’s index

Check the Index for the specific action in question. The magnifying glass icon beside each action will take you to a detailed view of the action.

view of the Index's actions listing, showing the magnifying glass icons beside each listed action

Critical actions like “look” have some notes at the top, but when you scroll past them, you’ll find details about exactly how the action works – what rules control it, what named values it includes, and what the default messages associated are.

action details - view of "look" in the Inform 7 IDE

The speech bubbles here indicate the presence of default responses that are built into the game. If we were still trying to alter the darkness messaging, we could check here for those default darkness messages by clicking the speech bubbles.

view of "look" in the index, displaying the default darkness messages

And here are the two darkness messages again!

Note the button marked “set” beside each message. This button will add code to your game that allows you to change the default message. We could have changed the darkness text this way instead of changing the activity, and this would also have been a valid solution.

The shiny brass lamp

Inform 7 has a built-in kind called the device, which can be switched on or switched off. This is extremely convenient for making, say, shiny brass lamps.

A shiny brass lamp is a device in Inside Building.

After switching on the lamp:
    now the lamp is lit;
    continue the action.

After switching off the lamp:
    now the lamp is unlit;
    continue the action.

The lamp is battery-powered (despite all my childhood impressions of something Aladdin-esque) and can only endure for so many turns. Every turn, it loses a little more power, and that phrase “every turn” is absolutely a hint as to how this can be implemented.

The shiny brass lamp has a number called the power. The power of the shiny brass lamp is 500.

Every turn when the shiny brass lamp is lit:
    now the power of the shiny brass lamp is the power of the shiny brass lamp – 1;
    if the power of the shiny brass lamp < 1:
        say “Your lamp has run out of power.”;
        now the lamp is unlit.

There are many more details that could be added to this implementation – the low battery warning message, the ability to add new batteries, the varying text when the lamp is on the ground lit or unlit. But we’ve already covered techniques for each of these…

  • Low battery warning message – write an appropriate “if” statement in the every turn rule
  • Adding new batteries – write a new “instead” rule for inserting batteries into the lamp
  • Varying text based on the lamp’s state – write an [if the lamp is lit]/[otherwise] rule into the description

…so walking through them would be redundant.

Further Reading

Part of this lesson addressed the concept of rules, which are the most basic machinery of Inform 7. For the most part, it is not necessary to understand rulebooks work in order to build an Inform 7 game. To peek further under the hood, see Chapter 19: Rulebooks.

§3.15. Light and darkness
§4.2 Using new kinds
§18.18 Printing a refusal to act in the dark
§18.19 Printing the announcement of darkness
§18.20 Printing the announcement of light
§18.21 Printing the name of a dark room
§18.22 Printing the description of a dark room
§24.3. High-level debugging commands

Bookmark the permalink.


  1. I’ve learned so much from this series. Thank you!

  2. Just a question – When you’re discussing falling into a pit, you put the chance of falling into an “After going” rule. Shouldn’t it be “After going while in darkness” or something similar? Otherwise those invisible pits will kill adventurers in broad daylight once out of every four steps…

Leave a Reply

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