Lua scripting - Revision history

DPhKraken: /* Tweaks */ humanoidable_only remap

2026-01-29T06:57:10Z

Tweaks: humanoidable_only remap

Doorkeeper: /* Random Creature Profiles */

2025-12-01T14:26:30Z

Random Creature Profiles

DPhKraken: /* Random Creature Profiles */ Main article

2025-10-24T22:05:32Z

Random Creature Profiles: Main article

DPhKraken: Bay12 update link

2025-07-21T21:05:42Z

Bay12 update link

DPhKraken: 52.01 main Lua release

2025-07-21T20:58:12Z

52.01 main Lua release

DPhKraken: /* Object generation */ Move snippet to example in context

2025-07-13T04:39:07Z

Object generation: Move snippet to example in context

DPhKraken: /* Structure */ Pre-gen randoms

2025-07-13T04:35:36Z

Structure: Pre-gen randoms

DPhKraken: /* Creatures */ Clean up todo section, expand color pickers

2025-07-07T20:33:39Z

Creatures: Clean up todo section, expand color pickers

DPhKraken: /* Tweaks */ Explain tweaks

2025-07-07T19:07:12Z

Tweaks: Explain tweaks

DPhKraken: /* Random Creature Profiles */ Describe RCP traits

2025-07-07T17:37:44Z

Random Creature Profiles: Describe RCP traits

@@ Line 178: / Line 178: @@
 *``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).
+*``options.humanoidable_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``.

@@ Line 152: / Line 152: @@
   }}
-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.
 ``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.

← Older revision		Revision as of 22:05, 24 October 2025
Line 135:		Line 135:

	===Random Creature Profiles===		===Random Creature Profiles===
		+	{{main\|Random creature profile}}
	A random creature profile is a type of "thing" a generated creature can be. For example:		A random creature profile is a type of "thing" a generated creature can be. For example:

@@ Line 7: / Line 7: @@
 '''[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://store.steampowered.com/news/app/975370/view/547867141501617961]
+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.

@@ Line 1: / Line 1: @@
-{{Template:Under_construction}}
+{{av}}
 [[File:Lua-Logo.svg|100px|right]]
 {{Modding}}
@@ Line 5: / Line 5: @@
 ''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."
+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://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.
 Scripts are loaded from a mod's ``scripts/init.lua`` file, and can ``require()`` other files.
 ==Structure==

@@ Line 56: / Line 56: @@
 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 a generation step and stop running your function like so:
+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.
 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.

@@ Line 14: / Line 14: @@
 ==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, do_once, 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``.
@@ Line 20: / Line 20: @@
 * ``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. The most important field 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 outside of ``do_once`` and the standard generation contexts.
+* ``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.
@@ Line 43: / Line 43: @@
 ===Object generation===
-The first steps after debugging are ``preprocess`` and ``do_once``. These are tables of functions, running each one at a time. This is where you want your side effects.
+When ``generate()`` is called, it uses ``random_object_parameters`` to determine what is generated.
-If you're registering an entirely new procedural object type, you can use these steps. ``do_once`` only runs in the "main world randoms" generation call and is the safest option for adding new objects. The [[Lua script examples#Adamantine alloys|"adamantine alloys" example]] is done through these steps. You can also add functions to ``postprocess``, which is like preprocessing but run after all the other generation steps.
+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.
 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====
-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 values at random depending on their weights.
+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: ``{interaction=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).

@@ Line 134: / Line 134: @@
 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 token|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.
+``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.
 {{Scriptdata
@@ Line 155: / Line 155: @@
 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 [[Lua functions#Options|options]] change the available tweaks or force one to happen; ie: ``options.no_tweak`` disables random tweaks, ``options.strong_attack_tweak`` allows access to most of the ``attack_tweaks`` table, ``options.humanoid_only`` makes the creature "twisted into humanoid form".
+A number of [[Lua functions#Options|options]] change the available tweaks or force one to happen, for example:
-One potential use of [[Lua functions#Creature patching|creature patching function tables]] is to add custom tweak candidates (pointing to keys in ``tweaks``).
+One potential use of ``btc1_tweaks`` (see [[Lua functions#Creature patching]]) is to add custom tweak candidates, pointing to keys in ``tweaks``.
 ===Color pickers===
 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.
 {{Scriptdata
@@ Line 197: / Line 202: @@
 }}
-===Logic insertion===
+``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.
-===Other stuff===
+Creatures with other blood types, such as ichor, are unaffected.
 [[Category:Modding]]
 [[Category:Lua|S]]

← Older revision		Revision as of 19:07, 7 July 2025
Line 154:		Line 154:

	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.		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 [[Lua functions#Options\|options]] change the available tweaks or force one to happen; ie: ``options.no_tweak`` disables random tweaks, ``options.strong_attack_tweak`` allows access to most of the ``attack_tweaks`` table, ``options.humanoid_only`` makes the creature "twisted into humanoid form".
		+
		+	One potential use of [[Lua functions#Creature patching\|creature patching function tables]] is to add custom tweak candidates (pointing to keys in ``tweaks``).

	===Color pickers===		===Color pickers===

← Older revision		Revision as of 17:37, 7 July 2025
Line 133:		Line 133:

	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.
		+
		+	``body_base`` points to a key in ``body_base_fun``, which is used to set creature options (walking and [[PCG layering token\|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.
		+
		+	{{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
		+	}}
		+
		+	``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===
		+
		+	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.
		+
		+	===Color pickers===
		+
		+	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.
		+
		+	{{Scriptdata
		+	\|title=color_picker_functions
		+	\|script=color_picker_functions={
		+	death_misery={
		+	cond=function(options)
		+	return options.spheres.DEATH or options.spheres.MISERY
		+	end,
		+	color=function(color)
		+	-- GRAY TO BLACK/BLUEISH GREEN THAT ARE SOMEWHAT GRAYISH AND MORE BLUE
		+	return (color.v<=0.75 and color.s<=0.001) or (color.v==color.b and color.s<=0.25)
		+	end
		+	},
		+	darkness_night={
		+	cond=function(options)
		+	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
		+	}
		+	}
		+	}}

	===Logic insertion===		===Logic insertion===