Z-machine interpreters with debug mode toggle?

I’m working on adding z4 support to my Status Line z-machine interpreter. I recall while working on the z3 version using a tool made by… someone?.. called… something? that would spit out opcode debug information for a game, which made it easy to compare where/why things were going wrong for my own interpreter.

Any recommendations? Hoping for something lightweight and z-machine-specific that is ready to go, rather than “take an open source project that supports 20 IF formats, insert debugging logs into the opcodes, compile a special version and watch logs in terminal”

But, I’ll do the above work if necessary.

Are you maybe looking for these tools?

Thank you, but no. Those are not what I’m looking for.

Specificallly, someone once shared a link to a z-machine which actually plays z-machine games and also spits out opcode information while playing. Playing that side-by-side with my own interpreter made it easy to see when and how my terp deviated from spec.

1 Like

Gotcha. I don’t think I’ve ever seen such a 'terp, but I hope the information turns up!

Is it Nitfol maybe?


I couldn’t find anything when I was casting about for this a few months ago, but I didn’t look that hard for it, so there may be something.

This is probably a bit of a stretch for you, but I did add such a thing to my own Z-machine project. If you’re comfortable building Rust, you could check out https://github.com/bkirwi/folly and run something like cargo run --package encrusted-heart --release --example term -- game.z4 --debug 2> debug.log to run a game and print out every instruction executed to debug.log. (It’s certainly not as battle-tested as other interpreters in the world, but I’m not aware of any bugs, so probably good enough to get things off the ground at least?)

1 Like

@Zed It was not Nitfol, but that looks like a nice option regardless. Thanks.

@bkirwi I don’t know anything about Rust, but I’m comfortable digging into something like that. Thank you, I’ll see what I can do with that.


That looks like it might be the one I was alerted to, yes. Looks like it is z3-only (and also impossible to use with games that need split-screen), so I will need to turn to previously suggested options. Or just dig in and do a customization of some other open source project. Thank you!

Cool! In theory you should be able to just install cargo and then run the command above.

This is working perfectly for me, thank you very much. My interpreter is also not battle tested, but having a sanity check like this is fantastic. Thank you for your help!

1 Like

Maybe I spoke too soon. Running Bureaucracy, I can’t progress through the “registration form” at the start. Can’t move to the next field. But still, for most games this should be a good option.

Thanks for mentioning this! Just pushed a fix, if you end up feeling like trying again.

1 Like

Wow, thank you for the swift repair. I’ll definitely be taking another look at it soon.

Unfortunately I am now in need of such a thing – my interpreter is struggling with parts of The Impossible Bottle. (Of the “long computation gives incorrect result” sort, which makes debugging rather nasty.) If anyone else has ideas for a good baseline comparison, I’m all ears! (Or if there’s a good boring easy-to-build interpreter I could modify, that’s great too.)

Edit: fixed the bug in question, but still interested in a less viscerally-urgent way.