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 any script even if vanilla_procedural is not loaded.

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 determine how it can be added to an interaction's syndrome.

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.

Interaction helpers

Function	Notes
table tbl, table end_tbl basic_lieutenant(string name, string name_plural, string token)	Generates an interaction that raises an intelligent undead and calls basic_lieutenant_powers(token).
table tbl, table end_tbl basic_lieutenant_powers(string token)	Adds any number of powers (chosen from among interaction.powers) and 0-5 sicken effects (from add_curses()) to the current definition.
table tbl, table end_tbl, int idx add_curses(table tbl, table end_tbl, string token, int num, int start_idx, int sev, table good_effects)	Adds num curses/afflictions to the current definition. good_effects lists the possible curses that can be chosen from default_curse_effects, and sev is the syndrome's severity. Basic lieutenants use a sev of 500.
string get_abstract_gesture()	Returns a random string from either gestures or gestures_abstract, used for [VERB].

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 subtype 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. [DIVINE] and [SPHERE] are added by generators.lua rather than in the individual function.
materials.mythical_remnant	function(sphere)	Primordial remnant	Possible spheres are determined by random_object_parameters.mythical_sphere.
materials.mythical_healing	function()	Mythical substance

Random Creatures

Creatures generated by vanilla_procedural use a number of shared functions to determine their attributes. The local options table stores most of the data used by these steps.

RCP Functions

The random creature profile determines the basic body of a generated creature, such as "humanoid" or "toad", and provides options and data to later build the proper creature definition.

Function	Notes
table get_random_creature_profile(options,blacklist)	Makes a weighted random choice of options from random_creature_types that satisfy arguments set in options (options.do_water, etc) and blacklist. Falls back to random_creature_types.GENERAL_BLOB. At debug_level >= 3, will log failures. At debug_level >= 4, will also log successes.
bool is_valid_random_creature(string creature, bool do_water, bool humanoid_only, bool is_good, bool beast_only)	Checks if creature is a valid key in certain tables depending on the arguments: aquatic (do_water), can be "twisted into humanoid form" (humanoid_only), isn't an "evil" species (is_good), and is an animal species (beast_only) At debug_level >= 3, will be logged.
void finalize_random_creature_types()	If random_creature_types_finalized is false: sets it to true and iterates over random_creature_types to sanitize certain inputs.

Shared Functions

Default creatures use add_regular_tokens(), populate_sphere_info(), get_random_creature_profile(), add_body_size() and build_procgen_creature() as the main steps in generating raws.

Function	Notes
add_regular_tokens(tbl,options)	Adds tokens to tbl. Sets [PETVALUE], calculates material weaknesses (if options.material_weakness), and adds a few immunity tokens depending on options.normal_biological.
tile_string(arg)	Returns a string usable for [CREATURE_TILE]. Encloses number arguments in characters.
add_body_size(tbl,size,options)	Adds [BODY_SIZE] and sets options.body_size. Calls body_size_properties().
body_size_properties(tbl,size,options)	Adds [BUILDINGDESTROYER] if size > 80,000; adds [GRASSTRAMPLE] and [TRAPAVOID] if size > 100,000.
populate_sphere_info(tbl,options)	Adds [SPHERE] tokens from options.spheres. If options.do_sphere_rcm, 1/2 chance to set options.sphere_rcm.
add_poison_bits(tbl,options)	Generates a poison material based on options.poison_state and options.sickness_name.
build_procgen_creature(rcp,tbl,options)	Calls build_body_from_rcp(), build_description(), and build_pcg_graphics().
build_body_from_rcp(rcp,tbl,options)	Generates based on rcp and options, assigns tweaks (mutations from the base body), tissues, organs, special attacks.
build_description(tbl,options)	Writes the [DESCRIPTION] and any [PREFSTRING]s.
build_pcg_graphics(tbl,options)	Assigns procedural graphics layers based on options.pcg_layering keys set by build_body_from_rcp().

Options

Key	Usage	Notes
do_water	get_random_creature_profile()	Use an aquatic RCP (water_based_random_creature)
humanoid_only	get_random_creature_profile()	Use a RCP that can be turned into a humanoid form (humanoidable_random_creature)
is_good	get_random_creature_profile() build_body_from_rcp() build_description()	Forbids "evil" RCPs (cannot_be_good_random_creature). Affects options for materials, tweaks, description.
is_evil	build_body_from_rcp() build_description()	Affects options for materials, tweaks, description.
beast_only	get_random_creature_profile()	Forbids generic humanoid/blob/quadruped RCPs (not_beast_random_creature).
normal_biological	add_regular_tokens()	If false, adds [AMPHIBIOUS], [SWIMS_INNATE], [NONAUSEA], [NOEXERT], [NO_DIZZINESS], [NOPAIN], [NOSTUN]. Used by experiments.
material_weakness	add_regular_tokens()	Will gain a 10x [MATERIAL_FORCE_MULTIPLIER] to a random weapon metal and a [GENERAL_MATERIAL_FORCE_MULTIPLIER:1:2].
body_size	build_description() build_pcg_graphics()	Set by body_size_properties(). Stores the creature's volume for later use.
spheres	populate_sphere_info() color_picker_functions build_description()	A set of the creature's spheres.
do_sphere_rcm	populate_sphere_info()	Adds a 1/2 chance to set options.sphere_rcm to a material relevant to their spheres.
pick_sphere_rcm	random_creature_class	If uniform, adds an additional 1/2 chance to use a material relevant to their spheres.
pos_sphere_rcm	populate_sphere_info()	Data storage for possible sphere RCM during populate_sphere_info().
sphere_rcm		Forces the creature to be uniform and made of that random_creature_material.
body_string	build_body_from_rcp()	An array of all [BODY] tokens used.
beak brain cheeks eyelids guts heart lips lungs mouth neck nose ribs skull spine teeth throat tongue	build_body_from_rcp()	Normally set by the creature's random_creature_class (MAMMAL, CHITIN_EXO, etc). Adds the listed parts to the creature's body plan.
blood ichor goo	build_body_from_rcp()	Normally set by the creature's random_creature_class (MAMMAL, CHITIN_EXO, etc). Sets the creature's default [BLOOD] type.
force_goo force_ichor	build_body_from_rcp()	If the creature is not uniform, overwrites the creature's [BLOOD] type.
blood_color	build_body_from_rcp()	Expects a function that takes a color's HSV values and returns a boolean. Sets the creature's blood color to any color that returns true for this function. Only works with standard blood from options.blood.
eyes glowing_eyes fingers toes finger_claws toe_claws finger_nails toe_nails finger_talons toe_talons bat_wings lacy_wings feathered_wings has_proboscis do_webs	build_body_from_rcp()	Set when building the body if the creature has those traits. Can be called by the description and when building graphics. Nails, claws, and talons are given attacks.