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.

Here are the major new features:

• Works with Undum. Now someone might wonder why anyone would want to record hypertext fiction stories, but even if there's less need to check what kind of input readers give, other reasons still apply: you might want to get statistical data on which choices the readers make, or see if the readers give up at some certain point in the story, or even find out if some of the choices just don't work as they should.
• Web interpreter template for Inform 7. There's a ready-made Inform 7 template to use with the "Release along with an interpreter" option. This makes it easier to start using the recorder although you still have to set up the database and the server scripts.

The project's new headquarters are at Github along with the instructions and downloads.

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.

Epistemology by Eric Eve

By far the most useful extension I've yet found. The first thing I do every time I start a new project is including this extension because it will almost certainly be used.

Epistemology adds two properties to every thing in the game: seen/unseen and familiar/unfamiliar. Every object starts as unseen and when the player encounters things (is in the same room or looks in the container where the object is) they automatically change to being seen. The familiar/unfamiliar property is what the author can toggle when needed if the player character already knows about something or learns about it during the game. The author can test whether a thing is either seen or familiar by checking if it's known or unknown.

The most obvious use is for an ask/tell conversation system: you can prevent the player from asking about things that the player character would not yet know about by defining the action as "ask [person] about [any known thing]".

In addition you should consider using the [any known thing] token every time when an action allows any noun to be used (not only those in scope). Let's say you want the player to be able to get more information about NPCs by commanding WHO IS. You've implemented the command with the grammar line "who is [any person]". You don't want the player to ask about John Q. Public, who is the surprise villain of your game. So you write something like this:

That works well when the player refers to John Q. by his full name, but now disambiguation can give the surprise away:

It's better to use "who is [any known person]" to avoid the disambiguation mechanism revealing things the player shouldn't know about.

Far Away by Jon Ingold

Far Away provides the adjective "distant" which simply puts things out of the player's reach. Anything except examining (and other actions that do not require touch) will be blocked with a "you can't reach it" message.

Far Away is most useful for filling in scenery items mentioned in room descriptions. You can create the item, give it a description, make it distant, and then just forget about it. No need worrying whether touching the sun or taking the clouds gives a reasonable response -- the response is always the "can't reach" one.

Object Response Tests by Juhana Leinonen

There's a reason other than shameless self-promotion for this extension to be on this list. The amount of verbs in the standard library is huge and testing each object against each verb is a staggering task. Object Response Tests allows you to try every available verb on one item with a single command. You can scan the output for unsuitable responses, like "You feel nothing unexpected" when the player types TOUCH THE FIRE.

You can also try a single verb on all objects in scope, or all verbs on all objects at once. Any custom commands in the game can be added to the testing batch, or disabled commands removed from it. Testing commands are disabled in the released game.

The extension is not a replacement for proper testing done by humans, but it will help catch some of the cases easily missed by testers.

Disambiguation Control by Jon Ingold

Another one of Jon Ingold's extensions, Disambiguation Control, completely replaces the default disambiguation mechanism. It's a tinkerer's dream: in addition to improving the parser's functionality in general, you get to define the parser's disambiguation preferences to whatever you want.

In contrast to the extensions mentioned before, this is not one that I'd recommend to everyone. I7's own disambiguation engine works fairly well in most cases. Disambiguation Control requires a relatively large amount of learning to use efficiently. It will also potentially increase the author's work because it adds new layers and options to the mechanism that by default does everything more or less automatically. Nevertheless if you find yourself thinking the standard parser's disambiguation should be smarter or hoping for more control over disambiguation choices, this is the extension for you.

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.