export worldgen tool

changelog.txt

@@ -27,6 +27,7 @@ Template for new versions:
 # Future
 
 ## New Tools
+- `export-worldgen`: export the loaded world's generation parameters as a ``world_gen.txt`` stanza that can regenerate it, with optional world painter (``PS_*``) map data
 - `devel/datamine`: watch live values for changes and diff structure snapshots to aid script development and reverse engineering
 - `devel/infinite-sky-probe`: tool for testing whether infinite sky is working correctly
 - `fix/stuck-written-materials`: free written materials that are stuck in a non-existent job
@@ -44,6 +45,7 @@ Template for new versions:
 - `caravan`: fix doubled "total value of items marked for trade" after toggling filter options, and keep item marks when switching between filter views in the ``Bring goods to depot`` overlay
 - `combine`: dyes are combined again, but only when their ``dye_profile`` matches, so mixed dyes no longer revert to a component dye
 - `fix/loyaltycascade`: guard against citizens that are not historical figures and emit a warning.
+- `full-heal`: ``--all-citizens`` still matches dead citizens (for resurrection) now that ``dfhack.units.isCitizen`` excludes the dead
 - `gui/settings-manager`: preserve built-in work details added after saved settings were created
 - `gui/siegemanager`: fix nil index if there are no siege engines on the map
 - `hide-tutorials`: also suppress the adventure mode start tutorial (defaults its checkbox to off and dismisses the popups)

docs/export-worldgen.rst

@@ -0,0 +1,119 @@
+export-worldgen
+===============
+
+.. dfhack-tool::
+    :summary: Export the loaded world's worldgen parameters to world_gen.txt.
+    :tags: armok inspection fort adventure legends embark
+
+Reads the ``worldgen_parms`` of the currently loaded world and appends a
+``[WORLD_GEN]`` parameter set stanza to your ``prefs/world_gen.txt`` file. The
+generated stanza can then be selected from the "create world" screen to
+regenerate a world with the same parameters.
+
+The ``prefs`` directory is resolved the same way DF does: if portable mode is
+enabled (``init.txt``), the ``prefs`` folder inside the DF install directory is
+used; otherwise the ``prefs`` folder in the DF application data directory is
+used.
+
+By default, seeds are *not* included in the stanza, so each use of the
+parameter set generates a fresh random world based on the same settings. Use
+the seed options to capture the actual seeds the world was generated with for
+an exact reproduction (to the extent that worldgen is deterministic).
+
+Usage
+-----
+
+::
+
+    export-worldgen [<options>]
+
+Examples
+--------
+
+``export-worldgen``
+    Append a stanza with all parameters, but no seeds, to
+    ``prefs/world_gen.txt``.
+
+``export-worldgen --all-seeds``
+    Append a stanza that includes all four seeds the world was generated with,
+    allowing the world to be regenerated as exactly as worldgen determinism
+    allows.
+
+``export-worldgen --seed --title MY FAVORITE WORLD``
+    Append a stanza with only the main seed and a custom parameter set title.
+
+``export-worldgen --map --relax``
+    Append a stanza that includes ``PS_*`` world painter data reconstructed
+    from the generated world map, with map rejection criteria and
+    post-processing relaxed so the painted data is used as-is.
+
+``export-worldgen --print``
+    Print the stanza to the console instead of appending it to
+    ``world_gen.txt``.
+
+Options
+-------
+
+``-t``, ``--title <name>``
+    The title for the parameter set (the ``[TITLE:...]`` token). Defaults to
+    the world's name in all caps.
+
+``-p``, ``--print``
+    Print the stanza to the console instead of appending it to
+    ``prefs/world_gen.txt``.
+
+``--seed``, ``--history-seed``, ``--name-seed``, ``--creature-seed``
+    Include the corresponding seed in the stanza. Each seed is opt-in.
+
+``--all-seeds``
+    Include all four seeds. Equivalent to specifying all of the individual
+    seed options.
+
+``--keep-name``
+    Emit a ``[CUSTOM_NAME:...]`` token with the world's name, so worlds
+    generated with this parameter set are given the same name. By default the
+    token is omitted and generated worlds get a fresh random name.
+
+``-m``, ``--map``
+    Emit ``PS_*`` world painter data for elevation, rainfall, temperature,
+    drainage, volcanism, and savagery. This is the same mechanism the old
+    in-game world painter and the PerfectWorldDF utility used. If the world was
+    originally generated from a preset, its data is re-emitted verbatim;
+    otherwise the data is reconstructed from the generated world map.
+
+``--relax``
+    Zero out map rejection criteria (``*_RANGES``, ``REGION_COUNTS``,
+    ``GOOD_SQ_COUNTS``/``EVIL_SQ_COUNTS``, ``PEAK_NUMBER_MIN``, ocean edge
+    minimums, ``VOLCANO_MIN``, ``RIVER_MINS``) and disable erosion and
+    orographic precipitation. Recommended with ``--map``, since painted maps
+    commonly fail the normal rejection criteria and since erosion would alter
+    the painted values a second time.
+
+Map reproduction caveats
+------------------------
+
+``--map`` can only capture the six fields the world painter supports:
+elevation, rainfall, temperature, drainage, volcanism, and savagery. Evil/good,
+vegetation, salinity, rivers, lakes, peaks, and other derived features are
+still generated by DF; include ``--all-seeds`` to have them regenerate the
+same way.
+
+When reconstructing from the generated world map (i.e., the world was not
+generated from a preset), some fidelity is unavoidably lost:
+
+- Elevation is stored at a quarter of the painter's resolution for land
+  biomes, so reconstructed values are quantized.
+- Temperature includes the effects of latitude, elevation, and other
+  adjustments that worldgen will apply again to painted data, so painted
+  temperature maps are approximate.
+- Other post-processing (e.g. erosion) has already been applied to the stored
+  map, which is why ``--relax`` is recommended.
+
+Notes
+-----
+
+- DF reads ``world_gen.txt`` when the parameter list is loaded. If the create
+  world screen is already open, leave and re-enter it (or reload the list) to
+  see the new parameter set.
+- If a parameter set with the same title already exists in ``world_gen.txt``,
+  a warning is printed but the stanza is still appended.