Table of Contents:

• Part One
  Purpose & Acknowledgements
  Glulx Inform - Glossary & Basics
  
• Part Two
  Glk - Terminology & Functions
  
• Part Three
  Glulx Inform & Glk - Error Checking & Glk Entry Points
  
• Part Four
  Other Glulx/Glk References & Library Add-Ons
  
• Appendixes
  infglk Wrapper Reference
  (Summarizes the functions in infglk.h -- their purposes, arguments, and return values.)
  Interpreter & Color Charts
  (Chart of Glulxe interpreters, and a color chart using hexadecimal notation.)

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.

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. player game Glk library interpreter
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.

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;
         
         to
         
         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.
      
      

      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.

      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.

      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.   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.

      Good banana. Roger Firth has created a beginner's getting-started-with-Glulx web page called Just Enough Glulx.   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?