Free Hero Mesh

Free Hero Mesh, which can be used by multiple files.

game.c: The game play. The game behaviour is implemented in exec.c; this
one just handles the input and display, and solution replay, and any move
which is made calls exec.c to execute the mode. It contains one function
(locate_me) which is called by exec.c.

instruc,instruc.h,instruc.js: The "instruc" file contains a list of the
keywords and internal operator names used in the class definitions. Some
of these are only used internally, although most are available directly
as keywords. Many are also opcodes in the compiled P-code, although some
are only used as keywords, which are handled during class loading. The
instruc.js program generates instruc.h from instruc.

keyicons.xbm: Graphics for key icons. These are used to display the replay

picedit.c: The picture editor.

picture.c: Contains initialization of graphics, and everything to draw
graphics on the screen, including icons and text. It also contains the
code for loading icons, for displaying popup messages, and scrollbars.
Loading fonts for code pages are also included in this file.

quarks,quarks.h,quarks.js: The "quarks" file contains names of predefined
quarks for use with the resource manager. The quarks.js program converts
quarks into quarks.h.

smallxrm.c,smallxrm.h: An implementation of the X resource manager. This
can be used independently from Free Hero Mesh.

sound.c: Implements sound effects. Also deals with loading sound effects,
amplification, MML, etc.


=== Invariants ===

=== Miscellaneous ===

Free Hero Mesh uses the PC character set. All contributions shall use this
character set (of which ASCII is a subset). (Exception: Documentation
written in languages other than English may use whatever character set is
appropriate for that document.)

See internals.doc for some details about internal working.

* TY_CODE: Currently only used in case blocks; there are no values of this
type in local or global variables.

* Numbers more than TY_MAXTYPE (15) means it is a generation number of an
object, and u is the index number of that object. In the internal code,
VOIDLINK means no object; this is represented in a Value structure as
t=0 (TY_NUMBER) and u=0. (Generation numbers are internally used so that
it can detect invalid references; once a reference becomes invalid, it
can never become valid again.)


=== Opcodes ===

The opcodes in the P-code are 16-bit unsigned integers. The numbers are
arranged as follows (giving ranges in hex):

The numbers of individual opcodes (with OP_ names) are not guaranteed to
remain the same between versions of Free Hero Mesh; they often change.

Some of these numbers, including the OP_ constants, are also used during
parsing; some of them occur only as tokens and not in the compiled P-code,
and some only occur in the compiled P-code and not as tokens.


=== Text encoding ===

The control codes for text formatting are:

1-8 (\0-\7) = Colours
10 (\n) = Line break
11 (\l) = Left
12 (\c) = Centre
14 (\i) = Icon
15 (\b) = Horizontal rule
16 (\q) = Quiz button
30 (\d) = Data
31 (\x) = Next byte is a character to display as graphic

Codes 32-255 are displayed as is, but characters 1-31 cannot be displayed
as a graphic unless a \x escape is present.


=== Solution format ===

The .SOL lumps have the following format:

* Level version number (16-bits small-endian): If this does not match the
level version number in the .LVL lump, then the solution is considered to
be invalid.

* Flags (8-bits): Specifies which other fields are present.

* Comment (null-terminated; only present if flag bit0 set): Normally
contains a user name, but may be any arbitrary text.

* Timestamp (64-bits small-endian; only present if flag bit1 set): The
UNIX timestamp when the solution was recorded.

* Move list: One byte per turn, being the key codes. (Use of numbers 0-7
here is reserved for future use; they are not valid key codes.)

(Free Hero Mesh currently ignores the comment and time stamp, although
this might change in a future version of Free Hero Mesh.)