Table of Contents:
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.
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.
," and "
" A Brief Overview of Glk (with examples from unglklib), the Demo
Just a Dream,
" and the Demo of glk screen transitions, "Vistas," see
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
refer to it as you read this guide.
Thanks to Adam Cadre's
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.
(Sorry, you got to read this stuff to understand this guide.)
A program which turns plain-text source code written in a high-level programming
language (such as Inform) into low-level machine language.
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
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.
A program which takes a game file (compiled source code) and
interpreters it, running (playing) it on a specific platform. There are Inform
for PCs, Macs, Palm Pilots, and more (but no banana interpreters yet).
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.
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.
A Glulx interpreter (Glulx
xecutable) that plays a game file
compiled by a Glulx compiler.
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.
A new portable API (application programming interface) created by Andrew
Plotkin to simplify the
programming of interpreters and increase the portability of games. Currently
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
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
the C functions, and formated them into Informese, so game authors can call
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
The archive file format used by Glulx Inform. Essentially a blorb is an archive
game file, graphics (optional), and sounds (optional).
Glulx Inform games with both code and resources packed all into one blorb have
.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.
A Dos/Windows blorb packing program written by L. Ross Raszewski.
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.
Okay, what does this all mean to me as an Inform programmer?
So, for the Inform programmer, if you want to write big games, switching to
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
for I/O previously not possible in regular Inform. Finally, it also means
changing your entire way of thinking from all-text to multimedia.
- 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
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,
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:
- 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.
- 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
also uses Z-machine opcodes, such as @set_cursor.
- 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
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
"The Game Author's Guide to Glulx Inform"
The rest of this guide focuses on Glulx Inform's use of Glk's multimedia
- 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.
(news). There is not much documentation or source code yet for using
And, if you are like me, reading the Glk specs may be more than you can or
take on. They are also designed for interpreter C-language programmers, not
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.
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:
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
outlining Glk while also
emphasizing Glulx Inform programming.
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.
Because Glulx Inform has increased memory and invokes Glk for I/O,
you can now create multimedia games with Inform. Well, actually, Glk.
Roger Firth has created a beginner's getting-started-with-Glulx web
Just Enough Glulx.
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
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
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.
Opening a graphic window (from Sensory Jam).
Glulx Inform's glk() one function
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,
gg_paintingwin = OpenGraphicWindow(gg_mainwin, 2, 1, 200,
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
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 --
I did in
How is Glk like a forest?
What multimedia capabilities does Glk have?
But with all these new capabilities, how do I keep track of what is going on?
This is getting complicated. What can I skip? What can't I skip?
Alright, maybe I'll try this thing. How do I get started?
Table of Contents
Doe's Main IF Page
(Updated 2/08 -- Links Only)
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
Direct any questions about Glulx and Glk themselves to their
This question deflection is deliberate. (I'm not THAT dumb.)