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

update Quickstart guide

develop
Myk Taylor 2023-01-16 00:15:17 -08:00
parent e7a30a9af8
commit 6b039aac9d
No known key found for this signature in database
1 changed files with 72 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
docs/Quickstart.rst
Unescape Escape View File

@ -13,11 +13,11 @@ What is DFHack?
DFHack is a framework for Dwarf Fortress that provides a unified, cross-platform DFHack is a framework for Dwarf Fortress that provides a unified, cross-platform
environment that enables mods and tools to significantly extend the game. The environment that enables mods and tools to significantly extend the game. The
default DFHack distribution contains a variety of tools, including bugfixes, default DFHack distribution contains a wide variety of tools, including bugfixes,
interface improvements, automation agents, design blueprints, modding tools, and interface improvements, automation agents, design blueprints, modding building
more. Third-party tools (e.g. mods downloaded from Steam Workshop or the forums) blocks, and more. Third-party tools (e.g. mods downloaded from Steam Workshop or
can also seamlessly integrate with the DFHack framework and extend the game far the forums) can also seamlessly integrate with the DFHack framework and extend
beyond what can be done by just modding the raws. the game far beyond what can be done by just modding the raws.
DFHack's mission is to provide tools and interfaces for players and modders to: DFHack's mission is to provide tools and interfaces for players and modders to:
@ -25,7 +25,7 @@ DFHack's mission is to provide tools and interfaces for players and modders to:
- reduce the impact of game bugs - reduce the impact of game bugs
- give the player more agency and control over the game - give the player more agency and control over the game
- provide alternatives to toilsome or frustrating aspects of gameplay - provide alternatives to toilsome or frustrating aspects of gameplay
- overall, make the game more fun - **make the game more fun**
What can I do with DFHack tools? What can I do with DFHack tools?
-------------------------------- --------------------------------
@ -43,7 +43,7 @@ Here are some common tasks people use DFHack tools to accomplish:
- Promote time-sensitive job types (e.g. food hauling) so they are done - Promote time-sensitive job types (e.g. food hauling) so they are done
expediently expediently
- 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 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 items on the map after a messy siege.
@ -51,15 +51,15 @@ to claim all 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.
Enableable tools that affect a fort save their state with the fort and will Tools that are enabled in the context of a fort will save their state with that
remember that they are enabled the next time you load your save. fort, and the will remember that they are enabled the next time you load your save.
And still other 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 configured with the `gui/overlay` tool. 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?
------------------------------------------- -------------------------------------------
@ -70,26 +70,25 @@ 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` tool.
When you hover the mouse over the logo (or hit the :kbd:`Ctrl`:kbd:`Shift`:kbd:`C` When you hover the mouse over the logo (or hit the Ctrl-Shift-C keyboard shortcut)
keyboard shortcut) a list of DFHack tools relevant to the current context comes up. a list of DFHack tools relevant to the current context comes up. For example, when
For example, when you have a unit selected, the hotspot will show a list of tools you have a unit selected, the hotspot will show a list of tools that inspect
that inspect units, allow you to edit them, or maybe even teleport them. Next to units, allow you to edit them, or maybe even teleport them. Next to each tool,
each tool, you'll see the global hotkey you can hit to invoke the command without you'll see the global hotkey you can hit to invoke the command without even
even opening the hover list. opening the hover list.
You can run any DFHack tool from `gui/launcher`, which is always listed first in You can run any DFHack tool from `gui/launcher`, which is always listed first in
the hover list. You can also bring up the launcher by tapping the backtick key the hover list. You can also bring up the launcher by tapping the backtick key
(\`) or hitting :kbd:`Ctrl`:kbd:`Shift`:kbd:`D`. In the launcher, you can quickly (\`) or hitting Ctrl-Shift-D. In the launcher, you can quickly autocomplete any
autocomplete any command name by selecting it in the list on the right side of command name by selecting it in the list on the right side of the window.
the window. Commands are ordered by how often you run them, so your favorite Commands are ordered by how often you run them, so your favorite commands will
commands will always be on top. You can also pull full commandlines out of your always be on top. You can also pull full commandlines out of your history with
history with :kbd:`Alt`:kbd:`S` (or by clicking on the "history search" hotkey hint). Alt-S (or by clicking on the "history search" hotkey hint).
Once you have typed (or autocompleted, or searched for) a command name, other Once you have typed (or autocompleted, or searched for) a command, other commands
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 autocomplete list.
Scanning through the related tools is a great way to learn about new tools that Scanning through that list is a great way to learn about new tools that you might
you might find useful. You can also see how commands are grouped by running the find useful. You can also see how commands are grouped by running the `tags` command.
`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
@ -100,7 +99,7 @@ How do DFHack in-game windows work?
Many DFHack tools have graphical interfaces that appear in-game. You can tell Many DFHack tools have graphical interfaces that appear in-game. You can tell
which windows belong to DFHack tools because they will have the word "DFHack" which windows belong to DFHack tools because they will have the word "DFHack"
printed across their bottom frame. DFHack provides a custom windowing system printed across their bottom frame edge. DFHack provides a custom windowing system
that gives the player a lot of control over where the windows appear and whether that gives the player a lot of control over where the windows appear and whether
they capture keyboard and mouse input. they capture keyboard and mouse input.
@ -108,26 +107,28 @@ The DFHack windowing system allows you to use DFHack tools without interrupting
the game. That is, if the game is unpaused, it will continue to run while a the game. That is, if the game is unpaused, it will continue to run while a
DFHack window is open. You can also interact with the map, scrolling it with the DFHack window is open. You can also interact with the map, scrolling it with the
keyboard or mouse and selecting units, buildings, and items. Some tools will keyboard or mouse and selecting units, buildings, and items. Some tools will
capture all keyboard input, such as tools with editable text fields, and some will
force-pause the game if it makes sense to, like `gui/quickfort`, since you cannot force-pause the game if it makes sense to, like `gui/quickfort`, since you cannot
interact with the map normally while placing a blueprint. interact with the map normally while trying to apply a blueprint.
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 be reasonably resized). (if the tool window has components that can reasonably be resized).
DFHack windows close with a right mouse click or keyboard :kbd:`Esc`, but if you DFHack windows close with a right mouse click or keyboard Esc, but if you
want to keep a DFHack tool open while you interact with the game, you can click the want to keep a DFHack tool open while you interact with the game, you can click the
pin in the upper right corner of the DFHack window or hit :kbd:`Alt`:kbd:`L` so pin in the upper right corner of the DFHack window or hit Alt-L so
that the pin turns green. The DFHack window will then ignore right clicks and that the pin turns green. The DFHack window will then ignore right clicks and
:kbd:`Esc` key presses that would otherwise close the window. This is especially Esc key presses that would otherwise close the window. This is especially
useful for the configuration tool windows for the automation tools. For example, useful for the configuration tool windows for the automation tools. For example,
you can pin the `gui/autochop` window and let it sit there monitoring your you can pin the `gui/autochop` window, set it to minimal mode, and let it sit
logging industry as you play, using it as a live status window. Note that you can there monitoring your logging industry as you play, using it as a live status
still right click *on* the DFHack tool window to close it, even when it is pinned. window. Note that you can still right click *on* the DFHack tool window to close
it, even when it is pinned.
You can have multiple DFHack tool windows on the screen at the same time. The You can have multiple DFHack tool windows on the screen at the same time. The
one that is receiving keyboard input has a highlighted title bar and will appear one that is receiving keyboard input has a highlighted title bar and will appear
over other windows if dragged over them. Clicking on a DFHack window that is not over other windows if dragged across them. Clicking on a DFHack window that is not
currently active will bring it to the foreground and make it the active window. currently active will bring it to the foreground and make it the active window.
Where do I go next? Where do I go next?
@ -136,11 +137,11 @@ 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 hovering
the mouse over the DFHack logo or by hitting :kbd:`Ctrl`:kbd:`Shift`:kbd:`C`. the mouse over the DFHack logo or by hitting Ctrl-Shift-C.
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 :kbd:`Ctrl`:kbd:`Shift`:kbd:`D`, and help text by hitting backtick (\`) or Ctrl-Shift-D, or, of course, by
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` You can list and start tools that run in the background with the `enable`
command. command.
@ -149,7 +150,7 @@ You can configure screen overlays with the `gui/overlay` tool.
With those four tools, you have the complete DFHack tool suite at your 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 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
@ -160,13 +161,32 @@ You can enable it from the GUI, so you don't need to run `enable autochop <enabl
directly. You can set a target number of logs, and autochop will manage directly. You can set a target number of logs, and autochop will manage
your logging industry for you. You can control where your woodsdwarves go to your logging industry for you. You can control where your woodsdwarves go to
cut down trees by setting up burrows and configuring autochop to only cut in cut down trees by setting up burrows and configuring autochop to only cut in
those burrows. those burrows. If you have the extra screen space, go ahead and click the pin so
it turns green and set the `gui/autochop` window to minimal mode (click on the
Finally, let's set up a water supply for your fort with `gui/quickfort`. Launching hint near the upper right corner of the window or hit Alt-M). As you play the game,
`gui/quickfort` will give you a list of blueprints you can load. Type in ``aquifer_tap`` you can glance at it to check on your stocks of wood.
to filter for just those blueprints. Select the ``aquifer_tap -n /help`` blueprint
to see the instructions for how to build an aquifer tap. Then, go back and load the Finally, let's do some fort design copy-pasting. Go to some bedrooms that you have
``aquifer_tap -n /dig`` blueprint, find some space in a light aquifer layer, and set up in your fort. Run `gui/blueprint`, set a name for your blueprint by
apply the blueprint there. It was that easy! clicking on the name field (or hitting the 'n' hotkey), typing "rooms" (or whatever)
and hitting Enter to set. Then draw a box around the target area by clicking with
There are many more tools to explore. Have fun! the mouse. When you select the second corner, the blueprint will be saved to your
``blueprints`` subfolder.
Now open up `gui/quickfort`. You can search for the blueprint you just created by
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".
Click on the "/dig" blueprint or select it with the keyboard arrow keys and hit Enter.
You can rotate or flip the blueprint around if you need to with the transform hotkeys.
You'll see a preview of where the blueprint will be applied as you move the mouse
cursor around the map. Red outlines mean that the blueprint may fail to fully apply
at that location, so be sure to 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 digging. Your dwarves will come and dig it out as if you
had designated the tiles yourself.
Once the area is dug out, run `gui/quickfort` again and select the "/build" blueprint
this time. Apply the blueprint in the dug-out area, and your furniture will be
designated. It's just that easy!
There are many, many more tools to explore. Have fun!