Using my proud newfound .dot skillz plus a lot of hand editing, have drawn a chart of Inform 7’s rulebook structure, including the rules and activities that Inform runs through in a given turn. (Procedural rules, which can happen any time, and some activities for managing output, which are ubiquitous, do not show up in the chart. So e.g. there is no chart entry for “printing the name of something”. But most things are in there.)
(PDF on clickthrough. It’s kind of big, I warn you.)
The plan is to refine this a bit and put it on the Inform documents page with future releases, if it is found to be helpful.
Emily Short's Interactive Storytelling 
This is wonderful! Thank you. This is exactly what I wanted to see: the “big picture”.
Yay!
Very nice. Just looking over this for the first time, I already see things that will help me streamline some code in my WIP. Thank you!
You freaking rock.
Preeetttyyyy. I really wanted this when I was first learning Inform 7.
Say, how did the dev team decide on when to use an Activity for something, and when to just use a single rulebook for something? I always wondered that, and this chart makes it obvious. (As making things obvious is what good charts do.) For example, everything in the parser except one is a activity. Visibility & touchability call down to an activity or a rulebook respectively, etc. Seems no rhyme or reason.
I’m attempting to write my own Programmer’s Intro to I7 and the reasons I give sometimes sound false even to my ears.
-R
PS: when’s the next build of I7 due?
As a general rule, tasks are more likely to become activities (which are really just sets of three rulebooks, a before, a for, and an after)
— if there is some reason to want hooks before and after the activity (as in, it’s really useful to be able to append things to names of objects with “before printing the name of something”).
— if it is likely that the author is going to want to completely supplant the behavior with his own “rule for doing whatever”. Many tasks that involve printing to the screen become activities rather than rulebooks for basically this reason.
They’re more likely to become simple rulebooks if
— there is no real application for any before/after section
— the rulebook exists to make a decision of some kind, and the author is most likely to want to add to the criteria in the rulebook rather than overriding its behavior.
If you look at the chart with that in mind, it may make a little more sense: most of the parser activities (especially “reading a command” and “deciding the scope”) make extensive use of the before/after hooks. Or they represent cases where the parser is printing a message of some kind; even the supplying a missing noun/second noun rule, which might seem to be just choosing something, often needs to print a message in the process. The does the player mean rulebook, on the other hand, is just making a decision, and there’s not going to be anything useful to do in a before or after rule for this decision-making process.
Likewise, yeah, visibility points to an activity and accessibility to a couple of rulebooks — but the reaching inside/outside rulebooks exist to make a decision, whereas the printing a refusal to act in the dark activity is printing something to the screen. (Functionally, the reaching inside/outside rulebooks are more like the visibility ruleboook — they’re choosing what can happen — than they are like the refusal to act in the dark activity, despite their relative distances down the tree.)
PS: when’s the next build of I7 due?
Um… not right away. There’s been a bunch of work done since the last release, but there remains a bunch more still to do, especially in fixing bugs reported since the last build.
Emily, this is beautiful!
Just a minor suggestion – instead of a .pdf, could you use a SVG (-Tsvg) when this is put on the I7 website? It’s more suitable for actual in-browser use.
Conceivably, though I don’t know a huge amount about SVG; one thing I like about the PDF version is that the text remains searchable. Would that be true of an SVG?
This looks impressive, even though I know almost nothing about Inform 7. But while skimming the chart, I noticed a few trivial typos:
The final sentence in each of the boxes “Amusing a victorious player activity”, “Reaching Outside Rules”, and “Reaching Inside Rules” ends with two periods instead of one.
In the “Deciding the scope activity” box, the phrase “after deciding the scope” begins with a single quotation mark (‘) but ends with a double quotation mark (“).
In the “Setting action variables for (specific action) rules” box, I would change “(e.g. looking, going, et al)” to “(e.g., looking, going, et al.)”. Actually, it should probably be “(e.g., looking, going)”, since I believe “e.g.” implies that the items following are only examples, not a complete list.
Thanks for the clear answer on that, Emily. I know exactly how to phrase that in tech terms.
I guess I’ll look for the next build again around April-ish.
-R
Thanks for the clear answer on that, Emily. I know exactly how to phrase that in tech terms.
Sure!
Though one other thing I realize I forgot to mention, about why printing-to-screen stuff especially tends to turn into an activity: activities provide context that can be referred to in the code elsewhere, while a bare rulebook does not. That’s especially useful when printing to the screen because it means that names of things printed can be given special-case output. So I can write “After printing the name of the foobar while asking which do you mean: …” (or whatever) in order to control output within the specific case that that activity covers, but there is no way to say “after printing the name of the foobar while running the does the player mean rulebook”.
OmegaM, thanks for the notes — I’ll be sure to tweak those when I next work on this. (Actually I’ve noticed a host of other inconsistencies — I really ought to be more regular about when to capitalize the names of things, and where to put line breaks; and the e.g./et al problem had already leapt out at me. And I don’t really like the font, and I need to figure out how to export from OmniGraffle with a bigger margin around the chart content… So it’s definitely in need of another proofread and more editing when I can come back to it with fresh eyes.)
Cool graph! Any chance that you could post the dot source (I use GraphViz a lot for my own projects, and I really like your formatting).
P.S. If you’re looking for a program that can handle really massive networks, Cytoscape is pretty good.
Most of the formatting was applied by hand, I’m afraid — I really only used .dot to get through the tedious work of making the rule lists up. What I did was copy and paste the list of rules from the rules index into a text file, then use a couple simple search-and-replace steps to transform into “foo” -> “bar” format as appropriate; then export the whole thing so that I had (in OmniGraffle) a page full of rule sequences. But everything after that — making the surrounding boxes to indicate rulebooks, drawing in the arrows connecting them, adding text explanations, etc. — was by hand. I know I could have done more of that in .dot in theory, but I still haven’t gotten OmniGraffle to import .dot files in a way that recognizes subgraphs.
Emily,
This is a great overview of how I7 works under the hood. I think it is worth including this on the I7 documents page.
Would it be worth putting up a link to this on RAIF to get a wider range of comments before it is finalised?
Oh yeah.. I now remember an episode where I wanted to ask “if the persuasion rules were running” but couldn’t. Banged my head on that one for about 5 minutes. I had to workaround with a stupid little truth state variable and a handful of rules to set & clear it.
Thanks again.
SVG is not searchable – what you get is (loosely) an image that can be zoomed in, or otherwise manipulated in the browser.
Mind you, as an svg file is basically text, google will index it for you, if that’s what you want (I assume not).
I have no problem with Google indexing, but I think it is also nice for someone looking at the chart to be able to search it for a specific rulebook.
That said, there is no real reason why we couldn’t offer both formats.
That’s very helpful indeed. Thank you for all the work. The I7 development community is a great example.