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. Shift
Enter
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
|
||||||
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]
inq
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.
Shift
Esc
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 Alt
I
.
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 Shift
Enter
, 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.