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}}.
 +
 +