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 scripting"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
(→‎Code Samples: Reaction class search)
m (Bay12 update link)
 
(16 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
{{Template:Under_construction}}
+
{{av}}
 +
[[File:Lua-Logo.svg|100px|right]]
 
{{Modding}}
 
{{Modding}}
  
 
''This article is about procedural raw generation. Information on [[Utility:DFHack]] scripting can be found at https://docs.dfhack.org/en/stable/.''
 
''This article is about procedural raw generation. Information on [[Utility:DFHack]] scripting can be found at https://docs.dfhack.org/en/stable/.''
  
−
[https://www.lua.org/ Lua] scripting is an experimental feature{{version|51.06}}. It is used to create custom procedurally-generated objects that were previously created by hardcoded methods. It was announced in a [https://www.youtube.com/watch?v=Z9rzhFwgfUk video], with the stated goal of "supporting future [[Magic|magical]] endeavors."
+
'''[https://www.lua.org/ Lua] scripting''' is a feature of Dwarf Fortress's [[modding]] system. It is used to write definitions for procedurally-generated objects, with the stated goal of "supporting future [[Magic|magical]] endeavors." [https://www.youtube.com/watch?v=Z9rzhFwgfUk]
 +
 
 +
It was added as an experimental feature in version 51.06 [https://store.steampowered.com/news/app/975370/view/547854206358257941?l=english] and incorporated into the 52.01 release. [https://www.bay12games.com/dwarves/index.html#2025-07-21][https://store.steampowered.com/news/app/975370/view/547867141501617961]
  
 
Inorganic [[Material definition token|materials]], [[Language token|languages]], [[Creature token|creatures]], [[Interaction token|interactions]],  [[Item token|items]] (currently excluding instruments), [[reaction]]s, [[Entity token|entities]], and [[Plant token|plants]] are open to this system.
 
Inorganic [[Material definition token|materials]], [[Language token|languages]], [[Creature token|creatures]], [[Interaction token|interactions]],  [[Item token|items]] (currently excluding instruments), [[reaction]]s, [[Entity token|entities]], and [[Plant token|plants]] are open to this system.
  
−
Scripts are loaded from a mod's ``scripts/init.lua`` file, as well as from any included files.
+
Scripts are loaded from a mod's ``scripts/init.lua`` file, and can ``require()`` other files.
 +
 
 +
==Videos==
 +
Announcement video:
 +
*[https://www.youtube.com/watch?v=Z9rzhFwgfUk More powerful mods coming to Dwarf Fortress via Lua]
 +
Tutorials:
 +
*[https://youtu.be/QMxgsUogIIk Generating raws with Lua]
 +
*[https://youtu.be/DEBTWMlUQzA Random creatures with Lua]
  
 
==Structure==
 
==Structure==
  
−
As of right now, Lua scripting is confined to generation of procedural objects. This is done by running the ``generate`` function, a global function loaded in ``'''data/init/generators.lua'''``. It runs unit tests, preprocess, materials, items, languages, creatures, interactions, entities and postprocessing, in that order.
+
As of right now, Lua scripting is confined to generation of procedural objects. This is done by running the ``generate()`` function, a global function loaded in ``'''data/init/generators.lua'''``. It runs unit tests, preprocess, do_once (or do_once_early), materials, items, languages, creatures, interactions, entities and postprocessing, in that order.
 +
 
 +
When random objects are first generated, the game populates two global tables, ``world`` and ``random_object_parameters``.
 +
 
 +
* ``world`` contains info about the world currently being generated (or, in the future, played in). It contains [[World token|worldgen parameters]], raw object definitions, and a few other fields.
 +
 
 +
* ``random_object_parameters`` contains what the game expects to be generated in the current generation call.
 +
 
 +
You can print the contents of these tables to the log to see what data is available. The [https://steamcommunity.com/sharedfiles/filedetails/?id=3492961907 Runtime Dataminer] mod includes a script to read these tables.
  
−
When random objects are first generated, the game populates two global tables, ``world`` and ``random_object_parameters``. ``world`` contains info about the world currently being generated (or, in the future, played in), while ``random_object_parameters`` contains what the game expects to be generated. The most important thing between these is ``random_object_parameters.main_world_randoms``, which is ``true`` for exactly one generation at the start of worldgen; it's what you want to check for if you're generating your own objects
+
DFHack also has a version of [https://github.com/DFHack/df-structures/blob/master/df.world.xml df.world], though these tables are not necessarily equivalent. Headers and paths may differ, even when referencing the same data.
  
 +
===Debugging===
 
You can set the global ``debug_level`` variable to print some debug info. It's a number, but what numbers are there are completely arbitrary. If it's >0, it'll run unit tests; if it's >=0.5, it'll display what step of generation it's at, at every step. You can use ``get_debug_logger(x)`` to return a function that logs to ``lualog.txt`` if the debug level is at least ``x``.
 
You can set the global ``debug_level`` variable to print some debug info. It's a number, but what numbers are there are completely arbitrary. If it's >0, it'll run unit tests; if it's >=0.5, it'll display what step of generation it's at, at every step. You can use ``get_debug_logger(x)`` to return a function that logs to ``lualog.txt`` if the debug level is at least ``x``.
  
−
Unit tests are functions that return a table, containing ``good``, which, if truthy, is considered passed, and ``info``, which is a string that contains information on said pass or fail. These unit tests should have no side effects, i.e. they shouldn't muck with global state any. Here's an example unit test, one that was used during development (but had no reason to be removed):
+
Unit tests are functions that return a table, containing ``good``, which, if truthy, is considered passed, and ``info``, which is a string that contains information on said pass or fail. These unit tests should have no side effects, i.e. they shouldn't muck with global state any. Here's an example unit test shipped with the generators:
  
 
{{Scriptdata
 
{{Scriptdata
−
|title=get_random_creature
+
|title=unittests.get_random_creature
 
|script=
 
|script=
 
     get_random_creature=function()
 
     get_random_creature=function()
Line 31: Line 50:
 
     end}}
 
     end}}
  
−
``preprocess`` is just a table of functions. It runs each function, one at a time. This is where you want your side effects, and, if you're adding an entirely new procedural object type, that's what you probably want. You should also use it if you want to mess around with ``random_object_parameters``, which is allowed (it's how demon types are assigned in vanilla, and you can change the proportions as an end user if you want). The "adamantine alloys" example below is an example of what can be done with preprocess (and postprocess, which is mostly identical except it happens after the rest of generation).
+
===Object generation===
 +
When ``generate()`` is called, it uses ``random_object_parameters`` to determine what is generated.
  
−
The game then generates all of the individual objects; the general procedure for this is that the game calls the ``generate_from_list`` function on a table of functions, which calls every function and picks one of the resulting tables at random depending on their weights. For example, the ``interactions.secrets`` table contains one entry, that for necromancers; it returns a table containing three entries: ``{interaction=tbl,weight=1,spheres=spheres}``. ``interaction`` is the full raw text of the interaction; ``weight`` is the random weight for the interaction, i.e. if you add another one which returns a table containing ``weight=2``, that will be twice as likely as necromancers. ``spheres=spheres`` is some extra data the generator might be able to use. It actually doesn't, at this point, but one could override ``generate_random_interactions`` with their own version that takes into account ``spheres`` and, say, tries to evenly distribute generated secrets over available spheres. (This didn't end up in vanilla primarily out of concerns of bug-like behavior cropping up).
+
Before the world map is generated, ``random_object_parameters.pre_gen_randoms`` is true for one generation. Once the map is finalized, ``random_object_parameters.main_world_randoms`` is true for one generation when "generating prehistory"; most of the initial randomization takes place here. Further generation calls, such as for [[experiment]]s being created, do not set these variables to true.
  
−
Languages are special, though; as can be seen below, the ``languages`` table just expects a table containing translations, e.g. ``tbl["ABBEY"]="abbey"``. If you want to procedurally add words or symbols (and yes, these are both doable), you can use preprocess or postprocess.
+
If you're registering an entirely new procedural object type, you can generate it during these steps. The game includes a number of tables which you can add functions to, the game runs each function in them when generating raws.
  
−
===C++ Function Calls===
+
*``do_once`` only runs in the "main world randoms" generation call and is the safest option for adding new objects.
 +
*``do_once_early`` runs in the "pre-gen randoms" generation call, and can be used for objects that need to be placed in the map like minerals or surface animal populations.
 +
*``preprocess`` runs before either of the former tables, but is run during every ``generate()`` call and you cannot predict when this happens.
 +
*``postprocess`` runs at the end of each ``generate()`` call, after the other steps complete.
  
−
{| {{prettytable}}
+
You can see examples of registering objects through these steps on the [[Lua script examples]] page.
−
|- style='background-color:#ddd'
 
−
! width="20%" | Function
 
−
! width="60%" | Description
 
  
−
|-
+
If you want to use ``preprocess`` or ``postprocess`` to generate raws, you can check if it's the right generation step by reading the aforementioned ``random_object_parameters``. The [[Lua script examples#Adamantine alloys|"adamantine alloys" example]] includes such a check.
−
| ''userdata'' get_random(''table'' t)
 
−
| Returns a random value from a table. Uses DF's own RNG.
 
  
−
|-
+
You can also mess around with ``random_object_parameters`` in preprocessing. Vanilla demon types are assigned here, and you can change the proportions as an end user if you want.
−
| ''int'' trandom(''int'' n)
 
−
| Returns a 32-bit integer from 1 to n. Uses DF's own RNG.
 
  
−
|-
+
====Generation from list====
−
| ''str'' capitalize_string_words(''str'' s)
+
After ``preprocess`` and ``do_once``, the game then generates all of the individual objects that the ``random_object_parameters`` expects. The general procedure for this is that the game calls the ``generate_from_list()`` function on a table of functions, which calls every function and picks one of the resulting values at random depending on their weights.
−
| Capitalizes every word in a string.
 
  
−
|-
+
For example, the ``interactions.secrets`` table contains one entry, that for necromancers; it returns a table containing three entries: ``{raws=tbl,weight=1,spheres=spheres}``.
−
| ''str'' capitalize_string_first_word(''str'' s)
 
−
| Capitalizes the first word in a string.
 
  
−
|-
+
*``raws`` is the full raw text of the interaction.
−
| ''str'' utterance()
+
*``weight`` is the random weight for the interaction, i.e. if you add another function which returns a table containing ``weight=2``, that will be twice as likely as necromancers.
−
| Returns a word from the [[kobold language]].
+
*``spheres`` is some extra data the generator might be able to use. It actually doesn't, at this point, but one could override ``generate_random_interactions()`` with their own version that takes into account ``spheres`` and, say, tries to evenly distribute generated secrets over available spheres. (This didn't end up in vanilla primarily out of concerns of bug-like behavior cropping up).
  
−
|-
+
====Languages====
−
| ''void'' lua_log(''str'' s)
+
Languages are special, though; as can be seen in the [[Divine language/script]] or [[Lua script examples#Identity language|identity language]]. The ``languages`` table just expects to return table containing translations, e.g. ``tbl["ABBEY"]="abbey"``. If you want to procedurally add words or symbols (and yes, these are both doable), you can do so with ``raws.register_languages()`` in another function table.
−
| Prints a string to `Dwarf Fortress/lualog.txt`. The ``log()`` function is more robust and should be used instead.
 
−
 
 
−
|}
 
  
 
==Creatures==
 
==Creatures==
Line 116: Line 126:
 
end}}
 
end}}
  
−
This is a lot of info! First, you build an ``options`` table; it's possible to make a full list of options used in vanilla, but other mods can also use arbitrary options. It then adds all the usual special-to-forgotten-beast tokens, in a big string, followed by calling ``add_regular_tokens(tbl,options)``, which adds some stuff common to all (vanilla) procedural creatures, based on the options given. It sets ``do_water`` and the WATER sphere if the FB is in a water cavern, an option which whitelists certain random creature profiles, as well as adding a random evil sphere. ``populate_sphere_info`` is similar to ``add_regular_tokens``; it adds all of the spheres in ``options.spheres`` to the creature, using the SPHERE token, then, if certain options are set, does more. Then, it gets a random creature profile using ``get_random_creature_profile`` and the options, uses ``add_body_size`` to set the BODY_SIZE tokens and attendant things that come with it, sets the creature tile, and finally runs the Big Function, ``build_procgen_creature``, which creates the description, body, tissues, et cetera.
+
This is a lot of info! First, you build an ``options`` table; it's possible to make a full [[Lua functions#Options|list of options used in vanilla]], but other mods can also use arbitrary options. It then adds all the usual special-to-forgotten-beast tokens, in a big string, followed by calling ``add_regular_tokens(tbl,options)``, which adds some stuff common to all (vanilla) procedural creatures, based on the options given.
 +
 
 +
It sets ``do_water`` and the WATER [[sphere]] if the FB is in a water [[cavern]], an option which whitelists certain random creature profiles, as well as adding a random evil sphere.
 +
 
 +
``populate_sphere_info()`` is similar to ``add_regular_tokens()``; it adds all of the spheres in ``options.spheres`` to the creature, using the {{token|SPHERE}} token, then, if certain options are set, does more.
 +
 
 +
Then, it gets a random creature profile using ``get_random_creature_profile()`` and the options, uses ``add_body_size()`` to set the BODY_SIZE tokens and attendant things that come with it, sets the creature tile, and finally runs the Big Function, ``build_procgen_creature()``, which creates the description, body, tissues, et cetera.
  
 
===Random Creature Profiles===
 
===Random Creature Profiles===
Line 135: Line 151:
 
  }}
 
  }}
  
−
Of these, only ``cannot_have_get_more_legs`` is optional. ``build_procgen_creature`` has direct access to the RCP, as the first argument, and thus extra table entries can be used however you like.
+
Of these, only ``cannot_have_get_more_legs`` is optional. ``build_procgen_creature()`` has direct access to the RCP, as the first argument, and thus extra table entries can be used however you like.
  
−
===Other stuff===
+
``body_base`` points to a key in ``body_base_fun``, which is used to set creature options (walking and [[Procedural graphics layer|PCG layering]] are set this way) and returns a list of [[body token]]s. Quadrupeds use a special function to vary the sprite, so here's the body base function for a humanoid.
−
TODO: Tweaks, random creature materials, random creature classes, color pickers, function that ``build_procgen_creature`` calls in the process of building that can be used to inject your own logic into creature building (e.g. ``btc1_tweaks``), etc.
 
  
−
==Code Samples==
+
{{Scriptdata
 +
|title=body_base_fun.HUMANOID
 +
|script=
 +
HUMANOID=function(rcp,options)
 +
options.pcg_layering_base="BEAST_HUMANOID"
 +
options.walk_var="STANDARD_BIPED_GAITS"
 +
options.walk_speed=900
 +
return {"RCP_UPPER_BODY","RCP_LOWER_BODY","RCP_NECK","RCP_HEAD","RCP_TWO_PART_ARMS","RCP_TWO_PART_LEGS"}
 +
end
 +
}}
  
−
Snippets of vanilla generation can be found in [[:Category:Lua script pages]], and all vanilla scripts can be found in ``data/vanilla/vanilla_procedural/scripts/``.
+
``c_class`` also refers to another determines the kind of tissue layers the creature has. "FLESHY", "MAMMAL", "CHITIN_EXO", etc imply a biological creature with sinew, blood, different organs, nerves, and so on. "UNIFORM" describes a creature made of a single material, the choice influenced by its options. The ``random_creature_class`` and ``random_creature_material`` tables store the info for these traits.
  
−
===Identity language===
+
Organic creatures can be tweaked to alter their surfaces, such as becoming skinless, hairy, or even uniform.
−
This makes a [[Language token|language]] called ``GEN_IDENTITY`` which is like: "Abbey abbeyabbeys the abbey of abbeys" - i.e. it's the "English" language you might see occasionally. It is present in ``vanilla_procedural`` and can be used for {{Token|TRANSLATION|entity}} by default.
 
  
−
{{Scriptdata
+
===Tweaks===
−
|title=GEN_IDENTITY
 
−
|script=
 
−
languages.GEN_IDENTITY=function()
 
−
    -- just to demonstrate the absolute most basic method of generating one of these
 
−
    -- also so that you can just mod stuff to use GEN_IDENTITY
 
−
    local tbl={}
 
−
    local unempty = function(str1, str2)
 
−
        return str1=='' and str2 or str1
 
−
    end
 
−
    for k,v in ipairs(world.language.word) do
 
−
        local str=''
 
−
        str=unempty(str,v.NOUN_SING)
 
−
        str=unempty(str,v.ADJ)
 
−
        str=unempty(str,v.VERB_FIRST_PRES)
 
−
        str=unempty(str,string.lower(v.token))
 
−
        tbl[v.token]=str
 
−
    end
 
−
    return tbl
 
−
end}}
 
  
−
===Search by reaction class===
+
In the broadest sense, a tweak is any deviation from the creature profile. The aforementioned surface changes, new body parts, and attack interactions are all examples of tweaks.
−
This script returns a table of all inorganic materials with a given {{token|REACTION_CLASS|md}}. The ``mat`` table also has ``reaction_product_class``, which includes both {{token|MATERIAL_REACTION_PRODUCT|md}} and {{token|ITEM_REACTION_PRODUCT|md}} IDs.
 
−
{{Scriptdata
 
−
|title=get_all_by_reaction_class()
 
−
|script=
 
−
function get_all_by_reaction_class(rc)
 
−
    local valid={}
 
−
    for i,inorg in ipairs(world.inorganic.inorganic) do
 
−
        for _,class in inorg.mat.reaction_class do
 
−
            if class==rc then
 
−
                valid[#valid+1]=inorg
 
−
            end
 
−
        end
 
−
    end
 
−
    return valid
 
−
end}}
 
  
−
===Kobold language===
+
A number of [[Lua functions#Options|options]] change the available tweaks or force one to happen, for example:
−
This generates a language made of {{token|UTTERANCES}}. This is essentially a proper translation based on the [[kobold language]]. Note that the hardcoded ``utterance()`` function generates words independently of any existing words in the language, so you may get duplicate words.  
+
*``options.no_tweak`` disables random tweaks.
 +
*``options.strong_attack_tweak`` allows the creature to always pick from the ``attack_tweaks`` table; ie: "Beware its webs!"
 +
*``options.humanoid_only`` makes the creature "twisted into humanoid form" (if evil), or "a <creature> in humanoid form" (if otherwise).
  
−
{{Scriptdata
+
One potential use of ``btc1_tweaks`` (see [[Lua functions#Creature patching]]) is to add custom tweak candidates, pointing to keys in ``tweaks``.
−
|title=GEN_KOBOLD
 
−
|script=
 
−
languages.GEN_KOBOLD=function()
 
−
    local tbl={}
 
−
    for k,v in ipairs(world.language.word) do
 
−
        tbl[v.token]=utterance()
 
−
    end
 
−
    return tbl
 
−
end}}
 
  
−
===New divine metal===
+
===Color pickers===
−
You can add new metal descriptions for divine metal pretty easily, for example:
 
  
−
{{Scriptdata
+
Color picker functions can give more fitting [[color]] choices based on the options, instead of the default full spectrum. There are color pickers for certain malevolent [[sphere]]s, giving them a dark appearance. [[Werebeast]]s use a flag to only have natural brown or black colors.
−
|title=Laughing metal
 
−
|script=
 
−
metal_by_sphere.CHILDREN={
 
−
    name="laughing metal",
 
−
    col="7:0:1",
 
−
    color="WHITE"
 
−
}
 
−
}}
 
  
−
===New forgotten beast===
+
If the creature matches ``cond`` and a given [[Descriptor color token|descriptor color]] matches ``color``, then it is added to the list of candidates. Colors have {{Tooltip|h,s,v|Hue, saturation, value}} and {{Tooltip|r,g,b|Red, green, blue}} values ranging from 0-1 (except hue, which ranges 0-360 degrees).
−
Add a new kind of forgotten beast.
 
  
 
{{Scriptdata
 
{{Scriptdata
−
|title=Unbidden spirit
+
|title=color_picker_functions
−
|script=
+
|script=color_picker_functions={
−
creatures.fb.unbidden=function(layer_type,tok)
+
    death_misery={
−
    if layer_type==0 then return nil end -- land only
+
        cond=function(options)
−
     local tbl={}
+
            return options.spheres.DEATH or options.spheres.MISERY
−
     local options={
+
        end,
−
         strong_attack_tweak=true,
+
        color=function(color)
−
         always_make_uniform=true,
+
            -- GRAY TO BLACK/BLUEISH GREEN THAT ARE SOMEWHAT GRAYISH AND MORE BLUE
−
        always_insubstantial=true,
+
            return (color.v<=0.75 and color.s<=0.001) or (color.v==color.b and color.s<=0.25)
−
         intangible_flier=true,
+
        end
−
        spheres={CAVERNS=true},
+
     },
−
         is_evil=true,
+
     darkness_night={
−
         sickness_name="beast sickness",
+
         cond=function(options)
−
         token=tok
+
            return options.spheres.DARKNESS or options.spheres.NIGHT
 +
        end,
 +
         color=function(color)
 +
            -- GRAY TO BLACK OR DARK BLUISH
 +
            return color.v<=0.4 and (color.s < 0.001 or (color.h>180 and color.h<=240))
 +
         end
 +
    },
 +
    werebeast={
 +
        cond=function(options)
 +
            -- werebeasts only, in vanilla
 +
            return options.animal_coloring_allowed
 +
         end,
 +
         color=function(color)
 +
            --BROWN OKAY TOO
 +
            return color.h>=30 and color.h<=48 and color.b<=0.15 and color.v<=0.75 and color.v > 0
 +
         end
 
     }
 
     }
−
    tbl=split_to_lines(tbl,[[
+
}
−
    [FEATURE_BEAST]
 
−
    [ATTACK_TRIGGER:0:0:2]
 
−
    [NAME:unbidden spirit:unbidden spirit:unbidden spirit]
 
−
    [CASTE_NAME:unbidden spirit:unbidden spirit:unbidden spirit]
 
−
    [NO_GENDER]
 
−
    [CARNIVORE]
 
−
    [DIFFICULTY:10]
 
−
 
 
−
    [NATURAL_SKILL:WRESTLING:6]
 
−
    [NATURAL_SKILL:BITE:6]
 
−
    [NATURAL_SKILL:GRASP_STRIKE:6]
 
−
    [NATURAL_SKILL:STANCE_STRIKE:6]
 
−
    [NATURAL_SKILL:MELEE_COMBAT:6]
 
−
    [NATURAL_SKILL:DODGING:6]
 
−
    [NATURAL_SKILL:SITUATIONAL_AWARENESS:6]
 
−
    [LARGE_PREDATOR]
 
−
    ]])
 
−
    add_regular_tokens(tbl,options)
 
−
    tbl[#tbl+1]=layer_type==0 and "[BIOME:SUBTERRANEAN_WATER]" or "[BIOME:SUBTERRANEAN_CHASM]"
 
−
    if layer_type==0 then options.spheres.WATER=true end
 
−
    options.spheres[pick_random(evil_spheres)]=true
 
−
    options.do_water=layer_type==0
 
−
    populate_sphere_info(tbl,options)
 
−
    local rcp=get_random_creature_profile(options)
 
−
    add_body_size(tbl,math.max(10000000,rcp.min_size),options)
 
−
    tbl[#tbl+1]="[CREATURE_TILE:"..tile_string(rcp.tile).."]"
 
−
    build_procgen_creature(rcp,tbl,options)
 
−
    -- Weight is a float; all vanilla objects have weight 1
 
−
    return {creature=tbl,weight=0.5}
 
−
end
 
 
}}
 
}}
  
−
===Remove default forgotten beast===
+
``options.blood_color`` works like a color picker function. If any colors match its function, then its [[blood]] will be colored like one of them. [[Bogeymen]] and [[nightmare]]s have a function that gives them magenta blood, for example, but you can create your own blood color functions.
  
−
<syntaxhighlight lang="lua" >
+
Creatures with other blood types, such as ichor, are unaffected.
−
creatures.fb.default=nil
 
−
</syntaxhighlight>
 
−
 
 
−
===Adamantine alloys===
 
−
 
 
−
You can add your own arbitrary generated objects, though as of right now there's no way to make settings for them. This allows for some ''truly'' wild stuff; here's a fun example: adamantine-metal alloys for every single non-special metal, giving you an average of the properties of them.
 
  
 
{{Scriptdata
 
{{Scriptdata
−
|title=Adamantine alloys
+
|title=options.blood_color (Bogeyman)
−
|script=
+
|script=blood_color=function(cl)
−
preprocess.adamantine_alloys=function()
+
             -- DARKER MAGENTA COLORS
−
    if not random_object_parameters.main_world_randoms then return end
+
             return cl.h>=260 and cl.h <= 340 and cl.v <= 0.5 and cl.v >= 0.1
−
    local l=get_debug_logger(2)
 
−
    local lines={}
 
−
    local reaction_lines={}
 
−
    local reaction_names={}
 
−
    local adamantine=world.inorganic.inorganic.ADAMANTINE
 
−
    if not adamantine then return end
 
−
    local adamantine_color=world.descriptor.color[world.descriptor.color_pattern[adamantine.material.color_pattern.SOLID].color[1]]
 
−
    local adamantine_modulus = 2500000  --mildly arbitrary, just below the theoretical limit
 
−
    l("Starting")
 
−
    local done_category=false
 
−
    for k,v in ipairs(world.inorganic.inorganic) do
 
−
        if not v.flags.SPECIAL and v.material.flags.IS_METAL then
 
−
            l(v.token)
 
−
             local token="GEN_ADAMANTINE_"..v.token
 
−
            lines[#lines+1]="[INORGANIC:"..token.."]"
 
−
            add_generated_info(lines)
 
−
            lines[#lines+1]="[USE_MATERIAL_TEMPLATE:METAL_TEMPLATE]"
 
−
            for kk,vv in pairs(v.material.adj) do
 
−
                lines[#lines+1]="[STATE_ADJ:"..kk..":adamantine "..vv.."]" --"adamantine molten steel"? it's fine
 
−
             end
 
−
            for kk,vv in pairs(v.material.name) do
 
−
                lines[#lines+1]="[STATE_NAME:"..kk..":adamantine "..vv.."]"
 
−
            end
 
−
            l(2)
 
−
            local mat_values={}
 
−
            -- Find the ratio for which you get closest to (but not below) 2000000 in the material's worst property
 
−
            local worst=math.min(v.material.yield.IMPACT,v.material.fracture.SHEAR)
 
−
            local wafers=1
 
−
            local bars=1
 
−
            if worst < 2000000 then
 
−
                local ratio = (2000000-3*worst)/1000000
 
−
                local best_diff=1
 
−
                for i=1,10 do
 
−
                    local wafer_amt=i*ratio
 
−
                    if wafer_amt>1 and wafer_amt<20 and math.ceil(wafer_amt)-wafer_amt<best_diff then
 
−
                        best_diff=math.ceil(wafer_amt)-wafer_amt
 
−
                        wafers=math.ceil(wafer_amt)
 
−
                        bars=i
 
−
                    end
 
−
                end
 
−
            end
 
−
            local avg_denom=1/(bars*3+wafers) -- Multiplication just a bit faster than division, we're rounding at the end anyway
 
−
            local solid_cl=nil
 
−
            for kk,vv in pairs(v.material.color_pattern) do
 
−
                -- time to get silly
 
−
                local this_color=world.descriptor.color[world.descriptor.color_pattern[vv].color[1]]
 
−
                local wanted_color={
 
−
                    r=(this_color.r*bars*3+adamantine_color.r*wafers)*avg_denom,
 
−
                    g=(this_color.g*bars*3+adamantine_color.g*wafers)*avg_denom,
 
−
                    b=(this_color.b*bars*3+adamantine_color.b*wafers)*avg_denom,
 
−
                }
 
−
                local best_total_diff=1000000000
 
−
                local best_clp=nil
 
−
                for _,clp in ipairs(world.descriptor.color_pattern) do
 
−
                    if clp.pattern=="MONOTONE" then
 
−
                        local cl=world.descriptor.color[clp.color[1]]
 
−
                        local diff=math.abs(wanted_color.r-cl.r)+math.abs(wanted_color.b-cl.b)+math.abs(wanted_color.g-cl.g)
 
−
                        if diff<best_total_diff then
 
−
                            best_clp=clp
 
−
                            best_total_diff=diff
 
−
                        end
 
−
                    end
 
−
                end
 
−
                lines[#lines+1]="[STATE_COLOR:"..kk..":"..best_clp.token.."]"
 
−
                if kk=="SOLID" then solid_cl=world.descriptor.color[best_clp.color[1]] end
 
−
            end
 
−
            local color_str=solid_cl.col_f..":0:"..solid_cl.col_br
 
−
            l(color_str)
 
−
            lines[#lines+1]="[DISPLAY_COLOR:"..color_str.."]"
 
−
            lines[#lines+1]="[BUILD_COLOR:"..color_str.."]"
 
−
            lines[#lines+1]="[ITEMS_METAL][ITEMS_HARD][ITEMS_SCALED][ITEMS_BARRED]"
 
−
            lines[#lines+1]="[SPECIAL]"
 
−
            if v.material.flags.ITEMS_DIGGER then
 
−
                lines[#lines+1]="[ITEMS_DIGGER]"
 
−
            end
 
−
            local function new_value(str)
 
−
                mat_values[str]=mat_values[str] or math.floor((adamantine.material[str]*wafers+v.material[str]*bars*3)*avg_denom+0.5)
 
−
                l(str,mat_values[str])
 
−
                return mat_values[str]
 
−
            end
 
−
            local function new_value_nested(str1,str2)
 
−
                mat_values[str1..str2]=mat_values[str1..str2] or math.floor((adamantine.material[str1][str2]*wafers+v.material[str1][str2]*bars*3)/(bars*3+wafers)+0.5)
 
−
                l(str1..str2,mat_values[str1..str2])
 
−
                return mat_values[str1..str2]
 
−
            end
 
−
            if new_value_nested("fracture","SHEAR")>170000 or new_value_nested("yield","IMPACT")>245000 then
 
−
                lines[#lines+1]="[ITEMS_WEAPON][ITEMS_AMMO]"
 
−
                if new_value("solid_density")<10000 then
 
−
                    lines[#lines+1]="[ITEMS_WEAPON_RANGED][ITEMS_ARMOR]"
 
−
                end
 
−
            end
 
−
            lines[#lines+1]="[MATERIAL_VALUE:"..new_value("base_value").."]"
 
−
            lines[#lines+1]="[SPEC_HEAT:"..new_value("temp_spec_heat").."]"
 
−
            lines[#lines+1]="[MELTING_POINT:"..new_value("temp_melting_point").."]"
 
−
            lines[#lines+1]="[BOILING_POINT:"..new_value("temp_boiling_point").."]"
 
−
            lines[#lines+1]="[SOLID_DENSITY:"..new_value("solid_density").."]"
 
−
            lines[#lines+1]="[LIQUID_DENSITY:"..new_value("liquid_density").."]"
 
−
            lines[#lines+1]="[MOLAR_MASS:"..new_value("molar_mass").."]" -- i don't think this is actually correct
 
−
            for _,thing in ipairs({"yield","fracture"}) do
 
−
                for force,_ in pairs(v.material[thing]) do
 
−
                    lines[#lines+1]="["..string.upper(force).."_"..string.upper(thing)..":"..new_value_nested(thing,force).."]"
 
−
                end
 
−
            end
 
−
            for _,force in ipairs("IMPACT","COMPRESSIVE","TENSILE","TORSION","SHEAR","BENDING") do
 
−
                local modulus = v.yield[force] / v.elasticity[force]
 
−
                local average_modulus = (adamantine_modulus*wafers + modulus*bars*3)*avg_denom
 
−
                local strain_at_yield = math.floor(new_value_nested("yield",force) / average_modulus + 0.5) -- usually zero, but can be 1 or 2 sometimes
 
−
                lines[#lines+1]="["..string.upper(force).."_YIELD:"..new_value_nested("yield",force).."]"
 
−
                lines[#lines+1]="["..string.upper(force).."_FRACTURE:"..new_value_nested("fracture",force).."]"
 
−
                lines[#lines+1]="["..string.upper(force).."_STRAIN_AT_YIELD:"..strain_at_yield.."]"
 
−
            end
 
−
            lines[#lines+1]="[MAX_EDGE:"..new_value("max_edge").."]"
 
−
            local reaction_token=token.."_MAKING"
 
−
            reaction_lines[#reaction_lines+1]="[REACTION:"..reaction_token.."]"
 
−
            add_generated_info(reaction_lines)
 
−
            reaction_lines[#reaction_lines+1]="[NAME:make adamantine "..v.material.name.SOLID.." (use bars)]"
 
−
            reaction_lines[#reaction_lines+1]="[BUILDING:SMELTER:NONE]"
 
−
            reaction_lines[#reaction_lines+1]="[REAGENT:A:"..tostring(150*wafers)..":BAR:NO_SUBTYPE:METAL:ADAMANTINE]"
 
−
            reaction_lines[#reaction_lines+1]="[REAGENT:B:"..tostring(150*bars)..":BAR:NO_SUBTYPE:METAL:"..v.token.."]"
 
−
            reaction_lines[#reaction_lines+1]="[PRODUCT:100:"..tostring(bars+wafers)..":BAR:NO_SUBTYPE:METAL:"..token.."][PRODUCT_DIMENSION:150]"
 
−
            reaction_lines[#reaction_lines+1]="[FORTRESS_MODE_ENABLED]"
 
−
            reaction_lines[#reaction_lines+1]="[CATEGORY:ADAMANTINE_ALLOYS]"
 
−
            if not done_category then
 
−
                done_category=true
 
−
                reaction_lines[#reaction_lines+1]="[CATEGORY_NAME:Adamantine alloys]"
 
−
                reaction_lines[#reaction_lines+1]="[CATEGORY_DESCRIPTION:Debase adamantine with other metals to get extremely strong alloys.]"
 
−
                reaction_lines[#reaction_lines+1]="[CATEGORY_KEY:CUSTOM_SHIFT_A]"
 
−
            end
 
−
            reaction_lines[#reaction_lines+1]="[FUEL]"
 
−
            reaction_lines[#reaction_lines+1]="[SKILL:SMELT]"
 
 
         end
 
         end
−
    end
+
}}
−
    local entity_lines={}
+
 
−
    raws.register_inorganics(lines)
 
−
    -- not used in vanilla right now, due to lack of instruments, but you CAN do this
 
−
    raws.register_reactions(reaction_lines)
 
−
end}}
 
 
[[Category:Modding]]
 
[[Category:Modding]]
−
[[Category:Lua]]
+
[[Category:Lua|S]]

Latest revision as of 21:05, 21 July 2025

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

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


This article is about procedural raw generation. Information on Utility:DFHack scripting can be found at https://docs.dfhack.org/en/stable/.

Lua scripting is a feature of Dwarf Fortress's modding system. It is used to write definitions for procedurally-generated objects, with the stated goal of "supporting future magical endeavors." [1]

It was added as an experimental feature in version 51.06 [2] and incorporated into the 52.01 release. [3][4]

Inorganic materials, languages, creatures, interactions, items (currently excluding instruments), reactions, entities, and plants are open to this system.

Scripts are loaded from a mod's scripts/init.lua file, and can require() other files.

Videos[edit]

Announcement video:

Tutorials:

Structure[edit]

As of right now, Lua scripting is confined to generation of procedural objects. This is done by running the generate() function, a global function loaded in data/init/generators.lua. It runs unit tests, preprocess, do_once (or do_once_early), materials, items, languages, creatures, interactions, entities and postprocessing, in that order.

When random objects are first generated, the game populates two global tables, world and random_object_parameters.

  • world contains info about the world currently being generated (or, in the future, played in). It contains worldgen parameters, raw object definitions, and a few other fields.
  • random_object_parameters contains what the game expects to be generated in the current generation call.

You can print the contents of these tables to the log to see what data is available. The Runtime Dataminer mod includes a script to read these tables.

DFHack also has a version of df.world, though these tables are not necessarily equivalent. Headers and paths may differ, even when referencing the same data.

Debugging[edit]

You can set the global debug_level variable to print some debug info. It's a number, but what numbers are there are completely arbitrary. If it's >0, it'll run unit tests; if it's >=0.5, it'll display what step of generation it's at, at every step. You can use get_debug_logger(x) to return a function that logs to lualog.txt if the debug level is at least x.

Unit tests are functions that return a table, containing good, which, if truthy, is considered passed, and info, which is a string that contains information on said pass or fail. These unit tests should have no side effects, i.e. they shouldn't muck with global state any. Here's an example unit test shipped with the generators:

Object generation[edit]

When generate() is called, it uses random_object_parameters to determine what is generated.

Before the world map is generated, random_object_parameters.pre_gen_randoms is true for one generation. Once the map is finalized, random_object_parameters.main_world_randoms is true for one generation when "generating prehistory"; most of the initial randomization takes place here. Further generation calls, such as for experiments being created, do not set these variables to true.

If you're registering an entirely new procedural object type, you can generate it during these steps. The game includes a number of tables which you can add functions to, the game runs each function in them when generating raws.

  • do_once only runs in the "main world randoms" generation call and is the safest option for adding new objects.
  • do_once_early runs in the "pre-gen randoms" generation call, and can be used for objects that need to be placed in the map like minerals or surface animal populations.
  • preprocess runs before either of the former tables, but is run during every generate() call and you cannot predict when this happens.
  • postprocess runs at the end of each generate() call, after the other steps complete.

You can see examples of registering objects through these steps on the Lua script examples page.

If you want to use preprocess or postprocess to generate raws, you can check if it's the right generation step by reading the aforementioned random_object_parameters. The "adamantine alloys" example includes such a check.

You can also mess around with random_object_parameters in preprocessing. Vanilla demon types are assigned here, and you can change the proportions as an end user if you want.

Generation from list[edit]

After preprocess and do_once, the game then generates all of the individual objects that the random_object_parameters expects. The general procedure for this is that the game calls the generate_from_list() function on a table of functions, which calls every function and picks one of the resulting values at random depending on their weights.

For example, the interactions.secrets table contains one entry, that for necromancers; it returns a table containing three entries: {raws=tbl,weight=1,spheres=spheres}.

  • raws is the full raw text of the interaction.
  • weight is the random weight for the interaction, i.e. if you add another function which returns a table containing weight=2, that will be twice as likely as necromancers.
  • spheres is some extra data the generator might be able to use. It actually doesn't, at this point, but one could override generate_random_interactions() with their own version that takes into account spheres and, say, tries to evenly distribute generated secrets over available spheres. (This didn't end up in vanilla primarily out of concerns of bug-like behavior cropping up).

Languages[edit]

Languages are special, though; as can be seen in the Divine language/script or identity language. The languages table just expects to return table containing translations, e.g. tbl["ABBEY"]="abbey". If you want to procedurally add words or symbols (and yes, these are both doable), you can do so with raws.register_languages() in another function table.

Creatures[edit]

Creatures have a lot more to them than other procedural objects. Forgotten beasts are, in a sense, the simplest of them:

This is a lot of info! First, you build an options table; it's possible to make a full list of options used in vanilla, but other mods can also use arbitrary options. It then adds all the usual special-to-forgotten-beast tokens, in a big string, followed by calling add_regular_tokens(tbl,options), which adds some stuff common to all (vanilla) procedural creatures, based on the options given.

It sets do_water and the WATER sphere if the FB is in a water cavern, an option which whitelists certain random creature profiles, as well as adding a random evil sphere.

populate_sphere_info() is similar to add_regular_tokens(); it adds all of the spheres in options.spheres to the creature, using the [SPHERE] token, then, if certain options are set, does more.

Then, it gets a random creature profile using get_random_creature_profile() and the options, uses add_body_size() to set the BODY_SIZE tokens and attendant things that come with it, sets the creature tile, and finally runs the Big Function, build_procgen_creature(), which creates the description, body, tissues, et cetera.

Random Creature Profiles[edit]

A random creature profile is a type of "thing" a generated creature can be. For example:

Of these, only cannot_have_get_more_legs is optional. build_procgen_creature() has direct access to the RCP, as the first argument, and thus extra table entries can be used however you like.

body_base points to a key in body_base_fun, which is used to set creature options (walking and PCG layering are set this way) and returns a list of body tokens. Quadrupeds use a special function to vary the sprite, so here's the body base function for a humanoid.

c_class also refers to another determines the kind of tissue layers the creature has. "FLESHY", "MAMMAL", "CHITIN_EXO", etc imply a biological creature with sinew, blood, different organs, nerves, and so on. "UNIFORM" describes a creature made of a single material, the choice influenced by its options. The random_creature_class and random_creature_material tables store the info for these traits.

Organic creatures can be tweaked to alter their surfaces, such as becoming skinless, hairy, or even uniform.

Tweaks[edit]

In the broadest sense, a tweak is any deviation from the creature profile. The aforementioned surface changes, new body parts, and attack interactions are all examples of tweaks.

A number of options change the available tweaks or force one to happen, for example:

  • options.no_tweak disables random tweaks.
  • options.strong_attack_tweak allows the creature to always pick from the attack_tweaks table; ie: "Beware its webs!"
  • options.humanoid_only makes the creature "twisted into humanoid form" (if evil), or "a <creature> in humanoid form" (if otherwise).

One potential use of btc1_tweaks (see Lua functions#Creature patching) is to add custom tweak candidates, pointing to keys in tweaks.

Color pickers[edit]

Color picker functions can give more fitting color choices based on the options, instead of the default full spectrum. There are color pickers for certain malevolent spheres, giving them a dark appearance. Werebeasts use a flag to only have natural brown or black colors.

If the creature matches cond and a given descriptor color matches color, then it is added to the list of candidates. Colors have h,s,v and r,g,b values ranging from 0-1 (except hue, which ranges 0-360 degrees).

options.blood_color works like a color picker function. If any colors match its function, then its blood will be colored like one of them. Bogeymen and nightmares have a function that gives them magenta blood, for example, but you can create your own blood color functions.

Creatures with other blood types, such as ichor, are unaffected.

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

Rating Lua scripting

Change