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.

2 Likes
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!

1 Like
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.

2 Likes
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
5 Likes
8

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

2 Likes
9

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

1 Like
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).

2 Likes
11

Why does the second console need elevated permissions?

12

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

1 Like