GUI Scripts

gui/* scripts implement dialogs in the main game window.

In order to avoid user confusion, as a matter of policy all these tools display the word DFHack on the screen somewhere while active. When that is not appropriate because they merely add keybinding hints to existing DF screens, they deliberately use red instead of green for the key.

Contents

• GUI Scripts
  • gui/advfort
  • gui/advfort_items
  • gui/assign-rack
  • gui/autobutcher
  • gui/choose-weapons
  • gui/clone-uniform
  • gui/companion-order
  • gui/confirm-opts
  • gui/create-item
  • gui/dfstatus
  • gui/extended-status
  • gui/family-affairs
  • gui/gm-editor
  • gui/gm-unit
  • gui/guide-path
  • gui/hack-wish
  • gui/hello-world
  • gui/liquids
  • gui/load-screen
  • gui/manager-quantity
  • gui/mechanisms
  • gui/mod-manager
  • gui/no-dfhack-init
  • gui/power-meter
  • gui/prerelease-warning
  • gui/quickcmd
  • gui/rename
  • gui/room-list
  • gui/settings-manager
  • gui/siege-engine
  • gui/stockpiles
  • gui/unit-info-viewer
  • gui/workflow
  • gui/workshop-job

gui/advfort

This script allows to perform jobs in adventure mode. For more complete help press ? while script is running. It’s most comfortable to use this as a keybinding. (e.g. keybinding set Ctrl-T gui/advfort). Possible arguments:

-a, –nodfassign:  uses different method to assign items. -i, –inventory:  checks inventory for possible items to use in the job. -c, –cheat:relaxes item requirements for buildings (e.g. walls from bones). Implies -a job:selects that job (e.g. Dig or FellTree)

An example of player digging in adventure mode:

WARNING: changes only persist in non procedural sites, namely: player forts, caves, and camps.

gui/advfort_items

Does something with items in adventure mode jobs.

gui/assign-rack

This script requires a binpatch, which has not been available since DF 0.34.11

See Bug 1445 for more info about the patches.

gui/autobutcher

An in-game interface for autobutcher. This script must be called from either the overall status screen or the animal list screen.

gui/choose-weapons

Activate in the Equip->View/Customize page of the military screen.

Depending on the cursor location, it rewrites all ‘individual choice weapon’ entries in the selected squad or position to use a specific weapon type matching the assigned unit’s top skill. If the cursor is in the rightmost list over a weapon entry, it rewrites only that entry, and does it even if it is not ‘individual choice’.

Rationale: individual choice seems to be unreliable when there is a weapon shortage, and may lead to inappropriate weapons being selected.

gui/clone-uniform

When invoked, the script duplicates the currently selected uniform template, and selects the newly created copy. Activate in the Uniforms page of the military screen with the cursor in the leftmost list.

gui/companion-order

A script to issue orders for companions. Select companions with lower case chars, issue orders with upper case. Must be in look or talk mode to issue command on tile.

• move - orders selected companions to move to location. If companions are following they will move no more than 3 tiles from you.
• equip - try to equip items on the ground.
• pick-up - try to take items into hand (also wield)
• unequip - remove and drop equipment
• unwield - drop held items
• wait - temporarily remove from party
• follow - rejoin the party after “wait”
• leave - remove from party (can be rejoined by talking)

gui/confirm-opts

A basic configuration interface for the confirm plugin.

gui/create-item

A graphical interface for creating items.

See also: createitem, modtools/create-item, Issue 735

gui/dfstatus

Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars. Sections can be enabled/disabled/configured by editing dfhack-config/dfstatus.lua.

gui/extended-status

Adds more subpages to the z status screen.

Usage:

gui/extended-status enable|disable|help|subpage_names
enable|disable gui/extended-status

gui/family-affairs

A user-friendly interface to view romantic relationships, with the ability to add, remove, or otherwise change them at your whim - fantastic for depressed dwarves with a dead spouse (or matchmaking players...).

The target/s must be alive, sane, and in fortress mode.

gui/family-affairs [unitID]

shows GUI for the selected unit, or the specified unit ID

gui/family-affairs divorce [unitID]

removes all spouse and lover information from the unit and it’s partner, bypassing almost all checks.

gui/family-affairs [unitID] [unitID]

divorces the two specificed units and their partners, then arranges for the two units to marry, bypassing almost all checks. Use with caution.

gui/gm-editor

This editor allows to change and modify almost anything in df. Press ? for in-game help. There are three ways to open this editor:

• Callling gui/gm-editor from a command or keybinding opens the editor on whatever is selected or viewed (e.g. unit/item description screen)
• using gui/gm-editor <lua command> - executes lua command and opens editor on its results (e.g. gui/gm-editor "df.global.world.items.all" shows all items)
• using gui/gm-editor dialog - shows an in game dialog to input lua command. Works the same as version above.
• using gui/gm-editor toggle - will hide (if shown) and show (if hidden) editor at the same position you left it

gui/gm-unit

An editor for various unit attributes.

gui/guide-path

Activate in the Hauling menu with the cursor over a Guide order.

The script displays the cached path that will be used by the order; the game computes it when the order is executed for the first time.

gui/hack-wish

An alias for gui/create-item. Deprecated.

gui/hello-world

A basic example for testing, or to start your own script from.

gui/liquids

This script is a gui front-end to liquids and works similarly, allowing you to add or remove water & magma, and create obsidian walls & floors.

Warning

There is no undo support. Bugs in this plugin have been known to create pathfinding problems and heat traps.

The b key changes how the affected area is selected. The default Rectangle mode works by selecting two corners like any ordinary designation. The p key chooses between adding water, magma, obsidian walls & floors, or just tweaking flags.

When painting liquids, it is possible to select the desired level with +-, and choose between setting it exactly, only increasing or only decreasing with s.

In addition, f allows disabling or enabling the flowing water computations for an area, and r operates on the “permanent flow” property that makes rivers power water wheels even when full and technically not flowing.

After setting up the desired operations using the described keys, use Enter to apply them.

gui/load-screen

A replacement for the “continue game” screen.

Usage: gui/load-screen enable|disable

gui/manager-quantity

Sets the quantity of the selected manager job

Sample usage:

keybinding add Alt-Q@jobmanagement gui/manager-quantity

gui/mechanisms

Lists mechanisms connected to the building, and their links. Navigating the list centers the view on the relevant linked buildings.

To exit, press Esc or Enter; Esc recenters on the original building, while Enter leaves focus on the current one. ShiftEnter has an effect equivalent to pressing Enter, and then re-entering the mechanisms UI.

gui/mod-manager

A simple way to install and remove small mods, which are not included in DFHack. Examples are available here.

Each mod is a lua script located in <DF>/mods/, which MUST define the following variables:

name:a name that is displayed in list author:mod author, also displayed description:a description of the mod

Of course, this doesn’t actually make a mod - so one or more of the following should also be defined:

raws_list:

a list (table) of file names that need to be copied over to df raws

patch_entity:

a chunk of text to patch entity TODO: add settings to which entities to add

patch_init:

a chunk of lua to add to lua init

patch_dofile:

a list (table) of files to add to lua init as “dofile”

patch_files:

a table of files to patch

filename:a filename (in raws folder) to patch patch:what to add after:a string after which to insert

guard:

a token that is used in raw files to find additions and remove them on uninstall

guard_init:

a token for lua file

[pre|post]_(un)install:  

Callback functions, which can trigger more complicated behavior

gui/no-dfhack-init

Shows a warning at startup if no valid dfhack.init file is found.

gui/power-meter

Activate an in-game interface for power-meter after selecting Pressure Plate in the build menu.

The script follows the general look and feel of the regular pressure plate build configuration page, but configures parameters relevant to the modded power meter building.

gui/prerelease-warning

Shows a warning on world load for pre-release builds.

With no arguments passed, the warning is shown unless the “do not show again” option has been selected. With the force argument, the warning is always shown.

gui/quickcmd

A list of commands which you can edit while in-game, and which you can execute quickly and easily. For stuff you use often enough to not want to type it, but not often enough to be bothered to find a free keybinding.

gui/rename

Backed by rename, this script allows entering the desired name via a simple dialog in the game ui.

• gui/rename [building] in q mode changes the name of a building.

  

  The selected building must be one of stockpile, workshop, furnace, trap, or siege engine. It is also possible to rename zones from the i menu.

• gui/rename [unit] with a unit selected changes the nickname.

  Unlike the built-in interface, this works even on enemies and animals.

• gui/rename unit-profession changes the selected unit’s custom profession name.

  

  Likewise, this can be applied to any unit, and when used on animals it overrides their species string.

The building or unit options are automatically assumed when in relevant UI state.

gui/room-list

Activate in q mode, either immediately or after opening the assign owner page.

The script lists other rooms owned by the same owner, or by the unit selected in the assign list, and allows unassigning them.

gui/settings-manager

An in-game manager for settings defined in init.txt and d_init.txt.

gui/siege-engine

Activate an in-game interface for siege-engine, after selecting a siege engine in q mode.

The main mode displays the current target, selected ammo item type, linked stockpiles and the allowed operator skill range. The map tile color is changed to signify if it can be hit by the selected engine: green for fully reachable, blue for out of range, red for blocked, yellow for partially blocked.

Pressing r changes into the target selection mode, which works by highlighting two points with Enter like all designations. When a target area is set, the engine projectiles are aimed at that area, or units within it (this doesn’t actually change the original aiming code, instead the projectile trajectory parameters are rewritten as soon as it appears).

After setting the target in this way for one engine, you can ‘paste’ the same area into others just by pressing p in the main page of this script. The area to paste is kept until you quit DF, or select another area manually.

Pressing t switches to a mode for selecting a stockpile to take ammo from.

Exiting from the siege engine script via Esc reverts the view to the state prior to starting the script. ShiftEsc retains the current viewport, and also exits from the q mode to main menu.

gui/stockpiles

An in-game interface for stocksettings, to load and save stockpile settings from the q menu.

Usage:

gui/stockpiles -save:  to save the current stockpile gui/stockpiles -load:  to load settings into the current stockpile gui/stockpiles -dir <path>:  set the default directory to save settings into gui/stockpiles -help:  to see this message

Don’t forget to enable stockpiles and create the stocksettings directory in the DF folder before trying to use the GUI.

gui/unit-info-viewer

Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size, and death info about a unit. Recommended keybinding AltI.

gui/workflow

Bind to a key (the example config uses Alt-W), and activate with a job selected in a workshop in q mode.

This script provides a simple interface to constraints managed by workflow. When active, it displays a list of all constraints applicable to the current job, and their current status.

A constraint specifies a certain range to be compared against either individual item or whole stack count, an item type and optionally a material. When the current count is below the lower bound of the range, the job is resumed; if it is above or equal to the top bound, it will be suspended. Within the range, the specific constraint has no effect on the job; others may still affect it.

Pressing i switches the current constraint between counting stacks or items. Pressing r lets you input the range directly; e, r, d, f adjust the bounds by 5, 10, or 20 depending on the direction and the i setting (counting items and expanding the range each gives a 2x bonus).

Pressing a produces a list of possible outputs of this job as guessed by workflow, and lets you create a new constraint by choosing one as template. If you don’t see the choice you want in the list, it likely means you have to adjust the job material first using job item-material or gui/workshop-job, as described in the workflow documentation. In this manner, this feature can be used for troubleshooting jobs that don’t match the right constraints.

If you select one of the outputs with Enter, the matching constraint is simply added to the list. If you use ShiftEnter, the interface proceeds to the next dialog, which allows you to edit the suggested constraint parameters to suit your need, and set the item count range.

Pressing s (or, with the example config, Alt-W in the z stocks screen) opens the overall status screen:

This screen shows all currently existing workflow constraints, and allows monitoring and/or changing them from one screen. The constraint list can be filtered by typing text in the field below.

The color of the stock level number indicates how “healthy” the stock level is, based on current count and trend. Bright green is very good, green is good, red is bad, bright red is very bad.

The limit number is also color-coded. Red means that there are currently no workshops producing that item (i.e. no jobs). If it’s yellow, that means the production has been delayed, possibly due to lack of input materials.

The chart on the right is a plot of the last 14 days (28 half day plots) worth of stock history for the selected item, with the rightmost point representing the current stock value. The bright green dashed line is the target limit (maximum) and the dark green line is that minus the gap (minimum).

gui/workshop-job

Run with a job selected in a workshop in the q mode.

The script shows a list of the input reagents of the selected job, and allows changing them like the job item-type and job item-material commands.

Specifically, pressing the i key pops up a dialog that lets you select an item type from a list.

Pressing m, unless the item type does not allow a material, lets you choose a material.

Since there are a lot more materials than item types, this dialog is more complex and uses a hierarchy of sub-menus. List choices that open a sub-menu are marked with an arrow on the left.

Warning

Due to the way input reagent matching works in DF, you must select an item type if you select a material, or the material will be matched incorrectly in some cases. If you press m without choosing an item type, the script will auto-choose if there is only one valid choice, or pop up an error message box instead of the material selection dialog.

Note that both materials and item types presented in the dialogs are filtered by the job input flags, and even the selected item type for material selection, or material for item type selection. Many jobs would let you select only one input item type.

For example, if you choose a plant input item type for your prepare meal job, it will only let you select cookable materials.

If you choose a barrel item instead (meaning things stored in barrels, like drink or milk), it will let you select any material, since in this case the material is matched against the barrel itself. Then, if you select, say, iron, and then try to change the input item type, now it won’t let you select plant; you have to unset the material first.