Merge branch 'develop' into adv_cursor

.github/workflows/watch-df-release.yml

@@ -31,7 +31,8 @@ jobs:
     - name: Compare branch metadata
       uses: nick-fields/retry@v3
       with:
-        timeout_minutes: 2
+        timeout_minutes: 5
+        retry_wait_seconds: 60
         command: |
           blob=$(wget 'https://api.steamcmd.net/v1/info/975370?pretty=1' -O- | \
               awk '/^ *"branches"/,0' | \
@@ -117,7 +118,8 @@ jobs:
     - name: Compare versions
       uses: nick-fields/retry@v3
       with:
-        timeout_minutes: 2
+        timeout_minutes: 5
+        retry_wait_seconds: 60
         command: |
           version=$(wget "${{ matrix.url }}" -qO- | tr '"' '\n' | fgrep 'tar.bz2' | head -n1 | sed -r 's/${{ matrix.prefix }}_([0-9]{2})_([0-9]{2})_linux.tar.bz2/\1.\2/')
           echo "latest ${{ matrix.channel }} version: $version"

.pre-commit-config.yaml

@@ -20,7 +20,7 @@ repos:
       args: ['--fix=lf']
     - id: trailing-whitespace
 - repo: https://github.com/python-jsonschema/check-jsonschema
-  rev: 0.30.0
+  rev: 0.31.1
   hooks:
     - id: check-github-workflows
 - repo: https://github.com/Lucas-C/pre-commit-hooks

CMakeLists.txt

@@ -7,7 +7,7 @@ cmake_policy(SET CMP0074 NEW)
 
 # set up versioning.
 set(DF_VERSION "51.04")
-set(DFHACK_RELEASE "r1")
+set(DFHACK_RELEASE "r1.1")
 set(DFHACK_PRERELEASE FALSE)
 
 set(DFHACK_VERSION "${DF_VERSION}-${DFHACK_RELEASE}")

data/init/dfhack.keybindings.init

@@ -49,6 +49,9 @@ keybinding add Ctrl-T@dwarfmode/ViewSheets/UNIT|dwarfmode/ViewSheets/ITEM|dungeo
 # quicksave
 keybinding add Ctrl-Alt-S@dwarfmode quicksave
 
+# toggle spectate
+keybinding add Ctrl-Shift-S@dwarfmode/Default "spectate toggle"
+
 # designate the whole vein for digging
 keybinding add Ctrl-V@dwarfmode digv
 keybinding add Ctrl-Shift-V@dwarfmode "digv x"

docs/about/Authors.rst

@@ -242,6 +242,7 @@ thurin                  thurin
 Tim Siegel              softmoth
 Tim Walberg             twalberg
 Timothy Collett         danaris
+Timothy Torres          timothymtorres
 Timur Kelman            TymurGubayev
 Tom Jobbins             TheBloke
 Tom Prince

docs/changelog.txt

@@ -54,14 +54,21 @@ Template for new versions:
 ## New Tools
 
 ## New Features
+- `spectate`: can now specify number of seconds (in real time) before switching to follow a new unit unit
+- `spectate`: new "cinematic-action" mode that dynamically speeds up perspective switches based on intensity of conflict
+- `spectate`: new global keybinding for toggling spectate mode: Ctrl-Shift-S
 
 ## Fixes
 - `gui/launcher`: ensure commandline is fully visible when searching through history and switching from a very long command to a short command
 - `createitem`: output items will now end up at look cursor if active
+- `spectate`: don't allow temporarily modified announcement settings to be written to disk when "auto-unpause" mode is enabled
+- `changevein`: fix a crash that could occur when attempting to change a vein into itself
 
 ## Misc Improvements
+- `spectate`: player-set configuration is now stored globally instead of per-fort
 
 ## Documentation
+- `stonesense-art-guide`: new guide for making sprite art for Stonesense
 
 ## API
 
@@ -70,6 +77,16 @@ Template for new versions:
 
 ## Removed
 
+# 51.04-r1.1
+
+## Fixes
+- `gui/launcher`: ensure commandline is fully visible when searching through history and switching from a very long command to a short command
+- `gui/launcher`: flatten text when pasting multi-line text from the clipboard
+- Ctrl-a hotkeys have been changed to something else (Ctrl-n) for tools that also have an editable text field, where Ctrl-a is interpreted as select all text
+
+## API
+- ``Core::getUnpausedMs``: new API for getting unpaused ms since load in a fort-mode game
+
 # 51.04-r1
 
 ## Misc Improvements

docs/guides/index.rst

@@ -10,3 +10,4 @@ These pages are detailed guides covering DFHack tools.
    /docs/guides/modding-guide
    /docs/guides/quickfort-library-guide
    /docs/guides/quickfort-user-guide
+   /docs/guides/stonesense-art-guide

docs/guides/stonesense-art-guide.rst

@@ -0,0 +1,71 @@
+.. _stonesense-art-guide:
+
+Stonesense art creation guide
+=============================
+
+Understanding isometric perspective
+-----------------------------------
+
+Stonesense uses an isometric perspective, a form of pseudo-3D projection where objects are displayed at an
+angle, typically with a 2:1 pixel ratio for diagonal lines. This perspective allows for a detailed and visually
+appealing representation of a 3D world using 2D sprites. Unlike traditional top-down views, isometric projection
+simulates depth while maintaining a consistent scale without vanishing points.
+
+Understanding sprites
+---------------------
+
+Understanding how Stonesense deals with sprites is central to anyone who wishes to modify the content. The
+scheme is not very complicated, and this guide will give a short introduction to how they work. With the
+exception of floors, which we will discuss later, all sprites are 32x32 pixels and come in groups known
+as sprite sheets. All sprites are loaded and rendered in 32-bit full-color PNGs. The image files should have
+a transparent background but pure magenta (RGB: 255,0,255) is also treated as transparent.
+
+
+.. image:: ../images/stonesense-sprite-sample.png
+    :align: left
+
+Here's an example of a typical Stonesense sprite.
+
+When working with Stonesense sprites, it is important to understand how they fit into the isometric grid.
+Each sprite is designed to align with the isometric perspective and must fit within a specific bounding area.
+To illustrate this, here is a template for the area that should be used by Stonesense sprites:
+
+.. image:: ../images/stonesense-sprite-template.png
+    :align: left
+
+The solid area is the floor space taken up by a sprite, while the dotted box indicates the volume above this
+area corresponding to one z-level.
+
+The way sprites are loaded is fairly generalized: the name of the sprite sheet, and the index of a sprite within that sheet.
+
+Sprite sheets
+-------------
+There can be an arbitrary number of sprite sheets for Stonesense, though there are 3 sheets that are
+always present as they contain default sprites (see further down). Configuring the XML to use new sheets is
+outside the scope of this guide but there may be a guide for such added in the future.
+
+Sprite index
+------------
+The sprite index, or sheet index, is the zero-indexed offset of a sprite on its sprite sheet.
+The index starts with the upper left sprite which has index zero. It then increments to the right. Stonesense
+is hardcoded to 20 sprite-wide sheets, this means that anything past 20 "sprite slots" is ignored, though less
+than 20 slots is fine. The first sprite on the second row always has index 20 (even if there are fewer sprites per row in the sheet), the next row is 40, and so on. This
+boundary is hardcoded and changing the size of the sheet will not affect it.
+
+This image shows how sprites are indexed. Grid added for readability.
+
+.. figure:: ../images/stonesense-indexed-sprites.png
+    :align: left
+
+
+Important sprite sheets
+-----------------------
+`objects.png <https://github.com/DFHack/stonesense/blob/master/resources/objects.png>`_ is the default sheet
+for buildings and vegetation. Also used for all hard-coded content, like default plants, the cursor, default
+walls and liquid.
+
+`creatures.png <https://github.com/DFHack/stonesense/blob/master/resources/creatures.png>`_ is the default
+sprite sheet for creatures. If no file is specified in a creature node, this is the sheet it will use.
+
+`floors.png <https://github.com/DFHack/stonesense/blob/master/resources/floors.png>`_ holds all the Stonesense
+floors. Unlike the other sprite sheet, this sheet is hard-coded with sprite dimensions of 32x20 pixels.

docs/plugins/changelayer.rst

@@ -22,8 +22,8 @@ Usage
 
 When run without options, ``changelayer`` will:
 
-- only affect the geology layer at the current cursor position
-- only affect the biome that covers the current cursor position
+- only affect the geology layer at the current keyboard cursor position
+- only affect the biome that covers the current keyboard cursor position
 - not allow changing stone to soil and vice versa
 
 You can use the `probe` command on various tiles around your map to find valid
@@ -34,8 +34,9 @@ Examples
 
 ``changelayer GRANITE``
    Convert the layer at the cursor position into granite.
-``changelayer SILTY_CLAY force``
-   Convert the layer at the cursor position into clay, even if it's stone.
+``changelayer SAND_RED force``
+   Convert the layer at the cursor position into red sand, even if it's
+   currently stone.
 ``changelayer MARBLE all_biomes all_layers``
    Convert all layers of all biomes which are not soil into marble.
 

docs/plugins/spectate.rst

@@ -2,61 +2,147 @@ spectate
 ========
 
 .. dfhack-tool::
-    :summary: Automatically follow productive dwarves.
-    :tags: fort interface
+    :summary: Automated spectator mode.
+    :tags: fort inspection interface
+
+This tool is for those who like to watch their dwarves go about their business.
+
+When enabled, `spectate` will lock the camera to following the dwarves
+scurrying around your fort. Every once in a while, it will automatically switch
+to following a different dwarf. It can also switch to following animals,
+hostiles, or visiting units. You can switch to the next target (or a previous
+target) immediately with the left/right arrow keys.
+
+`spectate` will disengage and turn itself off when you move the map, just like
+the vanilla follow mechanic. It will also disengage immediately if you open the
+squads menu for military action.
+
+It can also annotate your dwarves on the map with their name, job, and other
+information, either as floating tooltips or in a panel that comes up when you
+hover the mouse over a target.
+
+Run `gui/spectate` to configure the plugin's settings.
+
+Settings are saved globally, so your preferences for `spectate` and its
+overlays will apply to all forts, not just the currently loaded one. Follow
+mode is automatically disabled when you load a fort so you can get your
+bearings before re-enabling.
 
 Usage
 -----
 
 ::
 
     enable spectate
-    spectate
+    spectate [status]
+    spectate toggle
     spectate set <setting> <value>
-    spectate enable|disable <feature>
-
-When enabled, the plugin will lock the camera to following the dwarves
-scurrying around your fort. Every once in a while, it will automatically switch
-to following a different dwarf, preferring dwarves on z-levels with the highest
-job activity.
-
-If you have the ``auto-disengage`` feature disabled, you can switch to a new
-dwarf immediately by hitting one of the map movement keys (``wasd`` by
-default). To stop following dwarves, bring up `gui/launcher` and run
-``disable spectate``.
-
-Changes to settings will be saved with your fort, but if `spectate` is enabled
-when you save the fort, it will disenable itself when you load so you can get
-your bearings before re-enabling follow mode with ``enable spectate`` again.
+    spectate overlay <name> enable|disable
 
 Examples
 --------
 
 ``enable spectate``
-    Starting following dwarves and observing life in your fort.
+    Start following dwarves and observing life in your fort.
+
+``spectate toggle``
+    Toggle the plugin on or off. Intended for use with a keybinding. The
+    default is Ctrl-Shift-S.
 
 ``spectate``
     The plugin reports its configured status.
 
-``spectate enable auto-unpause``
-    Enable the spectate plugin to automatically dismiss pause events caused
-    by the game. Siege events are one example of such a game event.
+``spectate set auto-unpause true``
+    Configure `spectate` to automatically dismiss popups and pause events, like
+    siege announcements.
 
-``spectate set tick-threshold 1000``
-    Set the tick interval between camera changes back to its default value.
+``spectate set follow-seconds 30``
+    Configure `spectate` to switch targets every 30 seconds when in follow mode.
 
-Features
---------
-:auto-unpause:   Toggle auto-dismissal of game pause events. (default: disabled)
-:auto-disengage: Toggle auto-disengagement of plugin through player
-                 intervention while unpaused. (default: disabled)
-:animals:        Toggle whether to sometimes follow animals. (default: disabled)
-:hostiles:       Toggle whether to sometimes follow hostiles (eg. undead,
-                 titans, invaders, etc.) (default: disabled)
-:visiting:       Toggle whether to sometimes follow visiting units (eg.
-                 diplomats)
+``spectate overlay follow enable``
+    Show informative tooltips that follow each unit on the map.
 
 Settings
 --------
-:tick-threshold: Set the plugin's tick interval for changing the followed
-                 dwarf. (default: 1000)
+
+``auto-disengage`` (default: enabled)
+    Toggle automatically disabling the plugin when the player moves the map or
+    opens the squad panel. If this is disabled, you will need to manually
+    disable the plugin to turn off follow mode.
+
+``auto-unpause`` (default: disabled)
+    Toggle auto-dismissal of announcements that pause the game, like sieges,
+    forgotten beasts, etc.
+
+``cinematic-action`` (default: enabled)
+    Toggle whether to switch targets more rapidly when there is conflict.
+
+``follow-seconds`` (default: 10)
+    Set the time interval for changing the followed unit. The interval does not
+    include time that the game is paused.
+
+``include-animals`` (default: disabled)
+    Toggle whether to sometimes follow fort animals.
+
+``include-hostiles`` (default: disabled)
+    Toggle whether to sometimes follow hostiles (eg. undead, titans, invaders,
+    etc.)
+
+``include-visitors`` (default: disabled)
+    Toggle whether to sometimes follow visiting units, like diplomats.
+
+``include-wildlife`` (default: disabled)
+    Toggle whether to sometimes follow wildlife.
+
+``prefer-conflict`` (default: enabled)
+    Toggle whether to prefer following units in active conflict.
+
+``prefer-new-arrivals`` (default: enabled)
+    Toggle whether to prefer following (non-siege) units that have newly
+    arrived on the map.
+
+``tooltip-follow-job`` (default: enabled)
+    If the ``spectate.follow`` overlay is enabled, toggle whether to show the
+    job of the dwarf in the tooltip.
+
+``tooltip-follow-name`` (default: enabled)
+    If the ``spectate.follow`` overlay is enabled, toggle whether to show the
+    name of the dwarf in the tooltip.
+
+``tooltip-follow-stress`` (default: enabled)
+    If the ``spectate.follow`` overlay is enabled, toggle whether to show the
+    happiness level (stress) of the dwarf in the tooltip.
+
+``tooltip-hover-job`` (default: enabled)
+    If the ``spectate.follow`` overlay is enabled, toggle whether to show the
+    job of the dwarf in the hover panel.
+
+``tooltip-hover-name`` (default: enabled)
+    If the ``spectate.follow`` overlay is enabled, toggle whether to show the
+    name of the dwarf in the hover panel.
+
+``tooltip-hover-stress`` (default: enabled)
+    If the ``spectate.follow`` overlay is enabled, toggle whether to show the
+    happiness level (stress) of the dwarf in the hover panel.
+
+Overlays
+--------
+
+``spectate`` provides two overlays via the `overlay` framework to add
+information and functionality to the main map. These overlays can be controlled
+via the ``spectate overlay`` command or the ``Overlays`` tab in
+`gui/control-panel`.
+
+The information displayed by these overlays can be configured via the
+``spectate set`` command or the `gui/spectate` interface.
+
+``spectate.follow``
+    Show informative tooltips that follow each unit on the map. You can enable
+    this overlay by running ``spectate overlay follow enable`` or,
+    equivalently, ``overlay enable spectate.follow``.
+
+``spectate.hover``
+    Show a popup panel with selected information when your mouse cursor hovers
+    over a unit. You can enable this overlay by running
+    ``spectate overlay hover enable`` or, equivalently,
+    ``overlay enable spectate.hover``.