InfLight -- an overview of Inform debugging

Roger Firth's IF pages
InfLight -- Inform debugging
InfLight -- Inform debugging

Before we get too heavily involved in the technical detail, we'll summarise the steps you go through to build and play a game. There are three major stages:

creating a (human-readable) text file which contains the game's source,
compiling that source file into (binary) Z-code held in a second file,
executing the Z-code within a Z-machine interpreter in order to play the game.

Text editor

You need a text editing program (rather than a word processor) to create and modify your game file. Any editor which doesn't mess around with the source will do; on Windows you can use the standard NotePad, though you'll find it much more efficient to get hold of a proper programmers' editor like TextPad. On a Macintosh, BBEdit Lite is a good bet. Most people find that syntax colouring -- where the editor displays Inform keywords in one colour, strings in a second colour, comments in a third... -- is helpful in minimising syntax errors. Here is a comprehensive list of editors.

There's an ongoing debate about Inform IDEs (Integrated Development Environments) which -- theoretically -- ease the problems of building and debugging games by combining editor, compiler and interpreter into a single intelligent toolset. There are currently a few IDEs under construction (see for example Inform Explorer and IF-IDE), but they have yet to prove themselves in the heat of battle.

Inform compiler and Library files

The compiler transforms Inform source games into Z-code, or (more often) explains that it is unable to do so because of the errors in your program. It may also issue warnings: for example when you've created a variable but not used it, or when part of your program can never be executed. Although warnings don't prevent the Z-code being generated, they suggest something isn't quite as you intended; it's good policy to resolve the situation rather than let the warning recur. And it can reports loads of statistical and other data about your game.

The compiler is maintained by Graham Nelson. It's written in C, and Graham has taken great pains to make it portable. Portability means that the compiler can be made to run -- virtually unchanged -- on PCs, Apple Macs, UNIX boxes and a wide variety of other computing devices, and therefore that a given game will compile into identical Z-code on all of those platforms. The fact that a game's Z-code is always the same, irrespective of the computer on which it originated, is one of Inform's strengths.

Not that you have to worry much about the compiler. A host of public-spirited souls have already got it working on almost every conceivable platform, so all you need do is download the appropriate ready-to-run version. See Graham's Inform Downloads page or Jonadab's list. (You can also find the compiler's C source program via Graham's page, but you're most unlikely to need it in that form.)

You also need to download the Library: PARSER.H, VERBLIB.H, GRAMMAR.H and a few other Inform source files which provide a basic framework for your game. Thanks to the Library, you get a bare-bones environment in which your players can receive commands, move around, and interact with things. The Inform program that you write then builds on this foundation, fleshing it out with your own rooms, objects and people.

Z-code interpreter

The Z-machine is an imaginary computer which exists not as physical hardware, but rather as a software interpreter able to read and execute Z-code instructions; it's an example of what are often known as Virtual Machines. As with the Inform compiler, there are versions of the Z-machine interpreter readily available for PCs, Macs and most other things besides. Unlike the compiler, the various interpreters aren't all based on a single program of Graham's (though they do all conform to a well-defined standard in whose authorship he played a major part). Standardization means that any piece of Z-code, irrespective of where or how it was compiled, will run on any Z-machine. (And, as a nice bonus, those same Z-machines will also run any of the old Infocom games: This Is Not A Coincidence.)

The Z-code interpreter is primarily intended for playing Inform text adventure games (though as a general computing engine it can occasionally be seen employed for some alternative purpose, commonly referred to as an 'abuse of the Z-machine'). So, it reads a Z-code file created by the compiler, and then displays the game's descriptions and command prompts in a scrolling text window. The only time that the interpreter normally writes to an output file is when creating a transcript -- a copy of your commands and the game's responses.

Controlling the compiler

The operation of the compiler can be controlled in certain respects, using mechanisms which are rather sparsely explained in the Designer's Manual. More detail is available from the compiler's help, but people often forget to look there. Here's what the Windows compiler says; compilers on other platforms may have differing rules for the handling of file names.

Game sizes

The compiler is able to generate several flavours of Z-code, broadly similar but matching different versions of Infocom's Z-machine as it evolved over time in the 1980s. Only two of these are used nowadays -- Version 5 (the default) and Version 8 -- and these are identical other than in the maximum supported game size. In a Version 5 game, the Z-code is limited to 256K bytes (large enough for most games), while the Version 8 limit is 512K bytes. This trick is accomplished by using packed addressing -- see the later Numbers segment for more detail.

You use the compiler's v8 switch to generate Version 8 Z-code rather than the default Version 5 Z-code. Don't confuse this with the compiler's $small, $large and $huge commands; these control how much memory is needed to compile the game, and are largely unrelated to the size of the game itself once compiled. (A game with lots of little objects may consume more compiler memory than a game with a few large objects, even though the two games generate a similar amount of Z-code.)

Glulx

The reason that Z-code sets an absolute limit of 512K bytes on a compiled game is that the Z-machine uses a 16-bit architecture. A word of 16 bits can address 64K memory locations; packed addressing stretches this to 256K or 512K locations, but that's as good as it gets. The inability to create larger games, together with some more subtle memory limitations plus the lack of sensible graphical and audio capabilities, have contributed towards the development of a 32-bit Virtual Machine, called Glulx (don't ask). You can read about Glulx, and also download copies of the new compiler, Library and Glulxe interpreter, from Andrew Plotkin's comprehensive pages. The nice thing is: the new compiler reads your existing Inform source files and generates either Z-code or Glulx code. Hardly any changes to the games are needed -- see Zarf's Inform guide for details. There's lots more good stuff at Adam Cadre's Gull introduction (whose first few pages provide some excellent background to Glulx and Inform), and at Marnie Parker's Glulx for Dunces.

Footnote: A short evolutionary history

I think it happened roughly like this:

In 1975, Will Crowther and Don Woods wrote the first text adventure in FORTRAN; it ran on mainframes and mini-computers.
At the MIT AI-Lab, Mark Blank, Tim Anderson et al played Adventure; they were sure that if an adventure game could be written in FORTRAN, a better one could be done in MDL (a Lisp-like language). The result, around 1978, was Dungeon, (from which Bob Supnik at DEC created a FORTRAN version); the MDL original, however, was soon renamed Zork.
Since Zork was an obvious success, its authors formed Infocom to address the home computer market. MDL being unavailable there, they devised the similar but simpler ZORK Implementation Language (ZIL) in which to create their games, and the (virtual) Z-machine on which to run them. Zork was divided into the Zork I, II and III we know today.
Eventually, Infocom went out of business. Activision is believed to possess the ZIL source for Zork, Enchanter and all the other 30-some Infocom games, but has never made it available. In any case, the ZIL compiler and details of Infocom's Z-machine have been lost.
By reverse-engineering the Z-code of the published Infocom games, a group of dedicated hobbyists known as the Infocom Task Force (ITF) reconstructed the specification of the original Z-machine. This made it possible to write additional Z-machines (for example in Java and Perl), and therefore to play the old Infocom games on many more platforms.
There was, however, no way to write new Z-code until Graham Nelson devised the Inform compiler. Inform programs probably bear little or no relationship to ZIL; that doesn't matter. What's significant is that Inform games compile into Z-code, and therefore run on all of those Z-machines.
And now, Andrew Plotkin's Glulxe is a new VM, bringing many benefits to today's game writers, but incompatible with the Z-machine. Its Glulx compiler reads Inform programs, and produces code for either the Z-machine or for Glulxe. At this point, therefore, the 20-year-old link back to Infocom's ZORK is finally broken.

Enough of all this talk; let's make something happen.