modtools/* scripts provide tools for modders, often with changes
to the raw files, and are not intended to be called manually by end-users.
They all have standard arguments: arguments are of the form
tool -argName1 argVal1
-argName2 argVal2. This is equivalent to
tool -argName2 argVal2 -argName1
argVal1. It is not necessary to provide a value to an argument name:
-argName3 is fine.
Argument names are preceded with a dash, and supplying the same argument name multiple times will result in an error.
-help argument to any
modtools script will print a descriptive
usage string describing the arguments, similar to the documentation here.
For multiple word argument values, brackets must be used:
-argName4 [ sadf1 sadf2 sadf3 ]. In order to allow passing literal braces as
part of the argument, backslashes are used:
tool -argName4 [ \] asdf \foo ]
\] asdf foo. The
*-trigger scripts have a similar
policy with backslashes.
- Scripts for Modders
This allows adding and removing syndromes from units.
-syndrome name the name of the syndrome to operate on examples: "gila monster bite" -resetPolicy policy specify a policy of what to do if the unit already has an instance of the syndrome. examples: NewInstance default behavior: create a new instance of the syndrome DoNothing ResetDuration AddDuration -erase instead of adding an instance of the syndrome, erase one -eraseAll erase every instance of the syndrome -eraseClass SYN_CLASS erase every instance of every syndrome with the given SYN_CLASS -target id the unit id of the target unit examples: 0 28 -skipImmunities add the syndrome to the target even if it is immune to the syndrome
This allows running a short simple Lua script passed as an argument instead of running a script from a file. This is useful when you want to do something too complicated to make with the existing modtools, but too simple to be worth its own script file. Example:
anonymous-script "print(args)" arg1 arg2 # prints "arg1"
Replaces the createitem plugin, with standard arguments. The other versions will be phased out in a later version.
-creator id specify the id of the unit who will create the item, or \\LAST to indicate the unit with id df.global.unit_next_id-1 examples: 0 2 \\LAST -material matstring specify the material of the item to be created examples: INORGANIC:IRON CREATURE_MAT:DWARF:BRAIN PLANT_MAT:MUSHROOM_HELMET_PLUMP:DRINK -item itemstr specify the itemdef of the item to be created examples: WEAPON:ITEM_WEAPON_PICK -matchingShoes create two of this item -matchingGloves create two of this item, and set handedness appropriately
Creates a unit. Usage:
-race raceName specify the race of the unit to be created examples: DWARF HUMAN -caste casteName specify the caste of the unit to be created examples: MALE FEMALE -domesticate if the unit can't learn or can't speak, make it a friendly animal -civId id Make the created unit a member of the specified civ (or none if id = -1). If id is \\LOCAL, make it a member of the civ associated with the fort; otherwise id must be an integer -groupId id Make the created unit a member of the specified group (or none if id = -1). If id is \\LOCAL, make it a member of the group associated with the fort; otherwise id must be an integer -name entityRawName set the unit's name to be a random name appropriate for the given entity. examples: MOUNTAIN -nick nickname set the unit's nickname directly -location [ x y z ] create the unit at the specified coordinates -age howOld set the birth date of the unitby current age -flagSet [ flag1 flag2 ... ] set the specified unit flags in the new unit to true flags may be selected from df.unit_flags1, df.unit_flags2, or df.unit_flags3 -flagClear [ flag1 flag2 ... ] set the specified unit flags in the new unit to false flags may be selected from df.unit_flags1, df.unit_flags2, or df.unit_flags3
Force a unit to equip an item with a particular body part; useful in
conjunction with the
create scripts above. See also forceequip.
This script writes extra information to the gamelog. This is useful for tools like Soundsense.
This tool triggers events like megabeasts, caravans, and migrants.
-eventType event specify the type of the event to trigger examples: MegaBeast Migrants Caravan Diplomat WildlifeCurious WildlifeMischievous WildlifeFlier NightCreature -civ entity specify the civ of the event, if applicable examples: player MOUNTAIN EVIL 28
This triggers events when a unit uses an interaction on another. It works by scanning the announcements for the correct attack verb, so the attack verb must be specified in the interaction. It includes an option to suppress this announcement after it finds it.
-clear unregisters all triggers -onAttackStr str trigger the command when the attack verb is "str". both onAttackStr and onDefendStr MUST be specified -onDefendStr str trigger the command when the defend verb is "str". both onAttackStr and onDefendStr MUST be specified -suppressAttack delete the attack announcement from the combat logs -suppressDefend delete the defend announcement from the combat logs -command [ commandStrs ] specify the command to be executed commandStrs \\ATTACK_VERB \\DEFEND_VERB \\ATTACKER_ID \\DEFENDER_ID \\ATTACK_REPORT \\DEFEND_REPORT \\anything -> \anything anything -> anything
You must specify both an attack string and a defend string to guarantee correct performance. Either will trigger the script when it happens, but it will not be triggered twice in a row if both happen.
This tool configurably destroys invader items to prevent clutter or to prevent the player from getting tools exclusive to certain races.
-clear reset all registered data -allEntities [true/false] set whether it should delete items from invaders from any civ -allItems [true/false] set whether it should delete all invader items regardless of type when an appropriate invader dies -item itemdef set a particular itemdef to be destroyed when an invader from an appropriate civ dies. examples: ITEM_WEAPON_PICK -entity entityName set a particular entity up so that its invaders destroy their items shortly after death. examples: MOUNTAIN EVIL
This powerful tool triggers DFHack commands when a unit equips, unequips, or attacks another unit with specified item types, specified item materials, or specified item contaminants.
-clear clear all registered triggers -checkAttackEvery n check the attack event at least every n ticks -checkInventoryEvery n check inventory event at least every n ticks -itemType type trigger the command for items of this type examples: ITEM_WEAPON_PICK RING -onStrike trigger the command on appropriate weapon strikes -onEquip trigger the command when someone equips an appropriate item -onUnequip trigger the command when someone unequips an appropriate item -material mat trigger the commmand on items with the given material examples INORGANIC:IRON CREATURE_MAT:DWARF:BRAIN PLANT_MAT:MUSHROOM_HELMET_PLUMP:DRINK -contaminant mat trigger the command on items with a given material contaminant examples INORGANIC:IRON CREATURE_MAT:DWARF:BRAIN PLANT_MAT:MUSHROOM_HELMET_PLUMP:DRINK -command [ commandStrs ] specify the command to be executed commandStrs \\ATTACKER_ID \\DEFENDER_ID \\ITEM_MATERIAL \\ITEM_MATERIAL_TYPE \\ITEM_ID \\ITEM_TYPE \\CONTAMINANT_MATERIAL \\CONTAMINANT_MATERIAL_TYPE \\CONTAMINANT_MATERIAL_INDEX \\MODE \\UNIT_ID \\anything -> \anything anything -> anything
This is a standardized version of Putnam’s moddableGods script. It allows you to create gods on the command-line.
-name godName sets the name of the god to godName if there's already a god of that name, the script halts -spheres [ sphereList ] define a space-separated list of spheres of influence of the god -depictedAs str often depicted as a str -domain str set the domain of the god -description str set the description of the god
This allows you to specify certain custom buildings as outside only, or inside only. If the player attempts to build a building in an inappropriate location, the building will be destroyed.
-clear clears the list of registered buildings -checkEvery n set how often existing buildings are checked for whether they are in the appropriate location to n ticks -type [EITHER, OUTSIDE_ONLY, INSIDE_ONLY] specify what sort of restriction to put on the building -building name specify the id of the building
This triggers dfhack commands when projectiles hit their targets. Usage:
-clear unregister all triggers -material specify a material for projectiles that will trigger the command examples: INORGANIC:IRON CREATURE_MAT:DWARF:BRAIN PLANT_MAT:MUSHROOM_HELMET_PLUMP:DRINK -command [ commandList ] \\LOCATION \\PROJECTILE_ID \\FIRER_ID \\anything -> \anything anything -> anything
Trigger random dfhack commands with specified probabilities. Register a few scripts, then tell it to “go” and it will pick one based on the probability weights you specified.
Events are mutually-exclusive - register a list of scripts along with relative weights, then tell the script to select and run one with the specified probabilities. The weights must be positive integers, but they do NOT have to sum to any particular number.
The outcomes are mutually exclusive: only one will be triggered. If you want multiple independent random events, call the script multiple times.
99% of the time, you won’t need to worry about this, but just in case, you can specify a name of a list of outcomes to prevent interference from other scripts that call this one. That also permits situations where you don’t know until runtime what outcomes you want. For example, you could make a modtools/reaction-trigger that registers the worker as a mayor candidate, then run this script to choose a random mayor from the list of units that did the mayor reaction.
-outcomeListName name specify the name of this list of outcomes to prevent interference if two scripts are registering outcomes at the same time. If none is specified, the default outcome list is selected automatically. -command [ commandStrs ] specify the command to be run if this outcome is selected must be specified unless the -trigger argument is given -weight n the relative probability weight of this outcome n must be a non-negative integer if not specified, n=1 is used by default -trigger selects a random script based on the specified outcomeList (or the default one if none is specified) -preserveList when combined with trigger, preserves the list of outcomes so you don't have to register them again. -withProbability p p is a real number between 0 and 1 inclusive triggers the command immediately with this probability -seed s sets the random seed for debugging purposes (guarantees the same sequence of random numbers will be produced) use -listOutcomes lists the currently registered list of outcomes of the outcomeList along with their probability weights, for debugging purposes -clear unregister everything
-preserveList is something of a beta feature, which should be
avoided by users without a specific reason to use it.
It is highly recommended that you always specify
when you give this command to prevent almost certain interference.
If you want to trigger one of 5 outcomes three times, you might want
this option even without
The list is NOT retained across game save/load, as nobody has yet had a use for this feature. Contact expwnent if you would use it; it’s not that hard but if nobody wants it he won’t bother.
This triggers dfhack commands when reaction products are produced, once per product. Usage:
-clear unregister all reaction hooks -reactionName name specify the name of the reaction -command [ commandStrs ] specify the command to be run on the target(s) special args \\WORKER_ID \\REACTION \\BUILDING_ID \\LOCATION \\INPUT_ITEMS \\OUTPUT_ITEMS \\anything -> \anything anything -> anything
Triggers dfhack commands when custom reactions complete, regardless of whether it produced anything, once per completion. Arguments:
-clear unregister all reaction hooks -reactionName name specify the name of the reaction -syndrome name specify the name of the syndrome to be applied to the targets -allowNonworkerTargets allow other units in the same building to be targetted by either the script or the syndrome -allowMultipleTargets allow multiple targets to the script or syndrome if absent: if running a script, only one target will be used if applying a syndrome, then only one target will be infected -resetPolicy policy the policy in the case that the syndrome is already present policy NewInstance (default) DoNothing ResetDuration AddDuration -command [ commandStrs ] specify the command to be run on the target(s) special args \\WORKER_ID \\TARGET_ID \\BUILDING_ID \\LOCATION \\REACTION_NAME \\anything -> \anything anything -> anything
Prints useful things to the console and a file to help modders
autoSyndrome to modtools/reaction-trigger.
This script is basically an apology for breaking backward compatibility in June 2014, and will be removed eventually.
Sets or modifies a skill of a unit. Args:
|set the skill that we’re talking about|
|are we adding experience/levels or setting them?|
|direct experience, or experience levels?|
|-unit id:||id of the target unit|
|-value amount:||how much to set/add|
Creates flows at the specified location.
-material mat specify the material of the flow, if applicable examples: INORGANIC:IRON CREATURE_MAT:DWARF:BRAIN PLANT_MAT:MUSHROOM_HELMET_PLUMP:DRINK -location [ x y z] the location to spawn the flow -flowType type specify the flow type examples: Miasma Steam Mist MaterialDust MagmaMist Smoke Dragonfire Fire Web MaterialGas MaterialVapor OceanWave SeaFoam -flowSize size specify how big the flow is
Triggers dfhack commands when syndromes are applied to units.
-clear clear all triggers -syndrome name specify the name of a syndrome -command [ commandStrs ] specify the command to be executed after infection args \\SYNDROME_ID \\UNIT_ID \\LOCATION \\anything -> \anything anything -> anything
Transforms a unit into another unit type, possibly permanently. Warning: this will crash arena mode if you view the unit on the same tick that it transforms. If you wait until later, it will be fine.
-clear clear records of normal races -unit id set the target unit -duration ticks how long it should last, or "forever" -setPrevRace make a record of the previous race so that you can change it back with -untransform -keepInventory move items back into inventory after transformation -race raceName -caste casteName -suppressAnnouncement don't show the Unit has transformed into a Blah! event -untransform turn the unit back into what it was before