Lua functions

Dwarf Fortress defines a number of functions in addition to those standard for Lua 5.4.

C++ Function Calls

Function	Description
int  trandom(int n)	Returns a 32-bit integer from 0 to n-1. Uses DF's internal RNG system instead of math.random().
str  capitalize_string_words(str s)	Capitalizes every word in a string.
str  capitalize_string_first_word(str s)	Capitalizes the first word in a string.
str  utterance()	Returns a word from the kobold language.
void  lua_log(str s)	Prints a string to Dwarf Fortress/lualog.txt. The log() function is more robust and should be used instead.

init/globals.lua

Randomization

Function	Description
userdata  pick_random(table t)	Returns a random value from a table.
userdata  pick_random_no_replace(table t)	Returns a random value from a table, then removes it from the table.
userdata  pick_random_conditional(table t,function cond,...)	Returns a random value from a table that satisfies cond(...).
bool  one_in(num x)	Returns true with a one in x chance.
userdata  pick_random_pairs(table tbl)	Returns a random key from a table. For example, pick_random_pairs( {WATER = true} ) returns "WATER".
userdata  pick_weighted_from_table(table tbl)	Requires a table of tables with weight keys. Returns a weighted random value. At debug level >=4, logs the roll.
userdata  generate_from_list(table tbl,...)	Requires a table of functions that return a weight key. Runs each function and returns a weighted random output. Used by werebeasts to generate an interaction and link to options from it.

Tables

Function	Description
table  split_to_lines(table tbl,string str)	Adds a string into a table, with each line being a separate key.
table  map_merge(table tbl1, table tbl2)	Combines two tables. If tbl1 already has a value for a given key, it will not be overwritten. Used for sets such as { WATER = true }.
table  table_merge(table tbl1, table tbl2)	Adds each value from tbl2 onto the end of tbl1.
bool  find_in_array_part(table tbl, userdata item)	Returns true if item is a value in tbl.
void  convert_array_to_set(table tbl)	For each key in a table, sets the value to true.
void  add_unique(table tbl, userdata item)	Adds item to the end of tbl if not already present.
void  remove_item(table tbl, userdata item)	Removes all instances of item from tbl.
table  shallow_copy(table tbl)	Returns a table copied from all values in the input table.
table  deep_copy(table tbl)	Returns a table recursively copied from all values in the input table.

Debug

Function	Description
void  log(...)	Logs the input to Dwarf Fortress/lualog.txt. Used for most cases.
string  get_caller_loc_string()	Returns the debug source info and the current line.
string  get_debug_logger(num level=1,...)	Logs get_caller_loc_string() and any overloads if the debug_level is at least level. debug_level is a global variable that defaults to 0.
function  partial_function(function f,arg,...)	Returns f(arg,...).
function  log_table(table tbl,num debug_level=0,num nest_level=0,num added_debug_from_nest=0)	Logs a table if the global debug_level is at least the input debug_level. nest_level starts at 0 and adds added_debug_from_nest for each nesting to the input debug level.
function  print_table(table tbl,num nest_level=0)	Logs a table, regardless of debug level.

Spheres

Function	Description
string  get_random_sphere_adjective(string sphere)	Returns a random string from global table random_sphere_adjective[sph].
table  get_random_sphere_noun(string sphere)	Returns a random table tbl from global table random_sphere_nouns[sphere]. tbl has two members: tbl.str, which is a string; and tbl.flags, which defaults to {OF=true,PREPOS=true,PRE=true}, for grammar.
table  add_sphere_mpp(table sphere_list, string new_s, table available_sphere, table available_sphere_cur)	Adds new_s to sphere_list and all parents and children. Sets the added spheres in available_sphere and available_sphere_cur to false, and sets all enemies in available_sphere_cur to false. At debug level >= 2, will be logged.