I'm updating the I7 Programmer's Manual. Any requests?

I’m going to update the I7 Programmer’s Manual for the new build, 6F92. Anyone have any comments, suggestions, requests, clarifications, or other input for what they’d like to see in the next edition? Or not see? Obviously the new type system’s gymnastics will be added.

Semi-relatedly, I’m going to take another crack at the scene-based tutorial, and have a request. Who’s using the recent build’s ability to create relations to text? What’s it being used for? I ask, because I scribbled this last night:

Seems like it might be relevant or useful or something.

If it’s somehow feasible to use the floating point arithmetic that might be good to add!

The floating-point stuff has no support in this I7 release. I know Graham is interested in adding it, but this was a “no new language features” release, obviously.

i think the part about Kind Variables (21.7) is not clear enough. I think it should explicitly state that
“* of kind K” symbolizes the parameter on which other parameters depend (eg, list of Ks).

Questions of this sort


are asked so often, it would be nice if at least one of the manuals covered them. The Programmer’s Manual seems like a natural fit.


ah, as a matter of fact I think that is already done. Here’s a pre-release of the new section.

Yeah, performance. I agree it’s a good fit, but it’s such a slippery topic. Partly because it’s running on a VM, and even opcodes using bad algorithms like @linearsearch will beat the pants off the best binary search coded in I7/I6. Loops can hide easily, and I’ve more than once made a recursive Definition: that never ended.

Plus, I’m leery of using objects too much (as in, nodes for tree structures and the like). They don’t seem to scale well, whereas a table implementation seems much more robust. Granted, I know objects are more heavy-weight than a row, and used a linked-list rather than array arrangement in memory, but sometimes the parser iterates over them when it shouldn’t. (By way of [any…] tokens??) That’s more a feeling than something I’ve nailed down, though.

Then I got burned when I suggested how slow Instead rules were. Well, seems that was taken care of a few builds ago. I didn’t bother to check it again. That’s twice that Instead rules have been sped up. And when procedural rules bite the dust, that’s gonna change things too.

So with performance, I’m not sure what’s going to hold true long enough to be worth putting into print.

(I will say that if you’re trying to write Photoshop in Inform 7, well, I throw up my hands.)

Maybe this should be a community effort, then, when the system is stabilized. (Ideally, at that stage, Writing with Inform would itself offer some pointers.)

Actually, I’ve released a pretty zippy (at least on the graphically fast interpreters) graphics editor for I7.* Ironically, the things that really impair performance are text-related (indexed text, etc.)

  • It’s not Photoshop, more like Illustrator, but hey.


It might be better to rather teach people how to find the bottlenecks after they’ve noticed their game is starting to slow down. My philosophy follows the old programmer wisdom, “premature optimization is the root of all evil”: you shouldn’t optimize before you actually need to. Most often trying to avoid bottlenecks beforehand leads to much more work than solving them when and if they manifest. For example if a manual says that instead rules can potentially slow your game down, some people will start avoiding them at all costs. It leads to bad design and hours of wasted work trying to optimize where there is no need to do so. (This is a real life example.)

I know all about Glimmr; I’m poking fun. And at Alabaster too. I don’t suppose you’ve noticed the Programmer Manual makes no mention of graphics, sound, external files? I still have no real desire to explain that, partly cause I’ve never, ever touched it. At all.

I’m seriously considering adding a section on I6 hacking. And what section headings are good for. Since there’s less of a need for I6 hacking, it’s now a small enough task to be manageable. I’ll still point to the DM4 though.

Seems like there was one other area that I’m forgetting.

Juhana: agreed, but how? I don’t think we have a profiler, and I’ve always just taken educated guesses where the hit lies. Well, RULES ALL can allow one to arrange things so so many rules don’t appear, but that’s still thinking forward through stuff, rather than having a tool point out things we couldn’t have known about.

I figured! …but I still think it’s interesting (though probably not surprising) that text operations can be slower than graphics. A lot of the disparity has to do with interpreters and the optimizations they can make, particularly when they can fairly transparently take advantage of existing graphics libraries. Gargoyle actually writes “text” drawn to a graphics window pixel for pixel nearly as quickly as it writes text to the screen in a buffer. (And that’s in spite my code, which in addition to likely being amateurish, is optimized for user-friendliness rather than speed.)

This is a good idea. The manual (in the extensions chapter) actually does a pretty good job of covering the ways that you can write I6 inclusions into your code. Things that it would be nice to see better coverage of: what can be done with I7 code inclusions within I6 code blocks, some basic discussion of how most structures (rules, directions, etc.) map to the I6 level. The latter seems like it’s especially appropriate to the Programmer’s Manual.

I don’t have an answer to that - my preferred method is commenting stuff out until it works, but I wouldn’t necessarily recommend that to everybody.

If game speed is subjective enough that there aren’t any generally-established things that should be avoided, then you could just add a note saying so. I just don’t want to fall into any obvious pitfalls.

Minor update: still haven’t touched performance – I’ll hit it last – but the first paragraph in the new section on I6 gives a brief overview of how constructs map down. One of the examples is an Understand token, which WI only mentions in passing.