Merge branch 'master' into store-owned

Author: amade-w

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ ci:
 repos:
 # shared across repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v5.0.0
+  rev: v6.0.0
   hooks:
     - id: check-added-large-files
     - id: check-case-conflict
@@ -20,7 +20,7 @@ repos:
       args: ['--fix=lf']
     - id: trailing-whitespace
 - repo: https://github.com/python-jsonschema/check-jsonschema
-  rev: 0.33.2
+  rev: 0.33.3
   hooks:
     - id: check-github-workflows
 - repo: https://github.com/Lucas-C/pre-commit-hooks
@@ -34,6 +34,6 @@ repos:
         - json
 # specific to scripts:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v5.0.0
+  rev: v6.0.0
   hooks:
     - id: forbid-new-submodules

docs/fix/archery-practice.rst

@@ -0,0 +1,62 @@
+fix/archery-practice
+====================
+
+.. dfhack-tool::
+    :summary: Consolidate and remove extra ammo items to fix 'Soldier (no item)' issue.
+    :tags: fort bugfix items
+
+Combine ammo items inside quivers that are assigned for training to allow
+archery practice to take place.
+
+Usage
+-----
+
+``fix/archery-practice``
+    Combine ammo items inside quivers that are assigned for training.
+
+``fix/archery-practice -q``, ``fix/archery-practice --quiet``
+    Combine ammo items inside quivers that are assigned for training.
+    Do not print to console.
+
+This tool will combine ammo items inside the quivers of units in squads
+that are currently set to train with the objective of ensuring that each
+unit hold only one combined stack of ammo item assigned for training in
+their quiver. Any ammo items left over after the combining operation
+will be dropped on the ground.
+
+The 'Soldier (no item)' issue
+-----------------------------
+
+Due to a bug in the game, a unit that is scheduled to train will not be
+able to practice archery at the archery range when their quiver contains
+more than one stack of ammo item that is assigned to them for training.
+This is indicated on the unit by the 'Soldier (no item)' status.
+
+The issue occurs when the game assigns an ammo item with a stack size of
+less than 25 to the unit, prompting the game to assign additional stacks
+of ammo items to make up for the deficit.
+
+The workaround to this issue is to ensure the squad ammo assignments
+for use in training contain as few ammo items with stack sizes smaller
+than 25 as possible. Since training bolts are often made from wood or
+bone which are created in stacks of 5, the use of the  ``combine`` tool on
+ammo stockpiles is recommended to reduce the frequency of this issue
+occurring, while "incomplete" stacks of ammo items that are already
+picked up by training units can be managed by this tool.
+
+Any other stacks of ammo items inside the quiver that are not assigned
+for training will not affect the unit's ability to practice archery.
+
+Limitations
+-----------
+
+Due to the very limited number of ammo items a unit's quiver might contain,
+the material, quality, and maker of the items are ignored when performing
+the combining operation on them. Only ammo items assigned for training will
+be combined, while ammo items inside the quiver that are assigned for combat
+will not be affected.
+
+Although this tool will consolidate ammo items inside quivers and discard
+any surplus items, the training units may not immediately go for archery
+practice, especially if they are still trying to collect more ammo items
+that the game have assigned to them.

docs/gui/adv-finder.rst

@@ -0,0 +1,112 @@
+gui/adv-finder
+==============
+
+.. dfhack-tool::
+    :summary: Find and track historical figures and artifacts
+    :tags: adventure armok inspection items units
+
+A real-time tracker for historical figures and artifacts. Select a target by
+clicking the settings icon [☼] and selecting an entry from the list in the
+relevant tab. The list can be filtered by search string, as well as by
+excluding dead figures (displayed in red text). Artifacts can exclude books,
+and the "dead" option excludes artifacts held by dead figures (which are
+generally unrecoverable). Dismissing the screen (e.g., right-click) will
+close the target search window first. A second dismissal will close the
+finder window, but target settings will be preserved until the world is
+unloaded.
+
+Your coordinates will be kept up to date alongside your target's. There are
+two types of coordinates, and they will be displayed as long as they can be
+determined.
+
+==========  ==========
+Coord Type  Meaning
+==========  ==========
+Global      Distance in map blocks from the world origin (northwest corner).
+            The adventurer usually moves by 3 blocks during fast travel, but
+            slows to 1 when the zoomed site map is displayed. Equivalent to
+            16 local tiles. Always available except for targets with an
+            indeterminate location.
+Local       Tile coordinates, available outside of fast travel and sleeping.
+            Your target's local coordinates are displayed when nearby and
+            loaded. Local coordinates will remain consistent within a site, but
+            may jump around in the wilderness as areas of the world are loaded.
+==========  ==========
+
+For global coordinates, the Z component will only be displayed if it can be
+specifically determined by the location type. This represents an underground
+layer depth, so the surface is indicated by ``Z0`` and the first cavern layer
+is ``Z-1``.
+
+A compass and relative coordinates will be displayed. The relative coordinate
+display uses the most precise coordinate type shared between you and your
+target.
+
+There are six types of location types displayed for targets:
+
+=============  ==========
+Location Type  Meaning
+=============  ==========
+Nearby         The target is loaded into the map area and the local
+               coordinates will be displayed. If you don't see this when you're
+               in the correct area and outside fast travel, then the target
+               isn't loading for some reason and you'll never be able to find
+               them.
+Site           The target is located within a site. The text displays
+               "At <Sitename>" and the global coords will represent the center
+               of the site if the target doesn't track its own precise
+               coordinates (e.g., worldgen being vague).
+Traveling      The target is traveling around the world map like an army.
+Wilderness     The target is somewhere on the surface not in a site.
+Underground    The target is somewhere in the caverns not in a site.
+None           The target's location isn't defined in the game world.
+               Maybe they're a deity. Maybe they got dropped off in limbo
+               after their army disbanded. If they're dead, the location
+               wasn't recorded properly in history. The text displays "Missing"
+               if they're dead or can die of old age, else "Transcendent"
+               because nothing can touch them.
+=============  ==========
+
+Dead figures generally can't be encountered at all, and they take their items
+with them if they weren't separated properly by worldgen. The coord given is
+usually a death or abstract burial location, but the corpse isn't guaranteed to
+exist. Generally, wilderness and underground locations only have coords if you
+left something there in adventure mode. Anything lost there during worldgen or a
+fort mode mission likely can't be located. Anything in a site is usually a safe
+bet, but sometimes items won't load. (Fort missions can be used to acquire these
+for later retrieval, however.) Traveling targets are always valid.
+
+Usage
+-----
+
+::
+
+    gui/adv-finder [<options>]
+
+Examples
+--------
+
+``gui/adv-finder``
+    Open the finder window (unless already open). Target will be blank on first
+    use, but maintained on future invocations.
+``gui/adv-finder --histfig 1234``
+    Track the historical figure with ID #1234. Finder will be opened if not
+    already.
+``gui/adv-finder -h -1 -a -1``
+    Clear any target so it's just the adventurer. Finder will be opened if not
+    already.
+``gui/adv-finder --debug``
+    Display selected target IDs in the finder window title bar. Finder will be
+    opened if not already. This setting isn't saved, so it can be disabled by
+    invoking ``gui/adv-finder`` again without the option.
+
+Options
+-------
+
+``-h``, ``--histfig <id>``
+    Set the target to the historical figure with the given ID.
+``-a``, ``--artifact <id>``
+    Set the target to the artifact record with the given ID. (Not an item ID!)
+``-d``, ``--debug``
+    Display selected target IDs in the finder window title bar. Doesn't persist
+    between invocations.

docs/gui/aquifer.rst

@@ -12,7 +12,7 @@ tiles or warm tiles). Note that "just damp" tiles will still be highlighted if
 they are otherwise already visible.
 
 You can draw boxes around areas of tiles to alter their aquifer properties, or
-you can use the :kbd:`Ctrl`:kbd:`A`` shortcut to affect entire layers at a time.
+you can use the :kbd:`Ctrl`:kbd:`A` shortcut to affect entire layers at a time.
 
 If you want to see where the aquifer tiles are so you can designate digging,
 please run `gui/reveal`. If you only want to see the aquifer tiles and not