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.

Lua scripting

From Dwarf Fortress Wiki
(Redirected from Lua)
Jump to navigation Jump to search
Dwarven science stretched.png Research Pending!
This article or section is incomplete/under construction (likely due to recent changes) and may still be outdated or missing details. Feel free to do some testing and expand it.

Modding
Tokens
Audio · Biome · Graphics · 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
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 an experimental featurev51.06. It is used to create custom procedurally-generated objects that were previously created by hardcoded methods. It was announced in a video, with the stated goal of "supporting future magical endeavors."

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, as well as from any included files.

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, 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), 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

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):

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

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

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.

C++ Function Calls[edit]

Function Description
userdata get_random(table t) Returns a random value from a table. Uses DF's own RNG.
int trandom(int n) Returns a 32-bit integer from 1 to n. Uses DF's own RNG.
str capitalize_string_words(str s) Capitalizes every word in a string.
str capitalize_string_first_word(str s) Capitalizes the first word in a string.
str utterance() Returns a word from the kobold language.
void lua_log(str s) Prints a string to `Dwarf Fortress/lualog.txt`. The log() function is more robust and should be used instead.

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.

Other stuff[edit]

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

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/.

Identity language[edit]

This makes a 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 [TRANSLATION] by default.

Search by reaction class[edit]

This script returns a table of all inorganic materials with a given [REACTION_CLASS]. The mat table also has reaction_product_class, which includes both [MATERIAL_REACTION_PRODUCT] and [ITEM_REACTION_PRODUCT] IDs.

Kobold language[edit]

This generates a language made of [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.

New divine metal[edit]

You can add new metal descriptions for divine metal pretty easily, for example:

New forgotten beast[edit]

Add a new kind of forgotten beast.

Remove default forgotten beast[edit]

creatures.fb.default=nil

Adamantine alloys[edit]

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.

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