v50 Steam/Premium information for editors
  • v50 information can now be added to pages in the main namespace. v0.47 information can still be found in the DF2014 namespace. See here for more details on the new versioning policy.
  • Use this page to report any issues related to the migration.
This notice may be cached—the current version can be found here.

Difference between revisions of "Lua functions"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
(→‎Options: Added options)
(Undo revision 308800 by DPhKraken (talk))
Tag: Undo
Line 1: Line 1:
 +
{{Modding}}
 +
 +
Dwarf Fortress defines a number of functions in addition to those standard for [https://www.lua.org/manual/5.4/ Lua 5.4].
 +
 +
==C++ Function Calls==
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="30%" | Function
 +
! width="70%" | Description
 +
 +
|-
 +
| ''int'' {{text anchor|trandom}}(''int'' n)
 +
| Returns a 32-bit integer from {{Tooltip|0 to n-1|Lua arrays start at 1, C++ arrays start at 0, hence the discrepancy.}}. Uses DF's internal RNG system instead of ``math.random()``.
 +
 +
|-
 +
| ''str'' {{text anchor|capitalize_string_words}}(''str'' s)
 +
| Capitalizes every word in a string.
 +
 +
|-
 +
| ''str'' {{text anchor|capitalize_string_first_word}}(''str'' s)
 +
| Capitalizes the first word in a string.
 +
 +
|-
 +
| ''str'' {{text anchor|utterance}}()
 +
| Returns a word from the [[kobold language]].
 +
 +
|-
 +
| ''void'' {{text anchor|lua_log}}(''str'' s)
 +
| Prints a string to ``Dwarf Fortress/lualog.txt``. The ``log()`` function is more robust and should be used instead.
 +
 +
|-
 +
|
 +
''void'' {{text anchor|raws.register_creatures}}(''table'' lines)<br>
 +
''void'' {{text anchor|raws.register_entities}}(''table'' lines)<br>
 +
''void'' {{text anchor|raws.register_inorganics}}(''table'' lines)<br>
 +
''void'' {{text anchor|raws.register_interactions}}(''table'' lines)<br>
 +
''void'' {{text anchor|raws.register_items}}(''table'' lines)<br>
 +
''void'' {{text anchor|raws.register_languages}}(''table'' lines)<br>
 +
''void'' {{text anchor|raws.register_plants}}(''table'' lines){{verify}}
 +
| Takes a table of [[token]]s 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``.
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="30%" | Function
 +
! width="70%" | Description
 +
 +
|-
 +
| ''table'' {{text anchor|add_generated_info}}(''table'' tbl)
 +
| Adds {{token|GENERATED}} to the input table, and {{token|SOURCE_HFID}}/{{token|SOURCE_ENID}} if IDs are defined. Necessary for generated raws to be saved properly.
 +
 +
|}
 +
 +
===Randomization===
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="30%" | Function
 +
! width="70%" | Description
 +
 +
|-
 +
| ''userdata'' {{text anchor|pick_random}}(''table'' t)
 +
| Returns a random value from a table.
 +
 +
|-
 +
| ''userdata'' {{text anchor|pick_random_no_replace}}(''table'' t)
 +
| Returns a random value from a table, then removes it from the table.
 +
 +
|-
 +
| ''userdata'' {{text anchor|pick_random_conditional}}(''table'' t, ''function'' cond,...)
 +
| Returns a random value from a table that satisfies ``cond(...)``.
 +
 +
|-
 +
| ''bool'' {{text anchor|one_in}}(''num'' x)
 +
| Returns true with a one in x chance.
 +
 +
|-
 +
| ''userdata'' {{text anchor|pick_random_pairs}}(''table'' tbl)
 +
| Returns a random key from a table. For example, ``pick_random_pairs( {WATER = true} )`` returns "WATER".
 +
 +
|-
 +
| ''userdata'' {{text anchor|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'' {{text anchor|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 [[werebeast]]s to generate an interaction and link to options from it.
 +
 +
|}
 +
 +
===Tables===
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="30%" | Function
 +
! width="70%" | Description
 +
|-
 +
| ''table'' {{text anchor|split_to_lines}}(''table'' tbl,''string'' str)
 +
| Adds a string into a table, with each line being a separate key.
 +
 +
|-
 +
| ''table'' {{text anchor|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'' {{text anchor|table_merge}}(''table'' tbl1, ''table'' tbl2)
 +
| Adds each value from ``tbl2`` onto the end of ``tbl1``.
 +
 +
|-
 +
| ''bool'' {{text anchor|find_in_array_part}}(''table'' tbl, ''userdata'' item)
 +
| Returns true if ``item`` is a value in ``tbl``.
 +
 +
|-
 +
| ''void'' {{text anchor|convert_array_to_set}}(''table'' tbl)
 +
| For each key in a table, sets the value to true.
 +
 +
|-
 +
| ''void'' {{text anchor|add_unique}}(''table'' tbl, ''userdata'' item)
 +
| Adds ``item`` to the end of ``tbl`` if not already present.
 +
 +
|-
 +
| ''void'' {{text anchor|remove_item}}(''table'' tbl, ''userdata'' item)
 +
| Removes all instances of ``item`` from ``tbl``.
 +
 +
|-
 +
| ''table'' {{text anchor|shallow_copy}}(''table'' tbl)
 +
| Returns a table copied from all values in the input table.
 +
 +
|-
 +
| ''table'' {{text anchor|deep_copy}}(''table'' tbl)
 +
| Returns a table recursively copied from all values in the input table.
 +
 +
|}
 +
 +
===Debug===
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="40%" | Function
 +
! width="60%" | Description
 +
|-
 +
| ''void'' {{text anchor|log}}(...)
 +
| Logs the input to ``Dwarf Fortress/lualog.txt``. Used for most cases.
 +
 +
|-
 +
| ''string'' {{text anchor|get_caller_loc_string}}()
 +
| Returns the debug source info and the current line.
 +
 +
|-
 +
| ''string'' {{text anchor|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'' {{text anchor|partial_function}}(''function'' f, arg,...)
 +
| Returns ``f(arg,...)``.
 +
 +
|-
 +
| ''function'' {{text anchor|log_table}}(''table''&nbsp;tbl, ''num''&nbsp;debug_level=0, ''num''&nbsp;nest_level=0, ''num''&nbsp;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'' {{text anchor|print_table}}(''table'' tbl, ''num'' nest_level=0)
 +
| Logs a table, regardless of debug level.
 +
 +
|}
 +
 +
===Spheres===
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="45%" | Function
 +
! width="55%" | Description
 +
 +
|-
 +
| ''string'' {{text anchor|get_random_sphere_adjective}}(''string'' [[Sphere#Sphere tokens|sphere]])
 +
| Returns a random string from global table ``random_sphere_adjective[sph]``.
 +
 +
|-
 +
| ''table'' {{text anchor|get_random_sphere_noun}}(''string'' [[Sphere#Sphere tokens|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'' {{text anchor|add_sphere_mpp}}(''table''&nbsp;sphere_list, ''string''&nbsp;[[Sphere#Sphere tokens|new_s]], ''table''&nbsp;available_sphere, ''table''&nbsp;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 beast]]s 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{{Tooltip|*|if debug_level is at least 0}}, 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 [[werebeast]]s 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.
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="20%" | Table
 +
! width="80%" | Description
 +
 +
|-
 +
| preprocess
 +
| Runs once the world's terrain has been finalized and before history can begin.
 +
Includes two functions by default:<br>
 +
``preprocess.demon()``, which populates the distribution of ``demon_type`` string inputs<br>
 +
``preprocess.bogeyman_polymorph()``, which generates the [[bogeyman]]'s polymorph interaction if bogeymen exist<br>
 +
 +
|-
 +
| 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 [[Language token#WORD|word token]] and the value is the translated string.
 +
 +
|}
 +
 +
===Creatures===
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="40%" | Table
 +
! width="40%" | Inputs
 +
! width="60%" | Article
 +
 +
|-
 +
|
 +
creatures.angel.great_beast<br>
 +
creatures.angel.humanoid_generic<br>
 +
creatures.angel.humanoid_warrior
 +
| function(tok)
 +
| [[Angel]] (see [[Angel#Angel types|types]])
 +
 +
|-
 +
| creatures.demon
 +
| function(demon_type,difficulty,tok)
 +
| [[Demon]]
 +
 +
|-
 +
|
 +
creatures.experiment.beast_large<br>
 +
creatures.experiment.beast_small<br>
 +
creatures.experiment.failed_large<br>
 +
creatures.experiment.failed_small<br>
 +
creatures.experiment.humanoid_giant<br>
 +
creatures.experiment.humanoid<br>
 +
| 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{{Tooltip|*|Called by vanilla_procedural, not by init/generators}}
 +
| 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]].
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="40%" | Table
 +
! width="20%" | Inputs
 +
! width="60%" | Articles
 +
 +
|-
 +
| entities.vault_guardian
 +
| function(idx,tok)
 +
| [[Vault]] ([[angel]]s)
 +
 +
|-
 +
| entities.mythical_guardian
 +
| function(idx,tok)
 +
| [[Mysterious dungeon]] ([[dungeon guardian]]s)
 +
 +
|}
 +
 +
===Interactions===
 +
 +
====World====
 +
World interactions are generated in the ``generate_random_interactions()`` step of ``generators.lua``.
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="30%" | Table
 +
! width="30%" | Inputs
 +
! width="60%" | Examples
 +
 +
|-
 +
|
 +
interactions.blessing.minor<br>
 +
interactions.blessing.medium
 +
| function(idx)
 +
| [[Die]] roll effects: luck, holy item, healing, etc
 +
 +
|-
 +
|
 +
interactions.curse.minor<br>
 +
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 [[Surroundings#Evil|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.
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="15%" | Key
 +
! width="30%" | Inputs
 +
! width="60%" | 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 {{token|CE_CAN_DO_INTERACTION|syndrome}} and ``[[Interaction token#Usage|CDI]]``.
 +
* ``end_tbl`` consists of lines that define the [[interaction]].
 +
 +
|}
 +
 +
====Interaction helpers====
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="40%" | Function
 +
! width="60%" | Notes
 +
 +
|-
 +
| ''table''&nbsp;``tbl``, ''table''&nbsp;``end_tbl`` basic_lieutenant(''string''&nbsp;name, ''string''&nbsp;name_plural, ''string''&nbsp;token)
 +
| Generates an interaction that raises an [[intelligent undead]] and calls ``basic_lieutenant_powers(token)``.
 +
 +
|-
 +
| ''table''&nbsp;``tbl``, ''table''&nbsp;``end_tbl`` basic_lieutenant_powers(''string''&nbsp;token)
 +
| Adds any number of powers (chosen from among ``interaction.powers``) and 0-5 sicken effects (from ``add_curses()``) to the current definition.
 +
 +
|-
 +
| ''table''&nbsp;``tbl``, ''table''&nbsp;``end_tbl``, ''int''&nbsp;``idx`` add_curses(''table''&nbsp;tbl, ''table''&nbsp;end_tbl, ''string''&nbsp;token, ''int''&nbsp;num, ''int''&nbsp;start_idx, ''int''&nbsp;sev, ''table''&nbsp;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 {{token|VERB|interaction}}.
 +
 +
|}
 +
 +
===Items===
 +
 +
====Instruments====
 +
 +
The default [[instrument]] system is not currently open to Lua, but ``generators.lua`` defines tables for each token.
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="30%" | Table
 +
! width="30%" | Inputs
 +
! width="40%" | Token
 +
 +
|-
 +
| items.instruments.keyboard
 +
| N/A
 +
| {{token|GENERATE_KEYBOARD_INSTRUMENTS|e}}
 +
 +
|-
 +
| items.instruments.stringed
 +
| N/A
 +
| {{token|GENERATE_STRINGED_INSTRUMENTS|e}}
 +
 +
|-
 +
| items.instruments.wind
 +
| N/A
 +
| {{token|GENERATE_WIND_INSTRUMENTS|e}}
 +
 +
|-
 +
| items.instruments.percussion
 +
| N/A
 +
| {{token|GENERATE_PERCUSSION_INSTRUMENTS|e}}
 +
 +
|}
 +
 +
====Divine equipment====
 +
{{Main|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.
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="20%" | Table
 +
! width="20%" | Inputs
 +
! width="60%" | 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<br>
 +
angel_item_info.armor.armor.gen<br>
 +
angel_item_info.armor.helm.gen<br>
 +
angel_item_info.armor.gloves.gen<br>
 +
angel_item_info.armor.shoes.gen<br>
 +
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<br>
 +
angel_item_info.clothing.armor.gen<br>
 +
angel_item_info.clothing.helm.gen<br>
 +
angel_item_info.clothing.gloves.gen<br>
 +
angel_item_info.clothing.shoes.gen
 +
| function(i,prefix)
 +
| Generates 1 piece of [[clothing]] for each slot.
 +
 +
|-
 +
|
 +
angel_item_info.weapon.PIKE.gen<br>
 +
angel_item_info.weapon.WHIP.gen<br>
 +
angel_item_info.weapon.BOW.gen<br>
 +
angel_item_info.weapon.BLOWGUN.gen<br>
 +
angel_item_info.weapon.AXE.gen<br>
 +
angel_item_info.weapon.SWORD.gen<br>
 +
angel_item_info.weapon.DAGGER.gen<br>
 +
angel_item_info.weapon.MACE.gen<br>
 +
angel_item_info.weapon.HAMMER.gen<br>
 +
angel_item_info.weapon.SPEAR.gen<br>
 +
angel_item_info.weapon.CROSSBOW.gen
 +
| function(i,prefix)
 +
| Generates 5 [[weapon]]s. The tables correspond to [[combat skill]]s, and are not repeated. For example, a vault can't generate two types of swords.
 +
 +
|-
 +
|
 +
angel_item_info.ammo.ARROW<br>
 +
angel_item_info.ammo.BOLT<br>
 +
angel_item_info.ammo.BLOWDART
 +
| function()
 +
| When a ranged weapon is generated, it will also generate a random subtype of the proper ammunition.
 +
 +
|}
 +
 +
===Materials===
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="20%" | Table
 +
! width="15%" | Inputs
 +
! width="15%" | Article
 +
! width="60%" | Notes
 +
 +
|-
 +
| materials.clouds
 +
materials.rain
 +
| function()
 +
| [[Evil weather]]
 +
| Associated regional [[interaction]]s 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]].
 +
{{token|DIVINE|inorganic}} and {{token|SPHERE|inorganic}} 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.
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="40%" | Function
 +
! width="60%" | 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''&nbsp;creature, ''bool''&nbsp;do_water, ''bool''&nbsp;humanoid_only, ''bool''&nbsp;is_good, ''bool''&nbsp;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.
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="40%" | Function
 +
! width="60%" | Notes
 +
 +
|-
 +
| add_regular_tokens(tbl,options)
 +
| Adds tokens to ``tbl``. Sets {{token|PETVALUE|2000}}, 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 {{token|CREATURE_TILE}}. Encloses number arguments in ``''`` characters.
 +
 +
|-
 +
| add_body_size(tbl,size,options)
 +
| Adds {{token|BODY_SIZE|0:0:size}} and sets ``options.body_size``. Calls ``body_size_properties()``.
 +
 +
|-
 +
| body_size_properties(tbl,size,options)
 +
| Adds {{token|BUILDINGDESTROYER|2}} if size > 80,000; adds {{token|GRASSTRAMPLE|20}} and {{token|TRAPAVOID}} if size > 100,000.
 +
 +
|-
 +
| populate_sphere_info(tbl,options)
 +
| Adds {{token|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 [[Venom|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 {{token|DESCRIPTION}} and any {{token|PREFSTRING}}s.
 +
 +
|-
 +
| build_pcg_graphics(tbl,options)
 +
| Assigns [[procedural graphics layer]]s based on ``options.pcg_layering`` keys set by ``build_body_from_rcp()``.
 +
 +
|}
 +
 
===Options===
 
===Options===
 
{| {{prettytable}}
 
{| {{prettytable}}

Revision as of 16:14, 26 March 2025

Modding
Tokens
Audio · Biome · Graphics · Tile page · Interaction · Mod info · Plant · Speech · Sphere · Syndrome · World
Body tokens
Body · Body detail plan · Bodygloss · Tissue
Creature tokens
Creature · Creature mannerism · Personality facet · Creature variation · Procedural graphics layer
Descriptor tokens
Descriptor color · Color · Descriptor pattern · Descriptor shape
Entity tokens
Entity · Ethic · Language · Value · Position
Job tokens
Building · Labor · Reaction · Skill · Unit type
Item tokens
Item type · Item definition · Ammo · Armor · Instrument · Tool · Trap component · Weapon
Material tokens
Material type · Material definition · Inorganic material definition
Lua
Scripting · Examples · Functions
v · t · e


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.

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

Main article: 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].
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 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.

RCP Parameters

Retrieved from "https://dwarffortresswiki.org/index.php?title=Lua_functions&oldid=308801"
CancelHideAbout

Rating Lua functions

Change