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
(Globals (get_random isn't even a thing))
(→‎Tables: well that's just not right at all)
 
(44 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{av}}
 
{{Modding}}
 
{{Modding}}
  
Line 8: Line 9:
 
|- style='background-color:#ddd'
 
|- style='background-color:#ddd'
 
! width="30%" | Function
 
! width="30%" | Function
−
! width="60%" | Description
+
! width="70%" | Description
  
 
|-
 
|-
Line 29: Line 30:
 
| ''void'' {{text anchor|lua_log}}(''str'' s)
 
| ''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.
 
| Prints a string to ``Dwarf Fortress/lualog.txt``. The ``log()`` function is more robust and should be used instead.
 +
 +
|-
 +
|
 +
''void'' {{text anchor|raws.register_reactions}}(''table'' lines)<br>
 +
''void'' {{text anchor|raws.register_creatures}}(''table'' lines)<br>
 +
''void'' {{text anchor|raws.register_entities}}(''table'' lines)<br>
 +
''void'' {{text anchor|raws.register_items}}(''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_languages}}(''table'' lines)<br>
 +
''void'' {{text anchor|raws.register_plants}}(''table'' lines)
 +
| Takes a table of [[token]]s and reads them as that type of [[raw file]]. It is not necessary to add a header.
  
 
|}
 
|}
  
−
==init/globals.lua==
+
==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===
 
===Randomization===
Line 38: Line 66:
 
|- style='background-color:#ddd'
 
|- style='background-color:#ddd'
 
! width="30%" | Function
 
! width="30%" | Function
−
! width="60%" | Description
+
! width="70%" | Description
  
 
|-
 
|-
−
| ''userdata'' {{text anchor|pick_random}}(''table'' t)
+
| ''value'' {{text anchor|pick_random}}(''table'' t)
 
| Returns a random value from a table.
 
| Returns a random value from a table.
  
 
|-
 
|-
−
| ''userdata'' {{text anchor|pick_random_no_replace}}(''table'' t)
+
| ''value'' {{text anchor|pick_random_no_replace}}(''table'' t)
 
| Returns a random value from a table, then removes it from the table.
 
| Returns a random value from a table, then removes it from the table.
  
 
|-
 
|-
−
| ''userdata'' {{text anchor|pick_random_conditional}}(''table'' t,''function'' cond,...)
+
| ''value'' {{text anchor|pick_random_conditional}}(''table'' t, ''function'' cond,...)
 
| Returns a random value from a table that satisfies ``cond(...)``.
 
| Returns a random value from a table that satisfies ``cond(...)``.
  
Line 57: Line 85:
  
 
|-
 
|-
−
| ''userdata'' {{text anchor|pick_random_pairs}}(''table'' tbl)
+
| ''value'' {{text anchor|pick_random_pairs}}(''table'' tbl)
 
| Returns a random key from a table. For example, ``pick_random_pairs( {WATER = true} )`` returns "WATER".
 
| 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)
+
| ''value'' {{text anchor|pick_weighted_from_table}}(''table'' tbl)
 
| Requires a table of tables with ``weight`` keys. Returns a weighted random value.
 
| Requires a table of tables with ``weight`` keys. Returns a weighted random value.
 
At debug level >=4, logs the roll.
 
At debug level >=4, logs the roll.
  
 
|-
 
|-
−
| ''userdata'' {{text anchor|generate_from_list}}(''table'' tbl,...)
+
| ''value'' {{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.
 
| 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.
  
Line 76: Line 104:
 
|- style='background-color:#ddd'
 
|- style='background-color:#ddd'
 
! width="30%" | Function
 
! width="30%" | Function
−
! width="60%" | Description
+
! width="70%" | Description
 
|-
 
|-
 
| ''table'' {{text anchor|split_to_lines}}(''table'' tbl,''string'' str)
 
| ''table'' {{text anchor|split_to_lines}}(''table'' tbl,''string'' str)
Line 90: Line 118:
  
 
|-
 
|-
−
| ''bool'' {{text anchor|find_in_array_part}}(''table'' tbl, ''userdata'' item)
+
| ''bool'' {{text anchor|find_in_array_part}}(''table'' tbl, ''value'' item)
 
| Returns true if ``item`` is a value in ``tbl``.
 
| Returns true if ``item`` is a value in ``tbl``.
  
 
|-
 
|-
 
| ''void'' {{text anchor|convert_array_to_set}}(''table'' tbl)
 
| ''void'' {{text anchor|convert_array_to_set}}(''table'' tbl)
−
| For each key in a table, sets the value to true.
+
| Makes a set from an array, e.g. takes {"a","b","c"} and makes it {a=true,b=true,c=true} so that it can be indexed.
  
 
|-
 
|-
−
| ''void'' {{text anchor|add_unique}}(''table'' tbl, ''userdata'' item)
+
| ''void'' {{text anchor|add_unique}}(''table'' tbl, ''value'' item)
 
| Adds ``item`` to the end of ``tbl`` if not already present.
 
| Adds ``item`` to the end of ``tbl`` if not already present.
  
 
|-
 
|-
−
| ''void'' {{text anchor|remove_item}}(''table'' tbl, ''userdata'' item)
+
| ''void'' {{text anchor|remove_item}}(''table'' tbl, ''value'' item)
 
| Removes all instances of ``item`` from ``tbl``.
 
| Removes all instances of ``item`` from ``tbl``.
  
Line 119: Line 147:
 
{| {{prettytable}}
 
{| {{prettytable}}
 
|- style='background-color:#ddd'
 
|- style='background-color:#ddd'
−
! width="30%" | Function
+
! width="40%" | Function
 
! width="60%" | Description
 
! width="60%" | Description
 
|-
 
|-
Line 134: Line 162:
  
 
|-
 
|-
−
| ''function'' {{text anchor|partial_function}}(''function'' f,arg,...)
+
| ''function'' {{text anchor|partial_function}}(''function'' f, arg,...)
 
| Returns ``f(arg,...)``.
 
| Returns ``f(arg,...)``.
  
 
|-
 
|-
−
| ''function'' {{text anchor|log_table}}(''table'' tbl,''num'' debug_level=0,''num'' nest_level=0,''num'' added_debug_from_nest=0)
+
| ''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.
 
| 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)
+
| ''function'' {{text anchor|print_table}}(''table'' tbl, ''num'' nest_level=0)
 
| Logs a table, regardless of debug level.
 
| Logs a table, regardless of debug level.
  
Line 152: Line 180:
 
|- style='background-color:#ddd'
 
|- style='background-color:#ddd'
 
! width="45%" | Function
 
! width="45%" | Function
−
! width="60%" | Description
+
! width="55%" | Description
  
 
|-
 
|-
−
| ''string'' {{text anchor|get_random_sphere_adjective}}(''string'' [[Sphere#sphere tokens|sphere]])
+
| ''string'' {{text anchor|get_random_sphere_adjective}}(''string'' [[Sphere#Sphere tokens|sphere]])
 
| Returns a random string from global table ``random_sphere_adjective[sph]``.
 
| Returns a random string from global table ``random_sphere_adjective[sph]``.
  
 
|-
 
|-
−
| ''table'' {{text anchor|get_random_sphere_noun}}(''string'' [[Sphere#sphere tokens|sphere]])
+
| ''table'' {{text anchor|get_random_sphere_noun}}(''string'' [[Sphere#Sphere tokens|sphere]])
 
| Returns a random table ``tbl`` from global table ``random_sphere_nouns[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.
 
``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'' sphere_list, ''string'' [[Sphere#sphere tokens|new_s]], ''table'' available_sphere, ''table'' available_sphere_cur)
+
| ''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.
 
| 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.
 
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===
 +
 +
{{main|Lua scripting#Object generation}}
 +
 +
When the game uses ``generate()`` to generate objects, all functions in the following tables are run in sequence.
 +
 +
``random_object_parameters.pre_gen_randoms`` and ``random_object_parameters.main_world_randoms`` are only ever true for one generation call each, at the start of world generation in that order.
 +
 +
You cannot predict when ``generate()`` is called. Raws registered through ``preprocess`` and ``postprocess`` should check for either variable so that further calls do not endlessly register raws.
 +
 +
Functions stored and called through these tables are not supplied with arguments.
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="20%" | Table
 +
! width="80%" | Description
 +
 +
|-
 +
| preprocess
 +
| Run at the start of each ``generate()`` call, after unit testing.
 +
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 token|interactions]] if bogeymen exist<br>
 +
 +
|-
 +
| do_once_early
 +
| As ``do_once``, but only runs if ``random_object_parameters.pre_gen_randoms == true`` (before the map exists)
 +
Recommended for generating custom objects that need to be placed in the map; ie: animal populations, [[stone layers|minerals]].
 +
 +
|-
 +
| 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`` (in prehistory once the map is finalized)
 +
Recommended for generating most custom objects.<br>
 +
Includes one function by default:<br>
 +
``do_once.rcp_mat_emission()``, adds the ``RCP_MATERIAL_EMISSION`` [[Interaction token|interaction]]
 +
 +
|-
 +
| 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. Initial generation call only.
 +
 +
|}
 +
 +
===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]]
 +
 +
|}
 +
====Creature patching====
 +
{{Main|Lua scripting#Tweaks}}
 +
While ``SELECT_CREATURE`` cannot target generated objects, there are global tables set up to append data when building a creature. These tables contain functions which have access to tokens, options, and local functions from ``build_body_from_rcp()``. All functions in these tables are run at corresponding stages in the build function.
 +
 +
``lines``, ``options`` and ``rcp`` are the creature's raw lines and data, which can be read or modified in these functions.
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="10%" | Table
 +
! width="30%" | Inputs
 +
! width="50%" | Timing
 +
 +
|-
 +
| btc1_tweaks
 +
| function(lines, options, add_to_body, add_to_body_unique, add_tweak_candidate)
 +
| Before ``options.btc`` (the first tweak) is determined.
 +
 +
|-
 +
| feature_tweaks
 +
| function(rcp, options, add_to_body, add_to_body_unique, add_tweak_candidate)
 +
| After ``options.btc2`` is set. ``add_tweak_candidate()`` is unused in vanilla at this stage.
 +
 +
|-
 +
| post_attack_tweaks
 +
| function(lines, options, is_in_body)
 +
| After ``options.attack_tweak`` is set. By default, runs functions to add {{token|ATTACK}}s for body parts.
 +
 +
|-
 +
| post_gait_tweaks
 +
| function(lines, options)
 +
| This is the last operation in the build function.
 +
Includes the ``bogey_polymorph()`` function by default, which checks ``options.can_bogey_polymorph`` to add the interaction.
 +
 +
|}
 +
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="25%" | Local Function
 +
! width="80%" | Effect
 +
 +
|-
 +
| ''void'' add_to_body(str)
 +
| Adds the input [[body token]] to the ``options.body_string`` table.
 +
 +
|-
 +
| ''void'' add_to_body_unique(str)
 +
| As ``add_to_body()`` and ``add_unique()``, only adds if not already present.
 +
 +
|-
 +
| ''void'' add_tweak_candidate(str)
 +
| Adds the input to ``options.body_tweak_candidate``, pointing to a key in the ``tweaks`` table.
 +
 +
|-
 +
| ''bool'' is_in_body(str)
 +
| Checks if the input [[body token]] is in ``options.body_string``.
 +
 +
|}
 +
 +
===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====
 +
 +
Interaction helpers are defined by ``vanilla_procedural``.
 +
 +
{| {{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}}.
 +
 +
|-
 +
| populate_monotone_color_pattern()
 +
| Writes all [[Descriptor color token|MONOTONE color patterns]] from ``world.descriptor.color_pattern`` to the global table ``monotone_color_pattern``, if not already populated.
 +
Not to be confused with ``world.descriptor.color``, which has the same keys as a color rather than a pattern.
 +
 +
|-
 +
| add_base_poison_effects(mat, good_effects, sev, max_eff, min_start, max_start, min_peak, max_peak, min_end, max_end, terminal_chance, resist_chance, size_delay_chance, size_dilute_chance)
 +
| Writes 1 to ``max_eff`` [[syndrome]] effects from ``good_effects`` to ``mat``, a table of raw lines. Has a one in ``terminal_chance`` to not end. If the effect  {{token|RESISTABLE}}
 +
 +
|}
 +
 +
===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===
 +
{| {{prettytable}}
 +
|- style='background-color:#ddd'
 +
! width="15%" | Key
 +
! width="20%" | Usage
 +
! width="80%" | Notes
 +
 +
|-
 +
| token
 +
| add_poison_bits()
 +
build_body_from_rcp()
 +
| The creature's token.
 +
 +
|-
 +
| do_water
 +
| get_random_creature_profile()
 +
| Use an aquatic RCP (``water_based_random_creature``)
 +
 +
|-
 +
| humanoid_only
 +
| get_random_creature_profile()
 +
build_body_from_rcp()
 +
| Use a RCP that can be turned into a humanoid form (``humanoidable_random_creature``), and automatically applies the ``MAKE_HUMANOID`` tweak.
 +
 +
|-
 +
| beast_only
 +
| get_random_creature_profile()
 +
| Forbids generic humanoid/blob/quadruped RCPs (``not_beast_random_creature``).
 +
 +
|-
 +
| normal_biological
 +
| add_regular_tokens()
 +
| If untrue, adds {{token|AMPHIBIOUS}}, {{token|SWIMS_INNATE}}, {{token|NONAUSEA}}, {{token|NOEXERT}}, {{token|NO_DIZZINESS}}, {{token|NOPAIN}}, {{token|NOSTUN}}. Used by [[experiment]]s.
 +
 +
|-
 +
| always_nobreathe
 +
| build_body_from_rcp()
 +
| Adds {{token|NOBREATHE}}, even if not uniform.
 +
 +
|-
 +
| no_general_poison
 +
| build_body_from_rcp()
 +
| If untrue and the creature has blood or ichor, adds {{token|CREATURE_CLASS|c|GENERAL_POISON}}.
 +
 +
|-
 +
| fire_immune
 +
| build_body_from_rcp()
 +
| Adds {{token|FIREIMMUNE}}. Does not affect materials. Set if the creature has a fire interaction.
 +
 +
|-
 +
| material_weakness
 +
| add_regular_tokens()
 +
| Will gain a 10x {{token|MATERIAL_FORCE_MULTIPLIER}} to a random weapon [[metal]] and a {{token|GENERAL_MATERIAL_FORCE_MULTIPLIER|c|1:2}}.
 +
 +
|-
 +
| is_good
 +
|
 +
get_random_creature_profile()<br>
 +
build_body_from_rcp()<br>
 +
build_description()
 +
| Forbids "evil" RCPs (``cannot_be_good_random_creature``).
 +
Affects options for materials, tweaks, description. Cannot have attack tweaks unless the RCP forces it.
 +
 +
|-
 +
| is_evil
 +
| build_body_from_rcp()
 +
build_description()
 +
| Affects options for materials, tweaks, description.
 +
 +
|-
 +
| spheres
 +
| populate_sphere_info()
 +
color_picker_functions<br>
 +
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.UNIFORM.body_fun()
 +
| If uniform, adds an additional 1/2 chance to use a material relevant to their spheres.
 +
 +
|-
 +
| pos_sphere_rcm
 +
| populate_sphere_info()
 +
| Temporary data storage for possible sphere RCM during ``populate_sphere_info()``.
 +
 +
|-
 +
| sphere_rcm
 +
| build_body_from_rcp()
 +
| Forces the creature to be uniform and made of that ``random_creature_material``.
 +
 +
|-
 +
| always_insubstantial
 +
| build_body_from_rcp()
 +
| If uniform, will always choose an insubstantial material from ``insubstantial_materials``.
 +
 +
|-
 +
| never_uniform
 +
| build_body_from_rcp()
 +
| If ``options.r_class`` is UNIFORM, change it to FLESHY.
 +
 +
|-
 +
| always_make_uniform
 +
| build_body_from_rcp()
 +
| Changes ``options.r_class`` to UNIFORM.
 +
 +
|-
 +
| do_not_make_uniform
 +
| build_body_from_rcp()
 +
| Do not randomly change ``options.r_class`` to UNIFORM (normally there is a 1/20 chance), unless ``options.sphere_rcm`` is set.
 +
 +
|-
 +
| walk_var
 +
| build_body_from_rcp()
 +
| A string for {{token|APPLY_CREATURE_VARIATION}}, ex: "STANDARD_WALKING_GAITS". Usually set by ``rcp.body_base``.
 +
 +
|-
 +
| walk_speed
 +
special_walk_speed
 +
| build_body_from_rcp()
 +
| The basic walking speed in a creature's [[gait]]. ``options.special_walk_speed`` will be used instead of ``options.walk_speed`` if both are present.
 +
Crawling bodies use a ``options.walk_speed`` of 2900, walking bodies use 900.
 +
 +
|-
 +
| add_fly_gaits
 +
| build_body_from_rcp()
 +
| Creature has a flying gait even if wings aren't added. ``local add_fly_gaits`` is used for creatures with wings.
 +
 +
|-
 +
| intangible_flier
 +
| build_body_from_rcp()
 +
| If ``options.intangible`` (set by certain uniform materials), sets ``options.add_fly_gaits`` and adds {{token|FILER}}.
 +
 +
|-
 +
| cannot_swim
 +
| build_body_from_rcp()
 +
| Will not add a [[swimming]] gait.
 +
 +
|-
 +
| no_tweak
 +
| build_body_from_rcp()
 +
| Will not add any random tweaks (such as body parts or attacks) to the basic creature that aren't specified by the RCP.
 +
 +
|-
 +
| always_glowing_eyes
 +
| build_body_from_rcp()
 +
| Will always add glowing eyes if the creature has ``options.eyes``.
 +
 +
|-
 +
|
 +
no_glowing_eyes<br>
 +
cannot_have_antennae<br>
 +
cannot_have_mandibles
 +
| build_body_from_rcp()
 +
| Will not add the listed body tweaks.
 +
 +
|-
 +
| no_random_attack_tweak
 +
| build_body_from_rcp()
 +
| Will not add attack tweaks (or body parts that grant them) that aren't specified by the RCP.
 +
 +
|-
 +
| strong_attack_tweak
 +
| build_body_from_rcp()
 +
| Enables access to attack tweaks. Will always gain an attack tweak, unless the RCP already specifies it.
 +
 +
|-
 +
| experiment_attack_tweak
 +
| build_body_from_rcp()
 +
| Enables access to a limited set of attack tweaks 1/4 of the time.
 +
 +
|-
 +
| sickness_name
 +
| add_poison_bits()
 +
| Determines the name of [[syndrome]]s caused by this creature.
 +
 +
|-
 +
| poison_state
 +
| add_poison_bits()
 +
build_body_from_rcp()
 +
| Accepts "LIQUID" (default), "GAS", or "SOLID_POWDER". Determines the state of this creature's [[venom]].
 +
 +
|-
 +
| prioritize_bite
 +
| post_attack_tweaks
 +
| If true, non-bite attacks will have {{token|PRIORITY|c|SECOND}}. If untrue, non-bite attacks will have {{token|PRIORITY|c|MAIN}}.
 +
 +
|-
 +
| bite_interaction
 +
| post_attack_tweaks
 +
| Adds {{token|SPECIALATTACK_INTERACTION}} to bite attacks.
 +
 +
|-
 +
| can_bogey_polymorph
 +
| post_gait_tweaks
 +
| Allows the creature to use the [[bogeyman]] polymorph interaction.
 +
 +
|-
 +
| rcp
 +
| build_body_from_rcp()
 +
build_description()
 +
| Set in ``build_body_from_rcp()`` from the ``rcp`` argument.
 +
Usually derived from ``random_creature_types``, passes information from the random creature profile.
 +
 +
|-
 +
| r_class
 +
| build_body_from_rcp()
 +
| Set to a table in ``random_creature_class``. Describes the basic tissues/features a creature has, such as FLESHY, CHITIN_EXO, or UNIFORM.
 +
 +
|-
 +
| surface
 +
| build_body_from_rcp()
 +
| The creature's exterior tissue. Set based on its ``random_creature_class`` and any tweaks.
 +
 +
|-
 +
| rcm
 +
| random_creature_class.UNIFORM.body_fun()
 +
| Set by ``random_creature_class.UNIFORM.body_fun()``.
 +
If ``options.sphere_rcm`` is supplied, will use that, otherwise will be randomly chosen based on ``options.is_evil``, ``options.is_good``, ``options.pick_sphere_rcm``, ``options.rcp.requires_flexible_material``, and ``options.always_insubstantial``.
 +
 +
|-
 +
| post_mat_adj
 +
| build_description()
 +
| A string that says "composed of X", etc. Normally supplied by ``random_creature_material``.
 +
 +
|-
 +
| matgloss
 +
| random_creature_class.UNIFORM.body_fun()
 +
| Temporary data storage when calling inorganic materials from ``random_creature_material``.
 +
 +
|-
 +
| tok1
 +
tok2
 +
| random_creature_class.UNIFORM.body_fun()
 +
| A uniform creature's {{token|TISSUE_MATERIAL|tissue|options.tok1:options.tok2}}.
 +
Must be supplied by ``random_creature_material``.
 +
 +
|-
 +
| mat_temp1
 +
mat_temp2
 +
| random_creature_class.UNIFORM.body_fun()
 +
| A uniform creature's {{token|USE_MATERIAL_TEMPLATE|c|options.tok1:options.tok2}}.
 +
Can be supplied by ``random_creature_material`` to add an organic material.
 +
 +
|-
 +
| st_tok
 +
| random_creature_class.UNIFORM.body_fun()
 +
| A uniform creature's {{token|TISSUE_MAT_STATE|tissue}}. Must be supplied by ``random_creature_material``.
 +
 +
|-
 +
| fixed_temp
 +
| random_creature_class.UNIFORM.body_fun()
 +
| A uniform creature's {{token|FIXED_TEMP|}}.
 +
Can be supplied by ``random_creature_material``. If a material template is used, adds {{token|MAT_FIXED_TEMP|md}}.
 +
 +
|-
 +
| intangible
 +
| build_body_from_rcp()
 +
| Flag normally supplied by ``random_creature_material``. Creature is non-solid, serves as the condition for ``options.intangible_flier``. Limits access to attack tweak.
 +
 +
|-
 +
| fire_mat
 +
| build_body_from_rcp()
 +
| Flag normally supplied by ``random_creature_material``. Prevents a fire breath attack.
 +
 +
|-
 +
| body_string
 +
| build_body_from_rcp()
 +
| An array of all {{token|BODY}} tokens used.
 +
 +
|-
 +
| body_size
 +
| build_description()
 +
build_pcg_graphics()
 +
| Set by ``body_size_properties()``. Stores the creature's volume for later use.
 +
 +
|-
 +
| body_tweak_candidate
 +
| build_body_from_rcp()
 +
| Temporary data storage for assigning tweaks.
 +
 +
|-
 +
| tweak
 +
| ''quadruped_function_curry()''
 +
| Temporary data storage for quadruped leg tweaks.
 +
 +
|-
 +
|
 +
attack_tweak<br>
 +
btc<br>
 +
btc2<br>
 +
| build_body_from_rcp()
 +
build_description()
 +
| Strings used as a key to retrieve information about the chosen tweaks. Set by ``build_body_from_rcp()``
 +
 +
|-
 +
|
 +
eyes<br>
 +
beak<br>
 +
brain<br>
 +
cheeks<br>
 +
eyelids<br>
 +
guts<br>
 +
heart<br>
 +
lips<br>
 +
lungs<br>
 +
mouth<br>
 +
neck<br>
 +
nose<br>
 +
ribs<br>
 +
skull<br>
 +
spine<br>
 +
teeth<br>
 +
throat<br>
 +
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<br>
 +
ichor<br>
 +
goo
 +
| build_body_from_rcp()
 +
| Normally set by the creature's ``random_creature_class`` (MAMMAL, CHITIN_EXO, etc).
 +
Sets the creature's default {{token|BLOOD}} type.
 +
 +
|-
 +
| force_goo
 +
force_ichor
 +
| build_body_from_rcp()
 +
| If the creature is not uniform, overwrites the creature's default {{token|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``.
 +
 +
|-
 +
|
 +
glowing_eyes<br>
 +
fingers<br>
 +
toes<br>
 +
finger_claws<br>
 +
toe_claws<br>
 +
finger_nails<br>
 +
toe_nails<br>
 +
finger_talons<br>
 +
toe_talons<br>
 +
bat_wings<br>
 +
lacy_wings<br>
 +
feathered_wings<br>
 +
has_proboscis<br>
 +
do_webs
 +
 +
| build_procgen_creature()
 +
| Set when building the body if the creature has those traits. Can be called by the description and when building graphics.
 +
[[Nail]]s, claws, and talons are given attacks.
 +
 +
|-
 +
| eye_count
 +
| build_procgen_creature()
 +
| The number of eyes the creature has. Set when building the body.
 +
 +
|-
 +
| tail_count
 +
| build_procgen_creature()
 +
| The number of tails the creature has. Can be set before building the body.
 +
 +
|-
 +
| clp
 +
| build_procgen_creature()
 +
| The creature's body color. Chosen randomly or based on material unless ``rcp.cannot_have_color`` is true.
 +
 +
|-
 +
| eye_clp
 +
| build_procgen_creature()
 +
| The creature's eye color. Set when building the body.
 +
 +
|-
 +
|
 +
color_f<br>
 +
color_b<br>
 +
color_br
 +
| build_body_from_rcp()
 +
| Set based on ``options.clp`` unless ``options.forced_color`` is supplied. Adds {{token|COLOR|c|options.color_f:options.color_b:options.color_br}}.
 +
 +
|-
 +
| forced_color
 +
| build_body_from_rcp()
 +
| Adds {{token|COLOR|c|options.forced_color.f:options.forced_color.b:options.forced_color.br}} and {{token|NO_UNIT_TYPE_COLOR}}.
 +
 +
|-
 +
| animal_coloring_allowed
 +
| build_body_from_rcp()
 +
| Color must be a shade of brown.
 +
 +
|-
 +
| experiment_colors
 +
| build_body_from_rcp()
 +
| Uses the set of colors assigned to [[experiment]]s.
 +
 +
|-
 +
| exp_proc_surface_color
 +
| build_pcg_graphics
 +
| Stores the index of an experiment's color, for portraits.
 +
 +
|-
 +
|
 +
name_mat<br>
 +
flavor_adj<br>
 +
potential_end_phrase
 +
| Custom names
 +
| An array of names for a creature's material. Can be supplied by ``random_creature_material``.
 +
 +
|-
 +
| feature_flavor_adj
 +
| Custom names
 +
| When ``build_description()`` is run, populates ``options.flavor_adj`` with strings based on the creature's tweaks and [[color]].
 +
 +
|-
 +
| can_learn
 +
| build_description()
 +
| Enables certain description strings, such as "it knows and intones the names of all it encounters". Used by default intelligent creatures.
 +
 +
|-
 +
| no_extra_description
 +
| build_description()
 +
| Will not add strings from ``default_desc_adds``/``good_desc_adds``/``evil_desc_adds`` to the end of the description.
 +
 +
|-
 +
| custom_desc_func
 +
| build_description()
 +
| Adds the output of a string instead of ``default_desc_adds``/etc. Cannot have ``options.no_extra_description.``
 +
 +
|-
 +
| end_phrase
 +
| build_description()
 +
| Adds a phrase after all other generated description pieces, such as [[Night creature|"Now you know why you fear the night."]]
 +
 +
|-
 +
| and_add
 +
| build_description()
 +
| Temporary storage for description grammar.
 +
 +
|-
 +
| pref_str
 +
| build_description()
 +
| A table of possible {{token|PREFSTRING}}s.
 +
 +
|-
 +
| fallback_pref_str
 +
| build_description()
 +
| A string that is added to ``options.pref_str`` it is empty.
 +
 +
|-
 +
| odor_string
 +
odor_level
 +
| build_body_from_rcp()
 +
| Sets {{token|ODOR_STRING|}} and {{token|ODOR_LEVEL|}} respectively. Can be supplied by ``random_creature_material``.
 +
 +
|-
 +
| forced_odor_string
 +
forced_odor_level
 +
forced_odor_chance
 +
| build_body_from_rcp()
 +
| Sets {{token|ODOR_STRING|}} and {{token|ODOR_LEVEL|}} (defaults to 90), 1 in ``options.forced_odor_chance`` of the time.
 +
 +
|-
 +
| always_odor
 +
| build_body_from_rcp()
 +
| Can use the ``options.forced_odor_string`` even if creature is uniform.
 +
 +
|-
 +
| pcg_layering
 +
| build_pcg_graphics()
 +
| A set of [[procedural graphics layer]]s. Set by ``build_pcg_graphics()``.
 +
 +
|-
 +
| pcg_layering_base
 +
| build_pcg_graphics()
 +
| The basic PCG layer-set string, concatenated to form ``options.pcg_layering`` keys. Set by ``build_body_from_rcp()``.
 +
 +
|-
 +
| pcg_layering_modifier
 +
| build_pcg_graphics()
 +
| A set of extra info for PCG layering, such as experiment skin types. Set by ``build_body_from_rcp()``.
 +
 +
|-
 +
| use_werebeast_pcg
 +
| build_pcg_graphics()
 +
| If true, use the layers for [[werebeast]]s.
 +
 +
|-
 +
| experiment_layering
 +
| build_pcg_graphics()
 +
| If true, use the layers for humanoid [[experiment]]s. Expects ``options.experiment_colors`` to be true.
 +
 +
|-
 +
|
 +
is_male_version
 +
night_creature_strength_pref
 +
night_creature_agile_pref
 +
night_creature_strength_agile_pref
 +
| night_troll_names
 +
| Flags used by [[Night troll]]s.
 +
 +
|-
 +
| no_default_werebeast_curse
 +
| werebeast_origin_interactions.default()
 +
| If this is true for a custom function in creatures.night_creature.werebeast, ``generate_from_list(werebeast_origin_interactions,tok,rcp.name_string,options)`` will not be able to use werebeast_origin_interactions.default. This allows [[mod]]s to better control access to [[werebeast]] curses.
 +
 +
|-
 +
| amalgam_experiment
 +
failed_experiment
 +
| ''experiment_description()''
 +
| Flags used for default [[experiment]]s.
 +
 +
 +
|-
 +
| experiment_name_type
 +
| ''experiment_name_token''
 +
| Array of nouns used instead of ``ropar.making_experiment`` for naming [[experiment]]s.
 +
 +
|-
 +
| is_large
 +
| ''make_failed_rcp()''
 +
| Used for large failed [[experiment]]s. Capitalizes the creature tile.
 +
 +
|-
 +
| eadj
 +
fadj
 +
| Custom names
 +
| Temporary data storage for complex name generation.
 +
 +
|}
 +
 +
===RCP Parameters===
  
 
[[Category:Modding]]
 
[[Category:Modding]]
 
[[Category:Lua|F]]
 
[[Category:Lua|F]]

Latest revision as of 17:51, 10 October 2025

v52.04 · v0.47.05
This article is about the current version of DF.
Note that some content may still need to be updated.

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[edit]

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_reactions(table lines)
void  raws.register_creatures(table lines)
void  raws.register_entities(table lines)
void  raws.register_items(table lines)
void  raws.register_inorganics(table lines)
void  raws.register_interactions(table lines)
void  raws.register_languages(table lines)
void  raws.register_plants(table lines)

Takes a table of tokens and reads them as that type of raw file. It is not necessary to add a header.

Globals[edit]

Helper functions are defined in init/globals.lua, and can be accessed by any script even if vanilla_procedural is not loaded.

Generation[edit]

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[edit]

Function Description
value  pick_random(table t) Returns a random value from a table.
value  pick_random_no_replace(table t) Returns a random value from a table, then removes it from the table.
value  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.
value  pick_random_pairs(table tbl) Returns a random key from a table. For example, pick_random_pairs( {WATER = true} ) returns "WATER".
value  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.

value  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[edit]

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, value item) Returns true if item is a value in tbl.
void  convert_array_to_set(table tbl) Makes a set from an array, e.g. takes {"a","b","c"} and makes it {a=true,b=true,c=true} so that it can be indexed.
void  add_unique(table tbl, value item) Adds item to the end of tbl if not already present.
void  remove_item(table tbl, value 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[edit]

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[edit]

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[edit]

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[edit]

Main article: Lua scripting#Object generation

When the game uses generate() to generate objects, all functions in the following tables are run in sequence.

random_object_parameters.pre_gen_randoms and random_object_parameters.main_world_randoms are only ever true for one generation call each, at the start of world generation in that order.

You cannot predict when generate() is called. Raws registered through preprocess and postprocess should check for either variable so that further calls do not endlessly register raws.

Functions stored and called through these tables are not supplied with arguments.

Table Description
preprocess Run at the start of each generate() call, after unit testing.

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 interactions if bogeymen exist

do_once_early As do_once, but only runs if random_object_parameters.pre_gen_randoms == true (before the map exists)

Recommended for generating custom objects that need to be placed in the map; ie: animal populations, minerals.

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 (in prehistory once the map is finalized)

Recommended for generating most custom objects.
Includes one function by default:
do_once.rcp_mat_emission(), adds the RCP_MATERIAL_EMISSION interaction

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. Initial generation call only.

Creatures[edit]

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

Creature patching[edit]

Main article: Lua scripting#Tweaks

While SELECT_CREATURE cannot target generated objects, there are global tables set up to append data when building a creature. These tables contain functions which have access to tokens, options, and local functions from build_body_from_rcp(). All functions in these tables are run at corresponding stages in the build function.

lines, options and rcp are the creature's raw lines and data, which can be read or modified in these functions.

Table Inputs Timing
btc1_tweaks function(lines, options, add_to_body, add_to_body_unique, add_tweak_candidate) Before options.btc (the first tweak) is determined.
feature_tweaks function(rcp, options, add_to_body, add_to_body_unique, add_tweak_candidate) After options.btc2 is set. add_tweak_candidate() is unused in vanilla at this stage.
post_attack_tweaks function(lines, options, is_in_body) After options.attack_tweak is set. By default, runs functions to add [ATTACK]s for body parts.
post_gait_tweaks function(lines, options) This is the last operation in the build function.

Includes the bogey_polymorph() function by default, which checks options.can_bogey_polymorph to add the interaction.

Local Function Effect
void add_to_body(str) Adds the input body token to the options.body_string table.
void add_to_body_unique(str) As add_to_body() and add_unique(), only adds if not already present.
void add_tweak_candidate(str) Adds the input to options.body_tweak_candidate, pointing to a key in the tweaks table.
bool is_in_body(str) Checks if the input body token is in options.body_string.

Entities[edit]

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[edit]

World[edit]

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[edit]

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[edit]

Interaction helpers are defined by vanilla_procedural.

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].
populate_monotone_color_pattern() Writes all MONOTONE color patterns from world.descriptor.color_pattern to the global table monotone_color_pattern, if not already populated.

Not to be confused with world.descriptor.color, which has the same keys as a color rather than a pattern.

add_base_poison_effects(mat, good_effects, sev, max_eff, min_start, max_start, min_peak, max_peak, min_end, max_end, terminal_chance, resist_chance, size_delay_chance, size_dilute_chance) Writes 1 to max_eff syndrome effects from good_effects to mat, a table of raw lines. Has a one in terminal_chance to not end. If the effect [RESISTABLE]

Items[edit]

Instruments[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

Key Usage Notes
token add_poison_bits()

build_body_from_rcp()

The creature's token.
do_water get_random_creature_profile() Use an aquatic RCP (water_based_random_creature)
humanoid_only get_random_creature_profile()

build_body_from_rcp()

Use a RCP that can be turned into a humanoid form (humanoidable_random_creature), and automatically applies the MAKE_HUMANOID tweak.
beast_only get_random_creature_profile() Forbids generic humanoid/blob/quadruped RCPs (not_beast_random_creature).
normal_biological add_regular_tokens() If untrue, adds [AMPHIBIOUS], [SWIMS_INNATE], [NONAUSEA], [NOEXERT], [NO_DIZZINESS], [NOPAIN], [NOSTUN]. Used by experiments.
always_nobreathe build_body_from_rcp() Adds [NOBREATHE], even if not uniform.
no_general_poison build_body_from_rcp() If untrue and the creature has blood or ichor, adds [CREATURE_CLASS:GENERAL_POISON].
fire_immune build_body_from_rcp() Adds [FIREIMMUNE]. Does not affect materials. Set if the creature has a fire interaction.
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].
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. Cannot have attack tweaks unless the RCP forces it.

is_evil build_body_from_rcp()

build_description()

Affects options for materials, tweaks, description.
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.UNIFORM.body_fun() If uniform, adds an additional 1/2 chance to use a material relevant to their spheres.
pos_sphere_rcm populate_sphere_info() Temporary data storage for possible sphere RCM during populate_sphere_info().
sphere_rcm build_body_from_rcp() Forces the creature to be uniform and made of that random_creature_material.
always_insubstantial build_body_from_rcp() If uniform, will always choose an insubstantial material from insubstantial_materials.
never_uniform build_body_from_rcp() If options.r_class is UNIFORM, change it to FLESHY.
always_make_uniform build_body_from_rcp() Changes options.r_class to UNIFORM.
do_not_make_uniform build_body_from_rcp() Do not randomly change options.r_class to UNIFORM (normally there is a 1/20 chance), unless options.sphere_rcm is set.
walk_var build_body_from_rcp() A string for [APPLY_CREATURE_VARIATION], ex: "STANDARD_WALKING_GAITS". Usually set by rcp.body_base.
walk_speed

special_walk_speed

build_body_from_rcp() The basic walking speed in a creature's gait. options.special_walk_speed will be used instead of options.walk_speed if both are present.

Crawling bodies use a options.walk_speed of 2900, walking bodies use 900.

add_fly_gaits build_body_from_rcp() Creature has a flying gait even if wings aren't added. local add_fly_gaits is used for creatures with wings.
intangible_flier build_body_from_rcp() If options.intangible (set by certain uniform materials), sets options.add_fly_gaits and adds [FILER].
cannot_swim build_body_from_rcp() Will not add a swimming gait.
no_tweak build_body_from_rcp() Will not add any random tweaks (such as body parts or attacks) to the basic creature that aren't specified by the RCP.
always_glowing_eyes build_body_from_rcp() Will always add glowing eyes if the creature has options.eyes.

no_glowing_eyes
cannot_have_antennae
cannot_have_mandibles

build_body_from_rcp() Will not add the listed body tweaks.
no_random_attack_tweak build_body_from_rcp() Will not add attack tweaks (or body parts that grant them) that aren't specified by the RCP.
strong_attack_tweak build_body_from_rcp() Enables access to attack tweaks. Will always gain an attack tweak, unless the RCP already specifies it.
experiment_attack_tweak build_body_from_rcp() Enables access to a limited set of attack tweaks 1/4 of the time.
sickness_name add_poison_bits() Determines the name of syndromes caused by this creature.
poison_state add_poison_bits()

build_body_from_rcp()

Accepts "LIQUID" (default), "GAS", or "SOLID_POWDER". Determines the state of this creature's venom.
prioritize_bite post_attack_tweaks If true, non-bite attacks will have [PRIORITY:SECOND]. If untrue, non-bite attacks will have [PRIORITY:MAIN].
bite_interaction post_attack_tweaks Adds [SPECIALATTACK_INTERACTION] to bite attacks.
can_bogey_polymorph post_gait_tweaks Allows the creature to use the bogeyman polymorph interaction.
rcp build_body_from_rcp()

build_description()

Set in build_body_from_rcp() from the rcp argument.

Usually derived from random_creature_types, passes information from the random creature profile.

r_class build_body_from_rcp() Set to a table in random_creature_class. Describes the basic tissues/features a creature has, such as FLESHY, CHITIN_EXO, or UNIFORM.
surface build_body_from_rcp() The creature's exterior tissue. Set based on its random_creature_class and any tweaks.
rcm random_creature_class.UNIFORM.body_fun() Set by random_creature_class.UNIFORM.body_fun().

If options.sphere_rcm is supplied, will use that, otherwise will be randomly chosen based on options.is_evil, options.is_good, options.pick_sphere_rcm, options.rcp.requires_flexible_material, and options.always_insubstantial.

post_mat_adj build_description() A string that says "composed of X", etc. Normally supplied by random_creature_material.
matgloss random_creature_class.UNIFORM.body_fun() Temporary data storage when calling inorganic materials from random_creature_material.
tok1

tok2

random_creature_class.UNIFORM.body_fun() A uniform creature's [TISSUE_MATERIAL:options.tok1:options.tok2].

Must be supplied by random_creature_material.

mat_temp1

mat_temp2

random_creature_class.UNIFORM.body_fun() A uniform creature's [USE_MATERIAL_TEMPLATE:options.tok1:options.tok2].

Can be supplied by random_creature_material to add an organic material.

st_tok random_creature_class.UNIFORM.body_fun() A uniform creature's [TISSUE_MAT_STATE]. Must be supplied by random_creature_material.
fixed_temp random_creature_class.UNIFORM.body_fun() A uniform creature's [FIXED_TEMP].

Can be supplied by random_creature_material. If a material template is used, adds [MAT_FIXED_TEMP].

intangible build_body_from_rcp() Flag normally supplied by random_creature_material. Creature is non-solid, serves as the condition for options.intangible_flier. Limits access to attack tweak.
fire_mat build_body_from_rcp() Flag normally supplied by random_creature_material. Prevents a fire breath attack.
body_string build_body_from_rcp() An array of all [BODY] tokens used.
body_size build_description()

build_pcg_graphics()

Set by body_size_properties(). Stores the creature's volume for later use.
body_tweak_candidate build_body_from_rcp() Temporary data storage for assigning tweaks.
tweak quadruped_function_curry() Temporary data storage for quadruped leg tweaks.

attack_tweak
btc
btc2

 build_body_from_rcp()

build_description()

Strings used as a key to retrieve information about the chosen tweaks. Set by build_body_from_rcp()

eyes
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 default [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.

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_procgen_creature() 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.

eye_count build_procgen_creature() The number of eyes the creature has. Set when building the body.
tail_count build_procgen_creature() The number of tails the creature has. Can be set before building the body.
clp build_procgen_creature() The creature's body color. Chosen randomly or based on material unless rcp.cannot_have_color is true.
eye_clp build_procgen_creature() The creature's eye color. Set when building the body.

color_f
color_b
color_br

build_body_from_rcp() Set based on options.clp unless options.forced_color is supplied. Adds [COLOR:options.color_f:options.color_b:options.color_br].
forced_color build_body_from_rcp() Adds [COLOR:options.forced_color.f:options.forced_color.b:options.forced_color.br] and [NO_UNIT_TYPE_COLOR].
animal_coloring_allowed build_body_from_rcp() Color must be a shade of brown.
experiment_colors build_body_from_rcp() Uses the set of colors assigned to experiments.
exp_proc_surface_color build_pcg_graphics Stores the index of an experiment's color, for portraits.

name_mat
flavor_adj
potential_end_phrase

Custom names An array of names for a creature's material. Can be supplied by random_creature_material.
feature_flavor_adj Custom names When build_description() is run, populates options.flavor_adj with strings based on the creature's tweaks and color.
can_learn build_description() Enables certain description strings, such as "it knows and intones the names of all it encounters". Used by default intelligent creatures.
no_extra_description build_description() Will not add strings from default_desc_adds/good_desc_adds/evil_desc_adds to the end of the description.
custom_desc_func build_description() Adds the output of a string instead of default_desc_adds/etc. Cannot have options.no_extra_description.
end_phrase build_description() Adds a phrase after all other generated description pieces, such as "Now you know why you fear the night."
and_add build_description() Temporary storage for description grammar.
pref_str build_description() A table of possible [PREFSTRING]s.
fallback_pref_str build_description() A string that is added to options.pref_str it is empty.
odor_string

odor_level

build_body_from_rcp() Sets [ODOR_STRING] and [ODOR_LEVEL] respectively. Can be supplied by random_creature_material.
forced_odor_string

forced_odor_level forced_odor_chance

build_body_from_rcp() Sets [ODOR_STRING] and [ODOR_LEVEL] (defaults to 90), 1 in options.forced_odor_chance of the time.
always_odor build_body_from_rcp() Can use the options.forced_odor_string even if creature is uniform.
pcg_layering build_pcg_graphics() A set of procedural graphics layers. Set by build_pcg_graphics().
pcg_layering_base build_pcg_graphics() The basic PCG layer-set string, concatenated to form options.pcg_layering keys. Set by build_body_from_rcp().
pcg_layering_modifier build_pcg_graphics() A set of extra info for PCG layering, such as experiment skin types. Set by build_body_from_rcp().
use_werebeast_pcg build_pcg_graphics() If true, use the layers for werebeasts.
experiment_layering build_pcg_graphics() If true, use the layers for humanoid experiments. Expects options.experiment_colors to be true.

is_male_version night_creature_strength_pref night_creature_agile_pref night_creature_strength_agile_pref

night_troll_names Flags used by Night trolls.
no_default_werebeast_curse werebeast_origin_interactions.default() If this is true for a custom function in creatures.night_creature.werebeast, generate_from_list(werebeast_origin_interactions,tok,rcp.name_string,options) will not be able to use werebeast_origin_interactions.default. This allows mods to better control access to werebeast curses.
amalgam_experiment

failed_experiment

experiment_description() Flags used for default experiments.


experiment_name_type experiment_name_token Array of nouns used instead of ropar.making_experiment for naming experiments.
is_large make_failed_rcp() Used for large failed experiments. Capitalizes the creature tile.
eadj

fadj

Custom names Temporary data storage for complex name generation.

RCP Parameters[edit]

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