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

revise quickstart guide

develop
Myk Taylor 2023-09-14 11:47:15 -07:00
parent fc88bfcbbc
commit 540bd602af
No known key found for this signature in database
1 changed files with 116 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

220
docs/Quickstart.rst
Unescape Escape View File

@ -45,67 +45,75 @@ Here are some common tasks people use DFHack tools to accomplish:
- Quickly scan the map for visible ores of specific types so you can focus - Quickly scan the map for visible ores of specific types so you can focus
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
to claim all (reachable) items on the map after a messy siege. `unforbid all <unforbid>` 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.
For example, `enable seedwatch <seedwatch>` will start monitoring your stocks of Other tools must be `enabled <enable>` once and then they will run in the
seeds and prevent your chefs from cooking seeds that you need for planting. background. For example, once enabled, `seedwatch` will start monitoring your
Tools that are enabled in the context of a fort will save their state with that stocks of seeds and prevent your chefs from cooking seeds that you need for
fort, and they will remember that they are enabled the next time you load your save. planting. Tools that are enabled in the context of a fort will save their state
with that fort, and they will remember that they are enabled the next time you
A third class of tools add information to the screen or provide new integrated load your save.
functionality via the DFHack `overlay` framework. For example, the `unsuspend`
tool, in addition to its basic function of unsuspending all building construction A third class of tools adds information to the screen or provides new integrated
jobs, can also overlay a marker on suspended buildings to indicate that they are functionality via the DFHack `overlay` framework. For example, the `sort` tool
suspended (and will use different markers to tell you whether this is a problem). adds widgets to the squad member selection screen that allow you to search,
sort, and filter the list of military candidates. You don't have to run any
command to get the benefits of the tool, it appears automatically when you're
on the relevant screen.
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 ones 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 menu. It's in the upper left corner
left corner of the screen by default, though you can move it anywhere you want of the screen by default, though you can move it anywhere you want with the
with the `gui/overlay` configuration UI. `gui/overlay` configuration UI.
When you hover the mouse over the logo (or hit the Ctrl-Shift-C keyboard shortcut) When you click on the logo (or hit the Ctrl-Shift-C keyboard shortcut), a short
a list of DFHack tools relevant to the current context comes up. For example, when list of popular, relevant DFHack tools comes up. These are the tools that have
you have a unit selected, the hotspot will show a list of tools that inspect been assigned hotkeys that are active in the current context. For example, when
units, allow you to edit them, or maybe even teleport them. Next to each tool, you're looking at a fort map, the list will contain fortress design tools like
you'll see the hotkey you can hit to invoke the command without even opening the `gui/quickfort` and `gui/design`. You can click on the tools in the list, or
hover list. note the hotkeys listed next to them and maybe use them to launch the tool next
time without even opening the logo menu.
The second place to check is the DFHack control panel: `gui/control-panel`. It The second place to check is the DFHack control panel: `gui/control-panel`. It
will give you an overview of which tools are currently enabled, and will allow will give you an overview of which tools are currently enabled, and will allow
you to toggle them on or off, see help text for them, or launch their dedicated you to toggle them on or off, see help text for them, or launch their dedicated
configuration UIs. You can open the control panel from anywhere with the configuration UIs. You can open the control panel from anywhere with the
Ctrl-Shift-E hotkey or by selecting it from the logo hover list. Ctrl-Shift-E hotkey or by selecting it from the logo menu list.
In the control panel, you can also select which tools you'd like to be 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 automatically enabled and popular commands you'd like to run when you start a
you can change, like whether DFHack windows will pause the game when they come new fort. On the "Preferences" tab, there are settings you can change, like
up. whether you want to limit DFHack functionality to interface improvements,
bugfixes, and productivity tools, hiding the god-mode tools ("mortal mode") or
Finally, you can explore the full extent of the DFHack catalog in `gui/launcher`, whether you want DFHack windows to pause the game when they come up.
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 Finally, you can explore the full extent of the DFHack catalog in
launcher, you can quickly autocomplete any command name by selecting it in the `gui/launcher`, which is always listed first in the DFHack logo menu list. You
list on the right side of the window. Commands are ordered by how often you run can also bring up the launcher by tapping the backtick key (\`) or hitting
them, so your favorite commands will always be on top. You can also pull full Ctrl-Shift-D. In the launcher, you can quickly autocomplete any command name by
commandlines out of your history with Alt-S or by clicking on the "history search" selecting it in the list on the right side of the window. Commands are ordered
hotkey hint. 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
Once you have typed (or autocompleted, or searched for) a command, other commands on the "history search" hotkey hint.
related to the one you have selected will appear in the right-hand panel. Scanning
through that list is a great way to learn about new tools that you might find Once you have typed (or autocompleted, or searched for) a command, other
useful. You can also see how commands are grouped by running the `tags` command. commands related to the one you have selected will appear in the right-hand
panel. Scanning through that list is a great way to learn about new tools that
you might find 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
your command. After you run a command, the bottom panel switches to command output typing your command. After you run a command, the bottom panel switches to
mode, but you can get back to the help text by hitting Ctrl-T or clicking on the command output mode, but you can get back to the help text by hitting Ctrl-T or
``Help`` tab. clicking on the ``Help`` tab.
How do DFHack in-game windows work? How do DFHack in-game windows work?
----------------------------------- -----------------------------------
@ -122,84 +130,88 @@ you type at the keyboard. Hit Esc or right click to close the window or cancel
the current action. You can click anywhere on the screen that is not a DFHack the current action. You can click anywhere on the screen that is not a 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. If no DFHack windows are focused, you can right click directly on a window focus. If no DFHack windows are focused, you can right click directly on a
to close it without left clicking to focus it first. window 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
game is unpaused, it can continue to run while a DFHack window is open. If configured the game is unpaused, it can continue to run while a DFHack window is open. If
to do so in `gui/control-panel`, tools will initially pause the game to let you configured to do so in `gui/control-panel`, tools will initially pause the game
focus on the task at hand, but you can unpause like normal if you want. You can to let you focus on the task at hand, but you can unpause like normal if you
also interact with the map, scrolling it with the keyboard or mouse and selecting want. You can also interact with the map, scrolling it with the keyboard or
units, buildings, and items. Some tools will intercept all mouse clicks to allow mouse and selecting units, buildings, and items. Some tools will intercept all
you to select regions on the map. When these tools have focus, you will not be able mouse clicks to allow you to select regions of the map. When these tools have
to use the mouse to interact with map elements or pause/unpause the game. Therefore, focus, you will not be able to use the mouse to interact with map elements or
these tools will pause the game when they open, regardless of your settings in pause/unpause the game. Therefore, these tools will pause the game when they
`gui/control-panel`. You can still unpause with the keyboard (spacebar by default), open, regardless of your settings in `gui/control-panel`. You can still unpause
though. with the keyboard (spacebar by default), though.
Where do I go next? Where do I go next?
------------------- -------------------
To recap: 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 clicking on
the mouse over the DFHack logo or by hitting Ctrl-Shift-C. the DFHack logo or by hitting Ctrl-Shift-C.
You can enable DFHack tools and configure settings with `gui/control-panel`, You can enable DFHack tools and configure settings with `gui/control-panel`,
which you can access directly with the Ctrl-Shift-E hotkey. which you can open from the DFHack logo or access directly with the
Ctrl-Shift-E hotkey.
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 menu list.
With those three interfaces, you have the complete DFHack tool suite at your With those three interfaces, 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 examples to get you started.
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
manager orders screen, you can see all the orders that have been created for you. manager orders screen, you can see all the orders that have been created for
Note that you could have imported the orders directly from this screen as well, you. Note that you could have imported the orders directly from this screen as
using the DFHack `overlay` widget at the bottom of the manager orders panel. well, using the DFHack `overlay` widget at the bottom of the manager orders
panel.
Next, try setting up `autochop` to automatically designate trees for chopping when
you get low on usable logs. Run `gui/control-panel` and select ``autochop`` in the Next, try setting up `autochop` to automatically designate trees for chopping
``Fort`` list. Click on the button to the left of the name or hit Enter to enable when you get low on usable logs. Run `gui/control-panel` and select
it. You can then click on the configure button (the gear icon) to launch ``autochop`` in the ``Fort`` list. Click on the button to the left of the name
`gui/autochop` if you'd like to customize its settings. If you have the extra or hit Enter to enable it. You can then click on the configure button (the gear
screen space, you can go ahead and set the `gui/autochop` window to minimal mode icon) to launch `gui/autochop` if you'd like to customize its settings. If you
(click on the hint near the upper right corner of the window or hit Alt-M) and have the extra screen space, you can go ahead and set the `gui/autochop` window
click on the map so the window loses keyboard focus. As you play the game, you can to minimal mode (click on the hint near the upper right corner of the window or
glance at the live status panel to check on your stocks of wood. hit Alt-M) and click on the map so the window loses keyboard focus. As you play
the game, you can glance at the live status panel to check on your stocks of
Finally, let's do some fort design copy-pasting. Go to some bedrooms that you have wood.
set up in your fort. Run `gui/blueprint`, set a name for your blueprint by
clicking on the name field (or hitting the 'n' hotkey), typing "rooms" (or whatever) Finally, let's do some fort design copy-pasting. Go to some bedrooms that you
and hitting Enter to set. Then draw a box around the target area by clicking with have set up in your fort. Run `gui/blueprint`, set a name for your blueprint by
the mouse. When you select the second corner, the blueprint will be saved to your clicking on the name field (or hitting the 'n' hotkey), typing "rooms" (or
``blueprints`` subfolder. whatever) and hitting Enter to set. Then draw a box around the target area by
clicking with the mouse. When you select the second corner, the blueprint will
Now open up `gui/quickfort`. You can search for the blueprint you just created by be saved to your ``dfhack-config/blueprints`` subfolder.
typing its name, but it should be up near the top already. If you copied a dug-out
area with furniture in it, your blueprint will have two labels: "/dig" and "/build". Now open up `gui/quickfort`. You can search for the blueprint you just created
Click on the "/dig" blueprint or select it with the keyboard arrow keys and hit Enter. by typing its name, but it should be up near the top already. If you copied a
You can rotate or flip the blueprint around if you need to with the transform hotkeys. dug-out area with furniture in it, your blueprint will have two labels: "/dig"
You'll see a preview of where the blueprint will be applied as you move the mouse and "/build". Click on the "/dig" blueprint or select it with the keyboard
cursor around the map. Red outlines mean that the blueprint may fail to fully apply arrow keys and hit Enter. You can rotate or flip the blueprint around if you
at that location, so be sure to choose a spot where all the preview tiles are shown need to with the transform hotkeys. You'll see a preview of where the blueprint
with green diamonds. Click the mouse or hit Enter to apply the blueprint and will be applied as you move the mouse cursor around the map. Red outlines mean
designate the tiles for digging. Your dwarves will come and dig it out as if you that the blueprint may fail to fully apply at that location, so be sure to
had designated the tiles yourself. choose a spot where all the preview tiles are shown with green diamonds. Click
the mouse or hit Enter to apply the blueprint and designate the tiles for
Once the area is dug out, run `gui/quickfort` again and select the "/build" blueprint digging. Your dwarves will come and dig it out as if you had designated the
this time. Apply the blueprint in the dug-out area, and your furniture will be tiles yourself.
designated. It's just that easy! Note that `quickfort` uses `buildingplan` to place
buildings, so you don't even need to have the relevant furniture or building Once the area is dug out, run `gui/quickfort` again and select your "/build"
materials in stock. The planned furniture/buildings will get built whenever you are blueprint this time. Hit `o` to generate manager orders for the required
able to produce the building materials. furniture. Apply the blueprint in the dug-out area, and your furniture will be
designated. It's just that easy! Note that `quickfort` uses `buildingplan` to
place buildings, so you don't even need to have the relevant furniture or
building materials in stock yet. The planned furniture/buildings will get built
whenever you are able to produce the building materials.
There are many, many more tools to explore. Have fun! There are many, many more tools to explore. Have fun!