UnZ - Unpack Z-machine file format information

Oh, I can provide that! At least in broad strokes, but I can look into the details of any part you like.

When Dialog compiles a Z-machine file, it goes:

  • Header
  • IFID
  • Main heap
  • Aux heap
  • Long-term heap
  • Object tree
  • Object property tables (usually empty)
  • “Select table”: one byte for each (select) statement that needs it, used to remember its current state.
  • “Extended attribute table”: byte arrays used to give objects additional attributes beyond the ones the Z-machine provides. These are always static; even though they’re in RAM, Dialog never emits code to change them at runtime.
  • “Globals table”: the usual Z-machine global variables, followed by a word array holding any global variables that don’t fit in the Z-machine’s registers (I think? I’ve never actually hit the Z-machine register limit, I should test this).
  • “Object variables”: each per-object variable is stored as a word array indexed by object number.
  • Abbreviation strings
  • Abbreviation table
  • Scratch space
  • Header extension table
  • Unicode translation table
  • End of RAM
  • “Wordmaps”: for each predicate queried within a (determine object), there’s a table mapping possible words to objects that can emit those words. Common words like “the” don’t get entries, and some predicates can’t be statically analyzed, but this lets the runtime cut down the number of objects that need to be checked by multiple orders of magnitude.
  • “Wordmap data”: each entry in a wordmap is either a special value meaning “too common”, an object number, or a pointer into one of these tables that lists the possible objects.
  • Dictionary
  • End of addressable memory
  • Routines
  • Strings
2 Likes

Excellent!

Some future version of unz may decode some of that. I tried looking in the code, but Linus isn’t big on commenting the code.

1 Like

Unfortunately not. The ifcomp2025 branch has more comments than the rest, because I’ve annotated what I’m working on, but it’s still pretty sparse. (That one, notably, includes comments explaining the format of wordmaps and wordmap data tables.)

2 Likes