Implementing a Z-Machine for the first time

Hello all,

I want to implement a Z-Machine as a hobby project. I’ve implemented toy stack and register machines before, but nothing substantial.

I thought I’d target Version 2 of the Z-Machine first and work up to version 5 adding features incrementally. I’m trying to go into this blind, so haven’t looked at other implementations.

I was planning on using CZECH 0.8 to test it

I’ve found several standards documents online, but would appreciate people recommending a de facto version, or maybe the most beginner friendly version?

I understand that QUETZAL is something I should understand, and maybe later BLORB.

Because I’m a new user, I can only post 2 links. In addition to the 1.1 document at informDASHfictionDOTorg I’ve found:

If anybody has any general pointers to avoid common pitfalls, I’d appreciate it, but as I say I’m trying to treat this as a challenge and go in blind.

Many thanks all


Don’t do version 2, there’s hardly any story files at all. Do either version 3 or 5. If you make version 5 then you can test it with Praxix which is much more thorough than Czech.

The standards document you want is this one:
It’s very thorough, you probably won’t need much else. But if you have questions about how to interpret it you can always ask here.


That’s really useful, thanks @Dannii.

One thing you could clarify for me is if the game files I’d download from the internet and the save files are both Quetzal format?

No, only savefiles are in Quetzal, and it’s not required either for interpreters to use Quetzal. I’d recommend you do though, as well as considering whether you could use its layout for your call stack. If you build your interpreter from the beginning to use the Quetzal call stack format then saving and restoring will be much simpler.

You might as well support the Blorb standard, unless you’re targeting a retro platform. It’s very simple (for what you need for a Z-Machine interpreter.)

To add on to what Dannii said—Quetzal is a standard for saving and restoring game state which (ideally) lets saves be transferred between interpreters, and I’d recommend it both because it means your save files will be compatible with others’ and because it suggests an “obvious” way to implement stack frames.

Blorb is a standard for including external resources with the game file; later Z-machine versions include opcodes for “play sound number X” and “display image number X” and so on, but the Z-machine standard doesn’t specify how the interpreter decides what “image number X” means or where it finds the data for it. Blorb specifies how those resources can be bundled up with the bytecode, and it’s what everyone uses nowadays (there’s really no competition). But if you’re not implementing graphics or sound support, it’s not essential.

Definitely target version 3. It has a large number of story files, and lacks some complex features found in 5.

Once you have a handle on things, adding support for other versions should come fairly easily.

Story files you download are essentially copies of the machine’s memory and can be loaded directly into a byte array. Quetzal files are for saving your position within a game and the format is completely optional, although it is nice to support because it allows people to reuse save files across different interpreters.

Blorb is a format for storing graphics and sound files in a cross platform way, but version 3 games don’t use either of those things (except one single solitary version of Infocom’s: The Lurking Horror, which has sound support). It can also be used to bundle the entire story file with any resources, but again this isn’t particularly useful for version 3.

The standards document Danii linked is indeed definitive and thorough.

When I first started, I implemented the memory/stack first and then machinery to decode instructions. Then pick a game, e.g. Zork and run the game and implement the instructions one at a time as you encounter them. Most complexity for version 3 lies in the object manipulation and input reading instructions.


Thanks so much, all. These are great pointers to help me in the right direction.

I’ll be sure to base my stack on Quetzal, and knowing the game file can be pretty much loaded into memory is a great bootstrap.

1 Like