# Basic Scripts

Basic scripts are not stored in any subdirectory, and can be invoked directly. They are generally useful tools for any player.

Contents

- Basic Scripts
  - adaptation
  - add-recipe
  - add-thought
  - adv-fix-sleepers
  - adv-max-skills
  - adv-rumors
  - armoks-blessing
  - assign-attributes
  - assign-beliefs
  - assign-facets
  - assign-goals
  - assign-preferences
  - assign-profile
  - assign-skills
  - autolabor-artisans
  - autounsuspend
  - ban-cooking
  - binpatch
  - bodyswap
  - brainwash
  - break-dance
  - burial
  - cannibalism
  - caravan
  - catsplosion
  - clear-smoke
  - colonies
  - combat-harden
  - combine-drinks
  - combine-plants
  - create-items
  - deathcause
  - deep-embark
  - deteriorateclothes
  - deterioratecorpses
  - deterioratefood
  - digfort
  - dorf_tables
  - drain-aquifer
  - dwarf-op
  - elevate-mental
  - elevate-physical
  - embark-skills
  - emigration
  - empty-bin
  - exportlegends
  - exterminate
  - extinguish
  - feature
  - fillneeds
  - firestarter
  - fix-ster
  - fixnaked
  - flashstep
  - force
  - forget-dead-body
  - forum-dwarves
  - full-heal
  - gaydar
  - ghostly
  - growcrops
  - hermit
  - hfs-pit
  - hotkey-notes
  - install-info
  - item-descriptions
  - launch
  - lever
  - linger
  - load-save
  - locate-ore
  - lua
  - make-legendary
  - make-monarch
  - markdown
  - masspit
  - migrants-now
  - multicmd
  - names
  - open-legends
  - points
  - position
  - pref-adjust
  - prefchange
  - putontable
  - questport
  - quicksave
  - region-pops
  - rejuvenate
  - remove-stress
  - remove-wear
  - repeat
  - season-palette
  - set-orientation
  - setfps
  - show-unit-syndromes
  - siren
  - source
  - spawnunit
  - startdwarf
  - starvingdead
  - stripcaged
  - superdwarf
  - tame
  - teleport
  - tidlers
  - troubleshoot-item
  - twaterlvl
  - undump-buildings
  - unforbid
  - unretire-anyone
  - unsuspend
  - view-item-info
  - view-unit-reports
  - warn-starving
  - weather

## adaptation

View or set level of cavern adaptation for the selected unit or the whole fort. Usage: `adaptation <show|set> <him|all> [value]`. The `value` must be between 0 and 800,000 inclusive.

## add-recipe

Adds unknown weapon and armor crafting recipes to your civ. E.g. some civilizations never learn to craft high boots. This script can help with that, and more. Only weapons and armor are currently supported; things such as instruments are not. Available options:

- `add-recipe all` adds all available weapons and armor, including exotic items like blowguns, two-handed swords, and capes.
- `add-recipe native` adds only native (but unknown) crafting recipes. Civilizations pick randomly from a pool of possible recipes, which means not all civs get high boots, for instance. This command gives you all the recipes your civilisation could have gotten.
- `add-recipe single <item token>` adds a single item by the given item token. For example, `add-recipe single SHOES:ITEM_SHOES_BOOTS`.

## add-thought

Adds a thought or emotion to the selected unit. Can be used by other scripts, or the gui invoked by running `add-thought gui` with a unit selected.

## adv-fix-sleepers

Fixes Bug 6798. This bug is characterized by sleeping units who refuse to
  awaken in adventure mode regardless of talking to them, hitting them, or waiting so long you die of thirst.
Usage: If you come accross one or more bugged sleepers in adventure mode,
  simply run the script (type adv-fix-sleepers into the dfhack console), and all nearby sleepers will be cured.

## adv-max-skills

When creating an adventurer, raises all changeable skills and attributes to their maximum level.

## adv-rumors

Improves the “Bring up specific incident or rumor” menu in Adventure mode.

- Moves entries into one line
- Adds a “slew” keyword for filtering, making it easy to find your kills and not your companions’
- Trims repetitive words

Keybinding: Ctrl A in `dungeonmode/ConversationSpeak`

## armoks-blessing

Runs the equivalent of rejuvenate, elevate-physical, elevate-mental, and brainwash on all dwarves currently on the map. This is an extreme change, which sets every stat and trait to an ideal easy-to-satisfy preference.

Without providing arguments, only attributes, age, and personalities will be adjusted. Adding arguments allows for skills or classes to be adjusted to legendary (maximum).

Arguments:

- `list`

    Prints list of all skills

- `classes`

    Prints list of all classes

- `all`

    Set all skills, for all Dwarves, to legendary

- `<skill name>`

    Set a specific skill, for all Dwarves, to legendary

    example: `armoks-blessing RANGED_COMBAT`

    All Dwarves become a Legendary Archer

- `<class name>`

    Set a specific class (group of skills), for all Dwarves, to legendary

    example: `armoks-blessing Medical`

    All Dwarves will have all medical related skills set to legendary

## assign-attributes

A script to change the physical and mental attributes of a unit.

Attributes are divided into tiers from -4 to 4. Tier 0 is the standard level and represents the average values for that attribute, tier 4 is the maximum level, and tier -4 is the minimum level.

An example of the attribute “Strength”:

Tier | Description
--- | ---
4 | unbelievably strong
3 | mighty
2 | very strong
1 | strong
0 | (no description)
-1 | weak
-2 | very weak
-3 | unquestionably weak
-4 | unfathomably weak

For more information: https://dwarffortresswiki.org/index.php/DF2014:Attribute

Usage:

`-help`:
  print the help page.
`-unit <UNIT_ID>`:
  the target unit ID. If not present, the currently selected unit will be the target.
`-attributes [ <ATTRIBUTE> <TIER> <ATTRIBUTE> <TIER> <...> ]`:
  the list of the attributes to modify and their tiers. The valid attribute names can be found in the wiki: https://dwarffortresswiki.org/index.php/DF2014:Attribute (substitute any space with underscores); tiers range from -4 to 4. There must be a space before and after each square bracket.
`-reset`:
  reset all attributes to the average level (tier 0). If both this option and a list of attributes/tiers are present, the unit attributes will be reset and then the listed attributes will be modified.

Example:

`assign-attributes -reset -attributes [ STRENGTH 2 AGILITY -1 SPATIAL_SENSE -1 ]`

  This will reset all attributes to a neutral value and will set the following values (if the currently selected unit is a dwarf):

  > - Strength: a random value between 1750 and 1999 (tier 2);
  > - Agility: a random value between 401 and 650 (tier -1);
  > - Spatial sense: a random value between 1043 and 1292 (tier -1).

  The final result will be: `She is very strong, but she is clumsy. She has a questionable spatial sense.`

## assign-beliefs

A script to change the beliefs (values) of a unit.

Beliefs are defined with the belief token and a number from -3 to 3, which describes the different levels of belief strength, as explained here: https://dwarffortresswiki.org/index.php/DF2014:Personality_trait#Beliefs

Strength | Effect
--- | ---
3 | Highest
2 | Very High
1 | High
0 | Neutral
-1 | Low
-2 | Very Low
-3 | Lowest

Resetting a belief means setting it to a level that does not trigger a report in the “Thoughts and preferences” screen.

Usage:

`-help`:
  print the help page.
`-unit <UNIT_ID>`:
  set the target unit ID. If not present, the currently selected unit will be the target.
`-beliefs [ <BELIEF> <LEVEL> <BELIEF> <LEVEL> <...> ]`:
  the beliefs to modify and their levels. The valid belief tokens can be found in the wiki page linked above; level values range from -3 to 3. There must be a space before and after each square bracket.
`-reset`:
  reset all beliefs to a neutral level. If the script is called with both this option and a list of beliefs/levels, first all the unit beliefs will be reset and then those beliefs listed after `-beliefs` will be modified.

Example:

`assign-beliefs -reset -beliefs [ TRADITION 2 CRAFTSMANSHIP 3 POWER 0 CUNNING -1 ]`

  Resets all the unit beliefs, then sets the listed beliefs to the following values:

  - Tradition: a random value between 26 and 40 (level 2);
  - Craftsmanship: a random value between 41 and 50 (level 3);
  - Power: a random value between -10 and 10 (level 0);
  - Cunning: a random value between -25 and -11 (level -1).

  The final result (for a dwarf) will be: `She personally is a firm believer in the value of tradition and sees guile and cunning as indirect and somewhat worthless.`

Note that the beliefs aligned with the cultural values of the unit have not triggered a report.

## assign-facets

A script to change the facets (traits) of a unit.

Facets are defined with a token and a number from -3 to 3, which describes the different levels of facets strength, as explained here: https://dwarffortresswiki.org/index.php/DF2014:Personality_trait#Facets

Strength | Effect
--- | ---
3 | Highest
2 | Very High
1 | High
0 | Neutral
-1 | Low
-2 | Very Low
-3 | Lowest

Resetting a facet means setting it to a level that does not trigger a report in the “Thoughts and preferences” screen.

Usage:

`-help`:
  print the help page.
`-unit <UNIT_ID>`:
  set the target unit ID. If not present, the currently selected unit will be the target.
`-beliefs [ <FACET> <LEVEL> <FACET> <LEVEL> <...> ]`:
  the facets to modify and their levels. The valid facet tokens can be found in the wiki page linked above; level values range from -3 to 3. There must be a space before and after each square bracket.
`-reset`:
  reset all facets to a neutral level. If the script is called with both this option and a list of facets/levels, first all the unit facets will be reset and then those facets listed after `-facets` will be modified.

Example:

`assign-facets -reset -facets [ HATE_PROPENSITY -2 CHEER_PROPENSITY -1 ]`

  Resets all the unit facets, then sets the listed facets to the following values:

  - Hate propensity: a value between 10 and 24 (level -2);
  - Cheer propensity: a value between 25 and 39 (level -1).

  The final result (for a dwarf) will be: `She very rarely develops negative feelings toward things. She is rarely happy or enthusiastic, and she is conflicted by this as she values parties and merrymaking in the abstract.`

  Note that the facets are compared to the beliefs, and if conflicts arise they will be reported.

## assign-goals

A script to change the goals (dreams) of a unit.

Goals are defined with the goal token and a true/false value that describes whether or not the goal has been accomplished. Be advised that this last feature has not been properly tested and might be potentially destructive: I suggest leaving it at false.

For a list of possible goals: https://dwarffortresswiki.org/index.php/DF2014:Personality_trait#Goals

Bear in mind that nothing will stop you from assigning zero or more than one goal, but it’s not clear how it will affect the game.

Usage:

`-help`:
  print the help page.
`-unit <UNIT_ID>`:
  set the target unit ID. If not present, the currently selected unit will be the target.
`-goals [ <GOAL> <REALIZED_FLAG> <GOAL> <REALIZED_FLAG> <...> ]`:
  the goals to modify/add and whether they have been realized or not. The valid goal tokens can be found in the wiki page linked above. The flag must be a true/false value. There must be a space before and after each square bracket.
`-reset`:
  clear all goals. If the script is called with both this option and a list of goals, first all the unit goals will be erased and then those goals listed after `-goals` will be added.

Example:

`assign-goals -reset -goals [ MASTER_A_SKILL false ]`
  Clears all the unit goals, then sets the “master a skill” goal. The final result will be: `dreams of mastering a skill.`

## assign-preferences

A script to change the preferences of a unit.

Preferences are classified into 12 types. The first 9 are:

- like material;
- like creature;
- like food;
- hate creature;
- like item;
- like plant;
- like tree;
- like colour;
- like shape.

These can be changed using this script.

The remaining three are not currently managed by this script, and are: like poetic form, like musical form, like dance form.

To produce the correct description in the “thoughts and preferences” page, you must specify the particular type of preference. For each type, a description is provided in the section below.

You will need to know the token of the object you want your dwarf to like. Unless told otherwise, the best way to get those tokens is to activate the plugin Stonesense, load a world and let the plugin generate a file named “MatList.csv” in the root DF folder. Browse this file (import it as a .csv file with Excel or similar program) to get the desired token (in the “id” column). Otherwise, in the folder “/raw/objects/” under the main DF directory you will find all the raws defined in the game.

For more information: https://dwarffortresswiki.org/index.php/DF2014:Preferences

Usage:

`-help`:
  print the help page.
`-unit <UNIT_ID>`:
  set the target unit ID. If not present, the currently selected unit will be the target.
`-likematerial [ <TOKEN> <TOKEN> <...> ]`:
  usually a type of stone, a type of metal and a type of gem, plus it can also be a type of wood, a type of glass, a type of leather, a type of horn, a type of pearl, a type of ivory, a decoration material - coral or amber, a type of bone, a type of shell, a type of silk, a type of yarn, or a type of plant cloth. Write the tokens as found in the “id” column of the file “MatList.csv”, generated as explained above. There must be a space before and after each square bracket.
`-likecreature [ <TOKEN> <TOKEN> <...> ]`:
  one or more creatures liked by the unit. You can just list the species: if you are using the file “MatList.csv” as explained above, the creature token will be something similar to `CREATURE:SPARROW:SKIN`, so the name of the species will be `SPARROW`. Nothing will stop you to write the full token, if you want: the script will just ignore the first and the last parts. There must be a space before and after each square bracket.
`-likefood [ <TOKEN> <TOKEN> <...> ]`:
  usually a type of alcohol, plus it can be a type of meat, a type of fish, a type of cheese, a type of edible plant, a cookable plant/creature extract, a cookable mill powder, a cookable plant seed or a cookable plant leaf. Write the tokens as found in the “id” column of the file “MatList.csv”, generated as explained above. There must be a space before and after each square bracket.
`-hatecreature [ <TOKEN> <TOKEN> <...> ]`:
  works the same way as `-likecreature`, but this time it’s one or more creatures that the unit detests. They should be a type of `HATEABLE` vermin which isn’t already explicitly liked, but no check is performed about this. Like before, you can just list the creature species. There must be a space before and after each square bracket.
`-likeitem [ <TOKEN> <TOKEN> <...> ]`:
  a kind of weapon, a kind of ammo, a kind of piece of armor, a piece of clothing (including backpacks or quivers), a type of furniture (doors, floodgates, beds, chairs, windows, cages, barrels, tables, coffins, statues, boxes, armor stands, weapon racks, cabinets, bins, hatch covers, grates, querns, millstones, traction benches, or slabs), a kind of craft (figurines, amulets, scepters, crowns, rings, earrings, bracelets, or large gems), or a kind of miscellaneous item (catapult parts, ballista parts, a type of siege ammo, a trap component, coins, anvils, totems, chains, flasks, goblets, buckets, animal traps, an instrument, a toy, splints, crutches, or a tool). The item tokens can be found here: https://dwarffortresswiki.org/index.php/DF2014:Item_token If you want to specify an item subtype, look into the files listed under the column “Subtype” of the wiki page (they are in the “/raw/ojects/” folder), then specify the items using the full tokens found in those files (see examples below). There must be a space before and after each square bracket.
`-likeplant [ <TOKEN> <TOKEN> <...> ]`:
  works in a similar way as `-likecreature`, this time with plants. You can just List the plant species (the middle part of the token as listed in “MatList.csv”). There must be a space before and after each square bracket.
`-liketree [ <TOKEN> <TOKEN> <...> ]`:
  works exactly as `-likeplant`. I think this preference type is here for backward compatibility (?). You can still use it, however. As before, you can just list the tree (plant) species. There must be a space before and after each square bracket.
`-likecolor [ <TOKEN> <TOKEN> <...> ]`:
  you can find the color tokens here: https://dwarffortresswiki.org/index.php/DF2014:Color#Color_tokens or inside the “descriptor_color_standard.txt” file (in the “/raw/ojects/” folder). You can use the full token or just the color name. There must be a space before and after each square bracket.
`-likeshape [ <TOKEN> <TOKEN> <...> ]`:
  I couldn’t find a list of shape tokens in the wiki, but you can find them inside the “descriptor_shape_standard.txt” file (in the “/raw/ojects/” folder). You can use the full token or just the shape name. There must be a space before and after each square bracket.
`-reset`:
  clear all preferences. If the script is called with both this option and one or more preferences, first all the unit preferences will be cleared and then the listed preferences will be added.

Examples:

`assign-preferences -reset -likematerial [ INORGANIC:OBSIDAN PLANT:WILLOW:WOOD ]`
  “likes alabaster and willow wood”
`assign-preferences -reset -likecreature SPARROW`
  “likes sparrows for their …”
`assign-preferences -reset -likefood [ PLANT:MUSHROOM_HELMET_PLUMP:DRINK PLANT:OLIVE:FRUIT ]`
  “prefers to consume dwarven wine and olives”
`assign-preferences -reset -hatecreature SPIDER_JUMPING`
  “absolutely detests jumping spiders
`assign-preferences -reset -likeitem [ WOOD ITEM_WEAPON:ITEM_WEAPON_AXE_BATTLE ]`
  “likes logs and battle axes”
`assign-preferences -reset -likeplant BERRIES_STRAW`
  “likes straberry plants for their …”
`assign-preferences -reset -liketree OAK`
  “likes oaks for their …”
`assign-preferences -reset -likecolor AQUA`
  “likes the color aqua”
`assign-preferences -reset -likeshape STAR`
  “likes stars”

## assign-profile

A script to change the characteristics of a unit according to a profile loaded from a json file.

A profile can describe which attributes, skills, preferences, beliefs, goals and facets a unit must have. The script relies on the presence of the other `assign-...` modules in this collection: please refer to the other modules documentation for more specific information.

For information about the json schema, please see the the “/hack/scripts/dwarf_profiles.json” file.

Usage:

`-help`:
  print the help page.
`-unit <UNIT_ID>`:
  the target unit ID. If not present, the target will be the currently selected unit.
`-file <filename>`:
  the json file containing the profile to apply. It’s a relative path, starting from the DF root directory and ending at the json file. It must begin with a slash. Default value: “/hack/scripts/dwarf_profiles.json”.
`-profile <profile>`:
  the profile to apply. It’s the name of the profile as stated in the json file.
`-reset <list of characteristics>`:
  the characteristics to be reset/cleared. If not present, it will not clear or reset any characteristic. If it’s a valid list of characteristic, those characteristics will be reset, and then, if present in the profile, the new values will be applied. If set to `PROFILE`, it will reset only the characteristics changed in the profile (and then the new values will be applied). If set to `ALL`, it will reset EVERY characteristic. Possible values: `ALL`, `PROFILE`, `ATTRIBUTES`, `SKILLS`, `PREFERENCES`, `BELIEFS`, `GOALS`, `FACETS`.

Examples:

`assign-profile -reset ALL`
  Resets/clears all the characteristics of the unit, leaving behind a very bland character.
`assign-profile -profile CARPENTER -reset PROFILE`
  Loads and applies the profile called “CARPENTER” in the default json file, resetting/clearing all the characteristics listed in the profile, and then applying the new values.
`assign-profile -file /hack/scripts/military_profiles.json -profile ARCHER -reset ATTRIBUTES`
  Loads and applies the profile called “ARCHER” in the provided json file, keeping all the old characteristics but the attributes, which will be reset (and then, if the profile provides some attributes values, those value will be applied).

## assign-skills

A script to change the skills of a unit.

Skills are defined by their token and their rank. Skills tokens can be found here: https://dwarffortresswiki.org/index.php/DF2014:Skill_token

Below you can find a list of the first 16 ranks:

Rank | Skill name
--- | ---
0 | Dabbling
1 | Novice
2 | Adequate
3 | Competent
4 | Skilled
5 | Proficient
6 | Talented
7 | Adept
8 | Expert
9 | Professional
10 | Accomplished
11 | Great
12 | Master
13 | High Master
14 | Grand Master
15+ | Legendary

For more information: https://dwarffortresswiki.org/index.php/DF2014:Skill#Skill_level_names

Usage:

`-help`:
  print the help page.
`-unit <UNIT_ID>`:
  the target unit ID. If not present, the currently selected unit will be the target.
`-skills [ <SKILL> <RANK> <SKILL> <RANK> <...> ]`:
  the list of the skills to modify and their ranks. Rank values range from -1 (the skill is not learned) to normally 20 (legendary + 5). It is actually possible to go beyond 20, no check is performed. There must be a space before and after each square bracket.
`-reset`:
  clear all skills. If the script is called with both this option and a list of skills/ranks, first all the unit skills will be cleared and then the listed skills will be added.

Example:

`assign-skills -reset -skills [ WOODCUTTING 3 AXE 2 ]`
  Clears all the unit skills, then adds the Wood cutter skill (competent level) and the Axeman skill (adequate level).

## autolabor-artisans

Runs an autolabor command, for all labors where skill level influences output quality. Examples:

    autolabor-artisans 0 2 3
    autolabor-artisans disable

## autounsuspend

Automatically unsuspend construction jobs, on a recurring basis.

Will not unsuspend jobs where water flow > 1.

See unsuspend for one-off use, or resume `all`.

## ban-cooking

A more convenient way to ban cooking various categories of foods than the kitchen interface. Usage: `ban-cooking <type>`. Valid types are `booze`, `honey`, `tallow`, `oil`, `seeds` (non-tree plants with seeds), `brew`, `fruit`, `mill`, `thread`, and `milk`.

## binpatch

Implements functions for in-memory binpatches. See Patching the DF binary.

## bodyswap

This script allows the player to take direct control of any unit present in adventure mode whilst giving up control of their current player character.

To specify the target unit, simply select it in the user interface, such as by opening the unit’s status screen or viewing its description, and enter “bodyswap” in the DFHack console.

Alternatively, the target unit can be specified by its unit id as shown below.

Arguments:

    -unit id
        replace "id" with the unit id of your target
        example:
            bodyswap -unit 42

## brainwash

Modify the personality traits of the selected dwarf to match an idealised personality - for example, as stable and reliable as possible to prevent tantrums even after months of misery.

Usage: `brainwash <type>`, with one of the following types:

ideal: | reliable, with generally positive personality traits
baseline: | reset all personality traits to the average
stepford: | amplifies all good qualities to an excessive degree
wrecked: | amplifies all bad qualities to an excessive degree

## break-dance

Breaks up dances, such as broken or otherwise hung dances that occur when a unit can’t find a partner.

## burial

Sets all unowned coffins to allow burial. `burial -pets` also allows burial of pets.

## cannibalism

Allows consumption of sapient corpses. Use from an adventurer’s inventory screen or an individual item’s detail screen.

## caravan

Adjusts properties of caravans on the map. See also force to create caravans.

This script has multiple subcommands. Commands listed with the argument `[IDS]` can take multiple caravan IDs (see `caravan list`). If no IDs are specified, then the commands apply to all caravans on the map.

Subcommands:

- `list`: lists IDs and information about all caravans on the map.
- `extend [DAYS] [IDS]`: extends the time that caravans stay at the depot by the specified number of days (defaults to 7 if not specified). Also causes caravans to return to the depot if applicable.
- `happy [IDS]`: makes caravans willing to trade again (after seizing goods, annoying merchants, etc.). Also causes caravans to return to the depot if applicable.
- `leave [IDS]`: makes caravans pack up and leave immediately.

## catsplosion

Makes cats (and other animals) just multiply. It is not a good idea to run this more than once or twice.

Usage:

catsplosion: | Make all cats pregnant
catsplosion list:
| List IDs of all animals on the map
catsplosion ID …:
| Make animals with given ID(s) pregnant

Animals will give birth within two in-game hours (100 ticks or fewer).

## clear-smoke

Removes all smoke from the map. Note that this can leak memory and should be used sparingly.

## colonies

List vermin colonies, place honey bees, or convert all vermin to honey bees. Usage:

colonies: | List all vermin colonies on the map.
colonies place: | Place a honey bee colony under the cursor.
colonies convert:
| Convert all existing colonies to honey bees.

The `place` and `convert` subcommands by default create or convert to honey bees, as this is the most commonly useful. However both accept an optional flag to use a different vermin type, for example `colonies place ANT` creates an ant colony and `colonies convert TERMITE` ends your beekeeping industry.

## combat-harden

Sets the combat-hardened value on a unit, making them care more/less about seeing corpses. Requires a value and a target.

Valid values:

`-value <0-100>`: | A percent value to set combat hardened to.
`-tier <1-4>`: | Choose a tier of hardenedness to set it to. 1 = No hardendness. 2 = “is getting used to tragedy” 3 = “is a hardened individual” 4 = “doesn’t really care about anything anymore” (max)

If neither are provided, the script defaults to using a value of 100.

Valid targets:

`-all`: | All active units will be affected.
`-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.

## combine-drinks

Merge stacks of drinks in the selected stockpile.

## combine-plants

Merge stacks of plants or plant growths in the selected container or stockpile.

## create-items

Spawn items under the cursor, to get your fortress started.

The first argument gives the item category, the second gives the material, and the optionnal third gives the number of items to create (defaults to 20).

Currently supported item categories: `boulder`, `bar`, `plant`, `log`, `web`.

Instead of material, using `list` makes the script list eligible materials.

The `web` item category will create an uncollected cobweb on the floor.

Note that the script does not enforce anything, and will let you create boulders of toad blood and stuff like that. However the `list` mode will only show ‘normal’ materials.

Examples:

    create-items boulders COAL_BITUMINOUS 12
    create-items plant tail_pig
    create-items log list
    create-items web CREATURE:SPIDER_CAVE_GIANT:SILK
    create-items bar CREATURE:CAT:SOAP
    create-items bar adamantine

## deathcause

Select a body part ingame, or a unit from the `u` unit list, and this script will display the cause of death of the creature.

## deep-embark

Moves the starting units and equipment to a specific underground region upon embarking.

To use, create a file called “onMapLoad.init” in the DF raw folder and enter within it the name of this script followed by any of the args listed below.

example:
  deep-embark -depth CAVERN_2

Usage:

    -depth X
        (obligatory)
        replace "X" with one of the following:
            CAVERN_1
            CAVERN_2
            CAVERN_3
            UNDERWORLD

    -atReclaim
        including this arg will enable deep embarking
        when reclaiming sites too

    -blockDemons
        including this arg will prevent demon surges
        in the context of breached underworld spires
        (intended mainly for UNDERWORLD embarks)
        ("wildlife" demon spawning will be unaffected)

## deteriorateclothes

Somewhere between a “mod” and a “fps booster”, with a small impact on vanilla gameplay. All of those slightly worn wool shoes that dwarves scatter all over the place will deteriorate at a greatly increased rate, and eventually just crumble into nothing. As warm and fuzzy as a dining room full of used socks makes your dwarves feel, your FPS does not like it.

Usage: `deteriorateclothes (start|stop)`

## deterioratecorpses

Somewhere between a “mod” and a “fps booster”, with a small impact on vanilla gameplay.

In long running forts, especially evil biomes, you end up with a lot of toes, teeth, fingers, and limbs scattered all over the place. Various corpses from various sieges, stray kitten corpses, probably some heads. Basically, your map will look like a giant pile of assorted body parts, all of which individually eat up a small part of your FPS, which collectively eat up quite a bit.

In addition, this script also targets various butchery byproducts. Enjoying your thriving animal industry? Your FPS does not. Those thousands of skulls, bones, hooves, and wool eat up precious FPS that could be used to kill goblins and elves. Whose corpses will also get destroyed by the script to kill more goblins and elves.

This script causes all of those to rot away into nothing after several months.

Usage: `deterioratecorpses (start|stop)`

## deterioratefood

Somewhere between a “mod” and a “fps booster”, with a small impact on vanilla gameplay.

With this script running, all food and plants wear out and disappear after several months. Barrels and stockpiles will keep them from rotting, but it won’t keep them from decaying. No more sitting on a hundred years worth of food. No more keeping barrels of pig tails sitting around until you decide to use them. Either use it, eat it, or lose it. Seeds, are excluded from this, if you aren’t planning on using your pig tails, hold onto the seeds for a rainy day.

This script is…pretty far reaching. However, almost all long running forts I’ve had end up sitting on thousands and thousands of food items. Several thousand cooked meals, three thousand plump helmets, just as many fish and meat. It gets pretty absurd. And your FPS doesn’t like it.

Usage: `deterioratefood (start|stop)`

## digfort

A script to designate an area for digging according to a plan in csv format.

This script, inspired from quickfort, can designate an area for digging. Your plan should be stored in a .csv file like this:

    # this is a comment
    d;d;u;d;d;skip this tile;d
    d;d;d;i

Available tile shapes are named after the ‘dig’ menu shortcuts: `d` for dig, `u` for upstairs, `j` downstairs, `i` updown, `h` channel, `r` upward ramp, `x` remove designation. Unrecognized characters are ignored (eg the ‘skip this tile’ in the sample).

Empty lines and data after a `#` are ignored as comments. To skip a row in your design, use a single `;`.

One comment in the file may contain the phrase `start(3,5)`. It is interpreted as an offset for the pattern: instead of starting at the cursor, it will start 3 tiles left and 5 tiles up from the cursor.

additionally a comment can have a < for a rise in z level and a > for drop in z.

The script takes the plan filename, starting from the root df folder (where `Dwarf Fortress.exe` is found).

## dorf_tables

Data tables for pimp-it.lua.

Usage: load inside secondary script (pimp-it.lua)

## drain-aquifer

Remove all ‘aquifer’ tags from the map blocks. Irreversible.

## dwarf-op

Optimize dwarves for fort-mode work. The core function takes dwarves and allocates a “job” to each dwarf. This decision takes into account current counts for each job, in relation to how many should be allocated based on the working population size. Jobs involve required professions, tertiary professions (may or may not be applied), and types which come along with attribute buffs and characteristics (eg. strength, speed, focus, dodging, etc)

Usage: `dwarf-op -help` or `dwarf-op -select <sel-opt> -<command> <args>`

help: | Highly detailed help documentation.
select <option>:
| Indicates the next parameter will be indicate which dwarves to select

## elevate-mental

Set all mental attributes of the selected dwarf to the maximum possible, or any number numbers between 0 and 5000 passed as an argument: `elevate-mental 100` for example would make the dwarf very stupid indeed.

## elevate-physical

Set all physical attributes of the selected dwarf to the maximum possible, or any number numbers between 0 and 5000 passed as an argument. Higher is usually better, but an ineffective hammerer can be useful too…

## embark-skills

Adjusts dwarves’ skills when embarking.

Note that already-used skill points are not taken into account or reset.

points N: | Sets the skill points remaining of the selected dwarf to `N`.
points N all: | Sets the skill points remaining of all dwarves to `N`.
max: | Sets all skills of the selected dwarf to “Proficient”.
max all: | Sets all skills of all dwarves to “Proficient”.
legendary: | Sets all skills of the selected dwarf to “Legendary”.
legendary all: | Sets all skills of all dwarves to “Legendary”.

## emigration

Allows dwarves to emigrate from the fortress when stressed, in proportion to how badly stressed they are and adjusted for who they would have to leave with - a dwarven merchant being more attractive than leaving alone (or with an elf). The check is made monthly.

A happy dwarf (ie with negative stress) will never emigrate.

Usage: `emigration enable|disable`

## empty-bin

Empties the contents of the selected bin onto the floor.

## exportlegends

Controls legends mode to export data - especially useful to set-and-forget large worlds, or when you want a map of every site when there are several hundred.

The ‘info’ option exports more data than is possible in vanilla, to a `region-date-legends_plus.xml` file developed to extend World Viewer and other legends utilities.

Options:

info: | Exports the world/gen info, the legends XML, and a custom XML with more information
custom: | Exports a custom XML with more information
sites: | Exports all available site maps
maps: | Exports all seventeen detailed maps
all: | Equivalent to calling all of the above, in that order

Keybinding: Ctrl A -> `"exportlegends all"` in `legends`

## exterminate

Kills any unit of a given race.

With no argument, lists the available races and count eligible targets.

With the special argument `this`, targets only the selected creature. Alternatively, `him`, `her`, `it`, `target`, and `selected` do the same thing.

With the special argument `undead`, targets all undeads on the map, regardless of their race.

When specifying a race, a caste can be specified to further restrict the targeting. To do that, append and colon and the caste name after the race.

Any non-dead non-caged unit of the specified race gets its `blood_count` set to 0, which means immediate death at the next game tick. For creatures such as vampires, it also sets animal.vanish_countdown to 2.

An alternate mode is selected by adding a 2nd argument to the command, `magma`. In this case, a column of 7/7 magma is generated on top of the targets until they die (Warning: do not call on magma-safe creatures. Also, using this mode on birds is not recommended.) The final alternate mode is `butcher`, which marks them for butchering but does not kill.

Will target any unit on a revealed tile of the map, including ambushers, but ignore caged/chained creatures.

Ex:

    exterminate gob
    exterminate gob:male
    exterminate gob:enemy

To kill a single creature, select the unit with the ‘v’ cursor and:

    exterminate this

To purify all elves on the map with fire (may have side-effects):

    exterminate elve magma

## extinguish

This script allows the user to put out fires affecting map tiles, plants, units, items and buildings.

To select a target, place the cursor over it before running the script. Alternatively, use one of the arguments below.

Arguments:

    -all
        extinguish everything on the map

    -location [ x y z ]
        extinguish only at the specified coordinates

## feature

Enables management of map features.

- Discovering a magma feature (magma pool, volcano, magma sea, or curious underground structure) permits magma workshops and furnaces to be built.
- Discovering a cavern layer causes plants (trees, shrubs, and grass) from that cavern to grow within your fortress.

Options:

list: | Lists all map features in your current embark by index.
magma: | Enable magma furnaces (discovers a random magma feature).
show X: | Marks the selected map feature as discovered.
hide X: | Marks the selected map feature as undiscovered.

## fillneeds

Use with a unit selected to make them focused and unstressed.

Alternatively, a unit can be specified by passing `-unit UNIT_ID`

Use `-all` to apply to all units on the map.

## firestarter

Lights things on fire: items, locations, entire inventories even! Use while viewing an item, unit inventory, or tile to start fires.

## fix-ster

Utilizes the orientation tag to either fix infertile creatures or inflict infertility on creatures that you do not want to breed. Usage:

    fix-ster [fert|ster] [all|animals|only:<creature>]

`fert` or `ster` is a required argument; whether to make the target fertile or sterile. Optional arguments specify the target: no argument for the selected unit, `all` for all units on the map, `animals` for all non-dwarf creatures, or `only:<creature>` to only process matching creatures.

## fixnaked

Removes all unhappy thoughts due to lack of clothing.

## flashstep

A hotkey-friendly teleport that places your adventurer where your cursor is.

## force

A simpler wrapper around the modtools/force script.

Usage:

- `force event_type`
- `force event_type civ_id` - civ ID required for `Diplomat` and `Caravan` events

See modtools/force for a complete list of event types.

## forget-dead-body

Removes emotions associated with seeing a dead body.

## forum-dwarves

Saves a copy of a text screen, formatted in bbcode for posting to the Bay12 Forums. See markdown to export for Reddit etc.

This script will attempt to read the current df-screen, and if it is a text-viewscreen (such as the dwarf ‘thoughts’ screen or an item ‘description’) then append a marked-up version of this text to the target file. Previous entries in the file are not overwritten, so you may use the ‘forumdwarves’ command multiple times to create a single document containing the text from multiple screens (eg: text screens from several dwarves, or text screens from multiple artifacts/items, or some combination).

The screens which have been tested and known to function properly with this script are:

1. dwarf/unit ‘thoughts’ screen
2. item/art ‘description’ screen
3. individual ‘historical item/figure’ screens

There may be other screens to which the script applies. It should be safe to attempt running the script with any screen active, with an error message to inform you when the selected screen is not appropriate for this script.

The target file’s name is ‘forumdwarves.txt’. A reminder to this effect will be displayed if the script is successful.

Note

The text will be encoded in CP437, which is likely to be incompatible with the system default. This causes incorrect display of special characters (eg. é õ ç = `é õ ç`). You can fix this by opening the file in an editor such as Notepad++ and selecting the correct encoding before using the text.

Keybinding: Ctrl Shift F in `dwarfmode`

## full-heal

Attempts to fully heal the selected unit from anything, optionally including death. Usage:

full-heal: | Completely heal the currently selected unit.
full-heal -unit [unitId]:
| Apply command to the unit with the given ID, instead of selected unit.
full-heal -r [-keep_corpse]:
| Heal the unit, raising from the dead if needed. Add `-keep_corpse` to avoid removing their corpse. The unit can be targeted by selecting its corpse on the UI.
full-heal -all [-r] [-keep_corpse]:
| Heal all units on the map.
full-heal -all_citizens [-r] [-keep_corpse]:
| Heal all fortress citizens on the map. Does not include pets.
full-heal -all_civ [-r] [-keep_corpse]:
| Heal all units belonging to your parent civilisation, including pets and visitors.

For example, `full-heal -r -keep_corpse -unit ID_NUM` will fully heal unit ID_NUM. If this unit was dead, it will be resurrected without deleting the corpse - creepy!

## gaydar

Shows the sexual orientation of units, useful for social engineering or checking the viability of livestock breeding programs.

Targets:

-all: | shows orientation of every creature
-citizens: | shows only orientation of citizens in fort mode
-named: | shows orientation of all named units on map
(no target): | shows orientation of the unit under the cursor

Orientation filters:

-notStraight: | only creatures who are not strictly straight
-gayOnly: | only creatures who are strictly gay
-biOnly: | only creatures who can get into romances with both sexes
-straightOnly: | only creatures who are strictly straight
-asexualOnly: | only creatures who are strictly asexual

## ghostly

Toggles an adventurer’s ghost status. Useful for walking through walls, avoiding attacks, or recovering after a death.

## growcrops

Instantly grow seeds inside farming plots.

With no argument, this command list the various seed types currently in use in your farming plots. With a seed type, the script will grow specified seeds, ready to be harvested.

Arguments:

- `list` or `help`
    List the various seed types currently in use in your farming plots
- `<crop name>`
    Grow specific planted seed type
- `all`
    Grow all planted seeds

Example:

- Grow plump helmet spawn:
    `growcrops plump`

## hermit

Blocks all caravans, migrants, diplomats, and forgotten beasts (not wildlife). Useful for attempting the hermit challenge.

Use `enable` or `disable` to enable/disable, or `help` for this help.

Warning

This does not block sieges, and may not block visitors or monarchs.

## hfs-pit

Creates a pit to the underworld at the cursor, taking three numbers as arguments. Usage: `hfs-pit <size> <walls> <stairs>`

The first argument is size of the (square) pit in all directions. The second is `1` to wall off the sides of the pit on all layers except the underworld, or anything else to leave them open. The third parameter is 1 to add stairs. Stairs are buggy; they will not reveal the bottom until you dig somewhere, but underworld creatures will path in.

Examples:

    hfs-pit 1 0 0
        A single-tile wide pit with no walls or stairs.
        This is the default if no numbers are given.

    hfs-pit 4 0 1
        A four-across pit with no stairs but adding walls.

    hfs-pit 2 1 0
        A two-across pit with stairs but no walls.

## hotkey-notes

Lists the key, name, and jump position of your hotkeys in the DFHack console.

## install-info

Saves information about the current DFHack installation to `install-info.txt` in the current DF folder. Useful for bug reports.

## item-descriptions

Exports a table with custom description text for every item in the game. Used by view-item-info; see instructions there for how to override for mods.

## launch

Activate with a cursor on screen and you will go there rapidly. Attack something first to ride them there.

## lever

Allow manipulation of in-game levers from the dfhack console.

Can list levers, including state and links, with:

    lever list

To queue a job so that a dwarf will pull the lever 42, use `lever pull 42`. This is the same as `q` querying the building and queue a `P` pull request.

To queue a job at high priority, add `--high` or `--priority`:

    lever pull 42 --high

To magically toggle the lever immediately, add `--now` or `--cheat`:

    lever pull 42 --now

## linger

Enables the player to take control of their adventurer’s killer. Run this script after being presented with “You are deceased.”

The killer is identified by examining the historical event generated when the adventurer died. If this is unsuccessful, the killer is assumed to be the last unit to have attacked the adventurer prior to their death.

This will fail if the unit in question is no longer present on the local map.

(Adventure mode only!)

## load-save

When run on the title screen or “load game” screen, loads the save with the given folder name without requiring interaction.

Example: `load-save region`

This can also be run when starting DFHack from the command line:

    ./dfhack +load-game region1

(This is currently untested on Windows)

## locate-ore

Scan the map for metal ores.

Finds and designate for digging one tile of a specific metal ore. Only works for native metal ores, does not handle reaction stuff (eg STEEL).

When invoked with the `list` argument, lists metal ores available on the map.

Examples:

    locate-ore list
    locate-ore hematite
    locate-ore iron

## lua

There are the following ways to invoke this command:

1. `lua` (without any parameters)

   This starts an interactive lua interpreter.

2. `lua -f "filename"` or `lua --file "filename"`

   This loads and runs the file indicated by filename.

3. `lua -s ["filename"]` or `lua --save ["filename"]`

   This loads and runs the file indicated by filename from the save directory. If the filename is not supplied, it loads “dfhack.lua”.

4. `:lua` lua statement…

   Parses and executes the lua statement like the interactive interpreter would.

## make-legendary

Makes the selected dwarf legendary in one skill, a group of skills, or all skills. View groups with `make-legendary classes`, or all skills with `make-legendary list`. Use `make-legendary MINING` when you need something dug up, or `make-legendary all` when only perfection will do.

## make-monarch

Make the selected unit King or Queen of your civilisation.

## markdown

Save a copy of a text screen in markdown (for reddit among others). See forum-dwarves for BBCode export (for eg. the Bay12 Forums).

This script will attempt to read the current df-screen, and if it is a text-viewscreen (such as the dwarf ‘thoughts’ screen or an item / creature ‘description’) or an announcement list screen (such as announcements and combat reports) then append a marked-down version of this text to the target file (for easy pasting on reddit for example). Previous entries in the file are not overwritten, so you may use the``markdown`` command multiple times to create a single document containing the text from multiple screens (eg: text screens from several dwarves, or text screens from multiple artifacts/items, or some combination).

Usage: `markdown [-n] [filename]`

-n: | overwrites contents of output file
filename: | if provided, save to `md_filename.md` instead of the default `md_export.md`

The screens which have been tested and known to function properly with this script are:

1. dwarf/unit ‘thoughts’ screen
2. item/art ‘description’ screen
3. individual ‘historical item/figure’ screens
4. manual
5. announements screen
6. combat reports screen
7. latest news (when meeting with liaison)

There may be other screens to which the script applies. It should be safe to attempt running the script with any screen active, with an error message to inform you when the selected screen is not appropriate for this script.

## masspit

Designate all creatures in cages on top of a pit/pond activity zone for pitting. Works best with an animal stockpile on top of the zone.

Works with a zone number as argument (eg `Activity Zone #6` -> `masspit 6`) or with the game cursor on top of the area.

## migrants-now

Forces an immediate migrant wave. Only works after migrants have arrived naturally. Equivalent to modtools/force `-eventType migrants`

## multicmd

Run multiple dfhack commands. The argument is split around the character ; and all parts are run sequentially as independent dfhack commands. Useful for hotkeys.

Example:

    multicmd locate-ore IRON ; digv ; digcircle 16

## names

Rename units or items. Usage: :-help: print this help message :-if a first name is desired press f, leave blank to clear current first name :-if viewing an artifact you can rename it :-if viewing a unit you can rename them

## open-legends

Open a legends screen when in fortress mode. Requires a world loaded in fortress or adventure mode. Compatible with exportlegends.

Note that this script carries a significant risk of save corruption if the game is saved after exiting legends mode. To avoid this:

1. Pause DF
2. Run quicksave to save the game
3. Run open-legends (this script) and browse legends mode as usual
4. Immediately after exiting legends mode, run die to quit DF without saving (saving at this point instead may corrupt your save)

Note that it should be safe to run “open-legends” itself multiple times in the same DF session, as long as DF is killed immediately after the last run. Unpausing DF or running other commands risks accidentally autosaving the game, which can lead to save corruption.

The optional `force` argument will bypass all safety checks, as well as the save corruption warning.

## points

Sets available points at the embark screen to the specified number. Eg. `points 1000000` would allow you to buy everything, or `points 0` would make life quite difficult.

## position

Reports the current time: date, clock time, month, and season. Also reports location: z-level, cursor position, window size, and mouse location.

## pref-adjust

A two-stage script: `pref-adjust clear` removes preferences from all dwarves, and `pref-adjust` inserts an ‘ideal’ set which is easy to satisfy:

    Feb Idashzefon likes wild strawberries for their vivid red color,
    fisher berries for their round shape, prickle berries for their
    precise thorns, plump helmets for their rounded tops, prepared meals,
    plants, drinks, doors, thrones, tables and beds. When possible, she
    prefers to consume wild strawberries, fisher berries, prickle
    berries, plump helmets, strawberry wine, fisher berry wine, prickle
    berry wine, and dwarven wine.

## prefchange

Sets preferences for mooding to include a weapon type, equipment type, and material. If you also wish to trigger a mood, see strangemood.

Valid options:

show: | show preferences of all units
c: | clear preferences of selected unit
all: | clear preferences of all units
axp: | likes axes, breastplates, and steel
has: | likes hammers, mail shirts, and steel
swb: | likes short swords, high boots, and steel
spb: | likes spears, high boots, and steel
mas: | likes maces, shields, and steel
xbh: | likes crossbows, helms, and steel
pig: | likes picks, gauntlets, and steel
log: | likes long swords, gauntlets, and steel
dap: | likes daggers, greaves, and steel

Feel free to adjust the values as you see fit, change the has steel to platinum, change the axp axes to great axes, whatnot.

## putontable

Makes item appear on the table, like in adventure mode shops. Arguments: `-a` or `--all` for all items.

## questport

Sends your adventurer to the location of your quest log cursor. Usable from travel mode or on foot. Don’t try to travel normally while in forbidden travel areas (mountains, lairs) and you can questport out.

## quicksave

If called in dwarf mode, makes DF immediately saves the game by setting a flag normally used in seasonal auto-save.

Keybinding: Ctrl Alt S in `dwarfmode/Default`

## region-pops

Show or modify the populations of animals in the region.

Usage:

region-pops list [pattern]:
| Lists encountered populations of the region, possibly restricted by pattern.
region-pops list-all [pattern]:
| Lists all populations of the region.
region-pops boost <TOKEN> <factor>:
| Multiply all populations of TOKEN by factor. If the factor is greater than one, increases the population, otherwise decreases it.
region-pops boost-all <pattern> <factor>:
| Same as above, but match using a pattern acceptable to list.
region-pops incr <TOKEN> <factor>:
| Augment (or diminish) all populations of TOKEN by factor (additive).
region-pops incr-all <pattern> <factor>:
| Same as above, but match using a pattern acceptable to list.

## rejuvenate

Decreases the age of the selected dwarf to 20 years. Useful if valuable citizens are getting old.

Arguments:

- `-all`: applies to all citizens
- `-force`: also applies to units under 20 years old. Useful if there are too many babies around…
- `-dry-run`: only list units that would be changed; don’t actually change ages

## remove-stress

Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or very stressed dwarves taking on negative or greater values respectively. Applies to the selected unit, or use `remove-stress -all` to apply to all units.

## remove-wear

Sets the wear on items in your fort to zero. Usage:

remove-wear all:
| Removes wear from all items in your fort.
remove-wear ID1 ID2 …:
| Removes wear from items with the given ID numbers.

## repeat

Repeatedly calls a lua script at the specified interval. This can be used from init files. Note that any time units other than `frames` are unsupported when a world is not loaded (see `dfhack.timeout()`).

Usage examples:

    repeat -name jim -time delay -timeUnits units -command [ printArgs 3 1 2 ]
    repeat -time 1 -timeUnits months -command [ multicmd cleanowned scattered x; clean all ] -name clean

The first example is abstract; the second will regularly remove all contaminants and worn items from the game.

Arguments:

`-name`
  sets the name for the purposes of cancelling and making sure you don’t schedule the same repeating event twice. If not specified, it’s set to the first argument after `-command`.
`-time DELAY -timeUnits UNITS`
  DELAY is some positive integer, and UNITS is some valid time unit for `dfhack.timeout` (default “ticks”). Units can be in simulation-time “frames” (raw FPS) or “ticks” (only while unpaused), while “days”, “months”, and “years” are by in-world time.
`-command [ ... ]`
  `...` specifies the command to be run
`-cancel NAME`
  cancels the repetition with the name NAME

## season-palette

Swap color palettes when the seasons change.

For this script to work you need to add at least one color palette file to your save raw directory.

Palette file names:
  “colors.txt”: The world “default” (worldgen and replacement) palette. “colors_spring.txt”: The palette displayed during spring. “colors_summer.txt”: The palette displayed during summer. “colors_autumn.txt”: The palette displayed during autumn. “colors_winter.txt”: The palette displayed during winter.

If you do not provide a world default palette, palette switching will be disabled for the current world. The seasonal palettes are optional, the default palette is not! The default palette will be used to replace any missing seasonal palettes and during worldgen.

When the world is unloaded or this script is disabled, the system default color palette (“/data/init/colors.txt”) will be loaded. The system default palette will always be used in the main menu, but your custom palettes should be used everywhere else.

Usage:

> `season-palette start|enable` or `enable season-palette`:
>   Begin swapping seasonal color palettes.
> `season-palette stop|disable` or `disable season-palette`:
>   Stop swapping seasonal color palettes and load the default color palette.

If loaded as a module this script will export a single Lua function:

> `LoadPalette(path)`:
>   Load a color palette from the text file at “path”. This file must be in the same format as “/data/init/colors.txt”. If there is an error any changes will be reverted and this function will return false (returns true normally).

## set-orientation

Edit a unit’s orientation. Interest levels are 0 for Uninterested, 1 for Romance, 2 for Marry.

unit <UNIT ID>: | The given unit will be affected. If not found/provided, the script will try defaulting to the currently selected unit.
male <INTEREST>:
| Set the interest level towards male sexes
female <INTEREST>:
| Set the interest level towards female sexes
opposite <INTEREST>:
| Set the interest level towards the opposite sex to the unit
same <INTEREST>:
| Set the interest level towards the same sex as the unit
random: | Randomise the unit’s interest towards both sexes, respecting their ORIENTATION token odds.

Other arguments:

help: | Shows this help page.
view: | Print the unit’s orientation values in the console.

## setfps

Run `setfps <number>` to set the FPS cap at runtime, in case you want to watch combat in slow motion or something.

## show-unit-syndromes

Show syndromes affecting units and the remaining and maximum duration, along with (optionally) substantial detail on the effects.

Use one or more of the following options:

help: | Show the help message
showall: | Show units even if not affected by any syndrome
showeffects: | Show detailed effects of each syndrome
showdisplayeffects:
| Show effects that only change the look of the unit
selected: | Show selected unit
dwarves: | Show dwarves
livestock: | Show livestock
wildanimals: | Show wild animals
hostile: | Show hostiles (e.g. invaders, thieves, forgotten beasts etc)
world: | Show all defined syndromes in the world
export: | `export:<filename>` sends output to the given file, showing all syndromes affecting each unit with the maximum and present duration.

## siren

Wakes up sleeping units and stops parties, either everywhere or in the burrows given as arguments. In return, adds bad thoughts about noise, tiredness and lack of protection. The script is intended for emergencies, e.g. when a siege appears, and all your military is partying.

## source

Create an infinite magma or water source or drain on a tile. For more complex commands, try the liquids plugin.

This script registers a map tile as a liquid source, and every 12 game ticks that tile receives or remove 1 new unit of flow based on the configuration.

Place the game cursor where you want to create the source (must be a flow-passable tile, and not too high in the sky) and call:

    source add [magma|water] [0-7]

The number argument is the target liquid level (0 = drain, 7 = source).

To add more than 1 unit everytime, call the command again on the same spot.

To delete one source, place the cursor over its tile and use `source delete`. To remove all existing sources, call `source clear`.

The `list` argument shows all existing sources.

Examples:

    source add water     - water source
    source add magma 7   - magma source
    source add water 0   - water drain

## spawnunit

Provides a simpler interface to modtools/create-unit, for creating units.

Usage: `spawnunit [-command] RACE CASTE [NAME] [x y z] [...]`

The `-command` flag prints the generated modtools/create-unit command instead of running it. `RACE` and `CASTE` specify the race and caste of the unit to be created. The name and coordinates of the unit are optional. Any further arguments are simply passed on to modtools/create-unit.

## startdwarf

Use at the embark screen to embark with the specified number of dwarves. Eg. `startdwarf 500` would lead to a severe food shortage and FPS issues, while `startdwarf 10` would just allow a few more warm bodies to dig in. The number must be 7 or greater.

## starvingdead

Somewhere between a “mod” and a “fps booster”, with a small impact on vanilla gameplay. It mostly helps prevent undead cascades in the caverns, where constant combat leads to hundreds of undead roaming the caverns and destroying your FPS.

With this script running, all undead that have been on the map for one month gradually decay, losing strength, speed, and toughness. After six months, they collapse upon themselves, never to be reanimated.

Usage: `starvingdead (start|stop)`

## stripcaged

For dumping items inside cages. Will mark selected items for dumping, then a dwarf may come and actually dump them (or you can use autodump).

Arguments:

list: | display the list of all cages and their item content on the console
items: | dump items in the cage, excluding stuff worn by caged creatures
weapons: | dump equipped weapons
armor: | dump everything worn by caged creatures (including armor and clothing)
all: | dump everything in the cage, on a creature or not

Without further arguments, all commands work on all cages and animal traps on the map. With the `here` argument, considers only the in-game selected cage (or the cage under the game cursor). To target only specific cages, you can alternatively pass cage IDs as arguments:

    stripcaged weapons 25321 34228

## superdwarf

Similar to fastdwarf, per-creature.

To make any creature superfast, target it ingame using ‘v’ and:

    superdwarf add

Other options available: `del`, `clear`, `list`.

This script also shortens the ‘sleeping’ periods of targets.

## tame

Tame and train animals.

Usage: `tame -read` OR `tame -set <level>`

0: | semi-wild
1: | trained
2: | well-trained
3: | skillfully trained
4: | expertly trained
5: | exceptionally trained
6: | masterfully trained
7: | tame
8: | wild
9: | wild

## teleport

Teleports a unit to given coordinates. Examples:

teleport -showunitid:
| prints ID of unit beneath cursor
teleport -showpos:
| prints coordinates beneath cursor
teleport -unit 1234 -x 56 -y 115 -z 26:
| teleports unit 1234 to 56,115,26

See gui/teleport for an in-game UI.

## tidlers

Toggle between all possible positions where the idlers count can be placed.

## troubleshoot-item

Print various properties of the selected item.

## twaterlvl

Toggle between displaying/not displaying liquid depth as numbers.

Keybinding: Ctrl W

## undump-buildings

Undesignates building base materials for dumping.

## unforbid

> unforbid all

> > Options available: `all`, ``help``

## unretire-anyone

This script allows the user to add any living historical figure to the ‘Specific Person’ list in the adventure mode setup menu. They can then be selected and used as a player character, as if regaining control of a retired adventurer.

## unsuspend

Unsuspend construction jobs, on a one-off basis. See autounsuspend for regular use.

## view-item-info

A script to extend the item or unit viewscreen with additional information including a custom description of each item (when available), and properties such as material statistics, weapon attacks, armor effectiveness, and more.

The associated script item-descriptions.lua supplies custom descriptions of items. Individual descriptions can be added or overridden by a similar script `raw/scripts/more-item-descriptions.lua`. Both work as sparse lists, so missing items simply go undescribed if not defined in the fallback.

## view-unit-reports

Show combat reports for the current unit.

Current unit is unit near cursor in ‘v’, selected in ‘u’ list, unit/corpse/splatter at cursor in ‘k’. And newest unit with race when ‘k’ at race-specific blood spatter.

Keybinding: Ctrl Shift R

## warn-starving

If any (live) units are starving, very thirsty, or very drowsy, the game will be paused and a warning shown and logged to the console. Use with the repeat command for regular checks.

Use `warn-starving all` to display a list of all problematic units.

## weather

Prints a map of the local weather, or with arguments `clear`, `rain`, and `snow` changes the weather.