# 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

- 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

## modtools/add-syndrome

This allows adding and removing syndromes from units.

Arguments:

    -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

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

    -setUnitToFort
        Sets the groupId and civId to the local fort
        Can be used instead of -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
        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 unit by current age
        chosen randomly if not specified

    -quantity howMany
        replace "howMany" with the number of creatures you want to create
        defaults to 1 if not specified

    -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

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

## 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
    -depictedAs str
        often depicted as a str
    -domain str
        set the domain of the god
    -description str
        set the description of the 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:

need <ID>: | ID of the need to target. For example 0 or DrinkAlcohol. If the need is PrayOrMedidate, a -deity argument is also required.
deity <HISTFIG ID>:
| 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