DFHack/dfhack — pull request #402 by Ramblurr (2014-11-22 18:04:02+00:00)
Title: plugin: Stockpile Settings Serialization

Hello,

This PR consists of a massive modification to the stockpiles plugin. In addition to copying settings between stockpiles in game, now it can export the settings to a file on disk and import them in again, in a cross-platform and cross-world/save manner. Users can even share them among each other!

Stockpiling behavior by players has been getting more and more complicated as the years go by. Persisting stockpile settings that are tedious to setup will make it easier for players to adopt more efficient, but complicated, stockpiling practices.

Moreover, this is an incredible improvement over macros. Macros are not only tedious but error prone and impossible to edit after the fat. Not to mention sharing them is cumbersome and fraught with other problems.

## Usage

The usage is simple, much like copystock, position your cursor over your stockpile, then type `savestock filename` to save the settings or or `loadstock filename` to load them from the file and apply them to the stockpile.

```
[DFHack]# help savestock
savestock: Save the active stockpile's settings to a file.
Usage:
Must be in 'q' mode and have a stockpile selected.
example: 'savestock food.dfstock' will save the settings to 'food.dfstock'
in your stockpile folder.

-d, --debug: enable debug output
: filename to save stockpile settings to (will be overwritten!)

[DFHack]# help loadstock
loadstock: Load settings from a file and apply them to the active stockpile.
Usage:
Must be in 'q' mode and have a stockpile selected.
example: 'loadstock food.dfstock' will load the settings from 'food.dfstock'
in your stockpile folder and apply them to the selected stockpile.

-d, --debug: enable debug output
: filename to load stockpile settings from
```

## Serialization Format

Since DFHack already includes google's protobuf, I've opted to use it as the serialization method. The serialization process is quite simple in theory, but results in lots of tedious code.

Essentially, each material/type/etc index is mapped to its token (e.g., 0 -> INORGANIC:IRON) and this token is serialized. Importing is simply the reverse of this process. In same cases (food for example) that mapping is a bit more complicated.

### Two Formats: Binary and Text

The plugin supports two serialization formats: binary and text. Supporting the latter format required shipping the full protobuf library with dfhack, whereas before it was only shipping and linking against the latter.

The text format is pretty simple, here is a [default stone stockpile](http://hastebin.com/fojodofeku.sm).

The binary format produces much smaller files and is faster to load/save.

## Request for testing

Before this is merged into master, I would appreciate some testing. I've only tested this plugin on 40_14 saves on my own linux box. Testing on windows and OS X would be greatly appreciated.

## Future Plans

This plugin is a great step forward I think, but I hate solving problems for users by giving them another obtuse command line tool.

The next step for this plugin is a simple GUI component that integrates into the 'q' menu for stockpiles. The plugin will find all '*.dfstock' files in the DF folder, and display them in the list as presets the user can choose from. Finally, saving settings will also be possible from within the game's UI.