Module crawl
General crawl related functions, including interaction.
Functions
| article_a (s[, lowercase=true]) | Correctly attach the article 'a'. |
| c_input_line () | Cancellably prompt the user for a line of input. |
| call_dlua (chunk) | Call lua in dungeon (dlua) context. |
| clear_messages (force) | Clear the message window. |
| coinflip () | Flip a coin. |
| delay (ms) | Delay the display. |
| div_rand_round (numerator, denominator) | Random-round integer division. |
| do_commands (commands[, hide=false]) | Execute a sequence of named crawl commands The array must be the command names as they appear in cmd-name.h, they are processed in order by the macro internal command buffer. |
| do_targeted_command (command[, x=0[, y=0[, if=false]]]) | Handle any command that takes a target and no other parameters. |
| dpr (text) | Print to the debugging channel, which is desplayed only for debug builds. |
| dump_char () | Produce a character dump |
| enable_more (flag) | Toggle the use of --- more --- prompts. |
| err_trace (function, args) | Lua error trace a call Attempts to call-trace a lua function that is producing an error. |
| flush_input () | Flush the input buffer (typeahead). |
| flush_prev_message () | Flush the previous message to the window. |
| formatted_mpr (message, channel) | Print a formatted message. |
| game_started () | Has the game started? |
| get_command (name) | Look up the current key bound to a command. |
| get_target () | Prompt the user to choose a location via the targeting screen. |
| getch () | Get input key (combo). |
| grammar (what[, how="plain"]) | Grammatically describe something. |
| is_tiles () | Are we running under tiles? |
| is_touch_ui () | Are we using the touch ui? |
| is_webtiles () | Are we running under webtiles? |
| kbhit () | Check for pending input. |
| message (message, channel) | A wrapper for the low-level sequence of commands needed to produce message output. |
| message_filter (pat[, ch=-1]) | Create a message filter |
| messages (num) | Retrieve the message buffer. |
| more () | Display a --- more --- prompt |
| mpr (message, channel) | Print a message. |
| msgch_name (num) | Get the name of a message channel. |
| msgch_num (name) | Get the number of a message channel. |
| one_chance_in (in) | Perform a weighted coinflip. |
| playsound (sf) | Play a sound. |
| process_command () | Tell crawl to process a current macro delay. |
| process_keys (keys[, hide=false]) | Process a string of input keys The first key of the first argument must be a command key in the default key context. |
| random2 (max) | Return a random number from [0, max). |
| random2avg (max, num) | Average num random rolls from [0, max). |
| random_range (min, max[, rolls=1]) | Random number in a range. |
| random_real () | A random floating point number in [0,1.0) |
| read_options (filename) | Read options from file. |
| redraw_screen () | Redraw the screen. |
| regex (pat) | Compile a regular expression |
| roll_dice ([num_dice=1], sides) | Roll dice. |
| runmacro (macroname) | Run a macro. |
| sendkeys (keys[, ...]) | Send keypresses to crawl. |
| set_more_autoclear (flag) | Toggle autoclearing of --- more --- prompts. |
| set_sendkeys_errors (param) | Enable or disable crashing on an incomplete buffer. |
| setopt (opt) | Set user options from string. |
| simplex (x, y[, z[, w]]) | 2D-4D Simplex noise. |
| split (s, split) | Split a string at a token. |
| split_bytes (num) | Splits a 32-bit integer into four bytes. |
| stat_gain_prompt () | Is crawl asking us to choose a stat? |
| stderr (text) | Print to stderr for debugging hooks. |
| string_compare (s1, s2) | Compare two strings in a locale-independent way. |
| take_note (note) | Make a note. |
| trim (s) | Trim newlines and trailing whitespace. |
| version ([fmt="long"]) | Get the crawl version The optional argument is a string from "long", "major", or "short" to determine which version type to return. |
| weapon_check () | Check if the player really wants to use their weapon. |
| worley (px, py, pz) | Get the full Worley noise datum for a given point |
| worley_diff (px, py, pz) | Difference between nearest point Worley distances. |
| x_chance_in_y (x, y) | Do a random draw. |
| yesno (prompt, safe[, safeanswer[, clear_after=true[, interrupt_delays=true[, noprompt=false]]]]) | Ask the player a yes/no question. |
| yesnoquit (prompt, safe[, safeanswer[, allow_all=false[, clear_after=true]]]) | Ask the player a yes/no/quit question. |
Local Functions
| echoall (...) | Echoing function for the interpreter. |
dlua
| args () | Get the commandline arguments |
| god_speaks (Name, Speach) | Divine voices. |
| make_name () | Make an item name at random. |
| milestone (type, milestone, origin) | Mark a milestone Register a dgl milestone. |
| millis () | Current milliseconds. |
| redraw_stats () | Redraw the player stats. |
| redraw_view () | Redraw the viewwindow. |
| set_max_runes (nrune) | Set Max Runes Modify the total number of obtainable runes. |
| unavailable_god (godname) | Check if a god is still available. |
Class Regex
| Regex:equals (pat) | Test equality Tests if the two lua variables are the same underlying compiled pattern |
| Regex:find (s) | Test against a string. |
Class MessageFilter
| MessageFilter:equals (pat) | Test equality Tests if the two lua variables are the same underlying compiled pattern |
| MessageFilter:matches (msg, ch) | Check a message against a filter. |
Functions
- article_a (s[, lowercase=true])
-
Correctly attach the article 'a'.
Parameters:
- s string
- lowercase bool (default true)
Returns:
-
string
- c_input_line ()
-
Cancellably prompt the user for a line of input.
The line is limited to 500 characters.
Returns:
-
string or nil
a string if one is input or nil if input is cancelled
- call_dlua (chunk)
-
Call lua in dungeon (dlua) context.
Parameters:
- chunk string code run
Returns:
-
a scalar return value from dlua context
- clear_messages (force)
-
Clear the message window.
Parameters:
- force boolean
- coinflip ()
-
Flip a coin.
Returns:
-
boolean
- delay (ms)
-
Delay the display.
Parameters:
- ms int delay in milliseconds
- div_rand_round (numerator, denominator)
-
Random-round integer division.
Parameters:
- numerator int
- denominator int
Returns:
-
int
- do_commands (commands[, hide=false])
-
Execute a sequence of named crawl commands
The array must be the command names as they appear in cmd-name.h, they are
processed in order by the macro internal command buffer. The input buffer is
flushed before execution.
Parameters:
- commands array
- hide boolean hide targeter while processing (default false)
- do_targeted_command (command[, x=0[, y=0[, if=false]]])
-
Handle any command that takes a target and no other parameters. This includes
CMDPRIMARYATTACK, CMDEVOKEWIELDED, and CMD_FIRE. If the target
coordinates are out of bounds (the default), this enters interactive
targeting.
Parameters:
- command string name
- x number coordinate (default 0)
- y number coordinate (default 0)
- if boolean true, aim at the target; if false, shoot past it (default false)
Returns:
-
boolean
whether an action took place
- dpr (text)
-
Print to the debugging channel, which is desplayed only for debug builds.
Parameters:
- text string
- dump_char ()
- Produce a character dump
- enable_more (flag)
-
Toggle the use of
--- more ---prompts.Parameters:
- flag boolean
- err_trace (function, args)
-
Lua error trace a call
Attempts to call-trace a lua function that is producing an error.
Returns normally if the function runs normally, otherwise sends
Parameters:
- function
- args
Returns:
-
the result of the call if successful
- flush_input ()
- Flush the input buffer (typeahead).
- flush_prev_message ()
- Flush the previous message to the window.
- formatted_mpr (message, channel)
-
Print a formatted message.
Parameters:
- message string message to print
- channel
channel to print on; defaults to 0 (
MSGCH_PLAIN)
- game_started ()
-
Has the game started?
Returns:
-
boolean
- get_command (name)
-
Look up the current key bound to a command.
Parameters:
- name string Name as in cmd-name.h
Returns:
-
string or nil
- get_target ()
-
Prompt the user to choose a location via the targeting screen.
This is useful for scripts that require a user-selected target. For example,
one could imagine a "mark dangerous monster" script that would place a large
exclusion around a user-chosen monster that would then be deleted if the
monster moved or died. This function could be used for the user to select
a target monster.
Returns:
-
int,
int the relative position of the chosen location to the user
- getch ()
-
Get input key (combo).
Returns:
-
int
the key (combo) input
- grammar (what[, how="plain"])
-
Grammatically describe something.
Crawl provides the following description types:
- "plain": just give the name
- "the": use the definite article
- "a": use the indefinite article
- "your": use the second person possessive
- "its": use the third person possessive
- "worn": how it is equipped
- "inv": describe something carried
- "none": return the empty string
And some specific types for partial item naming:
- "base": base name of the item subtype
- "qualname": name without articles, quantities, or enchantments
These are used as the allowable values for how.
Parameters:
- what string thing to describe
- how string crawl description type (default "plain")
Returns:
-
string
grammatical description
- is_tiles ()
-
Are we running under tiles?
Returns:
-
boolean
- is_touch_ui ()
-
Are we using the touch ui?
Returns:
-
boolean
- is_webtiles ()
-
Are we running under webtiles?
Note: returns true if the crawl binary is a webtiles build, even if the
player is currently using console.
Returns:
-
boolean
- kbhit ()
-
Check for pending input.
Returns:
-
int 1 if there is, 0 otherwise
- message (message, channel)
-
A wrapper for the low-level sequence of commands needed to produce
message output.
Parameters:
- message string
- channel int messge channel number
See also:
- message_filter (pat[, ch=-1])
-
Create a message filter
Parameters:
- pat string filter pattern
- ch int channel number, -1 for anu (default -1)
Returns:
-
MessageFilter or nil
- messages (num)
-
Retrieve the message buffer.
See also Hooks.c_message for programmatically receiving messages as they are sent.
Parameters:
- num int how many lines back to go
Returns:
-
string
- more ()
-
Display a
--- more ---prompt - mpr (message, channel)
-
Print a message.
Parameters:
- message string message to print
- channel
channel to print on; defaults to 0 (
MSGCH_PLAIN)
- msgch_name (num)
-
Get the name of a message channel.
Parameters:
- num int channel number
Returns:
-
string
channel name
- msgch_num (name)
-
Get the number of a message channel.
Parameters:
- name string channel name
Returns:
-
int
channel number
- one_chance_in (in)
-
Perform a weighted coinflip.
Parameters:
- in int
Returns:
-
boolean
- playsound (sf)
-
Play a sound.
Only available when crawl is compiled with sound.
Parameters:
- sf string filename of sound to play
- process_command ()
-
Tell crawl to process a current macro delay.
Returns:
-
boolean whether it will actually do so
- process_keys (keys[, hide=false])
-
Process a string of input keys
The first key of the first argument must be a command key in the default key
context. The subsequent keys are processed as in sendkeys().
Parameters:
- keys string
- hide boolean hide targeter while processing (default false)
- random2 (max)
-
Return a random number from [0, max).
Parameters:
- max int
Returns:
-
int
- random2avg (max, num)
-
Average num random rolls from [0, max).
Parameters:
- max int
- num int
Returns:
-
int
- random_range (min, max[, rolls=1])
-
Random number in a range.
Parameters:
- min int
- max int
- rolls int Average over multiple rolls (default 1)
- random_real ()
-
A random floating point number in [0,1.0)
Returns:
-
number
- read_options (filename)
-
Read options from file.
Parameters:
- filename string name of file to read from
- redraw_screen ()
- Redraw the screen.
- regex (pat)
-
Compile a regular expression
Parameters:
- pat string the pattern string (PCRE)
Returns:
-
Regex or nil
- roll_dice ([num_dice=1], sides)
-
Roll dice.
Parameters:
- num_dice int (default 1)
- sides int
Returns:
-
int
- runmacro (macroname)
-
Run a macro.
Parameters:
- macroname string name of macro to run
- sendkeys (keys[, ...])
-
Send keypresses to crawl.
A flexible variadic function to send input to crawl. Will process any number
of arguments. Each argument can be a string, keycode number, or array of the
previous two types. They are processed in left-to-right order.
Parameters:
- keys string, int or array
- ... (optional)
- set_more_autoclear (flag)
-
Toggle autoclearing of
--- more ---prompts.Parameters:
- flag boolean
- set_sendkeys_errors (param)
-
Enable or disable crashing on an incomplete buffer.
Used for tests, not generally useful in real life. Crashing only happens in
wizmode.
Parameters:
- param boolean
- setopt (opt)
-
Set user options from string.
Parameters:
- opt string an option string in the same format as init.txt/.crawlrc
- simplex (x, y[, z[, w]])
-
2D-4D Simplex noise.
The first two parameters are required for 2D noise, the next two are
optional for and specify 3D or 4D, respectively.
Parameters:
- x number
- y number
- z number (optional)
- w number (optional)
Returns:
-
number
- split (s, split)
-
Split a string at a token.
Parameters:
- s string
- split string
Returns:
-
{string,...}
- split_bytes (num)
-
Splits a 32-bit integer into four bytes.
This is useful in conjunction with worley ids to get four random numbers
instead of one from the current node id.
Parameters:
- num int
Returns:
- byte
- byte
- byte
- byte
- stat_gain_prompt ()
-
Is crawl asking us to choose a stat?
Returns:
-
boolean
- stderr (text)
-
Print to stderr for debugging hooks.
Parameters:
- text string
- string_compare (s1, s2)
-
Compare two strings in a locale-independent way.
Lua's built in comparison operations for strings are dependent on locale,
which isn't always desireable. This is just a wrapper on
std::basic_string::compare.
Parameters:
- s1 string the first string.
- s2 string the second sring.
Returns:
-
number
-1 if s1 < s2, 1 if s2 < s1, 0 if s1 == s2.
- take_note (note)
-
Make a note.
Parameters:
- note string
- trim (s)
-
Trim newlines and trailing whitespace.
Parameters:
- s string
Returns:
-
string
- version ([fmt="long"])
-
Get the crawl version
The optional argument is a string from "long", "major", or "short" to
determine which version type to return. The argument * check is
case-insensitive.
Parameters:
- fmt string (default "long")
Returns:
-
string
- weapon_check ()
-
Check if the player really wants to use their weapon.
Returns:
-
boolean
- worley (px, py, pz)
-
Get the full Worley noise datum for a given point
Parameters:
- px number
- py number
- pz number
Returns:
- number distance1
- number distance2
- number id1
- number id2
- number id1
- number pos1x
- number pos1y
- number pos1z
- number pos2x
- number pos2y
- number pos2z
- worley_diff (px, py, pz)
-
Difference between nearest point Worley distances.
Parameters:
- px number
- py number
- pz number
Returns:
- number diff
- number id1
- x_chance_in_y (x, y)
-
Do a random draw.
Parameters:
- x int
- y int
Returns:
-
boolean
- yesno (prompt, safe[, safeanswer[, clear_after=true[, interrupt_delays=true[, noprompt=false]]]])
-
Ask the player a yes/no question.
The player is supposed to answer by pressing Y or N.
Parameters:
- prompt string question for the user
- safe boolean accept lowercase answers
- safeanswer string or nil if a letter, this will be considered a safe default (optional)
- clear_after boolean clear the question after the user answers (default true)
- interrupt_delays boolean interrupt any ongoing delays to ask the question (default true)
- noprompt boolean skip asking the question; just wait for the answer (default false)
- yesnoquit (prompt, safe[, safeanswer[, allow_all=false[, clear_after=true]]])
-
Ask the player a yes/no/quit question.
Mostly like yesno(), but doesn't support as many
parameters in this Lua binding.
Parameters:
- prompt string question for the user
- safe boolean accept lowercase answers
- safeanswer string or nil if a letter, this will be considered a safe default (optional)
- allow_all boolean actually ask a yes/no/quit/all question (default false)
- clear_after boolean clear the question after the user answers (default true)
Local Functions
dlua
- args ()
-
Get the commandline arguments
Returns:
-
table
- god_speaks (Name, Speach)
-
Divine voices.
Parameters:
- Name string of a current crawl god.
- Speach string
- make_name ()
-
Make an item name at random.
Returns:
-
string
- milestone (type, milestone, origin)
-
Mark a milestone
Register a dgl milestone. No op if not a dgl game.
Parameters:
- type string
- milestone string
- origin string
- millis ()
-
Current milliseconds.
Gives the current milliseconds of the time of day.
Returns:
-
int
- redraw_stats ()
- Redraw the player stats. You probably want redraw_screen unless you specifically want only the player stats.
- redraw_view ()
- Redraw the viewwindow. You probably want redraw_screen unless you specifically want only the view window.
- set_max_runes (nrune)
-
Set Max Runes
Modify the total number of obtainable runes.
Parameters:
- nrune int
- unavailable_god (godname)
-
Check if a god is still available.
For gods that are no longer appearing in new games, and Jiyva if its been
killed by the player.
Parameters:
- godname string
Returns:
-
boolean
Class Regex
Regular expression objects
- Regex:equals (pat)
-
Test equality
Tests if the two lua variables are the same underlying compiled pattern
Parameters:
- pat regex
Returns:
-
boolean
- Regex:find (s)
-
Test against a string.
Returns nil if the pattern object does not exist or if a non-string is
passed.
Parameters:
- s string
Returns:
-
boolean or nil
Class MessageFilter
Message filter object.
- MessageFilter:equals (pat)
-
Test equality
Tests if the two lua variables are the same underlying compiled pattern
Parameters:
- pat regex
Returns:
-
boolean
- MessageFilter:matches (msg, ch)
-
Check a message against a filter.
Parameters:
- msg string
- ch int message channel
Returns:
-
boolean