This file documents some of the internals of Free Hero Mesh. It is not
important to someone who will only use Free Hero Mesh normally, but may
be of interest to those who wish to modify Free Hero Mesh or to understand
some of its outputs that have internal data.
=== Types and values ===
In the Free Hero Mesh VM codes, values on the stack and in user-defined
local and global variables, as well as Misc1-Misc7, are stored as Value
structures (defined in heromesh.h).
The t member stores the type, which can be:
* TY_NUMBER: u or s is the 32-bit integer which it represents.
* TY_CLASS: u is the class number.
* TY_MESSAGE: u is the message number. Numbers less than 256 are standard
messages, and higher numbers are user-defined messages.
* TY_LEVELSTRING and TY_STRING: Represents a text string; u is a string
number. For TY_LEVELSTRING, this is an index into the levelstrings array,
and for TY_STRING, it is an index into the stringpool array.
* TY_SOUND and TY_USOUND: A sound.
* TY_FOR: This is used internally for the global variables which keep
track of the state of a for/next loop. Values of this type should never
occur on the operand stack.
* TY_MARK: A mark; u is always zero.
* TY_ARRAY: An array reference. The low 16-bits of u are the starting
index of the array (pointed by array_data), the next 10-bits and the high
6-bits indicate the size of the array.
* TY_CODE: Used in case blocks to denote a branch to another address. Also
used for link values; the high 16-bits are the class number and the low
16-bits are the address within the class codes for that class.
* 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):
0000-00FF = Short constants 0 to 255
0100-01FF = Short constants -256 to -1
0200-02FF = Built-in message constants
0300-03FF = Built-in sound constants
0400-04FF = User-defined sound constants
1000-107F = Short 7-bit constant and +
1080-10FF = Short 7-bit constant and -
1100-117F = Short 7-bit constant and *
1180-11FF = Short 7-bit constant and /
1200-127F = Short 7-bit constant and mod
1280-12FF = Short 7-bit constant and ,*
1300-137F = Short 7-bit constant and ,/
1380-13FF = Short 7-bit constant and ,mod
1400-147F = Short 7-bit constant and band
1480-14FF = Short 7-bit constant and bor
1500-157F = Short 7-bit constant and bxor
1580-15FF = Short 7-bit constant and lsh
1600-167F = Short 7-bit constant and rsh
1680-16FF = Short 7-bit constant and ,rsh
1700-177F = Short 7-bit constant and eq
1780-17FF = Short 7-bit constant and ne
1800-187F = Short 7-bit constant and lt
1880-18FF = Short 7-bit constant and gt
1900-197F = Short 7-bit constant and le
1980-19FF = Short 7-bit constant and ge
1A00-1A7F = Short 7-bit constant and ,lt
1A80-1AFF = Short 7-bit constant and ,gt
1B00-1B7F = Short 7-bit constant and ,le
1B80-1BFF = Short 7-bit constant and ,ge
1E00-1EFF = Short 7-bit constant and ret
1F00-1F1F = Read bit
1F20-1F3F = Write bit
2000-27FF = Read user-defined local variable
2800-2FFF = Read user-defined global variable
3000-37FF = Write user-defined local variable
3800-3FFF = Write user-defined global variable
4000-7FFF = Class constants
8000-87FF = Instructions
8800-8FFF = Instructions with ,
9000-97FF = Instructions with =
9800-9FFF = Instructions with = and ,
A000-BFFF = Instructions followed by .
C000-FFFF = User-defined message constants
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.)