Banner - Inform Glux/Glk for Dunces. Banner includes a dunce cap and the three, say no evil, hear no evil, see no evil monkeys.

Table of Contents:

Update: I am no longer supporting Glulx or this tutorial. Please see reasons in Part Four. 3/2009 - I have updated these pages a little to clear up some murky writing and correct a few errors.

Purpose:   This guide does not cover Glk for languages/interpreters other than Inform. It also doesn't cover basic Inform programming. This guide is designed to help you, the experienced / semi-experienced Inform programmer, reduce your learning curve so you can start playing with Glk quickly. In other words, give you just enough knowledge so you can get into serious trouble.

For the easier " unglklib.h ," and " briefglk.txt, " A Brief Overview of Glk (with examples from unglklib), the Demo Glulx multimedia game, " Just a Dream, " and the Demo of glk screen transitions, "Vistas," see Part Four.

Despite it's silliness, this guide is a "hard-core" look at Glk. It uses examples from infglk and is meant for the Informer who is willing to spend one to six months learning Glk.

Since this guide is essentially supplemental study material for the infglk Wrapper Reference, I recommend that you print out the attached reference first and refer to it as you read this guide.

Acknowledgements:   Thanks to Adam Cadre's Gull, for helping me start to understand Glk, and to Andrew Plotkin for answering my dumb questions. Also, special thanks to L. Ross Raszewski for agreeing to be the expert Glulx/Glk consultant for this guide.

Really dumb looking monkey eating a banana. Get comfortable while we get some (funny-named) terms out of the way.

Dunce Glossary (Sorry, you got to read this stuff to understand this guide.)

Compiler A program which turns plain-text source code written in a high-level programming language (such as Inform) into low-level machine language.
Z-machine A VM (virtual machine) used by Infocom and recreated by Inform. Also an idea which was way ahead of its time (Java is a VM). The ZIL (Zork Interpreter Language) compiler and the Inform language compiler turned/turns source code into machine code designed for the imaginary Z-machine. This means the resulting op codes (low-level machine language calls) are tailored for a virtual machine, not for any particular platform (PCs, Macs, Palm Pilots). Because of this, Z-machine games are highly portable.
Interpreter A program which takes a game file (compiled source code) and interpreters it, running (playing) it on a specific platform. There are Inform interpreters for PCs, Macs, Palm Pilots, and more (but no banana interpreters yet).
Glulx (Inform) A new virtual machine designed by Andrew Plotkin. Glulx Inform detaches Inform from the Z-machine and reattaches it to a new "G-machine." The Glulx VM lifts the memory constraints formerly imposed by the Z-machine (created by Infocom in pre-gigabyte days), and also invokes Glk to handle I/O.
informbp A bi-platform Inform compiler that can turn Inform source code into the usual Z-machine game file, or by using the -G command line switch, into a Glulx game file. Because it is bi-platform, it also needs the bi-platform Inform library (provided by Zarf). There is also a Glulx-only compiler.
Glulxe A Glulx interpreter (Glulx e = e xecutable) that plays a game file compiled by a Glulx compiler.
I/O Input/Output - Input from player/file and output to the screen/multimedia device/file. Because of hardware, I/O handling differs more from platform to platform than any other sort of programming. So a Z-machine I/O op code (usually preceeded by @, such as @read_char) is executed by a Mac and a PC differently and, therefore, must be programmed differently. Thus, making an Inform game able to play on various platforms is thanks in part to the use of the Z-machine VM, and in part to the interpreter programmers who tailored the I/O handling for specific platforms.
Glk A new portable API (application programming interface) created by Andrew Plotkin to simplify the programming of interpreters and increase the portability of games. Currently there are Glk interpreters for both Inform and Hugo, so it was not specifically designed for Inform. Glk attempts to create an IF I/O "standard" by making the user interface more consistent from platform to platform. It does this by putting a layer between the interpreter and the game file. This layer is actually a separate "Glk library" written in C. There are Glk libraries available for various platforms, so Glk interpreters for various platforms can call them to handle I/O.
Glk library
infglk infglk.h is an Inform include file that was created with a Perl script written by John Catre. His Perl script read the Glk C-source code, "lifted out" the C functions, and formated them into Informese, so game authors can call them.
glk() This is the one Glk function built into the Glulx Inform library. Although only one function, it can invoke all of the Glk functions calls in the platform-specific Glk C library that the player's interpreter uses. glk()'s first argument is an integer (represented in hexadecimal) that determines which Glk library function will be called. It's subsequent arguments set flags for that function.
Blorb The archive file format used by Glulx Inform. Essentially a blorb is an archive packed with:  game file, graphics (optional), and sounds (optional). Glulx Inform games with both code and resources packed all into one blorb have the .blb extension. Those without a blorb or with a separate blorb just for graphics and sound, have the .ulx extension. Like Glk, blorb also helps make games more portable.
iblorb A Dos/Windows blorb packing program written by L. Ross Raszewski.
blorbtar A Perl script to pack a blorb file, written by Evin Robertson. It is meant to be used with the Unix or Linux operating system.

A dunce cap. Stupid Questions
  1. Okay, what does this all mean to me as an Inform programmer?

    1. Big Games - If you want to use Glulx Inform just to write a game that is too big for the Z-machine, you probably won't have to make many changes to your code. Almost everything is done for you. But, remember, since Glulx Inform uses a new VM, it has its own opcodes (low-level machine language calls). So you have to change any Z-machine opcodes you might previously have inserted directly in your code, into G-machine op codes (commands preceeded by @, such as @set_cursor, are Z-machine opcodes.) And, since memory is increased, math is based on a four-byte word instead of regular Inform's two-byte word, so you have to change any math based memory addresses.

      The major changes are:

      1. Style - Although Z-machine opcodes are usually preceeded by @, style is sneaky. It is still a Z-machine opcode, because style is Inform's short cut notation for @set_style. So if you want to bold text -- style bold; print (string) "this is in boldface"; style roman -- you have to replace style with a Glk function call. This is because Glk is the part of Glulx Inform that handles I/O, and boldfacing text is I/O since it affects screen output.
      2. Status Line - If you replace the Glulx Inform's default status line routine with one of your own, you will also have to use Glk functions. This is because the regular Inform status line also uses Z-machine opcodes, such as @set_cursor.
      3. Math - Zarf (Andrew Plotkin) says the place this will usually crop up in your own code is when you divide a property by 2 to get the length of that property.
        len = (obj.#prop) / 2
        for (i=0 : i<len : i++)
             print (string) (obj.&prop)--<i;
        len = (obj.#prop) / WORDSIZE;
        for (i=0 : i<len : i++)
             print (string) (obj.&prop)--<i;
        Since the bi-platform Inform library has been changed to use WORDSIZE (so library routines will default to a 2-byte word for regular Inform and a 4-byte word for Glulx Inform), if you put something similar to this in your code, just change 2 to WORDSIZE.

        These three changes, a detailed explanation of Glulx Inform's new status line, and several other new Glulx Inform routines are all covered very well in Zarf's, "The Game Author's Guide to Glulx Inform" .

        The rest of this guide focuses on Glulx Inform's use of Glk's multimedia capabilities.

    2. Multimedia Games - But if you want to take advantage of Glulx Inform's multimedia capabilities -- in addition to, or instead of, writing a big game -- then you have to delve into Glk. Uh huh. This is where, you, like I, will probably run into difficulty. There is a whole slew of new Glk routines to learn.

      A spoiling banana.   Bad banana (news). There is not much documentation or source code yet for using Glk. And, if you are like me, reading the Glk specs may be more than you can or want take on. They are also designed for interpreter C-language programmers, not Informers, so they cover a lot of things not pertinent to Glulx Inform. However, if you are a very good programmer and/or have no difficulty understanding dense technical specs, consult the Glk API Specifications. A good banana.   Good banana. On the other hand, if like me, your brain tends to go "on hold" when confronted with too much technical information, Adam Cadre's has put together a comprehensive Inform author's guide to Glk:  Gull. The explanations of text styles, windows and graphics are excellent. There are also some nifty demo games with source code. There is also this guide, which I wrote to help clarify Glk for myself and, hopefully, subsequently for others. It focuses on a broad overview, outlining Glk while also emphasizing Glulx Inform programming.
      A spoiling banana.   Bad banana. Technically, according to programming purists, we shouldn't have been putting "raw" Z-machine opcodes into Inform anyway (inserting low-level machine language into a high-level programming language). But when direct screen manipulation was needed, such as boldfacing text or changing the status line, there was really no other way to do it. Well, Zarf is a purist, which is partly why Glk exists in the first place -- to formally separate out these low-level I/O procedures from game coding.

      A good banana.   Good banana. Because Glulx Inform has increased memory and invokes Glk for I/O, you can now create multimedia games with Inform. Well, actually, Glk.
      A good banana.   Good banana. Roger Firth has created a beginner's getting-started-with-Glulx web page called Just Enough Glulx.

      A good banana.   Good banana. I have also written a Glulx Inform add-on Glk library, for Informers who want to be able to use Glk immediately. "unglklib.h" comes with "briefglk.txt," A Brief Overview of Glk for the Inform 6 Programmer, "Just A Dream," a demo Glulx multimedia game with source code, and "Vistas" a demostration of the screen transitions possible with glk. They are here.

      Glulx Inform's built-in glk() function can be used to invoke Glk's I/O system. Or you may use the G-machine opcodes, copy and glk, similar to Z-machine opcodes. But the easiest (and less mentally-straining) thing to do is to use "wrappers," Inform functions that wrap around Glulx Inform's one low-level glk() function, separating out its actions.

      Example: Opening a graphic window (from Sensory Jam).

      Glulx Inform's glk() one function G-machine opcodes Wrappers
      gg_paintingwin = glk($0023, gg_mainwin, $12, 200, 5, GG_PAINTINGWIN_ROCK); @copy GG_PAINTINGWIN_ROCK sp;
      @copy 5 sp;
      @copy 200 sp;
      @copy $12 sp;
      @copy gg_mainwin sp;
      @glk 35 5 gg_paintingwin;
      infglk wrapper and constants
      gg_paintingwin = glk_window_open(gg_mainwin, winmethod_Above+winmethod_Fixed, 200, wintype_Graphics, GG_PAINTINGWIN_ROCK);

      unglklib wrapper
      gg_paintingwin = OpenGraphicWindow(gg_mainwin, 2, 1, 200, GG_PAINTINGWIN_ROCK);

      The first argument passed to Glulx Inform's glk() function is an interger (represented in hexadecimal) that determines which Glk library function will be called. For instance, $0023 = open window and $0024 = close window. If you want to know what they all are, they listed in the appendix of the Glk API specifications.

      Thankfully for us dunces, John Cater created infglk with Zarf-approved wrappers. They follow the C-source naming conventions. However, wrappers can be named anything, and you can even write your own -- like I did in unglklib ;-).

    So, for the Inform programmer, if you want to write big games, switching to Glulx Inform means learning new Glk function calls to replace the old familiar Z-machine opcodes. If you want to use its multimedia capabilities, it means learning quite a few additional Glk functions for I/O previously not possible in regular Inform. Finally, it also means changing your entire way of thinking from all-text to multimedia.

    Part Two

  2. How is Glk like a forest?

  3. What multimedia capabilities does Glk have?

    Part Three

  4. But with all these new capabilities, how do I keep track of what is going on?

  5. This is getting complicated. What can I skip? What can't I skip?

    Part Four

  6. Alright, maybe I'll try this thing. How do I get started?

   Table of Contents      Doe's Main IF Page

  Version 8.30
(Updated 2/08 -- Links Only)
Monkey in dunce cap. Disclaimer:   This introduction to Glulx/Glk was unwisely created by dunce Doe, with L. Ross Raszewski providing expert advice/error checking. I learned while writing this and have added on more since. So please address any corrections, suggestions, or comments about its contents to me. Direct any questions about Glulx and Glk themselves to their creator, Zarf. This question deflection is deliberate. (I'm not THAT dumb.)