User Tools

Site Tools


zxt:format_specification

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
zxt:format_specification [2021/08/06 08:09] asiezxt:format_specification [2021/08/11 06:21] (current) – Use propagating tag for ZAXMAKE/ZXTSPLIT links, instead of single version link. The propagation can be cancelled (even retroactively if needed) if changes are made that violate this specification. zzo38
Line 1: Line 1:
-====== ZXT Extended World Format ======+====== ZXT Extension Format Specification ======
  
-Version 0.XX+Version 1.0.0
  
-The specification follows a MAJOR.MINOR numbering scheme.+By Adrian "asie" Siekierka 
 + 
 +Special thanks: endgame, GreaseMonkey, Lancer-X, Noser, The Mysterious KM, WiL, zzo38 
 + 
 +The specification follows a MAJOR.MINOR.PATCH numbering scheme, where: 
 + 
 +  * Changes to the MAJOR number are expected to introduce breaking changes, resulting in a change of the extension header magic number; 
 +  * Changes to the MINOR number are expected to introduce changes which don't break backwards compatibility, such as giving meaning to reserved values or defining undefined behaviour; 
 +  * Changes to the PATCH number are expected to introduce changes which don't impact the meaning of the specification, such as fixing typos or clarifying used language. 
 +  
 +For example, a ZXT 1.1.x world which doesn't utilize functionality specific to ZXT 1.1.x would be expected to work as-is in a ZXT 1.0.x engine implementation; there is no such requirement placed on a ZXT 2.0.x world.
  
 ===== Introduction ===== ===== Introduction =====
  
-Extending and tweaking the functionality of the ZZT game engines ((ZZT and Super ZZT)) has always been an undercurrent in its world development community. While many games relying on edited executables or TSRs ((Terminate-Stay Resident programs)) have been released in the past, they ran into key problems, keeping their count small and the idea unpopular:+Extending and tweaking the functionality of the ZZT game engines ((ZZT and Super ZZT)) has always been an undercurrent in their world development community. While many games relying on edited executables or TSRs ((Terminate-Stay Resident programs)) have been released in the past, they ran into key problems, keeping their count small and the overall idea unpopular:
  
   * The lack of source code greatly increased the difficulty of performing non-trivial modifications.   * The lack of source code greatly increased the difficulty of performing non-trivial modifications.
-  * The requirement for special batch scripts or modified executables, typically made specifically for a given game, created additional hassle for the end user.+  * The requirement for special batch scripts or modified executables, typically made specifically for a given game, created additional hassle for the end user when trying to play such a game.
   * No consistent means of signaling required extensions was devised. For most worlds, this made them indistinguishable from ZZT 3.2-compatible ones for the end user or reimplementations, hurting compatibility.   * No consistent means of signaling required extensions was devised. For most worlds, this made them indistinguishable from ZZT 3.2-compatible ones for the end user or reimplementations, hurting compatibility.
  
Line 38: Line 48:
 Notably, the specification currently does **NOT** cover: Notably, the specification currently does **NOT** cover:
  
-  * The format of save (.SAV) files. While the creators suppose that many implementations will share the code for creating world files and save files, as ZZT itself does, we have decided not to mandate this at this time.+  * The format of save (.SAV) files. We have decided not to mandate this at this time.
   * The format of board (.BRD) files. This is due to the niche nature of the subject, and is likely to be expanded upon in a future version of the specification.   * The format of board (.BRD) files. This is due to the niche nature of the subject, and is likely to be expanded upon in a future version of the specification.
  
Line 60: Line 70:
     * **plstring** - a Pascal-style long string; a length u16 (N, of range between 0 and 65535) 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.+Where the specification mentions the terms **ZZT game engine** or **.ZZT**, one may substitute **Super ZZT game engine** and **.SZT** respectively.
  
 ===== File Format ===== ===== File Format =====
Line 75: Line 85:
   * The intent of .ZAX files is to extend games with additional functionality (keybind shortcuts, metadata, etc.), while preserving compatibility with the ZZT game engine. (They can also serve as patches on top of an otherwise unmodified .ZZT file.)   * The intent of .ZAX files is to extend games with additional functionality (keybind shortcuts, metadata, etc.), while preserving compatibility with the ZZT game engine. (They can also serve as patches on top of an otherwise unmodified .ZZT file.)
   * The intent of .ZXT files is to contain a modified ZZT game within one world file. This is especially useful for games which cannot be supported by unmodified versions of the ZZT game engine.   * The intent of .ZXT files is to contain a modified ZZT game within one world file. This is especially useful for games which cannot be supported by unmodified versions of the ZZT game engine.
 +
 +If a .ZXT file is being loaded, a .ZAX file should be ignored - .ZAX files apply for .ZZT files, not .ZXT files.
 +
 +The behaviour of multiple concatenated extension headers contained within one .ZXT or .ZAX file is undefined; distributed .ZXT or .ZAX files MUST NOT rely on it.
  
 ==== Extension Header ==== ==== Extension Header ====
Line 88: Line 102:
 ^ Offset ^ Type ^ Name ^ Description ^ ^ Offset ^ Type ^ Name ^ Description ^
 | 0 | u16 | flags | Extension flags; defined below. | | 0 | u16 | flags | Extension flags; defined below. |
-| 2 | u32 | owner_id | Extension owner ID | +| 2 | u32 | owner_id | Extension owner ID
-| 6 | u16 | selector_id | Extension selector ID | +| 6 | u16 | selector_id | Extension selector ID
-| 8 | u8 | reserved_0 | Reserved. | +| 8 | u8 | reserved_0 | Reserved; must be set to 0. | 
-| 9 | u16 | field_length | Field length. Can be between 0 and 65534; if set to 65535, an u32 containing the 32-bit field length follows. |+| 9 | u16 | field_length | Field length. Values between 0 and 65534 refer to the length in bytes; if set to 65535, an u32 containing the 32-bit field length in bytes follows. |
 | 11 | u8[field_length] | field_data | Field data. Extension-defined. | | 11 | u8[field_length] | field_data | Field data. Extension-defined. |
  
Line 109: Line 123:
 | 8 .. 15 | reserved | Reserved. | If set, an implementation MUST NOT continue parsing of the extension block. | | | 8 .. 15 | reserved | Reserved. | If set, an implementation MUST NOT continue parsing of the extension block. | |
  
-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.+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 for compliance.
  
 ===== Extension IDs ===== ===== Extension IDs =====
  
-Extension IDs are allocated on a per-owner ID basis.+Extension IDs are allocated on a per-owner ID basis. Within one owner ID, selector IDs SHOULD be used in a "one per extension" manner.
  
 ==== Owner ID Ranges ==== ==== Owner ID Ranges ====
  
-  * The range ''00000000'' - ''000000FF'' is reserved for **standard extensions** - potential "obvious" changes everyone agrees upon, as well as potential expansions to this standard.+  * The range ''00000000'' - ''000000FF'' is reserved for **standard extensions** - types of changes everyone agrees upon, as well as potential expansions to this standard.
   * The range ''00000100'' - ''FFFFFEFF'' is available for **public extensions** - you are free to claim them via signaling intent on the [[zxt:owner_ids|ZXT Owner IDs]] page.   * The range ''00000100'' - ''FFFFFEFF'' is available for **public extensions** - you are free to claim them via signaling intent on the [[zxt:owner_ids|ZXT Owner IDs]] page.
-  * The range ''FFFFFF00'' - ''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.+  * The range ''FFFFFF00'' - ''FFFFFFFF'' is reserved for **private use extensions** - prototypes and/or experiments within internal/development versions of worlds and engine implementations. Publicly released worlds and engine implementations SHOULD NOT use this range.
  
 ===== Interactions ===== ===== Interactions =====
Line 144: Line 158:
  
   * ZXT standard compliance concerns only the game engine's operation. The user interface and other external factors not impacting gameplay or game presentation are not in scope.   * ZXT standard compliance 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 choose to be compatible only with ZXT worlds containing certain extensions. Compatibility with un-extended ZZT worlds is OPTIONAL.+  * An implementation MAY choose to be compatible only with ZXT worlds containing certain extensions. Compatibility with un-extended ZZT worlds for a ZXT implementation is OPTIONAL.
  
 ==== Engine Accuracy ==== ==== Engine Accuracy ====
Line 176: Line 190:
 This is not a formal part of the specification - it's more of an "advice" section. This is not a formal part of the specification - it's more of an "advice" section.
  
-==== For world developers ====+==== World Developers ====
  
   * 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.   * 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.
Line 183: Line 197:
     * The argTile2 trick pioneered in “Wake Up and Unlock The Door".     * The argTile2 trick pioneered in “Wake Up and Unlock The Door".
  
-==== For engine developers ====+==== Extension Specification Authors ==== 
 + 
 +  * As soon as your extension is used by publicly-released worlds or implemented in publicly-released implementations, the expectation is for it not to change in a breaking manner! While undefined or explicitly reserved behaviour may be clarified further, breaking changes should be introduced via new extensions. There are two ways to avoid that issue during development: 
 +    * Use an ID inside the area of private use extensions while the extension's shape is not yet fully formed, 
 +    * Mark your public specification as "Draft" while details are not fully decided upon. 
 +  * If your extension is intended to work only with ZZT or Super ZZT, but not the other, it's a good idea to mention that explicitly in the specification. 
 + 
 +==== Engine Developers ==== 
 + 
 +  * Not every ZXT-compliant engine implementation must provide every extension! Don't fall neck-deep into code bloat, especially on your first try. Focus on the ones you care about, or which games you enjoy utilize. 
 +  * Remember that your save files need to be aware of which extensions ought to be enabled in order to correctly restore a gameplay session. An easy way for this is to do what ZZT itself does, and share the code for creating world files and save files. 
 + 
 +===== Side Notes ===== 
 + 
 +This is not a formal part of the specification - rather, it provides insight into some contested decisions. 
 + 
 +  * I am aware that the "owner/selector ID" system is not ideal. However, other alternatives considered had flaws deemed more important: 
 +    * A linear ID allocation system would most likely cause conflicts; 
 +    * A string-based ID system would increase implementation difficult, particularly on older compilers; 
 +    * The owner/selector divide was introduced after the decision to faciliate 48-bit IDs on older compilers, particularly Turbo Pascal. While 32-bit IDs were considered, they were rejected as potentially being too constraining. 
 +  * Save files are not mandated by the specification for two key reasons: 
 +    * Some extensions may require data specific to save files, and implementations may wish to have the freedom to decide how to store them in this case; 
 +    * Some implementations may store ZZT data in a custom format internally, and removing this requirement can make their code simpler. 
 +  * Multiple concatenated extension headers may be used as a feature in the future - for example, for faciliating multi-patch application for ZZT worlds.
  
 ===== Implementations ===== ===== Implementations =====
 +
 +This is not a formal part of the specification.
 +
 +==== Libraries ====
 +
 +=== ZXT 1.0.x ===
 +
 +  * [[https://github.com/OpenZoo/ClassicZoo/blob/0b39c34b2437f5e73b3601044545cefa586cf5dc/SRC/ZXTMGR.PAS|ZXTMGR v0.3.1]] - Turbo Pascal 5.5-compatible library, intended for using within a ZZT fork.
 +
 +==== Tools ====
 +
 +=== ZXT 1.0.x ===
 +
 +  * [[http://zzo38computer.org/fossil/freezzt.ui/dir?ci=zxt1.0&name=zxt|ZAXMAKE]], PostScript tooling for defining ZXT extension headers.
 +  * [[http://zzo38computer.org/fossil/freezzt.ui/dir?ci=zxt1.0&name=zxt|ZXTSPLIT]], C utility for extraction, listing and maintenance of ZXT/ZAX files.
 +
 +==== Engines ====
  
 TBD TBD
zxt/format_specification.1628237373.txt.gz · Last modified: 2021/08/06 08:09 by asie