Making debug file for ConsoleZLR with Inform 6?

Authoring Inform 6
1

I’ve been trying to experiment with ConsoleZLR (which can be used for debugging ZMachine games), but I don’t know if there’s a way to create the required debug file with the Inform compiler.

Can anyone help with either:

  • any pointers to a tool to convert the XML-debug-file to the binary one needed by ConsoleZLR
  • an example of a Inform6 correct debug file along with the source code for the game; this way I’ll at least have something to use to try out

Thanks for any pointers!

2

(Ah, found I could a game with a very-old inform6 compiler, so I have a debug file to play with. But if anyone knows any way to generate binary debug files from the modern compiler, or a tool to convert them, please let me know.)

3

@heasm66’s WinZLR includes a DebugWriter class that can do the conversion.

4

I’m thinking of “productify” it, but time is a limited resource…

It is pretty straigtforward so if anyone is in the mood for writing/converting it to a pythonscript or something. Feel Free!

5

Thanks, @heasm66 !

6

I’ve been meaning to do that at some point, but I keep running out of free time…maybe after TALJ.

7

I finally came around and did a “product”, ZConvert (I also added extracting ZCOD-chunk from zblorb).

GitHub: GitHub - heasm66/zconvert: A collection of conversion scripts for the z-machine. · GitHub
Precompiled for Win, OSX, Linux: https://drive.google.com/drive/folders/1S3bItNfNJArQRzlK9zVPT_eZWqH7Q9vl

ZConvert 0.1 (1st May 2026) by Henrik Åsman, (c) 2026
Usage: zconvert [switches] [filename]
A collection of conversion scripts for the z-machine.

 -bz, blorb_to_z    Extract ZCOD-chunk from zblorb-file.
 -h, --help, /?     Show this help.
 -o                 Specify output filename (default is <filename>.out).
 -xd, --xml_to_dbg  Converts a XML debug file to the binary DBG format.
                      Description of XML debug-format: https://gist.github.com/EmacsUser/3960569
                      Description of DBG debug-format: https://inform-fiction.org/source/tm/chapter12.txt
 filename           Name of file to convert (source).

Report bugs/suggestions to: heasm66@gmail.com
ZConvert homepage: https://github.com/heasm66/zconvert
8

If anyone have suggestions för other useful conversions to add, please tell me.

9

The XML format is now specified at https://www.inform-fiction.org/manual/I6-Addendum.html#debugformat

10

Here is a short instruction for those that want to test this with ConsoleZLR.

ConsoleZLR

ZLR is a .NET implementation of the Z-machine. Originally developed as a proof of concept for using JIT to speed up complex interactive fiction games, ZLR continues to be developed for use as a debugger and integration test engine in ZILF. Get ConsoleZLR here. I don’t know if @vaporware keeps any pre-compiled versions, but I have one for win-x64 here).

Instructions

Setting up a debug session with two console windows

  1. Compile an Inform6 file with the -k switch (output debugging information to “gameinfo.dbg”).

  2. Convert it with ZConvert.

  3. Start two consoles windows (the second as administrator)

  4. Console 1: ConsoleZLR -debug -listen 55555 advent.z3 advent.dbg

  5. Console 2: Telnet 127.0.0.1 55555

Commands and how to debug

ConsoleZLR.exe -debug advent.z3 advent.dbg

It’ll break on the first instruction. Type h or ? for the command list.

  • reset - Restart the game
  • step - Execute one instruction, entering function calls
  • over - Like step, but instead of entering a function call, run until the function returns or a breakpoint is hit
  • stepline, overline - Like step and over but for source lines instead of instructions
  • up - Run until the current function returns or a breakpoint is hit
  • run - Run until the game ends or a breakpoint is hit
  • break, clear - Set or unset a breakpoint. The argument can be a routine name (with optional offset, like PARSER+3), numeric address, or a source line reference like full path to source file:1234
  • breakpoints - List active breakpoints
  • tracecalls - Toggle printing a message for every function call
  • backtrace - Print the call stack
  • locals - List local variables and stack values for the current call frame
  • globals - List global variables
  • print - Evaluate an expression, using ZIL-like syntax. You can make changes by calling FSET, MOVE, SETG, etc.
  • showobj - Print the details of an object. The object is specified using the same ZIL-like syntax as print; in particular, you’ll need a comma if the object is in a global variable (showobj ,WINNER).
  • tree - Print the tree of all objects, or if an argument is given, the object tree with the given object as its root. The argument is in the same ZIL-like syntax as above.
  • quit - Exit
  • jump - Change the PC to a new address.

ZLR only works with binary debug info files (not XML).

11

Why does the second console need elevated permissions?

12

At least my win11 blocked comunication otherwise. May not be universal.