The ZLR Project

What is ZLR?

ZLR is a Z-machine interpreter whose primary goal is to be fast.

It is written in C# for the .NET Framework 2.0, and the ZLR engine should be portable to compatible runtimes such as Mono. The I/O interface is separate from the virtual machine core; a Windows console interface and a Gargoyle-based Glk interface are included, but ZLR could just as easily be adapted to run in a native graphical window via Windows Forms (or WPF, GTK#, etc.), or Unix text mode via MonoCurses, or bound to another Glk library.

(Note: the rest of this page is even more technical than the above. If you're not interested in such mumbo-jumbo, you might want to just skip to "Where can I get it?" at the bottom.)


The advent of Inform 7 has raised demands on interpreters. It's now shockingly easy to write a single statement that will perform hundreds of function calls, examine thousands of object relationships, and so on. Although such things can often be avoided, in many cases the benefit they provide outweighs the cost of execution time.

Also, the main limitation of the Z-machine is its 64k of writable memory. Code space, on the other hand, is subject to a much looser restriction. This means that one way to conserve memory is to calculate data as it's needed, rather than storing it in writable memory, which again has a cost in execution time.

The cost comes in because traditional interpreters spend most of their time not executing game code. Instead, most of the time is devoted to decoding instructions: figuring out what operation the game wants to perform, on what values, and what to do with the results. Even when they're executing the same instructions over and over, they have to decode them repeatedly, and every time it takes longer to figure out what to do than it takes to actually do it!

Some interpreters, such as Git for the Glulx platform, analyze the game code before it's executed, in order to get the decoding out of the way. The results of this analysis can be cached to avoid re-analyzing code that has already been executed once. ZLR goes a step further: instead of just chewing the code up into an internal format that's easier to digest, ZLR translates it into IL, the native language of .NET, which in turn is translated by .NET's just-in-time compiler into real, working machine code optimized for your CPU. The result is code that doesn't need to be analyzed ever again - just executed.

How does it work?

Because the Z-machine offers a few features that don't translate well to .NET -- mainly save/restore and undo -- it's not practical to translate the entire game to IL at once, or to directly map Z-machine routines to .NET methods and Z-machine local variables to .NET local variables.

Instead, ZLR translates fragments of Z-machine code into fragments of IL. When the game begins, we look at the initial PC (program counter) and start translating from there until we reach an instruction that can drastically change the game state: calling or returning from a routine, restoring a previously saved state, and so on.

Once we hit one of those instructions, we finish the fragment (including that last instruction, but none afterward), cache it, and execute it. The fragment will most likely change the value of PC: for example, a routine call would push a new call frame and then leave PC set to the start of the routine being called. After executing the fragment, we start translating again from the new value of PC, and the cycle continues.

What's the current status?

ZLR is currently able to execute V5 and V8 games with reasonable success. Casual benchmarking suggests that ZLR currently runs between 1X and 5X as fast as traditional interpreters, depending on the particular task.

Feature checklist:

What's still planned to be done?

Please see the SourceForge trackers for a list of planned changes and known issues.

Where can I get it?

Please use the SourceForge download system to get a copy of ZLR.

To compare ZLR's performance to other interpreters, you may wish to use this modified Windows Frotz that produces a similar performance report to ZLR's benchmark mode.

Where do I send feedback / bug reports?

Contact vaporware on ifMUD or send an email. Logo