MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update quickstart guide with control panel info

develop
Myk Taylor 2023-01-30 13:30:34 -08:00
parent 0c92317cce
commit 3805925c02
No known key found for this signature in database
GPG Key ID: 8A39CA0FA0C16E78
1 changed files with 62 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
docs/Quickstart.rst
Unescape Escape View File

@ -46,53 +46,66 @@ Here are some common tasks people use DFHack tools to accomplish:
your mining efforts your mining efforts
Some tools are one-shot commands. For example, you can run `unforbid all <unforbid>` Some tools are one-shot commands. For example, you can run `unforbid all <unforbid>`
to claim all items on the map after a messy siege. to claim all (reachable) items on the map after a messy siege.
Other tools must be `enabled <enable>` and then they will run in the background. Other tools must be `enabled <enable>` and then they will run in the background.
For example, `enable seedwatch <seedwatch>` will start monitoring your stocks of For example, `enable seedwatch <seedwatch>` will start monitoring your stocks of
seeds and prevent your chefs from cooking seeds that you need for planting. seeds and prevent your chefs from cooking seeds that you need for planting.
Tools that are enabled in the context of a fort will save their state with that Tools that are enabled in the context of a fort will save their state with that
fort, and the will remember that they are enabled the next time you load your save. fort, and they will remember that they are enabled the next time you load your save.
A third class of tools add information to the screen or provide new integrated A third class of tools add information to the screen or provide new integrated
functionality via the DFHack `overlay` framework. For example, the `unsuspend` functionality via the DFHack `overlay` framework. For example, the `unsuspend`
tool, in addition to its basic function of unsuspending all building construction tool, in addition to its basic function of unsuspending all building construction
jobs, can also overlay a marker on suspended buildings to indicate that they are jobs, can also overlay a marker on suspended buildings to indicate that they are
suspended (and will use different markers to tell you whether this is a problem). suspended (and will use different markers to tell you whether this is a problem).
These overlays can be enabled and configured with the `gui/overlay` interface.
How can I figure out which commands to run? How can I figure out which commands to run?
------------------------------------------- -------------------------------------------
There are several ways to scan DFHack tools and find the one you need right now. There are several ways to scan DFHack tools and find the ones you need right now.
The first place to check is the DFHack logo hover hotspot. It's in the upper The first place to check is the DFHack logo hover hotspot. It's in the upper
left corner of the screen by default, though you can move it anywhere you want left corner of the screen by default, though you can move it anywhere you want
with the `gui/overlay` tool. with the `gui/overlay` configuration UI.
When you hover the mouse over the logo (or hit the Ctrl-Shift-C keyboard shortcut) When you hover the mouse over the logo (or hit the Ctrl-Shift-C keyboard shortcut)
a list of DFHack tools relevant to the current context comes up. For example, when a list of DFHack tools relevant to the current context comes up. For example, when
you have a unit selected, the hotspot will show a list of tools that inspect you have a unit selected, the hotspot will show a list of tools that inspect
units, allow you to edit them, or maybe even teleport them. Next to each tool, units, allow you to edit them, or maybe even teleport them. Next to each tool,
you'll see the global hotkey you can hit to invoke the command without even you'll see the hotkey you can hit to invoke the command without even opening the
opening the hover list. hover list.
You can run any DFHack tool from `gui/launcher`, which is always listed first in The second place to check is the DFHack control panel: `gui/control-panel`. It
the hover list. You can also bring up the launcher by tapping the backtick key will give you an overview of which tools are currently enabled, and will allow
(\`) or hitting Ctrl-Shift-D. In the launcher, you can quickly autocomplete any you to toggle them on or off, see help text for them, or launch their dedicated
command name by selecting it in the list on the right side of the window. configuration UIs. You can launch the control panel from anywhere with the
Commands are ordered by how often you run them, so your favorite commands will tilde key (Shift-\`) or from the logo hover list.
always be on top. You can also pull full commandlines out of your history with
Alt-S (or by clicking on the "history search" hotkey hint). In the control panel, you can also select which tools you'd like to be
automatically enabled when you start a new fort. There are also system settings
you can change, like whether DFHack windows will pause the game when they come
up.
Finally, you can explore the full extent of the DFHack catalog in `gui/launcher`,
which is always listed first in the DFHack logo hover list. You can also bring up
the launcher by tapping the backtick key (\`) or hitting Ctrl-Shift-D. In the
launcher, you can quickly autocomplete any command name by selecting it in the
list on the right side of the window. Commands are ordered by how often you run
them, so your favorite commands will always be on top. You can also pull full
commandlines out of your history with Alt-S or by clicking on the "history search"
hotkey hint.
Once you have typed (or autocompleted, or searched for) a command, other commands Once you have typed (or autocompleted, or searched for) a command, other commands
related to the one you have selected will appear in the autocomplete list. related to the one you have selected will appear in the right-hand panel. Scanning
Scanning through that list is a great way to learn about new tools that you might through that list is a great way to learn about new tools that you might find
find useful. You can also see how commands are grouped by running the `tags` command. useful. You can also see how commands are grouped by running the `tags` command.
The bottom panel will show the full help text for the command you are running, The bottom panel will show the full help text for the command you are running,
allowing you to refer to the usage documentation and examples when you are typing allowing you to refer to the usage documentation and examples when you are typing
your command. your command. After you run a command, the bottom panel switches to command output
mode, but you can get back to the help text by hitting Ctrl-T or clicking on the
``Showing`` selector.
How do DFHack in-game windows work? How do DFHack in-game windows work?
----------------------------------- -----------------------------------
@ -106,26 +119,27 @@ whether they capture keyboard and mouse input.
The DFHack windowing system allows multiple overlapping windows to be active at The DFHack windowing system allows multiple overlapping windows to be active at
once. The one with the highlighted title bar has focus and will receive anything once. The one with the highlighted title bar has focus and will receive anything
you type at the keyboard. Hit Esc or right click to close the window or cancel you type at the keyboard. Hit Esc or right click to close the window or cancel
the current operation. You can click anywhere on the screen that is not a the current action. You can click anywhere on the screen that is not a DFHack
DFHack window to unfocus the window and let it just sit in the background. It won't window to unfocus the window and let it just sit in the background. It won't
respond to key presses or mouse clicks until you click on it again to give it respond to key presses or mouse clicks until you click on it again to give it
focus. You can right click directly on an unfocused window to close it without focus. If no DFHack windows are focused, you can right click directly on a window
left clicking to activate it first. to close it without left clicking to focus it first.
DFHack windows are draggable from the title bar or from anywhere on the window DFHack windows are draggable from the title bar or from anywhere on the window
that doesn't have a mouse-clickable widget on it. Many are resizable as well that doesn't have a mouse-clickable widget on it. Many are resizable as well
(if the tool window has components that can reasonably be resized). (if the tool window has components that can reasonably be resized).
You can generally use DFHack tools without interrupting the game. That is, if the You can generally use DFHack tools without interrupting the game. That is, if the
game is unpaused, it can continue to run while a DFHack window is open. Many tools game is unpaused, it can continue to run while a DFHack window is open. If configured
will initially pause the game to let you focus on the task at hand, but you can to do so in `gui/control-panel`, tools will initially pause the game to let you
unpause like normal if you want. You can also interact with the map, scrolling it focus on the task at hand, but you can unpause like normal if you want. You can
with the keyboard or mouse and selecting units, buildings, and items. Some tools also interact with the map, scrolling it with the keyboard or mouse and selecting
will capture all keyboard input, such as tools with editable text fields, and some units, buildings, and items. Some tools will capture all keyboard input, such as
will force-pause the game if it makes sense to, like `gui/quickfort`, since you tools with editable text fields, and some will force-pause the game if it makes
cannot interact with the map normally while trying to apply a blueprint. Windows sense to, like `gui/quickfort`, since you cannot interact with the map normally
for tools that force-pause the game will have a pause icon in their upper right while trying to apply a blueprint. Windows for tools that force-pause the game
corner to indicate which tool is responsible for the pausing. will have a pause icon in their upper right corner to indicate which tool is
preventing you from unpausing.
Where do I go next? Where do I go next?
------------------- -------------------
@ -135,33 +149,32 @@ To recap:
You can get to popular, relevant tools for the current context by hovering You can get to popular, relevant tools for the current context by hovering
the mouse over the DFHack logo or by hitting Ctrl-Shift-C. the mouse over the DFHack logo or by hitting Ctrl-Shift-C.
You can enable DFHack tools and configure settings with `gui/control-panel`,
which you can access directly with the tilde key (Shift-\`).
You can get to the launcher and its integrated autocomplete, history search, You can get to the launcher and its integrated autocomplete, history search,
and help text by hitting backtick (\`) or Ctrl-Shift-D, or, of course, by and help text by hitting backtick (\`) or Ctrl-Shift-D, or, of course, by
running it from the logo hover list. running it from the logo hover list.
You can list and start tools that run in the background with the `enable` With those three tools, you have the complete DFHack tool suite at your
command.
You can configure screen overlays with the `gui/overlay` tool.
With those four tools, you have the complete DFHack tool suite at your
fingertips. So what to run first? Here are a few commands to get you started. fingertips. So what to run first? Here are a few commands to get you started.
You can run them all from the launcher. You can run them all from the launcher.
First, let's import some useful manager orders to keep your fort stocked with First, let's import some useful manager orders to keep your fort stocked with
basic necessities. Run ``orders import library/basic``. If you go to your basic necessities. Run ``orders import library/basic``. If you go to your
mangager orders screen, you can see all the orders that have been created for you. mangager orders screen, you can see all the orders that have been created for you.
Note that you could have imported the orders directly from this screen as well,
Next, try setting up `autochop` by running the GUI configuration `gui/autochop`. using the DFHack `overlay` widget at the bottom of the manager orders panel.
You can enable it from the GUI, so you don't need to run `enable autochop <enable>`
directly. You can set a target number of logs, and autochop will manage Next, try setting up `autochop` to automatically designate trees for chopping when
your logging industry for you. You can control where your woodsdwarves go to you get low on usable logs. Run `gui/control-panel` and select ``autochop`` in the
cut down trees by setting up burrows and configuring autochop to only cut in list. Click on the button to the left of the name or hit Enter to enable it. You
those burrows. If you have the extra screen space, go ahead and set the can then click on the ``[configure]`` button to launch `gui/autochop` if you'd
`gui/autochop` window to minimal mode (click on the hint near the upper right like to customize its settings. If you have the extra screen space, you can go
corner of the window or hit Alt-M) and click on the map so the window loses ahead and set the `gui/autochop` window to minimal mode (click on the hint near
keyboard focus. As you play the game, you can glance at the status panel to the upper right corner of the window or hit Alt-M) and click on the map so the
check on your stocks of wood. window loses keyboard focus. As you play the game, you can glance at the live
status panel to check on your stocks of wood.
Finally, let's do some fort design copy-pasting. Go to some bedrooms that you have Finally, let's do some fort design copy-pasting. Go to some bedrooms that you have
set up in your fort. Run `gui/blueprint`, set a name for your blueprint by set up in your fort. Run `gui/blueprint`, set a name for your blueprint by