• Windows/Linux - Inconsistencies in how game code was interpreted between the Windows interpreter and the Linux interpreter. This cropped up in two main areas, screen draws and the glk entry point, HandleGlkEvent. For me this meant that when I developed a game in Windows that worked, I had to tweak it like crazy to also get it to work with the Linux terp.
• Linux - The Linux interpreter lacked code (that was supposed to be in the interpreter) to correctly draw certain types of jpegs. So two people wrote patches to make the Linux terp work with "Carma" and its intensive graphics approach. (The patches are at the archive.)
• Linux - Ditto with sound files, patches had to created to handle "Carma's" sounds/music.
• Windows/Mac - Sound files created under Windows, for some reason -- something to do with bit signing -- do not work with the Mac. Or, to be specific, do not work with QuickTime, the Mac terp's sound handler. This was the major platform incompatibility.
• Windows/Mac - Ditto with graphic files, QuickTime could not do the "animations" that I had developed under Windows and that also ran fine with Linux. Although this was not a platform file type of incompatibility, it amounted to the same thing as the above -- "Carma" would not run effectively on the Mac.

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.

Table of Contents:

• Part One
  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
  (Summarisizes 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.)

Get comfortable while we get some (funny-named) terms out of the way.

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

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 places where you might previously have inserted Z-machine opcodes directly into Inform 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 that is 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 to 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. I also wrote this guide to clarify Glk for myself and, hopefully, 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.   Good banana . Because Glulx Inform has increased memory and invokes for Glk I/O, you can now create multimedia games with Inform. Well, actually, Glk.

      Good banana . Since I first wrote this guide, Brendan Barnwell has created some add-on Glulx Libraries , and 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 Programmer, and "Just A Dream," a demo Glulx multimedia game with source code. They are here.

      
      Glulx Inform's built-in glk() function can be used to invoke Glk's I/O system. Or you may use 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() 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?
   
   

You are the visitor since Monday, July 31, 2000.