§43   Pictures, sounds, blurbs and Blorb

The blorb spell (safely protect a small object as though in a strong box).
— Marc Blank and P. David Lebling, ‘Enchanter’

Pictures may, but need not, accompany a Version 6 game. They are not stored in the story file itself, and different interpreters make different arrangements for getting access to them. Some interpreters can only read low-resolution, low-colour-range images in the awkward format used by Infocom's graphical games. Others take pictures from a “Blorb file” which can hold high-resolution and riotously colourful images in a format called PNG. The story file neither knows nor cares which, and refers to pictures only by their numbers.

A Blorb file can also safely protect sound effects and even the story file itself, so that a game and its multi-media resources can be a single file. Blorb is a simple format largely devised by Andrew Plotkin (partly based on the same author's earlier “Pickle”); it has been fully implemented in Kevin Bracey's ‘Zip2000’ interpreter for Acorn RISC OS machines, and is also used by the new “glulx” format of story files.

A Perl script called perlBlorb, runnable on many models of computer, gathers together sounds and images and constructs Blorb files as needed, from a list of instructions called a “blurb file”. For instance:

! Example of a blurb file
copyright "Angela M. Horns 1998"
release 17
palette 16 bit
resolution 600x400
storyfile "games/sherbet.z5"
sound    creak  "sounds/creaking.snd"
sound    wind   "sounds/wind.snd"
picture  flag     "flag_1.jpg"      scale 3/1
picture  pattern  "backdrop_1.jpg"

When run through perlBlorb, the above produces the text below:

! perlBlorb 1.0 [executing on 980124 at 15:31.33]
Constant SOUND_creak = 3;
Constant SOUND_wind = 4;
Constant PICTURE_flag = 1;
Constant PICTURE_pattern = 2;
! Completed: size 45684 bytes (2 pictures, 2 sounds)

This output text looks like Inform source code, and this is not an accident: the idea is that it can be used as an Include file to give sensible names to the sound and picture numbers, so that the rest of the code can include statements like this one:

@sound_effect SOUND_creak 2 128 255;

(“start playing this effect at about half maximum volume, repeating it indefinitely”). An attractive alternative is to use a convenient class library, such as "V6Lib.h" by Jason Penney, to avoid messing about with assembly language.

You're free to specify the numbering yourself, and you need not give names for the pictures and sounds. A blurb command like:

picture "backdrop.png"

gives this image the next picture number: i.e., the previous picture number plus 1, or just 1 if it's the first specified picture. On the other hand, a blurb command like:

picture 100 "backdrop.png"

gives it picture number 100. The only restriction is that pictures must be given in increasing numerical order. The numbering of sounds is similar.

· · · · ·

The full specification for the “blurb” language is as follows. With one exception (see palette below) each command occupies one and only one line of text. Lines are permitted to be empty or to contain only white space. Lines whose first non-white-space character is an exclamation mark are treated as comments, that is, ignored. (“White space” means spaces and tab characters.)

string› means any text within double-quotes, not containing either double-quote or new-line characters

number› means a decimal number in the range 0 to 32767

id› means either nothing at all, or a ‹number›, or a sequence of up to 20 letters, digits or underscore characters _

dim› indicates screen dimensions, and must take the form ‹numberxnumber

ratio› is a fraction in the form ‹number/number›. 0/0 is legal but otherwise both numbers must be positive

colour› is a colour expressed as six hexadecimal digits, as in some HTML tags: for instance F5DEB3 is the colour of wheat, with red value F5 (on a scale 00, none, to FF, full), green value DE and blue value B3. Hexadecimal digits may be given in either upper or lower case.

With the exception of picture and sound, each type of command can only occur at most once in any blurb file. Commands can be used in any order or not at all: an empty “blurb” file results in a perfectly legal, if useless, Blorb file. The full set of commands is as follows:

copyright string

Adds this copyright declaration to the file. It would normally consist of the author's name and the date.

release number

Gives this release number to the file. This is the number returned by the opcode @picture_data 0 within any game using the Blorb file, and might be used when printing out version information.

palette 16 bit
palette 32 bit
palette {colour-1› … ‹colour-N}

Blorb allows designers to signal to the interpreter that a particular colour-scheme is in use. The first two options simply suggest that the pictures are best displayed using at least 16-bit, or 32-bit, colours. The third option specifies colours used in the pictures in terms of red/green/blue levels, and the braces allow the sequence of colours to continue over many lines. At least one and at most 256 colours may be defined in this way. This is only a “clue” to the interpreter; see the Blorb specification for details.

resolution dim
resolution dim min dim
resolution dim max dim
resolution dim min dim max dim

Allows the designer to signal a preferred screen size, in real pixels, in case the interpreter should have any choice over this. The minimum and maximum values are the extreme values at which the designer thinks the game will be playable: they're optional, the default values being 0x0 and infinity by infinity.

storyfile string
storyfile string include

Tells perlBlorb the filename of the Z-code story file which these resources are being provided for. (There is no need to do this if you prefer not to.) Usually the Blorb file simply contains a note of the release number, serial code and checksum of the story file, which an interpreter can try to match at run-time to see if the Blorb file and story file go together. If the include option is used, however, the entire story file is embedded within the Blorb file, so that game and resources are all bound up in one single file.

sound id› ‹string
sound id› ‹string repeat number
sound id› ‹string repeat forever
sound id› ‹string music
sound id› ‹string song

Tells perlBlorb to take a sound sample from the named file and make it the sound effect with the given number. The file should be an AIFF file unless music is specified, in which case it should be a MOD file (roughly speaking a SoundTracker file); or unless song is specified, in which case it should be a song file (roughly, a SoundTracker file using other Blorb sound effects as note samples). Note that repeat information (the number of repeats to be played) is meaningful only with version 3 story files using sound effects, as only Infocom's ‘The Lurking Horror’ ever has.

picture id› ‹string
picture id› ‹string scale ratio
picture id› ‹string scale min ratio
picture id› ‹string scale ratio min ratio
and so on

Similarly for pictures: the named file must be a PNG-format image. Optionally, the designer can specify a scale factor at which the interpreter will display the image – or, alternatively, a range of acceptable scale factors, from which the interpreter may choose its own scale factor. (By default an image is not scaleable and an interpreter must display it pixel-for-pixel.) There are three optional scale factors given: the preferred scale factor, the minimum and the maximum allowed. The minimum and maximum each default to the preferred value if not given, and the default preferred scale factor is 1. Scale factors are expressed as fractions: so for instance,

picture "flag/png" scale 3/1

means “always display three times its normal size”, whereas

picture "backdrop/png" scale min 1/10 max 8/1

means “you can display this anywhere between one tenth normal size and eight times normal size, but if possible it ought to be just its normal size”.

REFERENCES
The Perl script ‘perlBlorb’ is available from the Inform web-page.   The source code to Kevin Bracey's fully Blorb-compliant standard interpreter ‘Zip2000’ is public.   Andrew Plotkin has published generic C routines for handling Blorb files.   Numerous utility programs exist which will convert GIF or JPEG images to PNG format, or WAV and MPEG sounds to AIFF.