puzzleset.doc

This file describes what files make up a puzzle set.

A Free Hero Mesh puzzle set consists of four files, each with the same
base name, but with a different suffix to identify its type:

 .xclass     -  Class resource file
 .class      -  Class definition file
 .level      -  Level file
 .solution   -  Solution file

The files can be renamed, as long as all of them have the same base
suffixes that they originally had, and the new base names are the same
as each other for each of the four files. Symlinks are also OK, e.g. if
multiple puzzle sets share the same class definitions, or if you want to
deal with multiple solution sets.

The class definition file is a plain text file, and you are expected to
edit it using any text editor. The other three files are Hamster archives,
and are normally written by Free Hero Mesh, so you do not need to tamper
with the internal contents of those files by yourself. You may extract and
insert parts of the Hamster archives if you are careful; the descriptions
below mention what each lump means.

A puzzle set may also be a "composite puzzle set"; see the below section
for information about composite puzzle sets.

(A "Hamster archive" consists of zero or more lumps, where each lump
consists of a null-terminated ASCII file name, the 32-bit PDP-endian data
size, and then the data.)


=== Class resource file ===

This file contains pictures and sounds associated with the puzzle set.
Nothing in this file affects the behaviour of the game, so you can safely
replace it with a different set of pictures/sounds if wanted.

The IMG lumps are the pictures. Each one may store multiple versions of a
picture; the loader will select one based on the user's criteria.

The DEP lumps are dependent pictures; each one references one or more IMG
lumps, and specifies how to modify them to produce the new picture (e.g.
by rotating, mirroring, changing colours, etc).

The WAV lumps are sound effects. Each one must be a RIFF WAVE file with a
type that can be loaded by SDL (PCM, MS-ADPCM, or IMA-ADPCM).

The PICEDIT.CFG lump stores the configuration for the picture editor. It
can safely be deleted if not needed.


=== Class definition file ===

This file is a plain text file which defines the classes of objects which
are used in the game. See class.doc for details of its format.


=== Level file ===

This file stores the levels in this puzzle set.

The CLASS.DEF lump associates class names and message names; the LVL lumps
then refer to the classes/messages by the numbers given here. This means
that if you want to copy the lumps, you must ensure this matches, or else
the resulting file will be incorrect.

The LVL lumps store the data of each level; they are named by the ID
number of the level. Each level consists of the grid of objects (which
may have parameters), the level code number (an extra value that you can
use for your own use in class codes), the level version number (used to
quickly invalidate solutions), the title text, and any level strings which
are used by objects of this level (there might not be any).

The LEVEL.IDX lump stores the level index. It consists of a series of
small-endian 16-bit level ID numbers, with no duplicates. The order of
the levels will be the order listed here.

It is not recommended to tamper with this file without using Free Hero
Mesh, due to the lumps depending on each other. If you wish to copy a
level, or convert levels using your own programs, using the level export
format is recommended (unfortunately, this is not implemented yet).
However, you can safely create a puzzle set with a subset of levels by
copying the lumps, and following the instructions above.


=== Solution file ===

This file stores the recorded solutions of each level. It may be empty if
no solutions are recorded, but it must exist for the game to work.

Each SOL lump stores the solution for the level with the ID number given
in the lump name. It also records the level version, as a check that the
solution is valid.

The solution file is also used for autotesting. In this case, the solution
of each level is executed, and it ensures that a win occurs during the
final turn, and not before. (A puzzle set catalog service may perhaps use
this in order to verify that the puzzles are solvable.)


=== Composite puzzle set ===

A composite puzzle set can have any file name, and is a Hamster archive
containing at least four lumps. The main four lumps have the same contents
as the four main files of a non-composite puzzle set, and their names must
have the correct suffix, although the part of the name before the first
dot can be anything that does not itself have a dot (it is not required to
match the file name of the composite puzzle set, and may be empty).

A composite puzzle set is always read-only. If you wish to modify it, you
must extract them as separate files.

There are other optional lumps, as follows:

* FILE_ID.DIZ: Contains a plain ASCII text description of this puzzle set.
Should have up to nine lines each no longer than 45 ASCII characters, and
the first line is a title of the puzzle set.

(Others may be added later, such as optional compression.)