The class definition file is a plain text file, which conists of a stream of tokens. Encoding is with PC character set (a superset of ASCII, although it is recommended to just use ASCII and to escape any non-ASCII characters).
The possible kind of tokens are:
- Open: Write ( to begin a block.
- Close: Write ) to end a block.
- Plain name: A plain word without the prefix to indicate what kind (although , and = prefixes may still be possible). The set of possible plain names is fixed; you cannot define your own.
- Number: A 32-bit integer. Can be positive or negative (with - prefix), or can be hexadecimal with 0x at first, or octal with 0o at first.
- String: A quoted string. See also formatting controls. Any backslashes and quotation marks must be escaped, and there should not be unescaped line breaks.
- Class: A name with $ at first. Class names are global, are user-defined, and do not need to be declared before they are used (but must still be declared in the same file).
- User sound: A name with ! at first. Must be a sound name in the .xclass file, without the .WAV suffix.
- User local variable: A name with % at first. Local variable names are scoped to the definition of a class, and need not ever be declared.
- User global variable: A name with @ at first. Global, and need not be declared.
- User message: A name with # at first. Global, and need not be declared.
- Label: A name with : at first. Scoped to the definition of a class. Must exist within that class (although it can be in a different message block) to jump to it.
- User function: A name with & at first. Global, and must be declared if used.
- Key name: A name with ' at first. You can't define your own; see Hero Mesh key name for a list. These are not necessarily bound to the same physical keys that they are named, however.
Also:
- Names: All names are case-sensitive. Valid characters include all digits 0 to 9, letters A to Z and a to z, plus, minus, underscore, question mark, period, forward slash, and asterisk.
- Prefixes: Many kind of tokens also accept a = and/or , prefix. These are used as modifiers to indicate the use in a different case.
- Comments: Start with ; (outside of a string literal) and up to the next line break is a comment.
- Macros: See Preprocessor.
Please note that SQL codes cannot be used in this file. SQL is used internally and in user configuration files, and may be entered by the user at runtime, but the rules of the game cannot be defined by use of SQL; it has its own programming language for defining the rules of the game, instead.
Top level blocks
At the top level (outside of any other blocks, and after the preprocessor has run, if any), the following kind of blocks are possible (all must be in parentheses):- Class definition: The first token is the class name. See below section for details. Each class must be defined only once.
- Global user variable: The first token is the global variable name, and second is the initial value (a constant). If not specified, the initial value is zero. Example: (@money 100)
- Background color: Something like (Background 1) but replace 1 with the background colour from 0 to 255 (the default value is 1, which is normally black).
- Max animation steps: Something like (Animate 32) but replace 32 with the maxinum number of animation steps allowed, from 1 to 256. The default value is 32.
- Volume: Something like (Volume 10000) but instead of 10000 you can specify a different number; the default value is 10000. Any number can be used; this determines the volume limit to move diagonally between objects. See documentation about moving objects for further details.
- Default message handler: A message block like in a class definition, but no local user variables are allowed. If the class does not include this message lock, then this one is used by default. If no message block is defined at all, then the message does nothing and always returns zero.
- Function: A function definition. The first token is a user function name (such as &AddScore), and then the instructions for that function. No local user variables are allowed.
Constants
Where a constant value (of any type) is expected, you may use any of the following:- Number
- Direction
- String
- Key code
- Class
- Message
- Sound
- Bit constant
Class definition blocks
The class definition block starts with the class name, and then the various things inside, which can be:- (Arrivals): Sets the relative positions to this object that this object cares about other objects moving into. Needs either the keyword InPlace, or twenty-five numbers each of which is either zero or one. InPlace means this object's position only. Otherwise, 0 means don't care and 1 means does care, making a 5x5 grid with this object in the middle.
- (Climb): Put a number. Defines how high the object can climb; see the documentation about moving objects for details about what this does.
- (CollisionLayers): Put one or more 8-bit numbers and/or bit constants; they are bitwise ORed together. The default value is zero. If the game engine tries to place an object into the location of another object with any shared bits set in the CollisionLayers value for any reason (normal movement, teleportation, or creation), it is prevented, and the COLLIDING and/or COLLIDE messages are sent.
- Compatible: Enable better compatibility with Hero Mesh, including that some standard variables are now limited to sixteen bits. For new puzzle sets, it is normally better to avoid this flag (although there may be some cases where you will want to use it).
- ,Compatible: Similar to Compatible but does not limit variables to sixteen bits.
- (DefaultImage): After the word DefaultImage is some numbers, or () with nothing in between or you can have a range by using () with two numbers in between. This defines which images are available for selection in the editor. If you write (DefaultImage ()) then this class is not available to place objects in the editor at all. If the DefaultImage command is not included, all images can be used. This only affects the editor, and the level file format.
- (Density): Put a number. Defines the density of the object. If there are multiple objects at the same location, this defines which ones are on top (meaning not obscured by others; does not mean its Y coordinate differs) and on bottom (meaning may be obscured by other objects) and the stuff in between. The object with the lowest density is on top, and highest density on bottom.
- (Departures): See Arrivals; this is similar, but sets the departure positions it cares about instead instead of arrival positions.
- (EditorHelp): After EditorHelp is one or more strings. Each is a line of help text for the composer. This does not affect game rules at all.
- (Hard): Either a 16-bit number, or pairs (each a parenthesized block) of a direction and a 16-bit number. Directions must be E, N, W, or S. If it is a single number, the same number is applicable for all directions. It sets the hardness of each side of the object; this is used together with sharpness to determine if any objects are destroyed when one object moves into another (see documentation about moving objects for further details).
- (Height): Put a number. Defines the height of the object; see the documentation about moving objects for details about what this does.
- (Help): After Help is one or more strings. Each is a line of help text for the player. This does not affect game rules at all.
- (Image): After the word Image is several strings, which are the name of images in the .xclass file (without the .IMG suffix). Those are the pictures used as the images of this class; the first one listed is image number zero.
- Input: Causes the KEY message to be sent to all objects of this class when a move is played and no popup quiz is waiting.
- Invisible: Objects of this class are invisible at runtime. (Clicking on objects will still reveal them, and they still have all interactions with other objects. They are also visible in the editor.)
- (Misc4): After the word Misc4 is one or more numbers; bit constants are also allows. Defines the Misc4 value (a 32-bit number) for this class as the bitwise OR of all numbers specified. The game engine does not use the Misc values; it is for your own use.
- (Misc5): Like Misc4 for sets Misc5 instead.
- (Misc6): Like Misc6 for sets Misc5 instead.
- (Misc7): Like Misc7 for sets Misc5 instead.
- Player: Indicate that the object of this class is the player object. (Affects the PLAYERMOVING and BEGIN_TURN messages, as well as possibly some user interface elements. This does not affect the KEY message; see Input for that.)
- Quiz: Hide values of local variables from the player by default. Can be overridden in the user configuration file. Puzzles should generally avoid using this, since it is supposed to be a game of complete information. (As suggested by the name, the intention of this flag is for use with the Quiz object from Hero Defiant.)
- (Shape): Either a 2-bit number, or pairs (each a parenthesized block) of a direction and a 2-bit number. Directions must be E, N, W, or S. If it is a single number, the same number is applicable for all directions. Sets the shape, which is used to allow one object to slide off of another if they hit each other while moving. See documentation of moving objects for further details about what this does.
- (Sharp): This is like the Hard command but sets sharpness instead of hardness.
- Shovable: This object is pushable in any direction (if the object pushing it is strong enough).
- (Shovable): Specifies which directions it can be pushed. After the word Shovable is either a 8-bit number, or can be one or more directions, which can be E, N, W, and S (diagonal shoving is not allowed). (It is recommended that you do not use a number; it is provided because some Hero Mesh puzzle sets set some bits that aren't supposed to be set, for some reason.)
- Stealthy: If this object moves, does not cause arrival and departure triggers. (Does not suppress any other interactions.)
- (Strength): Put a number. Defines the strength of the object; see the documentation about moving objects for details about what this does.
- (SUBS): A block of program instructions which is not associated with a message. It is not really that helpful (since you can use labeled blocks instead); it is provided in order to convert Hero Mesh puzzles into Free Hero Mesh. (In Hero Mesh, the SUBS block is mandatory, even if it is empty. In Free Hero Mesh, it can safely be omitted.)
- (Temperature): After the word Temperature is a number. Defines the Temperature attribute of this class. Like the Misc values, it is not used by the game engine and is only for your own use. (By convention, this is 100 more than the equivalent Celsius temperature, and 125 represents room temperature. However, you are not required to use this convention in your own puzzles.)
- UserState: Does nothing, but can be used for your own purpose.
- VisualOnly: Most interactions of this object with other objects are suppressed. (The original intention was that this is used for decorations that do not affect the game play; however, it has other uses too.) If Compatible is also specified, then VisualOnly implies Stealthy (but does not actually set that flag unless you do so explicitly).
- (Volume): Put a number. Defines the volume of the object; see the documentation about moving objects for details about what this does.
- (Weight): Put a number. Defines the weight of the object; see the documentation about moving objects for details about what this does.
It can also include blocks of program instructions, which can start with a label, a message name (either built-in or user message), or the SUBS keyword.