I’m trying to figure out Inform 7 headings. I’ve perused the Inform 7 built-in documentation as well as Ron Newcomb’s Inform 7 Programmer’s Manual and I think I have them nailed down, but would like confirmation - and to ask one additional question.
It looks like Inform 7 likes the following hierarchical headings. I think I understand the good-practice behind using them, from reading Newcomb’s book and Reed’s Creating Interactive Fiction with Inform 7 - they make debugging a little easier and can help organize the project the way I ordered essays when I was doing a lot of writing.
Now my question on their use: do you use headings to organize the source text or to organize the story? If Inform 7 was object-oriented I’d expect headings like “Rooms”, “Traps”, “Puzzles”, “NPCs”, and so on. But it seems the headings features is really intended to help structure a story?
I fuss around with organization from time to time. I tend to refactor whenever anything starts to bug me.
There are different ways to organize, of course, but this is what I’ve done with my WIP:
The first half of my source is sort of “mini-extensions” - new actions, modifications to grammar, common properties and relations, general stuff that’s not quite general or complex enough to go in a full extension, but not specific enough that it needs to refer to any specific objects in my game.
The second half isn’t quite as well organized. My original plan was to divide it into “Places,” “People,” and “Events,” but of course the story isn’t as neat as that. If I had it to do again, I might divide it into beginning, middle, and endgame, or into areas of the map that have more tightly coupled puzzles.
Whenever I refactor anything, I try to move stuff so that I can comment out parts of the source working backwards from the end without breaking any dependencies. That way it’s easier to trim the source down when looking for bugs.
In addition to making debugging easier, the headings also allow you to use shortened versions of object names unambiguously. If you have, let’s say, a bunk bed declared in Chapter 1 and a double bed in Chapter 2, then the compiler will (if memory serves) understand that you mean the bunk bed if you just call it “bed” provided you’re writing in Chapter 1, whereas in Chapter 2 an unadorned reference to “bed” will refer unambiguously to the double bed.
With respect to “it should be written as a story,” I think that depends on how you view stories as being written. It also depends on how you envision your story as being unfolded or encountered by the player during the course of the game.
I don’t think there’s any right or wrong way to use headings. You can easily make every room a separate Chapter in Volume 1, put all of the scene-related code in Volume 2, put the hints in Volume 3, and so on. Inform is pretty open-ended (though not entirely open-ended) in letting you structure the code however you prefer.
What’s helpful, I think, is a certain measure of internal consistency. If the butler is an NPC, I would personally suggest putting all of the code that directly controls the butler object in one section, rather than leaving some of it in the room where the butler is first encountered, some of it in a separate chapter on NPC conversations, some of it in a chapter containing newly defined actions, and so on. Inform will let you organize it that way, but it’s messy and error-prone.
Though it may make your head a’splode, I’d really recommend looking at the source for Blue Lacuna. Due to the scope of the game, organization is really… um… important. Though I haven’t the slightest idea what Mr. Reed is doing for most of this, it’s a pretty fine example of how using Inform’s limited organizational capabilities can be used to their seemingly ideal potential.
I think the best way to find how you like to use them is by experience and trial and error.
Code away at your game. Eventually there’ll be a moment where you say to yourself, ‘Hm, it’s annoying that A isn’t next to B.’ Then you might cut and paste so that A is now next to B, and put a heading above them describing the connection you just made. It might be a well different one to one I would make. But you’ve now grouped things in a way that is useful to you in this particular project.
In fact, the unique ways people group stuff makes following anyone else’s lengthy I7 code difficult, I find, but it makes it easy for me to follow my own code.
“Sections” really do help as far as compile errors when your source gets a bit huge. I set up mine like:
Section 1 - Game Setup (I throw my extension includes, mistake understandings, basic rule changes, scoring, etc all in here)
Section 2 - New Commands (I find it easier to throw all new understanding of actions here)
Section 3 - First Room(s)
Section 4 - First NPC
Secton 5 - Story part 1
Section 6 - Story part 2
Section 20 - Endings
Also, for more organization you can always comment things like:
And those will show up in green in the source, also making it easier to CTRL+F your code.
This of course though is just my style. I’m sure others would find it “weird” or whatever, but for me it works. Like SeveredHand said too though, you’ll probably find yourself plugging away for a while and then end up moving chunks of code around later on as the game fleshes out.