** Hero Mesh File Format **

This describes the file format of the Windows version of Hero Mesh. (Free
Hero Mesh uses a different file format described in a different file.)

All numbers are small-endian and unsigned. WORD is 16-bits, and DWORD is
32-bits, and BYTE is 8-bits.


=== Header ===

At the beginning of the file is the following:

Offset  Type      Description
0       WORD      File version
2       CHAR(4)   ASCII characters "MESH"
6       DWORD     Puzzle set number
10      WORD      Number of picture sizes
12      WORD(8)   Picture sizes
28      WORD      Number of words in picture allocation table

File version is 15 for Hero Mesh version 1.1c, and is 16 for Hero Mesh
version 2.0. Other versions (if any) are unknown. The rest of this
document is applicable to file version 16 (differences, if any, are
unknown; file version 15 does not seem to have any differences as far as
I can tell).

Puzzle set number is a number that can be read by the class codes but
otherwise does nothing. It is used by the Hero Hearts puzzle sets to
determine which puzzle set to link to after completing the last level.

The picture sizes are all square; the numbers given are the width (which
is equal to the height) of that picture size. For example, if it says 24
then the pictures are 24x24.

After this comes the picture allocation table, which specifies which
pictures are allocated. The first word of the allocation table is for the
first sixteen pictures; the low bit is for the first picture, and the high
bit is for the sixteenth picture.


=== Pictures ===

Picture data comes next. The encoding is like this C code:

  // nsizes = number of picture sizes (1 to 8; normally 3)
  // nalloc = number of words in picture allocation table
  // sizes[s] = width or height of picture size s (where s is 0 to 7)
  for(s=0;s<nsizes;s++) {
    for(i=0;i<nalloc;i++) {
      for(y=0;y<sizes[s];y++) {
        for(j=0;j<16;j++) {
          @< Read (sizes[s]) bytes from file into
             scanline y of size s of picture 16*i+j
             (one byte per pixel; zero = transparent) @>
        }
      }
    }
  }
  // Unallocated pictures are still read, even though they aren't used.

(This may also be considered as one large picture per size; where the
pictures are tile sets with sixteen tiles across.)

Next comes the picture availability table, which controls which pictures
are available for selection in the level editor. There are always 512
bytes, one byte per picture. The byte value is 1 if it is available or 0
if it is not available.


=== User Message Table ===

Next is the user message table. It starts with a WORD which is the number
of user messages. User message numbers start with 20; messages 0 to 19 are
the built-in messages. For each user message there is a BYTE giving the
length of the message name, followed by the message name. (There seems to
be always one extra message name at the end which is blank and is unused.
The reason for this is currently unknown.) If the name is empty then that
user message does not exist (it may have been deleted).

The standard messages are as follows:
 0 = INIT
 1 = CREATE
 2 = DESTROY
 3 = BEGIN_TURN
 4 = ARRIVED
 5 = DEPARTED
 6 = LASTIMAGE
 7 = MOVED
 8 = JUMPED
 9 = KEY
 10 = MOVING
 11 = SUNK
 12 = FLOATED
 13 = PLAYERMOVING
 14 = HIT
 15 = HITBY
 16 = DESTROYED
 17 = CREATED
 18 = POSTINIT
 19 = END_TURN


=== Classes ===

After the user message table comes the classes. This starts with a WORD
specifying the number of classes. Classes then follow.

Each class consists of the following:

* Name: A BYTE giving the length of the name, followed by the name.

* ID number: A WORD giving the zero-based class ID number (class ID
numbers are sometimes one-based, but here they are zero-based).

* Description: One or three bytes for length, followed by the plain text
(using CRLF for line endings). If length is less than 255 then it is one
byte. Otherwise, the first byte is 255 and then a WORD follows which gives
the length of the description. The description isn't null terminated. Any
escapes in the description are interpreted at runtime; they are not stored
with the control codes mentioned for special texts.

* Attributes: See attribute table below.

* Number of pictures (WORD)

* List of pictures. Each is a WORD, and is a zero-based number of the
picture from the picture area; after this, all further picture numbers in
the file are zero-based indexing into this table.

* Number of user variables (WORD)

* User variable names; each is eight bytes long and is padded with nulls.
(Variable names are actually limited to seven characters.)

* Number of subroutine labels (WORD)

* Label names; each is ten bytes long, and is a eight-byte null terminated
string, with junk in the remaining bytes; the final two bytes are a word
address into the sobroutine or message section.

* Subroutine program codes

* Number of message labels (WORD) (these aren't the message names; these
are labels outside of the subroutine section).

* Message label names; stored like the subroutine label names.

* Message program codes

Attribute Table
     0    BYTE     ???
     1    BYTE     Flag
     2    WORD     Misc4
     4    WORD     Misc5
     6    WORD     Misc6
     8    WORD     Misc7
    10    WORD     Shovable
    12    BYTE(5)  Arrivals
    17    BYTE(5)  Departures
    22    WORD     Density
    24    WORD     Volume
    26    WORD     Strength
    28    WORD     Weight
    30    WORD     HardE
    32    WORD     HardN
    34    WORD     HardW
    36    WORD     HardS
    38    WORD     SharpE
    40    WORD     SharpN
    42    WORD     SharpW
    44    WORD     SharpS
    46    WORD     Height
    48    WORD     Climb
    50    WORD     Temperature
    52    WORD     Shape
    54    WORD     ???
    56    WORD     ???
    58    WORD     ???
    60    WORD     ???

The flag byte has bit0 set for "receives keys" and has bit7 set for "is
the player". Other flags (if any) are unknown, they appear to be unset.

The arrivals and departures are stored each as five bytes, each byte for
one row, with the first byte corresponding to the top row. In each byte,
the rightmost column is the low bit; only the low 5-bits are used. (This
is not the same as the representation used in class codes!)

The last four attributes seem to have something to do with the program
length, but it is unknown. However, it is not necessary to read these in
order to figure out the program length (see below for details).


=== Program ===

Each class has program codes; this section describes how the program codes
are encoded in the file.

The first WORD of the subroutine section is the number of WORDs that make
up the the subroutine section, including the count itself. After that one
WORD header comes the instructions.

Each message block in the message section then consists of the header and
then the instructions. The header of each message block consists of two
WORDs, the first being the message number, and the second being the length
(in WORDs) of this message block, including the header.

The program is terminated by a header with both WORDs zero.

Program instructions are executed using a stack-based virtual machine.
Each instruction is normally one WORD; see below section for the opcodes.


=== Program Opcodes ===

The first byte is opcode byte (the major code). The second byte is the
minor code, the meaning depending on the opcode. In the descriptions
below, if it says / and a number, it is how many taken from stack. If
there is * then it pushes to stack, ! means end block, - means no effect
on data stack.

[1*] Local variables: 0=Class, 1=Temperature, 2=Shape, 4=Xloc, 5=Yloc,
6=LastDir, 7=CurImage, 8=Inertia, 9=Misc1, 10=Misc2, 11=Misc3, 12=Misc4,
13=Misc5, 14=Misc6, 15=Misc7, 16=Arrived, 17=Departed, 18=Arrivals,
19=Departures, 32=Busy, 33=Invisible, 34=UserSignal, 35=UserState,
36=KeyCleared, 37=IsPlayer, 38=Destroyed, 39=Stealthy, 40=VisualOnly,
48=Msg, 49=MsgFrom, 50=MsgArg1, 51=MsgArg2, 64=Density, 65=Volume,
66=Strength, 67=Weight, 68=Distance, 69=Height, 70=Climb, 72=HardE,
73=HardN, 74=HardW, 75=HardS, 76=SharpE, 77=SharpN, 78=SharpW, 79=SharpS,
80=ShapeE, 81=ShapeN, 82=ShapeW, 83=ShapeS, 84=Shovable

[2/1*] Retrieve local variable from other object. Local variable numbers
are the same as opcode 1.

[3/1] Assignment to standard local variables of current object.

[4/2] Assignment to standard local variable of other object (the first
(top) value taken from the stack is the value, and second is the object).

[5*] User-defined local variable; the second byte is zero-based local
variable number.

[6/1] Assignment to user-defined variable; the second byte is the
zero-based local variable number to write to.

[7*] Short decimal constant; the second byte is the 8-bit value.

[8*] Long decimal constant. The next two words are the small-endian 32-bit
number that it represents.

[9*] Short class constant; the second byte is a zero-based class number
(the class number is one-based at runtime).

[11*] Message constant; the second byte is the message number.

[13*] String literal. Follow by one WORD giving number of bytes of string
(including null terminator, always even), and then null-terminated special
text. There may be two null terminators if needed to make it even.

[14*] Direction constant (0-7 for absolute, 8-15 for relative)

[16/1*] Unary operator: 0=negative, 1=bitwise NOT, 2=logical NOT

[17/2*] Binary operator: 0=multiply, 1=divide, 2=modulo

[18/2*] Binary operator: 0=add, 1=subtract, 2=AND, 3=OR, 4=XOR

[19/2*] Bit shift operator: 0=left, 1=right

[20/2*] Comparison operator: 0=equal, 1=unequal, 2=less, 3=greater, 4=less
or equal, 5=greater or equal

[21/2*] Logical operator: 0=AND, 1=OR, 2=XOR (not short-circuiting)

[32] ObjDir

[34] ObjAbove

[36] ObjBelow

[38/2*] 0=ObjTopAt, 1=ObjBottomAt, 2=VolumeAt, 3=HeightAt, 4=Delta

[39*] Self

[40/3*] ObjClassAt

[48*] Key

[49*] Animation constant: 0=STOP, 1=ONCE, 2=LOOP, 8=OSC

[50*] Keyboard constant: See section about key codes.

[51*] Short hexadecimal constant; second byte is the 8-bit value.

[52*] Long hexadecimal constant. Next two words are the small-endian
32-bit number that it represents.

[53*] Global variable: 0=Level, 1=LevelCount, 2=AltImage, 3=ExplainDeath,
4=GlobalBool, 5=PuzzleSetNumber, 6=MoveNumber

[54] XDir

[56] YDir

[58] 0=NewX, 1=NewY

[59*] Bit constant 0-31; the second byte is the number 0-31, and at
runtime it is replaced by the relevant 32-bit number.

[60*] Sound constant (see section about user sounds)

[61] 0=ClassCount/1* (I don't know what this does), 1=GetArray

[64/3*] SendMessage (to Self)

[65/4*] SendMessage

[66/3*] Broadcast; second byte is zero-based class number

[67/4*] Broadcast

[68/1*] Move(Self, ...); minor code is 255 to take the value from the
stack, or is another number for a direction constant (in this latter case
the same bug occurs as with opcode 84).

[69/2*] Move; minor code is same as opcode 68, but the bug with opcode 84
does not occur, regardless of the minor code.

[70/2*] JumpTo(Self, ...)

[71/3*] JumpTo

[72/5*] Create

[74*] Destroy(Self)

[75/1*] Destroy

[80/3] SendMessage(Self, ...)

[81/4] SendMessage

[82/3] Broadcast; second byte is zero-based class number

[83/4] Broadcast

[84] Move(Self, dir). The second byte is the direction to move. Unlike
the normal Move() function, this one adds Strength to Inertia instead of
setting Inertia equal to Strength (this seems to be a bug). If the minor
code is 255 then takes direction from stack and does not have this bug.

[85] Move. The second byte is the same as for opcode 84; if 255 then it
takes from the stack (before taking the object to move). In this case the
bug mentioned above does not occur regardless of what the minor code is.

[88/5] Create

[96] Comment. Has one WORD giving length of the comment text (including
the null terminator), and then the plain text of the comment (with CRLF
line endings), null terminated.

[97] Popup setting. Second byte is 0 for PopupColor or 1 for PopupLoc.

[98] Destroy(Self)

[99/1] Destroy

[100] CallSub

[101-] Goto; next WORD is address to branch to unconditionally

[102] Return. Second byte is 0 for implicit end of SUBS block, 1 for
return from a subroutine, 2 for the end of a message block.

[103-] Return short constant. Second byte is return value.

[104/1] Return

[105/1] If. Second byte is zero for block-if or one for inline-if. The
next word is the number of words to skip (including the count itself) if
the condition is false.

[106] Else

[107/3] ImageSeq (seems to do nothing?)

[108/3] ImageLoop (seems to do nothing?)

[109] PopUp. Values taken from the stack is one plus the minor code.

[110/2] JumpTo(Self, ...)

[111/3] JumpTo

[112] Sound

[114] Array operations. Second byte: 0 = definition of an array, 1 =
SetArray, 2 = InitArray.

[126] Animate

[127] Link

[128] GotoLevel

[129-] 0=WinLevel, 1=LocateMe, 2=IgnoreKey, 3=PopupMisc, 4=UpdateScreen
(I don't know what UpdateScreen means?)

[130] FlushClass

[131] FlushObj

[132] SetInventory

[133] DelInventory

[134] ForEachObjAt

[240] Trace


=== Levels ===

After all classes are the levels. Before the levels comes a header of four
bytes that consists of:

* Number of levels (WORD)

* Two null bytes with unknown meaning

Each level consists of:

* Zero-based level number (WORD)

* Level description length, including the null terminator (WORD)

* Level description; a null-terminated special text

* Border colours, outer to inner (BYTE(32))

* Background colour (BYTE)

* Null byte (maybe the high byte of the background colour)

* Number of objects (WORD)

* Objects, in ordinary progressive television order; within each cell they
go bottom to top. See information about object records below.

* Number of level strings (WORD)

* Level strings; each one WORD length (the length includes the null
terminator), followed by the null-terminated special text.

An object record is sixteen bytes long, and consists of:
    0   WORD    Class (zero-based)
    2   WORD    CurImage (zero-based)
    4   BYTE    LastDir (zero-based; 0=east, 1=northeast, etc)
    5   BYTE    Data types for Misc vars
    6   WORD    X coordinate (one-based)
    8   WORD    Y coordinate (one-based)
   10   WORD    Misc1
   12   WORD    Misc2
   14   WORD    Misc3

The data types are as follows:
 0 = Number
 1 = Class (one-based)
 2 = Message
 3 = String
Data type for Misc1 is in bit1 and bit0, data type for Misc2 is in bit3
and bit2, data type for Misc3 is in bit5 and bit4. Bit7 and bit6 are
always zero.

The data type is used only in the editor and is irrelevant at run time.


=== Special Text ===

Level data may contain special text. This is text using the following
control codes (escapes have already been interpreted):

1 = Black (\0)
2 = Blue (\1)
3 = Green (\2)
4 = Cyan (\3)
5 = Red (\4)
6 = Purple (\5)
7 = Yellow (\6)
8 = White (\7)
10 = Line break (\n)
11 = Left (\l)
12 = Center (\c)
14 = Picture (\i); followed by two WORDs: zero-based class and image
15 = Horizontal line (\b)
16 = Quiz button (\q); followed by one byte key code


=== Solutions ===

After the levels come the solutions. There is first one WORD which is the
number of solutions, and then the solutions. Each solution consists of:

* Zero-based level number (WORD)

* Number of keys in solution (WORD)

* User name (BYTE(9)); the user name is null terminated, although there
may be junk after the null terminator.

* Key codes; one byte each.


=== User Sounds ===

Finally, the user sounds come last. One WORD gives the number of user
sounds. And then each sound consists of:

* Sound ID number (zero-based) (WORD)

* Name length (BYTE)

* Name (not terminated; length is given instead)

* Data length (WORD)

* Data (a RIFF WAVE file)

The built-in sounds are as follows:
 SPLASH
 POUR
 DOOR
 GLASS
 BANG
 UNHH
 UH_OH
 FROG
 THWIT
 KLINKK
 POWER
 KLECK
 CLICK
 SMALL_POP
 DINK
 TICK
 CHYEW
 CHEEP
 ANHH
 BRRRT
 BRRREEET
 BWEEP
 DRLRLRINK
 FFFFTT
 WAHOO
 YEEHAW
 OLDPHONE
 RATTLE
 BEEDEEP
 THMP_thmp
 BEDOINGNG
 HEARTBEAT
 LOCK
 TAHTASHH
 BOOOM
 VACUUM
 RATCHET2
 DYUPE
 UNCORK
 BOUNCE
 JAYAYAYNG
 DEEP_POP
 RATCHET1
 GLISSANT
 BUZZER
 FAROUT
 KEWEL
 WHACK
 STEAM
 HAWK


=== Key codes ===

   8  BACK
   9  TAB
  12  CENTER (number pad 5 when numlock is off)
  13  ENTER
  16  SHIFT
  17  CTRL
  19  BREAK
  20  CAPSLOCK
  32  SPACE
  33  PGUP
  34  PGDN
  35  END
  36  HOME
  37  LEFT
  38  UP
  39  RIGHT
  40  DOWN
  48  0 (the top row zero)
  57  9 (the top row nine; 1-8 are in between 0 and 9)
  65  A
  90  Z (letters B-Y are in between A and Z)
  96  NUMPAD0
 105  NUMPAD9 (number pad 1-8 are in between)
 106  MULTIPLY (the number pad "*" key)
 110  DECIMAL (the number pad "." key)
 111  DIVIDE (the number pad "/" key)
 120  F9
 121  F10
 122  F11
 123  F12
 144  NUMLOCK
 145  SCRLOCK
 186  SEMICOLON
 187  EQUALS
 188  COMMA
 189  MINUS
 190  PERIOD
 191  SLASH
 192  TILDE
 219  OBRACKET
 220  BACKSLASH
 221  CBRACKET
 222  QUOTE

The number pad and main enter keys have the same key code. When num lock
is off, the number pad keys have the same codes as the other arrow keys.
The NUMPAD codes are only when numlock is on.
