User Tools

Site Tools


notes:misc:detecting_megazeux_files

Detecting MegaZeux files

Detecting MegaZeux worlds with magic bytes

The MegaZeux world file header (for all versions) is documented here. From there, we can see that the following logic is sufficient:

  • The file extension is always `MZX` (world file),
  • If byte 25 is zero, the bytes 26-28 (magic) are either `MZX`, `MZ2`, `MZA`, or `M\x02?`, where ? is any byte;
  • If byte 25 is non-zero, the bytes 41-43 (magic) are either `MZX`, `MZ2`, `MZA`, or `M\x02?`, where ? is any byte;

Bytes 0-24 can then be used to parse the world title (codepage 437, null-terminated).

Detecting MegaZeux boards with magic bytes

Like the instructions above:

  • The file extension is always `MZB` (board file),
  • Byte 0 is always 0xFF,
  • Bytes 1-3 (magic) are either `MB2` or `M\x02?`, where ? is any byte;

Bytes 0-24 can then be used to parse the world title.

Detecting MegaZeux save files with magic bytes

Like the instructions above:

  • The file extension is always `SAV`,
  • The bytes 0-4 (magic) are either `MZSV2`, `MZXSA`, or `MZS\x02?`, where ? is any byte.

Detecting MegaZeux 2.00+ worlds with checkres

The most comprehensive to detect a MegaZeux 2.00+ file is to use `checkres`, a tool built as part of the MegaZeux distribution (source code, directory src/utils):

./checkres -AV [file]

If the error code is 1, the file is not a valid MegaZeux 2.00+ file. If the error code is 0, the file is a valid MegaZeux 2.00+ file - additionally, a CSV will be output containing the file's dependencies and whether or not they have been located, for example:

Required by,Expected file,Status,Found in
CAVERNS.MZX,CV_BALON.MOD,FOUND,.
CAVERNS.MZX,CV_BOSS.MOD,FOUND,.
CAVERNS.MZX,CV_HEVEN.MOD,FOUND,.
CAVERNS.MZX,CV_MAGIC.MOD,FOUND,.
CAVERNS.MZX,CV_STORY.MOD,FOUND,.
CAVERNS.MZX,CV_TECH.MOD,FOUND,.
CAVERNS.MZX,CV_TITLE.MOD,FOUND,.

Notice that I mentioned “2.00+” (this is also important, as for very modern files - we're talking the last few years - the format changed significantly, being effectively a ZIP file with a special file layout). For MegaZeux 1.xx worlds (the only MegaZeux worlds currently on DiscMaster), the output will be as follows:

ERROR: Worlds from MegaZeux 1.xx are not supported by this utility.

As with ZZT/Super ZZT, I am open to working on a dedicated tool to handle these (though PNG screenshot exports would be a little trickier).

notes/misc/detecting_megazeux_files.txt · Last modified: 2022/10/20 16:02 by asie