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.

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.

Argument names are preceded with a dash, and supplying the same argument name multiple times will result in an error.

The -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: 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.

Contents

modtools/add-syndrome ¶

This allows adding and removing syndromes from units.

Arguments:

-syndrome name|id
    the name or id of the syndrome to operate on
    examples:
        "gila monster bite"
        14
-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

modtools/anonymous-script ¶

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"

modtools/change-build-menu ¶

Change the build sidebar menus.

This script provides a flexible and comprehensive system for adding and removing items from the build sidebar menus. You can add or remove workshops/furnaces by text ID, or you can add/remove ANY building via a numeric building ID triplet.

Changes made with this script do not survive a save/load. You will need to redo your changes each time the world loads.

Just to be clear: You CANNOT use this script AT ALL if there is no world loaded!

Usage:

modtools/change-build-menu start|enable:

enable modtools/change-build-menu:

Start the ticker. This needs to be done before any changes will take effect. Note that you can make changes before or after starting the ticker, both options should work equally well.

modtools/change-build-menu stop|disable:

disable modtools/change-build-menu:

Stop the ticker. Does not clear stored changes. The ticker will automatically stop when the current world is unloaded.

modtools/change-build-menu add <ID> <CATEGORY> [<KEY>]:

Add the workshop or furnace with the ID <ID> to <CATEGORY>. <KEY> is an optional DF hotkey ID.

<CATEGORY> may be one of:

MAIN_PAGE

SIEGE_ENGINES

TRAPS

WORKSHOPS

FURNACES

CONSTRUCTIONS

MACHINES

CONSTRUCTIONS_TRACK

Valid <ID> values for hardcoded buildings are as follows:

CARPENTERS

FARMERS

MASONS

CRAFTSDWARFS

JEWELERS

METALSMITHSFORGE

MAGMAFORGE

BOWYERS

MECHANICS

SIEGE

BUTCHERS

LEATHERWORKS

TANNERS

CLOTHIERS

FISHERY

STILL

LOOM

QUERN

KENNELS

ASHERY

KITCHEN

DYERS

TOOL

MILLSTONE

WOOD_FURNACE

SMELTER

GLASS_FURNACE

MAGMA_SMELTER

MAGMA_GLASS_FURNACE

MAGMA_KILN

KILN

modtools/change-build-menu remove <ID> <CATEGORY>:

Remove the workshop or furnace with the ID <ID> from <CATEGORY>.

<CATEGORY> and <ID> may have the same values as for the “add” option.

modtools/change-build-menu revert <ID> <CATEGORY>:

Revert an earlier remove or add operation. It is NOT safe to “remove” an “add”ed building or vice versa, use this option to reverse any changes you no longer want/need.

Module Usage:

To use this script as a module put the following somewhere in your own script:

local buildmenu = reqscript "change-build-menu"

Then you can call the functions documented here like so:

Example: Remove the carpenters workshop:
buildmenu.ChangeBuilding("CARPENTERS", "WORKSHOPS", false)
Example: Make it impossible to build walls (not recommended!):
local typ, styp = df.building_type.Construction, df.construction_type.Wall
buildmenu.ChangeBuildingAdv(typ, styp, -1, "CONSTRUCTIONS", false)

Note that to allow any of your changes to take effect you need to start the ticker. See the “Command Usage” section.

Global Functions:

GetWShopID(btype, bsubtype, bcustom):: GetWShopID returns a workshop’s or furnace’s string ID based on its numeric ID triplet. This string ID should match what is expected by eventful for hardcoded buildings.
GetWShopType(id):: GetWShopIDs returns a workshop or furnace’s ID numbers as a table. The passed in ID should be the building’s string identifier, it makes no difference if it is a custom building or a hardcoded one. The return table is structured like so: {type, subtype, custom}
IsEntityPermitted(id):: IsEntityPermitted returns true if DF would normally allow you to build a workshop or furnace. Use this if you want to change a building, but only if it is permitted in the current entity. You do not need to specify an entity, the current fortress race is used.

ChangeBuilding(id, category, [add, [key]]):

ChangeBuildingAdv(typ, subtyp, custom, category, [add, [key]]):

These two functions apply changes to the build sidebar menus. If “add” is true then the building is added to the specified category, else it is removed. When adding you may specify “key”, a string DF hotkey ID.

The first version of this function takes a workshop or furnace ID as a string, the second takes a numeric ID triplet (which can specify any building, not just workshops or furnaces).

RevertBuildingChanges(id, category):

RevertBuildingChangesAdv(typ, subtyp, custom, category):: These two functions revert changes made by “ChangeBuilding” and “ChangeBuildingAdv”. Like those two functions there are two versions, a simple one that takes a string ID and one that takes a numeric ID triplet.

modtools/create-item ¶

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

Arguments:

-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
-quality qualitystr
    specify the quality level of the item to be created (df.item_quality)
    examples: Ordinary, WellCrafted, FinelyCrafted, Masterful, or 0-5
-matchingShoes
    create two of this item
-matchingGloves
    create two of this item, and set handedness appropriately

modtools/create-tree ¶

Spawns a tree.

Usage:

-tree treeName
    specify the tree to be created
    examples:
        OAK
        NETHER_CAP

-age howOld
    set the age of the tree in years (integers only)
    defaults to 1 if omitted

-location [ x y z ]
    create the tree at the specified coordinates

example:
    modtools/create-tree -tree OAK -age 100 -location [ 33 145 137 ]

modtools/create-unit ¶

Creates a unit. Usage:

-race raceName
    (obligatory)
    Specify the race of the unit to be created.
    examples:
        DWARF
        HUMAN

-caste casteName
    Specify the caste of the unit to be created.
    If omitted, the caste is randomly selected.
    examples:
        MALE
        FEMALE
        DEFAULT

-domesticate
    Tames the unit if it lacks the CAN_LEARN and CAN_SPEAK tokens.

-civId id
    Make the created unit a member of the specified civilisation
    (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

-setUnitToFort
    Sets the groupId and civId to those of the player in Fortress mode.
    Equivalent to -civId \\LOCAL and -groupId \\LOCAL.

-name entityRawName
    Set the unit's name to be a random name appropriate for the
    given entity. \\LOCAL can be specified instead to automatically
    use the fort group entity in fortress mode only.
    examples:
        MOUNTAIN
        EVIL

-nick nickname
    This can be included to nickname the unit.
    Replace "nickname" with the desired name.

-age howOld
    This can be included to specify the unit's age.
    Replace "howOld" with a (non-negative) number.
    The unit's age is set randomly if this is omitted.

-equip [ ITEM:MATERIAL:QUANTITY ... ]
    This can be included to create items and equip them onto
        the created unit.
    This is carried out via the same logic used in arena mode,
        so equipment will always be sized correctly and placed
        on what the game deems to be appropriate bodyparts.
        Clothing is also layered in the appropriate order.
    Note that this currently comes with some limitations,
        such as an inability to specify item quality
        and objects not being placed in containers
        (for example, arrows are not placed in quivers).
    Item quantity defaults to 1 if omitted.
    When spaces are included in the item or material name,
        the entire item description should be enclosed in
        quotation marks. This can also be done to increase
        legibility when specifying multiple items.
    examples:
        -equip [ RING:CREATURE:DWARF:BONE:3 ]
            3 dwarf bone rings
        -equip [ ITEM_WEAPON_PICK:INORGANIC:IRON ]
            1 iron pick
        -equip [ "ITEM_SHIELD_BUCKLER:PLANT:OAK:WOOD" "AMULET:AMBER" ]
            1 oaken buckler and 1 amber amulet

-skills [ SKILL:LEVEL ... ]
    This can be included to add skills to the created unit.
    Specify a skill token followed by a skill level value.
    Look up "Skill Token" and "Skill" on the DF Wiki for a list
        of valid tokens and levels respectively.
    Note that the skill level provided must be a number greater than 0.
    If the unit possesses a matching natural skill, this is added to it.
    Quotation marks can be added for legibility as explained above.
    example:
        -skill [ SNEAK:1 EXTRACT_STRAND:15 ]
            novice ambusher, legendary strand extractor

-profession token
    This can be included to set the unit's profession.
    Replace "token" with a Unit Type Token (check the DF Wiki for a list).
    For skill-based professions, it is recommended to give the unit
        the appropriate skill set via -skills.
    This can also be used to make animals trained for war/hunting.
    Note that this will be overridden if the unit has been given the age
        of a baby or child, as these have a special "profession" set.
    Using this for setting baby/child status is not recommended;
        this should be done via -age instead.
    examples:
        STRAND_EXTRACTOR
        MASTER_SWORDSMAN
        TRAINED_WAR

-customProfession name
    This can be included to give the unit a custom profession name.
    Enclose the name in quotation marks if it includes spaces.
    example:
        -customProfession "Destroyer of Worlds"

-duration ticks
    If this is included, the unit will vanish in a puff of smoke
        once the specified number of ticks has elapsed.
    Replace "ticks" with an integer greater than 0.
    Note that the unit's equipment will not vanish.

-quantity howMany
    This can be included to create multiple creatures simultaneously.
    Replace "howMany" with the desired number of creatures.
    Quantity defaults to 1 if this is omitted.

-location [ x y z ]
    (obligatory)
    Specify the coordinates where you want the unit to appear.

-locationRange [ x_offset y_offset z_offset ]
    If included, the unit will be spawned at a random location
        within the specified range relative to the target -location.
    z_offset defaults to 0 if omitted.
    When creating multiple units, the location is randomised each time.
    example:
        -locationRange [ 4 3 1 ]
            attempts to place the unit anywhere within
            -4 to +4 tiles on the x-axis
            -3 to +3 tiles on the y-axis
            -1 to +1 tiles on the z-axis
            from the specified -location coordinates

-locationType type
    May be used with -locationRange
        to specify what counts as a valid tile for unit spawning.
    Unit creation will not occur if no valid tiles are available.
    Replace "type" with one of the following:
        Walkable
            units will only be placed on walkable ground tiles
            this is the default used if -locationType is omitted
        Open
            open spaces are also valid spawn points
            this is intended for flying units
        Any
            all tiles, including solid walls, are valid
            this is only recommended for ghosts not carrying items

-flagSet [ flag1 flag2 ... ]
    This can be used to set the specified unit flags to true.
    Flags may be selected from:
        df.unit_flags1
        df.unit_flags2
        df.unit_flags3
        df.unit_flags4
    example:
        flagSet [ announce_titan ]
            causes an announcement describing the unit to appear
            when it is discovered ("[Unit] has come! ...")

-flagClear [ flag1 flag2 ... ]
    As above, but sets the specified unit flags to false.

modtools/equip-item ¶

Force a unit to equip an item with a particular body part; useful in conjunction with the create scripts above. See also forceequip.

modtools/extra-gamelog ¶

This script writes extra information to the gamelog. This is useful for tools like Soundsense.

Usage:

modtools/extra-gamelog enable
modtools/extra-gamelog disable

modtools/force ¶

This tool triggers events like megabeasts, caravans, and migrants.

Usage:

-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

modtools/if-entity ¶

Run a command if the current entity matches a given ID.

To use this script effectively it needs to be called from “raw/onload.init”. Calling this from the main dfhack.init file will do nothing, as no world has been loaded yet.

Usage:

id:

Specify the entity ID to match
cmd [ commandStrs ]:

Specify the command to be run if the current entity matches the entity given via -id

All arguments are required.

Example:

Print a message if you load an elf fort, but not a dwarf, human, etc. fort:
```
if-entity -id "FOREST" -cmd [ lua "print('Dirty hippies.')" ]
```

modtools/interaction-trigger ¶

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.

Usage:

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

modtools/invader-item-destroyer ¶

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

Arguments:

-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

modtools/item-trigger ¶

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.

Arguments:

-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 mode
    trigger the command when someone equips an appropriate item
    Optionally, the equipment mode can be specified
    Possible values for mode:
        Hauled
        Weapon
        Worn
        Piercing
        Flask
        WrappedAround
        StuckIn
        InMouth
        Pet
        SewnInto
        Strapped
    multiple values can be specified simultaneously
    example: -onEquip [ Weapon Worn Hauled ]
-onUnequip mode
    trigger the command when someone unequips an appropriate item
    see above note regarding 'mode' values
-material mat
    trigger the commmand on items with the given material
    examples
        INORGANIC:IRON
        CREATURE:DWARF:BRAIN
        PLANT:OAK:WOOD
-contaminant mat
    trigger the command for items with a given material contaminant
    examples
        INORGANIC:GOLD
        CREATURE:HUMAN:BLOOD
        PLANT:MUSHROOM_HELMET_PLUMP:DRINK
        WATER
-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

modtools/moddable-gods ¶

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

Arguments:

-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
-gender male|female|neuter
    sets the gender of the god
-depictedAs str
    often depicted as a str
-verbose
    if specified, prints details about the created god

modtools/outside-only ¶

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.

Arguments:

-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

modtools/pref-edit ¶

Add, remove, or edit the preferences of a unit. Requires a modifier, a unit argument, and filters.

-unit <UNIT ID>:

The given unit will be affected. If not found/provided, the script will try defaulting to the currently selected unit.

Valid modifiers:

-add:

Add a new preference to the unit. Filters describe the preference’s variables.
-remove:

Remove a preference from the unit. Filters describe what preference to remove.
-has:

Checks if the unit has a preference matching the filters. Prints a message in the console.
-removeall:

Remove all preferences from the unit. Doesn’t require any filters.

Valid filters:

-id <VALUE>:

This is the ID used for all preferences that require an ID. Represents item_type, creature_id, color_id, shape_id, plant_id, poetic_form_id, musical_form_id, and dance_form_id. Text IDs (e.g. “TOAD”, “AMBER”) can be used for all but poetic, musical, and dance.
-item, -creature, -color, -shape, -plant, -poetic, -musical, -dance:

Include one of these to describe what the id argument represents.
-type <PREFERENCE TYPE>:

This describes the type of the preference. Can be entered either using the numerical ID or text id. Run lua @df.unit_preference.T_type for a full list of valid values.
-subtype <ID>:

The value for an item’s subtype
-material <ID>:

The id of the material. For example “MUSHROOM_HELMET_PLUMP:DRINK” or “INORGANIC:IRON”.
-state <STATE ID>:

The state of the material. Values can be the numerical or text ID. Run lua @df.matter_state for a full list of valid values.
-active <TRUE/FALSE>:

Whether the preference is active or not (?)

Other arguments:

-help:

Shows this help page.

Example usage:

Like drinking dwarf blood:

modtools/pref-edit -add -item -id DRINK -material DWARF:BLOOD -type LikeFood

modtools/projectile-trigger ¶

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

modtools/random-trigger ¶

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.

Arguments:

-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

Note

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

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.

modtools/raw-lint ¶

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

modtools/reaction-product-trigger ¶

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

modtools/reaction-trigger ¶

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 valid targets
-allowNonworkerTargets
    allow other units to be targeted if the worker is invalid or ignored
-allowMultipleTargets
    allow all valid targets within range to be affected
    if absent:
        if running a script, only one target will be used
        if applying a syndrome, then only one target will be infected
-ignoreWorker
    ignores the worker when selecting the targets
-dontSkipInactive
    when selecting targets in range, include creatures that are inactive
    dead creatures count as inactive
-range [ x y z ]
    controls how far elligible targets can be from the workshop
    defaults to [ 0 0 0 ] (on a workshop tile)
    negative numbers can be used to ignore outer squares of the workshop
    line of sight is not respected, and the worker is always within range
-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
    when used with -syndrome, the target must be valid for the syndrome
    otherwise, the command will not be run for that target

modtools/reaction-trigger-transition ¶

Prints useful things to the console and a file to help modders transition from autoSyndrome to modtools/reaction-trigger.

This script is basically an apology for breaking backward compatibility in June 2014, and will be removed eventually.

modtools/set-belief ¶

Changes the beliefs (values) of units. Requires a belief, modifier, and a target.

Valid beliefs:

all:	Apply the edit to all the target’s beliefs
belief <ID>:	ID of the belief to edit. For example, 0 or LAW.

Valid modifiers:

set <-50-50>:

Set belief to given strength.

tier <1-7>:

Set belief to within the bounds of a strength tier:

Value	Strength
1	Lowest
2	Very Low
3	Low
4	Neutral
5	High
6	Very High
7	Highest

modify <amount>:

Modify current belief strength by given amount. Negative values need a \ before the negative symbol e.g. \-1

step <amount>:

Modify current belief tier up/down by given amount. Negative values need a \ before the negative symbol e.g. \-1

random:

Use the default probabilities to set the belief to a new random value.

default:

Belief will be set to cultural default.

Valid targets:

citizens:	All (sane) citizens of your fort will be affected. Will do nothing in adventure mode.
unit <UNIT ID>:	The given unit will be affected.

If no target is given, the provided unit can’t be found, or no unit id is given with the unit argument, the script will try and default to targeting the currently selected unit.

Other arguments:

help:	Shows this help page.
list:	Prints a list of all beliefs + their IDs.
noneed:	By default, unit’s needs will be recalculated to reflect new beliefs after every run. Use this argument to disable that functionality.
listunit:	Prints a list of all a unit’s beliefs. Cultural defaults are marked with `*`.

modtools/set-need ¶

Sets and edits unit needs.

Valid commands:

add:	Add a new need to the unit. Requires a -need argument, and target. -focus and -level can be used to set starting values, otherwise they’ll fall back to defaults.
remove:	Remove an existing need from the unit. Requires a need target, and target.
edit:	Change an existing need in some way. Requires a need target, at least one effect, and a target.
revert:	Revert a unit’s needs list back to its original selection and need strengths. Focus levels are preserved if the unit has a need before and after. Requires a target.

Valid need targets:

deity <HISTFIG ID>:
need <ID>:	ID of the need to target. For example 0 or DrinkAlcohol. If the need is PrayOrMedidate, a -deity argument is also required.
	Required when using PrayOrMedidate needs. This value should be the historical figure ID of the deity in question.
all:	All of the target’s needs will be affected.

Valid effects:

focus <NUMBER>:	Set the focus level of the targeted need. 400 is the value used when a need has just been satisfied.
level <NUMBER>:	Set the need level of the targeted need. Default game values are: 1 (Slight need), 2 (Moderate need), 5 (Strong need), 10 (Intense need)

Valid targets:

citizens:	All (sane) citizens of your fort will be affected. Will do nothing in adventure mode.
unit <UNIT ID>:	The given unit will be affected.

If no target is given, the provided unit can’t be found, or no unit id is given with the unit argument, the script will try and default to targeting the currently selected unit.

Other arguments:

help:	Shows this help page.
list:	Prints a list of all needs + their IDs.
listunit:	Prints a list of all a unit’s needs, their strengths, and their current focus.

Usage example - Satisfy all citizen’s needs:

modtools/set-need -edit -all -focus 400 -citizens

modtools/set-personality ¶

Changes the personality of units. Requires a trait, modifier, and a target.

Valid traits:

all:	Apply the edit to all the target’s traits
trait <ID>:	ID of the trait to edit. For example, 0 or HATE_PROPENSITY.

Valid modifiers:

set <0-100>:

Set trait to given strength.

tier <1-7>:

Set trait to within the bounds of a strength tier.

Value	Strength
1	Lowest
2	Very Low
3	Low
4	Neutral
5	High
6	Very High
7	Highest

modify <amount>:

Modify current base trait strength by given amount. Negative values need a \ before the negative symbol e.g. \-1

step <amount>:

Modify current trait tier up/down by given amount. Negative values need a \ before the negative symbol e.g. \-1

random:

Set the trait to a new random value.

average:

Sets trait to the creature’s caste’s average value (as defined in the PERSONALITY creature tokens).

Valid targets:

citizens:	All (sane) citizens of your fort will be affected. Will do nothing in adventure mode.
unit <UNIT ID>:	The given unit will be affected.

If no target is given, the provided unit can’t be found, or no unit id is given with the unit argument, the script will try and default to targeting the currently selected unit.

Other arguments:

help:	Shows this help page.
list:	Prints a list of all facets + their IDs.
noneed:	By default, unit’s needs will be recalculated to reflect new traits after every run. Use this argument to disable that functionality.
listunit:	Prints a list of all a unit’s personality traits, with their modified trait value in brackets.

modtools/skill-change ¶

Sets or modifies a skill of a unit. Args:

-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
-loud:	if present, prints changes to console

modtools/spawn-flow ¶

Creates flows at the specified location.

Arguments:

-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

modtools/spawn-liquid ¶

This script spawns liquid at the given coordinates.

Run modtools/spawn-liquid help for usage.

modtools/syndrome-trigger ¶

Triggers dfhack commands when syndromes are applied to units.

Arguments:

-clear
    clear any previously registered syndrome triggers

-syndrome SYN_NAME
    specify a syndrome by its SYN_NAME
    enclose the name in quotation marks if it includes spaces
    example:
        -syndrome "gila monster bite"

-synclass SYN_CLASS
    any syndrome with the specified SYN_CLASS will act as a trigger
    enclose in quotation marks if it includes spaces
    example:
        -synclass VAMPCURSE

-command [ commandStrs ]
    specify the command to be executed after infection
    remember to include a space after/before the square brackets!
    the following may be added to appropriate commands where relevant:
        \\UNIT_ID
            inserts the ID of the infected unit
        \\LOCATION
            inserts the x, y, z coordinates of the infected unit
        \\SYNDROME_ID
            inserts the ID of the syndrome
    note that:
        \\anything -> \anything
        anything -> anything
    examples:
        -command [ full-heal -unit \\UNIT_ID ]
            heals units when they acquire the specified syndrome
        -command [ modtools/spawn-flow -flowType Dragonfire -location [ \\LOCATION ] ]
            spawns dragonfire at the location of infected units

modtools/transform-unit ¶

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.

Arguments:

-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

Home

Related Topics

Table of Contents

Scripts for Modders¶

modtools/add-syndrome ¶

modtools/anonymous-script ¶

modtools/change-build-menu ¶

modtools/create-item ¶

modtools/create-tree ¶

modtools/create-unit ¶

modtools/equip-item ¶

modtools/extra-gamelog ¶

modtools/force ¶

modtools/if-entity ¶

modtools/interaction-trigger ¶

modtools/invader-item-destroyer ¶

modtools/item-trigger ¶

modtools/moddable-gods ¶

modtools/outside-only ¶

modtools/pref-edit ¶

modtools/projectile-trigger ¶

modtools/random-trigger ¶

modtools/raw-lint ¶

modtools/reaction-product-trigger ¶

modtools/reaction-trigger ¶

modtools/reaction-trigger-transition ¶

modtools/set-belief ¶

modtools/set-need ¶

modtools/set-personality ¶

modtools/skill-change ¶

modtools/spawn-flow ¶

modtools/spawn-liquid ¶

modtools/syndrome-trigger ¶

modtools/transform-unit ¶