Glk: An Interface Standard for Interactive Fiction

Introduction

Here's where I talk about what Glk is, why Glk is, and what it's good for. Unfortunately I haven't actually written this bit yet. Until I do, please refer to chapter zero of the specification document, which explains all the basic ideas.

I do, however, have a glowing testimonial.

Glk is a free standard. Here's what I mean by this.

Specification

This is the Glk API Specification, version 0.7.5.

And, just as important,

The "glk.h" header file (for C)

Liberation

If you're going to run a Glk program, you need a Glk library which runs on your machine.

The official and up-to-date archive of Glk libraries is on the IF Archive, under if-archive/programming/glk/implementations. Here is a list of some of them, but it's not a complete list and it is not immune to falling out of date:

CheapGlk library 1.0.6 (C source code for an extremely minimal Glk library; uses only stdio.h, and allows only a single window. Nonetheless, this is a fully Glk-compliant implementation.) [Glk 0.7.5]
GlkTerm library 1.0.4 (C source code for a terminal-window Glk library, implemented using the curses.h screen control library. Should compile on any Unix system or reasonable facsimile, as long as it has the curses.h library. (No relation to the Meldrews.)) [Glk 0.7.4]
GlkTerm library 1.0.4 with wide char support (Same as above, modified to use ncursesw or ncurses to display and accept all Unicode characters which the terminal supports. By Alexander Beels.) [Glk 0.7.4]
RemGlk library 0.3.1 (C source code for a remote-procedure-call Glk library. This uses stdin/stdout, but it's not as cheap as CheapGlk; it supports multiple windows. Generates output, and accepts input, in structured JSON form. See documentation.) [Glk 0.7.5]
IosGlk library 0.2.0 (ObjC source code and Xcode project for an iOS Glk library.) [Glk 0.7.3]
MacGlk library 0.8.7 (CodeWarrior library package for a Macintosh Glk library. And source for same.) [Glk 0.6.1]
GlkDOS 0.19.1 (a Glk library for DOS. And source code. By L. Ross Raszewski; see his GlkDOS page for more info.) [Glk 0.6.1]
DosGlk version 1998101701 (an older Glk library for DOS; 16-bit and 32-bit libraries included. And source for same. By Matt Kimball (mkimball@mkimball.org)) [Glk 0.4]
WindowsGlk version 1.2.1 (a Glk library for Windows 95/98/NT/00. And source. By David Kinder.) [Glk 0.6.1]
XGlk library 0.4.11 (C source code for an X Windows Glk library. Should compile on any Unix system which has X installed.) [Glk 0.6.1]
GlkLoader 0.3.0 (C and Perl source for a Unix library that can dynamically load any other Glk library, without recompilation. By Joe Mason.) [Glk 0.6.1]
GlkOte (Javascript library code which implements something analogous to, although not identical to, the Glk API. See documentation.)

Association

These are source files that come with the Glk API, although they're not actually part of it. If you're writing a Glk library, you'll want to look at them. See the spec for their full ineffable significance.

The Dispatch Layer: This allows virtual machine interpreters (and other run-time systems) to use the Glk API dynamically. To interoperate with the dispatch layer, a Glk library must include gi_dispa.c and gi_dispa.h.
The Blorb Layer: This allows the library to load images and sounds from a portable archive. To interoperate with the Blorb layer, a Glk library must include gi_blorb.c and gi_blorb.h.
The Debug Layer: This allows the library to pass debug command to the game (interpreter) via a side channel. To interoperate with the Debug layer, a Glk library must include gi_debug.c and gi_debug.h.

Programmification

In addition to a couple of pedagogical sample source files, we have games, interpreters, and other such goodies.

"model.c" (C source code for a simple model IF program; reads a line of text and reacts to it, maintains a status window, etc.)
"multiwin.c" (C source code for another Glk model; this one demonstrates multiple windows, timed input, and Latin-1 characters.)
Dungeon 3.2B for Glk (C source translated from the most recent Fortran source.)
Dungeon 3.2B with GDT for Glk (same as above, but with the in-game debugger -- thanks Paul Goyette.)
Floo (a simple Glk-native scripting language. This gets a whole directory to itself, so look here for interpreters, documentation, etc.)
TADS has been ported to Glk by Stephen Granade. It fits very well -- though that shouldn't be too much of a surprise, since the lessons I learned making MaxTADS went into Glk's design. See the TADS directory on the IF Archive. (The Glk port is included in the main source distribution.)
Hugo has also been ported to Glk. The connection is rather more awkward, because Hugo has a more complex display model that doesn't map well to Glk. Many Hugo features are not supported. Nonetheless, see the Hugo directory on the IF Archive. And here is the Mac executable (v25), which I support.
Nitfol is a Glk-based Z-machine interpreter, written by Evin Robertson. See also the Nitfol directory on the IF Archive.
Zeal is another Glk-based Z-machine interpreter, written by Jeremy Condit.
Grpad is a demo / test for Glk graphics windows, written by L. Ross Raszewski.

Execution

And if you're not into compiling, you can download the Glk programs as ready-to-run executables, for a couple of platforms at least.

Glulx is a virtual machine designed for IF; the interpreter uses Glk.
Mac executables of model.c and multiwin.c (built with MacGlk.)
Mac executable of Dungeon 3.2B (built with MacGlk.)
DOS executable of Dungeon 3.2B (built with DosGlk '101701. Matt says it's 32-bit only.)
Floo (executables here too.)

Miscellaneaification

Some other documents of relevance:

Charts of the Latin-1 character set, the official character set of Glk.
A quick discourse on the Z-machine quote-box problem.
Another discourse on multi-threaded Glk libraries.
Yet another discourse on interpreter autosave (for mobile Glulx intepreters).
Why IF save files break (every time you update the game). This is a hard problem.
Making a standalone Glulx app (on iOS, MacOS, or Windows).

And, just to show off what I'm doing here:

Screen shot of GlkTerm running model.c (6K GIF file).
Screen shot of MacGlk running model.c (8K GIF file).
Screen shot of XGlk running model.c (11K GIF file).

What's New

As of April 2020, the copyright of the Glk spec document is transferred to the Interactive Fiction Technology Foundation. I still act as the maintainer.

API spec 0.7.5! Graphics windows can support character input; Unicode text files must be UTF-8.

I've posted RemGlk, a very experimental library that uses JSON structured data on stdin and stdout.

API spec 0.7.4! Adds a way to read data from a Blorb chunk.

API spec 0.7.3! Expands the audio functions.

API spec 0.7.2! Adds date and time (clock and calendar) functions.

API spec 0.7.1!

winmethod_Border and winmethod_NoBorder constants, to request a border or no border between Glk windows.
glk_set_terminators_line_event(), to allow line input to be submitted when specific special keys (e.g., function keys) are hit.
glk_set_echo_line_event(), to control whether line input is echoed when the line is submitted or cancelled.
glk_buffer_canon_decompose_uni() and glk_buffer_canon_normalize_uni(), to normalize Unicode strings (Normalization Forms D and C).

API spec 0.7.0! Now with Unicode.

GlkOte, a Glk-style Javascript library for web applications.

Alexander Beels has contributed a port of GlkTerm which can accept and display Unicode characters, using the ncursesw library.

Last updated July 27, 2024.

Glulx home page

Zarfhome (map) (down)