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.
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.
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?
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_element (in) Choose a random element from a table.
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.
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.

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)
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
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 posessive
  • "its": use the third person posessive
  • "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
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.

Parameters:

  • num int how many lines back to go

Returns:

    strong
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_element (in)
Choose a random element from a table. If passed an array, a random element is chosen from the array. If passed a table, the values should be numeric or convertible to numeric and give the weights for their corresponding keys. A value with no key will default to a weight of 1. A random key is then returned based on these weights.

Parameters:

  • in table

Returns:

    a random element from in.
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:

  1. byte
  2. byte
  3. byte
  4. 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
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:

  1. number distance1
  2. number distance2
  3. number id1
  4. number id2
  5. number id1
  6. number pos1x
  7. number pos1y
  8. number pos1z
  9. number pos2x
  10. number pos2y
  11. number pos2z
worley_diff (px, py, pz)
Difference between nearest point Worley distances.

Parameters:

  • px number
  • py number
  • pz number

Returns:

  1. number diff
  2. 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)

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:

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:

Returns:

    boolean
MessageFilter:matches (msg, ch)
Check a message against a filter.

Parameters:

  • msg string
  • ch int message channel

Returns:

    boolean
generated by LDoc 1.4.6 Last updated 2018-08-21 11:24:55