Questions about organizing Inform 7 code tend to pop up regularly. Here's the method I use, which is of course not the official or the only way to do it.

Taking a ready-made header structure and trying to adapt your own code to it by filling in the blanks would be too inflexible, so I build the structure dynamically as I go along. A new project starts with no headers at all. New headers are added when code gets diverse enough to justify a new classification.

Include Rideable Vehicles by Graham Nelson.


The Front Yard is a room.

In this example the extension and the room definition don't have anything in common, so they're split into different headings.

Volume 1 — Extensions

Include Rideable Vehicles by Graham Nelson.

Volume 2 — Rooms

The Front Yard is a room.

When we add a new room, there's another split (although in real life the split would come only after they have a bit more content, we'll come back to that soon).

Volume 1 — Extensions

Include Rideable Vehicles by Graham Nelson.

Volume 2 — Rooms
Book 1 — Front Yard

The Front Yard is a room.

Book 2 — Driveway

The Driveway is a room. The Driveway is west of Front Yard.

Notice how the two similar headers are grouped together with a common parent header.

The general rule of thumb is that when something has at least two paragraphs of code, it gets its own header. For example, assuming we have the following code:

Chapter 1 — Engine room

The Engine room is south of Cable-car platform. The description is 
"The wooden shack houses a large diesel generator that moves the cableway. 
The shack's walls are rotten and patchy. The exit leads back out to the north."


The diesel generator is a device in the Engine room. 
"The diesel generator [if switched on]is running loudly, 
turning the cableway.[otherwise]looks like it hasn't been 
used in quite some while." The diesel generator is fixed in place.


The shack walls are scenery in the Engine room. The description is 
"Light is shining through the wall boards."

Each thing in this room (including the room itself) has only one paragraph of code, so they'd all stay under the same heading for now. Later when the code gets some meat around the bones, some things get more paragraphs and it's time to split them under more headings.

Chapter 1 — Engine room

The Engine room is south of Cable-car platform. The description is 
"The wooden shack houses a large diesel generator that moves the cableway. 
The shack's walls are rotten and patchy. The exit leads back out to the north."

Section 1 — Diesel generator

The diesel generator is a device in the Engine room. 
"The diesel generator [if switched on]is running loudly, 
turning the cableway.[otherwise]looks like it hasn't been 
used in quite some while." The diesel generator is fixed in place.


After switching on the diesel generator:

say "The generator makes some suspicious noises but then comes to life. 
The cableway starts moving again."



After switching off the diesel generator:

say "The generator shuts down and the cableway stops."


Section 2 — Shack walls

The shack walls are scenery in the Engine room. The description is 
"Light is shining through the wall boards."

The two-paragraphs rule is not absolute; sometimes it makes more sense to keep everything under one header when the code is not that important, like decorative scenery. Inform has only five header levels which also limits the size of the pieces into which you can split the code.

The five header levels are volume, book, part, chapter and section. I haven't really attached any specific fixed meaning to different header levels. Volumes contain top-level abstractions ("Metadata", "World", "Debugging") and any subheaders just use the next immediate type (volumes contain only books, books contain only parts etc.) This means that header levels in different parts of the source text aren't comparable: an NPC in one place might be under "part" level and another NPC could be under "section" level somewhere else, with neither being necessarily more important than the other.

The header structure is generally best arranged into a tree shape so that subheaders have a logical relationship with their parent headers, and headers on the same level under the same parent header belong to the same group. In other words, the diesel generator is a subheader under the Engine room because that's where the generator is. That much should be obvious, but subheaders under the the same parent header should also share a "theme" between each other: in the above example, if one of the subheaders is a new room-specific action, it's then better to group the objects under a new parent header so that the new action is not on the same level with the objects.

The important thing here is to not get hung up on getting it right the first time. The structure is allowed to live, and I tend to move parts of code around constantly while writing. The time it takes to keep the code organized is more than generously paid back later when navigating the code is fast and intuitive.

All that said, in the end the general top-level structure tends to usually be more or less something like this:

1. Meta
   • License
   • Changelog
   • Extensions
   • Bibliographical information
   • Releasing
2. Mechanics (any of these headers could get promoted to their own volume if there's a lot of content)
   • Commands
     • Modifications to standard commands
     • New commands
     • Out of world commands
       • Credits
       • Instructions
       • Hints
   • Default messages
   • Modifications to standard rules
   • New kinds
   • Scenes
   • Gameplay logic
   • Conversation system
   • Special mechanics
3. World
   • Rooms
     • Room 1
       • Thing in room
       • Misc scenery
     • Backdrops
   • Major NPCs
4. Debugging

But, as said, this is not a rigid structure but something that tends to form as a result of the dynamic method.

Here are sources of some full projects that use this method: Sparkle, Escapade!, Raising the Flag on Mount Yo Momma. For more ideas: source code by other people.

Very often I turn transcripting on when I start playing IF. As a side effect Zoom automatically runs the command VERSION, which in case of Inform 7 games shows the list of extensions the game uses. More often than not the list is empty.

I'm a big fan of extensions. Creating an IF game takes enough time as it is, so any way of avoiding reinventing the wheel someone has already invented and made public is a big plus. Extensions don't get enough use, and I'm not alone with this opinion: Aaron Reed has called for more exposure, including blogging about the best ones. I'll take a head start by introducing some of my own favorites.

Continue reading "Some useful Inform 7 extensions" →

One thing that seems to trip authors every time in I7 is finding the name of the action to work with. Here are some hints for finding the name of the action when you encounter the "that did not make sense as a description of an action" error.

Let's say we have in our game a coin and a slot machine and we would understandably want to handle PUT COIN IN MACHINE somehow. So we write this:

  The Casino is a room.


  A slot machine is in the Casino. The player carries a coin.


  Instead of putting the coin in the slot machine:
  

    say "The coin falls through the machine and straight into the winnings tray. It must be broken."
  

Looks all good, right? But when we try it, the compiler says this:

Problem. You wrote 'Instead of putting the coin in the slot machine' , which seems to introduce a rule taking effect only if the action is 'putting the coin in the slot machine'. But that did not make sense as a description of an action. I am unable to place this rule into any rulebook.

This happens because "putting it in" is actually not the action's name. Even though when playing the game one action can have several verbs that are synonymous (eg. TAKE and GET do exactly the same thing) but in the code each action has only one name (eg. taking). Actions are like those demons in folklore where you have to know their true name before you can control them.

How do you find an action's real name then? There are a couple of ways, but these two are probably the easiest.

The first method is to open the index page and take a look at the Actions tab. (This is the Mac IDE, the Windows and possibly Linux versions have the buttons in slightly different places.)

This page lists all actions and all verbs that are available in-game. Scroll down the page and find "put".

The command PUT has different meanings depending on the context but the line we want in this case is "put [other things] in/inside/into [something]". This shows the name of the action: inserting it into.

The drawback of this method is that the index tab is not always available if there was a problem compiling the game, so you might not get to see the list without trimming the non-working parts of the code and compiling again. There's another way of finding the name of the action right in the game itself. Go to the game running in the IDE (where the debugging verbs are available), type ACTIONS to turn the actions listing on and then the command you wish to manipulate (although this suffers from the same problem as the index in Linux and possibly Windows IDE; see the comments below):

The emphasized line shows that the action that the game tries is "inserting it into", which is the name of the action we need to use in our case.