MegaZeux File Format Reference

MZX

The most significant bit of the byte represents the leftmost pixel in the row and the least significant bit of the byte represents the rightmost pixel.

Example: setting the third, fifth, and seventh pixels.

SMZX

The most significant two bits of the byte represent the leftmost pixel in the row and the least significant two bits represent the rightmost pixel. The four colors are encoded as the following bit pairs and quaternary digits:

Example: setting the first and second pixels to color 2, third to color 4, and fourth to color 1.

Palette (.PAL)

This file format describes an MZX palette. A PAL file contains raw palette data only. Each color in the PAL file consists of 3 bytes representing the red, green, and blue components of the color. Each RGB component of a color is a value from 0 to 63 (inclusive).

A typical MZX or SMZX mode 1 PAL file contains 16 colors (48 bytes) and a typical SMZX mode 2 or mode 3 pal file contains 256 colors (768 bytes).

The PAL file does not encode any SMZX 3 color index information (see PALIDX).

Examples

Palette Indices (.PALIDX)

This file format describes SMZX mode 3 subpalette indices. A PALIDX file contains 256 sets of indices (one for each subpalette). Each set of indices is a sequence of four bytes (for a total of 1024 bytes per file); the first indicates color 1 of the subpalette, the second color 2, and so on.

World Format Header and Magic

Most world files begin with a 29-byte header. The only exceptions are locked worlds from MegaZeux 1.xx, encrypted worlds from MegaZeux 2.00 through 2.6, and rearchived MegaZeux 2.90 worlds (see the 2.90+ world format).

MegaZeux 1.xx locked world header:

MegaZeux 2.00 through 2.6 encrypted world header:

The following magic values are valid:

The internal MZX version value is derived from the world magic by 1) treating the last two bytes as a big-endian word if the magic is from 2.51s2 or later or 2) using 0x0100, 0x0205, and 0x0208 for 1.00, 2.00, and 2.51s1 worlds (respectively).

In all world files with a password, the password can be decrypted with the following algorithm:

In MegaZeux 2.00 through 2.6 encrypted worlds, the rest of the MZX file is XORed with a byte calculated from the password. The bundled MegaZeux utility "checkres" can output the unencrypted password and XOR value when given the -v option, if needed.

Notes:

1. The world title is a duplicate of the name of the title board.
2. The world title is null terminated within its fixed buffer.
3. The MZX 2.68 magic was erroneously never saved with world files, meaning worlds from MZX 2.68 relying on MZX 2.68 features won't work (as they are versioned for MZX 2.65). Resaving these worlds in a newer version (such as MZX 2.69) usually fixes this issue.
4. The password field is null terminated if it is 14 or fewer characters long. If the password is 15 characters long, it is NOT null terminated, and the null terminator must be added by the decryption algorithm.

Save Format Header and Magic

Save files use a different header from world files, but the idea is generally the same.

Format prior to MegaZeux 2.82

The internal MZX file format version is derived from the save magic the same way it is derived from the world magic, and is always the same as the MZX version that produced the save file.

The world version field (saved separately here) is always the same as the world version derived from the world magic when the world was initially loaded. Notably, this value is saved as a little endian word (whereas it is represented as a big endian word in the world magic string). In versions where this field is not present, the world version should be treated as the same as the file format version.

Global Data

World data immediately follows the header.

World Block 1

Total block length is 3890 bytes.

Notes

1. Worlds in this format do not contain ID chars block 3 (damages), so the 1.x default damages should be substituted for these instead. Likewise, goop (ID 34) didn't exist in 1.x, so char 176 should should be patched in for its character.
2. This is the first 178 bytes of the 2.00 ID chars block 2. The missing values are bullet chars (306-317), player chars (318-321), player color (322), missile color (323), and bullet colors (324-326). Equivalents to these values are stored separately later in the file.

Save Block 1 (.SAV only)

This block is present in save files only. Total block length is 16.

World Block 2

Total block length is 72.

Save Block 2 (.SAV only)

This block is present in save files only. Total block length is 9.

World Block 3

Total block length is 18.

Counters List (.SAV only)

This block is only present in save files and has an variable length. The counters list begins with the number of counters.

A list of N counters follows, each in the following format:

Board Names, Sizes, and Offsets

Following the board count byte is the board names list and the board sizes and offsets table.

For each board:

For each board:

Typically, board data immediately follows these tables.

Boards and Board RLE Planes

MegaZeux 1.xx does not support overlays or board modes; these should be treated as disabled and 100x100, respectively. Boards begin immediately with the board RLE plane data. Board contents are compressed with run length encoding, which is different from its MegaZeux 2.xx counterpart. Each board always has exactly 6 planes in the following order:

Each compressed plane starts with the following fields:

The RLE data follows after, and consists entirely of pairs of run lengths and byte values. The RLE plane can be decompressed with the following algorithm:

The RLE stream ends when (board width * board height) bytes have been expanded from the stream, and the next compressed plane or the board parameters block immediately follows.

Notes

1. There MAY be an extra run of length 0 padding between any two planes; if the width byte read is 0, skip the following byte and read the width and height from the next two bytes. (It's not clear why old versions of MegaZeux emit these runs, but this is exactly how VER1TO2 handles these. I have never seen this in practice. -Lachesis)

Board Parameters

The board parameters block follows the board RLE planes.

Notes

1. All 5 status durations are board variables in MegaZeux 1.x. This can be observed most easily in the "Flame Cavern" board of Caverns.
2. The default behavior is centered, but 1.x world files contain 0 here by default. A value of 0 needs to be corrected to -1 when loading worlds.

Board Objects

Following the board parameters are the robot, scroll, and sensor lists. Each list is stored as a single byte N indicating the number of robots, scrolls, or sensors on the board (0 to 255), followed by N stored objects of that type. Each object in its respective list immediately follows the prior, and the next list starts immediately following the last object in the previous list. The board data ends after all three lists and their objects have been read.

The board robots/scrolls/sensors in the list count from ID 1 upward, as ID 0 is the global robot and is invalid for scrolls and sensors. Since objects in the file are sequential, robot/scroll/sensor IDs may have to be reassigned when saving worlds or saves in these versions to optimize out gaps in the list.

Robots

Each robot is 37 bytes plus the length of the robot program long.

Notes

1. DOS MZX versions wrote robot, scroll, and sensor structs directly to world or save files. The unused 4-byte field at offset 4 probably corresponds to the program memory pointer in these versions, if MegaZeux 2.x is any indication. Scrolls likewise have an unused 4 byte field.

Scrolls

Each scroll block is 10 bytes plus the length of the scroll text long.

Notes

1. Scrolls in MegaZeux 1.x have a unique form of color coding that is not available in versions after. If the first character of a line is '!', the byte immediately following it will be used to apply the palette corresponding to that byte to the entire line. For example, if a line begins with 33 8e hex, the line will use color 8 as the background color and color 14 as the foreground color. Unlike 2.x scrolls, the scroll text does not begin with 01.

Sensors

Each sensor block is 31 bytes long.

Global Data

World data immediately follows the header. For ease of readability, it has been broken down into several blocks. Each block starts immediately after the previous block ends.

World Block 1

Total block length is 4129 bytes.

Save Block 1 (.SAV only)

This block is only present in save files. Total block length is 73 bytes plus the length of the current playing mod name.

Notes

1. The under player fields are used as an extra "layer" beneath where the player is standing. This is so e.g. the player can be placed on top of something that is on top of a floor and the floor won't be erased when the thing immediately beneath the player is pushed to the under layer. These fields are effectively unused though, because there is a duplicate in the second save block that is always loaded over these.
2. Prior to MZX 2.83, the mod playing length and mod playing fields were a single 13 byte null terminated buffer (total block length 84 bytes). Prior to MZX 2.51s2, the current playing mod was not saved at all (as it was always the same as the current board mod) (total block length 71 bytes).
3. Due to a bug, MegaZeux 2.80 through 2.84c instead save the board numbers of the first two saved positions as endian-dependent dwords (4 bytes) and ignore the last six.

World Block 2

Total block length is 72.

Save Block 2 (.SAV only)

This block is only present in save files has a length of 24 bytes.

Notes

1. Only the first 16 palette intensities were ever saved for SMZX modes 2 and 3.
2. Yes, this is duplicate info from the first save block, and no, I don't know why MZX saved this info twice. This copy is always loaded over the copy in save block 1.

Counters List (.SAV only)

WARNING: The format of the save blocks following this frequently changed from version to version. If there are any inaccuracies in the legacy world format documentation, they're probably below. MZX versions prior to 2.90 regularly dropped support for saves from older MZX versions due to the format changes in this part of the format being too messy to support. Difficulty in supporting changes to the world/save format are one of the main reasons the world format was replaced in MZX 2.90.

This block is only present in save files and has an variable length. The counters list begins with the number of counters.

A list of N counters follows, each in the following format in MZX versions 2.00 through 2.80X:

In MZX versions 2.81X and up, the counters are instead stored in the following format:

Notes

1. In MZX 2.51 and below, the maximum number of counters saved was 59, and the number of counters was saved as a byte. In DOS versions afterward, the maximum was 1020, and the number of counters was saved as a word (2 bytes). In MZX 2.80 to 2.84X, the maximum number of counters was lifted, and the number of counters was saved as a dword (4 bytes).
2. Save files created by MZX 2.84c will save two additional "counters" for MZX_SPEED and the MZX_SPEED locked status. These are named "mzx_speed" and "_____lock_speed". This vile hack was made unnecessary in MZX 2.90 by the new world format.

Strings List (2.80X through 2.84X) (.SAV only)

The strings block in versions 2.80X through 2.84X follows the counters block and is stored in a similar way.

A list of N string definitions follows. In 2.80X the strings were saved in the following format:

In versions 2.81b and onward (1), the following structure is used instead:

Notes

1. MegaZeux 2.81 tries to load strings in the format provided above but saves them in a different format unique to this release. Combined with no format validation at the time, the result was that 2.81 saves with strings always crashed on load.

Sprites List (2.65 through 2.84X) (.SAV only)

In versions that support sprites, the sprites list begins with N sprite definitions, where N = 64 for MZX 2.65 through 2.69b and N = 256 for MZX 2.69c and all releases afterward.

The sprite data is followed by the following global sprite variables:

The sprite collision list follows. In MZX 2.65 through 2.69b it is stored as follows:

From MZX 2.69c onward, the sprite collision list is saved as words and is always 256 in length:

Notes

1. Sprite flags:
   | Flag | Description | |--------|-------------| | `0x01` | Sprite is initialized | `0x02` | Sprite ccheck 1 is enabled | `0x04` | Sprite is drawn over the overlay | `0x08` | Sprite uses reference colors | `0x10` | Sprite is static relative to the viewport | `0x20` | Sprite ccheck 2 is enabled | `0x40` | Sprite references the vlayer

Strings List (2.68 through 2.70) (.SAV only)

Strings in DOS MZX versions do not have names and are instead numbered from 1 to 16. They are saved as fixed length buffers after the sprites list (rather than before it as in port versions). The length of this block is always 16*64=1024 (these weren't saved in versions with 16 char strings).

Math and File IO (2.68 through 2.84X) (.SAV only)

MZX versions 2.68 through 2.70 save the math and file IO vars as follows:

MZX versions 2.80X through 2.82X save the following:

MZX 2.83 saves the following:

MZX 2.84X saves the following:

Notes

1. These variables were still saved as a word from 2.80X through 2.84X despite the internal variable being expanded to a signed dword, meaning these were truncated and then loaded as unsigned words. This wasn't corrected until MZX 2.90. OOPS!

SMZX Data and Commands (2.69 through 2.84X) (.SAV only)

MZX versions 2.69 and up save the SMZX mode here.

If SMZX mode is 2 or 3 (2.81+), the SMZX palette (but NOT intensities, which were unsaved prior to 2.90) follows:

The commands value follows. MZX 2.69 through MZX 2.83 saved it as a word (despite the internal value being expanded to a dword in 2.80):

MZX 2.84X finally corrected this to a dword:

Vlayer (2.69c through 2.84X) (.SAV only)

The vlayer is saved as follows in 2.69c and 2.70:

MegaZeux 2.80X saves this instead:

This was changed to the following in 2.81X:

Global Robot Offset and Board Count

In an unencrypted world file this will always be at offset 4230.

Custom SFX Table

If the board count byte is 0, a custom SFX table is present. If there is not a custom SFX table in the world file, the world will use the MZX default SFX instead. The SFX table begins with:

Then, for each SFX (50 total):

Finally:

Board Names, Sizes, and Offsets

Following the board count byte is the board names list and the board sizes and offsets table.

For each board:

For each board:

Typically, board data immediately follows these tables, and the global robot is placed at the very end of the world file.

Boards

Each board begins with the following fields:

Notes

1. Boards in DOS MZX had a fixed buffer size of 10000 for each board plane. DOS MZX used the board mode field to determine what the maximum dimensions of the board were within the available space. MegaZeux 2.80+ ignores this field and uses the plane dimensions to to determine the board size.
   | Board Mode | Width | Height | |------------|-------|--------| | `0` | 60 | 166 | | `1` | 80 | 125 | | `2` | 100 | 100 | | `3` | 200 | 50 | | `4` | 400 | 25 |
2. If the second byte of the board non-zero, it is the lower byte of the level_id plane's width field. If this byte is 00, the board has an overlay and has the following extra field. As a consequence of this, saving a world with overlay disabled and a board width of 256 (which results in a lower byte of 00) in DOS MZX versions will generate a corrupt world and crash MZX. Port versions avoid this by incrementing the board width to a non-multiple of 256 when setting the board size in the editor.

Board RLE Planes

Board and overlay contents are compressed with run length encoding. Each board has either 6 or 8 planes (depending on whether the overlay is enabled), which immediately follow the mode fields and are stored in the following order:

Each compressed plane starts with the following fields:

The RLE data follows after. Values 0 through 127 represent a single literal value in the uncompressed data. If bit 7 is set, instead a run of length (byte & 127) should be filled with the next byte in the stream. The RLE plane can be decompressed with the following algorithm:

The RLE stream ends when (board width * board height) bytes have been expanded from the stream, and the next compressed plane or the board parameters block immediately follows.

Board Parameters (2.00 through 2.82X)

The board parameters block follows the board RLE planes. The following is the board parameters format for MZX versions prior to 2.83.

Board Parameters (2.83 and 2.84X)

The board parameters block follows the board RLE planes. The following is the board format for MZX versions 2.83 and 2.84X.

This block immediately follows the playing mod:

The following block is only present in save files.

The following block is in both world files and save files.

The final block is only present in save files.

Notes

1. Some MZX worlds created with an early alpha version of MZX 2.83 have boards parameters in the older format. Since these were saved with the MZX 2.83 world magic, they can't be loaded in newer versions of MZX, but they can be fixed by hex editing the magic from M\x02\x53 to M\x02\x52.

Board Objects

Following the board parameters are the robot, scroll, and sensor lists. Each list is stored as a single byte N indicating the number of robots, scrolls, or sensors on the board (0 to 255), followed by N stored objects of that type. Each object in its respective list immediately follows the prior, and the next list starts immediately following the last object in the previous list. The board data ends after all three lists and their objects have been read.

The board robots/scrolls/sensors in the list count from ID 1 upward, as ID 0 is the global robot and is invalid for scrolls and sensors. Since objects in the file are sequential, robot/scroll/sensor IDs may have to be reassigned when saving worlds or saves in these versions to optimize out gaps in the list.

Robots

Robots are stored in world/save files in the following format. Several of these fields are only used during runtime and thus initial values used when saving worlds are also listed.

Notes

1. DOS MZX versions wrote robot, scroll, and sensor structs directly to world or save files. The unused 2-byte field at offset 2 corresponds to the program memory pointer in these versions.
2. In DOS MZX versions from 2.69b to 2.70, the LOCAL2 counter was stored by using the robot walk direction as the upper byte and the robot locked status as the lower byte. Setting LOCAL2 had the side effects you would expect from modifying those variables.
3. In DOS MZX versions from 2.69b to 2.70, the LOCAL3 counter was stored by using the robot last touch direction as the upper byte and the robot last shot direction as the lower byte. Setting LOCAL3 had the side effects you would expect from modifying those variables.
4. The X/Y position variables are generally initialized to 0 in world files from DOS versions. Versions 2.80+ typically save the actual X and Y position in these variables in world files. The global robot is saved with the coordinates (-1,-1).
5. Robot statuses:
   | Status | Description | |--------|-------------| | 0 | Normal | 1 | Did not execute this cycle or only executed end, wait | 2 | Same as 1 but has also been sent a label
   When a robot's status is equal to 2, it will execute the label it was sent on reverse board scan. Every robot's status is reset to 0 at the start of each board cycle.
6. The local field in this block is completely ignored in versions 2.80+ and is saved in the robot save block instead. In versions prior to 2.51s1, this field existed but was not used.
7. The loopcount field in this block is completely ignored in 2.84X save files and is saved in the robot save block instead.

In save files from MegaZeux 2.80 and onward, an extra data block follows:

Notes

8. The loopcount field in this block was not present prior to 2.84 (i.e. the block started with the local counters instead and was 4 bytes shorter).

In both world and save files, the robot program immediately follows the above block(s). The size of the program in file is the same as the program length field in the robot data.

In older worlds, robots marked unused may have uninitialized memory saved where their program would usually go (the global robot from Slave Pit is an example). In this situation, the Robotic program should not be validated and should instead be ignored or replaced with FF 00.

Scrolls

Each scroll block is 7 bytes plus the length of the scroll text long.

Notes

1. The unused 2-byte field corresponds to the scroll text memory pointer in DOS versions of MZX.
2. The scroll text must begin with a 01 hex byte, must contain at least one line break (0A hex), and must be null terminated (i.e. the smallest valid scroll is 01 0A 00 with number of lines=1 and length=3).

Sensors

Each sensor block is 32 bytes long.

Files List

World and save files split their data into multiple internal files for modularization and to allow for compression of specific parts of the world data. The files supported by the world format and the order they are loaded in are as follows:

The board files (prefixed with b##) corresponding to a single board are all loaded before loading any files corresponding to the next board. The first ## in the names of these files is the board number in hex. Examples: b00 for the title board, b0A for board 10, bF9 for board 249 (the highest possible regular board number), and bFF for the special temporary board that may sometimes exist in save files. This number must be exactly two hex digits long.

Extra storage data for robots, scrolls, and sensors is stored in separate files. The file bXXrYY corresponds to the robot on board XX (hex) with the robot ID YY (also hex). Values from 01 (for robot 1) to FF (for robot 255) are valid. The same applies for scrolls and sensors. The robot/scroll/sensor must exist on the board for its corresponding properties file to be valid. These numbers must be exactly two hex digits long.

Filenames are case-insensitive. Prior to 2.93, they were case-sensitive and had to be all lowercase (aside from board/object numbers).

Properties Format

World, board, sprite, and object data are all stored in a simple extensible format created for MZX files similar to RIFF or a (very) simplified EBML. All internal files labeled "properties" use this format.

These files consist of an unspecified number of blocks of "properties" in the format:

Property data contents vary between different properties, so in the property list specifications the expected contents are explicitly defined. Most properties expect an int value and accept either 1 byte (equivalent to b), 2 bytes (w), or 4 bytes (ds) (expected size and signedness are explicitly noted). The next most common stored type is a variable length string with no null terminator (equivalent to s...). strings that are stored with null terminators are marked (with \0).

The file ends immediately when a property ID of 0x0000 is encountered indicating the end of the file. This value is the same for all different properties files. Unrecognized properties IDs are usually skipped unless noted otherwise. The EOF ID should always be present at the end of the file and there should be no data after the EOF ID.

It is possible to nest properties files to create a file with a more complex structure (though MZX currently does not do this).

World Properties

Global data is stored in a properties file for both world and save files. This is a common pattern in the new world format; save data is typically implemented as either extra properties only present in save files or (occasionally) as save-exclusive raw data files.

Unlike every other properties file in the format, the world properties file is very strict: every property expected for a particular file version must exist and must be in the order listed below. Also unlike other properties files in the world format, unrecognized properties in this file will usually generate an error. An integrity check is performed to enforce this early in the load process to determine whether or not the provided file is actually a world/save.

Additionally, compressing this file should be avoided, as it may be useful in the future for MZX to be able to peek at the contents of this file prior to initializing ZIP archive data structures.

1. World name maximum length is currently 24 characters; extra data will be ignored. Versions prior to 2.92d expect this field to be null terminated, and may leave parts of previous world names in the loaded name if it is not.
2. This field may be omitted. Valid output file mode values:
   | Value | Mode | |-------|--------------| | 0 | none/unknown | 1 | `w+b` | 2 | `r+b` | 3 | `a+b`
   Files opened in mode w+b should be reopened in mode r+b. The output file is currently write-only, so wb and ab are used in Robotic instead of w+b and a+b for now.

Status Counter Properties

Custom SFX Table

If this file is present, custom SFX will be enabled for the world. If this file is absent, custom SFX will be disabled.

In versions 2.93 and up, the sound effects are stored as a properties file with a 8-byte header:

This file is identical in format to the exported custom SFX file format, and files in 2.90+ world and save files can be used interchangeably with files created by SFX export.

Character Sets

The world character sets are saved as a single raw charset file. In 2.90+ saves and 2.91+ worlds, all 15 user charsets will be saved for a total size of 14*15*256 = 53760 bytes prior to compression. Worlds from MZX 2.90 will only save the main charset (for a total size of 3840 bytes).

Palettes, Palette Indices, and Palette Intensities

The world palettes are saved as raw palette files. In 2.93 and up, the file pal always contains the 16 color palette corresponding to MZX mode and SMZX mode 1. If SMZX modes 2 or 3 are active, an additional 256 color palette will be saved to palsmzx. If SMZX mode 3 is enabled, the palette indices will also be saved as a raw palette indices file in 2.90+ save files and 2.91+ world files.

In save files, the palette intensities are also saved. The file palint contains a raw array of 16 unsigned little endian dwords representing the MZX and SMZX mode 1 palette intensities. If SMZX modes 2 or 3 are active, an additional file palints containing the SMZX modes 2 and 3 will be saved. This file contains 256 unsigned little endian dwords.

Prior to 2.93

Only one pal and palint file were saved. These files always contained 256 entries, and always represented the current active screen mode. The palette intensities were stored as bytes, which corrupted larger intensity values.

In SMZX modes 2 and 3, the MZX palette and palette intensities were NOT saved. For worlds/saves from these versions with SMZX modes 2 or 3 active, the MZX palette should be derived from the first 16 entries of the SMZX palette (same as 2.84X and prior) and the MZX intensities should default to 100.

In 2.90X save files, the palette intensities file was stored using the internal indices order, and was incompatible with palette indices files. For each color, the two middle indices are in reverse order.

Vlayer Planes

The vlayer chars and colors planes are saved as raw data in two separate files in saves (2.90 and up) and world files (2.91 and up). These files are expected to be (vlayer_size) bytes long, where vlayer_size is specified in the world properties. If one of these files is missing, an error will be displayed and the plane will be zero-initialized.

Sprite Properties (.SAV only)

Sprite data is stored in a single properties file for all sprites with the following properties:

1. This property sets the sprite ID that all following individual sprite properties will be loaded to. This must be present before the properties of a given sprite for the sprite to be correctly loaded. All 256 sprites and their properties will typically be saved regardless of whether they have been used or not, which is why this file is compressed.
2. Sprite flags:
   | Flag | Description | |--------|-------------| | `0x01` | Sprite is initialized | `0x02` | Sprite ccheck 1 is enabled | `0x04` | Sprite is drawn over the overlay | `0x08` | Sprite uses reference colors | `0x10` | Sprite is static relative to the viewport | `0x20` | Sprite ccheck 2 is enabled | `0x40` | Sprite references the vlayer | `0x80` | Sprite is unbound | `0x100`| Sprite off-on-exit is enabled
   For unbound sprites, if both the ccheck 1 and ccheck 2 flags are set, sprite ccheck 3 is enabled instead.

Counter and String Lists (.SAV only)

The counter and string lists are packed in the same binary format they were in prior versions, each in their own file.

Counters List

The counter list file starts with the number of counters:

A list of N counter definitions follows:

Strings List

The string list file starts with the number of strings:

A list of N string definitions follows:

Board Properties

Board data is stored in a properties file with the following properties:

1. Properties marked "strict" must be present and in the order specified in the table for the board data to be considered valid. If the board properties file is invalid, the entire board contents will be dummied out. Properties marked "save-only" are saved to save files only, but will be respected if loaded from a world file. Properties marked "1.x only" are saved/loaded only if the world compatibility version is 1.x.
2. Board name maximum length is currently 24 characters; extra data will be ignored. Versions prior to 2.93 expect this field to be null terminated and may append garbage to the name if it is not.
3. This field exists mainly to provide redundancy for the .MZB file header. In world and save files, this field should be redundant with the file version field derived from the world or save magic.

Board Planes

Each board has 6 or 8 planes (depending on if overlay is enabled) saved in separate files as raw data of size (board width * board height) bytes each. If any of the expected planes are missing when loading a board, an error will display and the plane will be zero-initialized.

Robot Properties

Robot data is stored in a properties file with the following properties:

1. Properties marked "strict" must be present and in the order specified in the table for the robot data to be considered valid. Properties marked "save-only" are saved to save files only, but will be respected if loaded from a world file.
2. Robot name maximum length is currently 14 characters; extra data will be ignored. Versions prior to 2.92d expect this field to be exactly 15 bytes long and to contain a null terminator, and may behave unexpectedly if it does not.

Scroll Properties

Scroll data is stored in a properties file with the following properties:

Sensor Properties

Sensor data is stored in a properties file with the following properties:

1. Robot/sensor name maximum length is currently 14 characters; extra data will be ignored. Versions prior to 2.92d expect these fields to be exactly 15 bytes long and to contain a null terminator, and may behave unexpectedly if they do not.

Board Files for MegaZeux 1.x

A MegaZeux 1.x board file contains the raw data for a single board in the world format (including robots, scrolls, and sensors as-needed). These board files actually do NOT contain the above header; they begin exactly at the first RLE plane. See the world format documentation for boards for more info. A 25-byte null terminated board name follows the board data.

Board Files for 2.00 through 2.84X

The header is immediately followed by the raw data for a single board in the world format (including robots, scrolls, and sensors as-needed). See the world format documentation for boards for more info. A 25-byte null terminated board name follows the board data.

Board Files for 2.90 onward

The header is immediately followed by a ZIP archive containing the board properties, board planes, and object properties files for a single board. The following filenames are used:

MZM3

An MZM3 file begins with the following 20-byte header:

The world version is stored as a 2-byte little endian value where the upper byte is the major version number and the lower byte is the minor version number (like the world version field in the save format header). MZM3 files are forward compatible unless they contain robot information, in which case the robots in the MZM are replaced with customblocks.

The header is immediately followed by a board data block or a layer data block depending on the storage mode value indicated in the header.

Storage Mode 0 (Board)

The MZM data is stored in the following format if the "board" storage mode is selected. The data is composed of (width * height) blocks, where each block is 6 bytes and contains the following:

Signs, scrolls, sensors, players, and IDs >=128 will be replaced with spaces when an MZM is loaded. Robots in a board MZM require extra storage information.

When a board MZM is created from the overlay or vlayer, the ID is typically set to 5, the param to the char, the color to the color, and all other values are set to 0.

Storage Mode 1 (Layer)

The MZM data is stored in the following format if the "layer" storage mode is selected. The data is composed of (width * height) blocks, where each block is 2 bytes and contains the following:

Robot Data

MZMs using the "board" storage mode may additionally include a robot data block if the MZM board data contains robots. This block will always be located after the board data, and the format of this block is based on the MZX world format corresponding to the world version indicated in the header.

MZMs created in MZX 2.84X will contain N robot blocks as described in the 2.00 through 2.84X world format documentation. If this is a savegame MZM, the robots will be in the save format instead of the world format.

MZMs created in MZX 2.90 and onward will contain a ZIP archive after the board data containing N robot properties files named in the format r##, where ## is a hexadecimal number between 1 and 255 corresponding to a robot ID in the board data. If this is a savegame MZM, the robots will contain savegame properties.

MZM2

MZM2 was introduced in MegaZeux 2.80 and is essentially the same as MZM3 without the version field in the header. The MZM2 header is 16 bytes long:

The board data and robot data follows exactly as MZM3 with the exception that robots are always use the MZX 2.80 through 2.83 robot format rather than newer formats.

MZMX

MZMX is the original MZM format that was introduced in MZX 2.68. It is much more limited than newer MZM formats and is generally only supported for compatibility. MZMX only supports blocks with dimensions of 255 or smaller, does not save robots, and only supports storage mode 0. The MZMX header is 16 bytes long:

The board data follows as described by MZM3's Storage Mode 0.

Copyright © 2020-2023 Lachesis — https://github.com/AliceLR/megazeux/

Permission to use, copy, modify, and distribute this document for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE DOCUMENT IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS DOCUMENT INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS DOCUMENT.