dfhack/docs/guides/quickfort-library-guide.rst

.. _blueprint-library-guide:
.. _quickfort-library-guide:

Quickfort blueprint library
===========================

This guide contains a high-level overview of the blueprints available in the
:source:`quickfort blueprint library <data/blueprints>`.

Each file is hyperlinked to its online version so you can see exactly what the
blueprints do before you run them. Also, if you use `gui/quickfort`, you will
get a live preview of which tiles will be modified by the blueprint before you
apply it to your map.

Whole fort blueprint sets
-------------------------

These files contain the plans for entire fortresses. Each file has one or more
help sections that walk you through how to build the fort, step by step.

- :source:`library/dreamfort.csv <data/blueprints/dreamfort.csv>`
- :source:`library/quickfortress.csv <data/blueprints/quickfortress.csv>`

.. _dreamfort:

Dreamfort
~~~~~~~~~

Dreamfort is a fully functional, self-sustaining fortress with defenses,
farming, a complete set of workshops, self-managing quantum stockpiles, a grand
dining hall, hospital (werecreature-ready), library, temple, jail, fresh water
well system, guildhalls, noble suites, and bedrooms for hundreds of dwarves. It
also comes with manager work orders to automate basic fort needs, such as food,
booze, and item production. It can function by itself or as the core of a
larger, more ambitious fortress. Read the walkthrough by running
`gui/quickfort`, searching for ``dreamfort help``, and selecting the blueprints.

Dreamfort blueprints are available for easy viewing and copying `online
<https://drive.google.com/drive/folders/1dsmvnzbOKsyFS3DCj0F8ibSnMhVHEjdV>`__.

The online spreadsheets also include `embark profile suggestions
<https://docs.google.com/spreadsheets/d/15TDBebP8rBNvsFbezb9xuKPmGWNzv7j4XZWq1AsfCio/edit#gid=149144025>`__,
a complete `example embark profile
<https://docs.google.com/spreadsheets/d/15TDBebP8rBNvsFbezb9xuKPmGWNzv7j4XZWq1AsfCio/edit#gid=1727884387>`__,
and a convenient `checklist
<https://docs.google.com/spreadsheets/d/15TDBebP8rBNvsFbezb9xuKPmGWNzv7j4XZWq1AsfCio/edit#gid=1459509569>`__
that you can use to track your progress.

If you like, you can download a fully built Dreamfort-based fort from
:dffd:`dffd <15434>`, load it, and explore it interactively.

Here are annotated screenshots of the major Dreamfort levels (or click `here
<https://drive.google.com/drive/folders/1_gtMQAqa13zZjGkf3fiY3CNEuRpt_WF2>`__
for a slideshow).

Surface level
`````````````

.. image:: https://drive.google.com/uc?export=download&id=1dlu3nmwQszav-ZaTx-ac28wrcaYBQc_t
  :alt: Annotated screenshot of the dreamfort surface level
  :target: https://drive.google.com/file/d/1dlu3nmwQszav-ZaTx-ac28wrcaYBQc_t
  :align: center

Farming level
`````````````

.. image:: https://drive.google.com/uc?export=download&id=1vDaedLcgoexUdKREUz75ZXQi0ZSdwWwj
  :alt: Annotated screenshot of the dreamfort farming level
  :target: https://drive.google.com/file/d/1vDaedLcgoexUdKREUz75ZXQi0ZSdwWwj
  :align: center

Industry level
``````````````

.. image:: https://drive.google.com/uc?export=download&id=1c8YTHxTgJY5tUII-BOWdLhmDFAHwIOEs
  :alt: Annotated screenshot of the dreamfort industry level
  :target: https://drive.google.com/file/d/1c8YTHxTgJY5tUII-BOWdLhmDFAHwIOEs
  :align: center

Services levels (4 deep)
````````````````````````

.. image:: https://drive.google.com/uc?export=download&id=1RQMy_zYQWM5GN7-zjn6LoLWmnrJjkxPM
  :alt: Annotated screenshot of the dreamfort services level
  :target: https://drive.google.com/file/d/1RQMy_zYQWM5GN7-zjn6LoLWmnrJjkxPM
  :align: center

Services waterway:

.. image:: https://drive.google.com/uc?export=download&id=1SXknicNS13Dkq1A_8QLoK8OMxdolw-BY
  :alt: Annotated screenshot of the dreamfort waterway
  :target: https://drive.google.com/file/d/1SXknicNS13Dkq1A_8QLoK8OMxdolw-BY
  :align: center

**Example plumbing to fill cisterns**

If you are routing water to fill the cisterns, you can do it like this (1
z-level below the preceding screenshot)

.. image:: https://drive.google.com/uc?export=download&id=1paXqPJ-7h9_jG_eNXU1z5GGvR0J8C0uJ
  :alt: Annotated screenshot of an example aqueduct addition to the dreamfort cisterns
  :target: https://drive.google.com/file/d/1paXqPJ-7h9_jG_eNXU1z5GGvR0J8C0uJ
  :align: center

Cistern drain (keep open while you're digging out the aquifer tap):

.. image:: https://drive.google.com/uc?export=download&id=1SwSluJcN_kOrCYPdcFOfJ13wEDvZGcJe
  :alt: Annotated screenshot of an example drainage addition to the dreamfort cisterns
  :target: https://drive.google.com/file/d/1SwSluJcN_kOrCYPdcFOfJ13wEDvZGcJe
  :align: center

Guildhall level
```````````````

.. image:: https://drive.google.com/uc?export=download&id=1mt66QOkfBqFLtw6AJKU6GNYmhB72XSJG
  :alt: Annotated screenshot of the dreamfort guildhall level
  :target: https://drive.google.com/file/d/1mt66QOkfBqFLtw6AJKU6GNYmhB72XSJG
  :align: center

Noble suites
````````````

.. image:: https://drive.google.com/uc?export=download&id=16XRb1w5zFoyVq2LBMx_aCwOyjFq7GULc
  :alt: Annotated screenshot of the dreamfort noble suites
  :target: https://drive.google.com/file/d/16XRb1w5zFoyVq2LBMx_aCwOyjFq7GULc
  :align: center

Apartments
``````````

.. image:: https://drive.google.com/uc?export=download&id=16-NXlodLIQjeZUMSmsWRafeytwU2dXQo
  :alt: Annotated screenshot of the dreamfort apartments
  :target: https://drive.google.com/file/d/16-NXlodLIQjeZUMSmsWRafeytwU2dXQo
  :align: center

Crypt
`````

.. image:: https://drive.google.com/uc?export=download&id=16iT_ho7BIRPD_eofuxdlVQ4FunR1Li23
  :alt: Annotated screenshot of the dreamfort crypt
  :target: https://drive.google.com/file/d/16iT_ho7BIRPD_eofuxdlVQ4FunR1Li23
  :align: center

The Quick Fortress
~~~~~~~~~~~~~~~~~~

The Quick Fortress is an updated version of the example fortress that came with
`Python Quickfort 2.0 <https://github.com/joelpt/quickfort>`__ (the utility that
inspired DFHack quickfort). While it is not a complete fortress by
itself, it is much simpler than Dreamfort and is good for a first introduction
to `quickfort` blueprints. Read its walkthrough with ``quickfort run
library/quickfortress.csv`` or view the blueprints `online
<https://docs.google.com/spreadsheets/d/1WuLYZBM6S2nt-XsPS30kpDnngpOQCuIdlw4zjrcITdY>`__.

Layout helpers
--------------

These files simply draw diagonal marker-mode lines starting from the cursor.
They are especially useful for finding the center of the map when you are
planning your fortress. Once you are done using them for alignment, use
``quickfort undo`` at the same cursor position to make them disappear. Since
these ``#dig`` blueprints can only mark undug wall tiles for mining, they are
best used underground. They won't do much on the surface, where there aren't
many walls.

- :source:`library/layout-helpers/mark_up_left.csv <data/blueprints/layout-helpers/mark_up_left.csv>`
- :source:`library/layout-helpers/mark_up_right.csv <data/blueprints/layout-helpers/mark_up_right.csv>`
- :source:`library/layout-helpers/mark_down_right.csv <data/blueprints/layout-helpers/mark_down_right.csv>`
- :source:`library/layout-helpers/mark_down_left.csv <data/blueprints/layout-helpers/mark_down_left.csv>`

Bedrooms
--------

These are popular bedroom layouts from the :wiki:`Bedroom design` page on the
wiki. Each file has blueprints to dig the rooms, zone them as bedrooms, and
build the furniture.

- :source:`library/bedrooms/48-4-Raynard_Whirlpool_Housing.csv <data/blueprints/bedrooms/48-4-Raynard_Whirlpool_Housing.csv>`
- :source:`library/bedrooms/95-9-Hactar1_3_Branch_Tree.csv <data/blueprints/bedrooms/95-9-Hactar1_3_Branch_Tree.csv>`
- :source:`library/bedrooms/28-3-Modified_Windmill_Villas.csv <data/blueprints/bedrooms/28-3-Modified_Windmill_Villas.csv>`

Tombs
-----

These blueprints have burial plot layouts for fortress that expect a lot of
casualties.

- :source:`library/tombs/Mini_Saracen.csv <data/blueprints/tombs/Mini_Saracen.csv>`
- :source:`library/tombs/The_Saracen_Crypts.csv <data/blueprints/tombs/The_Saracen_Crypts.csv>`

Exploratory mining
------------------

Several mining patterns to choose from when searching for gems or ores. The
patterns can be repeated up or down z-levels (via `gui/quickfort`\'s
:kbd:`r`\epeat functionality) for exploring through the depths.

- :source:`library/exploratory-mining/tunnels.csv <data/blueprints/exploratory-mining/tunnels.csv>`
- :source:`library/exploratory-mining/vertical-mineshafts.csv <data/blueprints/exploratory-mining/vertical-mineshafts.csv>`
- :source:`library/exploratory-mining/connected-mineshafts.csv <data/blueprints/exploratory-mining/connected-mineshafts.csv>`

Miscellaneous
-------------

Extra blueprints that are useful in specific situations.

- :source:`library/aquifer_tap.csv <data/blueprints/aquifer_tap.csv>`
- :source:`library/embark.csv <data/blueprints/embark.csv>`
- :source:`library/pump_stack.csv <data/blueprints/pump_stack.csv>`

Light aquifer tap
~~~~~~~~~~~~~~~~~

The aquifer tap helps you create a safe, everlasting source of fresh water from
a light aquifer. See the step-by-step guide, including information on how to
create a drainage system so your dwarves don't drown when digging the tap, by
running the ``library/aquifer_tap.csv`` ``/help`` blueprint.

You can see how to nullify the water pressure (so you don't flood your fort) in
the `Dreamfort screenshot above <Services levels (4 deep)>`_.

The blueprint spreadsheet is also available
`online <https://docs.google.com/spreadsheets/d/1kwuCipF9FYAHNP9C_XlMpqVseaPu4SmL9YLUSQkbW4s/edit#gid=611877584>`__.

.. image:: https://drive.google.com/uc?export=download&id=11bzEF615QTyTNbN8A8M4UYi1YWtqPuCf
  :alt: Annotated screenshot of the aquifer tap
  :target: https://drive.google.com/file/d/11bzEF615QTyTNbN8A8M4UYi1YWtqPuCf
  :align: center

Post-embark
~~~~~~~~~~~

The embark blueprints are useful directly after embark. It contains a ``#build``
blueprint that builds important starting workshops (mason, carpenter, mechanic,
and craftsdwarf) and a ``#place`` blueprint that lays down a pattern of useful
starting stockpiles.

Pump stack
~~~~~~~~~~

The pump stack blueprints help you move water and magma up to more convenient
locations in your fort. See the step-by-step guide for using it by running the
``library/pump_stack.csv`` ``/help`` blueprint.

The blueprint spreadsheet is also available
`online <https://docs.google.com/spreadsheets/d/1TP2n-W-O9f30Dtl6yoTcn6yczWQRu11iM7U6TEE9634/edit#gid=0>`__.