[z-machine] [I7] Inform 7, blorbs and the Z-machine

[Graham Nelson]

[Readers of rec.arts.int-fiction may have seen that three
blorbed story files have recently been published, the first to
be written with Inform 7. I've been working on some notes
which I hope might be useful to Z-machine people, to
accompany the public beta: here's my current draft.]



Inform 7 and Z-Machine Interpreters

This note accompanies the public beta release of Inform 7, a new
design system for interactive fiction based on natural language.

Inform 7 is built on Inform 6 as a foundation, and consequently it
compiles story files which comply with the Z-Machine Standards
Document (ZMSD). All the same, minor improvements to existing  
interpreters
might make them deal much better with Inform 7-written games. This
may be a minor nuisance to interpreter writers and maintainers, for
which I apologise, but I hope the effort will be thought worthwhile.
The changes described have been made to two interpreters thus far:
Windows Frotz and Zoom for OS X (and Unix).


1. The Z-machine stack

I7 is a rules-based system, and complex I7 code makes heavy use of
the Z-machine stack. At one stage, one of the "Test Suite" of games
used in unit testing of I7 crashed dumb-frotz, the dumb-terminal
interpreter we use for unit testing: it developed that the 4K of
stack allocated by dumb-frotz had overflowed. Optimisation of I7's
stack usage enabled us to bring the Test Suite back into working
condition even on dumb-frotz, but the problem is likely to recur
with more complicated I7 games in the future, and we would prefer
to avoid this if possible.

The ZMSD does not formally specify a size for the stack, only a
minimum likely to make Infocom story files playable. Moreover,
the ZMSD does not specify how the stack is to be stored: on most
interpreters it holds both explicitly stacked values and also
stack frames of routines, but Zoom keeps its stack frames
elsewhere, for instance. This unfortunately means that story
files crashing out on one interpreter may work fine on another.

We ask that interpreter-writers raise the stack size as far as
sensibly possible. On genuinely small machines, this could be a
waste of memory, but at any rate please ensure a stack of no
lower than 16K in size, and if memory is not a concern then
please allow 64K or more, just in case.


2. Wrapping story files in Blorb

The Blorb standard is now six years old. Inform 6 recognised it as
a good thing, and documented "blurb", the Blorb specification
language, back in the DM4 (2002). All the same, Blorb did not
really take off except for enthusiasts for graphical games, since
there was no pressing need for collating resources with text games
which had no resources to collate. Few blorb files now exist,
and those which do are not necessarily good examples. Although it
was originally hoped that interpreter-writers would recognise the
Blorb format, only a few interpreters now do so.

However, all of that may now change, because I7 releases story
files in Blorb format by default. (It does have an option to
release story file only, but this is off by default, and the
documentation deprecates it.) A typical I7-compiled object, then,
will be a Blorb file which contains:

     (i) the Z-machine story file, probably version 5 or 8;
     (ii) bibliographic metadata (see below);
     and (iii) cover image art.

Such a file will typically have a name ending in the ".zblorb"
file extension, to distinguish it from ".gblorb", a Blorb which
holds a glulx.

The minimum required to handle such a file is to find the story
file inside and ignore the rest, which requires very little coding,
but we hope that the ability to find an accurate title, author's
name, genre, release number, etc., will be welcomed by interpreters,
if only so that they can label playing windows "A Change of Pace"
rather than "chngpc.z5". (On OS X, for instance, Zoom uses this
bibliographic data to archive the story file and offer an
iTunes-like browser interface of stories.)

The current version of the Blorb specification is 2.0, which can
be found in draft form at:

     http://eblong.com/zarf/blorb/blorbtmp.html

Andrew Plotkin, the original creator of Blorb, has made a number
of minor improvements, but most notably has added two new optional
chunks:

The IFmd (IF metadata) chunk holds an XML file of metadata.

4 bytes         'IFmd'          chunk ID
4 bytes         n               chunk length
n bytes         ...             XML document (UTF-8 encoding)

The Fspc (Frontispiece) chunk declares that a given picture number
is the front cover art image.

4 bytes         'Fspc'          chunk ID
4 bytes         4               chunk length
4 bytes         number          number of a Pict resource

The actual image can be in JPEG or PNG format, and is stored
exactly as picture resources have always been specified in Blorb.
It is expected but not required to be square: designers of user
interfaces should plan on a square shape, but be prepared to
letterbox something rectangular to fit if need be.

Although Blorb 2.0 is still only a draft specification, the above
changes are fairly settled.


3. Metadata

Every Inform 7 project has a "library card" of bibliographic data
attached: the title, author, back cover text, genre, release number,
year of first writing and so forth. Moreover, every project created
is given a unique ID number, which can (it is hoped) be used to
distinguish all I7-published works, and which is presented to the
user as equivalent to an ISBN.

When a project is released as a Blorb file, this library card
is compiled into an XML file, and included in the IFmd chunk (above).

The format for this file is still under discussion, but it is
essentially the .iFiction format already used by the Zoom
interpreter. An example is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<ifindex version="0.9">
<!-- Metadata output generated by Inform 7 build 3E53 -->

<story>
   <id>
    <uuid>
     <uuid>AC736F19-3C4D-461E-9C84-49A759C72F42</uuid>
    </uuid>
    <format>zcode</format>
   </id>
   <id>
    <zcode>
     <serial>060121</serial>
     <release>1</release>
    </zcode>
   </id>
   <title>The Reliques of Tolti-Aph</title>
   <headline>A W&amp;W Scenario</headline>
   <author>Graham Nelson</author>
   <genre>Fantasy</genre>
   <description>It used to be said that...</description>
   <year>2005</year>
   <auxiliary>
     <leafname>Collegio.pdf</leafname>
     <description>Collegio magazine</description>
   </auxiliary>
   <auxiliary>
     <leafname>Guide</leafname>
     <description>Baltrazar's Guide</description>
   </auxiliary>
   <auxiliary>
     <leafname>Mating Wyverns.mp3</leafname>
     <description>The mating call of the green wyvern</description>
   </auxiliary>
   <coverpicture>1</coverpicture>
   <group>Inform</group>
</story>
</ifindex>

where the <description>, a back cover text, has been somewhat
abbreviated: it will usually be two or three paragraphs of text.
Some of this information duplicates what can be found in the
rest of the blorb. Most of the tags are self-explanatory.

<auxiliary> ... </auxiliary> is used to indicate that resources
not included in the blorb have been released with the game.
(Feelie PDFs, for instance.) The point of this is for archiving
programs or interpreters to be able to gather files together, or
notice that files are missing. By convention, the leafname must
end in a file extension (e.g. ".pdf") if the resource is a single
file: otherwise the resource is a folder containing HTML and
associated images, etc., in which case the top page is
guaranteed to be "index.html" in that folder. (The folder will
normally be a mini-website without external links.)


4. Unique ID number

In addition, all I7-generated Z-machine story files, whether embedded
in blorbs or not, are branded with the unique ID text: they each
contain a ZSCII string array in byte-accessible memory, in the form -

UUID://AC736F19-3C4D-461E-9C84-49A759C72F42//

the ID being the part between the pairs of double-slashes.

--
Graham Nelson