Scripts for Modders

modtools/* scripts provide tools for modders, often with changes to the raw files, and are not intended to be called manually by end-users.

These scripts are mostly useful for raw modders and scripters. 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: tool -argName3 is fine. Supplying the same argument name multiple times will result in an error. Argument names are preceded with a dash. The -help argument will print a descriptive usage string describing the nature of the arguments. For multiple word argument values, brackets must be used: tool -argName4 [ sadf1 sadf2 sadf3 ]. In order to allow passing literal braces as part of the argument, backslashes are used: tool -argName4 [ \] asdf \foo ] sets argName4 to \] asdf foo. The *-trigger scripts have a similar policy with backslashes.

Any of these scripts can be called with -help for more information.


This allows adding and removing syndromes from units.


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[1])" arg1 arg2
# prints "arg1"


Replaces the createitem plugin, with standard arguments. The other versions will be phased out in a later version.


Creates a unit. Use modtools/create-unit -help for more info.


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.


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.


This tool configurably destroys invader items to prevent clutter or to prevent the player from getting tools exclusive to certain races.


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.


This is a standardized version of Putnam’s moddableGods script. It allows you to create gods on the command-line.


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.


This triggers dfhack commands when projectiles hit their targets.


This triggers 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. Outcomes are mutually exclusive. To make independent random events, call the script multiple times.


Checks for simple issues with raw files. Can be run automatically.


This triggers dfhack commands when reaction products are produced, once per product.


Triggers dfhack commands when custom reactions complete, regardless of whether it produced anything, once per completion. Use the -help command for more information.


Scans raw files and creates a file to help modders transition from autoSyndrome to reaction-trigger.

Prints useful things to the console and a file to help modders transition from autoSyndrome to reaction-trigger. This script is basically an apology for breaking backward compatibiility, and will be removed eventually.


Sets or modifies a skill of a unit. Args:

-help:print the help message
-skill skillName:
 set the skill that we’re talking about
-mode (add/set):
 are we adding experience/levels or setting them?
-granularity (experience/level):
 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.


Triggers dfhack commands when syndromes are applied to units.


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.