Over the past thirty years, many ideas have been theorized and approaches tried with regards to extending and tweaking the behaviour and capabilities of the ZZT and Super ZZT game engines. With the release of the Reconstruction of ZZT greatly lowering the bar for creating such modified engine versions, the complexity and amount of forks, as well as interest in them, has begun to grow significantly. As such, in order to preserve to the extent possible the interoperability ZZT's ecosystem is known for, a standardized way to declare worlds which use or depend on extensions to the original ZZT and Super ZZT game engines is necessary.

A common format for declaring extensions will allow:

• Creating forks and source ports of ZZT which support a more complete set of the diversified (non-ZZT 3.2-strict) game world catalog,
• Mixing and matching extensions between forks at will,
• Broader editor support for handling extended worlds.

The game world types that the ZXT format considers are as follows:

• Creating completely custom experiences derived from ZZT or Super ZZT. Example: “The King in Yellow Borders”, WiL.
• Creating games which can benefit from enhanced functionality, but are playable in unmodified ZZT or Super ZZT engines. Example: “Variety”, WiL.
• Standardizing pre-fork games which modify ZZT or Super ZZT in an incompatible way. Example: “ZZT Enhancer”, Craig Boston; “Banana Quest”, WiL; 64K intros by bitbot.
• Standardizing pre-fork games which modify ZZT or Super ZZT in partially or fully compatible ways. Example: “Angelis Finale: Episode 1”, Commodore (custom character set); “Daedalus' Obelisk”, Darren Hewer (optional ZZT modification to remove certain sounds and messages).

These definitions may be used freely in extension standards without re-introduction.

• The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this and following documents are to be interpreted as described in RFC 2119.
• The following types, in data blob specifications, all little-endian (where applicable):
  • u8 - unsigned byte (8 bits),
  • s8 - signed byte,
  • u16 - unsigned word (2 bytes),
  • s16 - signed word,
  • u32 - unsigned dword (4 bytes),
  • s32 - signed dword,
  • u64 - unsigned qword (8 bytes),
  • s64 - signed qword,
  • bool - a special case of an u8, where zero means “false”, and non-zero means “true”,
  • pstring[X] - a Pascal-style string; a length u8 (N, of range between 0 and X) followed by X characters, of which the first N are considered valid.
  • pstring - a Pascal-style string; a length u8 (N, of range between 0 and 255) followed by N characters.
  • plstring - a Pascal-style long string; a length u16 (N, of range between 0 and 65535) followed by N characters.

Things marked “COMMENT:” below are “non-normative” and are not considered a part of the specification.

The extension data can be provided in one of two ways:

• Providing a .ZAX file with the same filename as a world file (for instance, TOWN.ZZT and TOWN.ZAX) or board file, containing only the Extension Header.
• Providing a .ZXT file, being formed as a concatenation of an Extension Header and a world file (cat TOWN.ZAX TOWN.ZZT > TOWN.ZXT is a valid operation) or board file.

This is done because neither solution is strictly superior:

• .ZAX files can be used to extend games with additional functionality (keybind shortcuts, metadata, etc.) without the need to distribute a modified .ZZT file.
• A .ZXT file cannot be understood by unmodified versions of ZZT or Super ZZT, which would require ZZT-compatible games making use of extensions to distribute two variants - a .ZZT and a .ZXT.
• Distributing the world as a single .ZXT allows for greater user-friendliness than having to carry around two files, especially for non-ZZT-compatible worlds.

Notably, this does not cover save files. Saves are NOT guaranteed by the specification to be interchangeable between different implementations of the engine. (However, the authors expect a lot of implementations to simply follow ZZT's lead in terms of SAV files being valid ZXT files.)

The extension header's format is as follows:

After the header follow block_count extension blocks, in sequence:

An extension being “understood” is defined as one for whose ID pair the engine provides an implementation compliant with its standard.

The extension flags are as follows:

It is important to note that the flags can be distinct from the ID pair; for instance, the same ZZT-OOP extension can be defined as “recommended for playing” if optional for gameplay, but “mandatory for playing” if required for gameplay. However, an extension standard may require you to set or clear certain bits.

• Extension Order: Extensions MAY depend on their order of definition in the file. Implementations MUST, as such, preserve the order of extension definition when writing a ZXT file.
• Repeated Extensions: Extensions MAY allow being defined multiple times within a single list of extension blocks. However, if an extension does not specify behaviour in this event, the engine's reaction is undefined.

Any interactions not listed above are undefined behaviour and MUST NOT be relied upon. Here's an example scenario:

• One extension is defined as “increasing the number of Keys from 7 to 16”,
• Another extension is defined as “redefining the Keys to allow holding multiple at a time”,
• It is not certain what should happen if both extensions are in place, unless additional detail is provided. One could interpret it as only allowing the seven vanilla ZZT Keys to be held multiple at a time, or as allowing all sixteen to do so.

• Header/Data Expansion: If an extension extends the board header, the world header, the tile data, the stat data, or any other existing in-file structure outside of the extension block, the order of parsing MUST be in ascending order of the 32-bit owner ID, then the 16-bit selector ID.
• Incompatible Format Changes:
  • If any change which sets the reading_must flag to 1 is present, the implementation SHOULD set the world ID to 0xE227. Rare omissions are permitted, if the set of world format changes corresponds 1:1 to another non-standard world format ID (such as FreeZZT) - however, the list of extensions MUST reflect the same format changes. Extensions derive only from ZZT and Super ZZT's vanilla world formats.
  • If a ZXT or ZAX file is present, the implementation MUST ignore the world ID present in the file itself, and trust the ZXT/ZAX file instead.

• The range 00000000 - 000000FF is reserved for standard extensions - expansions to this standard, as well as potential “obvious” changes everyone agrees upon.
• The range FFFFF000 - FFFFFFFF is reserved for private extensions - usage when a standard for a given extension is not yet defined, or for internal/private experiments. Publicly released worlds SHOULD NOT use this range.

• Compliance in the context of ZXT support concerns only the game engine's operation. The user interface and other external factors not impacting gameplay or game presentation are not in scope.
• An implementation MAY only be compatible with ZXT worlds containing certain extensions. Compatibility with un-extended ZZT 3.2 worlds is not a requirement.

• An implementation consuming a .ZXT world, or a world with a .ZAX file, MUST NOT be expected to preserve ZZT's memory or stack layout exactly when running on a ZXT-compliant implementation.
  • Most out-of-bounds memory reads and writes, as such, are not guaranteed to work correctly.
  • The argTile2 trick pioneered in “Wake Up and Unlock The Door” counts as reliance on stack layout.
  • If you're relying on such behaviours, consider making an extension standard for it instead!
• Certain behaviours have been grandfathered due to widespread usage pre-Reconstruction of ZZT. Extensions may change or disable their emulation. These are listed below:
  • Implementations MUST emulate the Black Key. The behaviour, including the gem value change and the message duration, MUST be preserved, although the specific text message emitted MAY be changed.
  • Implementations MUST support reading the state of stat -1. While the state of stat -1 in ZZT may change in rare circumstances, it is recommended to assume the following values:

• A .ZXT world, or a world with a .ZAX file, MUST treat any feature which crashes regular ZZT (or causes double-frees, particularly double #BIND) as undefined behaviour, unless an extension states otherwise.
  • That is to say, ZXT-compliant implementations are free to fix them or not.

These questions/concerns must be decided upon before the specification is finalized.

1. Should extension definitions allow depending on their order of placement within the ZXT extension data list? This will complicate implementation, but allow additional flexibility. YES
2. Should extension definitions allow for the same extension to be present multiple times in the same file? This will complicate implementation, but allow additional flexibility. YES
3. Should there be any considerations on preserving extension information as part of save files? THE SPEC DOES NOT REGULATE SAVE FILES
   • Defining save files as implementation-specific is the easy way out and handy for some use-cases, but hinders save cross-compatibility and loading saves as game worlds in the editor.
   • Low-memory platforms may be hindered by requiring to load a lot of unnecessary extension data and keep it in memory. (For example, character sets.)
     • However, so long as the complete data is unnecessary to play the world, does it really hurt a save file?
     • Maybe we could allow a save file to be augmented with a .ZXT or .ZAX to restore blocks which are missing?
       • This would be best done with a “playing_mutates” bit - if it is 0, the extension could plausibly be restored from the original .ZXT file.
   • The compromise route, with no clear drawbacks, is to define save file rules as a SHOULD but not a MUST, allowing implementation-specific variants but encouraging a route for typical implementations.
4. The use-case of ZAXes was defined as being strictly for worlds whose .ZZT file is compatible with ZZT 3.2. However, zzo38 pointed out that he'd prefer to use ZAXes even for worlds incompatible with ZZT 3.2. Should the ZXT format reserve magic world IDs for this scenario? PROPOSAL A
   • Proposal A:
     • Define a world ID (f.e. 0xE227) which means “this world file requires a ZXT header or ZAX file to be correctly parsed”,
     • Implementations must ignore the world ID if ZXT/ZAX information is present.
     • The drawback is that using a valid, but incorrect ZAX will break loading… but a valid, but incorrect ZAX is possible anyway (OOP changes, element changes, etc).
   • Proposal B:
     • Allow extensions to define acceptable world IDs.
     • Drawback: doesn't handle multiple world format changes
5. How should extensions changing the world format (board header, world header, etc.) be handled?
   • Proposal A: In order of definition (see “allowing depending on order of placement”)
   • Proposal B: In ascending order of extension IDs
6. Should there be more or fewer restrictions with regards to ZZT 3.2 behaviours allowed for a ZXT/ZAX-utilizing world? LOTS OF TWEAKS
   • The current ones are solely to not force implementations to emulate the entire ZZT 3.2 data segment; while Roton (commendably) tries to do it, it is a very large amount of effort that is also difficult to accomplish efficiently on some lower-end platforms.
7. How should boards be prefixed? They can be of any size and don't have a magic number.
   • Proposal A: Boards are not defined by the standard.
     • Super ZZT and ZZT .BRD files use the same extension, but are not interchangeable. This wouldn't be new…
   • Proposal B: ZXT Boards start with two “0” bytes (a length of 0), immediately followed by the 0xB227 magic. A bit clunky, though…
8. Which extensions should be stored as part of a .BRD file? How to handle conflicts on import/export? Do we need a new flag to check if an extension applies to a board's format?
9. Should the specification make it clear that preference goes from last (most preferred) to first (least preferred) extension? (Think extensions which overwrite the same thing, but in increasingly more complex ways. For example, sound replacement could go from #PLAY → FM data → MIDI, or something.)

As the specification has not been finalized, no such implementations exist yet.

• ZXTMGR (Pascal, Zero Clause BSD)
• zxtsplit (C, public domain)