Blorb: An IF Resource Collection Format Standard

A PNG resource has a chunk type of '⁠PNG ⁠'.

PNG is a lossless image compression format. The PNG file format is available at

A JPEG resource has a chunk type of '⁠JPEG⁠'.

JPEG is a lossy image compression format, developed for photograph-like images. For information on JPEG, see

A third form of picture resource is a placeholder rectangle. A rectangle has only size, but no contents. This format exists to describe the legacy behavior of some V6 Infocom games (Zork Zero, Shogun, and Arthur). Its support in interpreters is optional, and its use is strongly discouraged for any purpose other than conversions of Infocom graphics.

Either or both of the width and height may be zero.

In a Z-code game, a rectangle exists for the purposes of @picture_data and @erase_picture, but its use in @draw_picture or @picture_table is an error. The behavior of rectangles in Glulx and other game files is not defined.

An AIFF (Audio IFF) file has chunk type '⁠FORM⁠', and formtype '⁠AIFF⁠'. AIFF is an uncompressed digital-sample format developed in the late 1980s. The AIFF format is available at these locations:

An Ogg Vorbis file has chunk type '⁠OGGV⁠'. This is a high-quality (but lossy) audio compression format, comparable to MP3 (but without the patent concerns that encumber MP3). The Ogg format is available at:

MOD is an Amiga-originated format for music synthesized from note samples. Over the years, other formats of this type — generally called “tracker” or “module music” formats — have arisen. Blorb supports four: original “.MOD” files, ImpulseTracker (“.IT”), FastTracker 2 Extended (“.XM”), and ScreamTracker 3 (“.S3M”).

Because tracker-playing libraries typically handle many formats, it is most practical for Blorb to lump them all together. Regardless of which tracker format is used, the chunk type will be '⁠MOD ⁠'.

The formats are described here:

This spec does not attempt to distinguish variations within the four supported formats. (“.MOD” is particularly ill-defined, although I have saved comments on the original MOD format at https://eblong.com/zarf/blorb/mod-spec.txt.) Instead, we recommend that C implementations embed libmodplug, a public-domain tracker-playing library. Its home page is:

However, some bug fixes are included in the version packaged with Windows Glk:

Where libmodplug is not practical, implementations should use whatever tracker-playing library claims to support the four formats in question. We trust, perhaps beyond reason, that implementation differences will not lead game creators to their doom.

A song file has chunk type '⁠SONG⁠'. This is similar to a MOD file, but with no built-in sample data. The samples are instead taken from AIFF sounds in the resource file. For each sample, the 22-byte sample-name field in the song should contain the string “SND1” to refer to sound resource 1, “SND953” to refer to sound resource 953, and so on. Any sound so referred to must be an AIFF, not a MOD or song. (You can experiment with fractal recursive music on your own time.)

Each sample record in a MOD or song contains six fields: sample name, sample length, finetune value, volume, repeat start, repeat length. In a MOD file, the sample name is ignored by Blorb (it is traditionally used to store a banner or comments from the author.) In a song file, the sample name contains a resource reference as described above; but the sample length, repeat start, and repeat length fields are ignored. These values are inferred from the AIFF resource. (The repeat start and repeat length are taken from the sustainLoop of the AIFF’s instrument chunk. If there is no instrument chunk, or if sustainLoop.playMode is NoLooping, there is no repeat; the repeat start and length values are then considered zero.)

The intent of allowing song files is both to allow higher quality, and to save space. Note samples are the largest part of a MOD file, and if the samples are stored in resources, they can be shared between songs. (Typically note samples will be given high resource numbers, so that they do not conflict with sounds used directly by the game. However, it is legal for the game to use a note sample as a sampled-sound effect, if it wants.)

As of this spec, no IF system puts more than one '⁠Exec⁠' chunk in a Blorb file, or has any need to. However, this could change in the future.

One possible use (noted as a comment in earlier versions of this spec) is to support several loadable libraries or game segments. In such a case, chunk zero should contain the code to execute first, or at the top level.

Another possibility is to distribute several versions of a game in one Blorb package. IF platforms are famed for the fragility of their save files; a player who downloads an updated game file is likely to find that it no longer loads her old saved games. This could be avoided if the updated Blorb actually contained multiple game files, one per '⁠Exec⁠' chunk. Chunk zero would be the preferred (most recent) game version, but when loading a save file, the interpreter would select whichever game version was compatible with it.

This chunk is used to tell the interpreter the release number of the resource file. It is meaningful only in Z-code resource files.

The interpreter passes this information to the game when the @picture_data opcode is executed with an argument of 0. The release number is a 16-bit value. The chunk format is:

This chunk is optional. If it is not present, the interpreter should assume a release number of 0.

This chunk contains information used to scale images. The chunk type is '⁠Reso⁠'. It is optional. This chunk is meaningful only in Z-code resource files.

A scalable image is one which the author says should be larger when more space is available, and smaller when less space is available.

It is also possible to create images that have a fixed scaling ratio; they are always scaled up or down by a particular amount, regardless of window size.

Not all images have to be scalable. Unless the resolution chunk gives scaling data for an image, that image is assumed to be non-scalable. Non-scalable images are always displayed at their actual size. (One image pixel per screen pixel.)

This chunk is optional; if it is not present, then all of the images in this file are non-scalable.

The “standard window size” is the normal size, the author’s original chosen size, for the Z-machine window. It is not the only possible size; a good V6 game should be prepared for any window the interpreter chooses to create. The idea is that when the Z-machine window is exactly the standard size, scalable images are presented at their original size. When the Z-machine window is larger than the standard size, scalable images are scaled up; when it is smaller, scalable images are scaled down.

The minimum and maximum window sizes are provided as a hint to the interpreter, when it is choosing a window size. It may also use the standard window size as a hint for this purpose. (If the interpreter lacks the ability to choose its own window size, of course, it will ignore these hints.) The idea is that the minimum and maximum sizes define the range in which the game can draw itself successfully.

Any or all of minx, miny, maxx, maxy can indicate “no limit in this direction” by containing a value of zero. However, px and py must contain non-zero values. Unless the min or max values are zero, it must be true that minx ≤ px ≤ maxx, miny ≤ py ≤ maxy.

Also note that I have not mentioned Z-pixels. This standard does not concern itself with Z-pixels.

On with the show.

The standard, minimum, and maximum window sizes are followed by a set of image entries, one for each scalable image. (Non-scalable images do not have an entry in this table; that’s how they are declared to be non-scalable.) Each image entry is 28 bytes, of the form:

The number is the picture number; in other words, this entry applies to the resource whose usage is '⁠Pict⁠' and whose number matches this value.

The entry then contains a standard, minimum, and maximum image scaling ratio. Each ratio is a real number, represented by two integers:

Minratio can indicate zero (“no minimum limit”) by having both minnum and minden equal to zero. Similarly, maxratio can indicate infinity (“no maximum limit”) by having maxnum and maxden equal to zero. It is illegal to have only half of a fraction be zero.

To compute the actual scaling ratio for this image, the interpreter must first compute the overall game scaling ratio, or Elbow Room Factor (ERF). If the actual game window size is (wx,wy), and the standard window size is (px,py), then

The scaling ratio R for this image is then determined:

If minratio and maxratio are the same value, then R will always be this value; ERF and stdratio are ignored in this case. (This indicates a scalable image with a fixed scaling ratio.)

The interpreter then knows that this image should be drawn at a scale of R screen pixels per image pixel, both vertically and horizontally. The interpreter should report this scaled size to the game if queried with @picture_data (as opposed to the original image size).

Yes, this is an ornate system. The author is free to ignore it by not including a resolution chunk. If the author wants scaled images, or variably-scalable images, this system should suffice.

Here are some examples. They’re not necessarily examples of good art design, but they do demonstrate how a given set of desires translate into images and resolution values. All are for a game with a standard size of (600,400).

End of verbose examples.

This chunk contains a list of pictures that change their colors according to the pictures plotted before. The chunk type is '⁠APal⁠'. It is optional. This chunk is meaningful only in Z-code resource files.

This format exists to describe the legacy behavior of some V6 Infocom games (Zork Zero and Arthur). Its support in interpreters is optional, and its use is strongly discouraged for any purpose other than conversions of Infocom graphics.

Each entry is 4 bytes, of the form:

If this chunk is present:

However, the following rules still apply from the PNG standard:

These restrictions, though intricate, serve to make the interpreter’s life easier at the expense of constraining the creator. The constraints are natural given the form of the original Infocom graphics.

The interpreter should keep track of the “Current Palette”. This will be a 14-entry table, covering color indices 2-16. For ease of implementation, this will probably be a 16-entry table, whose first two entries are not significant.

Whenever a picture not listed in the APal chunk is plotted, its palette (as derived from its PLTE, gAMA, cHRM and sRGB/iCCP chunks) should be copied into the Current Palette. If its palette has fewer than 16 entries, then only those entries of the Current Palette are changed.

Whenever a picture listed in the APal chunk is plotted, its palette should be ignored, and it should be plotted with the Current Palette.

The behavior is undefined if any adaptive-palette pictures are plotted before a non-adaptive picture has been plotted.

Alternatively, for the full retro-gaming experience, the pictures can be handled in the same way as the Amiga and IBM MCGA interpreters, as follows: Use a 16-color screen mode. Copy non-adaptive pictures’ palette (apart from the first two entries) into the screen palette when plotted. Use color indices 0 and 1 for the window background and text respectively. This mimics the IBM MGA and Amiga display, where drawing a picture can change the colors of graphics already on the screen, but it is not the preferred rendering.

Shogun and Journey do not use any adaptive-palette images, but on some platforms the effect of pictures already on the screen changing color is visible. To give an interpreter the ability to do this if desired, and to signal that optimizations may be possible because of the limited nature of the graphics, the Blorb files for Shogun and Journey contain an empty APal chunk.

This chunk contains information about which sounds are looped, in a V3 Z-machine game. The chunk type is '⁠Loop⁠'. It is optional.

The format is:

Each entry is 8 bytes, of the form:

The repeats flag is one if the sound is to be played once; it is zero if the sound is to repeat indefinitely (until it is stopped or another sound started.) If there is no entry for a particular sound resource, or if the looping chunk is absent, the V3 interpreter should assume the flag is one, and play the sound exactly once.

Previous versions of the Blorb spec did not discuss file naming. However, with the relapse of MacOS into filename suffix semantics, it is impossible for us to pretend that the issue is an implementation detail.

It is always legal for a Blorb file to have a “.blorb” filename suffix. However, interpreters have a natural interest in locating their sort of Blorb files — Z-code, Glulx, or so on — and it is generally easier for them to do this by filename suffix, rather than by opening each Blorb and looking at its resource index. Therefore, “.zblorb” and “.gblorb” should be used to designate Blorb files containing Z-code and Glulx games, respectively.

On platforms which limit filename suffixes to three characters, the suffixes “.blb”, “.zlb”, and “.glb” may be used instead. But this practice, at least, I can deprecate without qualm. I hope.

Historically, Blorb files have been associated with the MIME type application/x-blorb.

We can use the profile feature of MIME to differentiate the contents: application/x-blorb;profile="zcode" and application/x-blorb;profile="glulx" for the common virtual machines.

The image system presented in this document is fully backwards-compatible with Infocom’s interpreters. Infocom V6 games, such as Arthur, Journey, and Zork Zero, contain only non-scalable image resources. The game files are written to deal with both variations in window size and variations in image size (since the interpreters for different platforms had different window sizes and different art.) Therefore, if you construct a Blorb file containing the images from a particular platform (say, the Mac) and give it the suggested window size of the Infocom Mac interpreter, the game file will deal with it correctly.

The image system is also sort of forwards-compatible, in the following sense. If you take a Blorb file whose standard (intended) window size is the same as the Infocom interpreter’s, and break it out into Infocom image files, the Infocom interpreter should display it correctly. The interpreter will not scale images, but since the window size is equal to the standard size, the Blorb rules require the images to be displayed unscaled anyway.

Also, of course, if you take a Blorb file which contains only non-scalable images, an Infocom interpreter will act correctly, since it will not scale the images regardless of the standard size.

The sound system is slightly more problematic. A game file can announce that it uses sound, by setting a header bit; the interpreter can announce that it does not support sound, by clearing that bit. But there is no way to distinguish a game that uses sampled sound only, from one that uses sampled sound and music. (And similarly for the interpreter’s support of samples versus music.) This may be addressed in a future revision of the Z-machine. In the meantime, games should set that header bit if any kind of sound is used (samples or music or both.) And interpreters should clear that bit only if no sound support is available. If the interpreter supports sampled sound but not music, it should leave the header bit set, announcing that it does “support sound.” It should then ignore any request to play a music resource.

There is also the question of overlapping sounds. The Z-Spec (9.4.2) says that starting a new sound effect automatically stops any current one. But it is not desirable that a sound effect such as footsteps should interrupt the playing of background music. Therefore, the interpreter should amend this rule, and consider sampled sounds and music to be in seperate “channels”. Samples interrupt samples, and music interrupts music, but one form of sound does not interrupt the other.

This is an actual variance in the behavior of the Z-machine, and worse, a variance which depends on data format. (One sound will either stop another, or not, depending on whether the sound is stored in AIFF (sampled) or Ogg/MOD (music) format.) We apologize for the ugliness.

Again, future versions of the Z-machine may address this issue, and allow a more general system where any sound can be overlaid on any other sound, or interrupt it, as the game desires and regardless of storage format. (After all, there can be background sounds as well as background music.) Such a system would also allow the interpreter to announce its limitations and capabilities — whether it can play music, whether it can play two pieces of music at once, how many sampled sounds it can play at once, etc.

A final, ah, note: The remark at the end of Z-Spec chapter 9, about sequencing sound effects to simulate the slow Amiga version of “The Lurking Horror”, should not be applied to music sounds. New music should interrupt old music immediately, regardless of whether keyboard input has occurred since the old music started.

The Glk I/O library was designed with portable resources in mind, so there should be no incompatibility.

Remember that the resolution and scaling data is not used by Glk. That chunk is ignored by Blorb-capable Glk libraries.

ADRIFT supports more media formats than Blorb, but has adopted Blorb as a packaging format. To permit this, the following chunk types may be used in ADRIFT blorbs:

For images: '⁠GIF ⁠'.

For sounds: '⁠WAV ⁠', '⁠MIDI⁠', '⁠MP3 ⁠'.

ADRIFT Blorb files should use MIME type application/x-blorb;profile="adrift". The filename suffix should be “.blorb” or “.adriftblorb”.