changelog.txt

=== Scroll down for changes

===[[[
The text below is included in docs/dev/Documentation.rst - see that file for more details on the changelog setup.
This is kept in this file as a quick syntax reference.

===help

changelog.txt uses a syntax similar to RST, with a few special sequences:

- ``===`` indicates the start of a comment
- ``#`` indicates the start of a release name (do not include "DFHack")
- ``##`` indicates the start of a section name (this must be listed in ``gen_changelog.py``)
- ``-`` indicates the start of a changelog entry. **Note:** an entry currently must be only one line.
- ``:`` (colon followed by space) separates the name of a feature from a description of a change to that feature.
    Changes made to the same feature are grouped if they end up in the same section.
- ``:\`` (colon, backslash, space) avoids the above behavior
- ``- @`` (the space is optional) indicates the start of an entry that should only be displayed in NEWS-dev.rst.
    Use this sparingly, e.g. for immediate fixes to one development build in another development build that
    are not of interest to users of stable builds only.
- Three ``[`` characters indicate the start of a block (possibly a comment) that
  spans multiple lines. Three ``]`` characters indicate the end of such a block.
- ``!`` immediately before a phrase set up to be replaced (see gen_changelog.py) stops that occurrence from being replaced.

Template for new versions:

## New Tools

## New Features

## Fixes

## Misc Improvements

## Documentation

## API

## Lua

## Removed

===end
]]]

================================================================================
======== IMPORTANT: rename this, and add a new "Future" section, BEFORE ========
======== making a new DFHack release, even if the only changes made     ========
======== were in submodules with their own changelogs!                  ========
================================================================================

# Future

## New Tools

## New Features
- `spectate`: can now specify number of seconds (in real time) before switching to follow a new 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
- `spectate`: new overlay panel that allows you to cycle through following next/prevous units (regardless of whether spectate mode is enabled)
- ``disable-vanilla-dimensions``: new binpatch to disable the vanilla dimensions tooltip
- `gui/sitemap`: is now the official "go to" tool. new global hotkey for fort and adventure mode: Ctrl-G

## Fixes
- Windows console: fix possible hang if the console returns a too-small window width (for any reason)
- `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
- `autobutcher`: treat animals on restraints as unavailable for slaughter
- `stockpiles`: add property filters for brewable, millable, and processable (e.g. at a Farmer's workshop) organic materials

## Documentation
- `stonesense-art-guide`: guide for making sprite art for Stonesense

## API
- ``Military::removeFromSquad``: removes unit from any squad assignments
- ``Buildings::checkFreeTiles``: now replaces the extents parameter for a building pointer

## Lua
- ``dfhack.units.setAutomaticProfessions``: sets unit labors according to current work detail settings
- ``dfhack.military.removeFromSquad``: Lua API for ``Military::removeFromSquad``
- ``gui.dwarfmode``: adventure mode cursor now supported in ``getCursorPos``, ``setCursorPos``, and ``clearCursorPos`` funcitons
- ``dfhack.buildings.checkFreeTiles``: now replaces the extents parameter for a building pointer

## Removed

# 51.05-r1

## Misc Improvements
- Compatibility with DF 51.05
# 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
- ``Units::getPosition``, ``Items::getPosition``: return invalid coord for inactive units and items held by off-map units
- ``Units::isUnitInBox``, ``Units::getUnitsInBox``: don't include inactive units
- ``Units::isActive``: return false for off-map units

# 51.04-r1

## Misc Improvements
- Compatibility with Steam release of DF 51.04

# 51.03-r1.1

## Misc Improvements
- Compatibility with Itch release of DF 51.03

# 51.03-r1

## Fixes
- `gui/gm-editor`: fix Enter key not being recognized for opening the selected object

# 51.02-r1

## Misc Improvements
- DFHack edit field widgets, such as the commandline editor in `gui/launcher`, now support text selection and other advanced text editing features from `gui/journal`

# 50.15-r2

## New Features
- `stockpiles`: add simple import/export dialogs to stockpile overlay panel
- `orders`: add transparent overlays to the manager orders screen that allow right clicks to cancel edit of quantities or condition details instead of exiting to the main screen

## Fixes
- `preserve-rooms`: don't erroneously release reservations for units that have returned from their missions but have not yet entered the fort map
- `preserve-rooms`: handle case where unit records are culled by DF immediately after a unit leaves the map
- `preserve-tombs`: properly re-enable after loading a game that had the tool enabled
- `zone`: assign animal to cage/restraint dialog now allows you to unassign a pet from the cage or restraint if the pet is already somehow assigned (e.g.  war dog was in cage and was subsequently assigned to a dwarf)
- `stockpiles`: don't set ``use_links_only`` flag to a random value when the flag is not set to anything in the settings that are being imported
- `strangemood`: ensure generated names for artifacts match what the game itself would generate

## Misc Improvements
- `strangemood`: add ability to choose Stone Cutting and Stone Carving as the mood skill
- `suspendmanager`: add more specific messages for submerged job sites and those managed by `buildingplan`
- `dig-now`: handle digging in pool and river tiles

## Documentation
- Added example code for creating plugin RPC endpoints that can be used to extend the DFHack API

## API
- ``Units::isUnitInBox``, ``Units::getUnitsInBox``: add versions accepting pos arguments
- ``Units::getVisibleName``: when acting on a unit without an impersonated identity, returns the unit's name structure instead of the associated histfig's name structure
- ``Translation::generateName``: generates in-game names, mirroring DF's internal logic
- ``Persistence::getUnsavedSeconds``: returns the number of seconds since last save or load

## Lua
- ``dfhack.units.isUnitInBox``, ``dfhack.units.getUnitsInBox``: add versions accepting pos arguments
- ``widgets.FilteredList``: search keys for list items can now be functions that return a string
- ``dfhack.translation.generateName``: Lua API for ``Translation::generateName``
- ``dfhack.persistent.getUnsavedSeconds``: Lua API for ``Persistence::getUnsavedSeconds``

## Removed
- ``dfhack.TranslateName`` has been renamed to ``dfhack.translation.translateName``

## Internals
- Plugin command callbacks are now called with the core suspended by default so DF memory is always safe to access without extra steps
- Errors when unloading a plugin's DLL are now checked and reported

# 50.15-r1.2

## Misc Improvements

- Updated support for Itch

# 50.15-r1.1

## Misc Improvements

- Updated support for Classic (Itch not available for analysis yet)

# 50.15-r1

## Fixes

- `gui/prerelease-warning`: don't pop up during worldgen, only after a fort has been loaded

# 50.14-r2

## New Tools
- `infinite-sky`: (reinstated, renamed from ``infiniteSky``) automatically create new z-levels of sky to build in
- `forceequip`: (reinstated) forcibly move items into a unit's inventory

## New Features
- `tweak`: ``realistic-melting``: change melting return for inorganic armor parts, shields, weapons, trap components and tools to stop smelters from creating metal, bring melt return for adamantine in line with other metals to ~95% of forging cost. wear reduces melt return by 10% per level

## Fixes
- Fix mouse clicks bleeding through resizable DFHack windows when clicking in the space between the frame and the window content
- `autobutcher`: don't run a scanning and marking cycle on the first tick of a fortress to allow for all custom configuration to be set first
- `nestboxes`: don't consider eggs to be infertile just because the mother has left the nest; eggs can still hatch in this situation
- `timestream`: adjust the incubation counter on fertile eggs so they hatch at the expected time
- `timestream`: adjust the timeout on traps so they can be re-triggered at normal rates
- `logistics`: don't ignore rotten items when applying stockpile logistics operations (e.g. autodump, autoclaim, etc.)

## Misc Improvements
- DFHack now verifies that critical DF data structures have known sizes and refuses to start if there is a mismatch
- DFHack text edit fields now delete the character at the cursor when you hit the Delete key
- DFHack text edit fields now move the cursor by one word left or right with Ctrl-Left and Ctrl-Right
- DFHack text edit fields now move the cursor to the beginning or end of the line with Home and End
- Quickfort blueprint library: ``aquifer_tap`` blueprint walkthough rewritten for clarity
- Quickfort blueprint library: ``aquifer_tap`` blueprint now designated at priority 3 and marks the stairway tile below the tap in "blueprint" mode to prevent drips while the drainage pipe is being prepared
- `preserve-rooms`: automatically release room reservations for captured squad members. we were kidding ourselves with our optimistic kept reservations. they're unlikely to come back : ((
- `buildingplan`: add value info to item selection dialog (effectively ungrouping items with different values) and add sorting by value
- `timestream`: improve FPS by a further 10%
- `fix/occupancy`: additionally handle the case where tile building occupancy needs to be set instead of cleared
- `orders`: ``orders sort`` now moves orders that are tied to a specific workshop to the top of the list in the global manager orders screen
- `gui/pathable`: make wagon path to depot representation more robust

## Documentation
- Dreamfort: add link to Dreamfort tutorial youtube series: https://www.youtube.com/playlist?list=PLzXx9JcB9oXxmrtkO1y8ZXzBCFEZrKxve
- The error message that comes up if there is a version mismatch between DF and DFHack now informs you which DF versions are supported by the installed version of DFHack

## API
- ``DFHack::Units``: new function ``setPathGoal``
- ``Units::setAutomaticProfessions``: bay12-provided entry point to assign labors based on work details

## Lua
- ``dfhack.units``: new function ``setPathGoal``
- ``widgets.TabBar``: updated to allow for horizontal scrolling of tabs when there are too many to fit in the available space

## Removed
- UI focus strings for squad panel flows combined into a single tree: ``dwarfmode/SquadEquipment`` -> ``dwarfmode/Squads/Equipment``, ``dwarfmode/SquadSchedule`` -> ``dwarfmode/Squads/Schedule``
- `faststart`: removed since the vanilla startup sequence is now sufficiently fast

# 50.14-r1

## Fixes
- `preserve-rooms`: don't reserve a room for citizens that you expel from the fort
- `autobutcher`: fix regression in ordering of butcherable animals

# 50.13-r5

## New Tools
- `preserve-rooms`: manage room assignments for off-map units and noble roles. reserves rooms owned by traveling units and reinstates their ownership when they return to the site. also allows you to assign rooms to noble/administrator roles, and the rooms will be automatically assigned whenever the holder of the role changes

## Fixes
- prevent hang when buildings in zones are destroyed in the case where the buildings were not added to the zone in the same order that they were created (uncommon)
- `buildingplan`: improved performance in forts with large numbers of items
- System clipboard: when pasting single lines from the system clipboard, replace newlines with spaces so they don't show up as strange CP437 glyphs in-game
- `exterminate`: don't kill friendly undead (unless ``--include-friendly`` is passed) when specifying ``undead`` as the target
- `gui/settings-manager`: work details overlay no longer disappears when you click on a unit in the unit list
- `buildingplan`: fixed processing errors when using quick material filter slot '0'
- DFHack screens that allow keyboard cursor and camera movement while focused now also allow diagonal and Z-change keyboard cursor keys
- `strangemood`: manually-triggered Macabre moods will now correctly request up to 3 bones/remains for the primary component instead of only 1
- `regrass`: no longer add all compatible grass types when using ``--force`` without ``--new``
- `regrass`: ``--mud`` now converts muddy slade to grass, consistent with normal DF behavior
- `gui/pathable`: fix hang when showing trade depot wagon access and a trade depot is submerged under water or magma
- `gui/pathable`: fix representation of wagon paths over stairs and through doors
- DFHack state for a site is now properly saved when retiring a fort
- `gui/teleport`: fix issue when teleporting units that are not prone, resulting in later issues with phantom "cannot build here: unit blocking tile" messages

## Misc Improvements
- `sort`: can now search for stockpiles on the Places>Stockpile tab by name, number, or enabled item categories
- `gui/family-affairs`: you can start this tool by the name ``gui/pregnancy`` to start directly on the "Pregnancies" tab
- `buildingplan`: only consider building materials that can be accessed by at least one citizen/resident
- Dreamfort: integrate with `preserve-rooms` to assign relevant rooms to nobles/adimistrators
- Dreamfort: smooth tiles under statues and other large furniture that you can't easily smooth later

## Documentation
- add documentation for ``dfhack.items.findType(string)`` and ``dfhack.items.findSubtype(string)``
- `modding-guide`: added examples for reading and writing various types of persistent storage
- `modding-guide`: updated all code snippets for greater clarity

## API
- ``Units``: new ``isWildlife`` and ``isAgitated`` property checks
- ``Items::createItem``: removed ``growth_print`` parameter; now determined automatically
- ``DFHack::cuboid``: ``cuboid::clampMap`` now returns the cuboid itself (instead of boolean) to allow method chaining; call ``cuboid::isValid`` to determine success

## Lua
- ``dfhack.units``: ``isWildlife`` and ``isAgitated`` property checks
- ``dfhack.units.isDanger``: no longer unconditionally returns true for intelligent undead
- Overlay widgets can now assume their ``active`` and ``visible`` functions will only execute in a context that matches their ``viewscreens`` associations
- ``gui.simulateInput``: do not generate spurious keycode from ``_STRING`` key inputs
- ``dfhack.items.createItem``: removed ``growth_print`` parameter to match C++ API

## Removed
- ``quickfortress.csv``: remove old sample blueprints for "The Quick Fortress", which were unmaintained and non-functional in DF v50+. Online blueprints are available at https://docs.google.com/spreadsheets/d/1WuLYZBM6S2nt-XsPS30kpDnngpOQCuIdlw4zjrcITdY if anyone is interested in giving these blueprints some love

# 50.13-r4

## New Features
- `gui/journal`: new hotkey, accessible from anywhere in fort mode: Ctrl-j

## Fixes
- `changelayer`: fix incorrect lookup of geological region in multi-region embarks
- Copy/Paste: Fix handling of multi-line text when interacting with the system clipboard on Windows
- `zone`: fix alignment of animal actions overlay panel (the one where you can click to geld/train/etc.) when the animal has a custom portrait (like named dragons)
- `autodump`: cancel any jobs that point to dumped items
- `add-spatter`: fix a crash related to unloading a savegame with add-spatter reactions, then loading a second savegame with add-spatter reactions
- `plant`: properly detect trees in a specified cuboid that only have branches/leaves in the cuboid area

## Misc Improvements
- performance improvements for DFHack tools and infrastructure
- `gui/pathable`: give edge tiles where wagons can enter the map a special highlight to make them more identifiable. this is especially useful when the game decides that only a portion of the map edge is usable by wagons.
- `autodump`: allow dumping items into mid-air, converting them into projectiles like `gui/autodump` does

## Documentation
- improved docs for ``dfhack.units`` module functions

## API
- ``Units``: add overloads that take historical figures for ``getReadableName``, ``getVisibleName``, and ``getProfessionName``
- ``Units::isUnitInBox``, ``getUnitsInBox``: add versions that take a cuboid range, add filter fn parameter for ``getUnitsInBox``
- ``Units::getProfession``: account for units with fake identities
- ``Units::getCasteRaw``: get a caste_raw from a unit or race and caste
- ``cuboid``: construct from ``df::map_block*``, ``forBlock`` iterator to access map blocks in cuboid
- ``cuboid``: ``clamp(cuboid other)``, ``clampNew(cuboid other)`` for cuboid intersection. ``clampNew`` returns new cuboid instead of modifying.
- ``Items``: no longer need to pass MapCache parameter to ``moveToGround``, ``moveToContainer``, ``moveToBuilding``, ``moveToInventory``, ``makeProjectile``, or ``remove``
- ``Units::isVisible``: account for units in cages
- ``Units::getReadableName``: correct display of ghost+curse names w/r/t each other and unit prof, use ``curse.name`` instead of iterating syndrome name effects
- ``setAreaAquifer``, ``removeAreaAquifer``: add overloads that take cuboid range specifiers
- ``Units::isNaked``: now only checks equipped items (including rings, for now). Setting bool ``no_items`` to true checks empty inventory like before.
- ``Units::isUndead``: bool ``include_vamps`` renamed to ``hiding_curse``. Fn now checks that instead of bloodsucker syndrome.
- ``Units::isDanger``: added bool ``hiding_curse``, passed to ``isUndead`` to avoid spoilers
- ``Units::getRaceChildName``, ``getRaceChildNameById``, ``getRaceBabyName``, ``getRaceBabyNameById``: bool ``plural`` to get plural form
- ``Units::getProfessionName``: bool ``land_title`` to append "of Sitename" where applicable, use Prisoner/Slave and noble spouse titles (controlled by ``ignore_noble``)

## Lua
- ``gui.ZScreen``: new ``defocused`` property for starting screens without keyboard focus
- ``dfhack.units``: allow historical figures to be passed instead of units for ``getReadableName``, ``getVisibleName``, and ``getProfessionName``
- ``dfhack.items.moveToInventory``: make ``use_mode`` and ``body_part`` args optional
- ``dfhack.units``: add ``getRaceReadableName``, ``getRaceReadableNameById``, ``getRaceNamePluralById``

## Removed
- The ``PRELOAD_LIB`` environment variable has been renamed to ``DF_PRELOAD`` to match the naming scheme of other environment variables used by the ``dfhack`` startup script. If you are preloading libraries (e.g. for performance testing) please define ``DF_PRELOAD`` instead of ``PRELOAD_LIB`` or ``LD_PRELOAD``
- ``cuboid::clamp(bool block)``: renamed to ``cuboid::clampMap(bool block)``, name taken by ``cuboid::clamp(cuboid other)``
- ``Units::MAX_COLORS``, ``Units::findIndexById``, ``Units::getNumUnits``, ``Units::getUnit``: replaced by ``DFHack::COLOR_MAX`` and the generated type-specific ``get_vector`` functions
- ``Units::getPhysicalDescription``: function requires DF call point that is no longer available. alternative is to navigate the unit info sheet and extract the description from the UI (see `markdown`)

# 50.13-r3

## New Tools
- `plant`: (reinstated) tool for creating/growing/removing plants

## New Features
- `tweak`: ``named-codices``: display book titles instead of a material description in the stocks/trade screens
- `logistics`: automatically forbid or claim items brought to a stockpile
- `plant`: can now ``remove`` shrubs and saplings; ``list`` all valid shrub/sapling raw IDs; ``grow`` can make mature trees older; many new command options
- Locale-sensitive number formatting: select your preferred format in `gui/control-panel`. prices and other large numbers in DFHack UIs can be displayed with commas (English formatting), the number formatting used by your system locale, in SI units (e.g. ``12.3k``), or even in scientific notation

## Fixes
- ``Gui::makeAnnouncement``, ``Gui::autoDFAnnouncement``: fix case where a new announcement is created instead of adding to the count of an existing announcement if the existing announcement was the first one in the reports vector
- `regrass`: don't remove mud on regrass, consistent with vanilla behavior
- `seedwatch`: display a limit of ``-`` instead of ``0`` for a seed that is present in inventory but not being watched
- `tiletypes`: make aquifers functional when adding the ``aquifer`` property and there are no existing aquifer tiles in the same map block
- `seedwatch`: do not include unplantable tree seeds in status report
- ``Buildings::containsTile``: fix result for buildings that are solid and have no extent structures
- Mortal mode: prevent keybindings that run armok tools from being recognized when in mortal mode
- `dig`: don't leave phantom dig designations behind when autodigging warm/damp designated tiles
- `buildingplan`: properly identify appropriate construction items for modded buildings built from thread
- `overlay`: overlay positions are now adjusted according to the configured max interface width percentage in the DF settings
- `zone`: animal assignment overlay button moved to not conflict with vanilla aquarium/terrarium button on glass cages
- `zone`: allow friendly creatures to be released from cages by assigning them to a pasture zone and then unassigning them
- `autobutcher`: fix inverted ranking of which animals to butcher first

## Misc Improvements
- `blueprint`: capture track carving designations in addition to already-carved tracks
- `changevein`: follow veins into adjacent map blocks so you can run the command once instead of once per map block that the vein crosses
- `regrass`: now accepts numerical IDs for grass raws; ``regrass --list`` replaces ``regrass --plant ""``
- `tiletypes`: performance improvements when affecting tiles over a large area
- `tiletypes`: support for creating heavy aquifers
- `tiletypes`: new ``autocorrect`` property for autocorrecting adjacent tiles when making changes (e.g. adding ramp tops when you add a ramp)
- Dreamfort: add a full complement of beds and chests to both barracks
- Dreamfort: redesign guildhall/temple/library level for better accessibility
- Dreamfort: walkthrough documentation refresh
- Dreamfort: add milking/shearing station in surface grazing pasture
- Dreamfort: integrate building prioritization into the blueprints and remove `prioritize` checklist steps
- Dreamfort: add plumbing template for filling cisterns with running water
- `buildingplan`: add option to ignore items from a specified burrow
- `autobutcher`: do not butcher pregnant (or brooding) females
- `quickfort`: support buildable instruments
- `orders`: you can now delete your exported orders from the import dialog
- `nestboxes`: increase the scanning frequency for fertile eggs to reduce the chance that they get snarfed by eager dwarves
- `autonestbox`: wait until juveniles become adults before they are assigned to nestboxes
- `suspendmanager`: add option to ``unsuspend`` that unsuspends all jobs, regardless of potential issues (like blocking other construction jobs)
- `gui/create-item`: allow right click to cancel out of material dialog submenus

## Documentation
- `installing`: add instructions for how to use Steam DFHack with non-Steam DF (e.g. to benefit from DFHack auto-updates and cloud backups)
- `modding-guide`: add a section on persistent storage, both for global settings and world-specific settings
- Developer's primer for DFHack's type identity system

## API
- Focus strings have moved for stockpile states: ``dwarfmode/CustomStockpile`` is now ``dwarfmode/Stockpile/Some/Customize`` and similar for ``dwarfmode/StockpileTools`` and ``dwarfmode/StockpileLink``
- ``Buildings::getName``: get a building's name
- ``Maps::isTileAquifer``, ``Maps::isTileHeavyAquifer``, ``Maps::setTileAquifer``, ``Maps::removeTileAquifer``, ``Maps::setAreaAquifer``, ``Maps::removeAreaAquifer``: new aquifer detection and modification API
- ``Units::create``, ``Units::makeown``: new APIs to use bay12-provided entry points for low-level operations
- ``format_number``: format numbers according to the configured player formatting preference
- ``Items::remove``: now cancels related jobs and marks the item as hidden and forbidden until it can be garbage collected
- ``Job::addGeneralRef``: new easy API for creating general references and adding them to a Job
- ``Job::addWorker``: new API function for assigning a job to unit

## Lua
- ``dfhack.gui.getSelectedJob``: can now return the job with a destination under the keyboard cursor (e.g. digging/carving/engraving jobs)
- ``widgets.makeButtonLabelText``: create text and graphical buttons from character/color/tile maps and/or dynamically loaded tilesets
- ``widgets.DimensionsTooltip``: reusable selected dimensions tooltip that follows the mouse cursor around
- ``widgets.ButtonGroup``: subclass of CycleHotkeyLabel that additionally displays clickable graphical buttons
- ``widgets.CycleHotkeyLabel``: when the widget has both forward and backward hotkeys defined, support moving backwards by clicking on the appropriate hotkey hint
- ``safe_index``: will now return nil when attempting to index into a non-indexable object
- ``script-manager``: add ``getModSourcePath`` and ``getModStatePath`` so modders can get the directory path to their own files
- ``widgets.FilteredList``: don't restrict the player from inputting multiple successive space characters
- ``dfhack.maps.isTileAquifer``, ``dfhack.maps.isTileHeavyAquifer``, ``dfhack.maps.setTileAquifer``, ``dfhack.maps.removeTileAquifer``: access to new aquifer API
- ``plugins.tiletypes.tiletypes_setTile``: can now accept a table for access to previously unavailable options
- ``dialogs.showYesNoPrompt``: extend options so the standard dialog can be used for `gui/confirm`-style confirmation prompts
- ``dfhack.units.create``, ``dfhack.units.makeown``: Lua access to new module API
- ``dfhack.formatInt``, ``dfhack.formatFloat``: formats numbers according to the player preferences for number formatting set in `gui/control-panel`
- ``gui.get_interface_rect``, ``gui.get_interface_frame``: convenience functions for working with scaled interfaces
- ``overlay``: new attributes: ``fullscreen`` and ``full_interface`` for overlays that need access to the entire screen or the scaled interface area, respectively
- ``string:wrap``: now preserves inter-word spacing and can return the wrapped lines as a table of strings instead of a single multi-line string
- ``dfhack.internal.getClipboardTextCp437Multiline``: for retrieving multiline text from the system clipboard

## Removed
- `plants`: renamed to `plant`
- ``gui.FramedScreen``: this class is now deprecated; please use ``gui.ZScreen`` and ``widgets.Window`` instead
- ``dfhack.HIDE_CONSOLE_ON_STARTUP`` and ``dfhack.HIDE_ARMOK_TOOLS`` are no longer directly accessible. Please use `control-panel` or `gui/control-panel` to interact with those settings.

# 50.13-r2.1

## Fixes
- `suspendmanager`: stop suspending single tile stair constructions

# 50.13-r2

## New Tools
- Updated for adventure mode: `reveal`

## New Features
- `buildingplan`: quick material filter favorites on main planner panel
- DFHack and the Dwarf Fortress translation project can now both be run at the same time

## Fixes
- `zone`: fix display of distance from cage/pit for small pets in assignment dialog
- `blueprint`: correctly define stockpile boundaries in recorded stockpile ("place") blueprints when there are adjacent non-rectangular stockpiles of identical types
- `dig`: refresh count of tiles that will be modified by "mark all designated tiles on this z-level for warm/damp dig" when the z-level changes
- `dig`: don't affect already-revealed tiles when marking z-level for warm/damp dig
- `zone`: refresh values in distance column when switching selected pastures when the assign animals dialog is open
- `logistics`: include semi-wild pets when autoretrain is enabled
- `suspendmanager`: fully suspend unbuildable dead ends (e.g. building second level of a wall when the wall top is only accessible via ramp, causing the planned wall to be pathable but not buildable)
- `prospect`: don't use scientific notation for representing large numbers

## Misc Improvements
- `caravan`: display who is in the cages you are selecting for trade and whether they are hostile
- `regrass`: can now add grass to stairs, ramps, ashes, buildings, muddy stone, shrubs, and trees
- `regrass`: can now restrict area of effect to specified tile, block, cuboid, or z-levels
- `regrass`: can now add grass in map blocks where there hasn't been any
- `regrass`: can now choose specific grass type
- `dig`: warm/damp/aquifer status will now be shown in mining mode for tiles that your dwarves can see from the level below
- `dig`: warm/damp/aquifer status will now be shown when in smoothing/engraving modes
- `stockpiles`: support import and export "desired items" configuration for route stops
- New commandline options for controlling the Cloud Save coprocess when launching from Steam. See the `dfhack-core` documentation for details.
- `markdown`: new keybinding for triggering text export: Ctrl-t (when unit or item is selected)
- `flashstep`: new keybinding for teleporting adventurer to the mouse cursor: Ctrl-t (when adventure map is in the default state and mortal mode is disabled in DFHack preferences)
- Dreamfort: move wells on services level so brawling drunken tavern patrons are less likely to fall in
- `unretire-anyone`: new keybinding for adding a historical figure to the adventurer selection list in the adventure mode setup screen: Ctrl-a

## Documentation
- Quickfort Blueprint Library: add demo videos for pump stack and light aquifer tap blueprints
- Update docs for dependency requirements and compilation procedures

## API
- ``dfhack.items.getReadableDescription()``: easy API for getting a human-readable item description with useful annotations and information (like tattered markers or who is in a cage)
- ``Items::createItem``: now returns a list of item pointers rather than a single ID, moved creator parameter to beginning, added growth_print and no_floor parameters at end
- ``World::getAdventurer``: returns current adventurer unit
- ``World::ReadPauseState``: now returns true when the game is effectively paused due to a large panel obscuring the map. this aligns the return value with the visual state of the pause button when in fort mode.

## Lua
- ``dfhack.internal.setClipboardTextCp437Multiline``: for copying multiline text to the system clipboard
- ``dfhack.world.getAdventurer``: returns current adventurer unit
- ``dfhack.items.createItem``: return value and parameters have changed as per C++ API

# 50.13-r1.1

## Documentation
- Update docs on release procedures and symbol generation

# 50.13-r1

## Fixes
- Fixed misidentification of visitors from your own civ as residents; affects all tools that iterate through citizens/residents
- `cursecheck`: act on selected unit only if a unit is selected
- Fixed incorrect DFHack background window texture when DF is started in ascii mode and subsequently switched to graphics mode

## Misc Improvements
- `suspendmanager`: Account for walls planned on the z-layer below when determining accessibility to a job

## Documentation
- `autoclothing`: add section comparing ``autoclothing`` and `tailor` to guide players choosing which to enable

# 50.12-r3

## New Tools
- `aquifer`: commandline tool for creating, draining, and modifying aquifers

## New Features
- `buildingplan`: add overlays for unlinking and freeing mechanisms from buildings
- `dig`: designate tiles for damp or warm dig, which allows you to dig through damp or warm tiles without designations being canceled
- `dig`: damp and warm tile icons now remain visible when included in the designation selection box (graphics mode)
- `dig`: aquifer tiles are now visually distinct from "just damp" tiles (graphics and ascii modes)
- `dig`: light aquifer tiles are now visually distinct from heavy aquifer tiles (graphics and ascii modes)
- `dig`: autodig designations that are marked for damp/warm dig propagate the damp/warm tag when expanding to newly exposed tiles
- `blueprint`: designations and active dig jobs are now captured in generated blueprints
- `blueprint`: warm/damp dig markers are captured in generated blueprints

## Fixes
- fix behavior of Linux Steam launcher on systems that don't support the inotify API
- fix rendering of resize "notch" in lower right corner of resizable windows in ascii mode
- `quickfort`: stockpiles can now be placed even if there is water covering the tile, as per vanilla behavior
- `suspendmanager`: prevent cancellation spam when an item is preventing a building from being completed
- `stonesense`: fix a crash with buildings made of unusual materials (such as campsite tents made out of organic "walls")

## Misc Improvements
- `tailor`: allow turning off automatic confiscation of tattered clothing
- aquifer_tap blueprint: now designates in damp dig mode for uninterrupted digging in a light aquifer
- pump_stack blueprint: now designates in warm and damp dig mode for uninterrupted digging through warm and damp tiles
- `keybinding`: you can now assign keybindings to mouse buttons (if your mouse has more than the three buttons already used by DF)

## Documentation
- Lua API: documented existing ``enum:next_item(index)`` function

## API
- ``Units::citizensRange``: c++-20 std::range filter for citizen units
- ``Units::forCitizens``: iterator callback function for citizen units
- ``Units::paintTile``, ``Units::readTile``: now takes an optional field specification for reading and writing to specific map compositing layers
- ``Buildings::checkFreeTiles``: now takes a ``allow_flow`` parameter to control whether water- or magma-filled tiles are valid

## Lua
- ``dfhack.gui.matchFocusString``: focus string matching is now case sensitive (for performance reasons)

# 50.12-r2.1

## Fixes
- `orders`: don't intercept keyboard input for setting skill or labor restrictions on workshop workers tab when the player is setting the building nickname

# 50.12-r2

## New Features
- `stocks`: add button/hotkey for removing empty categories from the stocks list
- `sort`: updated and reinstated military status/squad membership/burrow membership filter for work animal assignment screen
- `logistics`: ``autoretrain`` will automatically assign trainers to your partially-trained (but not yet domesticated) livestock. this prevents children of partially-trained parents from reverting to wild if you don't notice they were born
- `orders`: add overlay for configuring labor and skill level restrictions for workshops

## Fixes
- `autochop`: fix underestimation of log yield for cavern mushrooms
- `gui/notify`: prevent notification overlay from showing up in arena mode
- `logistics`: don't melt/trade/dump empty containers that happen to be sitting on the stockpile unless the stockpile accepts those item types
- `gui/launcher`: fix detection on Shift-Enter for running commands and autoclosing the launcher
- `logistics`: don't send autotrade items to forbidden depots
- `autoclothing`: don't produce clothes for dead units
- `caravan`: fix trade price calculations when the same item was requested for both import and export

## Misc Improvements
- `autobutcher`: prefer butchering partially trained animals and save fully domesticated animals to assist in wildlife domestication programs
- `autodump`: can now teleport items loosely stored in buildings (clutter)
- When launched from the Steam client on Linux, both Dwarf Fortress and DFHack will be shown as "Running". This ensures that DF has proper accounting for Linux player usage.
- `suspendmanager`: improve performance when there are many active jobs
- `clean`: protect farm plots when cleaning mud
- `tweak`: add ``quiet`` option for silent enablement and disablement of tweaks
- `gui/teleport`: add global Ctrl-Shift-T keybinding (only available when DFHack mortal mode is disabled)
- Dreamfort: the four Craftsdwarf's workshops on the industry level are now specialized for Stonecrafting, Woodcrafting, Bone Carving, and miscellaneous tasks, respectively
- `dwarfvet`: automatically unassign animals from pastures when they need treatment so they can make their way to the hospital. reassign them to their original pasture when treatment is complete.
- `dwarfvet`: ignore animals assigned to cages or restraints
- Many tools that previously only worked for citizens or only for dwarves now work for all citizens and residents, e.g. `fastdwarf`, `rejuvenate`, etc.
- `buildingplan`: remember player preference for whether unavailable materials should be hidden in the filter selection dialog
- `buildingplan`: sort by available quantity by default int he filter selection dialog
- Dreamfort: update embark profile recommendations and example embark profile

## Documentation
- `overlay-dev-guide`: updated examples and troubleshooting steps
- `introduction`: refresh getting started content
- `quickstart`: refresh quickstart guide

## API
- ``Units::isForgottenBeast``: property check for forgotten beasts
- ``Units::isGreatDanger``: now includes forgotten beasts
- ``Units::isResident``: property check for residents (as opposed to citizens)
- ``Units::getCitizens``: now includes residents by default

## Lua
- ``widgets.Label``: ``*pen`` attributes can now either be a pen or a function that dynamically returns a pen
- `helpdb`: ``search_entries`` now returns a match if *all* filters in the ``include`` list are matched. previous behavior was to match if *any* ``include`` filter matched.
- ``matinfo.decode``: now directly handles plant objects
- ``dfhack.units.isForgottenBeast``: make new units method available to Lua
- ``dfhack.units.getCitizens``: now includes residents by default

# 50.12-r1.1

## Fixes
- `sort`: fix crash when assigning work animals to units

## Removed
- offline HTML rendered docs are no longer distributed with DFHack since they are randomly triggering Windows Defender antivirus heuristics. If you want to download DFHack docs for offline browsing, you can still get them from the Downloads link at https://dfhack.org/docs

# 50.12-r1

## Misc Improvements
- `sort`: squad assignment overlay rewritten for compatibility with new vanilla data structures and screen layouts

## Fixes
- `gui/design`: no longer comes up when Ctrl-D is pressed but other DFHack windows have focus

## API

- ``Gui::getWidget``: retrieve a vanilla DF widget by name or index

## Lua

- ``dfhack.gui.getWidget``: retrieve a vanilla DF widget by hierarchy path, with each step specified by a widget name or index
- ``dfhack.gui.getWidgetChildren``: retrieve a list of child widgets for a given widget container

## Removed
- `burrow`: removed overlay 3D box select since it is now provided by the vanilla UI
- `sort`: removed Search widgets for screens that now have vanilla search

# 50.11-r7

## New Tools
- `tweak`: (reinstated) a collection of small bugfixes and gameplay tweaks
- `pet-uncapper`: (reinstated, renamed from ``petcapRemover``) allow pets to breed beyond the default population cap of 50

## New Features
- `cleanowned`: Add a "nodump" option to allow for confiscating items without dumping
- `tweak`: Add "flask-contents", makes flasks/vials/waterskins be named according to their contents

## Fixes
- `dig`: overlay that shows damp designations in ASCII mode now properly highlights tiles that are damp because of an aquifer in the layer above
- `dig-now`: fix digging stairs in the surface sometimes creating underworld gates.
- ``Units::getVisibleName``: don't reveal the true identities of units that are impersonating other historical figures
- ``Gui::revealInDwarfmodeMap``: properly center the zoom even when the target tile is near the edge of the map
- `warn-stranded`: don't complain about units that aren't on the map (e.g.  soldiers out on raids)
- `autoclothing`: Fix enabled behavior
- ``Gui::makeAnnouncement``, ``Gui::autoDFAnnouncement``: don't display popup for all announcement types
- ``gui.View:getMouseFramePos``: function now detects the correct coordinates even when the widget is nested within other frames
- `strangemood`: correctly recognize Stonecutter and Stone Carver as moodable skills, move the Mason's boosted mood chance to the Stone Carver, and select Fell/Macabre based on long-term stress

## Misc Improvements
- `autonestbox`: assign egg layers to the nestbox they have chosen if they have already chosen a nestbox
- `regrass`: also regrow depleted cavern moss
- `probe`: act on the selected building/unit instead of requiring placement of the keyboard cursor for ``bprobe`` and ``cprobe``
- `buildingplan`: use closest matching item rather than newest matching item
- `zone`: animal assignment dialog now shows distance to pasture/cage and allows sorting by distance
- `zone`: animal assignment dialog shows number of creatures assigned to this pasture/cage/etc.

## API
- Gui module Announcement functions now use DF's new announcement alert system
- ``Gui::addCombatReport``, ``Gui::addCombatReportAuto``: add versions that take ``report *`` instead of report vector index
- ``Gui::MTB_clean``, ``Gui::MTB_parse``, ``Gui::MTB_set_width``: new functions for manipulating ``markup_text_boxst``
- ``toupper_cp437(char)``, ``tolower_cp437(char)``: new ``MiscUtils`` functions, return a char with case changed, respecting CP437
- ``toUpper``, ``toLower``: ``MiscUtils`` functions renamed to ``toUpper_cp437`` and ``toLower_cp437``, CP437 compliant
- Gui focus strings will now include ``dwarfmode/Default`` if the only other panel open is the Squads panel
- ``Gui::revealInDwarfmodeMap``: unfollow any currently followed units/items so the viewport doesn't just jump back to where it was

## Lua
- Overlay framework now respects ``active`` and ``visible`` widget attributes
- ``dfhack.gui`` announcement functions use default arguments when omitted
- ``dfhack.units.getCitizens`` now only returns units that are on the map
- ``dfhack.upperCp437(string)``, ``dfhack.lowerCp437(string)``: new functions, return string with all chars changed, respecting CP437 code page

# 50.11-r6

## New Features
- `zone`: Add overlay for toggling butchering/gelding/adoption/taming options in animal "Overview" tabs

## Fixes
- `dig-now`: remove diagonal ramps rendered unusable by digging
- `dig-now`: fix error propagating "light" and "outside" properties to newly exposed tiles when piercing the surface
- `sort`: fix potential crash when switching between certain info tabs
- `suspendmanager`: overlays for suspended building info panels no longer disappear when another window has focus

## Misc Improvements
- `reveal`: automatically reset saved map state when a new save is loaded
- `autonestbox`: don't automatically assign partially trained egg-layers to nestboxes if they don't have an ongoing trainer assigned since they might revert to wild
- `buildingplan`: replace ``[edit filters]`` button in planner overlay with abbreviated filter information

## API
- ``Units::assignTrainer``: assign a trainer to a trainable animal
- ``Units::unassignTrainer``: unassign a trainer from an animal
- ``Gui::getAnyWorkshopJob``: get the first job associated with the selected workshop
- ``Gui::getAnyJob``: get the job associated with the selected game element (item, unit, workshop, etc.)

## Lua
- ``dfhack.units.isTamable``: return false for invaders to match vanilla logic
- ``dfhack.units.assignTrainer``: expose API to Lua
- ``dfhack.units.unassignTrainer``: expose API to Lua
- ``dfhack.gui.getAnyWorkshopJob``: expose API to Lua
- ``dfhack.gui.getAnyJob``: expose API to Lua

## Removed
- ``nopause``: functionality has moved to `spectate`

# 50.11-r5

## New Tools
- `gui/embark-anywhere`: new keybinding (active when choosing an embark site): Ctrl-A

## New Features
- `sort`: search and sort for the "choose unit to elevate to the barony" screen. units are sorted by the number of item preferences they have and the units are annotated with the items that they have preferences for
- `zone`: add button to location details page for retiring unused locations
- `gui/mass-remove`: new global keybinding: Ctrl-M while on the fort map

## Fixes
- `reveal`: now avoids revealing blocks that contain divine treasures, encased horrors, and deep vein hollows (so the surprise triggers are not triggered prematurely)
- `sort`: fix mouse clicks falling through the squad assignment overlay panel when clicking on the panel but not on a clickable widget
- `sort`: fix potential crash when removing jobs directly from the Tasks info screen
- `misery`: fix error when changing the misery factor
- When passing map movement keys through to the map from DFHack tool windows, also pass fast z movements (shift-scroll by default)
- `getplants`: fix crash when processing mod-added plants with invalid materials
- Dreamfort: fix holes in the "Inside+" burrow on the farming level (burrow autoexpand is interrupted by the pre-dug miasma vents to the surface)
- ``Maps::getBiomeType``, ``Maps::getBiomeTypeWithRef``: fix identification of tropical oceans
- DFHack tabs (e.g. in `gui/control-panel`) are now rendered correctly when there are certain vanilla screen elements behind them
- `buildingplan`: when you save a game and load it again, newly planned buildings are now correctly placed in line after existing planned buildings of the same type
- `buildingplan`: treat items in wheelbarrows as unavailable, just as vanilla DF does. Make sure the `fix/empty-wheelbarrows` fix is enabled so those items aren't permanently unavailable!
- `buildingplan`: show correct number of materials required when laying down areas of constructions and some of those constructions are on invalid tiles
- `stonesense`: fix crash in cleanup code after mega screenshot (Ctrl-F5) completes; however, the mega screenshot will still make stonesense unresponsive. close and open the stonesense window to continue using it.
- `gui/design`: fix incorrect highlight when box selecting area in ASCII mode
- `fastdwarf`: prevent units from teleporting to inaccessible areas when in teledwarf mode
- `fastdwarf`: allow units to meander and satisfy needs when they have no current job and teledwarf mode is enabled

## Misc Improvements
- `autochop`: better error output when target burrows are not specified on the commandline
- `autoclothing` : now does not consider worn (x) clothing as usable/available; reduces overproduction when using `tailor` at same time
- `buildingplan`: add option for preventing constructions from being planned on top of existing constructions (e.g. don't build floors on top of floors)
- `burrow`: flood fill now requires an explicit toggle before it is enabled to help prevent accidental flood fills
- wherever units are listed in DFHack tools, properties like "agitated" or (-trained-) are now shown
- `work-now`: now saves its enabled status with the fort
- `fastdwarf`: now saves its state with the fort
- `zone`: add include/only/exclude filter for juveniles to the pasture/pit/cage/restraint assignment screen
- The "PAUSE FORCED" badge will blink briefly to draw attention if the player attempts to unpause when a DFHack tool window requires the game to be paused
- `sort`: add "Toggle all filters" hotkey button to the squad assignment panel
- `sort`: rename "Weak mental fortitude" filter to "Dislikes combat", which should be more understandable
- Dreamfort: put more chairs adjacent to each other to make the tavern more "social"
- `zone`: show geld status and custom profession (if set, it's the lower editable line in creature description) in pasture/pit/cage/restraint assignment screen
- `orders`: reduce prepared meal target and raise booze target in ``basic`` importable orders in the orders library

## Documentation
- `installing`: Add installation instructions for wineskin on Mac
- UTF-8 text in tool docs is now properly displayed in-game in `gui/launcher` (assuming that it can be converted to cp-437)
- `modding-guide`: Add examples for script-only and blueprint-only mods that you can upload to DF's Steam Workshop
- DFHack developer's guide updated, with refreshed `architectural-diagrams`

## API
- ``random_index``, ``vector_get_random``: new ``MiscUtils`` functions, for getting a random entry in a vector
- ``capitalize_string_words``: new ``MiscUtils`` function, returns string with all words capitalized
- ``grab_token_string_pos``: new ``MiscUtils`` function, used for parsing tokens
- ``Items``: add item melting logic ``canMelt(item)``, ``markForMelting(item)``, and ``cancelMelting(item)``
- ``World``: ``GetCurrentSiteId()`` returns the loaded fort site ID (or -1 if no site is loaded)
- ``World``: ``IsSiteLoaded()`` check to detect if a site (e.g. a player fort) is active (as opposed to the world or a map)
- ``World``: ``AddPersistentData`` and related functions replaced with ``AddPersistentSiteData`` and ``AddPersistentWorldData`` equivalents
- New plugin API for saving and loading persistent data. See plugins/examples/skeleton.cpp and plugins/examples/persistent_per_save_example.cpp for details
- Plugin ABI (binary interface) version bump! Any external plugins must be recompiled against this version of DFHack source code in order to load.
- ``Persistence``: persistent keys are now namespaced by an entity_id (e.g. a player fort site ID)
- ``Persistence``: data is now stored one file per entity ID (plus one for the global world) in the DF savegame directory
- ``Units.isDanger``: now returns true for agitated wildlife
- ``Constructions::designateRemove``: no longer designates the non-removable "pseudo" constructions that represent the top of walls

## Lua
- ``dfhack.capitalizeStringWords``: new function, returns string with all words capitalized
- ``widgets.Divider``: linear divider to split an existing frame; configurable T-junction edges and frame style matching
- ``dfhack.persistent``: new, table-driven API for easier world- and site-associated persistent storage. See the Lua API docs for details.
- ``dfhack.isSiteLoaded``: returns whether a site (e.g. a player fort) is loaded
- ``dfhack.items``: access to ``canMelt(item)``, ``markForMelting(item)``, and ``cancelMelting(item)`` from ``Items`` module
- ``dfhack.world.getCurrentSite``: returns the ``df.world_site`` instance of the currently loaded fort

## Removed
- ``persist-table``: replaced by new ``dfhack.persistent`` API
- `channel-safely`: (temporarily) removed due to stability issues with the underlying DF API

# 50.11-r4

## Fixes
- `buildingplan`: fix choosing the wrong mechanism (or something that isn't a mechanism) when linking a lever and manually choosing a mechanism, but then canceling the selection
- RemoteServer: don't shut down the socket prematurely, allowing continuing connections from, for example, dfhack-run
- `sort`: fix potential crash when exiting and re-entering a creatures subtab with a search active
- `sort`: prevent keyboard keys from affecting the UI when search is active and multiple keys are hit at once
- `tailor`: fix corner case where existing stock was being ignored, leading to over-ordering

## Misc Improvements
- `buildingplan`: save magma safe mechanisms for when magma safety is requested when linking levers and pressure plates to targets
- `buildingplan`: when choosing mechanisms for linking levers/pressure plates, filter out unreachable mechanisms
- `sort`: when searching on the Tasks tab, also search the names of the things the task is associated with, such as the name of the stockpile that an item will be stored in

# 50.11-r3

## New Tools
- `burrow`: (reinstated) automatically expand burrows as you dig

## New Features
- `prospect`: can now give you an estimate of resources from the embark screen. hover the mouse over a potential embark area and run `prospect`.
- `burrow`: integrated 3d box fill and 2d/3d flood fill extensions for burrow painting mode
- `buildingplan`: allow specific mechanisms to be selected when linking levers or pressure plates
- `sort`: military and burrow membership filters for the burrow assignment screen

## Fixes
- `stockpiles`: hide configure and help buttons when the overlay panel is minimized
- `caravan`: price of vermin swarms correctly adjusted down. a stack of 10000 bees is worth 10, not 10000
- `sort`: when filtering out already-established temples in the location assignment screen, also filter out the "No specific deity" option if a non-denominational temple has already been established
- RemoteServer: continue to accept connections as long as the listening socket is valid instead of closing the socket after the first disconnect
- `buildingplan`: overlay and filter editor gui now uses ctrl-d to delete the filter to avoid conflict with increasing the filter's minimum quality (shift-x)
- `tailor`: fix crash on Linux where scanned unit is wearing damaged non-clothing (e.g. a crown)

## Misc Improvements
- `buildingplan`: display how many items are available on the planner panel
- `buildingplan`: make it easier to build single-tile staircases of any shape (up, down, or up/down)
- `sort`: allow searching by profession on the squad assignment page
- `sort`: add search for places screens
- `sort`: add search for work animal assignment screen; allow filtering by military/squad/civilian/burrow
- `sort`: on the squad assignment screen, make effectiveness and potential ratings use the same scale so effectiveness is always less than or equal to potential for a given unit. this way you can also tell when units are approaching their maximum potential
- `sort`: new overlay on the animal assignment screen that shows how many work animals each visible unit already has assigned to them
- `dreamfort`: Inside+ and Clearcutting burrows now automatically created and managed

## Documentation
- Document the Lua API for the ``dfhack.world`` module

## API
- ``Gui::revealInDwarfmodeMap``: gained ``highlight`` parameter to control setting the tile highlight on the zoom target
- ``Maps::getWalkableGroup``: get the walkability group of a tile
- ``Units::getReadableName``: now returns the *untranslated* name
- ``Burrows::setAssignedUnit``: now properly handles inactive burrows
- ``Gui::getMousePos``: now takes an optional ``allow_out_of_bounds`` parameter so coordinates can be returned for mouse positions outside of the game map (i.e. in the blank space around the map)
- ``Buildings::completebuild``: used to link a newly created building into the world

## Lua
- ``dfhack.gui.revealInDwarfmodeMap``: gained ``highlight`` parameter to control setting the tile highlight on the zoom target
- ``dfhack.maps.getWalkableGroup``: get the walkability group of a tile
- ``dfhack.gui.getMousePos``: support new optional ``allow_out_of_bounds`` parameter
- ``gui.FRAME_THIN``: a panel frame suitable for floating tooltips
- ``dfhack.buildings.completebuild``: expose new module API

# 50.11-r2

## New Tools
- `spectate`: (reinstated) automatically follow dwarves, cycling among interesting ones
- `preserve-tombs`: keep tombs assigned to units when they die

## New Features
- `logistics`: ``automelt`` now optionally supports melting masterworks; click on gear icon on `stockpiles` overlay frame
- `sort`: new search widgets for Info panel tabs, including all "Creatures" subtabs, all "Objects" subtabs, "Tasks", candidate assignment on the "Noble" subtab, and the "Work details" subtab under "Labor"
- `sort`: new search and filter widgets for the "Interrogate" and "Convict" screens under "Justice"
- `sort`: new search widgets for location selection screen (when you're choosing what kind of guildhall or temple to dedicate)
- `sort`: new search widgets for burrow assignment screen and other unit assignment dialogs
- `sort`: new search widgets for artifacts on the world/raid screen
- `sort`: new search widgets for slab engraving menu; can filter for only units that need a slab to prevent rising as a ghost
- `stocks`: hotkey for collapsing all categories on stocks screen

## Fixes
- `buildingplan`: remove bars of ash, coal, and soap as valid building materials to match v50 rules
- `buildingplan`: fix incorrect required items being displayed sometimes when switching the planner overlay on and off
- `zone`: races without specific child or baby names will now get generic child/baby names instead of an empty string
- `zone`: don't show animal assignment link for cages and restraints linked to dungeon zones (which aren't normally assignable)
- `sort`: don't count mercenaries as appointed officials in the squad assignment screen
- `dwarfvet`: fix invalid job id assigned to ``Rest`` job, which could cause crashes on reload

## Misc Improvements
- `overlay`: allow ``overlay_onupdate_max_freq_seconds`` to be dynamically set to 0 for a burst of high-frequency updates
- Help icons added to several complex overlays. clicking the icon runs `gui/launcher` with the help text in the help area
- `orders`: ``recheck`` command now only resets orders that have conditions that can be rechecked
- `sort`: added help button for squad assignment search/filter/sort
- `zone`: animals trained for war or hunting are now labeled as such in animal assignment screens
- `buildingplan`: support filtering cages by whether they are occupied
- `buildingplan`: show how many items you need to make when planning buildings
- `tailor`: now adds to existing orders if possible instead of creating new ones

## Documentation
- unavailable tools are no longer listed in the tag indices in the online docs

## API
- added ``Items::getCapacity``, returns the capacity of an item as a container (reverse-engineered), needed for `combine`

## Lua
- added ``GRAY`` color aliases for ``GREY`` colors
- added ``dfhack.items.getCapacity`` to expose the new module API
- ``utils.search_text``: text search routine (generalized from internal ``widgets.FilteredList`` logic)

## Removed
- ``FILTER_FULL_TEXT``: moved from ``gui.widgets`` to ``utils``; if your full text search preference is lost, please reset it in `gui/control-panel`

# 50.11-r1

## New Tools
- `tubefill`: (reinstated) replenishes mined-out adamantine

## Fixes
- `autolabor`: ensure vanilla work details are reinstated when the fort or the plugin is unloaded
- ``dfhack.TranslateName()``: fixed crash on certain invalid names, which affected `warn-starving`
- EventManager: Unit death event no longer misfires on units leaving the map

## Misc Improvements
- `digtype`: designate only visible tiles by default, and use "auto" dig mode for following veins
- `digtype`: added options for designating only current z-level, this z-level and above, and this z-level and below
- `hotkeys`: make the DFHack logo brighten on hover in ascii mode to indicate that it is clickable
- `hotkeys`: use vertical bars instead of "!" symbols for the DFHack logo in ascii mode to make it easier to read
- EventManager: guard against potential iterator invalidation if one of the event listeners were to modify the global data structure being iterated over
- EventManager: for ``onBuildingCreatedDestroyed`` events, changed firing order of events so destroyed events come before created events

## Lua
- mouse key events are now aligned with internal DF semantics: ``_MOUSE_L`` indicates that the left mouse button has just been pressed and ``_MOUSE_L_DOWN`` indicates that the left mouse button is being held down. similarly for ``_MOUSE_R`` and ``_MOUSE_M``. 3rd party scripts may have to adjust.

# 50.10-r1

## Fixes
- Linux launcher: allow Steam Overlay and game streaming to function
- `autobutcher`: don't ignore semi-wild units when marking units for slaughter

## Misc Improvements
- 'sort': Improve combat skill scale thresholds

# 50.09-r4

## New Features
- `dig`: new overlay for ASCII mode that visualizes designations for smoothing, engraving, carving tracks, and carving fortifications

## 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
- `gui/mod-manager`: don't continue to display overlay after the raws loading progress bar appears

## Misc Improvements
- `sort`: add sort option for training need 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
- add instructions for downloading development builds to the ``Installing`` page

## 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.

# 50.09-r3

## New Features
- `sort`: search, sort, and filter for squad assignment screen
- `zone`: advanced unit assignment screens for cages, restraints, and pits/ponds
- `buildingplan`: one-click magma/fire safety filter for planned buildings

## Fixes
- Core: reload scripts in mods when a world is unloaded and immediately loaded again
- Core: fix text getting added to DFHack text entry widgets when Alt- or Ctrl- keys are hit
- `buildingplan`: ensure selected barrels and buckets are empty (or at least free of lye and milk) as per the requirements of the building
- `orders`: prevent import/export overlay from appearing on the create workorder screen
- `caravan`: corrected prices for cages that have units inside of them
- `tailor`: remove crash caused by clothing items with an invalid ``maker_race``
- ``dialogs.MessageBox``: fix spacing around scrollable text
- `seedwatch`: ignore unplantable tree seeds
- `autobutcher`: fix ``ticks`` commandline option incorrectly rejecting positive integers as valid values

## Misc Improvements
- Surround DFHack-specific UI elements with square brackets instead of red-yellow blocks for better readability
- `autobutcher`: don't mark animals for butchering if they are already marked for some kind of training (war, hunt)
- `hotkeys`: don't display DFHack logo in legends mode since it covers up important interface elements. the Ctrl-Shift-C hotkey to bring up the menu and the mouseover hotspot still function, though.
- `sort`: animals are now sortable by race on the assignment screens
- `createitem`: support creating items inside of bags

## API
- ``Items::getValue()``: remove ``caravan_buying`` parameter since the identity of the selling party doesn't actually affect the item value
- `RemoteFortressReader`: add a ``force_reload`` option to the GetBlockList RPC API to return blocks regardless of whether they have changed since the last request
- ``Units``: new animal property check functions ``isMarkedForTraining(unit)``, ``isMarkedForTaming(unit)``, ``isMarkedForWarTraining(unit)``, and ``isMarkedForHuntTraining(unit)``
- ``Gui``: ``getAnyStockpile`` and ``getAnyCivzone`` (along with their ``getSelected`` variants) now work through layers of ZScreens. This means that they will still return valid results even if a DFHack tool window is in the foreground.

## Lua
- ``new()``: improved error handling so that certain errors that were previously uncatchable (creating objects with members with unknown vtables) are now catchable with ``pcall()``
- ``dfhack.items.getValue()``: remove ``caravan_buying`` param as per C++ API change
- ``widgets.BannerPanel``: panel with distinctive border for marking DFHack UI elements on otherwise vanilla screens
- ``widgets.Panel``: new functions to override instead of setting corresponding properties (useful when subclassing instead of just setting attributes): ``onDragBegin``, ``onDragEnd``, ``onResizeBegin``, ``onResizeEnd``
- ``dfhack.screen.readTile()``: now populates extended tile property fields (like ``top_of_text``) in the returned ``Pen`` object
- ``dfhack.units``: new animal property check functions ``isMarkedForTraining(unit)``, ``isMarkedForTaming(unit)``, ``isMarkedForWarTraining(unit)``, and ``isMarkedForHuntTraining(unit)``
- ``dfhack.gui``: new ``getAnyCivZone`` and ``getAnyStockpile`` functions; also behavior of ``getSelectedCivZone`` and ``getSelectedStockpile`` functions has changes as per the related API notes

# 50.09-r2

## New Plugins
- `3dveins`: reinstated for v50, this plugin replaces vanilla DF's blobby vein generation with veins that flow smoothly and naturally between z-levels
- `zone`: new searchable, sortable, filterable screen for assigning units to pastures
- `dwarfvet`: reinstated and updated for v50's new hospital mechanics; allow your animals to have their wounds treated at hospitals
- `dig`: new ``dig.asciiwarmdamp`` overlay that highlights warm and damp tiles when in ASCII mode. there is no effect in graphics mode since the tiles are already highlighted there

## Fixes
- Fix extra keys appearing in DFHack text boxes when shift (or any other modifier) is released before the other key you were pressing
- `logistics`: don't autotrain domestic animals brought by invaders (they'll get attacked by friendly creatures as soon as you let them out of their cage)
- `logistics`: don't bring trade goods to depot if the only caravans present are tribute caravans
- `gui/create-item`: when choosing a citizen to create the chosen items, avoid choosing a dead citizen
- `logistics`: fix potential crash when removing stockpiles or turning off stockpile features

## Misc Improvements
- `stockpiles`: include exotic pets in the "tameable" filter
- `logistics`: bring an autotraded bin to the depot if any item inside is tradeable instead of marking all items within the bin as untradeable if any individual item is untradeable
- `autonick`: add more variety to nicknames based on famous literary dwarves
- ``widgets.EditField``: DFHack edit fields now support cut/copy/paste with the system clipboard with Ctrl-X/Ctrl-C/Ctrl-V
- Suppress DF keyboard events when a DFHack keybinding is matched. This prevents, for example, a backtick from appearing in a textbox as text when you launch `gui/launcher` from the backtick keybinding.
- Dreamfort: give noble suites double-thick walls and add apartment doors

## Documentation
- `misery`: rewrite the documentation to clarify the actual effects of the plugin

## API
- ``Units::getUnitByNobleRole``, ``Units::getUnitsByNobleRole``: unit lookup API by role
- ``Items::markForTrade()``, ``Items::isRequestedTradeGood()``, ``Items::getValue``: see Lua notes below

## Internals
- Price calculations fixed for many item types

## Lua
- ``dfhack.units.getUnitByNobleRole``, ``dfhack.units.getUnitsByNobleRole``: unit lookup API by role
- ``dfhack.items.markForTrade``: mark items for trade
- ``dfhack.items.isRequestedTradeGood``: discover whether an item is named in a trade agreement with an active caravan
- ``dfhack.items.getValue``: gained optional ``caravan`` and ``caravan_buying`` parameters for prices that take trader races and agreements into account
- ``widgets.TextButton``: wraps a ``HotkeyLabel`` and decorates it to look more like a button

# 50.09-r1

## Internals

- Core: update SDL interface from SDL1 to SDL2

# 50.08-r4

## New Plugins
- `logistics`: automatically mark and route items or animals that come to monitored stockpiles. options are toggleable on an overlay that comes up when you have a stockpile selected.

## Fixes
- `buildingplan`: don't include artifacts when max quality is masterful
- `dig-now`: clear item occupancy flags for channeled tiles that had items on them
- `RemoteFortressReader`: fix a crash with engravings with undefined images

## Misc Improvements
- `autonick`: additional nicknames based on burrowing animals, colours, gems, and minerals
- `stockpiles`: added ``barrels``, ``organic``, ``artifacts``, and ``masterworks`` stockpile presets
- `orders`: only display import/export/sort/clear panel on main orders screen
- `orders`: refine order conditions for library orders to reduce cancellation spam
- Blueprint library: dreamfort: full rewrite and update for DF v50
- Blueprint library: pump_stack: updated walkthrough and separated dig and channel steps so boulders can be cleared
- Blueprint library: aquifer_tap: updated walkthrough
- `dig-now`: can now handle digging obsidian that has been formed from magma and water

## Documentation
- `blueprint-library-guide`: update Dreamfort screenshots and links, add ``aquifer_tap`` screenshot

# 50.08-r3

## Fixes
- Fix crash for some players when they launch DF outside of the Steam client

# 50.08-r2

## New Plugins
- `add-spatter`: (reinstated) allow mods to add poisons and magical effects to weapons
- `changeitem`: (reinstated) change item material, quality, and subtype
- `createitem`: (reinstated) create arbitrary items from the command line
- `deramp`: (reinstated) removes all ramps designated for removal from the map
- `flows`: (reinstated) counts map blocks with flowing liquids
- `lair`: (reinstated) mark the map as a monster lair (this avoids item scatter when the fortress is abandoned)
- `luasocket`: (reinstated) provides a Lua API for accessing network sockets
- `work-now`: (reinstated, renamed from ``workNow``) prevent dwarves from wandering aimlessly with "No job" after completing a task

## Fixes
- DFHack screen backgrounds now use appropriate tiles in DF Classic
- RemoteServer: fix crash on malformed json in ``dfhack-config/remote-server.json``
- `autolabor`: work detail override warning now only appears on the work details screen
- `RemoteFortressReader`: ensured names are transmitted in UTF-8 instead of CP437

## Misc Improvements
- `autodump`: no longer checks for a keyboard cursor before executing, so ``autodump destroy`` (which doesn't require a cursor) can still function
- Settings: recover gracefully when settings files become corrupted (e.g. by DF CTD)
- `orders`: update orders in library for prepared meals, bins, archer uniforms, and weapons
- `gui/control-panel`: new preference for whether filters in lists search for substrings in the middle of words (e.g. if set to true, then "ee" will match "steel")
- `gui/design`: Improved performance for drawing shapes
- Dreamfort: improve traffic patterns throughout the fortress
- `gui/blueprint`: recording of stockpile layouts and categories is now supported. note that detailed stockpile configurations will *not* be saved (yet)
- Core: new commandline flag/environment var: pass ``--disable-dfhack`` on the Dwarf Fortress commandline or specify ``DFHACK_DISABLE=1`` in the environment to disable DFHack for the current session.
- `overlay`: add links to the quickstart guide and the control panel on the DF title screen
- Window behavior: non-resizable windows now allow dragging by their frame edges by default
- `gui/autodump`: fort-mode keybinding: Ctrl-H (when ``armok`` tools are enabled in `gui/control-panel`)
- Window behavior: if you have multiple DFHack tool windows open, scrolling the mouse wheel while over an unfocused window will focus it and raise it to the top
- `stockpiles`: allow filtering creatures by tameability

## Internals
- ``dfhack.internal``: added memory analysis functions: ``msizeAddress``, ``getHeapState``, ``heapTakeSnapshot``, ``isAddressInHeap``, ``isAddressActiveInHeap``, ``isAddressUsedAfterFreeInHeap``, ``getAddressSizeInHeap``, and ``getRootAddressOfHeapObject``

## Lua
- ``overlay.reload()``: has been renamed to ``overlay.rescan()`` so as not to conflict with the global ``reload()`` function. If you are developing an overlay, please take note of the new function name for reloading your overlay during development.
- ``gui``: changed frame naming scheme to ``FRAME_X`` rather than ``X_FRAME``, and added aliases for backwards compatibility. (for example ``BOLD_FRAME`` is now called ``FRAME_BOLD``)
- ``ensure_keys``: walks a series of keys, creating new tables for any missing values

## Removed
- `orders`: ``library/military_include_artifact_materials`` library file removed since recent research indicates that platinum blunt weapons and silver crossbows are not more effective than standard steel. the alternate military orders file was also causing unneeded confusion.

# 50.08-r1

## Fixes
- `autoclothing`: eliminate game lag when there are many inventory items in the fort
- `buildingplan`: fixed size limit calculations for rollers
- `buildingplan`: fixed items not being checked for accessibility in the filter and item selection dialogs
- `dig-now`: properly detect and complete smoothing designations that have been converted into active jobs

## Misc Improvements
- `buildingplan`: planner panel is minimized by default and now remembers minimized state
- `buildingplan`: can now filter by gems (for gem windows) and yarn (for ropes in wells)
- ``toggle-kbd-cursor``: add hotkey for toggling the keyboard cursor (Alt-K)
- ``version``: add alias to display the DFHack help (including the version number) so something happens when players try to run "version"
- `gui/control-panel`: add preference option for hiding the terminal console on startup
- `gui/control-panel`: add preference option for hiding "armok" tools in command lists
- ``Dwarf Therapist``: add a warning to the Labors screen when Dwarf Therapist is active so players know that changes they make to that screen will have no effect. If you're starting a new embark and nobody seems to be doing anything, check your Labors tab for this warning to see if Dwarf Therapist thinks it is in control (even if it's not running).
- `overlay`: add the DFHack version string to the DF title screen

## Lua
- ``widgets.RangeSlider``: new mouse-controlled two-headed slider widget
- ``gui.ZScreenModal``: ZScreen subclass for modal dialogs
- ``widgets.CycleHotkeyLabel``: exposed "key_sep" and "option_gap" attributes for improved stylistic control.

## Removed
- `title-version`: replaced by an `overlay` widget

# 50.07-r1

## New Plugins
- `faststart`: speeds up the "Loading..." screen so the Main Menu appears faster

## Fixes
-@ `hotkeys`: hotkey hints on menu popup will no longer get their last character cut off by the scrollbar
-@ ``launchdf``: launch Dwarf Fortress via the Steam client so Steam Workshop is functional
- `blueprint`: interpret saplings, shrubs, and twigs as floors instead of walls
- `combine`: fix error processing stockpiles with boundaries that extend outside of the map
-@ `prospector`: display both "raw" Z levels and "cooked" elevations
- `stockpiles`: fix crash when importing settings for gems from other worlds
-@ `stockpiles`: allow numbers in saved stockpile filenames

## Misc Improvements
-@ `buildingplan`: items in the item selection dialog should now use the same item quality symbols as the base game
-@ `buildingplan`: hide planner overlay while the DF tutorial is active so that it can detect when you have placed the carpenter's workshop and bed and allow you to finish the tutorial
- `buildingplan`: can now filter by cloth and silk materials (for ropes)
-@ `buildingplan`: rearranged elements of ``planneroverlay`` interface
-@ `buildingplan`: rearranged elements of ``itemselection`` interface
-@ Mods: scripts in mods that are only in the steam workshop directory are now accessible. this means that a script-only mod that you never mark as "active" when generating a world will still receive automatic updates and be usable from in-game
-@ Mods: scripts from only the most recent version of an installed mod are added to the script path
-@ Mods: give active mods a chance to reattach their load hooks when a world is reloaded
- `gui/control-panel`: bugfix services are now enabled by default
- Core: hide DFHack terminal console by default when running on Steam Deck

## Documentation
- `installing`: updated to include Steam installation instructions

## Lua
- added two new window borders: ``gui.BOLD_FRAME`` for accented elements and ``gui.INTERIOR_MEDIUM_FRAME`` for a signature-less frame that's thicker than the existing ``gui.INTERIOR_FRAME``

# 50.07-beta2

## New Plugins
- `getplants`: reinstated: designate trees for chopping and shrubs for gathering according to type
- `prospector`: reinstated: get stone, ore, gem, and other tile property counts in fort mode.

## Fixes
-@ `buildingplan`: filters are now properly applied to planned stairs
-@ `buildingplan`: existing carved up/down stairs are now taken into account when determining which stair shape to construct
- `buildingplan`: upright spike traps are now placed extended rather than retracted
- `buildingplan`: you can no longer designate constructions on tiles with magma or deep water, mirroring the vanilla restrictions
-@ `buildingplan`: fixed material filters getting lost for planning buildings on save/reload
-@ `buildingplan`: respect building size limits (e.g. roads and bridges cannot be more than 31 tiles in any dimension)
- `tailor`: properly discriminate between dyed and undyed cloth
-@ `tailor`: no longer default to using adamantine cloth for producing clothes
- `tailor`: take queued orders into account when calculating available materials
- `tailor`: skip units who can't wear clothes
- `tailor`: identify more available items as available, solving issues with over-production

## Misc Improvements
- `buildingplan`: filters and global settings are now ignored when manually choosing items for a building, allowing you to make custom choices independently of the filters that would otherwise be used
- `buildingplan`: if `suspendmanager` is running, then planned buildings will be left suspended when their items are all attached. `suspendmanager` will unsuspend them for construction when it is safe to do so.
- `buildingplan`: add option for autoselecting the last manually chosen item (like `automaterial` used to do)
- `confirm`: adds confirmation for removing burrows via the repaint menu
- `stockpiles`: support applying stockpile configurations with fully enabled categories to stockpiles in worlds other than the one where the configuration was exported from
- `stockpiles`: support partial application of a saved config based on dynamic filtering (e.g. disable all tallow in a food stockpile, even tallow from world-specific generated creatures)
- `stockpiles`: additive and subtractive modes when applying a second stockpile configuration on top of a first
- `stockpiles`: write player-exported stockpile configurations to the ``dfhack-config/stockpiles`` folder. If you have any stockpile configs in other directories, please move them to that folder.
- `stockpiles`: now includes a library of useful stockpile configs (see docs for details)
- `automelt`: now allows metal chests to be melted (workaround for DF bug 2493 is no longer needed)
- `orders`: add minimize button to overlay panel so you can get it out of the way to read long statue descriptions when choosing a subject in the details screen
- `orders`: add option to delete exported files from the import dialog
- `enable`: can now interpret aliases defined with the `alias` command
- Mods: scripts in mods are now automatically added to the DFHack script path. DFHack recognizes two directories in a mod's folder: ``scripts_modinstalled/`` and ``scripts_modactive/``. ``scripts_modinstalled/`` folders will always be added the script path, regardless of whether the mod is active in a world. ``scripts_modactive/`` folders will only be added to the script path when the mod is active in the current loaded world.

## Documentation
- `modding-guide`: guide updated to include information for 3rd party script developers
- the ``untested`` tag has been renamed to ``unavailable`` to better reflect the status of the remaining unavailable tools. most of the simply "untested" tools have now been tested and marked as working. the remaining tools are known to need development work before they are available again.

## Lua
- ``widgets.Label``: tokens can now specify a ``htile`` property to indicate the tile that should be shown when the Label is hovered over with the mouse
- ``widgets.Label``: click handlers no longer get the label itself as the first param to the click handler
- ``widgets.CycleHotkeyLabel``: options that are bare integers will no longer be interpreted as the pen color in addition to being the label and value
- ``widgets.CycleHotkeyLabel``: option labels and pens can now be functions that return a label or pen

# 50.07-beta1

## Fixes
-@ `buildingplan`: items are now attached correctly to screw pumps and other multi-item buildings
-@ `buildingplan`: buildings with different material filters will no longer get "stuck" if one of the filters currently matches no items
- `showmood` properly count required number of bars and cloth when they aren't the main item for the strange mood

## Misc Improvements
-@ `buildingplan`: can now filter by clay materials
-@ `buildingplan`: remember choice per building type for whether the player wants to choose specific items
-@ `buildingplan`: you can now attach multiple weapons to spike traps
-@ `buildingplan`: can now filter by whether a slab is engraved
-@ `buildingplan`: add "minimize" button to temporarily get the planner overlay out of the way if you would rather use the vanilla UI for placing the current building
-@ `buildingplan`: add ``buildingplan reset`` command for resetting all filters to defaults
-@ `buildingplan`: rename "Build" button to "Confirm" on the item selection dialog and change the hotkey from "B" to "C"
- `blueprint`: now writes blueprints to the ``dfhack-config/blueprints`` directory
- `blueprint-library-guide`: library blueprints have moved from ``blueprints`` to ``hack/data/blueprints``
- `blueprint-library-guide`: player-created blueprints should now go in the ``dfhack-config/blueprints`` folder. please move your existing blueprints from ``blueprints`` to ``dfhack-config/blueprints``. you don't need to move the library blueprints -- those can be safely deleted from the old ``blueprints`` directory.
-@ `showmood`: clarify how many bars and/or cloth items are actually needed for the mood

## Removed
-@ `buildingplan`: "heat safety" setting is temporarily removed while we investigate incorrect item matching

# 50.07-alpha3

## Fixes
-@ ``widgets.HotkeyLabel``: don't trigger on click if the widget is disabled
- ``dfhack.job.isSuitableMaterial``: now properly detects lack of fire and magma safety for vulnerable materials with high melting points
- `dig-now`: fixed multi-layer channel designations only channeling every second layer

## Misc Improvements
- `dig-now`: added handling of dig designations that have been converted into active jobs
- `buildingplan`: entirely new UI for building placement, item selection, and materials filtering!

## API
- Gui focus strings will no longer get the "dfhack/" prefix if the string "dfhack/" already exists in the focus string
- ``Military``: New module for military functionality
- ``Military``: new ``makeSquad`` to create a squad
- ``Military``: changed ``getSquadName`` to take a squad identifier
- ``Military``: new ``updateRoomAssignments`` for assigning a squad to a barracks and archery range
- ``Maps::GetBiomeType`` renamed to ``Maps::getBiomeType`` for consistency
- ``Maps::GetBiomeTypeRef`` renamed to ``Maps::getBiomeTypeRef`` for consistency

## Lua
- ``dfhack.job.attachJobItem()``: allows you to attach specific items to a job
- ``dfhack.screen.paintTile()``: you can now explicitly clear the interface cursor from a map tile by passing ``0`` as the tile value
- ``widgets.Label``: token ``tile`` properties can now be functions that return a value
- ``widgets.CycleHotkeyLabel``: add ``label_below`` attribute for compact 2-line output
-@ ``widgets.FilteredList``: search key matching is now case insensitive by default
-@ ``gui.INTERIOR_FRAME``: a panel frame style for use in highlighting off interior areas of a UI
- ``maps.getBiomeType``: exposed preexisting function to Lua

## Removed
-@ ``gui.THIN_FRAME``: replaced by ``gui.INTERIOR_FRAME``
- `automaterial`: all functionality has been merged into `buildingplan`

# 50.07-alpha2

## Fixes
-@ `nestboxes`: fixed bug causing nestboxes themselves to be forbidden, which prevented citizens from using them to lay eggs. Now only eggs are forbidden.
-@ `autobutcher`: implemented work-around for Dwarf Fortress not setting nicknames properly, so that nicknames created in the in-game interface are detected & protect animals from being butchered properly. Note that nicknames for unnamed units are not currently saved by dwarf fortress - use ``enable fix/protect-nicks`` to fix any nicknames created/removed within dwarf fortress so they can be saved/reloaded when you reload the game.
-@ `seedwatch`: fix saving and loading of seed stock targets
- `autodump`: changed behaviour to only change ``dump`` and ``forbid`` flags if an item is successfully dumped.
-@ `autochop`: generate default names for burrows with no assigned names
- ``Buildings::StockpileIterator``: fix check for stockpile items on block boundary.
- `tailor`: block making clothing sized for toads; make replacement clothing orders use the size of the wearer, not the size of the garment
-@ `confirm`: fix fps drop when enabled
-@ `channel-safely`: fix an out of bounds error regarding the REPORT event listener receiving (presumably) stale id's

## Misc Improvements
- `autobutcher`: logs activity to the console terminal instead of making disruptive in-game announcements
- DFHack tool windows that capture mouse clicks (and therefore prevent you from clicking on the "pause" button) now unconditionally pause the game when they open (but you can still unpause with the keyboard if you want to). Examples of this behavior: `gui/quickfort`, `gui/blueprint`, `gui/liquids`
- `showmood`: now shows the number of items needed for cloth and bars in addition to the technically correct but always confusing "total dimension" (150 per bar or 10,000 per cloth)
-@ Stopped mouse clicks from affecting the map when a click on a DFHack screen dismisses the window
- `confirm`: configuration data is now persisted globally.
- `tailor`: add support for adamantine cloth (off by default); improve logging

## API
- ``Gui::any_civzone_hotkey``, ``Gui::getAnyCivZone``, ``Gui::getSelectedCivZone``:  new functions to operate on the new zone system
- Units module: added new predicates for ``isGeldable()``, ``isMarkedForGelding()``, and ``isPet()``

## Lua
- ``dfhack.gui.getSelectedCivZone``: returns the Zone that the user has selected currently
- ``widgets.FilteredList``: Added ``edit_on_change`` optional parameter to allow a custom callback on filter edit change.
- ``widgets.TabBar``: new library widget (migrated from control-panel.lua)

# 50.07-alpha1

## Fixes
- ``Units::isFortControlled``: Account for agitated wildlife
-@ Fix right click sometimes closing both a DFHack window and a vanilla panel
-@ Fixed issue with scrollable lists having some data off-screen if they were scrolled before being made visible
-@ `channel-safely`: fixed bug resulting in marker mode never being set for any designation
-@ `automelt`: fixed bug related to lua stack smashing behavior in returned stockpile configs
-@ `autochop`: fixed bug related to lua stack smashing behavior in returned stockpile configs
-@ `nestboxes`: now cancels any in-progress hauling jobs when it protects a fertile egg
-@ Fix persisted data not being written on manual save
-@ `nestboxes`: now scans for eggs more frequently and cancels any in-progress hauling jobs when it protects a fertile egg

## Misc Improvements
-@ `automelt`: is now more resistent to vanilla savegame corruption
-@ `hotkeys`: DFHack logo is now hidden on screens where it covers important information when in the default position (e.g. when choosing an embark site)
- `misery`: now persists state with the fort
-@ `autodump`: reinstate ``autodump-destroy-item``, hotkey: Ctrl-K
- `autodump`: new hotkey for ``autodump-destroy-here``: Ctrl-H
-@ `dig`: new hotkeys for vein designation on z-level (Ctrl-V) and vein designation across z-levels (Ctrl-Shift-V)
-@ `clean`: new hotkey for `spotclean`: Ctrl-C
- `autobutcher`: changed defaults from 5 females / 1 male to 4 females / 2 males so a single unfortunate accident doesn't leave players without a mating pair
- `autobutcher`: now immediately loads races available at game start into the watchlist
-@ replaced DFHack logo used for the hover hotspot with a crisper image
-@ `orders`: recipe for silver crossbows removed from ``library/military`` as it is not a vanilla recipe, but is available in ``library/military_include_artifact_materials``
- `stonesense`: added an ``INVERT_MOUSE_Z`` option to invert the mouse wheel direction

## Documentation

## API

## Lua
- `overlay`: overlay widgets can now specify focus paths for the viewscreens they attach to so they only appear in specific contexts. see `overlay-dev-guide` for details.
- ``widgets.CycleHotkeyLabel``: Added ``key_back`` optional parameter to cycle backwards.
- ``widgets.HotkeyLabel``: Added ``setLabel`` method to allow easily updating the label text without mangling the keyboard shortcut.
- ``widgets.HotkeyLabel``: Added ``setOnActivate`` method to allow easily updating the ``on_activate`` callback.
- ``widgets.FilteredList``: Added ``case_sensitive`` optional parameter to determine if filtering is case sensitive.

# 50.05-alpha3.1

## Fixes
-@ `seedwatch`: fix parameter parsing when setting targets

# 50.05-alpha3

## New Plugins
- `autoslab`: automatically create work orders to engrave slabs for ghostly dwarves

## Fixes
-@ DF screens can no longer get "stuck" on transitions when DFHack tool windows are visible. Instead, those DF screens are force-paused while DFHack windows are visible so the player can close them first and not corrupt the screen sequence. The "PAUSE FORCED" indicator will appear on these DFHack windows to indicate what is happening.
-@ allow launcher tools to launch themselves without hanging the game
-@ fix issues with clicks "passing through" some DFHack window elements to the screen below
- `getplants`: trees are now designated correctly
- `autoclothing`: fixed a crash that can happen when units are holding invalid items.
-@ `orders`: fix orders in library/basic that create bags
- `orders`: library/military now sticks to vanilla rules and does not add orders for normally-mood-only platinum weapons. A new library orders file ``library/military_include_artifact_materials`` is now offered as an alternate ``library/military`` set of orders that still includes the platinum weapons.
- `autochop`: fixed a crash when processing trees with corrupt data structures (e.g. when a trunk tile fails to fall when the rest of the tree is chopped down)

## Misc Improvements
-@ DFHack windows can now be "defocused" by clicking somewhere not over the tool window. This has the same effect as pinning previously did, but without the extra clicking.
- `getplants`: ID values will now be accepted regardless of case
-@ Windows now display "PAUSE FORCED" on the lower border if the tool is forcing the game to pause
-@ New borders for DFHack tool windows -- tell us what you think!
-@ `autoclothing`: merged the two separate reports into the same command.
- `automelt`: stockpile configuration can now be set from the commandline
- `channel-safely`: new monitoring for cave-in prevention
-@ `gui/control-panel`: you can now configure whether DFHack tool windows should pause the game by default
- `gui/control-panel`: new global hotkey for quick access: Ctrl-Shift-E
-@ `hotkeys`: clicking on the DFHack logo no longer closes the popup menu
- `nestboxes`: now saves enabled state in your savegame
- `gui/launcher`: sped up initialization time for faster window appearance
- `orders`: orders plugin functionality is now accessible via an `overlay` widget when the manager orders screen is open
- `gui/quickcmd`: now has its own global keybinding for your convenience: Ctrl-Shift-A
- `seedwatch`: now persists enabled state in the savegame, automatically loads useful defaults, and respects reachability when counting available seeds
-@ `quickfort`: planned buildings are now properly attached to any pertinent overlapping zones

## Documentation
- `compile`: instructions added for cross-compiling DFHack for Windows from a Linux Docker builder
-@ Quickstart guide has been updated with info on new window behavior and how to use the control panel

## API
- ``Buildings::containsTile()``: no longer takes a ``room`` parameter since that's not how rooms work anymore. If the building has extents, the extents will be checked. otherwise, the result just depends on whether the tile is within the building's bounding box.
- ``Units::getCitizens()``: gets a list of citizens, which otherwise you'd have to iterate over all units the world to discover
- ``Screen::Pen``: now accepts ``top_of_text`` and ``bottom_of_text`` properties to support offset text in graphics mode
- `overlay`: overlay widgets can now specify a default enabled state if they are not already set in the player's overlay config file
- ``Lua::Push``: now supports ``std::unordered_map``

## Lua
- `helpdb`: new function: ``helpdb.refresh()`` to force a refresh of the database. Call if you are a developer adding new scripts, loading new plugins, or changing help text during play
- `helpdb`: changed from auto-refreshing every 60 seconds to only refreshing on explicit call to ``helpdb.refresh()``. docs very rarely change during a play session, and the automatic database refreshes were slowing down the startup of `gui/launcher` and anything else that displays help text.
- ``widgets.Label``: ``label.scroll()`` now understands ``home`` and ``end`` keywords for scrolling to the top or bottom
- ``widgets.List``: new callbacks for double click and shift double click
- ``dfhack.units.getCitizens()``: gets a list of citizens
-@ ``gui.ZScreen``: new attribute: ``defocusable`` for controlling whether a window loses keyboard focus when the map is clicked
- ``widgets.Label``: token ``tile`` properties can now be either pens or numeric texture ids
- `tiletypes`: now has a Lua API! ``tiletypes_setTile``

## Removed
- `autohauler`: no plans to port to v50, as it just doesn't make sense with the new work detail system

# 50.05-alpha2

## Fixes
-@ `autofarm`: don't duplicate status line entries for crops with no current supply
-@ `orders`: allow the orders library to be listed and imported properly (if you previously copied the orders library into your ``dfhack-config/orders`` directory to work around this bug, you can remove those files now)
- `tailor`: now respects the setting of the "used dyed clothing" standing order toggle

# 50.05-alpha1

## Fixes
- ``widgets.WrappedLabel``: no longer resets scroll position when window is moved or resized

## Misc Improvements
- Scrollable widgets now react to mouse wheel events when the mouse is over the widget
- the ``dfhack-config/scripts/`` folder is now searched for scripts by default
- `hotkeys`: overlay hotspot widget now shows the DFHack logo in graphics mode and "DFHack" in text mode
- `script-paths`: removed "raw" directories from default script paths. now the default locations to search for scripts are ``dfhack-config/scripts``, ``save/*/scripts``, and ``hack/scripts``
- ``init.d``: directories have moved from the ``raw`` subfolder (which no longer exists) to the root of the main DF folder or a savegame folder

## Documentation
- `overlay-dev-guide`: added troubleshooting tips and common development workflows
- added DFHack architecture diagrams to the dev intro
- added DFHack Quickstart guide

## API
- ``Gui::getDwarfmodeDims``: now only returns map viewport dimensions; menu dimensions are obsolete
- ``Gui::getDFViewscreen``: returns the topmost underlying DF viewscreen
- ``Screen::Pen``: now accepts ``keep_lower`` and ``write_to_lower`` properties to support foreground and background textures in graphics mode

## Lua
- Removed ``os.execute()`` and ``io.popen()`` built-in functions
- ``gui.View``: ``visible`` and ``active`` can now be functions that return a boolean
- ``widgets.Panel``: new attributes to control window dragging and resizing with mouse or keyboard
- ``widgets.Window``: Panel subclass with attributes preset for top-level windows
- ``widgets.CycleHotkeyLabel``: now supports rendering option labels in the color of your choice
- ``widgets.CycleHotkeyLabel``: new functions ``setOption()`` and ``getOptionPen()``
- ``widgets.ToggleHotkeyLabel``: now renders the ``On`` option in green text
- ``widgets.Label``: tiles can now have an associated width
- `overlay`: ``OverlayWidget`` now inherits from ``Panel`` instead of ``Widget`` to get all the frame and mouse integration goodies
- ``dfhack.gui.getDFViewscreen()``: returns the topmost underlying DF viewscreen
- ``gui.ZScreen``: Screen subclass that implements window raising, multi-viewscreen input handling, and viewscreen event pass-through so the underlying map can be interacted with and dragged around while DFHack screens are visible
- ``gui.View``: new function ``view:getMouseFramePos()`` for detecting whether the mouse is within (or over) the exterior frame of a view
- ``gui.CLEAR_PEN``: now clears the background and foreground and writes to the background (before it would always write to the foreground)
- ``gui.KEEP_LOWER_PEN``: a general use pen that writes associated tiles to the foreground while keeping the existing background

## Removed
- ``fix-job-postings`` from the `workflow` plugin is now obsolete since affected savegames can no longer be loaded
- Ruby is no longer a supported DFHack scripting language