Glulx graphic/sound resources

Roger Firth's IF pages
Glulx graphic/sound resources
Glulx graphic/sound resources

Using Glulx as a straight replacement for the Z-machine is relatively straightforward, especially if you've glanced at the introductory material from Adam, from Doe (now slightly dated), from Emily and from Zarf (especially his Game Author's Guide for Glulx Inform).

When your ambitions extend towards the inclusion of sounds and pictures in your Glulx game, things become more... interesting. Apart from the obvious problems of creating or locating audio-visual resources whose presence will genuinely enhance the game, you face the rather more mundane issues of linkage -- how to refer to the resources in your game --- and packaging -- how to deliver the resources to your eventual players.

The linkage issue is actually pretty straightforward. As far as your source code is concerned, all sounds and pictures are referenced by number (rather than by name). To play a sound, or to display an image, you issue one of these calls:

  glk_schannel_play(channel, sound)
  glk_schannel_play_ext(channel, sound, repeats, notify)

  glk_image_draw(window, image, val1, val2)
  glk_image_draw_scaled(window, image, val1, val2, width, height)

The highlighted sound and image arguments are the reference numbers. Each sound resource needs its own distinct number, and each picture resource needs its own distinct number, though the numbers used for sounds don't have to be different from the numbers used for pictures. The choice of which numbers to use is down to you. However, for reasons that will (hopefully) become clear, I suggest that you assign numbers to the sounds in the order which you add them to the game -- irrespective of the order in which they may be played -- with the first sound added being allocated number 3, the next one number 4, then 5, 6, and so on. Similarly, you can allocate number 3 to the first picture which you include, 4 to the next, in the same way.

The issue of packaging is slightly more complex. It's important to realise that the compiler's job is simply to turn an Inform source program into executable code targetted at the Glulx VM; all it knows is that you've made numeric reference to some sounds and pictures. It's the interpreter that marries the game with the resource files containing those sounds and pictures. Therefore, your problem is: how to transport your sounds and your images to the player's machine? You have three options:

shipping the game and the resources as individual files;
shipping the game and its resources collected into a single file;
shipping the game in one file, with all the resources collected into a second file.

If you follow my recommendations on naming your resource files, you can automatically combine the first and third of these options, so that your compiled game.ULX file will work with resource files which are either contained in an associated game.BLB or -- when that file isn't available -- placed individually in the same directory as the game. This gives maximum flexibility, especially while you're developing the game.

Individual files

This is the easiest option... for you (though it's slightly messier for the player). Recollect that in your game you've played a sound by issuing a call to one of the Glk functions glk_schannel_play(... sound ...) or glk_schannel_play_ext(... sound ...), where sound is the number associated with the sound resource. It turns out that, left to its own devices, the interpreter simply looks for a file called SNDsound.AIF (or SNDsound.AIFF) or MUSsound.MOD in the same directory as the game.ULX file, and plays it. So, call Glk with a sound value of 3, provide either SND3.AIF or MUS3.MOD, and just sit back and listen.

In exactly the same way, you could call one of the Glk functions glk_image_draw(... image ...) or glk_image_draw_scaled(... image ...). This time, the interpreter looks for a file called PICimage.JPG or PICimage.PNG and displays it. So, you can for example call Glk with an image value of 3 at some suitable point in your game, and providing you've made either PIC3.JPG or PIC3.PNG available in the same directory, the picture will appear.

The disadvantage of this approach is largely one of player inconvenience -- having to ensure that the various resources files don't get mislaid, or overwritten by identically-named resources from other games. However, with a little discipline and the help of a program like WinZip, this isn't an insurmountable hurdle.

Merged game and resources

Rather than deliver a game file game.ULX plus a whole load of individual resource files, you can bundle them all into a single Blorb file game.BLB (see also Adam's Blorb section in Gull). A clever interpreter is smart enough to handle .BLB files as well as .ULX files, and to extract from them the right bits at the right time. All that you need do is create the Blorb file in the first place. Here's how on a Windows PC.

Assign sensible names to each audio-visual resource that you wish to use. Let's say you've got two sounds -- BELLS and WAVES -- and three pictures RED_SQ, BEACH and TUNDRA. Create a file (say) RUSSIA.RES which links each resource name to the appropriate file containing the sound or picture, and to the compiled game. You can call your resource files whatever you like, but for maximum flexibility you should stick to the formal name-and-number scheme described in the previous section (SNDsound.AIF, MUSsound.MOD, PICimage.JPG, and PICimage.PNG). For example:
```
    sound   BELLS  mus3.mod
    sound   WAVES  snd4.aif
    picture RED_SQ pic3.jpg
    picture BEACH  pic4.png
    picture TUNDRA pic5.png
    code           russia.ulx
 
```
Download L Ross Raszewski's iblorbb.zip package, which provides the bres and blc tools.
In an MS-DOS window, run bres RUSSIA. This simply reads RUSSIA.RES and automatically creates the two further files RUSSIA.BLI (a set of Inform constant definitions):
```
    Constant BELLS  3;   !Blorb Snd:mus3.mod
    Constant WAVES  4;   !Blorb Snd:snd4.aif
    Constant RED_SQ 3;   !Blorb Pict:pic3.jpg
    Constant BEACH  4;   !Blorb Pict:pic4.png
    Constant TUNDRA 5;   !Blorb Pict:pic5.png
 
```
and RUSSIA.BLC (a control file for blc):
```
    Snd  3 MOD mus3.mod
    Snd  4 FORM snd4.aif
    Pict 3 JPEG pic3.jpg
    Pict 4 PNG pic4.png
    Pict 5 PNG pic5.png
    Exec 0 GLUL russia.ulx
```
You'll notice that bres has allocated the numbers 3,4,5... to the sounds and to the images. It always does that, irrespective of what the resource files are called. However, if you follow my suggestion and use the name-and-number scheme for your resource files, and if you list them in the correct order, then the numbers allocated by bres will coincide with the numbers that you've assigned. Trust me: this both reduces confusion and gives enhanced flexibility.
Optionally, edit your game to add the line Include "RUSSIA.BLI"; somewhere near the top; you can then use the resource name constants rather than numbers when invoking the resources. For example, you might call glk_schannel_play(... BELLS ...) and glk_image_draw(... RED_SQ ...) rather than glk_schannel_play(... 3 ...) and glk_image_draw(... 3 ...).
Compile the game to create RUSSIA.ULX.
In an MS-DOS window, run blc RUSSIA.BLC RUSSIA.BLB. This reads RUSSIA.BLC, collects together the resources named therein, and merges them into a single file RUSSIA.BLB.
Run a Glulxe interpreter and open the file RUSSIA.BLB.

The only disadvantage of this approach is that you're distributing a single .BLB file containing both the game and its resources. Players whose interpreter is expecting a .ULX file and can't handle Blorb files won't be able to play the game.

Collection of resources

In this scenario, you ship two files: the original game.ULX and an associated game.BLB containing just the resources for that game. When you start to play the .ULX file, the interpreter notices the .BLB file, looks inside it, and finds the individual resources that the game is about to invoke.

What you do is almost identical to the previous procedure. The only differences are:

In your linkage file RUSSIA.RES, omit the code line which mentions the compiled game:

    sound   BELLS  mus3.mod
    sound   WAVES  snd4.aif
    picture RED_SQ pic3.jpg
    picture BEACH  pic4.png
    picture TUNDRA pic5.png

Follow the other steps.
Run a Glulxe interpreter and open the file RUSSIA.ULX.

Players whose interpreter can handle Blorb files will see the game complete with sound and pictures. Interpreters which don't understand Blorb will see the game without the extra goodies.