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.
void  raws.register_creatures(table lines) void  raws.register_entities(table lines) void  raws.register_inorganics(table lines) void  raws.register_interactions(table lines) void  raws.register_items(table lines) void  raws.register_languages(table lines) void  raws.register_plants(table lines)[Verify]	Takes a table of tokens and reads them as that type of raw file. It is not necessary to add a header.

Globals

Helper functions are defined in init/globals.lua, and can be accessed by

Generation

This function is defined in init/generators.lua.

Function	Description
table  add_generated_info(table tbl)	Adds [GENERATED] to the input table, and [SOURCE_HFID]/[SOURCE_ENID] if IDs are defined. Necessary for generated raws to be saved properly.

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.

Generation Tables

The generate() function is defined in init/generators.lua, and is called to generate objects.

Each type of random object is defined through a function that generates a table of raws. To generate objects for specific purposes, generate() can call functions from a table and provide inputs such as tok (unique token string). For example, forgotten beasts are unique and generated for each cave region. If multiple functions are defined in creatures.fb, such as both creatures.fb.default and a modded forgotten beast, the game uses the weight output to influence which one will be randomly chosen.

By default, objects are generated in this order: unittests*, preprocess, do_once, materials, items, languages, creatures, interactions, entities, and postprocess. Do note that you can register raws at any step. For example, each vault entity generates a set of divine equipment during the entity step, and werebeasts generate a curse interaction during the creature step.

Custom

All functions in these tables are run each tick, but global variable random_object_parameters is only ever populated with values once per generation. Functions called through these tables are not supplied with arguments.

Table	Description
preprocess	Runs once the world's terrain has been finalized and before history can begin. Includes two functions by default: preprocess.demon(), which populates the distribution of demon_type string inputs preprocess.bogeyman_polymorph(), which generates the bogeyman's polymorph interaction if bogeymen exist
do_once	Runs immediately after all functions in preprocess, and before all other generation steps. Only runs if random_object_parameters.main_world_randoms = true, for added safety. Recommended for generating custom objects.
postprocess	Runs after all other generation steps are finished.
unittests	Runs before preprocess if the global debug_level is greater than 0. Expects a boolean output.
languages	For each function in this table, registers a language. Expects table of key-value pairs where the key is the word token and the value is the translated string.

Creatures

Table	Inputs	Article
creatures.angel.great_beast creatures.angel.humanoid_generic creatures.angel.humanoid_warrior	function(tok)	Angel (see types)
creatures.demon	function(demon_type,difficulty,tok)	Demon
creatures.experiment.beast_large creatures.experiment.beast_small creatures.experiment.failed_large creatures.experiment.failed_small creatures.experiment.humanoid_giant creatures.experiment.humanoid	function(tok)	Experiment
creatures.fb	function(layer_type,tok)	Forgotten beast
creatures.night_creature.bogeyman	function(tok)	Bogeyman
creatures.night_creature.nightmare	function(tok)	Nightmare
creatures.night_creature.troll	function(tok)	Night troll
creatures.night_creature.werebeast werebeast_origin_interactions*	function(tok) function(tok,name,options)	Werebeast
creatures.titan	function(subregion,tok)	Titan

Entities

Generated entities are supplied with the idx parameter, which is a number that starts at 1 and increments by 1 for each entity of that type. It can be used to give a unique ID to divine equipment.

Table	Inputs	Articles
entities.vault_guardian	function(idx,tok)	Vault (angels)
entities.mythical_guardian	function(idx,tok)	Mysterious dungeon (dungeon guardians)

Interactions

World

World interactions are generated in the generate_random_interactions() step of generators.lua.

Table	Inputs	Examples
interactions.blessing.minor interactions.blessing.medium	function(idx)	Die roll effects: luck, holy item, healing, etc
interactions.curse.minor interactions.curse.medium	function(idx)	Die roll effects: week of curse
interactions.curse.major	function(idx,tok)	Vampire
interactions.disturbance	function(idx)	Mummy
interactions.mythical	function(idx,power_level,sphere)	Dungeon guardian
interactions.mythical_item_power	spheres={}, interaction=function()	Primordial remnant#List of powers
interactions.regional	function(idx)	Reanimating evil biomes
interactions.secrets	function(idx,sphere)	Necromancer

Powers

Powers are stored in the interactions.powers table and can be generated by other interactions. The structure of each power entry contains several keys that

Key	Inputs	Notes
tags	table	A table of user-defined values that can be checked by other functions.
tags.lieutenant	bool	If true, available to intelligent undead.
rarity	number n	Higher is rarer. An intelligent undead has a 1 in n chance to receive this power.
gen	table tbl, table end_tbl function(name)	Generates and returns lines of raws. tbl consists of syndrome lines comprising [CE_CAN_DO_INTERACTION] and [CDI]. end_tbl consists of lines that define the interaction.

Items

Instruments

The default instrument system is not currently open to Lua, but generators.lua defines tables for each token.

Table	Inputs	Token
items.instruments.keyboard	N/A	[GENERATE_KEYBOARD_INSTRUMENTS]
items.instruments.stringed	N/A	[GENERATE_STRINGED_INSTRUMENTS]
items.instruments.wind	N/A	[GENERATE_WIND_INSTRUMENTS]
items.instruments.percussion	N/A	[GENERATE_PERCUSSION_INSTRUMENTS]

Divine equipment

entities.vault_guardian.default generates from the list angel_item_gens, the default function of which then calls functions from angel_item_info. Unless otherwise stated, the Behavior column refers to the behavior of how angel_item_gens.default generates from these lists.

Table	Inputs	Behavior
angel_item_gens	function(prefix,tokens)	Called by entities.vault_guardian.default, which supplies a unique prefix and doesn't provide tokens.
angel_item_info.armor.pants.gen angel_item_info.armor.armor.gen angel_item_info.armor.helm.gen angel_item_info.armor.gloves.gen angel_item_info.armor.shoes.gen angel_item_info.shield.gen	function(i,prefix)	Generates 1 piece of armor for each slot and 1 shield.
angel_item_info.clothing.pants.gen angel_item_info.clothing.armor.gen angel_item_info.clothing.helm.gen angel_item_info.clothing.gloves.gen angel_item_info.clothing.shoes.gen	function(i,prefix)	Generates 1 piece of clothing for each slot.
angel_item_info.weapon.PIKE.gen angel_item_info.weapon.WHIP.gen angel_item_info.weapon.BOW.gen angel_item_info.weapon.BLOWGUN.gen angel_item_info.weapon.AXE.gen angel_item_info.weapon.SWORD.gen angel_item_info.weapon.DAGGER.gen angel_item_info.weapon.MACE.gen angel_item_info.weapon.HAMMER.gen angel_item_info.weapon.SPEAR.gen angel_item_info.weapon.CROSSBOW.gen	function(i,prefix)	Generates 5 weapons. The tables correspond to combat skills, and are not repeated. For example, a vault can't generate two types of swords.
angel_item_info.ammo.ARROW angel_item_info.ammo.BOLT angel_item_info.ammo.BLOWDART	function()	When a ranged weapon is generated, it will also generate a random type of the proper ammunition.

Materials

Table	Inputs	Article	Notes
materials.clouds materials.rain	function()	Evil weather	Associated regional interactions are automatically written by init/generators.lua.
materials.divine.metal materials.divine.silk	function(sphere)	Divine metal Divine fabric	The list of potential spheres is determined by the individual function. See Lua script examples#New divine metal.
materials.mythical_remnant	function(sphere)	Primordial remnant	Possible spheres are determined by random_object_parameters.mythical_sphere.
materials.mythical_healing	function()	Mythical substance