ADDED   class.doc
Index: class.doc
==================================================================
--- class.doc
+++ class.doc
@@ -0,0 +1,1484 @@
+[TODO: This document is incomplete]
+
+This document describes how class definitions are working.
+
+
+=== Syntax ===
+
+The following kinds of tokens are available:
+
+* Open and closing delimiters: These are ( and ) and no spaces are
+required around it. They are used for grouping in many places.
+
+* Plain name: A plain word with no sigil. The set of valid plain names is
+fixed, and they are all explained in the rest of this document.
+
+* Number: Can be in decimal, or in hexadecimal with a 0x prefix, or in
+octal with a 0o prefix. The "x" or "o" must be in lowercase, but the
+hexadecimal digits can be uppercase or lowercase. Decimal numbers may be
+optionally preceded by a - or + sign.
+
+* Qualified name: A name with a sigil prefix. See below for the list of
+possible sigils and their meanings. In all cases except key names, you can
+define your own qualified names.
+
+* String: A string literal with quotation marks around it. A string may
+contain escapes, which use a backslash followed by whatever text is being
+escaped; see below section for the list of string escapes.
+
+Names can contain the following characters:
+  0123456789-+_?.*/
+  ABCDEFGHIJKLMNOPQRSTUVWXYZ
+  abcdefghijklmnopqrstuvwxyz
+
+Plain and qualified names may also optionally be prefixed by an equal
+sign and/or a comma; their purpose is explained later. If you have both,
+the equal sign comes first and then the comma.
+
+Name sigils are:
+  $  Class
+  @  Global variable
+  '  Key code
+  :  Label
+  %  Local variable
+  #  User message
+  !  User sound
+
+Comments are also allowed; these start with a semicolon (outside of a
+string literal) and end at the next line break.
+
+
+=== Escapes ===
+
+\0
+  Makes further text black (default).
+
+\1
+  Makes further text blue.
+
+\2
+  Makes further text green.
+
+\3
+  Makes further text cyan.
+
+\4
+  Makes further text red.
+
+\5
+  Makes further text purple.
+
+\6
+  Makes further text yellow.
+
+\7
+  Makes further text white.
+
+\b
+  Draws a horizontal rule.
+
+\c
+  Makes further text centred.
+
+\iCLASS:NUMBER\
+  Displays a picture. Give the class name (without $ at first) and a
+  colon and the zero-based index number of the picture in that class.
+  This is then followed by another backslash. The picture may span
+  multiple lines; it will automatically move the text to make room.
+
+\l
+  Makes further text left aligned (default).
+
+\n
+  Line break.
+
+\qX
+  Make a "quiz button". Any string containing this command is a "quiz
+  string", and there are special behaviours involving quiz strings. The
+  X should be replaced by any digit or uppercase letter; that will be
+  displayed, and if clicked, it represents that key code.
+
+\xXX
+  Hexadecimal escape, where XX is a hexadecimal number from 01 to FF,
+  and displays a graphic character with the given PC character code.
+
+
+=== Preprocessor ===
+
+Free Hero Mesh includes a macro preprocessor, which you may use if wanted.
+All preprocessor commands are in braces; that constitutes a preprocessor
+token, which may contain other tokens as arguments.
+
+Other preprocessor tokens include the macro separator token, which is
+written as a vertical bar, and a macro argument token, which is one or
+more backslashes followed by a number from 1 to 255.
+
+For user-defined macros, one argument can be either many tokens inside of
+parentheses (the parentheses are part of the argument), a single token, or
+a macro separator token (omitted from the expansion) followed by any number
+of further tokens to make up the last argument.
+
+Built-in macros include:
+
+{+ <numbers...>}
+  Addition. The result is 0 if no arguments are specified.
+
+{- <number> <number>}
+  Subtraction.
+
+{* <numbers...>}
+  Multiplication. The result is 1 if no arguments are specified.
+
+{/ <number> <number>}
+  Division.
+
+{band <numbers...>}
+  Bitwise AND. The result is -1 if no arguments are specified.
+
+{bit <numbers...>}
+  The numbers are in range 0 to 31 and denote bit positions; the result is
+  a number with only those bits set.
+
+{bnot <number>}
+  Bitwise complement.
+
+{bor <numbers...>}
+  Bitwise OR. The result is 0 if no arguments are specified.
+
+{bxor <numbers...>}
+  Bitwise XOR. The result is 0 if no arguments are specified.
+
+{call <string> <tokens...>}
+  Call a macro dynamically.
+
+{cat <tokens...>}
+  Makes a string by concatenating several tokens together. Sigils are
+  omitted, macro separator tokens are removed, and numbers are converted
+  to decimal. Strings are also allowed.
+
+{define <string> <tokens...>}
+  Define a macro. The inner tokens are not expanded yet; they will be
+  expanded during each use. A macro argument token with a single backslash
+  expands to the argument in that position, while a macro argument tokens
+  with multiple tokens becomes the token with one less backslash. It is
+  permitted to redefine existing macros as well as new ones.
+
+{include <string>}
+  Include text from another file into this one. You cannot use {include}
+  inside of another macro or in a macro argument.
+
+{mod <number> <number>}
+  Modulo.
+
+{version <number>}
+  Expands into nothing. The number must be zero, otherwise it is an error.
+  Future versions of Free Hero Mesh may change this.
+
+It is possible to implement a tag system in this preprocessor, which makes
+it Turing complete. For example:
+
+  {define "skip" {call \2}}
+  {define "1" {skip \1|"3"|"3"|"2"|"1"|"H"}}
+  {define "2" {skip \1|"3"|"3"|"1"}}
+  {define "3" {skip \1|"3"|"3"}}
+  {define "H" \1}
+  {call "2"|"1"|"1"}
+
+Note: Macro names are entirely independent from token names.
+
+
+=== Global definitions ===
+
+These are the global definitions in the class definition file.
+
+(Animate <limit>)
+  Set the limit for logical animations, from 1 to 255. The default is 32.
+
+(Background <number>)
+  Set the background colour, from 0 to 255. The default value is 1.
+
+(Synchronize <slot> <length> <speed>)
+  Define an animation slot for synchronized animation. The slot number can
+  be 0 to 7, the length is the number of images in the sequence, and the
+  speed is the number of centiseconds between frames.
+
+(Volume <number>)
+  Define the maximum allowed volume for an object to move diagonally
+  between two other objects. The default value is 10000.
+
+($<name> <definitions...>)
+  Define a class. See the section about class definitions for details.
+
+(@<name> <value>)
+  Define a global variable and its initial value.
+
+(<message> <code...>)
+  Defines a default message code for all classes which do not specify
+  their own code for this message.
+
+
+=== Data types ===
+
+The following data types are available:
+
+* Number: A 32-bit integer. Whether it is treated as signed or unsigned
+depends on the context. In some cases, it is used as bit field data.
+
+* Class: A class name with a $ prefix.
+
+* Message: A message name. User-defined message names have a # prefix;
+standard message names have no prefix.
+
+* Object: A reference to an object. There are no literals of this type.
+
+* String: A string in quotation marks. There are no string manipulation
+functions; the only thing that can be done with a string is to display it.
+
+* Sound: A sound.
+
+Some things are not their own types, and are other uses of numbers:
+
+* Null: A null class or null object is represented as zero.
+
+* Boolean: When a boolean is required as input to some instruction, zero
+is false, and most other values (of any type) are true, except for sounds
+which cannot be used as booleans at all. When an instruction produces a
+boolean value as output, true is one and false is zero.
+
+* Key: A key code for input (not necessarily the same as the physical key
+with that label). See the list in the below section.
+
+* Direction: Can be absolute or relative. For absolute directions, zero is
+east, and increasing numbers go counterclockwise 45 degrees each, up to
+seven for southeast. Relative directions start at eight for forward and
+otherwise work similarly (increasing numbers go counterclockwise).
+
+
+=== Constants ===
+
+The following constants are available. Some of them are numeric constants
+and using them pushes numbers to the stack, and they are interchangeable
+with the corresponding numbers where instructions are expected.
+
+Absolute directions:
+  E = 0
+  NE = 1
+  N = 2
+  NW = 3
+  W = 4
+  SW = 5
+  S = 6
+  SE = 7
+
+Relative directions:
+  F = 8
+  LF = 9
+  L = 10
+  LB = 11
+  B = 12
+  RB = 13
+  R = 14
+  RF = 15
+
+Bit constants:
+  bit0 to bit31 = numbers with a single bit set
+
+Animation constants:
+  STOP = 0
+  ONCE = 1
+  LOOP = 2
+  OSC = 8
+  OSCLOOP = 10
+
+Standard messages:
+  ARRIVED
+  BEGIN_TURN
+  COLLIDE
+  COLLIDEBY
+  CREATE
+  CREATED
+  DEPARTED
+  DESTROY
+  DESTROYED
+  END_TURN
+  FLOATED
+  HIT
+  HITBY
+  INIT
+  JUMPED
+  KEY
+  LASTIMAGE
+  MOVED
+  MOVING
+  PLAYERMOVING
+  POSTINIT
+  SUNK
+
+Input constants:
+  'BACK = 8
+  'TAB = 9
+  'CENTER = 12
+  'ENTER = 13
+  'SHIFT = 16
+  'CTRL = 17
+  'BREAK = 19
+  'CAPSLOCK = 20
+  'SPACE = 32
+  'PGUP = 33
+  'PGDN = 34
+  'END = 35
+  'HOME = 36
+  'LEFT = 37
+  'UP = 38
+  'RIGHT = 39
+  'DOWN = 40
+  'DELETE = 46
+  '0 = 48
+  '1 = 49
+  '2 = 50
+  '3 = 51
+  '4 = 52
+  '5 = 53
+  '6 = 54
+  '7 = 55
+  '8 = 56
+  '9 = 57
+  'A = 65
+  'B = 66
+  'C = 67
+  'D = 68
+  'E = 69
+  'F = 70
+  'G = 71
+  'H = 72
+  'I = 73
+  'J = 74
+  'K = 75
+  'L = 76
+  'M = 77
+  'N = 78
+  'O = 79
+  'P = 80
+  'Q = 81
+  'R = 82
+  'S = 83
+  'T = 84
+  'U = 85
+  'V = 86
+  'W = 87
+  'X = 88
+  'Y = 89
+  'Z = 90
+  'NUMPAD0 = 96
+  'NUMPAD1 = 97
+  'NUMPAD2 = 98
+  'NUMPAD3 = 99
+  'NUMPAD4 = 100
+  'NUMPAD5 = 101
+  'NUMPAD6 = 102
+  'NUMPAD7 = 103
+  'NUMPAD8 = 104
+  'NUMPAD9 = 105
+  'MULTIPLY = 106
+  'DECIMAL = 110
+  'DIVIDE = 111
+  'F9 = 120
+  'F10 = 121
+  'F11 = 122
+  'F12 = 123
+  'NUMLOCK = 144
+  'SCRLOCK = 145
+  'SEMICOLON = 186
+  'EQUALS = 187
+  'COMMA = 188
+  'MINUS = 189
+  'PERIOD = 190
+  'SLASH = 191
+  'TILDE = 192
+  'OBRACKET = 219
+  'BACKSLASH = 220
+  'CBRACKET = 221
+  'QUOTE = 222
+
+Standard sound constants:
+  ANHH
+  BANG
+  BEDOINGNG
+  BEEDEEP
+  BOOOM
+  BOUNCE
+  BRRREEET
+  BRRRT
+  BUZZER
+  BWEEP
+  CHEEP
+  CHYEW
+  CLICK
+  DEEP_POP
+  DINK
+  DOOR
+  DRLRLRINK
+  DYUPE
+  FAROUT
+  FFFFTT
+  FROG
+  GLASS
+  GLISSANT
+  HAWK
+  HEARTBEAT
+  JAYAYAYNG
+  KEWEL
+  KLECK
+  KLINKK
+  LOCK
+  OLDPHONE
+  POUR
+  POWER
+  RATCHET1
+  RATCHET2
+  RATTLE
+  SMALL_POP
+  SPLASH
+  STEAM
+  TAHTASHH
+  THMP_thmp
+  THWIT
+  TICK
+  UH_OH
+  UNCORK
+  UNHH
+  VACUUM
+  WAHOO
+  WHACK
+  YEEHAW
+
+
+=== Variables ===
+
+These are the variables which each object has. Some are marked [ro] below
+because they are read-only. In all cases, you can put , in front to access
+a different object rather than self and = in front to write that variable
+(unless it is read-only). You can also access some of these variables also
+on classes instead of objects; these are always read-only. The variables
+which are available on classes too are marked [c] below.
+
+Some variables list one type, and some list two. If there are two types,
+"int16/int32" means any number written to it is truncated to 16-bits in
+compatible mode, but the full value is retained in incompatible mode. The
+16-bit number is treated as unsigned, so it is zero-extended to 32-bits.
+The notation "int16/any" means the same thing, except that the variable
+is not limited to numbers; non-numbers are never truncated.
+
+A few variables require a direction on the top of the stack, above the
+value if you are writing. These are marked [d] below. These are really
+four variables, one for each direction (not counting diagonals).
+
+If you use the comma prefix to refer to another object, the object to
+refer to is always below the direction and/or value to write on the stack
+(if there are any such values).
+
+In incompatible mode, many "physics" variables are treated as signed.
+
+Most of these variables are state-changing; writing to them is not allowed
+on the same turn as IgnoreKey. Exceptions are Distance and KeyCleared.
+
+%xyz : any
+  A user-defined variable. This variable cannot be accessed on other
+  objects other than this one. You can give it any name with a percentage
+  sign at first. User variables are initialized to zero, and need not be
+  declared anywhere.
+
+Arrivals : int32
+  Only the low 25-bits are used. Each bit which is set indicates that it
+  cares if other objects arrive around it at that relative location, where
+  bit0 is two paces northeast, bit1 is to the west of that, etc, and then
+  bit4 two paces northwest of this object, and bit5 starts on the next
+  row to the south, etc, and bit12 is this object's location.
+
+Arrived : int32
+  When an object arrives in the location where this object cares about
+  arrivals (according to the Arrivals variable), the corresponding bits
+  are set in the Arrived variable. If this value is nonzero, then it will
+  also send a ARRIVED message during the trigger phase. You can write all
+  bits of this variable, but only the low 25-bits can be read back; if you
+  write a nonzero number with only the high bits set, then it will still
+  be triggered but will be read back as zero.
+
+Busy : bool
+  If any object has either the Busy or UserSignal variable set, then the
+  player input is blocked, and the turn may continue. Use this to control
+  the timing of effects in LASTIMAGE blocks.
+
+Class : class [ro]
+  The class of this object.
+
+Climb : int16/int32 [c]
+  In order for this object to move, this object's Climb must equal or
+  exceed the Height of all objects at the target location, otherwise it
+  is prevented from moving.
+
+CollisionLayers : int8 [c] [ro]
+  Any set bit means no other object with that same bit set in this field
+  may exist at the same location.
+
+Compatible : bool [c] [ro]
+  The compatibility flag. Class definitions imported from EKS Hero Mesh
+  always set this flag; in new puzzle sets it is normally not set.
+
+Density : int16/int32 [c]
+  Determines the order that objects are stacked within each cell. When an
+  object is moved or created, its Density is compared with the Density of
+  the objects already present at that location, in order to insert it into
+  the stack of objects there, at the top, bottom, or middle, where lesser
+  numbers mean closer to the top, and greater numbers are deeper. If there
+  are multiple objects of the same Density, the new one goes above others
+  with the same Density. If you change the value of this variable, it will
+  automatically float/sink the object if necessary in order to fit it into
+  the correct stacking order, sending FLOATED and SUNK messages.
+
+Departed : int32
+  This is like Arrived but triggered for departures (as specified by the
+  Departures variable) rather than arrivals.
+
+Departures : int32
+  This is like Arrivals but for positions where it is triggered by objects
+  leaving those locations rather than arriving there.
+
+Destroyed : bool [ro]
+  It is set if this object has been successfully destroyed (but not yet
+  deleted from memory). You must use the Destroy or Assassinate command
+  in order to set this flag; you cannot set it by yourself.
+
+Dir : int3
+  The current direction. When it moves (without teleportation), it will
+  automatically be set to the direction it moved. You can also set this
+  by yourself. Relative directions are relative to this direction. If you
+  set this by yourself to a relative direction, then it will automatically
+  be set to an absolute direction, based on the previous value.
+
+Distance : int16
+  When an object moves (including due to teleportation), the Manhattan
+  distance of the movement is added to the Distance variable. This is
+  reset to zero at the beginning of each turn.
+
+Done : bool [c]
+  This flag is used to determine whether or not to find the object in a
+  for/next loop. It automatically clears all Done flags at the beginning
+  of each turn and at the entry of each for/next loop, so usually you do
+  not need to set this by yourself.
+
+Hard : int16 [c] [d]
+  See Sharp.
+
+Height : int16/int32 [c]
+  Used to block the movement of other objects; see Climb for details. In
+  order for HIT and HITBY messages to work, Height must be positive.
+
+Image : int8
+  The index number of the picture to display. The (Image) block in the
+  class definition specifies which picture to display for each index
+  number, where the first picture is zero. The actual picture being
+  displayed may differ if an animation is in progress, and no picture
+  will be displayed at all if the Invisible flag is set, although this
+  variable still remains available in such circumstances.
+
+Inertia : int16/int32
+  This determines how much "left over" Strength an object has to move.
+  Normally, when an object tries to move, its Inertia is set to the
+  Strength of the object which is moving, and then the Weight of the
+  objects moved are deducted from Inertia. Normally you do not need to
+  set this value by yourself nor to read it, but you might use it in the
+  HIT or HITBY messages to affect how much it can push, or to check the
+  Inertia after the movement is complete to see what is left over.
+
+Invisible : bool [c]
+  If set, then this object is not displayed on the screen. However, it
+  is still present in the level and does everything else that a visible
+  object will do.
+
+KeyCleared : bool
+  The game engine does nothing with this except to automatically clear it
+  between turns, so that you need not do by yourself.
+
+Misc1 : int16/any
+  The game engine does not use this variable; use it for your own use.
+
+Misc2 : int16/any
+  The game engine does not use this variable; use it for your own use.
+
+Misc3 : int16/any
+  The game engine does not use this variable; use it for your own use.
+
+Misc4 : int16/any [c]
+  The game engine does not use this variable; use it for your own use.
+
+Misc5 : int16/any [c]
+  The game engine does not use this variable; use it for your own use.
+
+Misc6 : int16/any [c]
+  The game engine does not use this variable; use it for your own use.
+
+Misc7 : int16/any [c]
+  The game engine does not use this variable; use it for your own use.
+
+Moved : bool
+  After a Move instruction successfully moves this object, it will set
+  this flag. During the trigger phase, it will send the MOVED message
+  to all objects which have moved; you can set or clear this flag by
+  yourself if you want to cause it to trigger even though it didn't
+  move or to not trigger even though it did move.
+
+Player : bool [c] [ro]
+  If this object is the player. This is used implicitly as the From of
+  some messages sent by the game engine, and has a few other purposes.
+  (Normally, a level should have exactly one object of such a class,
+  although this is not mandatory.)
+
+Shape : int8 [c]
+  Defines the shape of the object, which is used when one object tries to
+  move into another one that it can't climb over. The low 2-bits are for
+  east, next 2-bits for north, next 2-bits for west, and finally the high
+  2-bits are for south. Each of these 2-bit values can be 0 for flat (no
+  sliding), 1 for slanted to the left, 2 for slanted to the right, and 3
+  for slanted both left and right. (Left and right are when "facing" that
+  side of the object.)
+
+ShapeDir : int2 [c] [d]
+  Allows accessing the individual 2-bit parts of Shape.
+
+Sharp : int16 [c] [d]
+  When one object tries to move into another object, the Hard and Sharp
+  values for the sides that are touching will be compared. If the Sharp
+  value for one is greater than the Hard of the other, then the object
+  with insufficient Hardness is destroyed.
+
+Shovable : int8 [c]
+  Defines what directions the object may be shoved, where bit0 means east,
+  bit2 means north, bit4 means west, and bit6 means south.
+
+Stealthy : bool [c]
+  If this flag is set, then the Arrived and Departed variables of other
+  objects are not automatically set when this object moves.
+
+Strength : int16/int32 [c]
+  When this object's code tries to move this or other objects by the use
+  of the Move instruction, the Strength must be greater than or equal to
+  the total Weight of all objects being moved, or else it won't move.
+
+Temperature : int16/int32 [c]
+  The game engine does not use this variable; use it for your own use.
+
+UserSignal : bool
+  This variable has the same effect as Busy; see Busy for details. It is
+  still a separate variable though.
+
+UserState : bool [c]
+  The game engine does not use this variable; use it for your own use.
+
+VisualOnly : bool [c]
+  If set, this object is ignored by most operations, although it can still
+  receive messages, and ObjClassAt can still find it. If the Compatible
+  flag is also set, then VisualOnly also has the effects of Stealthy.
+
+Volume : int16/int32 [c]
+  If an object tries to move diagonally, it will not be able to move if
+  the sum of its Volume and the largest Volumes at the orthogonally
+  adjacent cells that it is moving between is greater than the limit
+  (which is normally 10000, but you can redefine it globally). See the
+  documentation about moving objects for further details.
+
+Weight : int16/int32 [c]
+  Determines how much Inertia is required to move this object (and is used
+  up once it has moved, or if it failed to move it). See Strength.
+
+Xloc : int8 [ro]
+  The 1-based X coordinate of this object.
+
+Yloc : int8 [ro]
+  The 1-based Y coordinate of this object (1 is at the top of the screen).
+
+
+=== Instructions ===
+
+For some instructions, a comma prefix means to operate on another object,
+while the lack of the comma means to operate on itself; for some other
+instructions, a comma prefix means to use signed instead of unsigned
+arithmetic. An equal sign prefix usually means to write instead of read.
+
+Some instructions are block instructions; see the next section.
+
+Many instructions are state-changing instructions; these instructions are
+marked with ** in the summary line. Such instructions are not allowed to be
+used on the same turn as the IgnoreKey instruction.
+
+.  ( x -- )
+
++  ( in1 in2 -- out )
+  Add two numbers together.
+
+-  ( in1 in2 -- out )
+  Subtract in2 from in1.
+
+*  ( in1 in2 -- out )
+  Multiply two numbers together.
+
+,*  ( in1 in2 -- out )
+  Signed multiply in1 by in2.
+
+/  ( in1 in2 -- out )
+  Unsigned divide in1 by in2 producing the quotient.
+
+,/  ( in1 in2 -- out )
+  Signed divide in1 by in2 producing the quotient.
+
+Animate  ( flag start end delay -- ) **
+  Start or stop an animation for this object. This also sets the Image
+  variable equal to the start value. The flag can be STOP to stop an
+  animation, ONCE to play the animation once (and to queue a LASTIMAGE
+  event if the animation isn't changed before that happens; note that
+  the message is sent even before the animation is actually visible),
+  LOOP to play it in a loop, or OSCLOOP for an oscillating loop. The
+  delay between frames is in centiseconds; the start and end are the
+  image numbers in this class, and may be ascending or descending.
+
+Arg1  ( -- value )
+  The first message argument.
+
+=Arg1  ( value -- )
+  Allows setting the first message argument. This will last until the
+  current message returns, and does not affect further messages sent; it
+  allows Arg1 to be used as a mutable local variable.
+
+Arg2  ( -- value )
+  The second message argument.
+
+=Arg2  ( value -- )
+  Allows setting the second message argument. This will last until the
+  current message returns, and does not affect further messages sent; it
+  allows Arg2 to be used as a mutable local variable.
+
+Arg3  ( -- value )
+  The third message argument. If the message was sent with only two
+  arguments, then this value is zero by default.
+
+=Arg3  ( value -- )
+  Allows setting the third message argument. This will last until the
+  current message returns, and does not affect further messages sent; it
+  allows Arg3 to be used as a mutable local variable.
+
+Assassinate  ( -- ) **
+  Destroy this object without sending any messages. The object is marked
+  as destroyed, but its variables are still accessible until the garbage
+  collector runs (during the trigger step for combatible objects, and
+  during the cleanup step for all objects). Assassination always succeeds,
+  so there is no result value to indicate success or not.
+
+,Assassinate  ( obj -- ) **
+  Destroy the given object without sending any messages.
+
+band  ( in1 in2 -- out )
+  Bitwise AND.
+
+(bit <numbers>)  ( -- number )
+  Make a number with only the specified bits set, given numbers 0 to 31.
+
+bnot  ( in -- out )
+  Bitwise NOT.
+
+bor  ( in1 in2 -- out )
+  Bitwise OR.
+
+Broadcast  ( class message arg1 arg2 -- count )
+  Send a message to all objects of the specified class (or to all objects
+  of all classes if the specified class is zero), in the reverse order of
+  the creation of the objects. The result value is the number of objects
+  of that class.
+
+(Broadcast <class>)  ( message arg1 arg2 -- count )
+  An alternative syntax for Broadcast (needed only for compatibility with
+  EKS Hero Mesh).
+
+BroadcastEx  ( class message arg1 arg2 arg3 -- count )
+  As Broadcast but with three message arguments.
+
+BroadcastSum  ( class message arg1 arg2 -- total )
+  As Broadcast but the result is the sum of the return values rather than
+  the number of objects. If a return value is a class or object, it is
+  treated as 1. Other non-numeric return values are errors.
+
+BroadcastSumEx  ( class message arg1 arg2 arg3 -- total )
+  As BroadcastSum but with three message arguments.
+
+bxor  ( in1 in2 -- out )
+  Bitwise XOR.
+
+Create  ( class x y image dir -- obj ) **
+  Creates a new object at the specified location, and returns it. The
+  result is zero if the class is zero, the coordinates are out of range,
+  the object cannot be created due to the CollisionLayers, or if the new
+  object is destroyed before its CREATE message returns.
+
+DelInventory  ( class image -- ) **
+  Delete an item from the inventory; see SetInventory for more details.
+
+Delta  ( in1 in2 -- out )
+  Subtracts the smaller input from the larger (unsigned).
+
+Destroy  ( -- value ) **
+  Destroy this object. The variables can still be accessed after it is
+  destroyed until it is garbage collected. This calls the DESTROY message;
+  the return value will be the result of this instruction, and if it is
+  false then it is destroyed, and if true then the destruction fails.
+
+,Destroy  ( object -- value ) **
+  Destroy the specified object (as Destroy but for any object).
+
+dup  ( x -- x x )
+
+eq  ( in1 in2 -- bool )
+  Test if they are equal. Sounds cannot be compared, but you can compare
+  values of any other type. Strings compare as equal if they contain the
+  same text. Object references are only equal if they refer to the same
+  object; objects which no longer exist still compare correctly. Values
+  of two different types are never equal to each other.
+
+FlushClass  ( class -- ) **
+  Resets the Arrived, Busy, Departed, Inertia, Moved, and UserSignal flags
+  of all objects of the specified class to zero. If the class is -1, then
+  all objects are flushed in this way, and during the input phase, it also
+  skips the other phases similarly to IgnoreKey if the class is -1.
+
+FlushObj  ( obj -- ) **
+  Resets the Arrived, Busy, Departed, Inertia, Moved, and UserSignal flags
+  of the specified object only.
+
+From  ( -- obj )
+  The object which send the message to this object. In some cases, this
+  will be zero instead of a valid object.
+
+ge  ( in1 in2 -- bool )
+  Test if first input is greater or equal to second input (unsigned).
+
+,ge  ( in1 in2 -- bool )
+  Test if first input is greater or equal to second input (signed).
+
+GetInventory  ( class image -- value true | false )
+  Read from the inventory, with true if it exists or false if not.
+
+gt  ( in1 in2 -- bool )
+  Test if first input is greater than second input (unsigned).
+
+,gt  ( in1 in2 -- bool )
+  Test if first input is greater than second input (signed).
+
+HeightAt  ( x y -- height )
+  Finds the greatest height among objects at the specified location.
+
+IgnoreKey  ( -- )
+  There is no effect outside of the input phase. During the input phase,
+  indicates that this input is not part of the solution, so it will not
+  be entered into the replay. It is an error to ignore inputs which do
+  cause state changes. Pop-up messages are still allowed, and unlike in
+  EKS Hero Mesh they will not break replayability; the key to dismiss a
+  non-quiz popup is not entered into the replay list, and the key to
+  dismiss a quiz popup will be treated as a non-quiz input. IgnoreKey
+  also causes the rest of the turn after the input phase to be skipped.
+
+IntMove  ( dir -- bool ) **
+  Similar to Move but do not initialize Inertia at all; use the current
+  value of Inertia instead.
+
+,IntMove  ( obj dir -- bool ) **
+  Similar to ,Move but do not initialize Inertia at all; use the current
+  value of Inertia instead.
+
+is  ( x y -- bool )
+  Where x is a class or object or zero, and y is a class, check that it
+  is an object of that class, is the same class, or is a subclass of the
+  class. If y is zero, then it is always true unless x is zero.
+
+JumpTo  ( x y -- bool ) **
+  As MoveTo but sends JUMPED message to that object after it has been
+  successfully teleported.
+
+,JumpTo  ( obj x y -- bool ) **
+  As ,MoveTo but sends JUMPED message to that object after it has been
+  successfully teleported.
+
+Key  ( -- number )
+  During the input phase, the key input. During other phases, zero.
+
+land  ( in1 in2 -- out )
+  Logical AND.
+
+le  ( in1 in2 -- bool )
+  Test if first input is less or equal to second input (unsigned).
+
+,le  ( in1 in2 -- bool )
+  Test if first input is less or equal to second input (signed).
+
+Level  ( -- number )
+  The level code value for this level. The game engine does nothing with
+  this value, but you can use it in class codes if you wish. (For puzzle
+  sets converted from EKS Hero Mesh, this is the zero-based level number;
+  a few badly designed puzzles use it. In Free Hero Mesh, you can set it
+  to whatever 16-bit number you wish in the level editor, and then use it
+  as an additional parameter for the puzzle.)
+
+lnot  ( in -- out )
+  Logical NOT.
+
+Loc  ( -- x y )
+  The X and Y coordinates of this object; same as "Xloc Yloc".
+
+,Loc  ( obj -- x y )
+  The X and Y coordinates of the specified object; same as "dup ,Xloc
+  swap ,Yloc" (but more efficient).
+
+LocateMe  ( -- )
+  Makes the current object especially visible. This is meant to help the
+  player to notice where the "Hero" object is more easily, but you can use
+  it to make other objects noticeable too if that is appropriate.
+
+lor  ( in1 in2 -- out )
+  Logical OR.
+
+LoseLevel  ( -- )
+  Ends all execution and results in loss of game.
+
+lsh  ( in shift -- out )
+  Left shift.
+
+lt  ( in1 in2 -- bool )
+  Test if first input is less than second input (unsigned).
+
+,lt  ( in1 in2 -- bool )
+  Test if first input is less than second input (signed).
+
+lxor  ( in1 in2 -- out )
+  Logical XOR.
+
+MaxInventory  ( number -- )
+  Results in an error and loss of game if the number of different
+  inventory items exceeds the given number, otherwise no effect.
+
+mod  ( in1 in2 -- out )
+  Unsigned divide in1 by in2 producing the remainder.
+
+,mod  ( in1 in2 -- out )
+  Signed divide in1 by in2 producing the remander.
+
+Move  ( dir -- bool ) **
+  Move this object in the given direction (which may be absolute or
+  relative to the current direction). The result will be true if the
+  move is successful or false if it failed. See the section about
+  movement for details.
+
+,Move  ( obj dir -- bool ) **
+  As Move but moves a specified object rather than necessarily this one.
+
+Move+  ( dir -- bool ) **
+  Similar to Move but adds Strength to Inertia without resetting Inertia.
+  (The reason this exists is for compatibility with a bug in EKS Hero
+  Mesh; you probably do not need to use this yourself.)
+
+,Move+  ( obj dir -- bool ) **
+  As Move+ but for a specified object.
+
+MoveNumber  ( -- number )
+  The current move number. This is initially zero, and is advanced after
+  each input phase (before the beginning phase).
+
+MoveTo  ( x y -- bool ) **
+  Teleports this object to the specified coordinates; the MOVING message
+  (and PLAYERMOVING if applicable) are sent to check if it is allowed.
+  This also updates the Distance variable, and will deal with arrivals and
+  departures, and send FLOATED and SUNK messages as appropriate.
+
+,MoveTo  ( obj x y -- bool ) **
+  As MoveTo but for a specified object, not necessarily this one.
+
+Msg  ( -- message )
+  The current message being processed.
+
+ne  ( in1 in2 -- bool )
+  As eq but the result is inverted (like "eq lnot").
+
+neg  ( in -- out )
+  Multiply by negative one.
+
+NewX  ( oldx dir -- newx )
+  Advance the number in the direction as though it is a X coordinate. If
+  the direction is north or south, leaves it alone, but if it is east or
+  west then it is increased or decreased by one.
+
+NewY  ( oldx dir -- newy )
+  Advance the number in the direction as though it is a Y coordinate.
+
+nip  ( x y -- y )
+
+ObjAbove  ( -- obj )
+  The object above this one (0 if this one is at the top). "Above" means
+  it overlaps this object, not upward on the screen (north).
+
+,ObjAbove  ( obj -- obj )
+  The object above the specified object (0 if there isn't any).
+
+ObjBelow  ( -- obj )
+  The object below this one (0 if this one is at the bottom). "Below"
+  means this object overlaps it, not downward on the screen (south).
+
+,ObjBelow  ( obj -- obj )
+  The object below the specified object (0 if there isn't any).
+
+ObjBottomAt  ( x y -- obj )
+  Find the object on the bottom at the specified location. The result will
+  be zero if that location is vacant or out of range.
+
+ObjClassAt  ( class x y -- obj )
+  Find the bottom-most object of the specified class at that location. If
+  there is no object of that class, then the result is zero. This function
+  will find objects with the VisualOnly flag set as well as clear. You may
+  specify zero instead of a class, in which case it finds nothing. Any
+  other number, or any other value that isn't a class, is an error.
+
+ObjDir  ( dir -- obj )
+  Find the top-most object in the cell one step in the specified direction
+  from this object.
+
+,ObjDir  ( obj dir -- obj )
+  Find the top-most object in the cell one step in the specified direction
+  from the specified object.
+
+ObjLayerAt  ( layers x y -- obj )
+  Find an object with the given CollisionLayers bits set at that location.
+  If you specify multiple bits, it finds one with any of those bits. (It
+  is not possible for there to be more than one such object.)
+
+ObjTopAt  ( x y -- obj )
+  Find the object on the top at the specified location. The result will be
+  zero if that location is vacant or out of range.
+
+PopUp  ( value -- )
+  Displays a popup message. Normally, the value is a string, but it can be
+  another type, and it will try to display it. If the text contains any \q
+  commands, then dismissing the popup message will send a KEY message to
+  the object which created the popup message. If there is already another
+  existing popup message, only the first one set up will be displayed, and
+  the others will be ignored. IgnoreKey also affects what happens when a
+  popup message is dismissed; see IgnoreKey for details.
+
+(PopUp <number>)  ( string args... -- )
+  Displays a popup message, like PopUp does. However, this one allows the
+  string to contain substitution codes; see the section below about what
+  substitution codes are allowed in popup messages. Each substitution code
+  consumes some number of arguments, from bottom to top. The number of
+  arguments must be 0 to 32.
+
+QueueTurn  ( key -- ) **
+  Queue another turn after this one, using the specified key code, which
+  must be a number from 0 to 255. The extra turn is not entered into the
+  replay list and does not increase MoveNumber, but otherwise will act
+  like any other turn. Popup messages are not removed; they will be
+  retained, and these extra turns execute the input phase as though there
+  is no popup quiz.
+
+ret  ( -- )
+  Exit the current subroutine. If this is a message block, it must either
+  leave the stack as it is, or leave it but with one extra value pushed
+  which will be the return value from the message call. (This is implied
+  at the end of a code block.)
+
+rot  ( x y z -- y z x )
+
+-rot  ( x y z -- z x y )
+
+rsh  ( in shift -- out )
+  Logical right shift.
+
+,rsh  ( in shift -- out )
+  Arithmetic right shift.
+
+Self  ( -- obj )
+  The reference to the current object.
+
+Send  ( message arg1 arg2 -- value )
+  Similar to ,Send but this object sends the message to itself.
+
+,Send  ( obj message arg1 arg2 -- value )
+  Send a message to the specified object.
+
+SendEx  ( message arg1 arg2 -- value )
+  Similar to ,SendEx but this object sends the message to itself.
+
+,SendEx ( obj message arg1 arg2 arg3 -- value )
+  Send a message to the specified object.
+
+SetInventory  ( class image value -- ) **
+  Sets an inventory item with the specified class and image number to the
+  specified value (which must be a number). If there is no inventory item
+  with that exact class and image, an inventory item will be added,
+  otherwise the existing one is updated to the new value.
+
+Sound  ( sound interruptflag -- )
+  Play a sound; if the interrupt flag is zero then it does not interrupt
+  existing sounds but otherwise it does. It is not an error if the values
+  of the arguments are not valid.
+
+swap  ( x y -- y x )
+
+Synchronize  ( slot startimage -- ) **
+  Start a synchronized animation. Give the slot number of the animation,
+  and the starting image number. The length and speed are defined in a
+  global definition, and the animation is always a non-oscillating loop.
+
+Trace  ( obj arg1 arg2 -- )
+  If tracing is enabled, sends the three values and some other information
+  on stdout. If tracing is disabled, does nothing. This is intended to be
+  used for debugging class codes.
+
+tuck  ( x y -- y x y )
+
+VolumeAt  ( x y -- volume )
+  Finds the greatest volume among objects at the specified location.
+
+WinLevel  ( -- )
+  Ends all execution and accepts the input sequence that resulted in the
+  current game state as a valid solution.
+
+XDir  ( dir -- newx )
+  Finds the X coordinate of the cell in the specified direction.
+
+,XDir  ( obj dir -- newx )
+  Finds the X coordinate of the cell in the specified direction of the
+  specified object.
+
+YDir  ( dir -- newy )
+  Finds the Y coordinate of the cell in the given direction.
+
+,YDir  ( obj dir -- newy )
+  Finds the Y coordinate of the cell in the specified direction of the
+  specified object.
+
+
+=== Block instructions ===
+
+These are block flow controls. They include bodies of other instructions.
+
+begin <body> again  ( -- )
+  Executes <body> an unlimited number of times; it will only stop once some
+  command inside of the loop jumps out, returns, or results in an error.
+
+begin <body> until  ( -- ) ( bool -- )
+  Executes <body>, and then pops one boolean from the stack; if false, then it
+  will be repeated, but if true then it stops.
+
+begin <part1> while <part2> repeat  ( -- ) ( bool -- ) ( -- )
+  Executes <part1>, and then pops one boolean from the stack; if true, then it
+  will execute <part2> and then repeat; if false then it jumps out of the loop
+  and does not execute <part2>.
+
+for <body> next  ( upflag x y -- ) **
+  It starts by saving the inputs into an internal variable (each class has its
+  own such variables, and they are separate for each instance of the word "for"
+  in the program, but they will interfere if the same loop is reentrant on the
+  same object or other objects of the same class), and then resetting the Done
+  flag of all objects at the given (x,y) coordinates. If upflag is false, then
+  it starts at the top, and if true, starts at the bottom. At the beginning of
+  the <body>, the found object is on the stack; you can then use or store it.
+  Once "next" is reached, it finds the next object and goes back.
+
+if <truepart> [el <cond> if <truepart> ...] [else <falsepart>] then  ( bool -- )
+  Takes a boolean value from the stack. If true, then <truepart> is executed;
+  otherwise it tries the other parts; "el" means to execute <cond> and take
+  another boolean, and continue; "else" means always do this if none of the
+  previous parts match.
+
+
+=== Substitution codes ===
+
+%c
+  Display a single character whose code is the low 8-bits of the value.
+
+%d
+  Display a signed decimal number.
+
+%i
+  Display a picture. Consumes two arguments, being first a class and then
+  the image number. If either argument is not valid, displays nothing. The
+  picture may take up multiple lines of space; the lines will be moved
+  farther apart to make room if necessary.
+
+%s
+  Display a string. If the value is not a string, it will display it as
+  whatever type it is.
+
+%u
+  Display a unsigned decimal number.
+
+%x
+  Display a unsigned hexadecimal number in lowercase.
+
+%X
+  Display a unsigned hexadecimal number in uppercase.
+
+%%
+  Display a percentage sign; does not consume an argument.
+
+
+=== Messages ===
+
+This section describes when the various standard messages are sent to
+objects, and what return values are expected. (Do not confuse CREATE with
+CREATED or DESTROY with DESTROYED; they have different purposes.)
+
+ARRIVED
+  
+
+BEGIN_TURN
+  Sent to all objects during the beginning phase (the phase after the
+  input phase). From is an object with the Player flag (if there is any),
+  Arg1 and Arg2 are the X and Y coordinates of that object, and Arg3 is
+  the most recent return value from a KEY message.
+
+COLLIDE
+  Received when this object is trying to move into a location where there
+  is a collision, so it can't move there. Of the return value, bit0 means
+  to prevent the movement (even if the objects are moved out of the way or
+  destroyed in order to make room), bit1 means to not send any COLLIDEBY
+  messages, and bit2 means to pretend the move attempt was successful even
+  if it isn't successful. Even if bit0 is set, that won't prevent sending
+  COLLIDEBY messages unless bit1 is also set.
+
+COLLIDEBY
+  Received when another object is trying to move into the location of this
+  object or trying to be created in the same location as this object, if
+  there is a collision in the CollisionLayers values of those two objects.
+  Of the return value, bit0 means to prevent the movement, bit1 means to
+  not send any more COLLIDEBY messages, bit2 means to pretend the movement
+  attempt is successful even if it isn't (there is no effect for creating
+  objects; this bit is meaningful only for moves), and bit4 means that if
+  necessary, it will try to destroy this object to make room.
+
+CREATE
+  Sent when the object is created by the Create instruction. This is done
+  after the object is created, but before sending any other messages. The
+  From is the object that created it. The return value will be used as the
+  Arg3 of the SUNK and CREATED messages it might send if appropriate.
+
+CREATED
+  
+
+DEPARTED
+  
+
+DESTROY
+  Received when the object is about to be destroyed. Arg3 is the reason:
+  0 for the Destroy or ,Destroy instruction, 1 due to this object moving
+  into something sharp, 2 due to something sharp moving into this one,
+  or 3 for a conflict with CollisionLayers. The return value is false to
+  allow it to be destroyed or true to keep the object.
+
+DESTROYED
+  
+
+END_TURN
+  
+
+FLOATED
+  
+
+HIT
+  Indicates that this object is trying to move into another one; that
+  other object is the From value of the message. Arg1 and Arg2 are the
+  X and Y coordinates of that object, and Arg3 is the current hit value
+  (see below). The return value is ORed with the hit value to make the
+  new hit value.
+
+HITBY
+  Indicates that this object was hit by another object that was trying to
+  move, where From is the object trying to move, Arg1 and Arg2 are the X
+  and Y coordinates of that object, and Arg3 is the current hit value, and
+  the return value is ORed with the hit value to make the new hit value.
+
+INIT
+  Sent to all objects when the level is initialized. Objects which are
+  created during this time will not receive INIT messages, but they will
+  receive POSTINIT messages.
+
+JUMPED
+  Sent after a successful teleport by the JumpTo instruction. Arg1 and
+  Arg2 are the previous X and Y coordinates, and Arg3 (not From) is the
+  object that caused the move.
+
+KEY
+  During the input phase, it sends this message either to all objects with
+  the Input flag set, or to only the current quiz object if there is one
+  (whether or not it has the Input flag). Arg1 is the key code (the Key
+  instruction can also be used), Arg2 is the return value of the previous
+  KEY message (0 for the first one), and Arg3 is zero for normal input or
+  one for a quiz. The return value is passed as Arg2 for the next object.
+
+LASTIMAGE
+  
+
+MOVED
+  
+
+MOVING
+  Called when the object is about to be moved (whether due to Move,
+  MoveTo, JumpTo, or any other reason). From is the object that caused
+  the move, and Arg1 and Arg2 are the target X and Y coordinates. If the
+  return value is true, then the move is aborted.
+
+PLAYERMOVING
+  If an object with the Player flag is about to move, then after the
+  MOVING message is sent, PLAYERMOVING is sent to all objects. From is
+  the object which is moving, Arg1 and Arg2 are where it will be moved to,
+  and Arg3 is the From of the MOVING message. If the return value is true,
+  then the move is aborted.
+
+POSTINIT
+  After all INIT messages are sent when the level is initialized, then it
+  will send POSTINIT to all objects. Objects which are created during this
+  time will not receive POSTINIT messages.
+
+SUNK
+  
+
+
+=== Hit values ===
+
+This section describes the bits of the return value of the HIT and HITBY
+messages; these values are also used as the Arg3 of those messages.
+
+Some descriptions below are marked with an asterisk. If the Compatible
+flag is set for the object that returned this value, then all bits with
+the asterisk in the below descriptions are masked out.
+
+bit0
+  Do not send the HITBY message to the target object.
+
+bit1
+  Do not destroy either object due to hardness/sharpness.
+
+bit2
+  Do not attempt to shove the target object.
+
+bit3
+  Abort the move attempt immediately. Do not send any more HIT or HITBY
+  messages, do not check hardness/sharpness, and do nothing else either.
+
+bit4
+  Do not send the HITBY message to the target object or to any further
+  objects at the target location.
+
+bit5
+  Do not destroy either object due to hardness/sharpness, nor should any
+  further objects at the target location be destroyed due to sharpness.
+
+bit6
+  Do not attempt to shove the target object, nor attempt to shove any
+  other objects at the target location.
+
+bit7 *
+  Do not attempt sliding.
+
+bit8
+  Abort after sending the HITBY message.
+
+bit9
+  Abort after hardness/sharpness checking.
+
+bit10
+  Abort after attempting shoving.
+
+bit11
+  Set by the game engine if the move attempt has been restarted due to
+  bit15 being set during the previous attempt.
+
+bit12 *
+  If the move attempt fails, pretend it was successful, even though the
+  object hasn't actually moved. This means that the result of Move will
+  be 1 and that the MOVED message will trigger; it does not trigger any
+  ARRIVED, DEPARTED, FLOATED, or SUNK, nor does it set Distance.
+
+bit13 *
+  Abort before actually moving the object and before trying sliding.
+
+bit14 *
+  Do not set the Moved flag even if successful.
+
+bit15
+  Try again after trying shoving (whether or not the shoving is
+  successful). If it tries to shove an object and it is successful, then
+  it will automatically set this bit and automatically try again.
+
+bit16
+  Set by the game engine if it is attempting sliding.
+
+bit17 *
+  Do not actually move the object. It still does everything else, but when
+  it is time to move the object, just assume it is successful without even
+  trying. Things that Move and JumpTo have in common aren't done.
+
+bit18 *
+  Do not restart, even if bit15 is set.
+
+bit19
+  Set by the game engine if the requested movement is diagonal.
+
+bit20 *
+  If set, then when the movement attempt is restarted (due to bit15 set),
+  the direction will be reread from the object's Dir variable.
+
+bit21 *
+  Allows the object to move regardless of Height.
+
+bit22 *
+  Prevents movement regardless of Height, but may still allow sliding.
+
+bit23 *
+  Reserved for future.
+
+bit24 *
+  Reserved for future.
+
+bit25 *
+  Reserved for future.
+
+bit26
+  Available for your own use; preserved across restarts.
+
+bit27
+  Available for your own use; preserved across restarts.
+
+bit28
+  Available for your own use.
+
+bit29
+  Available for your own use.
+
+bit30
+  Available for your own use.
+
+bit31
+  Available for your own use.
+
+
+=== Compatibility ===
+
+Compatible objects have the following differences from the default:
+
+* VisualOnly implies Stealthy.
+
+* If the current quiz object is Compatible, The effect of "-1 FlushObj"
+is implied at the beginning of the turn (before the input phase), except
+that Inertia is not reset.
+
+* Some bits are masked out of the return value from HIT and HITBY.
+
+* Many variables are limited to 16-bits.
+
+* Moving objects is not allowed during LASTIMAGE processing.
+