ADDED bindings.doc Index: bindings.doc ================================================================== --- bindings.doc +++ bindings.doc @@ -0,0 +1,101 @@ +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), and any name with : at first +to ask the user for the value to use. + + +=== Game commands === + +'' ' + Input a move. + +'+ ' + Advance that many moves in the replay list. + +'- ' + Rewind that many moves. + +'= ' + Restart and replay that many moves. + +'^o' + List objects at the specified coordinates. + + +=== Editor commands === + +'^c' + Display the class selection menu. + + +=== Mode-independent commands === + +':!' + Execute a system command. + +':;' + Ignore the rest of the result rows of this SQL statement. + +':?' + Write text to stdout. + +':m' + Display text on the screen, wait to push enter to continue. + +':x' + Ask for a SQL statement, execute it, and display the results. + +'^E' + Switch to the editor. + +'^P' + Switch to the game play. + +'^Q' + Quit. + +'go' + 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. + ADDED sql.doc Index: sql.doc ================================================================== --- sql.doc +++ sql.doc @@ -0,0 +1,142 @@ +This document explains the SQL functions and SQL tables which are +available for the user customization in Free Hero Mesh. (You cannot +use SQL to define the rules of the game.) + + +=== Functions === + +Asterisks denote aggregate/window functions. + +BASENAME() + The base name, which is a copy of the first command-line argument (not + counting the switches or the program name). + +CLASS_DATA(id,info) + Returns data about a class. + +CVALUE(number) + Makes a game value of type 'class', given the class number. + +HEROMESH_ESCAPE(blob) + Converts blob representation of a game string into escaped format. + +HEROMESH_TYPE(value) + The type of a game value, given as a 64-bit integer. The types are + 'class', 'number', 'string', 'object', and 'sound'. + +HEROMESH_UNESCAPE(text) + Converts escaped representation of a game string into text format. + +LEVEL() + The one-based order number of the current level. + +LEVEL_CACHEID() + The cache ID number of this level in the user cache table. + +LEVEL_ID() + The ID number of the current level. + +LEVEL_TITLE() + The title of the current level, as a blob. + +LOAD_LEVEL(level_id) + Only valid when Free Hero Mesh is invoked with the -x switch. Loads + the level with the specified ID number. + +MVALUE(number) + Makes a game value of type 'message'. + +MODSTATE() + The SDL keyboard modifier state. + +MOVENUMBER() + Return the number of moves executed so far since the level restarted. + +NVALUE(number) + Makes a game value of type 'number'. Same as ZERO_EXTEND. + +OVALUE(number) + Makes a game value of type 'object'. The argument is the ID number of + the object in the OBJECTS table. + +PICTURE_SIZE() + Tell you the picture size. + +READ_LUMP_AT(offset,ptr) + Used internally; there is no way to use this in user SQL codes. + +RESOURCE(...) + Given the list of resource names, read a value from the X resource + manager. Returns null if there is no such resource value. + +SIGN_EXTEND(number) + Sign extends a 32-bit number to 64-bits. + +TRACE_OFF() + Disables tracing when called. + +TRACE_ON() + Enables tracing when called. + +ZERO_EXTEND(number) + Zero extends a 32-bit number to 64-bits. Same as NVALUE. + + +=== Tables === + +Asterisks denote virtual tables. + +CREATE TABLE "CLASSES"("ID" INTEGER PRIMARY KEY, "NAME" TEXT, "EDITORHELP" +TEXT, "HELP" TEXT, "INPUT" INT, "QUIZ" INT, "TRACEIN" INT, "TRACEOUT" INT, +"GROUP" TEXT, "PLAYER" INT); * + A list of classes in the current puzzle set; mostly read-only. Only + QUIZ, TRACEIN, and TRACEOUT are writable. If TRACEIN is true then it + will trace messages received by this class (if tracing is enabled). If + TRACEOUT is true then it will trace messages sent by this class (if + tracing is enabled). + +CREATE TABLE "MESSAGES"("ID" INTEGER PRIMARY KEY, "NAME" TEXT, "TRACE" +INT); * + The list of messages in the current puzzle set; mostly read-only. Only + TRACE is writable; if true, this message will be traced. + +CREATE TABLE "OBJECTS"("ID" INTEGER PRIMARY KEY, "CLASS" INT, "MISC1" INT, +"MISC2" INT, "MISC3" INT, "IMAGE" INT, "DIR" INT, "X" INT, "Y" INT, "UP" +INT, "DOWN" INT, "DENSITY" INT HIDDEN); * + List of objects. Read-only during the game, writable in the editor. + CLASS is a class number (the ID in the CLASSES table), DIR is the + direction (where 0 is east, 7 is southeast), and MISC1, MISC2, MISC3 + are the game values for the initial Misc values of this object; they + must be numbers, classes, messages, or strings. Once an object is + created, you cannot change its class; you must delete it and then add + a new object of the correct class. DENSITY is read-only, but you can + use ORDER BY DENSITY to sort in the stacking order of the objects. + UP and DOWN are also read-only. + +CREATE TEMPORARY TABLE "PICTURES"("ID" INTEGER PRIMARY KEY, "NAME" TEXT +COLLATE NOCASE, "OFFSET" INT); + List of all pictures available in this puzzle set. + +CREATE TABLE "USERCACHEDATA"("ID" INTEGER PRIMARY KEY, "FILE" INT, +"LEVEL" INT, "NAME" TEXT COLLATE NOCASE, "OFFSET" INT, "DATA" BLOB, +"USERSTATE" BLOB); + Contains the user cache data for the .level and .solution files of each + puzzle set, in order to speed up loading and saving. The DATA will be + null unless the data has changed, in which case the new data is stored + here; it will later rewrite the Hamster archive with the new data and + then it will be set to null again. USERSTATE contains user data such as + the list of moves made by the player. FILE is the ID in the user cache + index, and indicates which Hamster archive file this lump belongs to. + +CREATE TABLE "USERCACHEINDEX"("ID" INTEGER PRIMARY KEY, "NAME" TEXT, +"TIME" INT); + The user cache index; contains one record for each .level and .solution + file of all puzzle sets which have been loaded. NAME is the full path, + and TIME is the UNIX timestamp. If you want to delete a record, then + you should also delete all records from USERCACHEDATA whose FILE value + is the same as the ID value in this table for which it is deleted. You + should not touch it while Free Hero Mesh is running, though. + +CREATE TEMPORARY TABLE "VARIABLES"("ID" INTEGER PRIMARY KEY, "NAME" TEXT); + List of all global and local user variables used in the game. +