I dove right into inform7, thinking I’d create a small game, just to try this out. Well, I really enjoyed it, so I kept doing more, adding on, enhancing… and now I have a decent sized game. 92 rooms, 200 things, lots of stuff…
Unfortunately, I didn’t know about Sections, Volumes, Parts, Chapters, etc… relative to organizing the code. I just used comments like:
[— setup—]
[---- Oxford ----]
[— treasures—]
etc…
to do the organization. I’m embarking on organizing and cleaning up the code. I assume if one uses the official “sections” commands etc, you can somehow create these easily readable html websites like Emily Short’s Bronze site where you can pursue the code in a browser?
Any suggestions on (1) organizing (2) web enabling (3) references…
If you Release along with an interpreter and source text. (see documentation “Writing With Inform” §25. Releasing) you will get an index.html page that will contain a Source Text link.
Clicking the Source Text link will display a clickable outline of your source code based on your use of Volumes, Books, Parts, Chapters, and Sections headings.
Definitely use the built-in headings. In the IDE, they give you syntax highlighting and a clickable table of contents, as well as being able to release as neat source code as shown above.
The way I see it, there are two main ways to organize code:
Chronologically: the code goes in order of when the player would (ideally) find it. So you might have something like:
volume - OUT OF WORLD
test me with "turn on sink / z / z / z".
volume - GAME
part - KITCHEN
the Kitchen is a room.
water level is a kind of value.
the water levels are no water, half-full, lots of water, and overflowing.
the sink has a water level.
the water level of the sink is no water.
the sink is in the Kitchen.
the sink is a device.
the description of the sink is "A sink [if switched on]with a running faucet[else]waiting to be used[end if].".
every turn:
if the sink is switched on:
if the water level of the sink is not overflowing:
now the water level of the sink is the water level after the water level of the sink;
else:
say "You rush over to the sink.";
try switching off the sink.
By mechanic: each section is a category (scenes, rules, things, etc.)
volume - OUT OF WORLD
test me with "turn on sink / z / z / z".
volume - WORLD
part - ROOMS
the Kitchen is a room.
volume - OBJECTS
the sink is in the Kitchen.
the sink is a device.
the description of the sink is "A sink [if switched on]with a running faucet[else]waiting to be used[end if].".
water level is a kind of value.
the water levels are no water, half-full, lots of water, and overflowing.
the sink has a water level.
the water level of the sink is no water.
volume - RULES
every turn:
if the sink is switched on:
if the water level of the sink is not overflowing:
now the water level of the sink is the water level after the water level of the sink;
else:
say "You rush over to the sink.";
try switching off the sink.
I personally use a mixture of the two, going mostly chronologically but with some sections separated by mechanic.
Oh yes… It already made it SO much better, just by changing all the comment dividers into volumes, books, chapters, sections, etc… The Index is GREAT.
I think I’ll follow your advice and do a mixture of chronologically and mechanic… I put most of my people together rather than Chronologically, so not sure how that counts maybe a third degree of mixture. (
I don’t use the headings much. Source code doesn’t have the same innate structure as a book; why would I try to force it into that structure? Besides a search function will get you where you need to be faster in most cases.
I organize my code by putting different concerns in different extensions. I also use VS Code rather than the IDE, but that’s not required. I don’t find the section navigation in the IDE useful because it’s too slow and clumsy.
The fancy source code site is baffling to me — what’s the point? Code is to be run, not artistically appreciated, right?
I usually have this idea that I’d like to do general things up front. Variables, decisions, new actions, general clockwork. After that, I do the playable content: rooms and things.
If I have big amounts of data, I keep them at the end.
This is a high-level outline of a pretty big game. I don’t really use the clickable links within the IDE much. It’s the bolded headers that I look at while reading/searching
I also put huge comment spacers in things, and use searchable tags if I need to.
Though I feel things get out of hand after a while. In a big enough project, it can feel like the organization needs organization. I think my only game is like that. For my next big project I’ll keep some things in separate extensions so that I can have more windowpanes to look at without scrolling around.
A lot of what Phil says, basically, though I think it’s fine to like the HTML.
Code is also to be read and studied to see how other people did things to add to your own projects. Like how did Emily Short implement GO TO [any room]in Bronze?
There have been no announcements, though there is some beta stuff that can be compiled. That’s all beyond reach for me, as I use the IDE and don’t compile… er… compilers.
When I started collecting Cragne Manor source code, I certainly wanted it to be artistically appreciated. It’s a cross-section of well-known IF authors and their coding styles. Practically a museum exhibit.
Also, why not present the code to onlookers using (roughly) the same stylesheet as the Inform IDE?
I think that Steve Jobs used to stress the elegance of things like wiring and circuits on circuit boards. In his mind, the entire piece should have a quality of construction and an elegance that was there if you looked for it.
In my mind, code is both to be run and can be artistically appreciated.
Inform’s philosophy is that any given line of code will probably be read more times than it’s written. So it’s important to think about readability! Your future self will thank you later.
And no software engineer would disagree with you there — but when we think about readability we’re thinking about collaboration, change, and maintenance, not about aesthetics. I’m not sure I find code beautiful. But that’s me. Everyone can value what they value.
Yeah, Inform is a bit of an oddball in that department. But the idea is that we’ve got a lot of practice skimming English text, getting the gist of it, and finding the bit we want. So Inform’s designed to tap into that ability—hence the English-like syntax—but that also means presenting it with serif fonts, italics, and so on for better readability.
I realize that this approach may not suit everyone (your code, your rules), but on my end, I heavily rely on headers. I divide my work into three parts:
Worldbuilding: In this first volume, I code the laws of my universe (light, passage of time, monetary system…), the declarations for property values, and the categories for rooms, persons, devices, backdrops…, as well as the management of scope, prompt, and status bar, all action processing rules, object libraries (unique or duplicated), etc.;
Worldsetting: In this second volume, I implement the elements that inherit from the first part and bring the world to life: regions, rooms, inhabitants, interest groups (using relations), mainly recurring events;
Story: In the third and final volume, I incorporate the narrative elements; primarily conditional events, everything related to the QBN, and the rules that allow the story to progress from one phase to another.
I code from the first part to the last. Naturally, I need a very precise hierarchy with this approach because, when I decide, for instance, to create a room in the second volume, I need to know all the configuration characteristics that must be filled in (which differ if it’s a library, a mountain pass, or a vegetable garden).
What makes me realize that this method works well for me and that heavy use of headers is useful is that, as the project progresses, the code becomes easier and faster to deploy, and it aligns more with the purely narrative aspects of the story. I also think that the first volume could event be reused for other stories in the same universe and might even have a version number.
Perhaps the use of private extensions could be another way to follow this path, but it’s a subject where my skills are still exceedingly limited (among others).