Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[myk]

Update: quickfort is now part of the official DFHack release!

The docs are available on the DFHack docs server:

• quickfort command reference
• quickfort blueprint creation guide
• quickfort keystroke alias guide
• quickfort blueprint library

This thread has also expanded from just quickfort development to support of the whole quickfort ecosystem:

• quickfort: blueprint application
• buildingplan: building materials filtering and management
• blueprint: blueprint generation from in-game maps
• blueprint library: the curated library of blueprints distributed with DFHack, including the whole-fort Dreamfort blueprint set

Original first post:
I'm implementing quickfort inside of DFHack. Why would I do this? Well, a couple reasons:

• The original Quickfort is unmaintained, and is based on python2, which is slowly disappearing from the internet's collective consciousness
• DFHack can apply blueprints faster, can gracefully recover from errors, and can intelligently select building materials based on available items and player preferences
• There is an opportunity to integrate with other DFHack functionality, like generating workshop orders to build the items required for a blueprint

For those who are unfamiliar with quickfort/qfconvert, the idea is that you record the keys you want to play back in a spreadsheet. Quickfort moves the cursor to the position that corresponds to the cell in the spreadsheet and plays back the keystrokes. Quickfort runs in one of four modes: dig, build, place, and query. Dig digs, build builds, place places stockpiles, and query changes building/stockpile settings. The mode is determined by a marker in the upper-left cell of the spreadsheet. You can see an example of sheets in each of the four modes here.

What about digfort and fortplan?

Yeah, they work great, actually, but digfort only does dig mode and fortplan only handles build mode, and only the buildings that buildingplan supports (mostly furniture). I plan to build on what they already provide, but I'd really like to see support for all buildings and constructions, stockpiles, query mode, the full set.

So what's your plan?

I wrote a design doc, if you're into that sort of thing, but here's a quick rundown of what I have in mind:

Spoiler: Script usage examples (click to show/hide)

[/list][/list]

Code: [Select]

Usage:
  quickfort list [-l]
  quickfort [run|orders|undo] <list number>
  quickfort [run|orders|undo] <filename> [-s <sheet_number>]

There will also be some configuration files where you can define custom aliases for query blueprints (like defining the name "ironores" to mean the keystrokes "s{Down 5}deb{Right}{Down}{Right}&{Down}&{Down}&{Down}&{Down 5}&^") and material preferences for orders and building (like forbidding constructions from being made out of precious coal bars or potash). Once all functions are supported, we can also include a library of useful blueprints to be distributed with DFHack.

There would be both a commandline interface at the DFHack# prompt and a GUI interface that will let you scroll through the blueprints and select one to apply.

"quickfort list" prints a list of plans based on the files in the "blueprints" directory, annotated with information from their initial comment (and maybe the sheet name from xlsx files). If -l is specified, the output includes blueprints from the library directory. For example:

Code: [Select]

[DFHack]# quickfort list
1) farming.xlsx -s1 (dig)
Last Edit: August 21, 2020, 12:26:39 am
+ Attachments and other options
shortcuts: hit alt+s to submit/post or alt+p to preview

 


SMF 2.0.13 | SMF © 2016, Simple Machines
XH
2) farming.xlsx -s2 (build: workshops)
3) farming.xlsx -s3 (build: furniture)
4) farming.xlsx -s4 (place)
5) farming.xlsx -s5 (query)
6) rooms.xlsx -s1 (dig: dining hall)
7) rooms.xlsx -s2 (build: dining hall)
8) surface-dig.csv (dig: clear trees)
9) surface_walls-build.csv (build)
Skipping 57 blueprints in the library subdirectory. Use quickfort list -l to include them.
"quickfort run" and "quickfort orders" can take either the number from the list command or the full params:

Code: [Select]

[DFHack]# quickfort run surface-dig.csv
Applied surface-dig.csv (dig: clear trees)

[DFHack]# quickfort orders 7
Reading material preferences from dfhack-config/quickfort/material_prefs
Ordered 1 rock block
Ordered 16 rock thrones
Ordered 16 rock tables
Ordered 4 rock coffers
Ordered 2 rock cabinets
Ordered 36 rock statues
Generated 6 orders for rooms.xlsx -s2 (build: dining hall)

[DFHack]# quickfort run 7
Reading material preferences from dfhack-config/quickfort/material_prefs
Used:
  2 chert blocks
  16 thrones (11 chert, 5 microcline)
  16 tables (10 chert, 6 gabbro)
  4 chert coffers
  2 microcline cabinets
  36 statues (9 chert, 10 microcline, 4 gabbro, 13 orthoclase)
Applied rooms.xlsx -s2 (build: dining hall)

[DFHack]# quickfort run farming.xlsx -s5
Reading aliases from: dfhack-config/quickfort/aliases
Reading aliases from: blueprints/rooms.xlsx sheet: Aliases
Applied farming.xlsx -s5 (query)
"quickfort undo" will undo the specified blueprint, removing placed constructions and stockpiles, and clearing tiles marked for digging. It might be too difficult to undo query blueprints, though.

Code: [Select]

[DFHack]# quickfort undo 7
Canceled construction for:
  2 workshops
  16 thrones
  16 tables
  4 coffers
  2 cabinets
  34 statues
Scheduled for removal:
  2 statues
Undo complete for rooms.xlsx -s2 (build: dining hall)

What are your thoughts? How many quickfort users do we have out there who would appreciate something like this? What other features would you like to see? What are the most annoying manual steps you have to take that could be automated by this project?

Here are the milestones I'm using to track my progress:
Done

• Plan is approved by DFHack core devs (@lethosor)
• Forum thread started for public discussions and progress reports (this one)
• Blueprint plugin saves files to blueprints/ dir (PR#1607) -- quickfort will read blueprints from this same directory
• Interface skeletons are implemented (PR#1609, PR#159)
• Settings can be set (PR#163)
• Blueprints can be listed (PR#164)
• Blueprints can be tokenized (PR#165)
• Dig-mode blueprints can be applied (PR#167)
• Place-mode blueprints can be applied (PR#168)
• Build-mode blueprints can be applied (PR#169)
• Query-mode blueprints can be applied (PR#171)
• Stockpile settings are initialized (PR#172)
• Documentation (PR#1617)
• Curated library of blueprint files is included with DFHack (PR#1625)
• Xlsx dependencies are included in dfhack build/release (PR#1620)
• Can read from xlsx files (PR#177)
• Basic buildingplan integration (PR#1622, PR#184)
• Orders can be generated from build-mode blueprints (PR#185)
• Multi-blueprint files/sheets (PR#185)
• Meta blueprints (PR#185)
• Zone mode (PR#185)
• GUI (PR#185)

All done! I have lots of ideas of where to go from here, but I'd like to see the script get some real usage first so we can work out the bugs.

[clinodev]

I'm really glad to see this project!

As one of the /r/dwarffortress mods, I very regularly see and field questions about problems with quickfort, and while I've been recommending the current DFhack replacements, not everyone has had great luck with those either. I tried to copy and duplicate one of my own mutti-level structures recently (mining only,) with them, and it was a mess. Perhaps it was an operator error, or the components didn't go together the way I hoped; I'm not sure.

I am hopeful a single command / single source solution could solve a lot of problems, and if it reads the many existing community blueprints, that would be excellent!

[myk]

Yes, compatibility with current blueprints is definitely a priority. I'd hate to lose all the great work that's already out there!

I think the feature I'm looking forward to most in this project is materials control. I'm just so tired of forbidding bars of ash and charcoal every time I want to apply a build blueprint!

I'm curious - what are the common problems people have with quickfort?

[danaris]

Very glad to see you picking this up, after I had to leave it unfinished five years ago!

I don't currently have time for much Dwarf Fortress in my life, but if I did, I would definitely still want this tool, and I'm happy that soon it will (hopefully!) be available to those who can benefit from it.

[clinodev]

myk quickfort notes

Awkwardly, we remove the sorts of posts you'd probably like to see, but I'll copy a recent representative one  I can still view.

>Hey everyone, I got some good help on credit last time with an issue I had, so here we go again.

>I'm trying out quickfort as it came with the starter pack I downloaded, and I'm finding that the digs are coming out weird. It seems to be doing fine, and then all of a sudden at around 75% or so it starts doing a bunch of weird stuff, then it says its done. I've attached images of this that show the issue very clearly, but I've tested it on a bunch of blueprints.

>Thanks for the help

>*should also point out that it tends to designate stuff that is outside of the original footprint that was designated with alt-v.

>

>

>EDIT: I've done some testing, and I think that it might be relevant that it fails in the same way every time.


This is pretty much my post 0.44.x experience as well. I had a similar experience recently trying to use the DFhack equivalent tools, unfortunately, but I haven't followed up.

[myk]

Problems with rendering dig plans should certainly be solved. Quickfort applies blueprints by simulating keystrokes, which is not exactly foolproof. Keystrokes can get lost, and cursor positions can shift when the screen has to scroll and the mousequery plugin's edge scrolling feature is enabled.

This particular problem, though, is probably already solved with DFHack's digfort, which applies dig blueprints via DFHack's internal APIs. I plan to absorb its functionality into the new quickfort script.

[myk]

Ok, I wrote a first draft of the help text (which will appear in https://docs.dfhack.org/en/stable/docs/Scripts.html). I'd appreciate comments on whether everything is clear -- especially on whether it would be clear to someone who had never heard of quickfort before! The formatting and hyperlinks get lost when I paste it in the forums like this, but you can see the markup source at https://github.com/myk002/scripts/blob/quickfort_skeleton/quickfort.lua

quickfort
Processes Quickfort-style blueprint files. This is a pre-release – not all features are implemented yet.

Quickfort blueprints record what you want at each map coordinate in a spreadsheet, storing the keys in a spreadsheet cell that you would press to make something happen at that spot on the DF map. Quickfort runs in one of four modes: dig, build, place, or query. dig designates tiles for digging, build builds buildings and constructions, place places stockpiles, and query changes building or stockpile settings. The mode is determined by a marker in the upper-left cell of the spreadsheet (e.g.: #dig in cell A1).

You can create these blueprints by hand or by using any spreadsheet application, saving them as .xlsx or .csv files. You can also build your plan “for real” in Dwarf Fortress, and then export your map using the DFHack blueprint plugin for later replay in a different fort. Blueprint files should go in the blueprints subfolder in the main DF folder.

You can read more about how to create blueprint files in the blueprints/README.txt file, and there are ready-to-use examples of blueprints in each of the four modes in the blueprints/library folder.

Usage:

quickfort set [<key> <value>]
Allows you to modify the active quickfort configuration. Just run quickfort set to show current settings. See the Configuration section below for available keys and values.

quickfort list [-l]
Lists blueprints in the blueprints folder. Blueprints are .csv files or sheets within .xlsx files that contain a #<mode> comment in the upper-left cell. By default, blueprints in the blueprints/library/ subfolder are not included. Specify -l to include library blueprints.

quickfort <command> <list_num>
Applies the blueprint with the number from the list command.

quickfort <command> <filename> [-s <sheet_num>]
Applies the blueprint from the named file. If it is an .xlsx file, the -s parameter is required to identify the sheet number (the first sheet is -s 1).

<command> can be one of:

run
applies the blueprint at your current active cursor position.

orders
uses the manager interface to queue up orders for the specified build-mode blueprint.

undo
applies the inverse of the specified blueprint, depending on its type. Dig tiles are undesignated, buildings are canceled or removed (depending on their construction status), and stockpiles are removed. No effect for query blueprints.

Configuration:

The quickfort script reads its startup configuration from the dfhack-config/quickfort/quickfort.txt file, which you can customize. The following settings may be dynamically modified by the quickfort set command (note that settings changed with the quickfort set command will not change the configuration stored in the file):

blueprints-dir (default: ‘blueprints’)
Can be set to an absolute or relative path. If set to a relative path, resolves to a directory under the DF folder.

force-marker-mode (default: ‘false’)
Set to “true” or “false”. If true, will designate dig blueprints in marker mode. If false, only cells with dig codes prefixed with m will be designated in marker mode.

interactive-build (default: ‘false’)
Allows you to manually select building materials for each building/construction when running (or creating orders for) build blueprints. Materials in selection dialogs are ordered according to preferences in materials.txt (see below). If false, will only prompt for materials that have :labels. See original Quickfort documentation for details.

There are also two other configuration files in the dfhack-config/quickfort folder: aliases.txt and materials.txt. aliases.txt defines keycode shortcuts for query blueprints, and materials.txt defines forbidden materials and material preferences for build blueprints. The formats for these files are described in the files themselves.

[myk]

Skeleton PRs are up as PR#1609 and PR#159!

[myk]

I've completed a few milestones beyond what I've started PRs for -- I'm waiting for the current PRs to get reviewed and merged before I start more PRs (I don't want to overwhelm the dev team with review requests!). Specifically, I just finished implementing dig mode, and I could use some help with test material.

For those of you who have made blueprints, could you send them to me? I'd like to make sure I've tested "real" blueprints and can handle all the variations there are in style and formatting.

The DFHack quickfort plugin will have a few capabilities beyond digfort or the original quickfort. the new quickfort script:

• is FAST (hundreds of thousands of tiles designated in a few seconds)
• works correctly even if some blueprint tiles are outside the map area
• handles hidden tiles appropriately
• handles area specifications like d(10x5)
• handles track carving, including overlapping/crossing track segments
• differentiates between chopping trees, gathering plants, and digging walls so only the intended tiles are designated
• gives you nifty statistics about what was done

The new script depends on some library functionality in PR1609, but once that gets in, people who are interested in beta testing can try it out.

[myk]

In order to keep the new quickfort separate from the release while it's under initial development, lethosor has created a separate branch that I'm merging into. We'll merge it into master once it's implemented enough/stable enough, but beta testers are welcome to snag it from that branch in the meantime!

In other news, I've implemented place blueprints except for one last detail. The fun part about place blueprints was implementing a "flood fill" algorithm that figures out the boundaries of an arbitrarily-shaped stockpile.  Now you can have stockpiles of any shape, as long as it's connected horizontally or vertically to another stockpile tile, and as long as the whole thing fits within the Dwarf Fortress stockpile limit of 31x31 tiles. For example:

Code: [Select]

#place
 ,a, , , ,a,a
a,a, , , , ,a
a,a,a, , , ,a
a,a,a,a,a,a,a
would create a valid, though oddly shaped, animal stockpile.

The last bit of place to implement is enabling the correct stockpile category based on the type of stockpile in the blueprint. The code for this is not straightforward, and it looks like I'll have to do some refactoring inside of the DFHack codebase to cleanly support it. I'll probably move on to build for now and come back to this part later.

[Fleeting Frames]

Huh. Does that mean

Code: [Select]

#place
 ,a,w,w,w,a,a
a,a,w,w,w,w,a
a,a,a,w,w,w,a
a,a,a,a,a,a,aWould also work?

[myk]

absolutely. that layout is similar to one of my test cases that I used to verify the algorithm. You can have circular stockpiles surrounded by other circular stockpiles, or stockpiles that have the same bounding box upper-left corner like this:

Code: [Select]

#place
a,u,s,h
u,u,s,h
s,s,s,h
h,h,h,h
(which doesn't sound complicated but there's some technical complexity with it)

[lethosor]

PTW. That flood-fill support sounds cool!

[Fleeting Frames]

Does it connect diagonally or only orthogonally?

[myk]

Currently, just orthogonally, but there's no reason why I can't make it also connect diagonally if that's what map makers want. What would be "expected" by a novice mapmaker? should this be one stockpile or two?:

Code: [Select]

#place
a,a, ,a
a, ,a,a
In either case, I plan to suport adding labels to the cells so a stockpile can be defined as disconnected patches. Like, if we do decide to keep the flood fill just checking orthogonal tiles, we could still define the above stockpile as a single pile like this:

Code: [Select]

#place
a:onepile,a:onepile,         ,a:onepile
a:onepile,         ,a:onepile,a:onepile
or even do a disconnected one like this:

Code: [Select]

#place
a:onepile, , , ,a:onepile
a:onepile, , , ,a:onepile
a:onepile, , , ,a:onepile
But I'll get to that once I get basic functionality done for build and query