Merge pull request #3747 from myk002/myk_sort_squad_v2

[sort] squad screen v2

docs/changelog.txt

@@ -59,6 +59,9 @@ Template for new versions:
 - `buildingplan`: make the construction dimensions readout visible again
 
 ## 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
 

docs/plugins/sort.rst

@@ -14,54 +14,75 @@ 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" sort shows the order that your dwarves appeared at your
-that takes into account genetic predispositions in physical and mental
+fort. The numbers on the left indicate the relative arrival order, and the
-attributes, as well as body size. Dwarves (and other humanoid creatures) with
+numbers for the most recent migration wave will be colored bright green.
-higher rating are expected to be more effective in melee combat if they train
+Dwarves that arrived earlier will have numbers in yellow, and your original
-their attributes to their genetic maximum.
+dwarves (if any still survive) will have numbers in red.
-
+
-If sorting is done by "ranged potential" citizens are arranged based on their
+The "stress" sort order will bring your most stressed dwarves to the top, ready
-ranged combat potential rating. This rating is a statistical measure that takes into
+for addition to a :wiki:`therapy squad <Stress#Recovering_unhappy_dwarves>` to
-account genetic predispositions in physical and mental attributes. Dwarves
+help improve their mood.
-(and other humanoid creatures) with higher rating are expected to be more
+
-effective in ranged combat if they train their attributes to the maximum.
+Similarly, sorting by "need for training" will show you the dwarves that are
-
+feeling the most unfocused because they are having their military training
-You can search for a dwarf by name by typing in the Search field. You can also
+needs unmet.
-type in the name of any job skill (military-related or not) and dwarves with
+
-any experience in that skill will be shown. For example, to only see citizens
+Both "stress" and "need for training" sorts use the dwarf happiness indicators
-with military tactics skill, type in "tactics".
+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 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`.