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 script examples"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
(→‎Generators: Creature tutorial scripts)
Line 307: Line 307:
 
creatures.fb.default=nil
 
creatures.fb.default=nil
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
===Basic generated creature===
 +
 +
This is essentially the simplest possible creature. It has no extraordinary options (beyond an [[Sphere|association]] with animals and creation), and each world generates one species from this function. It doesn't have any biome tokens or likewise, so it can only be spawned in the arena, but it is still functional.
 +
 +
A sample output would be "A quadruped composed of flame. It has two narrow tails and it has a regal bearing."
 +
 +
{{Scriptdata
 +
|title=do_once.basic_creature
 +
|script=do_once.basic_creature = function()
 +
local lines = {}
 +
local tok="BASIC_PROCEDURAL_CREATURE"
 +
lines[#lines+1]="[CREATURE:"..tok.."]"
 +
add_generated_info(lines)
 +
 +
local options={
 +
token=tok,
 +
spheres={
 +
ANIMALS=true,
 +
CREATION=true
 +
}
 +
}
 +
lines=split_to_lines(lines,[[
 +
[NAME:procedural creature:procedural creatures:procedural]
 +
[CASTE_NAME:procedural creature:procedural creatures:procedural]
 +
]])
 +
--adds some common tokens depending on the options
 +
add_regular_tokens(lines,options)
 +
 +
--handles sphere options: fills out [SPHERE] tokens from options.spheres, and so on
 +
populate_sphere_info(lines,options)
 +
 +
--choose a creature profile to base on
 +
local rcp=get_random_creature_profile(options)
 +
--set [BODY_SIZE] and some relevant tokens
 +
add_body_size(lines,rcp.min_size,options)
 +
--add the tile from the creature profile
 +
lines[#lines+1]="[CREATURE_TILE:"..tile_string(rcp.tile).."]"
 +
 +
--the Big Function determining tweaks, body, appearance, description...
 +
build_procgen_creature(rcp,lines,options)
 +
 +
raws.register_creatures(lines)
 +
end
 +
}}
 +
 +
===Making your own RCP===
 +
 +
You don't have to be limited to the vanilla list of random creature variants. Mods can add new kinds of random creature profiles, materials, etc that can be seamlessly integrated into how it generates creatures.
 +
 +
This script generates a single creature based on a [[Wiki:Eurypterid|eurypterid]]. It has a unique RCP, set in the function itself.
 +
 +
{{Scriptdata
 +
|title=do_once.local_rcp
 +
|script=do_once.local_rcp = function()
 +
local lines = {}
 +
local tok="LOCAL_RCP"
 +
lines[#lines+1]="[CREATURE:"..tok.."]"
 +
add_generated_info(lines)
 +
 +
local options={
 +
token=tok,
 +
spheres={
 +
ANIMALS=true,
 +
WATER=true
 +
}
 +
}
 +
add_regular_tokens(lines,options)
 +
populate_sphere_info(lines,options)
 +
--habitat
 +
lines[#lines+1]="[BIOME:ANY_OCEAN]"
 +
lines[#lines+1]="[LARGE_ROAMING]"
 +
lines[#lines+1]="[AQUATIC][UNDERSWIM]"
 +
 +
--define a local creature profile
 +
local rcp={
 +
name_string="eurypterid",
 +
tile='E',
 +
body_base="SCORPION",
 +
c_class="CHITIN_EXO",
 +
must_have_pincers=true,
 +
must_have_tail=true,
 +
min_size=70000,
 +
weight=200,
 +
}
 +
local name_str = rcp.name_string..":"..rcp.name_string.."s:"..rcp.name_string.."]"
 +
lines[#lines+1] = "[NAME:"..name_str
 +
lines[#lines+1] = "[CASTE_NAME:"..name_str
 +
 +
add_body_size(lines,rcp.min_size,options)
 +
lines[#lines+1]="[CREATURE_TILE:"..tile_string(rcp.tile).."]"
 +
build_procgen_creature(rcp,lines,options)
 +
 +
raws.register_creatures(lines)
 +
end
 +
}}
 +
<br><br>
 +
Adding a eurypterid profile to ``random_creature_profiles`` allows any creature to access it, if their profile is determined randomly.
 +
 +
This script gives it proper flippers in its body base function. It's also associated with water-based random creatures, so it can potentially generate as an aquatic [[forgotten beast]] species.
 +
 +
Other feature variants stored in tables, like materials, attacks, or descriptions, can be added in this way.
 +
 +
{{Scriptdata
 +
|title=Global RCP
 +
|script=
 +
random_creature_types.EURYPTERID={
 +
name_string="eurypterid",
 +
tile='E',
 +
body_base="SCORPION_FLIPPERS",
 +
c_class="CHITIN_EXO",
 +
must_have_pincers=true,
 +
must_have_tail=true,
 +
min_size=70000,
 +
weight=200,
 +
}
 +
 +
body_base_fun.SCORPION_FLIPPERS=function(rcp,options)
 +
options.pcg_layering_base="BEAST_SCORPION"
 +
options.walk_var="STANDARD_WALKING_GAITS"
 +
options.walk_speed=900
 +
return {"RCP_CEPHALOTHORAX","RCP_ABDOMEN","RCP_FIRST_SIMPLE_LEGS","RCP_SECOND_SIMPLE_LEGS","RCP_THIRD_SIMPLE_LEGS","RCP_PINCERS","RCP_FRONT_FLIPPER"}
 +
end
 +
 +
water_based_random_creature.EURYPTERID=true
 +
}}
  
 
===New forgotten beasts===
 
===New forgotten beasts===
Line 359: Line 485:
 
     -- Weight is a float; all vanilla objects have weight 1
 
     -- Weight is a float; all vanilla objects have weight 1
 
     return {creature=tbl,weight=0.5}
 
     return {creature=tbl,weight=0.5}
 +
end
 +
}}
 +
 +
===Tweaking creatures===
 +
 +
<!--Consolidate the creature patching stuff in a single header-->
 +
This function is run in ``build_body_from_rcp()`` right before tweaks are determined. If a generated creature's size is greater than 500,000 Γ (about as much as an [[elephant]]), this patch adds {{token|POWER}} and the like to make forgotten beasts, titans, etc capable of impersonating [[Deity|deities]] and ruling [[civilization]]s.
 +
 +
{{Scriptdata
 +
|title=btc1_tweaks.titan_worship
 +
|script=
 +
-- make all large creatures into powers
 +
btc1_tweaks.titan_worship=function(lines,options,add_to_body,add_to_body_unique,add_tweak_candidate)
 +
if options.body_size>=500000 then -- described as "very large", graphics size cutoff
 +
options.can_learn=true -- for flavor text
 +
lines[#lines+1]="[INTELLIGENT]"
 +
lines[#lines+1]="[SUPERNATURAL]" -- knows secrets according to their spheres
 +
lines[#lines+1]="[POWER]" -- impersonates deities
 +
lines[#lines+1]="[SPREAD_EVIL_SPHERES_IF_RULER]"
 +
end
 
end
 
end
 
}}
 
}}

Revision as of 04:34, 7 July 2025

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


Main article: Lua scripting

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

Helper functions

Search by reaction class

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.

Languages

Identity language

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.

Kobold language

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.

Generators

Non-random generated material

Here's an example of an object registered through the do_once table. There are no random elements, it is equivalent (save for being [GENERATED]) to an object defined through Material definition tokens and registered through the raws.register_inorganics() function. It also prints itself to the lualog for debugging purposes.



You can register multiple objects at the same time. This script takes a table of color tokens, and makes a metal named after each of them, with a corresponding cheaty adventure reaction.

Random generation

Here's an example of various DF-specific randomizers in use:

  • trandom() is used to determine how many metals generate this way.
  • utterance() generates utterances from the Kobold language, e.g. "gorsnus", "stogodilmus", "gaylgis"
  • pick_random_no_replace() determines the color from the table, but removes the rolled value so there's no repeats.

New divine metals

Many of the tables used by vanilla procedural objects are global and thus can be added to or overwritten by mods. You can add new metal descriptions for divine metal pretty easily, for example:



You can also add alternatives to the default divine metal function, such as one based on the aforementioned kobold metals. Vanilla divine metal uses metal_by_sphere to determine its properties, and is thus valid only if the input sphere has an entry in that table. Note that even if the weights are nominally the same; because it is valid for all input spheres, it will outnumber instances of the more limited vanilla material.

Remove default functions

Just as easily as you can add new functions and table entries, you can overwrite default entries so that they cannot generate. This snippet removes the default forgotten beasts.

See Lua functions#Generation Tables for a list of the tables the default functions are stored in. 

creatures.fb.default=nil

Basic generated creature

This is essentially the simplest possible creature. It has no extraordinary options (beyond an association with animals and creation), and each world generates one species from this function. It doesn't have any biome tokens or likewise, so it can only be spawned in the arena, but it is still functional.

A sample output would be "A quadruped composed of flame. It has two narrow tails and it has a regal bearing."

Making your own RCP

You don't have to be limited to the vanilla list of random creature variants. Mods can add new kinds of random creature profiles, materials, etc that can be seamlessly integrated into how it generates creatures.

This script generates a single creature based on a eurypterid. It has a unique RCP, set in the function itself.



Adding a eurypterid profile to random_creature_profiles allows any creature to access it, if their profile is determined randomly.

This script gives it proper flippers in its body base function. It's also associated with water-based random creatures, so it can potentially generate as an aquatic forgotten beast species.

Other feature variants stored in tables, like materials, attacks, or descriptions, can be added in this way.

New forgotten beasts

You can add new types of forgotten beasts, generating as alternatives when populating the caverns with unique monsters. There are a number of options to interact with shared generation functions.

Unbidden spirits only appear in dry cave layers, and like "spirit" demons, are malevolent floating beings made of gas or dust.

Tweaking creatures

This function is run in build_body_from_rcp() right before tweaks are determined. If a generated creature's size is greater than 500,000 Γ (about as much as an elephant), this patch adds [POWER] and the like to make forgotten beasts, titans, etc capable of impersonating deities and ruling civilizations.

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.

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

Rating Lua script examples

Change