D 2018-08-18T06:14:28.371
L Level\sfile\sformat
P e64a2af24373463e763280f11aaeee4ab05a5457
U zzo38
W 5003
This document describes the file format for level files. The .level file is a [Hamster archive], containing lumps <tt>CLASS.DEF</tt>, <tt>*.LVL</tt>, and <tt>LEVEL.IDX</tt>. All numbers (except the lump sizes) are small-endian.
<h2>CLASS.DEF</h2>
This lump consists of two parts, which are the list of classes and list of user messages; two zero bytes come after the list of classes before the list of user messages.
Each part consists of zero or more records concatenated together. Each record consists of a 16-bit number and then a null-terminated string.
The class section has class numbers (minimum 1) and class names (without the <tt>$</tt> prefix). The user message section has user message numbers (minimum 256) and user message names (without the <tt>#</tt> prefix).
This data is used to determine what class/message the level data refers to, since reordering them in the class definition file may cause them to be internally renumbered, so in this way, first the CLASS.DEF lump is read in order to define the numbers before reading the class definition file, so only the class names that aren't mentioned in the level file will be auto-numbered, and then recorded in the CLASS.DEF lump once an object of that class is added to a level using the level editor.
<h2>*.LVL</h2>
The lump name starts with the zero-based ID number (instead of an asterisk), which must be from 0 to 65535.
The header of this lump consists of:
* Level version (16-bits): Used to invalidate solutions when the level is altered.
* Level code (16-bits): The <tt>Level</tt> command in class codes read this parameter.
* Playfield width (8-bits): This is a number from 0 to 63, which is one less than the playfield width for this level.
* Playfield height (8-bits): This is a number from 0 to 63, which is one less than the playfield height for this level.
* Title (var): A null-terminated level title text, which may include formatting controls.
After that comes the objects. They should be in order starting at (1,1) and going right, going to the next line after that; within each cell, they go bottom (most density) to top (least density). Each object record consists of:
* Flag byte: Described below.
* X coordinate (1 byte): Only present if bit5 of flag byte is set. Coordinates are 1-based.
* Y coordinate (1 byte): Only present if bit4 of flag byte is set. Coordinates are 1-based.
* Class number (2 bytes): The high bit is not part of the class number; if the high bit is set, use the default image number instead of the one in the next byte. The class and image number are not present if bit7 of the flag byte is set.
* Image number (1 byte): See above.
* Data types (1 byte): Present only if bit3 of flag byte is set, and not for MRU.
* Misc data (var): Depends on data types.
Normal flag byte:
* bit7 = Clear (indicates not MRU)
* bit6 = Increment X
* bit5 = Has X coordinate
* bit4 = Has Y coordinate
* bit3 = Has misc data
* bit2-bit0 = Direction
MRU flag byte:
* bit7 = Set (indicates MRU)
* bit6 = Increment X
* bit5 = Has X coordinate
* bit4 = Has Y coordinate
* bit3-bit0 = Repeat count
Either way, bit6 and bit5 should not both be set together. Also, if bit4 is not set for the first object, the Y coordinate is 1, and if bit5 is not set for the first object, the X coordinate is 0 (which is not a valid coordinate, unless bit6 is also set).
The MRU has two layers, one for the bottom object and one for the object directly above the bottom object. All data other than the coordinates are stored in the MRU. Objects above the second one are not stored in MRU. If the repeat count is nonzero, then in addition to the current cell, further cells to the right copy it too (this is only applicable for the bottom layer), leaving the cursor on the rightmost cell that has been written to.
The data type byte consists of:
* bit7-bit6 = Indicate which parameters are set. 0=Misc2 and Misc3, 1=Misc1, 2=Misc1 and Misc2, 3=Misc1 and Misc2 and Misc3.
* bit5-bit4 = Data type of Misc3. 0=number, 1=class, 2=message, 3=string. (Directions and key codes also use type 0.)
* bit3-bit2 = Data type of Misc2.
* bit1-bit0 = Data type of Misc1.
After the data type byte will be the misc data; any misc data not defined implicitly has a value of zero. The data is represented as a 16-bit number, in order Misc1, Misc2, Misc3, whichever are present (as specified above).
(Note: In EKS Hero Mesh the data type is used only in the editor. In Free Hero Mesh, data is strongly typed and so the data type is used at run time too.)
After the objects is a byte with value 0xFF to indicate there are no more objects, and then the level strings (if any). The level strings are simply null-terminated strings (which can include formatting controls).
<h2>LEVEL.IDX</h2>
This lump contains a series of 16-bit numbers, which are the ID numbers of the levels, in the display order.
Z 32de6723f68b267b5b5bbb1c92e3dc72