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)
Line 1: Line 1:
−
{{Modding}}
+
===Options===
−
 
 
−
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}}
 
{| {{prettytable}}
 
|- style='background-color:#ddd'
 
|- style='background-color:#ddd'
−
! width="30%" | Function
+
! width="20%" | Key
−
! width="70%" | Description
+
! width="20%" | Usage
 +
! width="80%" | Notes
  
 
|-
 
|-
−
| ''int'' {{text anchor|trandom}}(''int'' n)
+
| do_water
−
| 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()``.
+
| get_random_creature_profile()
 +
| Use an aquatic RCP (``water_based_random_creature``)
  
 
|-
 
|-
−
| ''str'' {{text anchor|capitalize_string_words}}(''str'' s)
+
| humanoid_only
−
| Capitalizes every word in a string.
+
| get_random_creature_profile()
−
 
+
| Use a RCP that can be turned into a humanoid form (``humanoidable_random_creature``)
−
|-
 
−
| ''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.
 
  
 
|-
 
|-
 +
| is_good
 
|
 
|
−
''void'' {{text anchor|raws.register_creatures}}(''table'' lines)<br>
+
get_random_creature_profile()<br>
−
''void'' {{text anchor|raws.register_entities}}(''table'' lines)<br>
+
build_body_from_rcp()<br>
−
''void'' {{text anchor|raws.register_inorganics}}(''table'' lines)<br>
+
build_description()
−
''void'' {{text anchor|raws.register_interactions}}(''table'' lines)<br>
+
| Forbids "evil" RCPs (``cannot_be_good_random_creature``).
−
''void'' {{text anchor|raws.register_items}}(''table'' lines)<br>
+
Affects options for materials, tweaks, description.
−
''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)
+
| is_evil
−
| 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.
+
| build_body_from_rcp()
−
 
+
build_description()
−
|}
+
| Affects options for materials, tweaks, description.
−
 
 
−
===Randomization===
 
−
{| {{prettytable}}
 
−
|- style='background-color:#ddd'
 
−
! width="30%" | Function
 
−
! width="70%" | Description
 
  
 
|-
 
|-
−
| ''userdata'' {{text anchor|pick_random}}(''table'' t)
+
| beast_only
−
| Returns a random value from a table.
+
| get_random_creature_profile()
 +
| Forbids generic humanoid/blob/quadruped RCPs (``not_beast_random_creature``).
  
 
|-
 
|-
−
| ''userdata'' {{text anchor|pick_random_no_replace}}(''table'' t)
+
| normal_biological
−
| Returns a random value from a table, then removes it from the table.
+
| add_regular_tokens()
 +
| If false, adds {{token|AMPHIBIOUS}}, {{token|SWIMS_INNATE}}, {{token|NONAUSEA}}, {{token|NOEXERT}}, {{token|NO_DIZZINESS}}, {{token|NOPAIN}}, {{token|NOSTUN}}.
  
 
|-
 
|-
−
| ''userdata'' {{text anchor|pick_random_conditional}}(''table'' t, ''function'' cond,...)
+
| material_weakness
−
| Returns a random value from a table that satisfies ``cond(...)``.
+
| 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}}.
  
 
|-
 
|-
−
| ''bool'' {{text anchor|one_in}}(''num'' x)
+
| body_size
−
| Returns true with a one in x chance.
+
| build_description()
 +
build_pcg_graphics()
 +
| Set by ``body_size_properties()``. Stores the creature's volume for later use.
  
 
|-
 
|-
−
| ''userdata'' {{text anchor|pick_random_pairs}}(''table'' tbl)
+
| spheres
−
| Returns a random key from a table. For example, ``pick_random_pairs( {WATER = true} )`` returns "WATER".
+
| populate_sphere_info()
−
 
+
color_picker_functions<br>
−
|-
+
build_description()
−
| ''userdata'' {{text anchor|pick_weighted_from_table}}(''table'' tbl)
+
| A set of the creature's spheres.
−
| 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
 
  
 
|-
 
|-
−
|
+
| do_sphere_rcm
−
interactions.curse.minor<br>
+
| populate_sphere_info()
−
interactions.curse.medium
+
| Adds a 1/2 chance to set ``sphere_rcm`` to a material relevant to their spheres.
−
| function(idx)
 
−
| [[Die]] roll effects: week of curse
 
  
 
|-
 
|-
−
| interactions.curse.major
+
| pick_sphere_rcm
−
| function(idx,tok)
+
| random_creature_class
−
| [[Vampire]]
+
| If uniform, adds an additional 1/2 chance to use a material relevant to their spheres.
  
 
|-
 
|-
−
| interactions.disturbance
+
| pos_sphere_rcm
−
| function(idx)
+
| populate_sphere_info()
−
| [[Mummy]]
+
| Data storage for possible sphere RCM during ``populate_sphere_info()``.
−
 
 
−
|-
 
−
| 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.
 
  
 
|-
 
|-
 +
| sphere_rcm
 
|  
 
|  
−
angel_item_info.weapon.PIKE.gen<br>
+
| Forces the creature to be uniform and made of that ``random_creature_material``.
−
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.
 
  
 
|-
 
|-
−
|  
+
| body_string
−
angel_item_info.ammo.ARROW<br>
+
| build_body_from_rcp()
−
angel_item_info.ammo.BOLT<br>
+
| An array of all {{token|BODY}} tokens used.
−
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]]
 
 
|
 
|
−
 
+
beak<br>
−
|}
+
brain<br>
−
 
+
cheeks<br>
−
==Random Creatures==
+
eyelids<br>
−
 
+
guts<br>
−
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.
+
heart<br>
−
 
+
lips<br>
−
===RCP Functions===
+
lungs<br>
−
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.
+
mouth<br>
−
 
+
neck<br>
−
{| {{prettytable}}
+
nose<br>
−
|- style='background-color:#ddd'
+
ribs<br>
−
! width="40%" | Function
+
skull<br>
−
! width="60%" | Notes
+
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.
  
 
|-
 
|-
−
| ''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="20%" | Key
 
−
! width="20%" | Usage
 
−
! width="80%" | 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()<br>
+
blood<br>
−
build_body_from_rcp()<br>
+
ichor<br>
−
build_description()
+
goo
−
| Forbids "evil" RCPs (``cannot_be_good_random_creature``).
 
−
Affects options for materials, tweaks, description.
 
−
 
 
−
|-
 
−
| is_evil
 
 
| build_body_from_rcp()
 
| build_body_from_rcp()
−
build_description()
+
| Normally set by the creature's ``random_creature_class`` (MAMMAL, CHITIN_EXO, etc).
−
| Affects options for materials, tweaks, description.
+
Sets the creature's default {{token|BLOOD}} type.
−
 
+
|}
−
|-
 
−
| beast_only
 
−
| get_random_creature_profile()
 
−
| Forbids generic humanoid/blob/quadruped RCPs (``not_beast_random_creature``).
 
  
−
|}
+
===RCP Parameters===
  
 
[[Category:Modding]]
 
[[Category:Modding]]
 
[[Category:Lua|F]]
 
[[Category:Lua|F]]

Revision as of 16:12, 26 March 2025

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=308800"