Print

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

[myk]

Thank you both! I'm excited to see this go out too, but it remains to be seen whether I've done a good job -- the lack of beta testers makes me very nervous. I am but a simple coder. I have stars in my eyes, but I have written no unit tests. Lethosor has been awesome finding bugs in code reviews, but despite whatever testing we have done, the chance that my >4000 line script (plus the >2000 line rewrite of buildingplan) is bug-free is essentially nil.

n.b. I do have plans for unit and integration tests, but there are a lot of organizational and technical hurdles to figure out before tests are feasible. Once the tests are in place, though, we can have much more confidence that future changes to the quickfort script won't break existing features.

[myk]

Just a quick update: support for all building types in buildingplan is making its way through code review, and in the meantime, I started work on zone configuration. You can already set the flags for the zone type(s), but this is for the settings on the sub-screens, like pit/pond or hospital supplies. Hospital supplies was tricky since there are no hotkeys defined in the UI for setting the values. I had to come up with a syntax for use in zone blueprints. The code I wrote for it might someday be useful for parameterized query blueprint aliases too. Like, currently to set up a quantum dump you'd write something like:

Code: [Select]

#query
{quantumstopfromeast}{namelastrouteprefix}Goods/Wood quantum{namelastroutesuffix}
but we could potentially use the syntax I defined to simplify to:

Code: [Select]

#query
{quantumstopfromeast name="Goods/Wood quantum"}
I put that on my "Future ideas" list

I also looked into how hard it might be to assign animals to pastures in #zone blueprints. This would eliminate another common manual step in fortress setup. It looks like the zone plugin might do what we need here. I'd just need to build an interface to the zone plugin that I could call from quickfort. Hopefully it will be easier to update than buildingplan was!

[myk]

A release is coming! A release is coming!

-r3 is upon us!

The quickfort script will finally be part of an official release! I'm looking forward to the bug reports ^_^

We decided to delay the buildingplan changes until -r4, though, so we can have more time to test. I expect some users will be annoyed when their buildings disappear due to lack of materials, but we *really* don't want to break buildingplan with a hasty release.

[Nameless Archon]

Keeping an eye on this one - Quickfort has always been one of my favorite tools and I'm looking forward to demonstrating this one later on stream this month.

[myk]

That would be awesome! The -r3 release is finalized, so please try it out! I would love to hear your impressions and suggestions on what could be done better.

Now that quickfort is part of an official release, the docs are available on the DFHack docs server:

• quickfort command reference
• quickfort user guide

As of now, this is my plan for -r4 (totally open for change, though, if there are requests from the community):

• Address any bug reports that come up

of course

• Support all building types in buildingplan

This solves the #1 usability problem: buildings disappearing after running a #build blueprint because of lack of required materials. quickfort orders will generate manager orders to manufacture everything you need for a #build blueprint, but once buildingplan supports all buildings, you won't have to actually wait for all the orders to be fulfilled. You can run the #build blueprint right away.

• Add support in DFHack for bookcases, display furniture, and offering places

Quickfort and buildingplan will pick up support for free once the core library supports them. After this, the only building type left is instruments, but those will be considerably more difficult to support since they're handled so differently by the game.

• Parameterized aliases (i.e. alias functions)

Allows us to simplify #query blueprint alias definitions like {myaliasprefix}something{myaliassuffix} to {myalias varname=something}

• Configure configurable activity zones (e.g. pit/pond toggle, hospital supplies)

You can currently do this in #query blueprints, but the functionality would be more at home in a #zone blueprint. Hospital settings, which have no hotkeys assigned, will use the parameterized alias syntax defined by the previous task.

• More/better organized library blueprints

I feel like this is important to help people get started with quickfort, but I would feel more comfortable with community feedback about which blueprints would be best to include. I don't want to just include everything that's out there. That would be overwhelming for someone who is seeing quickfort for the first time. What I would like here at least is a good set of generally useful #dig blueprints accompanied by corresponding #build (and, if applicable, #query) blueprints

• Automated test infrastructure design

This will be going on in the background for a while, I think, but I want to get it started. I want to get the code fully tested and then integrate the tests into the automated pull request verification process. Quickfort is very large -- it is already the largest script in all of DFHack -- and it depends on other plugins and core DFHack functionality that other people modify. It's impossible to manually test everything after every change. Automated tests will help keep quickfort from getting broken by future changes.

[ESharpAxe]

Is this the right place to ask a question about dreamfort? I loaded PeridexisErrant's Starter Pack 0.47.04-r09, which has DFHack 0.47.04-r3. I've never used quickfort before, so I am trying dreamfort from the library with
[DFHack] # quickfort list -l
I ran the "/surface1". I get a message that says
Once the area is clear, continue with /surface2.
I'm not sure what that means. Is there some documentation or walkthrough on how to run dreamfort? What is a good way to learn quickfort?

[myk]

Hi! Yes, this is definitely the right place to ask. I put the Dreamfort set of blueprints together to showcase what quickfort can do.

The Dreamfort walkthrough is the first blueprint in the series - the "/help" blueprint. You can run it to read it, or see it online here.

Run quickfort list dreamfort -l to just see the Dreamfort blueprints -- or run quickfort gui and set the filter to dreamfort.

To answer your question, though, /surface1 clears some trees on the surface, and /surface2 builds starting workshops in the clear area. That's what the message is referring to.

I'm definitely interested in hearing how quickfort can be made more accessible. If you have trouble, or if anything isn't as clear as it should be, please share your thoughts on this thread!

[ESharpAxe]

TL;DR Quickfort is not accessible to me without learning the blueprint macro language to make use of quickfort.

Here's the story of my introduction to quickfort. I hope my n00b perspective can help those wishing to expand the accessibility of quickfort to achieve their goals.

Two different programs with one language.
At first I was confused by having fun reading documentation where some docs referred to a DFHack command, while other docs referred to a Python utility that needed to be running. In my Starter Pack, I found two folders called blueprints. When I ran quickfort like this
[DFHack]# quickfort
I got this output
quickfort is not a recognized command.
After more documentation fun, I found that I needed Starter Pack 0.44.12-r09 instead of the 0.44.12-08 I was using. After a quick upgrade, I found the quickfort command I wanted to use.

After a couple of hours of documentation fun and an understanding that the DFHack quickfort is a new implementation of an old Python program, I was ready to apply some blueprints. I had learned that the new  quickfort script is supposed to use the same blueprint language that the old Python program used. My preliminary orientation was complete.

I guess I could work on the dwarffortresswiki.org to help others become aware of the two different programs and the multiple blueprints folders in the Starter Pack.

My hopes for quickfort.
When I first started exploring quickfort, I imagined that it might be a way for me to experience other fort designs. I was excited to experience and learn about someone else's approach to the game.

Even though I've been playing DF for six years, my forts are rudimentary and quick to fail. I never figured out channeling, wall building, or levers. My rudimentary forts do have a pattern though. I thought that I would like to capture that and start building on it with quickfort.

I hoped I would be able to apply blueprints and capture existing structures into blueprints without learning the blueprint macro language. I hoped and wondered if it was possible for me to build a fort with quickfort by applying a blueprint example, make some modifications, capture the design to a new blueprint, and apply the new blueprint to a fresh embark. I hoped I would be able to use a blueprint like some kind of JSON nugget of fort design. I imagined that the Design Strategies page in the dwarffortresswiki.org would maybe start referencing some blueprints as examples of security, efficiency, or aesthetics.

Wow! This quickfort thing is going to be awesome.

Hopes dashed.
I was off to find a blueprint to start with. Most blueprints are just code. TheQuickFortress looked good, but after a couple of paragraphs, I ran into this.
Consider building Blueprints/General/embarding-build.csv and -stockpiles.csv first (outside of your 30x20 footprint).
I couldn't figure this out. It seemed like there were missing pieces. So, I gave up on that. The only other blueprint that sounded like what I wanted and had some documentation to go along with it was Dreamfort. It also had the advantage of being included in the DFHack blueprints library.

I started running the Dreamfort though quickfort. I was reading all the messages on the screen from "/help." A message said
Directly after embark, apply /surface1 on a flat area on the surface
I thought I better chop down all the trees to make it flat. I hoped the wood piles would be okay. I wasn't exactly sure what "flat area" meant. So, I had the dwarfs chop down all the trees.
Another message said to be sure to bring blocks. I have never used blocks, so I wasn't sure if my embark was suitable for Dreamfort. The message said to apply "/surface1" on a flat surface and "/industry1" underground. I was wondering how they would be connected. I ran "/surface1" and got this message.
Once the area is clear, continue with /surface2.
I wondered if I needed to have all the wood piles cleared from the surface. I wasn't sure what "area is clear" meant.
I navigated my game cursor down a few levels. I ran "/industry1." When I resumed the game, I started getting announcements about non-economic blocks and unable to complete <some> workshop.

This is when I had had enough fun on my own and decided to ask for help.

Going forward
It seems there is no way for me to use quickfort without learning the blueprint macro language. The Quickfort User Guide states that it "teaches players how to understand and build blueprint files. It also says that the Dreamfort case study is a practical guide to advanced blueprint design. I'm starting to think of quickfort as a macro interpreter that reads the blueprint macro language. I do not think it is a tool that helps me build fortresses that other people have designed. I now think of the Quickfort User Guide as a blueprint programming manual.

I think of the Quickfort User Guide as something like The C Programming Language by Kernighan and Ritchie. I think the Quickfort User Guide could benefit from a "hello, world" example. To quote from Kernighan, "The only way to learn a new programming language is by writing programs in it." If Dreamfort is a showcase of blueprint code, I think the "hello, world" example should be one of the first building blocks of Dreamfort. There are a few code chunks in the Editing Blueprints section of the Quickfort User Guide, I plan to write files based on those code chunks and learn the language. Once I learn enough to read the Dreamfort "/surface1", I hope to be able to take chunks of code from that file to make a tutorial for myself.

This post is too long, but I wanted to capture my n00b perspective in hopes that it might help hose wishing to expand the accessibility of quickfort to achieve their goals.

[myk]

TL;DR Quickfort is not accessible to me without learning the blueprint macro language to make use of quickfort.

First of all, thank you very much for your feedback! I've been working mostly blind up to this point, and stories like this really help me figure out the next steps I need to take. It definitely looks like you've run into some rough edges. Let me see what I can do to smooth them out. You touch on a lot of topics, so methinks this will also be a long post.

From your story, I'm hearing that:

• You hoped to use quickfort to experience other players' fort designs, but the process is frustrating.
• The quickfort documentation was too technical for what you wanted to achieve.
• When applying the dreamfort blueprints, the instructions were not clear and used unfamiliar terminology, and you ran into strange problems.

Let me say that allowing players to easily experience other's fort designs is exactly what I want for quickfort. To me, this has meant:

• I should add features to quickfort that allow blueprint authors to automate away all manual steps
• I should make it easy to package, document, and share blueprint sets

Dreamfort has been my main test case for figuring out what features I need to add. Each Dreamfort level has a list of manual steps you still have to take. One of my goals is to get those lists down to zero.

You have pointed out a number of glaring holes in the documentation, though (sorry, another list. i like lists, it seems):

• Dreamfort needs a better walkthrough with more context
• We need a low-touch blueprint creation guide, focusing on how to auto-create blueprints and the minimal syntax you need to know to make finishing touches

I hoped I would be able to apply blueprints and capture existing structures into blueprints without learning the blueprint macro language. I hoped and wondered if it was possible for me to build a fort with quickfort by applying a blueprint example, make some modifications, capture the design to a new blueprint, and apply the new blueprint to a fresh embark.

Let me introduce you to the blueprint plugin, which looks at the map area you specify and writes a quickfort blueprint. The blueprint documentation refers to another tool, fortplan, which is another previous, partial implementation of quickfort functionality. The quickfort script will be able to play them back. The blueprint plugin cannot capture every nuance of your setup, though. For example, it won't capture stockpile configuration, so you might still have to make some manual blueprint modifications, particularly in the #query blueprints.

When I resumed the game, I started getting announcements about non-economic blocks and unable to complete <some> workshop.

I plan to fix this in the next DFHack release. Blocks are generally preferable to boulders for a number of reasons, and if quickfort didn't restrict the building to using blocks, the game might choose to use your precious iron bars, or coal, or potash, or logs, or some other material with other, better uses. However, as you've seen, if you don't have blocks, this feature is just an annoyance. I'm rewriting it to prefer blocks if they're available, and otherwise use boulders or logs. This should "just work" by default. In the meantime, you can edit your dfhack-config/quickfort/quickfort.txt file and change the buildings_use_blocks setting to false.

In my Starter Pack, I found two folders called blueprints.

I'll talk to PeridexisErrant about that -- it seems to me that we should be able to combine them.

I guess I could work on the dwarffortresswiki.org to help others become aware of the two different programs

This is the very first release of the DFHack quickfort script, so the internet isn't very aware of it yet. I would definitely appreciate it if you started adding links to DFHack quickfort on the wiki!

I think of the Quickfort User Guide as something like The C Programming Language by Kernighan and Ritchie. I think the Quickfort User Guide could benefit from a "hello, world" example. To quote from Kernighan, "The only way to learn a new programming language is by writing programs in it." If Dreamfort is a showcase of blueprint code, I think the "hello, world" example should be one of the first building blocks of Dreamfort. There are a few code chunks in the Editing Blueprints section of the Quickfort User Guide, I plan to write files based on those code chunks and learn the language. Once I learn enough to read the Dreamfort "/surface1", I hope to be able to take chunks of code from that file to make a tutorial for myself.

This is why the engineers shouldn't write the docs. I'm too familiar with the code. I would love to see any tutorial that you write, and, with your permission, maybe integrate it into the official docs.

[ESharpAxe]

I believe you got all that I was trying to say. Thank you for the info on "blocks not rocks." I'm working on learning the blueprint language. I find the Quickfort User Guide helpful for that. I'll be back with more when I get a few blueprints to run right. I like the direction you are taking this. I hope to be able to help you more. Now, back to fun with blueprints for me.

[myk]

I look forward to seeing what you are able to accomplish! As you experiment more, I would love to hear your thoughts on what works well and what doesn't.

To alleviate the confusion around requiring blocks by default for quickfort buildings, I'm planning on moving the material matching functionality to buildingplan (which quickfort uses to manage placed buildings). Buildingplan is much better suited for this kind of thing since it already deals with material selection. I would have done it this way to begin with, but I only recently rewrote buildingplan to get it into shape to handle features like this.

I'll remove the buildings_use_blocks setting from quickfort and introduce a new Global Settings page for buildingplan. Settings pages are surprisingly hard to write -- how much help text do you need? How should everything be formatted? What granularity of settings should you provide? How much familiarity with buildingplan concepts can you assume the player has?

Anyway, here's a mockup of the new settings page (accessible via the 'G' hotkey shown on every building build sidebar, where the other buildingplan hotkeys already are). I included a bunch of features from my TODO list that I intend to add to buildingplan eventually to fill the page out a little more. The first version will likely only have the generic/fire-safe/magma-safe building material type toggles and the Legacy Quickfort Mode toggle.

Code: [Select]

                          Buildingplan Global Settings
 
  e: Enable all: Off
    Enables buildingplan for all building types. Use this to avoid having to
    manually enable buildingplan for each building type that you want to plan.
    Note that DFHack quickfort will use buildingplan to manage buildings
    regardless of whether buildingplan is "enabled" for the building type.
 
  Allowed types for generic, fire-safe, and magma-safe building material:
  b: Blocks:   On
  s: Boulders: On
  w: Wood:     On
  r: Bars:     Off
    Changes to these settings will be applied to newly-planned buildings.
 
  A: Apply building material filter settings to existing planned buildings
    Use this if your planned buildings can't be completed because the settings
    above were too restrictive when the buildings were originally planned.
 
  M: Edit list of materials to avoid
  potash
  pearlash
  ash
  coal
    Buildingplan will avoid using these material types when a planned building's
    material filter is set to 'any'. They can stil be matched when they are
    explicitly allowed by a planned building's material filter. Changes to this
    list take effect for existing buildings immediately.
 
  g: Allow bags: Off
    This allows bags to be placed where a 'coffer' is planned.
 
  f: Legacy Quickfort Mode: Off
    Compatibility mode for the legacy Python-based Quickfort application. This
    setting is not needed for DFHack quickfort.

I also plan to implement settings persistence across map reloads and support setting these global settings from the [DFHack]# prompt (so you can set things the way you like from dfhack.init).

[myk]

I think at this point I've completed the critical changes I was hoping to get into the next release (0.47.04-r4):

• support for all buildings in buildingplan (which means that quickfort now has "plan now, items later" support for all buildings). Bookcases, display furniture, and altars are also added to the list of buildings that DFHack supports.
• dreamfort library blueprint improvements: detailed walkthroughs for each dreamfort level, importable automation orders that keep a dreamfort fort running (useful for any fort, really)
• documentation improvements, including greater emphasis on the blueprint plugin as a way to create blueprints without having to learn the blueprint syntax
• generic building material filtering in buildingplan (that is, for constructions and workshops and anything else that needs a "generic building material" item, there are now toggles for whether buildingplan can use blocks, boulders, logs, and bars). these settings are persisted in your savegame so you won't lose them when you restart df. quickfort's buildings_use_blocks setting has been removed
• more quality blueprints in the blueprint library distributed with DFHack
• ability to define parameterized aliases for use in query blueprints so the hauling route aliases won't be so ugly
• ability to configure flags and hospital supply info for zones so, for example, you don't have to write a query blueprint just to turn a pit into a pond
• 500% speed-up for the first call to quickfort list, reducing the time you have to wait for quickfort to populate its modeline cache
• allow the player to turn off query blueprint sanity checking, just in case they want to do something that quickfort thinks is insane (new quickfort setting: query_unsafe)
• fix issues with building nest boxes, slabs, hives, floor grates, floor hatches, and floor bars
• fix handling of modifier keys (e.g. {Ctrl}) in query blueprints
• fix a few typos in alias definitions in aliases-common.txt

Once these are out in the upcoming -r4 release, I'd like to focus more on testing (though I have a seemingly endless list of features that I'd like to get to as well). My hope is that as usage of quickfort picks up, we'll start getting more specific requests.

[myk]

One more item I think I need to get in before -r4: there's functionality overlap between the automaterial and buildingplan plugins when placing constructions, and building constructions from the ui is a bit confusing now as a result (building from quickfort works as expected, though). I need to get automaterial and buildingplan talking to each other so the right thing happens if both, one, or neither plugin is enabled.

[myk]

Ok, 0.47.04-r4 is just about wrapped. Found and fixed a few more small bugs. Nothing to write home about.

With the buildingplan changes in this release, players can finally lay out entire fortresses and everything will just "come into being" as items are manufactured (automated with quickfort orders). This has been my dream since I started playing DF decades ago, and is the main reason I started this project. I've lost count of the number of times I've started building my fortress, just to get interrupted when I ran out of materials and lose my train of thought. Now I can design in peace and things will just happen! : )

This, along with the manager orders that I distribute with dreamfort (put the file in dfhack-config/orders/ and use with

Code: [Select]

orders import automation) means that the low level toil of building a self-sustaining fortress is now completely automated, and players can focus on other exciting things, like trade or dwarven engineering projects or preparing for HFS or conquering the world!

@Nameless Archon: if you're still looking to do a quickfort stream, I think this release will give you something pretty exciting to show : D

So what's next?

Lethosor and I have been having a good discussion about automated regression testing, and I'm excited to get started on that after -r4. It's great to build something cool, but in software, the greater challenge is keeping it running. Despite its importance, it's the less shiny side of engineering, so I'm unlikely to talk about it much here. If there are any reliability engineers (test engineers, SREs, etc.) reading this who have an opinion, feel free to chime in at the link above.

Other than testing, I have my eyes on a few high-level objectives:

• Make more stuff automatable with quickfort blueprints

This is a continuing goal to eliminate manual steps when applying blueprints. My primary driver is dreamfort, where there are still steps like "assign grazing animals to pasture" and "assign minecart to route" that can't yet be done by a blueprint. Also features like blueprint repetitions and transformations, and syntax for context-sensitive repetitions like "repeat until map edge" or "repeat until surface".

• Make it easy to create useful blueprints from in-game maps

This comes down to expanding the usability and capabilities of the blueprint plugin. There is a lot of information about a fort that we can detect and record in blueprints that the plugin doesn't do yet.

• Make designs on the DF wiki more accessible with quickfort

As ESharpAxe suggested, it would be useful to have downloadable blueprints on the wiki wherever there are design examples.

As always, I'd love to hear suggestions and feedback from the community as well.

[A_Curious_Cat]

Out of curiosity what happens when quickfort encounters that caverns while digging?  Can it cancel the part that extends into the cavern and automatically wall-up the hole?  Also, how good is it at recovering from breaching the caverns from above.  Can it make proper by-passes?