diff options
author | Manoj Srivastava <srivasta@debian.org> | 2014-05-14 23:54:09 -0700 |
---|---|---|
committer | Manoj Srivastava <srivasta@debian.org> | 2014-05-14 23:54:09 -0700 |
commit | 4f8b58cc5366bfc2ea3b56fe6ff0443464d10f0f (patch) | |
tree | a0a9cad00e7916b9a97e14831fb362f21871cbef /lib/help/lua_util.txt |
tome (2.3.11-ah-2) unstable; urgency=low
* Modified the install paths to deploy to the FHS compliant
/usr/games/tome and /var/games/tome, as we have always done
* This is a major change, and includes theming. Some of the options have
changed. Because of this, the manual page has been removed; there is a
command line help option and in game help until the manual page is
rewritten.
# imported from the archive
Diffstat (limited to 'lib/help/lua_util.txt')
-rw-r--r-- | lib/help/lua_util.txt | 898 |
1 files changed, 898 insertions, 0 deletions
diff --git a/lib/help/lua_util.txt b/lib/help/lua_util.txt new file mode 100644 index 00000000..8886a2b4 --- /dev/null +++ b/lib/help/lua_util.txt @@ -0,0 +1,898 @@ +|||||oy + +#####R /----------------------------------------\ +#####R < util.pkg functions helper file > +#####R \----------------------------------------/ + +---------------------------------------------------------------------- + +#####R=== bst === + +#####GDeclaration + s32b bst(s32b what, s32b t); + +#####GFile + util.c + +#####GComment +/* + * Break scalar time + */ + +#####GDescription +Return the minute, hour, day, or year for turn "t". One turn takes 7.5 +seconds. + +#####GParameters +> "what" is the unit to be returned and must be one of + MINUTE (number of turns per minute, which is 8) + HOUR (number of turns per hour, which is 480) + DAY (number of turns per day, which is 11,520) + YEAR (number of turns per year, which is 4,204,800) +> "t" is the number of turns. + +---------------------------------------------------------------------- + +#####R=== path_build === + +#####GDeclaration + errr path_build(char *buf, int max, cptr path, cptr file); + +#####GFile + util.c + +#####GComment +/* +* Create a new path by appending a file (or directory) to a path +* +* This requires no special processing on simple machines, except +* for verifying the size of the filename, but note the ability to +* bypass the given "path" with certain special file-names. +* +* Note that the "file" may actually be a "sub-path", including +* a path and a file. +* +* Note that this function yields a path which must be "parsed" +* using the "parse" function above. +*/ + +#####GDescription +Append file "file" to path "path" and return the result in "buf". The +length of "buf" is a maximum of "max" characters. If "file" starts +with '~' then return "file". If "file" starts with the path separator +and the path separator is not blank then return "file". If there is no +path then return "file". Otherwise return "path" + path separator + +"file". The path separator is defined in "H-config.h". + +#####GParameters +> "buf" contains the new path. +> "max" is the maximum number of characters allowed in "buf". +> "path" is the original path. +> "file" is the original file. + +---------------------------------------------------------------------- + +#####R=== move_cursor === + +#####GDeclaration + void move_cursor(int row, int col); + +#####GFile + util.c + +#####GComment +/* +* Move the cursor +*/ + +#####GDescription +Move the cursor to row "row" and column "col". + +#####GParameters +> "row" is the row the cursor is to be moved to. +> "col" is the column the cursor is to be moved to. + +---------------------------------------------------------------------- + +#####R=== inkey === + +#####GDeclaration + char inkey(void); + +#####GFile + util.c + +#####GComment +/* +* Get a keypress from the user. +* +* This function recognises a few "global parameters". These are variables +* which, if set to TRUE before calling this function, will have an effect +* on this function, and which are always reset to FALSE by this function +* before this function returns. Thus they function just like normal +* parameters, except that most calls to this function can ignore them. +* +* If "inkey_xtra" is TRUE, then all pending keypresses will be flushed, +* and any macro processing in progress will be aborted. This flag is +* set by the "flush()" function, which does not actually flush anything +* itself, but rather, triggers delayed input flushing via "inkey_xtra". +* +* If "inkey_scan" is TRUE, then we will immediately return "zero" if no +* keypress is available, instead of waiting for a keypress. +* +* If "inkey_base" is TRUE, then all macro processing will be bypassed. +* If "inkey_base" and "inkey_scan" are both TRUE, then this function will +* not return immediately, but will wait for a keypress for as long as the +* normal macro matching code would, allowing the direct entry of macro +* triggers. The "inkey_base" flag is extremely dangerous! +* +* If "inkey_flag" is TRUE, then we will assume that we are waiting for a +* normal command, and we will only show the cursor if "hilite_player" is +* TRUE (or if the player is in a store), instead of always showing the +* cursor. The various "main-xxx.c" files should avoid saving the game +* in response to a "menu item" request unless "inkey_flag" is TRUE, to +* prevent savefile corruption. +* +* If we are waiting for a keypress, and no keypress is ready, then we will +* refresh (once) the window which was active when this function was called. +* +* Note that "back-quote" is automatically converted into "escape" for +* convenience on machines with no "escape" key. This is done after the +* macro matching, so the user can still make a macro for "backquote". +* +* Note the special handling of "ascii 30" (ctrl-caret, aka ctrl-shift-six) +* and "ascii 31" (ctrl-underscore, aka ctrl-shift-minus), which are used to +* provide support for simple keyboard "macros". These keys are so strange +* that their loss as normal keys will probably be noticed by nobody. The +* "ascii 30" key is used to indicate the "end" of a macro action, which +* allows recursive macros to be avoided. The "ascii 31" key is used by +* some of the "main-xxx.c" files to introduce macro trigger sequences. +* +* Hack -- we use "ascii 29" (ctrl-right-bracket) as a special "magic" key, +* which can be used to give a variety of "sub-commands" which can be used +* any time. These sub-commands could include commands to take a picture of +* the current screen, to start/stop recording a macro action, etc. +* +* If "angband_term[0]" is not active, we will make it active during this +* function, so that the various "main-xxx.c" files can assume that input +* is only requested (via "Term_inkey()") when "angband_term[0]" is active. +* +* Mega-Hack -- This function is used as the entry point for clearing the +* "signal_count" variable, and of the "character_saved" variable. +* +* Hack -- Note the use of "inkey_next" to allow "keymaps" to be processed. +* +* Mega-Hack -- Note the use of "inkey_hack" to allow the "Borg" to steal +* control of the keyboard from the user. +*/ + +#####GDescription +Get a keypress from the user. + +---------------------------------------------------------------------- + +#####R=== cmsg_print === + +#####GDeclaration + void cmsg_print(byte color, cptr msg); + +#####GFile + util.c + +#####GComment +/* +* Output a message to the top line of the screen. +* +* Break long messages into multiple pieces (40-72 chars). +* +* Allow multiple short messages to "share" the top line. +* +* Prompt the user to make sure he has a chance to read them. +* +* These messages are memorised for later reference (see above). +* +* We could do "Term_fresh()" to provide "flicker" if needed. +* +* The global "msg_flag" variable can be cleared to tell us to +* "erase" any "pending" messages still on the screen. +* +* XXX XXX XXX Note that we must be very careful about using the +* "msg_print()" functions without explicitly calling the special +* "msg_print(NULL)" function, since this may result in the loss +* of information if the screen is cleared, or if anything is +* displayed on the top line. +* +* XXX XXX XXX Note that "msg_print(NULL)" will clear the top line +* even if no messages are pending. This is probably a hack. +*/ + +#####GDescription +In color "color", output message "msg" to the top line of the screen. +If the message is blank or has more than 1000 characters, nothing is +printed. Long messages are split after the 40th character and before +the 72nd character. + +#####GParameters +> "color" is the color of the message. + *****fields.txt*0[colors] +> "msg" is the message. + +---------------------------------------------------------------------- + +#####R=== msg_print === + +#####GDeclaration + void msg_print(cptr msg); + +#####GFile + util.c + +#####GComment +/* Hack -- for compatibility and easy sake */ + +#####GDescription +Print message "msg" in white (see cmsg_print() above). + +#####GParameters +> "msg" is the message. + +---------------------------------------------------------------------- + +#####R=== screen_save === + +#####GDeclaration + void screen_save(void); + +#####GFile + util.c + +#####GComment +/* + * Save the screen, and increase the "icky" depth. + * + * This function must match exactly one call to "screen_load()". + */ + +#####GDescription +Save a screen shot. + +---------------------------------------------------------------------- + +#####R=== screen_load === + +#####GDeclaration + void screen_load(void); + +#####GFile + util.c + +#####GComment +/* + * Load the screen, and decrease the "icky" depth. + * + * This function must match exactly one call to "screen_save()". + */ + +#####GDescription +Load a previously saved screen shot. + +---------------------------------------------------------------------- + +#####R=== c_put_str === + +#####GDeclaration + void c_put_str(byte attr, cptr str, int row, int col); + +#####GFile + util.c + +#####GComment +/* +* Display a string on the screen using an attribute. +* +* At the given location, using the given attribute, if allowed, +* add the given string. Do not clear the line. +*/ + +#####GDescription +Put string "str" at row "row" and column "col" with attribute "attr". + +#####GParameters +> "attr" is the color of the message. + *****fields.txt*0[colors] +> "msg" is the message. +> "row" is the row the message is to be printed at. +> "col" is the column the message is to be printed at. + +---------------------------------------------------------------------- + +#####R=== c_prt === + +#####GDeclaration + void c_prt(byte attr, cptr str, int row, int col); + +#####GFile + util.c + +#####GComment +/* +* Display a string on the screen using an attribute, and clear +* to the end of the line. +*/ + +#####GDescription +Clear row "row" from column "col". Put string "str" at "row", "col" +with attribute "attr". + +#####GParameters +> "attr" is the color of the message. + *****fields.txt*0[colors] +> "msg" is the message. +> "row" is the row the message is to be printed at. +> "col" is the column the message is to be printed at. + +---------------------------------------------------------------------- + +#####R=== clear_from === + +#####GDeclaration + void clear_from(int row); + +#####GFile + util.c + +#####GComment +/* +* Clear part of the screen +*/ + +#####GDescription +Clear the screen from row "row" onwards. + +#####GParameters +> "row" is the first row of the screen to be cleared. + +---------------------------------------------------------------------- + +#####R=== askfor_aux === + +#####GDeclaration + bool askfor_aux(char *buf, int len); + +#####GFile + util.c + +#####GComment +/* +* Get some input at the cursor location. +* Assume the buffer is initialized to a default string. +* Note that this string is often "empty" (see below). +* The default buffer is displayed in yellow until cleared. +* Pressing RETURN right away accepts the default entry. +* Normal chars clear the default and append the char. +* Backspace clears the default or deletes the final char. +* ESCAPE clears the buffer and the window and returns FALSE. +* RETURN accepts the current buffer contents and returns TRUE. +*/ + +#####GDescription +Get string "buf" from the screen. "buf" is to be no more than "len" +bytes. The string starts at the current cursor position. The length +can not exceed the number of bytes from the cursor to the end of the +line. Accept user input until the escape or return key is pressed. + +#####GParameters +> "buf" is the string returned from the screen. +> "len" is the length of the string. If it is <1 it is forced to 1. + +---------------------------------------------------------------------- + +#####R=== get_string === + +#####GDeclaration + bool get_string(cptr prompt, char *buf, int len); + +#####GFile + util.c + +#####GComment +/* +* Get a string from the user +* +* The "prompt" should take the form "Prompt: " +* +* Note that the initial contents of the string is used as +* the default response, so be sure to "clear" it if needed. +* +* We clear the input, and return FALSE, on "ESCAPE". +*/ + +#####GDescription +Print prompt "prompt" at the top-left corner of the screen and return +response "buf" which will have a maximum length "length". If ESCAPE +is entered, the function returns FALSE, otherwise it returns TRUE. + +#####GParameters +> "prompt" is the prompt for input. +> "buf" is the returned response. +> "len" is the maximum length of the string. + +---------------------------------------------------------------------- + +#####R=== get_check === + +#####GDeclaration + bool get_check(cptr prompt); + +#####GFile + util.c + +#####GComment +/* +* Verify something with the user +* +* The "prompt" should take the form "Query? " +* +* Note that "[y/n]" is appended to the prompt. +*/ + +#####GDescription +Ask the user question "prompt" which requires a yes/no answer. The +prompt appears in the top-left corner of the screen. A response of +'Y' (either case) returns TRUE. A response of 'N' (either case) or +ESCAPE returns FALSE. + +#####GParameters +> "prompt" is the question asked. It has a maximum length of 70 + characters. + +---------------------------------------------------------------------- + +#####R=== get_com_lua === + +#####GDeclaration + bool get_com_lua @ get_com(cptr promtp, int *com); + +#####GFile + util.c + +#####GComment +/* +* Prompts for a keypress +* +* The "prompt" should take the form "Command: " +* +* Returns TRUE unless the character is "Escape" +*/ + +#####GDescription +Ask the user for command "prompt" and return the key press "com". A +response of ESCAPE returns FALSE. All other responses return TRUE. + +#####GParameters +> "prompt" is the prompt for the key press. +> "com" is the returned key press. + +---------------------------------------------------------------------- + +#####R=== get_quantity === + +#####GDeclaration + s32b get_quantity(cptr prompt, s32b max); + +#####GFile + util.c + +#####GComment +/* +* Request a "quantity" from the user +* +* Hack -- allow "command_arg" to specify a quantity +*/ + +#####GDescription +Ask the user for quantity "prompt" of maximum value "max" and return +a quantity. If the user quantity is higher than the maximum then the +maximum is returned. If the response is a letter then the maximum is +returned. If the user quantity is negative then zero is returned. + +#####GParameters +> "prompt" is the prompt for a quantity. +> "max" is the maximum value allowed. + +---------------------------------------------------------------------- + +#####R=== test_monster_name === + +#####GDeclaration + int test_monster_name(cptr name); + +#####GFile + util.c + +#####GComment +/* + * Given monster name as string, return the index in r_info array. Name + * must exactly match (look out for commas and the like!), or else 0 is + * returned. Case doesn't matter. -GSN- + */ + +#####GDescription +Return the monster index for monster with name "name". If no match is +found then zero is returned. + +#####GParameters +> "name" is the monster name. + +---------------------------------------------------------------------- + +#####R=== test_item_name === + +#####GDeclaration + int test_item_name(cptr name); + +#####GFile + util.c + +#####GComment +/* + * Given item name as string, return the index in k_info array. Name + * must exactly match (look out for commas and the like!), or else 0 is + * returned. Case doesn't matter. -DG- + */ + +#####GDescription +Return the item index for item with name "name". If no match is found +then zero is returned. + +#####GParameters +> "name" is the item name. + +---------------------------------------------------------------------- + +#####R=== luck === + +#####GDeclaration + int luck(int min, int max); + +#####GFile + xtra1.c + +#####GComment +/* + * Return a luck number between a certain range + */ + +#####GDescription +Return a number for luck between minimum "min" and maximum "max". The +value begins with the player's current luck. The value is forced to +be between -30 and +30. 30 is added to give a value between 0 and 60. +The value is multiplied by the range (maximum - minimum) and divided +by 60. The value is increased by the minimum. The value is returned. + +For example, if the player's current luck is 15, the minimum is -10, +and the maximum is 10 (range 20), then the value returned is +(45 * 20) / 60 which is 900 / 60 which is 15 + the minimum -10 gives +a returned value of 5. + +#####GParameters +> "min" is the minimum luck. +> "max" is the maximum luck. Beware: this should be greater than the + minimum but it is not checked! + +---------------------------------------------------------------------- + +#####R=== get_player_race_name === + +#####GDeclaration + cptr get_player_race_name(int pr, int ps); + +#####GFile + util.c + +#####GComment +(none) + +#####GDescription +Return the name for player race "pr" and player sub-race "ps". + +#####GParameters +> "pr" is the index for player race. +> "ps" is the index for player sub-race. + +---------------------------------------------------------------------- + +#####R=== quit === + +#####GDeclaration + void quit(cptr str); + +#####GFile + z-util.c + +#####GComment +/* + * Exit (ala "exit()"). If 'str' is NULL, do "exit(0)". + * If 'str' begins with "+" or "-", do "exit(atoi(str))". + * Otherwise, plog() 'str' and exit with an error code of -1. + * But always use 'quit_aux', if set, before anything else. + */ + +#####GDescription +Quit the game. If "str" is a string then write the string to the +error file or screen. If "str" is a number then exit with the +number as the exit code. + +#####GParameters +> "str" is an error message or exit code. + +---------------------------------------------------------------------- + +#####R=== dump_hooks === + +#####GDeclaration + void dump_hooks(); + +#####GFile + plots.c + +#####GComment +(none) + +#####GDescription +Print the name and type (C or Lua) of hooks in the hook list. + +---------------------------------------------------------------------- + +#####R=== add_hook_script === + +#####GDeclaration + void add_hook_script(int h_idx, char *script, cptr name); + +#####GFile + plots.c + +#####GComment +(none) + +#####GDescription +To hook list with index "h_idx", add a script with script file +"script" and name "name" as a Lua hook if a hook with that name +does not already exist. + +#####GParameters +> "h_idx" is the index of the hook list in the array of hook lists. +> "script" is the name of the script file. +> "name" is the name of the hook to be added. + +---------------------------------------------------------------------- + +#####R=== del_hook_name === + +#####GDeclaration + void del_hook_name(int h_idx, cptr name); + +#####GFile + plots.c + +#####GComment +(none) + +#####GDescription +Search hook list with index "h_idx" and remove the hook with name +"name". + +#####GParameters +> "h_idx" is the index of the hook list in the array of hook lists. +> "name" is the name of the hook to be removed. + +---------------------------------------------------------------------- + +#####R=== pern_dofile === + +#####GDeclaration + bool pern_dofile(char *file); + +#####GFile + script.c + +#####GComment +(none) + +#####GDescription +Parse the Lua script file "file". + +#####GParameters +> "file" is the Lua script file to be parsed. + +---------------------------------------------------------------------- + +#####R=== intMod === + +#####GDeclaration + s32b intMod(s32b a, s32b b); + +#####GFile + script.c + +#####GComment +(none) + +#####GDescription +Return the result of operation "a" mod "b" (a % b). + +#####GParameters +> "a" is a number. +> "b" is a number. + +---------------------------------------------------------------------- + +#####R=== intAnd === + +#####GDeclaration + s32b intAnd(s32b a, s32b b); + +#####GFile + script.c + +#####GComment +(none) + +#####GDescription +Return the result of bitwise operation "a" AND "b" (a & b). + +#####GParameters +> "a" is a number. +> "b" is a number. + +---------------------------------------------------------------------- + +#####R=== intOr === + +#####GDeclaration + s32b intOr(s32b a, s32b b); + +#####GFile + script.c + +#####GComment +(none) + +#####GDescription +Return the result of bitwise operation "a" OR "b" (a | b). + +#####GParameters +> "a" is a number. +> "b" is a number. + +---------------------------------------------------------------------- + +#####R=== intXor === + +#####GDeclaration + s32b intXor(s32b a, s32b b); + +#####GFile + script.c + +#####GComment +(none) + +#####GDescription +Return the result of bitwise operation "a" XOR "b" (a ^ b). + +#####GParameters +> "a" is a number. +> "b" is a number. + +---------------------------------------------------------------------- + +#####R=== intShiftl === + +#####GDeclaration + s32b intShiftl(s32b a, s32b b); + +#####GFile + script.c + +#####GComment +(none) + +#####GDescription +Return the result of bitwise operation "a" << "b". + +#####GParameters +> "a" is a number. +> "b" is a number. + +---------------------------------------------------------------------- + +#####R=== intShiftr === + +#####GDeclaration + s32b intShiftr(s32b a, s32b b); + +#####GFile + script.c + +#####GComment +(none) + +#####GDescription +Return the result of bitwise operation "a" >> "b". + +#####GParameters +> "a" is a number. +> "b" is a number. + +---------------------------------------------------------------------- + +#####R=== intBitNot === + +#####GDeclaration + s32b intBitNot(s32b b); + +#####GFile + script.c + +#####GComment +(none) + +#####GDescription +Return the result of bitwise operation NOT "b" (~ b). + +#####GParameters +> "b" is a number. + +---------------------------------------------------------------------- + +#####R=== register_savefile === + +#####GDeclaration + void register_savefile(int num); + +#####GFile + loadsave.c + +#####GComment +/* + * Add num slots to the savefile + */ + +#####GDescription +Add "num" slots to the save file. + +#####GParameters +> "num" is the number of slots to add to the savefile. If num is <0 + then "num" is forced to zero. + +---------------------------------------------------------------------- + +#####R=== save_number_key === + +#####GDeclaration + void save_number_key(char *key, s32b val); + +#####GFile + util.c + +#####GComment +(none) + +#####GDescription +Save the length of key "key", the key itself, and the value "val" as +bytes in the savefile. + +#####GParameters +> "key" is the key string for the value. +> "val" is the value to be saved. + +---------------------------------------------------------------------- + + + +Back to the *****lua.hlp*0[lua help index] . + + + [[[[[gThis file by Chris Hadgis] + |