diff --git a/docs/Quickstart.rst b/docs/Quickstart.rst new file mode 100644 index 000000000..c61658f35 --- /dev/null +++ b/docs/Quickstart.rst @@ -0,0 +1,167 @@ +.. _quickstart: + +Quickstart guide +================ + +Welcome to DFHack! This guide will help get you oriented with the DFHack system +and teach you how to find and use the tools productively. If you're reading this +in `dfhack-quickstart-guide`, hit the right arrow key or click on the hotkey +hint in the lower right corner of the window to go to the next page. + +What is DFHack? +--------------- + +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 +default DFHack distribution contains a variety of tools, including bugfixes, +interface improvements, automation agents, design blueprints, modding tools, and +more. Third-party tools (e.g. mods downloaded from Steam Workshop or the forums) +can also seamlessly integrate with the DFHack framework and extend 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: +- expand the bounds of what is possible in Dwarf Fortress +- reduce the impact of game bugs +- give the player more agency and control over the game +- provide alternatives to toilsome or frustrating aspects of gameplay +- overall, make the game more fun + +What can I do with DFHack tools? +-------------------------------- + +DFHack has been around for a long time -- almost as long as Dwarf Fortress +itself. Many of the game's rough edges have been smoothed with DFHack tools. +Here are some common tasks people use DFHack tools to accomplish: + +- Automatically chop trees when log stocks are low +- Record fortress layouts in blueprint files and later play them back in + different forts +- Import and export lists of manager orders +- Clean contaminants from map squares that dwarves can't reach +- Automatically butcher excess livestock so you don't become overrun with + animals +- Promote time-sensitive job types (e.g. food hauling) so they are done + expediently +- Quickly scan the map for visible ores of specific types so you can focus + your mining + +Some tools are one-shot commands. For example, you can run `unforbid all ` +to claim all items on the map after a messy siege. + +Other tools must be `enabled ` and then they will run in the background. +For example, `enable seedwatch ` will start monitoring your stocks of +seeds and preventing your chefs from cooking seeds that you need for planting. +Enableable tools that affect a fort save their state with the fort and will +remember that they are enabled the next time you load your save. + +Other tools add information to the screen or provide new integrated functionality +via the DFHack `overlay` framework. For example, the `unsuspend` 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 suspended (and +will use different markers to tell you whether this is a problem). These overlays +can be configured with the `gui/overlay` tool. + +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. + +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 +with the `gui/overlay` tool. + +When you hover the mouse over the logo (or hit the :kbd:`Ctrl`:kbd:`Shift`:kbd:`C` +keyboard shortcut) 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 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 opening the hover list. + +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 +(\`) or hitting :kbd:`Ctrl`:kbd:`Shift`:kbd:`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 :kbd:`Alt`:kbd:`S` (or by clicking on the "history search" hotkey hint). + +Once you have typed (or autocompleted, or searched for) a command name, other +commands 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 +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, +allowing you to refer to the usage documentation and examples when you are typing +your command. + +How do DFHack in-game windows work? +----------------------------------- + +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" +printed across their bottom frame. DFHack provides a custom windowing system +that gives the player a lot of control over where the windows appear and whether +they capture keyboard and mouse input. + +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 +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 +force-pause the game if it make sense to. + +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 +(if the tool window has components that can be reasonably resized). DFHack windows +close with :kbd:`Esc` or a right mouse click, but if you want to keep a DFHack +tool open while you interact with the game, you can hit :kbd:`Alt`:kbd:`L` or +click the pin in the upper right corner of the DFHack window so that it turns +green. The DFHack window will then ignore :kbd:`Esc` button presses and right +clicks that would otherwise close the 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 +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 +currently active will bring it to the foreground and make it the active window. + +Where do I go next? +------------------- + +To recap: + +You can get to popular, relevant tools for the current context by hovering +the mouse over DFHack logo or by hitting :kbd:`Ctrl`:kbd:`Shift`:kbd:`C`. + +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`, +or, of course, by running it from the logo hover list. + +You can list and start tools that run in the background with the `enable` +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. +You can run them from the launcher. + +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 +mangager orders screen, you can see all the orders that have been created for you. + +Next, try setting up `autochop` by running the GUI configuration `gui/autochop`. +You can enable it from the GUI, so you don't need to run `enable autochop ` +directly. You can set a target number of logs, and let autochop will manage +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 +those burrows. + +Finally, let's set up a water supply for your fort with `gui/quickfort`. Launching +`gui/quickfort` will give you a list of blueprints you can load. Type in ``aquifer_tap`` +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 +``aquifer_tap -n /dig`` blueprint, find some space in a light aquifer layer, and +apply the blueprint there. It was that easy! + +There are many more tools to explore. Have fun! diff --git a/index.rst b/index.rst index af0f76052..2792e2d9a 100644 --- a/index.rst +++ b/index.rst @@ -15,6 +15,7 @@ Quick Links * `Downloads `_ * `Installation guide ` +* `quickstart` * `Getting help ` * :source:`Source code <>` (**important:** read `compile` before attempting to build from source.) @@ -26,6 +27,7 @@ User Manual :maxdepth: 2 /docs/Introduction + /docs/Quickstart /docs/Installing /docs/Core /docs/Tools