bindings.doc

This document describes the format of the key/mouse bindings and the list
of the available commands that the binding can be set to.

The resource name for a binding consists of the following in order:
* The puzzle set name (can be "?" to apply to all puzzle sets)
* One of "editClick", "editKey", "gameClick", or "gameKey"
* Zero or more components for modifier keys (see below)
* Key name (or mouse button)

You cannot use "?" for keys, mouse buttons, or modifiers. You may,
however, use "?" in place of the edit/game selection.

Valid modifier keys are:
* shift
* ctrl
* alt
* meta
* numLock (cannot be combined with other modifiers except shift)

Most key names are lowercase, except alphabetic keys which are uppercase.
Mouse button names are "left", "middle", or "right".

The value specifies what action. The action can be one of the below:

It can be + (to advance) or - (to rewind) or = (to restart) followed by
the number of moves.

It can be ! followed by a system command.

It can be ' followed by a Hero Mesh key name, to input a move.

It can be ^ followed by one more character, to execute a command which
has ^ as the first character; if it requires an argument, the clicked
location will be used if it is clicked with the mouse.

Finally, it can be a single SQL statement. The result rows are treated as
commands to execute, where the first column is a string of two characters
(the possibilities are explained below) and the rest of the columns (if
any) are the arguments. You can use NULL for trailing arguments if you do
not need that many arguments.

SQL statements can also contain host parameters. The valid host parameters
are $X (clicked X coordinate), $Y (clicked Y coordinate), $LEVEL (level
order number), $LEVEL_ID (level ID number), $KEY_XY (ask for X and Y
coordinates, and produce a single number like the XY function does), and
any name with : at first to ask the user for the value to use.


=== Game commands ===

'' ' <key>
  Input a move.

'+ ' <count>
  Advance that many moves in the replay list.

'- ' <count>
  Rewind that many moves.

'= ' <count>
  Restart and replay that many moves.

'^<'
  Rewind to mark.

'^>'
  Replay to mark.

'^-'
  Delete one move.

'^+'
  Toggle insertion mode. Insertion mode is automatically reset when
  restarting a level or when accessing a different level.

'^?'
  Displays some debugging information. (What information is displayed and
  how it is formatted may be changed (or possibly removed entirely) in
  future; you should rely on it.)

'^D'
  Delete all moves forward.

'^I'
  Toggle the inventory/move-list display.

'^L'
  List of levels.

'^M'
  Set the replay mark position.

'^S'
  If the level is in a won state, record the solution.

'^T'
  Display the level title popup.

'^d' <location>
  Display the pop-up help text of the object at the location.

'^g'
  Display values of global variables.

'^n' <location>
  List objects at the specified coordinates in the bizarro world, to
  examine their values.

'^o' <location>
  List objects at the specified coordinates, to examine their values.

'^p'
  Start or stop slow replay. Any move input also interrupts slow replay.

'^s'
  Toggle solution replay.

'^x'
  Cancel dead animation.

'lo' <location>
  Flash the specified location briefly (same as the LocateMe instruction in
  the class codes).

'ls' <slot>
  Load save state slot (0 to 7).

'md' <number>
  Multiple deletion. No effect if the number is zero or negative. If the
  number is 1 then it is the same as the '^-' binding, while a sufficiently
  large number is the same as the '^D' binding.

'mi' <command>
  Import a move list. The argument is a operating system command, that
  when executed will write the move list to stdout, with one byte per
  move (the Hero Mesh key codes).

'ml' <blob>
  Load a move list from a SQL blob.

'mx' <command>
  Export a move list. The argument is a operating system command that
  will receive the move list (in the same format as above) on stdin.

'rS' <number>
  Set replay speed to the specified number (1 to 255).

'rs' <number>
  Adjust replay speed by the specified number (negative to make faster, or
  positive to make slower; zero leaves it unchanged).

'ss' <slot>
  Save save state slot (0 to 7).

'xs' <slot>
  Exchange save state slot (0 to 7).

'xy' <x> <y>
  Input a move using coordinate input. Coordinates are 1-based.


=== Editor commands ===

'^I'
  Level index editor.

'^N'
  Add a new level (after the last one). The new level has the same
  dimensions as the current level, but contains no objects or strings,
  and the title is set to "New Level".

'^S'
  Save level.

'^T'
  Edit the level title.

'^Z'
  Cancel selection rectangle.

'^a' <location>
  Add an object with the current MRU values to that location, if there
  is not already another object of the same class there.

'^c'
  Display the class selection menu.

'^e'
  Edit the currently selected MRU values. (You can only edit the direction
  and the Misc values (1 to 3), not the class and image; to edit the class
  and image, use the class selection menu.)

'^s'
  Display the list of level strings.

'^u' <location>
  Add an object with the current MRU values to that location, even if
  there is already another object of the same class at that location.

'^w'
  Swap the normal world with the bizarro world.

'^<' <location>
  Set top corner of selection rectangle.

'^>' <location>
  Set bottom corner of selection rectangle.

'am' <class> <image> <misc1> <misc2> <misc3> <dir>
  Add a MRU and select the added MRU.

'em' <object>
  Edit the Misc/Dir of an existing object.

'ex' <command>
  Export a level (given the operating system command to receive the
  exported data). See export.doc for details.

'im' <command>
  Import a level (given the operating system command to produce the data
  to be imported). See export.doc for details.

'lc' <number>
  Set the level code number. This is a 16-bit number which can be used in
  the class codes of your puzzle set for whatever purpose you wish; the
  game engine does not use this value itself.

'lt' <blob>
  Set the level title. The value must be unescaped; you can use the
  HEROMESH_UNESCAPE function to do this.

'lv' <number>
  Set the level version number. This number is used to detect the validity
  of stored solutions. Normally, you do not need to set this; it will do
  so automatically once the level is saved, if any changes have been made
  which might invalidate the solution (although it doesn't know for sure,
  so there are false positives). However, you can set this deliberately by
  yourself, in case you know that the solution remains valid; if you do
  set it by yourself just before saving, it will use your value rather
  than setting it automatically.

'mm' <class> <image> <misc1> <misc2> <misc3> <dir>
  Modify a MRU. Any values specified as null means no change.

'mR' <number>
  Select a relative MRU. Negative numbers move up the list, and positive
  numbers move down the list.

'mr' <number>
  Select a MRU, given the MRU number (0 to 31; the top is zero).

're' <width> <height>
  Remove all objects from the level and resize the level. The minimum size
  is 1x1 and the maximum size is 64x64.


=== Commands available in game and editor ===

'^E'
  Switch to the editor.

'^P'
  Switch to the game play.

'^Q'
  Quit.

'^Y'
  Sound test. (Does nothing if sound is not configured.)

'^l' <location>
  Draw lines horizontal, vertical, and diagonal, from the clicked location,
  until the mouse button is released.

'go' <level>
  Go to the specified level. If the level number is negative, then it is
  a level order number, otherwise it is a level ID number.


=== Mode-independent commands ===

':!' <command>
  Execute a system command.

':;'
  Ignore the rest of the result rows of this SQL statement.

':?' <text>
  Write text to stdout.

':m' <text>
  Display text on the screen, wait to push enter to continue.

':s'
  Write memory allocation status to stderr.

':x'
  Ask for a SQL statement, execute it, and display the results.