Merge branch 'develop' into andriel_argparse

docs/changelog.txt

@@ -56,12 +56,18 @@ Template for new versions:
 ## New Features
 
 ## Fixes
+- `buildingplan`: make the construction dimensions readout visible again
+- `seedwatch`: fix a crash when reading data saved by very very old versions of the plugin
 
 ## Misc Improvements
+- `sort`: sort by need for training on squad assignment screen
+- `sort`: filter mothers with infants, units with weak mental fortitude, and critically injured units on the squad assignment screen
+- `sort`: display a rating relative to the current sort order next to the visible units on the squad assignment screen
 
 ## Documentation
 
 ## API
+- `overlay`: overlay widgets can now declare a ``version`` attribute. changing the version of a widget will reset its settings to defaults. this is useful when changing the overlay layout and old saved positions will no longer be valid.
 
 ## Lua
 - ``argparse.boolean``: convert arguments to lua boolean values.

docs/dev/overlay-dev-guide.rst

@@ -90,6 +90,10 @@ The ``overlay.OverlayWidget`` superclass defines the following class attributes:
     This will be filled in with the display name of your widget, in case you
     have multiple widgets with the same implementation but different
     configurations.
+- ``version``
+    You can set this to any string. If the version string of a loaded widget
+    does not match the saved settings for that widget, then the configuration
+    for the widget (position, enabled status) will be reset to defaults.
 - ``default_pos`` (default: ``{x=-2, y=-2}``)
     Override this attribute with your desired default widget position. See
     the `overlay` docs for information on what positive and negative numbers

docs/plugins/sort.rst

@@ -14,54 +14,80 @@ Searching and sorting functionality is provided by `overlay` widgets, and widget
 Squad assignment overlay
 ------------------------
 
-The squad assignment screen can be sorted by name, by migrant wave, by stress,
+You can search for a dwarf by name by typing in the Search field. The search
-by various military-related skills or by long-term military potential.
+field is always focused, so any lowercase letter you type will appear there.
-
+
-If sorted by "any melee", then the citizen is sorted according to the "melee
+The squad assignment screen can be sorted by name, by arrival order, by stress,
-skill effectiveness". This rating uses the highest skill they have in axes, short
+by various military-related skills, or by long-term military potential.
-swords, maces, warhammers or spears along with physical and mental attributes and
+
-general fighting skill. Citizens with higher rating are expected to be more
+If sorted by "melee effectiveness" (the default), then the citizens are sorted
-effective in melee combat with their corresponding weapon.
+according to how well they will perform in battle when using the weapon they
-
+have the most skill in. The effectiveness rating also takes into account
-If sorted by "any ranged", then the citizen is sorted according to the "ranged
+physical and mental attributes as well as general fighting (non-weapon) skills.
-skill effectiveness". This rating uses crossbow and general archery skills
+
-along with mental and physical attributes. Citizens with higher rating are
+The "ranged effectiveness" sort order does a similar sort for expected
-expected to be more effective in ranged combat.
+effectiveness with a crossbow. This sort also takes into account relevant
-
+physical and mental attributes.
-If sorted by "leadership", then the citizen is sorted according to the highest
+
-skill they have in leader, teacher, or military tactics.
+The "effectiveness" sorts are the ones you should be using if you need the best
-
+squad you can make right now. The numbers to the left of the unit list indicate
-If sorting is done by "mental stability" citizens are arranged based on their
+exactly how effective that dwarf is expected to be. Light green numbers
-mental stability rating. This rating is a measure that takes into account
+indicate the best of the best, while red numbers indicate dwarves that will not
-facets and values of an individual and correlates to better stress values.
+be effective in the military in their current state (though see "melee
-It is designed to be higher for more stress-resistant citizens.
+potential" and "ranged potential" sorts below for predictions about future
-
+effectiveness).
-If sorting is done by "melee potential" citizens are arranged based on
+
-their "melee combat potential" rating. This rating is a statistical measure
+The "arrival order" sorts your citizens according to the most recent time they
-that takes into account genetic predispositions in physical and mental
+entered your map. The numbers on the left indicate the relative arrival order,
-attributes, as well as body size. Dwarves (and other humanoid creatures) with
+and the numbers for the group of dwarves that most recently entered the map
-higher rating are expected to be more effective in melee combat if they train
+will be at the top and be colored bright green. If you run this sort after you
-their attributes to their genetic maximum.
+get a new group of migrants, the migrant wave will be colored bright green.
-
+Dwarves that arrived earlier will have numbers in yellow, and your original
-If sorting is done by "ranged potential" citizens are arranged based on their
+dwarves (if any still survive and have never left and re-entered the map) will
-ranged combat potential rating. This rating is a statistical measure that takes into
+have numbers in red.
-account genetic predispositions in physical and mental attributes. Dwarves
+
-(and other humanoid creatures) with higher rating are expected to be more
+The "stress" sort order will bring your most stressed dwarves to the top, ready
-effective in ranged combat if they train their attributes to the maximum.
+for addition to a :wiki:`therapy squad <Stress#Recovering_unhappy_dwarves>` to
-
+help improve their mood.
-You can search for a dwarf by name by typing in the Search field. You can also
+
-type in the name of any job skill (military-related or not) and dwarves with
+Similarly, sorting by "need for training" will show you the dwarves that are
-any experience in that skill will be shown. For example, to only see citizens
+feeling the most unfocused because they are having their military training
-with military tactics skill, type in "tactics".
+needs unmet.
+
+Both "stress" and "need for training" sorts use the dwarf happiness indicators
+to show how dire the dwarf's situation is and how much their mood might be
+improved if you add them to an appropriate squad.
+
+If sorting is done by "melee potential", then citizens are arranged based on
+genetic predispositions in physical and mental attributes, as well as body
+size. Dwarves (and other humanoid creatures) with higher ratings are expected
+to be more effective in melee combat if they train their attributes to their
+genetic maximum.
+
+Similarly, the "ranged potential" sort orders citizens by genetic
+predispositions in physical and mental attributes that are relevant to ranged
+combat. Dwarves (and other humanoid creatures) with higher rating are expected
+to be more effective in ranged combat if they train their attributes to the
+maximum.
+
+The squad assignment panel also offers options for filtering which dwarves are
+shown. Each filter option can by cycled through "Include", "Only", and
+"Exclude" settings. "Include" does no filtering, "Only" shows only units that
+match the filter, and "Exclude" shows only units that do *not* match the filter.
+
+The following filters are provided:
+
+- Units that are assigned to other squads
+- Elected and appointed officials (e.g. mayor, priests, tavern keepers, etc.)
+- Nobility (e.g. monarch, barons, counts, etc.)
+- Mothers with infants (you may not want mothers using their babies as shields)
+- Weak mental fortitude (units that have facets and values that indicate that
+  they will react poorly to the stresses of battle)
+- Critically injured (units that have lost their ability to see, grasp weapons,
+  or walk)
 
 "Melee skill effectiveness", "ranged skill effectiveness", "melee combat potential"
 and "ranged combat potential" are explained in detail here:
 https://www.reddit.com/r/dwarffortress/comments/163kczo/enhancing_military_candidate_selection_part_3/
 "Mental stability" is explained here:
 https://www.reddit.com/r/dwarffortress/comments/1617s11/enhancing_military_candidate_selection_part_2/
-
-You can see all the job skill names that you can search for by running::
-
-    :lua @df.job_skill
-
-in `gui/launcher`.

library/LuaApi.cpp

@@ -1368,8 +1368,8 @@ static CommandHistory * ensureCommandHistory(std::string id,
 
 static int getCommandHistory(lua_State *state)
 {
-    std::string id = lua_tostring(state, 1);
+    std::string id = luaL_checkstring(state, 1);
-    std::string src_file = lua_tostring(state, 2);
+    std::string src_file = luaL_checkstring(state, 2);
     std::vector<std::string> entries;
     ensureCommandHistory(id, src_file)->getEntries(entries);
     Lua::PushVector(state, entries);
@@ -2030,7 +2030,7 @@ static int units_getCitizens(lua_State *L) {
 }
 
 static int units_getUnitsByNobleRole(lua_State *L) {
-    std::string role_name = lua_tostring(L, -1);
+    std::string role_name = luaL_checkstring(L, -1);
     std::vector<df::unit *> units;
     Units::getUnitsByNobleRole(units, role_name);
     Lua::PushVector(L, units);

library/xml

@@ -1 +1 @@
-Subproject commit 1cb9a961351db5c2988cee3a194eb24eac4abc1a
+Subproject commit e2e369242253b556f6eba7e419aa5f833ff8a46e

plugins/lua/buildingplan/planneroverlay.lua

@@ -478,7 +478,7 @@ function PlannerOverlay:init()
             end,
         },
         widgets.Label{
-            frame={b=2, l=23},
+            frame={b=4, l=23},
             text_pen=COLOR_DARKGREY,
             text={
                 'Selected area: ',

plugins/lua/overlay.lua

@@ -261,7 +261,11 @@ local function load_widget(name, widget_class)
         next_update_ms=widget.overlay_onupdate and 0 or math.huge,
     }
     if not overlay_config[name] then overlay_config[name] = {} end
+    if widget.version ~= overlay_config[name].version then
+        overlay_config[name] = {}
+    end
     local config = overlay_config[name]
+    config.version = widget.version
     if config.enabled == nil then
         config.enabled = widget.default_enabled
     end

plugins/seedwatch.cpp

@@ -102,7 +102,11 @@ static void remove_seed_config(color_ostream &out, int id) {
 static bool validate_seed_config(color_ostream& out, PersistentDataItem c)
 {
     int seed_id = get_config_val(c, SEED_CONFIG_ID);
-    auto plant = binsearch_in_vector(world->raws.plants.all, &df::plant_raw::index, seed_id);
+    auto plant = df::plant_raw::find(seed_id);
+    if (!plant) {
+        WARN(config, out).print("discarded invalid seed id: %d\n", seed_id);
+        return false;
+    }
     bool valid = (!plant->flags.is_set(df::enums::plant_raw_flags::TREE));
     if (!valid) {
         DEBUG(config, out).print("invalid configuration for %s discarded\n", plant->id.c_str());