diff --git a/.gitignore b/.gitignore index 63bd079c36..70ccb04455 100644 --- a/.gitignore +++ b/.gitignore @@ -21,7 +21,7 @@ buntu build/VC2010 # Sphinx generated documentation -docs/_*/ +docs/_* docs/html/ #except for the real one diff --git a/.travis.yml b/.travis.yml index 1863835f1e..4afad17042 100644 --- a/.travis.yml +++ b/.travis.yml @@ -18,7 +18,7 @@ script: - python travis/lint.py - python travis/script-in-readme.py - python travis/script-syntax.py --ext=lua --cmd="luac5.2 -p" -- python travis/script-syntax.py --ext=rb --cmd="ruby -c" +- python travis/script-syntax.py --ext=rb --cmd="ruby -c" --path scripts/ - mkdir build-travis - cd build-travis - cmake .. && make -j3 diff --git a/CMakeLists.txt b/CMakeLists.txt index 84db3f36f5..b6228a9e1f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -93,7 +93,7 @@ endif() # set up versioning. set(DF_VERSION "0.40.24") -SET(DFHACK_RELEASE "r3") +SET(DFHACK_RELEASE "r4") set(DFHACK_VERSION "${DF_VERSION}-${DFHACK_RELEASE}") @@ -184,10 +184,7 @@ endif() # build the lib itself IF(BUILD_LIBRARY) add_subdirectory (library) - ## install the default documentation files - #install(FILES LICENSE NEWS "Lua API.html" Readme.html Compile.html Contributors.html DESTINATION ${DFHACK_USERDOC_DESTINATION}) - install(FILES LICENSE NEWS DESTINATION ${DFHACK_USERDOC_DESTINATION}) - #install(DIRECTORY docs/images DESTINATION ${DFHACK_USERDOC_DESTINATION}) + install(FILES LICENSE.rst NEWS.rst DESTINATION ${DFHACK_USERDOC_DESTINATION}) endif() install(DIRECTORY dfhack-config/ DESTINATION dfhack-config/default) @@ -204,43 +201,34 @@ if (BUILD_DOCS) if (NOT SPHINX_FOUND) message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled") endif() - set(SPHINX_THEME "alabaster") - set(SPHINX_THEME_DIR) - set(SPHINX_BINARY_BUILD_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build") - set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/_doctrees") - set(SPHINX_HTML_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/") - - configure_file( - "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py.in" - "${SPHINX_BINARY_BUILD_DIR}/conf.py" - @ONLY) file(GLOB SPHINX_DEPS "${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst" "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png" - "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py.in" + "${CMAKE_CURRENT_SOURCE_DIR}/docs/styles/*" + "${CMAKE_CURRENT_SOURCE_DIR}/conf.py" + "${CMAKE_CURRENT_SOURCE_DIR}/scripts/about.txt" + "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/about.txt" + ) + file(GLOB_RECURSE SPHINX_SCRIPT_DEPS "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*/*.lua" + "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.rb" + ) + set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} + "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.rst" + "${CMAKE_CURRENT_SOURCE_DIR}/NEWS.rst" + "${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt" ) - set(SPHINX_DEPS ${SPHINX_DEPS} LICENSE NEWS README.rst) set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo") set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) add_custom_command(OUTPUT ${SPHINX_OUTPUT} COMMAND ${SPHINX_EXECUTABLE} -a -E -q -b html - -c "${SPHINX_BINARY_BUILD_DIR}" - -d "${SPHINX_CACHE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}" - "${SPHINX_HTML_DIR}" + "${CMAKE_CURRENT_SOURCE_DIR}/docs/html" + -w "${CMAKE_CURRENT_SOURCE_DIR}/docs/_sphinx-warnings.txt" + -j 2 DEPENDS ${SPHINX_DEPS} COMMENT "Building HTML documentation with Sphinx" ) @@ -253,16 +241,18 @@ if (BUILD_DOCS) add_custom_command(TARGET dfhack_docs POST_BUILD COMMAND ${CMAKE_COMMAND} -E touch ${SPHINX_OUTPUT}) - install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html - DESTINATION ${DFHACK_USERDOC_DESTINATION} - #FILES_MATCHING PATTERN "*.lua" - # PATTERN "*.rb" - # PATTERN "3rdparty" EXCLUDE + install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html/ + DESTINATION ${DFHACK_USERDOC_DESTINATION}/docs ) + install(FILES "README.html" DESTINATION "${DFHACK_DATA_DESTINATION}") endif() # Packaging with CPack! +SET(DFHACK_PACKAGE_SUFFIX "") IF(UNIX) + execute_process(COMMAND ${CMAKE_CXX_COMPILER} -dumpversion OUTPUT_VARIABLE GCC_VERSION) + string(STRIP ${GCC_VERSION} GCC_VERSION) + SET(DFHACK_PACKAGE_SUFFIX "-gcc-${GCC_VERSION}") if(APPLE) SET(CPACK_GENERATOR "ZIP;TBZ2") else() @@ -277,7 +267,7 @@ IF(APPLE) ELSE() set(DFHACK_PACKAGE_PLATFORM_NAME ${CMAKE_SYSTEM_NAME}) ENDIF() -set(CPACK_PACKAGE_FILE_NAME "dfhack-${DFHACK_VERSION}-${DFHACK_PACKAGE_PLATFORM_NAME}") +set(CPACK_PACKAGE_FILE_NAME "dfhack-${DFHACK_VERSION}-${DFHACK_PACKAGE_PLATFORM_NAME}${DFHACK_PACKAGE_SUFFIX}") INCLUDE(CPack) #INCLUDE(FindSphinx.cmake) diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 9bdc729f08..0000000000 --- a/LICENSE +++ /dev/null @@ -1,359 +0,0 @@ -License of DFHack -================= -https://github.com/peterix/dfhack -Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com) -:: - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any - damages arising from the use of this software. - - Permission is granted to anyone to use this software for any - purpose, including commercial applications, and to alter it and - redistribute it freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must - not claim that you wrote the original software. If you use this - software in a product, an acknowledgment in the product documentation - would be appreciated but is not required. - - 2. Altered source versions must be plainly marked as such, and - must not be misrepresented as being the original software. - - 3. This notice may not be removed or altered from any source - distribution. - -clsocket license -================ -:: - - Copyright (c) 2007-2009 CarrierLabs, LLC. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - - 3. The name of the author may not be used to endorse or promote products - derived from this software without specific prior written permission. - - 4. The name "CarrierLabs" must not be used to - endorse or promote products derived from this software without - prior written permission. For written permission, please contact - mark@carrierlabs.com. - - THIS SOFTWARE IS PROVIDED BY MARK CARRIER ``AS IS'' AND ANY - EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MARK CARRIER OR - ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED - OF THE POSSIBILITY OF SUCH DAMAGE. - -Lua license -=========== - -Lua is licensed under the terms of the MIT license reproduced below. -This means that Lua is free software and can be used for both academic -and commercial purposes at absolutely no cost. - -For details and rationale, see http://www.lua.org/license.html . - -:: - - Copyright (C) 1994-2008 Lua.org, PUC-Rio. - - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in - all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN - THE SOFTWARE. - -Protobuf license -================ -:: - - Copyright 2008, Google Inc. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following disclaimer - in the documentation and/or other materials provided with the - distribution. - * Neither the name of Google Inc. nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - Code generated by the Protocol Buffer compiler is owned by the owner - of the input file used when generating it. This code is not - standalone and requires a support library to be linked with it. This - support library is itself covered by the above license. - - -License of tinyxml (XML reader library) -======================================= -http://www.sourceforge.net/projects/tinyxml - -Original code, 2.0 and earlier, copyright 2000-2006 Lee Thomason (http://www.grinninglizard.com) -:: - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any - damages arising from the use of this software. - - Permission is granted to anyone to use this software for any - purpose, including commercial applications, and to alter it and - redistribute it freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must - not claim that you wrote the original software. If you use this - software in a product, an acknowledgment in the product documentation - would be appreciated but is not required. - - 2. Altered source versions must be plainly marked as such, and - must not be misrepresented as being the original software. - - 3. This notice may not be removed or altered from any source - distribution. - -tinythread license -================== -:: - - Copyright (c) 2010 Marcus Geelnard - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - - 3. This notice may not be removed or altered from any source - distribution. - -zlib license -============ - -:: - - Copyright (C) 1995-2010 Jean-loup Gailly and Mark Adler - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. - - -dirent.h - dirent API for Microsoft Visual Studio -================================================= -:: - - Copyright (C) 2006 Toni Ronkko - - Permission is hereby granted, free of charge, to any person obtaining - a copy of this software and associated documentation files (the - "Software"), to deal in the Software without restriction, including - without limitation the rights to use, copy, modify, merge, publish, - distribute, sublicense, and/or sell copies of the Software, and to - permit persons to whom the Software is furnished to do so, subject to - the following conditions: - - The above copyright notice and this permission notice shall be included - in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS - OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. - IN NO EVENT SHALL TONI RONKKO BE LIABLE FOR ANY CLAIM, DAMAGES OR - OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, - ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR - OTHER DEALINGS IN THE SOFTWARE. - - -linenoise.c -=========== -Parts of dfhack are based on linenoise: a line editing library against the -idea that a line editing lib needs to be 20,000 lines of C code. - -You can find the latest source code at http://github.com/antirez/linenoise -:: - - Copyright (c) 2010, Salvatore Sanfilippo - Copyright (c) 2010, Pieter Noordhuis - - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - -UTF-8 Decoder -============= -See http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details. -:: - - Copyright (c) 2008-2010 Bjoern Hoehrmann - - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all - copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, - WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - -luafilesystem -============= -Parts of dfhack are based on luafilesystem: -:: - - Copyright (c) 2003-2014 Kepler Project. - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation - files (the "Software"), to deal in the Software without - restriction, including without limitation the rights to use, copy, - modify, merge, publish, distribute, sublicense, and/or sell copies - of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. - -jsoncpp -======== -:: - - Copyright (c) 2007-2010 Baptiste Lepilleur - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation - files (the "Software"), to deal in the Software without - restriction, including without limitation the rights to use, copy, - modify, merge, publish, distribute, sublicense, and/or sell copies - of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. - - -JSON.lua -======== -Copyright 2010-2014 Jeffrey Friedl, http://regex.info/blog/ - -Latest version: http://regex.info/blog/lua/json - -This code is released under a Creative Commons CC-BY "Attribution" License: -http://creativecommons.org/licenses/by/3.0/deed.en_US diff --git a/LICENSE.rst b/LICENSE.rst new file mode 100644 index 0000000000..e6a643e3d9 --- /dev/null +++ b/LICENSE.rst @@ -0,0 +1,145 @@ +.. _license: + +######## +Licenses +######## + +DFHack is distributed under the Zlib license, with some MIT- +and BSD-licensed components. These licenses protect your right +to use DFhack for any purpose, distribute copies, and so on. + +The core, plugins, scripts, and other DFHack code all use the +ZLib license unless noted otherwise. By contributing to DFHack, +authors release the contributed work under this license. + +DFHack also draws on several external packages. +Their licenses are summarised here and reproduced below. + +=============== ============= ================================================= +Component License Copyright +=============== ============= ================================================= +DFHack_ Zlib \(c\) 2009-2012, Petr Mrázek +clsocket_ BSD 3-clause \(c\) 2007-2009, CarrierLabs, LLC. +dirent_ MIT \(c\) 2006, Toni Ronkko +JSON.lua_ CC-BY-SA_ \(c\) 2010-2014, Jeffrey Friedl +jsoncpp_ MIT \(c\) 2007-2010, Baptiste Lepilleur +linenoise_ BSD 2-clause \(c\) 2010, Salvatore Sanfilippo & Pieter Noordhuis +lua_ MIT \(c\) 1994-2008, Lua.org, PUC-Rio. +luafilesystem_ MIT \(c\) 2003-2014, Kepler Project +protobuf_ BSD 3-clause \(c\) 2008, Google Inc. +tinythread_ Zlib \(c\) 2010, Marcus Geelnard +tinyxml_ Zlib \(c\) 2000-2006, Lee Thomason +UTF-8-decoder_ MIT \(c\) 2008-2010, Bjoern Hoehrmann +=============== ============= ================================================= + +.. _DFHack: https://github.com/DFHack/dfhack +.. _clsocket: https://github.com/DFHack/clsocket +.. _dirent: https://github.com/tronkko/dirent +.. _JSON.lua: http://regex.info/blog/lua/json +.. _jsoncpp: https://github.com/open-source-parsers/jsoncpp +.. _linenoise: http://github.com/antirez/linenoise +.. _lua: http://www.lua.org +.. _luafilesystem: https://github.com/keplerproject/luafilesystem +.. _protobuf: https://github.com/google/protobuf +.. _tinythread: http://tinythreadpp.bitsnbites.eu/ +.. _tinyxml: http://www.sourceforge.net/projects/tinyxml +.. _UTF-8-decoder: http://bjoern.hoehrmann.de/utf-8/decoder/dfa + +.. _CC-BY-SA: http://creativecommons.org/licenses/by/3.0/deed.en_US + + +Zlib License +============ +See https://en.wikipedia.org/wiki/Zlib_License +:: + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any + damages arising from the use of this software. + + Permission is granted to anyone to use this software for any + purpose, including commercial applications, and to alter it and + redistribute it freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must + not claim that you wrote the original software. If you use this + software in a product, an acknowledgment in the product + documentation would be appreciated but is not required. + + 2. Altered source versions must be plainly marked as such, and + must not be misrepresented as being the original software. + + 3. This notice may not be removed or altered from any source + distribution. + +MIT License +=========== +See https://en.wikipedia.org/wiki/MIT_License +:: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, + TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +BSD Licenses +============ +See https://en.wikipedia.org/wiki/BSD_licenses +:: + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +``linenoise`` adds no further clauses. + +``protobuf`` adds the following clause:: + + 3. Neither the name of Google Inc. nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + +``clsocket`` adds the following clauses:: + + 3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + + 4. The name "CarrierLabs" must not be used to endorse or promote + products derived from this software without prior written + permission. For written permission, please contact + mark@carrierlabs.com diff --git a/NEWS b/NEWS deleted file mode 100644 index 31525ef4d6..0000000000 --- a/NEWS +++ /dev/null @@ -1,863 +0,0 @@ -.. comment - This is the changelog file for DFHack. If you add or change anything, note - it here under the heading "DFHack Future", in the appropriate section. - Items within each section are listed in alphabetical order to minimise merge - conflicts. Try to match the style and level of detail of the other entries. - - -DFHack Future -============= -:: - - Internals - A method for caching screen output is now available to Lua (and C++) - Developer plugins can be ignored on startup by setting the DFHACK_NO_DEV_PLUGINS environment variable - The console on Linux and OS X now recognizes keyboard input between prompts - JSON libraries available (C++ and Lua) - More DFHack build information used in plugin version checks and available to plugins and lua scripts - Fixed a rare overflow issue that could cause crashes on Linux and OS X - Stopped DF window from receiving input when unfocused on OS X - Fixed issues with keybindings involving Ctrl-A and Ctrl-Z, as well as Alt-E/U/N on OS X - Multiple contexts can now be specified when adding keybindings - Keybindings can now use F10-F12 and 0-9 - Plugin system is no longer restricted to plugins that exist on startup - dfhack.init file locations significantly generalized - Lua - Scripts can be enabled with the built-in enable/disable commands - A new function, reqscript(), is available as a safer alternative to script_environment() - Lua viewscreens can choose not to intercept the OPTIONS keybinding - New internal commands - kill-lua: Interrupt running Lua scripts - type: Show where a command is implemented - New plugins - confirm: Adds confirmation dialogs for several potentially dangerous actions - fix-unit-occupancy: Fixes issues with unit occupancy, such as faulty "unit blocking tile" messages (bug 3499) - title-version (formerly vshook): Display DFHack version on title screen - New scripts - burial: sets all unowned coffins to allow burial ("-pets" to allow pets too) - fix-ster: changes fertility/sterility of animals or dwarves - view-item-info: adds information and customisable descriptions to item viewscreens - warn-starving: check for starving, thirsty, or very drowsy units and pause with warning if any are found - modtools/create-unit: create new units from nothing - modtools/equip-item: a script to equip items on units - points: set number of points available at embark screen - Vjek's script collection: - - armoks-blessing: Adjust all attributes, personality, age and skills of all dwarves in play - - brainwash: brainwash a dwarf (modifying their personality) - - elevate-mental: elevate all the mental attributes of a unit - - elevate-physical: elevate all the physical attributes of a unit - - make-legendary: modify skill(s) of a single unit - - pref-adjust: Adjust all preferences of all dwarves in play - - rejuvenate: make any "old" dwarf 20 years old - New tweaks - embark-profile-name: Allows the use of lowercase letters when saving embark profiles - kitchen-keys: Fixes DF kitchen meal keybindings - kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences - kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs - Fixes - Plugins with vmethod hooks can now be reloaded on OS X - Lua's os.system() now works on OS X - Fixed default arguments in Lua gametype detection functions - Circular lua dependencies (reqscript/script_environment) fixed - Prevented crash in Items::createItem() - buildingplan: Now supports hatch covers - gui/create-item: - - fixed assigning quality to items - - made "esc" work properly - gui/gm-editor handles lua tables properly - help: now recognizes built-in commands, like "help" - manipulator: fixed crash when selecting custom professions when none are found - remotefortressreader: fixed crash when attempting to send map info when no map was loaded - search: - - fixed crash in unit list after cancelling a job - - fixed crash when disabling stockpile category after searching in a subcategory - stockpiles: now checks/sanitizes filenames when saving - stocks: fixed a crash when right-clicking - steam-engine: - - fixed a crash on arena load - - number keys (e.g. 2/8) take priority over cursor keys when applicable - tweak fps-min fixed - tweak farm-plot-select: Stopped controls from appearing when plots weren't fully built - workflow: Fixed some issues with stuck jobs - - Note: Existing stuck jobs must be cancelled and re-added - zone: Fixed a crash when using "zone set" (and a few other potential crashes) - Misc Improvements - DFHack documentation: - - massively reorganised, into files of more readable size - - added many missing entries - - indexes, internal links, offline search all documents - - includes documentation of linked projects (df-structures, 3rdparty scripts) - - better HTML generation with Sphinx - autolabor: - - Stopped modification of labors that shouldn't be modified for brokers/diplomats - - Prioritize skilled dwarves more efficiently - - Prevent dwarves from running away with tools from previous jobs - dwarfmonitor: - - widgets' positions, formats, etc. are now customizable (see Readme) - - weather display now separated from the date display - - New mouse cursor widget - dfstatus: Can enable/disable individual categories and customize metal bar list - full-heal: "-r" option removes corpses - gui/gm-editor - - Pointers can now be displaced - - Added some useful aliases: "item" for the selected item, "screen" for the current screen, etc. - - Now avoids errors with unrecognized types - gui/hack-wish: renamed to gui/create-item - "keybinding list" accepts a context - lever: - - Lists lever names - - "lever pull" can be used to pull the currently-selected lever - memview: Fixed display issue - modtools/create-item: arguments are named more clearly, and you can specify the creator to be - the unit with id df.global.unit_next_id-1 (useful in conjunction with modtools/create-unit) - nyan: Can now be stopped with dfhack-run - plug: - - lists all plugins - - shows state and number of commands in plugins - prospect: works from within command-prompt - quicksave: Restricted to fortress mode - remotefortressreader: Exposes more information - search: - - Supports noble suggestion screen (e.g. suggesting a baron) - - Supports fortress mode loo[k] menu - - Recognizes ? and ; keys - stocks: can now match beginning and end of item names - teleport: Fixed cursor recognition - tweak: - - debug output now logged to stderr.log instead of console - makes DFHack start faster - - farm-plot-select: Fixed issues with selecting undiscovered crops - workflow: Improved handling of plant reactions - Removed - embark-tools nano: 1x1 embarks are now possible in vanilla 0.40.24 - -DFHack 0.40.24-r3 -================= -:: - - Internals - Ruby library now included on OS X - ruby scripts should work on OS X 10.10 - libstdc++ should work with older versions of OS X - Added support for onLoadMap/onUnloadMap.init scripts - game type detection functions are now available in the World module - The DFHACK_LOG_MEM_RANGES environment variable can be used to log information to stderr.log on OS X - Fixed adventure mode menu names - Fixed command usage information for some commands - Lua - Lua scripts will only be reloaded if necessary - Added a df2console() wrapper, useful for printing DF (CP437-encoded) text to the console in a portable way - Added a strerror() wrapper - New internal commands - hide/show: hide and show the console on Windows - sc-script: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts) - New plugins - autohauler: A hauling-only version of autolabor - New scripts - modtools/reaction-product-trigger: triggers callbacks when products are produced (contrast with when reactions complete) - New tweaks - fps-min: Fixes the in-game minimum FPS setting - shift-8-scroll: Gives Shift+8 (or *) priority when scrolling menus, instead of scrolling the map - tradereq-pet-gender: Displays pet genders on the trade request screen - New features - autolabor: A negative pool size can be specified to use the most unskilled dwarves - catsplosion: Works on any specified races - exportlegends: Now exports more information - Fixes - Fixed game type detection in: - 3dveins - createitem - reveal - seedwatch - Made PRELOAD_LIB more extensible on Linux - add-spatter, eventful: Fixed crash on world load - building-hacks: made buildings produce/consume correct amount of power - Gave add-thought a proper subthought arg. - fix-armory compiles and is available again (albeit with issues) - gui/gm-editor: Added search option (accessible with "s") - hack-wish: Made items stack properly. - modtools/skill-change: made level granularity work properly. - show-unit-syndromes should work - stockflow: Fixed error message in Arena mode - stockflow: No longer checks the DF version - stockflow: Fixed ballistic arrow head orders - stockflow: Now convinces the bookkeeper to update records more often - zone: Stopped crash when scrolling cage owner list - Misc Improvements - building-hacks: Added a way to allow building to work even if it consumes more power - than is available. Added setPower/getPower functions. - catsplosion: Can now trigger pregnancies in (most) other creatures - exportlegends: 'info' and 'all' exports legends_plus xml with more data for legends utilities - manipulator: - Added ability to edit nicknames/profession names - Added "Job" as a View Type, in addition to "Profession" and "Squad" - Custom profession templates, with masking - remotefortressreader: Exposes more information - -DFHack 0.40.24-r2 -================= -:: - - Internals - Lua scripts can set environment variables of each other with dfhack.run_script_with_env. - Lua scripts can now call each others internal nonlocal functions with dfhack.script_environment(scriptName).functionName(arg1,arg2). - eventful Lua reactions no longer require LUA_HOOK as a prefix: you can register a - callback for the completion of any reaction with a name - Filesystem module now provides file access/modification times and can list directories (normally and recursively) - Units Module: New functions: - isWar - isHunter - isAvailableForAdoption - isOwnCiv - isOwnRace - getRaceName - getRaceNamePlural - getRaceBabyName - getRaceChildName - isBaby - isChild - isAdult - isEggLayer - isGrazer - isMilkable - isTrainableWar - isTrainableHunting - isTamable - isMale - isFemale - isMerchant - isForest - isMarkedForSlaughter - Buildings Module: New Functions: - isActivityZone - isPenPasture - isPitPond - isActive - findPenPitAt - Fixes - dfhack.run_script should correctly find save-specific scripts now. - Updated add-thought to properly affect stress. - hfs-pit should work now - Autobutcher takes gelding into account - init.lua existence checks should be more reliable (notably when using non-English locales) - Misc Improvements - Multiline commands are now possible inside dfhack.init scripts. See dfhack.init-example for example usage. - -DFHack 0.40.24-r1 -================= -:: - - Internals - CMake shouldn't cache DFHACK_RELEASE anymore. People may need to manually update/delete - their CMake cache files to get rid of it. - -DFHack 0.40.24-r0 -================= -:: - - Internals - EventManager: fixed crash error with EQUIPMENT_CHANGE event. - key modifier state exposed to Lua - Fixes - dfhack script can now be run from other directories on OSX - New Plugins - blueprint: export part of your fortress to quickfort .csv files - New Scripts - hotkey-notes: print key, name, and jump position of hotkeys - Removed - embark.lua - needs_porting/* - Misc Improvements - added support for searching more lists - -DFHack 0.40.23-r1 -================= -:: - - Internals - plugins will not be loaded if globals they specify as required are not located (should prevent some crashes) - Fixes - Fixed numerous (mostly Lua-related) crashes on OS X by including a more up-to-date libstdc++ - Alt should no longer get stuck on Windows (and perhaps other platforms as well) - advfort works again - autobutcher takes sexualities into account - devel/export-dt-ini: Updated for 0.40.20+ - digfort: now checks file type and existence - exportlegends: Fixed map export - full-heal: Fixed a problem with selecting units in the GUI - gui/hack-wish: Fixed restrictive material filters - mousequery: Changed box-select key to Alt+M - plugins/dwarfmonitor: correct date display (month index, separator) - scripts/putontable: added to the readme - siren should work again - stderr.log: removed excessive debug output on OS X - trackstop: No longer prevents cancelling the removal of a track stop or roller. - Fixed a display issue with PRINT_MODE:TEXT - Fixed a symbol error (MapExtras::BiomeInfo::MAX_LAYERS) when compiling DFHack in Debug mode - New Plugins - fortplan: designate construction of (limited) buildings from .csv file, quickfort-style - New Scripts - gui/stockpiles: an in-game interface for saving and loading stockpile - settings files. - position: Reports the current date, time, month, and season, plus - some location info. Port/update of position.py - hfs-pit: Digs a hole to hell under the cursor. Replaces needs_porting/hellhole.cpp - Removed - embark.lua: Obsolete, use `embark-tools` - New tweaks: - eggs-fertile: Displays an egg fertility indicator on nestboxes - max-wheelbarrow: Allows assigning more than 3 wheelbarrows to a stockpile - Misc Improvements - embark-tools: Added basic mouse support on the local map - Made some adventure mode keybindings in dfhack.init-example only work in adventure mode - Added a default keybinding for "gui/companion-order" - further work on needs_porting - -DFHack 0.40.19-r1 -================= -:: - - Fixes: - typo fix in modtools/reaction-trigger - modtools/item-trigger should now work with item types - New plugins: - savestock and loadstock: two commands for saving and loading - stockpile settings to a file. They can be used to migrate stockpile - settings between worlds and saves. - New scripts: - remove-stress [all]: set selected or all units unit to -1,000,000 stress - this script replaces removebadthoughts.rb - Misc improvements: - cmd-prompt can now access selected items, units, and buildings - autolabor plugin: add an optional talent pool parameter - -DFHack 0.40.16-r1 -================= -:: - - Internals: - EventManager should handle INTERACTION triggers a little better. It still can get confused - about who did what but only rarely. - EventManager should no longer trigger REPORT events for old reports after loading a save. - lua/persist-table.lua: a convenient way of using persistent tables of arbitrary structure and dimension in Lua - Fixes: - mousequery: Disabled when linking levers - stocks: Melting should work now - scripts/full-heal: Updated with proper argument handling. - scripts/modtools/reaction-trigger-transition.lua - should produce the correct syntax now - scripts/superdwarf.rb should work better now - scripts/forum-dwarves.lua - update for new df-structures changes - New scripts: - scripts/ - adaptation.rb - view or set the cavern adaptation level of your citizens - add-thought.lua - allows the user to add thoughts to creatures. - gaydar.lua - detect the sexual orientation of units on the map - markdown.lua - Save a copy of a text screen in markdown (for reddit among others). - devel/ - all-bob.lua: renames everyone Bob to help test interaction-trigger - Misc improvements: - autodump: - Can now mark a stockpile for auto-dumping (similar to - automelt and autotrade) - buildingplan: - Can now auto-allocate rooms to dwarves with specific positions - (e.g. expedition leader, mayor) - dwarfmonitor - Now displays a weather indicator and date - lua/syndrome-util.lua - now you can remove syndromes by SYN_CLASS - scripts/modtools/add-syndrome.lua - now you can remove syndromes by SYN_CLASS - No longer writes empty .history files - -DFHack 0.40.15-r1 -================= -:: - - Fixes: - - mousequery: Fixed behavior when selecting a tile on the lowest z-level - Internals: - - EventManager: deals with frame_counter getting reset properly now. - - modtools/item-trigger: fixed equip/unequip bug and corrected minor documentation error - - teleport: Updated with proper argument handling and proper unit-at-destination handling. - - autotrade: Removed the newly obsolete "Mark all" functionality. - - search: Adapts to the new trade screen column width - - tweak fast-trade: Switching the fast-trade keybinding to Shift-Up/Shift-Down, due to Select All conflict - -DFHack 0.40.14-r1 -================= -:: - - Internals: - - The DFHack console can now be disabled by setting the DFHACK_DISABLE_CONSOLE - environment variable: "DFHACK_DISABLE_CONSOLE=1 ./dfhack" - Fixes: - - Stopped duplicate load/unload events when unloading a world - - Stopped "-e" from being echoed when DFHack quits on Linux - - automelt now uses a faster method to locate items - - autotrade: "Mark all" no longer double-marks bin contents - - drainaquifer.rb: replaced with a faster less buggy drain-aquifer.lua - - embark-tools no longer conflicts with keys on the notes screen - - fastdwarf: Fixed problems with combat/attacks - - forum-dwarves should work now - - manipulator now uses a stable sort, allowing sorting by multiple categories - - rendermax updated to work with 0.40 - New plugins: - - trackstop: Shows track stop friction and dump direction in its 'q' menu - New tweaks: - - farm-plot-select: Adds "Select all" and "Deselect all" options to farm plot menus - - import-priority-category: Allows changing the priority of all goods in a - category when discussing an import agreement with the liaison - - manager-quantity: Removes the limit of 30 jobs per manager order - - civ-view-agreement: Fixes overlapping text on the "view agreement" screen - - nestbox-color: Fixes the color of built nestboxes - Misc Improvements: - - exportlegends.lua can now handle site maps - -DFHack 0.40.13-r1 -================= -:: - - Internals: - - unified spatter structs - - added ruby df.print_color(color, string) method for dfhack console - Fixes: - - no more -e after terminating - - fixed superdwarf - -DFHack 0.40.12-r1 -================= -:: - - Fixes: - - possible crash fixed for hack-wish - - updated search to not conflict with BUILDJOB_SUSPEND - - workflow: job_material_category -> dfhack_material_category - - New plugins: - - hotkeys (by Falconne): Shows ingame viewscreen with all dfhack keybindings active in current mode. - - automelt: allows marking stockpiles for automelt - (i.e. any items placed in stocpile will be designated for melting) - - Misc Improvements: - - now you can use @ to print things in interactive Lua with subtley different semantics - - optimizations for stockpiles for autotrade and stockflow - - updated exportlegends.lua to work with new maps, dfhack 40.11 r1+ - - Internals: - - support for global onLoadWorld.init and onUnloadWorld.init files, - called when loading and unloading a world - - Close file after loading a binary patch. - -DFHack 0.40.11-r1 -================= -:: - - Internals: - - Plugins on OS X now use ".plug.dylib" as an extension instead of ".plug.so" - Fixes: - - 3dveins should no longer hang/crash on specific maps - - Fixed some autotrade and search layout issues - - Updated deathcause - - hack-wish should work now - - reveal no longer allocates data for nonexistent map blocks - - Various documentation fixes and updates - -DFHack v0.40.10-r1 -================== - -A few bugfixes. - -DFHack v0.40.08-r2 -================== -:: - - Internals: - supported per save script folders - Items module: added createItem function - Sorted CMakeList for plugins and plugins/devel - diggingInvaders no longer builds if plugin building is disabled - EventManager: - EQUIPMENT_CHANGE now triggers for new units - new events: - ON_REPORT - UNIT_ATTACK - UNLOAD - INTERACTION - - New scripts: - lua/ - repeat-util.lua - makes it easier to make things repeat indefinitely - syndrome-util.lua - makes it easier to deal with unit syndromes - scripts/ - forum-dwarves.lua - helps copy df viewscreens to a file - full-heal.lua - fully heal a unit - remove-wear.lua - removes wear from all items in the fort - repeat.lua - repeatedly calls a script or a plugin - ShowUnitSyndromes.rb - shows syndromes affecting units and other relevant info - teleport.lua - teleports units - scripts/devel/ - print-args.lua - scripts/fix/ - blood-del.lua - makes it so civs don't bring barrels full of blood ichor or goo - feeding-timers.lua - reset the feeding timers of all units - scripts/gui/ - hack-wish.lua - creates items out of any material - unit-info-viewer.lua - displays information about units - scripts/modtools/ - add-syndrome.lua - add a syndrome to a unit or remove one - anonymous-script.lua - execute an lua script defined by a string. For example, - 'scripts/modtools/anonymous-script "print(args[2] .. args[1])" one two' - will print 'twoone'. Useful for the *-trigger scripts. - force.lua - forces events: caravan, migrants, diplomat, megabeast, curiousbeast, - mischievousbeast, flier, siege, nightcreature - item-trigger.lua - triggers commands based on equipping, unequipping, and wounding units with items - interaction-trigger.lua - triggers commands when interactions happen - invader-item-destroyer.lua - destroys invaders' items when they die - moddable-gods.lua - standardized version of Putnam's moddable gods script - outside-only.lua - register buildings as outside only or inside only - replaces outsideOnly plugin - projectile-trigger.lua - standardized version of projectileExpansion - reaction-trigger.lua - trigger commands when custom reactions complete - replaces autoSyndrome - reaction-trigger-transition.lua - a tool for converting mods from autoSyndrome to reaction-trigger - random-trigger.lua - triggers random scripts that you register - skill-change.lua - for incrementing and setting skills - spawn-flow.lua - creates flows, like mist or dragonfire - syndrome-trigger.lua - trigger commands when syndromes happen - transform-unit.lua - shapeshifts a unit, possibly permanently - - Misc improvements: - new function in utils.lua for standardized argument processing - - Removed - digmat.rb: digFlood does the same functionality with less FPS impact - scripts/invasionNow: scripts/modtools/force.lua does it better - autoSyndrome replaced with scripts/modtools/reaction-trigger.lua - syndromeTrigger replaced with scripts/modtools/syndrome-trigger.lua - devel/printArgs plugin converted to scripts/devel/print-args.lua - -DFHack v0.40.08-r1 -================== - -Was a mistake. Don't use it. - -DFHack v0.34.11-r5 -================== -:: - - Internals: - - support for calling a lua function via a protobuf request (demonstrated by dfhack-run --lua). - - support for basic filesystem operations (e.g. chdir, mkdir, rmdir, stat) in C++ and Lua - - Lua API for listing files in directory. Needed for mod-manager. - - Lua API for creating unit combat reports and writing to gamelog. - - Lua API for running arbitrary DFHack commands - - support for multiple raw/init.d/*.lua init scripts in one save. - - eventful now has a more friendly way of making custom sidebars - - on Linux and OSX the console now supports moving the cursor back and forward by a whole word. - - New scripts: - - gui/mod-manager: allows installing/uninstalling mods into df from df/mods directory. - - gui/clone-uniform: duplicates the currently selected uniform in the military screen. - - fix/build-location: partial work-around for bug 5991 (trying to build wall while standing on it) - - undump-buildings: removes dump designation from materials used in buildings. - - exportlegends: exports data from legends mode, allowing a set-and-forget export of large worlds. - - log-region: each time a fort is loaded identifying information will be written to the gamelog. - - dfstatus: show an overview of critical stock quantities, including food, drinks, wood, and bars. - - New commands: - - 'plant create' - spawn a new shrub under the cursor - - command-prompt: a dfhack command prompt in df. - - New tweaks: - - craft-age-wear: make crafted items wear out with time like in old versions (bug 6003) - - adamantine-cloth-wear: stop adamantine clothing from wearing out (bug 6481) - - confirm-embark: adds a prompt before embarking (on the "prepare carefully" screen) - - New plugins: - - rendermax: replace the renderer with something else. Most interesting is "rendermax light"- a lighting engine for df. - - automelt: allows marking stockpiles for automelt (i.e. any items placed in stocpile will be designated for melting) - - embark-tools: implementations of Embark Anywhere, Nano Embark, and a few other embark-related utilities - - building-hacks: Allows to add custom functionality and/or animations to buildings. - - petcapRemover: triggers pregnancies in creatures so that you can effectively raise the default - pet population cap from the default 50 - - Misc improvements: - - plant: move the 'grow', 'extirpate' and 'immolate' commands as 'plant' subcommands - - digfort: improved csv parsing, add start() comment handling - - exterminate: allow specifying a caste (exterminate gob:male) - - createitem: in adventure mode it now defaults to the controlled unit as maker. - - autotrade: adds "(Un)mark All" options to both panes of trade screen. - - mousequery: several usability improvements. - - mousequery: show live overlay (in menu area) of what's on the tile under the mouse cursor. - - search: workshop profile search added. - - dwarfmonitor: add screen to summarise preferences of fortress dwarfs. - - getplants: add autochop function to automate woodcutting. - - stocks: added more filtering and display options. - - Siege engine plugin: - - engine quality and distance to target now affect accuracy - - firing the siege engine at a target produces a combat report - - improved movement speed computation for meandering units - - operators in Prepare To Fire mode are released from duty once - hungry/thirsty if there is a free replacement - -DFHack v0.34.11-r4 -================== -:: - - New commands: - - diggingInvaders - allows invaders to dig and/or deconstruct walls and buildings in order to get at your dwarves. - - digFlood - automatically dig out specified veins as they are revealed - - enable, disable - Built-in commands that can be used to enable/disable many plugins. - - restrictice - Restrict traffic on squares above visible ice. - - restrictliquid - Restrict traffic on every visible square with liquid. - - treefarm - automatically chop trees and dig obsidian - New scripts: - - autobutcher: A GUI front-end for the autobutcher plugin. - - invasionNow: trigger an invasion, or many - - locate_ore: scan the map for unmined ore veins - - masspit: designate caged creatures in a zone for pitting - - multicmd: run a sequence of dfhack commands, separated by ';' - - startdwarf: change the number of dwarves for a new embark - - digmat: dig veins/layers tile by tile, as discovered - Misc improvements: - - autoSyndrome: - disable by default - reorganized special tags - minimized error spam - reset policies: if the target already has an instance of the syndrome you can skip, - add another instance, reset the timer, or add the full duration to the time remaining - - core: fix SC_WORLD_(UN)LOADED event for arena mode - - exterminate: renamed from slayrace, add help message, add butcher mode - - fastdwarf: fixed bug involving fastdwarf and teledwarf being on at the same time - - magmasource: rename to 'source', allow water/magma sources/drains - - ruby: add df.dfhack_run "somecommand" - - syndromeTrigger: replaces and extends trueTransformation. Can trigger things when syndromes are added for any reason. - - tiletypes: support changing tile material to arbitrary stone. - - workNow: can optionally look for jobs when jobs are completed - New tweaks: - - hive-crash: Prevent crash if bees die in a hive with ungathered products (bug 6368). - New plugins: - - 3dveins: Reshapes all veins on the map in a way that flows between Z levels. May be unstable. Backup before using. - - autotrade: Automatically send items in marked stockpiles to trade depot, when trading is possible. - - buildingplan: Place furniture before it's built - - dwarfmonitor: Records dwarf activity to measure fort efficiency - - mousequery: Look and poke at the map elements with the mouse. - - outsideOnly: make raw-specified buildings impossible to build inside - - resume: A plugin to help display and resume suspended constructions conveniently - - stocks: An improved stocks display screen. - Internals: - - Core: there is now a per-save dfhack.init file for when the save is loaded, and another for when it is unloaded - - EventManager: fixed job completion detection, fixed removal of TICK events, added EQUIPMENT_CHANGE event - - Lua API for a better random number generator and perlin noise functions. - - Once: easy way to make sure something happens once per run of DF, such as an error message - -DFHack v0.34.11-r3 -================== -:: - - Internals: - - support for displaying active keybindings properly. - - support for reusable widgets in lua screen library. - - Maps::canStepBetween: returns whether you can walk between two tiles in one step. - - EventManager: monitors various in game events centrally so that individual plugins - don't have to monitor the same things redundantly. - - Now works with OSX 10.6.8 - Notable bugfixes: - - autobutcher can be re-enabled again after being stopped. - - stopped Dwarf Manipulator from unmasking vampires. - - Stonesense is now fixed on OSX - Misc improvements: - - fastdwarf: new mode using debug flags, and some internal consistency fixes. - - added a small stand-alone utility for applying and removing binary patches. - - removebadthoughts: add --dry-run option - - superdwarf: work in adventure mode too - - tweak stable-cursor: carries cursor location from/to Build menu. - - deathcause: allow selection from the unitlist screen - - slayrace: allow targetting undeads - New tweaks: - - tweak military-training: speed up melee squad training up to 10x (normally 3-5x). - New scripts: - - binpatch: the same as the stand-alone binpatch.exe, but works at runtime. - - region-pops: displays animal populations of the region and allows tweaking them. - - lua: lua interpreter front-end converted to a script from a native command. - - dfusion: misc scripts with a text based menu. - - embark: lets you embark anywhere. - - lever: list and pull fort levers from the dfhack console. - - stripcaged: mark items inside cages for dumping, eg caged goblin weapons. - - soundsense-season: writes the correct season to gamelog.txt on world load. - - create-items: spawn items - - fix/cloth-stockpile: fixes bug 5739; needs to be run after savegame load every time. - New GUI scripts: - - gui/guide-path: displays the cached path for minecart Guide orders. - - gui/workshop-job: displays inputs of a workshop job and allows tweaking them. - - gui/workflow: a front-end for the workflow plugin (part inspired by falconne). - - gui/assign-rack: works together with a binary patch to fix weapon racks. - - gui/gm-editor: an universal editor for lots of dfhack things. - - gui/companion-order: a adventure mode command interface for your companions. - - gui/advfort: a way to do jobs with your adventurer (e.g. build fort). - New binary patches (for use with binpatch): - - armorstand-capacity: doubles the capacity of armor stands. - - custom-reagent-size: lets custom reactions use small amounts of inputs. - - deconstruct-heapfall: stops some items still falling on head when deconstructing. - - deconstruct-teleport: stops items from 16x16 block teleporting when deconstructing. - - hospital-overstocking: stops hospital overstocking with supplies. - - training-ammo: lets dwarves with quiver full of combat-only ammo train. - - weaponrack-unassign: fixes bug that negates work done by gui/assign-rack. - Workflow plugin: - - properly considers minecarts assigned to routes busy. - - code for deducing job outputs rewritten in lua for flexibility. - - logic fix: collecting webs produces silk, and ungathered webs are not thread. - - items assigned to squads are considered busy, even if not in inventory. - - shearing and milking jobs are supported, but only with generic MILK or YARN outputs. - - workflow announces when the stock level gets very low once a season. - New Fix Armory plugin: - Together with a couple of binary patches and the gui/assign-rack script, - this plugin makes weapon racks, armor stands, chests and cabinets in - properly designated barracks be used again for storage of squad equipment. - New Search plugin by falconne: - Adds an incremental search function to the Stocks, Trading, Stockpile and Unit List screens. - New AutoMaterial plugin by falconne: - Makes building constructions (walls, floors, fortifications, etc) a little bit easier by - saving you from having to trawl through long lists of materials each time you place one. - Dfusion plugin: - Reworked to make use of lua modules, now all the scripts can be used from other scripts. - New Eventful plugin: - A collection of lua events, that will allow new ways to interact with df world. - Auto syndrome plugin: - A way of automatically applying boiling rock syndromes and calling dfhack commands controlled by raws. - Infinite sky plugin: - Create new z-levels automatically or on request. - True transformation plugin: - A better way of doing permanent transformations that allows later transformations. - Work now plugin: - Makes the game assign jobs every time you pause. - -DFHack v0.34.11-r2 -================== -:: - - Internals: - - full support for Mac OS X. - - a plugin that adds scripting in ruby. - - support for interposing virtual methods in DF from C++ plugins. - - support for creating new interface screens from C++ and lua. - - added various other API functions. - Notable bugfixes: - - better terminal reset after exit on linux. - - seedwatch now works on reclaim. - - the sort plugin won't crash on cages anymore. - Misc improvements: - - autodump: can move items to any walkable tile, not just floors. - - stripcaged: by default keep armor, new dumparmor option. - - zone: allow non-domesticated birds in nestboxes. - - workflow: quality range in constraints. - - cleanplants: new command to remove rain water from plants. - - liquids: can paint permaflow, i.e. what makes rivers power water wheels. - - prospect: pre-embark prospector accounts for caves & magma sea in its estimate. - - rename: supports renaming stockpiles, workshops, traps, siege engines. - - fastdwarf: now has an additional option to make dwarves teleport to their destination. - New commands: - - misery: multiplies every negative thought gained (2x by default). - - digtype: designates every tile of the same type of vein on the map for 'digging' (any dig designation). - New tweaks: - - tweak stable-cursor: keeps exact cursor position between d/k/t/q/v etc menus. - - tweak patrol-duty: makes Train orders reduce patrol timer, like the binary patch does. - - tweak readable-build-plate: fix unreadable truncation in unit pressure plate build ui. - - tweak stable-temp: fixes bug 6012; may improve FPS by 50-100% on a slow item-heavy fort. - - tweak fast-heat: speeds up item heating & cooling, thus making stable-temp act faster. - - tweak fix-dimensions: fixes subtracting small amounts from stacked liquids etc. - - tweak advmode-contained: fixes UI bug in custom reactions with container inputs in advmode. - - tweak fast-trade: Shift-Enter for selecting items quckly in Trade and Move to Depot screens. - - tweak military-stable-assign: Stop rightmost list of military->Positions from jumping to top. - - tweak military-color-assigned: In same list, color already assigned units in brown & green. - New scripts: - - fixnaked: removes thoughts about nakedness. - - setfps: set FPS cap at runtime, in case you want slow motion or speed-up. - - siren: wakes up units, stops breaks and parties - but causes bad thoughts. - - fix/population-cap: run after every migrant wave to prevent exceeding the cap. - - fix/stable-temp: counts items with temperature updates; does instant one-shot stable-temp. - - fix/loyaltycascade: fix units allegiance, eg after ordering a dwarf merchant kill. - - deathcause: shows the circumstances of death for a given body. - - digfort: designate areas to dig from a csv file. - - drainaquifer: remove aquifers from the map. - - growcrops: cheat to make farm crops instantly grow. - - magmasource: continuously spawn magma from any map tile. - - removebadthoughts: delete all negative thoughts from your dwarves. - - slayrace: instakill all units of a given race, optionally with magma. - - superdwarf: per-creature fastdwarf. - New GUI scripts: - - gui/mechanisms: browse mechanism links of the current building. - - gui/room-list: browse other rooms owned by the unit when assigning one. - - gui/liquids: a GUI front-end for the liquids plugin. - - gui/rename: renaming stockpiles, workshops and units via an in-game dialog. - - gui/power-meter: front-end for the Power Meter plugin. - - gui/siege-engine: front-end for the Siege Engine plugin. - - gui/choose-weapons: auto-choose matching weapons in the military equip screen. - Autolabor plugin: - - can set nonidle hauler percentage. - - broker excluded from all labors when needed at depot. - - likewise, anybody with a scheduled diplomat meeting. - New Dwarf Manipulator plugin: - Open the unit list, and press 'l' to access a Dwarf Therapist like UI in the game. - New Steam Engine plugin: - Dwarven Water Reactors don't make any sense whatsoever and cause lag, so this may be - a replacement for those concerned by it. The plugin detects if a workshop with a - certain name is in the raws used by the current world, and provides the necessary - behavior. See hack/raw/*_steam_engine.txt for the necessary raw definitions. - Note: Stuff like animal treadmills might be more period, but absolutely can't be - done with tools dfhack has access to. - New Power Meter plugin: - When activated, implements a pressure plate modification that detects power in gear - boxes built on the four adjacent N/S/W/E tiles. The gui/power-meter script implements - the necessary build configuration UI. - New Siege Engine plugin: - When enabled and configured via gui/siege-engine, allows aiming siege engines - at a designated rectangular area with 360 degree fire range and across Z levels; - this works by rewriting the projectile trajectory immediately after it appears. - Also supports loading catapults with non-boulder projectiles, taking from a stockpile, - and restricting operator skill range like with ordinary workshops. - Disclaimer: not in any way to undermine the future siege update from Toady, but - the aiming logic of existing engines hasn't been updated since 2D, and is almost - useless above ground :(. Again, things like making siegers bring their own engines - is totally out of the scope of dfhack and can only be done by Toady. - New Add Spatter plugin: - Detects reactions with certain names in the raws, and changes them from adding - improvements to adding item contaminants. This allows directly covering items - with poisons. The added spatters are immune both to water and 'clean items'. - Intended to give some use to all those giant cave spider poison barrels brought - by the caravans. - diff --git a/NEWS.rst b/NEWS.rst new file mode 100644 index 0000000000..fb16ab3f8b --- /dev/null +++ b/NEWS.rst @@ -0,0 +1,969 @@ +.. comment + This is the changelog file for DFHack. If you add or change anything, note + it here under the heading "DFHack Future", in the appropriate section. + Items within each section are listed in alphabetical order to minimise merge + conflicts. Try to match the style and level of detail of the other entries. + + Sections for each release are added as required, and consist solely of the + following in order as subheadings:: + + Internals + Lua + New [Internal Commands | Plugins | Scripts | Tweaks] + Fixes + Misc Improvements + Removed + + When referring to a script, plugin, or command, use backticks (```) to + create a link to the relevant documentation - and check that the docs are + still up to date! + + When adding a new release, change "DFHack future" to the appropriate title + before releasing, and then add a new "DFHack future" section after releasing. + + +######### +Changelog +######### + +.. contents:: + :depth: 2 + + +DFHack 0.40.24-r4 +================= + +Internals +--------- +- A method for caching screen output is now available to Lua (and C++) +- Developer plugins can be ignored on startup by setting the ``DFHACK_NO_DEV_PLUGINS`` environment variable +- The console on Linux and OS X now recognizes keyboard input between prompts +- JSON libraries available (C++ and Lua) +- More DFHack build information used in plugin version checks and available to plugins and lua scripts +- Fixed a rare overflow issue that could cause crashes on Linux and OS X +- Stopped DF window from receiving input when unfocused on OS X +- Fixed issues with keybindings involving Ctrl-A and Ctrl-Z, as well as Alt-E/U/N on OS X +- Multiple contexts can now be specified when adding keybindings +- Keybindings can now use F10-F12 and 0-9 +- Plugin system is no longer restricted to plugins that exist on startup +- :file:`dfhack.init` file locations significantly generalized + +Lua +--- +- Scripts can be enabled with the built-in enable/disable commands +- A new function, ``reqscript()``, is available as a safer alternative to ``script_environment()`` +- Lua viewscreens can choose not to intercept the OPTIONS keybinding + +New internal commands +--------------------- +- kill-lua: Interrupt running Lua scripts +- type: Show where a command is implemented + +New plugins +----------- +- `confirm`: Adds confirmation dialogs for several potentially dangerous actions +- `fix-unit-occupancy`: Fixes issues with unit occupancy, such as faulty "unit blocking tile" messages (:bug:`3499`) +- title-version (formerly vshook): Display DFHack version on title screen + +New scripts +----------- +- `armoks-blessing`: Adjust all attributes, personality, age and skills of all dwarves in play +- `brainwash`: brainwash a dwarf (modifying their personality) +- `burial`: sets all unowned coffins to allow burial ("-pets" to allow pets too) +- `deteriorateclothes`: make worn clothes on the ground wear far faster to boost FPS +- `deterioratecorpses`: make body parts wear away far faster to boost FPS +- `deterioratefood`: make food vanish after a few months if not used +- `elevate-mental`: elevate all the mental attributes of a unit +- `elevate-physical`: elevate all the physical attributes of a unit +- `emigration`: stressed dwarves may leave your fortress if they see a chance +- `fix-ster`: changes fertility/sterility of animals or dwarves +- `gui/family-affairs`: investigate and alter romantic relationships +- `make-legendary`: modify skill(s) of a single unit +- `modtools/create-unit`: create new units from nothing +- `modtools/equip-item`: a script to equip items on units +- `points`: set number of points available at embark screen +- `pref-adjust`: Adjust all preferences of all dwarves in play +- `rejuvenate`: make any "old" dwarf 20 years old +- `starvingdead`: make undead weaken after one month on the map, and crumble after six +- `view-item-info`: adds information and customisable descriptions to item viewscreens +- `warn-starving`: check for starving, thirsty, or very drowsy units and pause with warning if any are found + +New tweaks +---------- +- embark-profile-name: Allows the use of lowercase letters when saving embark profiles +- kitchen-keys: Fixes DF kitchen meal keybindings +- kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences +- kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs + +Fixes +----- +- Plugins with vmethod hooks can now be reloaded on OS X +- Lua's ``os.system()`` now works on OS X +- Fixed default arguments in Lua gametype detection functions +- Circular lua dependencies (reqscript/script_environment) fixed +- Prevented crash in ``Items::createItem()`` +- `buildingplan`: Now supports hatch covers +- `gui/create-item`: fixed assigning quality to items, made :kbd:`Esc` work properly +- `gui/gm-editor`: handles lua tables properly +- help: now recognizes built-in commands, like "help" +- `manipulator`: fixed crash when selecting custom professions when none are found +- `remotefortressreader`: fixed crash when attempting to send map info when no map was loaded +- `search-plugin`: fixed crash in unit list after cancelling a job; fixed crash when disabling stockpile category after searching in a subcategory +- `stockpiles`: now checks/sanitizes filenames when saving +- `stocks`: fixed a crash when right-clicking +- `steam-engine`: fixed a crash on arena load; number keys (e.g. 2/8) take priority over cursor keys when applicable +- tweak fps-min fixed +- tweak farm-plot-select: Stopped controls from appearing when plots weren't fully built +- `workflow`: Fixed some issues with stuck jobs. Existing stuck jobs must be cancelled and re-added +- `zone`: Fixed a crash when using ``zone set`` (and a few other potential crashes) + +Misc Improvements +----------------- +- DFHack documentation: + + - massively reorganised, into files of more readable size + - added many missing entries + - indexes, internal links, offline search all documents + - includes documentation of linked projects (df-structures, third-party scripts) + - better HTML generation with Sphinx + - documentation for scripts now located in source files + +- `autolabor`: + + - Stopped modification of labors that shouldn't be modified for brokers/diplomats + - Prioritize skilled dwarves more efficiently + - Prevent dwarves from running away with tools from previous jobs + +- `automaterial`: Fixed several issues with constructions being allowed/disallowed incorrectly when using box-select +- `dwarfmonitor`: + + - widgets' positions, formats, etc. are now customizable (see Readme) + - weather display now separated from the date display + - New mouse cursor widget + +- `gui/dfstatus`: Can enable/disable individual categories and customize metal bar list +- `full-heal`: ``-r`` option removes corpses +- `gui/gm-editor` + + - Pointers can now be displaced + - Added some useful aliases: "item" for the selected item, "screen" for the current screen, etc. + - Now avoids errors with unrecognized types + +- `gui/hack-wish`: renamed to `gui/create-item` +- "keybinding list" accepts a context +- `lever`: + + - Lists lever names + - "lever pull" can be used to pull the currently-selected lever + +- memview: Fixed display issue +- `modtools/create-item`: arguments are named more clearly, and you can specify the creator to be the unit with id ``df.global.unit_next_id-1`` (useful in conjunction with `modtools/create-unit`) +- nyan: Can now be stopped with dfhack-run +- plug: lists all plugins; shows state and number of commands in plugins +- `prospect`: works from within command-prompt +- `quicksave`: Restricted to fortress mode +- `remotefortressreader`: Exposes more information +- `search-plugin`: + + - Supports noble suggestion screen (e.g. suggesting a baron) + - Supports fortress mode loo[k] menu + - Recognizes ? and ; keys + +- `stocks`: can now match beginning and end of item names +- `teleport`: Fixed cursor recognition +- `tidlers`, `twaterlvl`: now implemented by scripts instead of a plugin +- `tweak`: + + - debug output now logged to stderr.log instead of console - makes DFHack start faster + - farm-plot-select: Fixed issues with selecting undiscovered crops + +- `workflow`: Improved handling of plant reactions + +Removed +------- +- `embark-tools` nano: 1x1 embarks are now possible in vanilla 0.40.24 + +DFHack 0.40.24-r3 +================= + +Internals +--------- +- Ruby library now included on OS X - Ruby scripts should work on OS X 10.10 +- libstdc++ should work with older versions of OS X +- Added support for ``onLoadMap.init``/``onUnloadMap.init`` scripts +- game type detection functions are now available in the World module +- The ``DFHACK_LOG_MEM_RANGES`` environment variable can be used to log information to ``stderr.log`` on OS X +- Fixed adventure mode menu names +- Fixed command usage information for some commands + +Lua +--- +- Lua scripts will only be reloaded if necessary +- Added a ``df2console()`` wrapper, useful for printing DF (CP437-encoded) text to the console in a portable way +- Added a ``strerror()`` wrapper + +New Internal Commands +--------------------- +- `hide`, `show`: hide and show the console on Windows +- `sc-script`: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts) + +New Plugins +----------- +- `autohauler`: A hauling-only version of autolabor + +New Scripts +----------- +- `modtools/reaction-product-trigger`: triggers callbacks when products are produced (contrast with when reactions complete) + +New Tweaks +---------- +- `fps-min `: Fixes the in-game minimum FPS setting +- `shift-8-scroll `: Gives Shift+8 (or ``*``) priority when scrolling menus, instead of scrolling the map +- `tradereq-pet-gender `: Displays pet genders on the trade request screen + +Fixes +----- +- Fixed game type detection in `3dveins`, `gui/create-item`, `reveal`, `seedwatch` +- PRELOAD_LIB: More extensible on Linux +- `add-spatter`, `eventful`: Fixed crash on world load +- `add-thought`: Now has a proper subthought arg. +- `building-hacks`: Made buildings produce/consume correct amount of power +- `fix-armory`: compiles and is available again (albeit with issues) +- `gui/gm-editor`: Added search option (accessible with "s") +- `hack-wish `: Made items stack properly. +- `modtools/skill-change`: Made level granularity work properly. +- `show-unit-syndromes`: should work +- `stockflow`: + + - Fixed error message in Arena mode + - no longer checks the DF version + - fixed ballistic arrow head orders + - convinces the bookkeeper to update records more often' + +- `zone`: Stopped crash when scrolling cage owner list + +Misc Improvements +----------------- +- `autolabor`: A negative pool size can be specified to use the most unskilled dwarves +- `building-hacks`: + + - Added a way to allow building to work even if it consumes more power than is available. + - Added setPower/getPower functions. + +- `catsplosion`: Can now trigger pregnancies in (most) other creatures +- `exportlegends`: ``info`` and ``all`` options export ``legends_plus.xml`` with more data for legends utilities +- `manipulator`: + + - Added ability to edit nicknames/profession names + - added "Job" as a View Type, in addition to "Profession" and "Squad" + - added custom profession templates with masking + +- `remotefortressreader`: Exposes more information + + +DFHack 0.40.24-r2 +================= + +Internals +--------- +- Lua scripts can set environment variables of each other with dfhack.run_script_with_env. +- Lua scripts can now call each others internal nonlocal functions with dfhack.script_environment(scriptName).functionName(arg1,arg2). +- `eventful`: Lua reactions no longer require LUA_HOOK as a prefix; you can register a callback for the completion of any reaction with a name +- Filesystem module now provides file access/modification times and can list directories (normally and recursively) +- Units Module: New functions:: + + isWar + isHunter + isAvailableForAdoption + isOwnCiv + isOwnRace + getRaceName + getRaceNamePlural + getRaceBabyName + getRaceChildName + isBaby + isChild + isAdult + isEggLayer + isGrazer + isMilkable + isTrainableWar + isTrainableHunting + isTamable + isMale + isFemale + isMerchant + isForest + isMarkedForSlaughter + +- Buildings Module: New Functions:: + + isActivityZone + isPenPasture + isPitPond + isActive + findPenPitAt + +Fixes +----- +- ``dfhack.run_script`` should correctly find save-specific scripts now. +- `add-thought`: updated to properly affect stress. +- `hfs-pit`: should work now +- `autobutcher`: takes gelding into account +- init.lua existence checks should be more reliable (notably when using non-English locales) + +Misc Improvements +----------------- +Multiline commands are now possible inside dfhack.init scripts. See :file:`dfhack.init-example` for example usage. + + +DFHack 0.40.24-r1 +================= + +Internals +--------- +CMake shouldn't cache DFHACK_RELEASE anymore. People may need to manually update/delete their CMake cache files to get rid of it. + + +DFHack 0.40.24-r0 +================= + +Internals +--------- +- `EventManager`: fixed crash error with EQUIPMENT_CHANGE event. +- key modifier state exposed to Lua (ie :kbd:`Ctrl`, :kbd:`Alt`, :kbd:`Shift`) + +Fixes +----- +``dfhack.sh`` can now be run from other directories on OS X + +New Plugins +----------- +- `blueprint`: export part of your fortress to quickfort .csv files + +New Scripts +----------- +- `hotkey-notes`: print key, name, and jump position of hotkeys + +Removed +------- +- embark.lua +- needs_porting/* + +Misc Improvements +----------------- +Added support for searching more lists + + +DFHack 0.40.23-r1 +================= + +Internals +- plugins will not be loaded if globals they specify as required are not located (should prevent some crashes) + +Fixes +----- +- Fixed numerous (mostly Lua-related) crashes on OS X by including a more up-to-date libstdc++ +- :kbd:`Alt` should no longer get stuck on Windows (and perhaps other platforms as well) +- `gui/advfort` works again +- `autobutcher`: takes sexualities into account +- devel/export-dt-ini: Updated for 0.40.20+ +- `digfort`: now checks file type and existence +- `exportlegends`: Fixed map export +- `full-heal`: Fixed a problem with selecting units in the GUI +- `gui/hack-wish`: Fixed restrictive material filters +- `mousequery`: Changed box-select key to Alt+M +- `dwarfmonitor`: correct date display (month index, separator) +- `putontable`: added to the readme +- `siren` should work again +- stderr.log: removed excessive debug output on OS X +- `trackstop`: No longer prevents cancelling the removal of a track stop or roller. +- Fixed a display issue with ``PRINT_MODE:TEXT`` +- Fixed a symbol error (MapExtras::BiomeInfo::MAX_LAYERS) when compiling DFHack in Debug mode + +New Plugins +----------- +- `fortplan`: designate construction of (limited) buildings from .csv file, quickfort-style + +New Scripts +----------- +- `gui/stockpiles`: an in-game interface for saving and loading stockpile settings files. +- `position`: Reports the current date, time, month, and season, plus some location info. Port/update of position.py +- `hfs-pit`: Digs a hole to hell under the cursor. Replaces needs_porting/hellhole.cpp + +Removed +------- +- embark.lua: Obsolete, use `embark-tools` + +New tweaks +---------- +- `eggs-fertile `: Displays an egg fertility indicator on nestboxes +- `max-wheelbarrow `: Allows assigning more than 3 wheelbarrows to a stockpile + +Misc Improvements +----------------- +- `embark-tools`: Added basic mouse support on the local map +- Made some adventure mode keybindings in :file:`dfhack.init-example` only work in adventure mode +- `gui/companion-order`: added a default keybinding +- further work on needs_porting + + +DFHack 0.40.19-r1 +================= + +Fixes +----- +- `modtools/reaction-trigger`: fixed typo +- `modtools/item-trigger`: should now work with item types + +New plugins +----------- +- `savestock, loadstock `: save and load stockpile settings across worlds and saves + +New scripts +----------- +- `remove-stress`: set selected or all units unit to -1,000,000 stress (this script replaces removebadthoughts) + +Misc improvements +----------------- +- `command-prompt`: can now access selected items, units, and buildings +- `autolabor`: add an optional talent pool parameter + + +DFHack 0.40.16-r1 +================= + +Internals +--------- +- `EventManager` should handle INTERACTION triggers a little better. It still can get confused about who did what but only rarely. +- `EventManager` should no longer trigger REPORT events for old reports after loading a save. +- lua/persist-table: a convenient way of using persistent tables of arbitrary structure and dimension in Lua + +Fixes +----- +- `mousequery`: Disabled when linking levers +- `stocks`: Melting should work now +- `full-heal`: Updated with proper argument handling +- `modtools/reaction-trigger-transition`: should produce the correct syntax now +- `superdwarf`: should work better now +- `forum-dwarves`: update for new df-structures changes + +New Scripts +----------- +- `adaptation`: view or set the cavern adaptation level of your citizens +- `add-thought`: allows the user to add thoughts to creatures. +- `gaydar`: detect the sexual orientation of units on the map +- `markdown`: Save a copy of a text screen in markdown (for reddit among others). +- devel/all-bob: renames everyone Bob to help test interaction-trigger + +Misc Improvements +----------------- +- `autodump`: Can now mark a stockpile for auto-dumping (similar to automelt and autotrade) +- `buildingplan`: Can now auto-allocate rooms to dwarves with specific positions (e.g. expedition leader, mayor) +- `dwarfmonitor`: now displays a weather indicator and date +- lua/syndrome-util, `modtools/add-syndrome`: now you can remove syndromes by SYN_CLASS +- No longer write empty :file:`.history` files + + +DFHack 0.40.15-r1 +================= + +Fixes +----- +- mousequery: Fixed behavior when selecting a tile on the lowest z-level + +Misc Improvements +----------------- +- `EventManager`: deals with frame_counter getting reset properly now. +- `modtools/item-trigger`: fixed equip/unequip bug and corrected minor documentation error +- `teleport`: Updated with proper argument handling and proper unit-at-destination handling. +- `autotrade`: Removed the newly obsolete :guilabel:`Mark all` functionality. +- `search-plugin`: Adapts to the new trade screen column width +- `tweak fast-trade `: Switching the fast-trade keybinding to Shift-Up/Shift-Down, due to Select All conflict + + +DFHack 0.40.14-r1 +================= + +Internals +--------- +- The DFHack console can now be disabled by setting the DFHACK_DISABLE_CONSOLE environment variable: ``DFHACK_DISABLE_CONSOLE=1 ./dfhack`` + +Fixes +----- +- Stopped duplicate load/unload events when unloading a world +- Stopped ``-e`` from being echoed when DFHack quits on Linux +- `automelt`: now uses a faster method to locate items +- `autotrade`: "Mark all" no longer double-marks bin contents +- `drain-aquifer`: new script replaces the buggy plugin +- `embark-tools`: no longer conflicts with keys on the notes screen +- `fastdwarf`: Fixed problems with combat/attacks +- `forum-dwarves`: should work now +- `manipulator`: now uses a stable sort, allowing sorting by multiple categories +- `rendermax`: updated to work with 0.40 + +New Plugins +----------- +- `trackstop`: Shows track stop friction and dump direction in its :kbd:`q` menu + +New Tweaks +---------- +- farm-plot-select: Adds "Select all" and "Deselect all" options to farm plot menus +- import-priority-category: Allows changing the priority of all goods in a category when discussing an import agreement with the liaison +- manager-quantity: Removes the limit of 30 jobs per manager order +- civ-view-agreement: Fixes overlapping text on the "view agreement" screen +- nestbox-color: Fixes the color of built nestboxes + +Misc Improvements +----------------- +- `exportlegends`: can now handle site maps + + +DFHack 0.40.13-r1 +================= + +Internals +--------- +- unified spatter structs +- added ruby df.print_color(color, string) method for dfhack console + +Fixes +----- +- no more ``-e`` after terminating +- fixed `superdwarf` + + +DFHack 0.40.12-r1 +================= + +Internals +--------- +- support for global :file:`onLoadWorld.init` and :file:`onUnloadWorld.init` files, called when loading and unloading a world +- Close file after loading a binary patch. + +New Plugins +----------- +- `hotkeys`: Shows ingame viewscreen with all dfhack keybindings active in current mode. +- `automelt`: allows marking stockpiles so any items placed in them will be designated for melting + +Fixes +----- +- possible crash fixed for `gui/hack-wish` +- `search-plugin`: updated to not conflict with BUILDJOB_SUSPEND +- `workflow`: job_material_category -> dfhack_material_category + +Misc Improvements +----------------- +- now you can use ``@`` to print things in interactive Lua with subtley different semantics +- optimizations for stockpiles for `autotrade` and `stockflow` +- updated `exportlegends` to work with new maps, dfhack 40.11 r1+ + + +DFHack 0.40.11-r1 +================= + +Internals +- Plugins on OS X now use ``.plug.dylib` as an extension instead of ``.plug.so`` + +Fixes +----- +- `3dveins`: should no longer hang/crash on specific maps +- `autotrade`, `search-plugin`: fixed some layout issues +- `deathcause`: updated +- `gui/hack-wish`: should work now +- `reveal`: no longer allocates data for nonexistent map blocks +- Various documentation fixes and updates + + +DFHack v0.40.10-r1 +================== + +A few bugfixes. + +DFHack v0.40.08-r2 +================== + +Internals +--------- +- supported per save script folders +- Items module: added createItem function +- Sorted CMakeList for plugins and plugins/devel +- diggingInvaders no longer builds if plugin building is disabled +- `EventManager`: EQUIPMENT_CHANGE now triggers for new units. New events:: + + ON_REPORT + UNIT_ATTACK + UNLOAD + INTERACTION + +New Scripts +----------- +- lua/repeat-util: makes it easier to make things repeat indefinitely +- lua/syndrome-util: makes it easier to deal with unit syndromes +- forum-dwarves: helps copy df viewscreens to a file +- full-heal: fully heal a unit +- remove-wear: removes wear from all items in the fort +- repeat: repeatedly calls a script or a plugin +- ShowUnitSyndromes: shows syndromes affecting units and other relevant info +- teleport: teleports units +- devel/print-args +- fix/blood-del: makes it so civs don't bring barrels full of blood ichor or goo +- fix/feeding-timers: reset the feeding timers of all units +- gui/hack-wish: creates items out of any material +- gui/unit-info-viewer: displays information about units +- modtools/add-syndrome: add a syndrome to a unit or remove one +- modtools/anonymous-script: execute an lua script defined by a string. Useful for the ``*-trigger`` scripts. +- modtools/force: forces events: caravan, migrants, diplomat, megabeast, curiousbeast, mischievousbeast, flier, siege, nightcreature +- modtools/item-trigger: triggers commands based on equipping, unequipping, and wounding units with items +- modtools/interaction-trigger: triggers commands when interactions happen +- modtools/invader-item-destroyer: destroys invaders' items when they die +- modtools/moddable-gods: standardized version of Putnam's moddable gods script +- modtools/projectile-trigger: standardized version of projectileExpansion +- modtools/reaction-trigger: trigger commands when custom reactions complete; replaces autoSyndrome +- modtools/reaction-trigger-transition: a tool for converting mods from autoSyndrome to reaction-trigger +- modtools/random-trigger: triggers random scripts that you register +- modtools/skill-change: for incrementing and setting skills +- modtools/spawn-flow: creates flows, like mist or dragonfire +- modtools/syndrome-trigger: trigger commands when syndromes happen +- modtools/transform-unit: shapeshifts a unit, possibly permanently + +Misc improvements +----------------- +- new function in utils.lua for standardized argument processing + +Removed +------- +- digmat.rb: digFlood does the same functionality with less FPS impact +- scripts/invasionNow: scripts/modtools/force.lua does it better +- autoSyndrome replaced with scripts/modtools/reaction-trigger.lua +- syndromeTrigger replaced with scripts/modtools/syndrome-trigger.lua +- devel/printArgs plugin converted to scripts/devel/print-args.lua +- outsideOnly plugin replaced by modtools/outside-only + + +DFHack v0.40.08-r1 +================== + +Was a mistake. Don't use it. + +DFHack v0.34.11-r5 +================== + +Internals +--------- +- support for calling a lua function via a protobuf request (demonstrated by dfhack-run --lua). +- support for basic filesystem operations (e.g. chdir, mkdir, rmdir, stat) in C++ and Lua +- Lua API for listing files in directory. Needed for mod-manager. +- Lua API for creating unit combat reports and writing to gamelog. +- Lua API for running arbitrary DFHack commands +- support for multiple ``raw/init.d/*.lua`` init scripts in one save. +- eventful now has a more friendly way of making custom sidebars +- on Linux and OS X the console now supports moving the cursor back and forward by a whole word. + +New scripts +----------- +- gui/mod-manager: allows installing/uninstalling mods into df from df/mods directory. +- gui/clone-uniform: duplicates the currently selected uniform in the military screen. +- fix/build-location: partial work-around for bug 5991 (trying to build wall while standing on it) +- undump-buildings: removes dump designation from materials used in buildings. +- exportlegends: exports data from legends mode, allowing a set-and-forget export of large worlds. +- log-region: each time a fort is loaded identifying information will be written to the gamelog. +- dfstatus: show an overview of critical stock quantities, including food, drinks, wood, and bars. +- command-prompt: a dfhack command prompt in df. + +New plugins +----------- +- rendermax: replace the renderer with something else, eg ``rendermax light``- a lighting engine +- automelt: allows marking stockpiles for automelt (i.e. any items placed in stocpile will be designated for melting) +- embark-tools: implementations of Embark Anywhere, Nano Embark, and a few other embark-related utilities +- building-hacks: Allows to add custom functionality and/or animations to buildings. +- petcapRemover: triggers pregnancies in creatures so that you can effectively raise the default pet population cap +- 'plant create': spawn a new shrub under the cursor + +New tweaks +---------- +- craft-age-wear: make crafted items wear out with time like in old versions (bug 6003) +- adamantine-cloth-wear: stop adamantine clothing from wearing out (bug 6481) +- confirm-embark: adds a prompt before embarking (on the "prepare carefully" screen) + +Misc improvements +----------------- +- plant: move the 'grow', 'extirpate' and 'immolate' commands as 'plant' subcommands +- digfort: improved csv parsing, add start() comment handling +- exterminate: allow specifying a caste (exterminate gob:male) +- createitem: in adventure mode it now defaults to the controlled unit as maker. +- autotrade: adds "(Un)mark All" options to both panes of trade screen. +- mousequery: several usability improvements. +- mousequery: show live overlay (in menu area) of what's on the tile under the mouse cursor. +- search: workshop profile search added. +- dwarfmonitor: add screen to summarise preferences of fortress dwarfs. +- getplants: add autochop function to automate woodcutting. +- stocks: added more filtering and display options. + +- Siege engine plugin: + + - engine quality and distance to target now affect accuracy + - firing the siege engine at a target produces a combat report + - improved movement speed computation for meandering units + - operators in Prepare To Fire mode are released from duty once hungry/thirsty if there is a free replacement + + +DFHack v0.34.11-r4 +================== + +New commands +------------ +- diggingInvaders - allows invaders to dig and/or deconstruct walls and buildings in order to get at your dwarves. +- digFlood - automatically dig out specified veins as they are revealed +- enable, disable - Built-in commands that can be used to enable/disable many plugins. +- restrictice - Restrict traffic on squares above visible ice. +- restrictliquid - Restrict traffic on every visible square with liquid. +- treefarm - automatically chop trees and dig obsidian + +New Scripts +----------- +- autobutcher: A GUI front-end for the autobutcher plugin. +- invasionNow: trigger an invasion, or many +- locate_ore: scan the map for unmined ore veins +- masspit: designate caged creatures in a zone for pitting +- multicmd: run a sequence of dfhack commands, separated by ';' +- startdwarf: change the number of dwarves for a new embark +- digmat: dig veins/layers tile by tile, as discovered + +Misc improvements +----------------- +- autoSyndrome: + + - disable by default + - reorganized special tags + - minimized error spam + - reset policies: if the target already has an instance of the syndrome you can skip, + add another instance, reset the timer, or add the full duration to the time remaining + +- core: fix SC_WORLD_(UN)LOADED event for arena mode +- exterminate: renamed from slayrace, add help message, add butcher mode +- fastdwarf: fixed bug involving fastdwarf and teledwarf being on at the same time +- magmasource: rename to ``source``, allow water/magma sources/drains +- ruby: add df.dfhack_run "somecommand" +- syndromeTrigger: replaces and extends trueTransformation. Can trigger things when syndromes are added for any reason. +- tiletypes: support changing tile material to arbitrary stone. +- workNow: can optionally look for jobs when jobs are completed + +New tweaks +---------- +- hive-crash: Prevent crash if bees die in a hive with ungathered products (bug 6368). + +New plugins +----------- +- 3dveins: Reshapes all veins on the map in a way that flows between Z levels. May be unstable. Backup before using. +- autotrade: Automatically send items in marked stockpiles to trade depot, when trading is possible. +- buildingplan: Place furniture before it's built +- dwarfmonitor: Records dwarf activity to measure fort efficiency +- mousequery: Look and poke at the map elements with the mouse. +- outsideOnly: make raw-specified buildings impossible to build inside +- resume: A plugin to help display and resume suspended constructions conveniently +- stocks: An improved stocks display screen. + +Internals +--------- +- Core: there is now a per-save dfhack.init file for when the save is loaded, and another for when it is unloaded +- EventManager: fixed job completion detection, fixed removal of TICK events, added EQUIPMENT_CHANGE event +- Lua API for a better random number generator and perlin noise functions. +- Once: easy way to make sure something happens once per run of DF, such as an error message + + +DFHack v0.34.11-r3 +================== + +Internals +--------- +- support for displaying active keybindings properly. +- support for reusable widgets in lua screen library. +- Maps::canStepBetween: returns whether you can walk between two tiles in one step. +- EventManager: monitors various in game events centrally so that individual plugins + don't have to monitor the same things redundantly. +- Now works with OS X 10.6.8 + +Notable bugfixes +---------------- +- autobutcher can be re-enabled again after being stopped. +- stopped Dwarf Manipulator from unmasking vampires. +- Stonesense is now fixed on OS X + +Misc improvements +----------------- +- fastdwarf: new mode using debug flags, and some internal consistency fixes. +- added a small stand-alone utility for applying and removing binary patches. +- removebadthoughts: add --dry-run option +- superdwarf: work in adventure mode too +- tweak stable-cursor: carries cursor location from/to Build menu. +- deathcause: allow selection from the unitlist screen +- slayrace: allow targetting undeads +- Workflow plugin: + + - properly considers minecarts assigned to routes busy. + - code for deducing job outputs rewritten in lua for flexibility. + - logic fix: collecting webs produces silk, and ungathered webs are not thread. + - items assigned to squads are considered busy, even if not in inventory. + - shearing and milking jobs are supported, but only with generic MILK or YARN outputs. + - workflow announces when the stock level gets very low once a season. + +- Auto syndrome plugin: A way of automatically applying boiling rock syndromes and calling dfhack commands controlled by raws. +- Infinite sky plugin: Create new z-levels automatically or on request. +- True transformation plugin: A better way of doing permanent transformations that allows later transformations. +- Work now plugin: Makes the game assign jobs every time you pause. + +New tweaks +---------- +- tweak military-training: speed up melee squad training up to 10x (normally 3-5x). + +New scripts +----------- +- binpatch: the same as the stand-alone binpatch.exe, but works at runtime. +- region-pops: displays animal populations of the region and allows tweaking them. +- lua: lua interpreter front-end converted to a script from a native command. +- dfusion: misc scripts with a text based menu. +- embark: lets you embark anywhere. +- lever: list and pull fort levers from the dfhack console. +- stripcaged: mark items inside cages for dumping, eg caged goblin weapons. +- soundsense-season: writes the correct season to gamelog.txt on world load. +- create-items: spawn items +- fix/cloth-stockpile: fixes bug 5739; needs to be run after savegame load every time. + +New GUI scripts +--------------- +- gui/guide-path: displays the cached path for minecart Guide orders. +- gui/workshop-job: displays inputs of a workshop job and allows tweaking them. +- gui/workflow: a front-end for the workflow plugin (part inspired by falconne). +- gui/assign-rack: works together with a binary patch to fix weapon racks. +- gui/gm-editor: an universal editor for lots of dfhack things. +- gui/companion-order: a adventure mode command interface for your companions. +- gui/advfort: a way to do jobs with your adventurer (e.g. build fort). + +New binary patches +------------------ +(for use with binpatch) + +- armorstand-capacity: doubles the capacity of armor stands. +- custom-reagent-size: lets custom reactions use small amounts of inputs. +- deconstruct-heapfall: stops some items still falling on head when deconstructing. +- deconstruct-teleport: stops items from 16x16 block teleporting when deconstructing. +- hospital-overstocking: stops hospital overstocking with supplies. +- training-ammo: lets dwarves with quiver full of combat-only ammo train. +- weaponrack-unassign: fixes bug that negates work done by gui/assign-rack. + +New Plugins +----------- +- fix-armory: Together with a couple of binary patches and the gui/assign-rack script, this plugin makes weapon racks, armor stands, chests and cabinets in properly designated barracks be used again for storage of squad equipment. +- search: Adds an incremental search function to the Stocks, Trading, Stockpile and Unit List screens. +- automaterial: Makes building constructions (walls, floors, fortifications, etc) a little bit easier by saving you from having to trawl through long lists of materials each time you place one. +- Dfusion: Reworked to make use of lua modules, now all the scripts can be used from other scripts. +- Eventful: A collection of lua events, that will allow new ways to interact with df world. + +DFHack v0.34.11-r2 +================== + +Internals +--------- +- full support for Mac OS X. +- a plugin that adds scripting in ruby. +- support for interposing virtual methods in DF from C++ plugins. +- support for creating new interface screens from C++ and lua. +- added various other API functions. + +Notable bugfixes +---------------- +- better terminal reset after exit on linux. +- seedwatch now works on reclaim. +- the sort plugin won't crash on cages anymore. + +Misc improvements +----------------- +- autodump: can move items to any walkable tile, not just floors. +- stripcaged: by default keep armor, new dumparmor option. +- zone: allow non-domesticated birds in nestboxes. +- workflow: quality range in constraints. +- cleanplants: new command to remove rain water from plants. +- liquids: can paint permaflow, i.e. what makes rivers power water wheels. +- prospect: pre-embark prospector accounts for caves & magma sea in its estimate. +- rename: supports renaming stockpiles, workshops, traps, siege engines. +- fastdwarf: now has an additional option to make dwarves teleport to their destination. +- Autolabor plugin: + + - can set nonidle hauler percentage. + - broker excluded from all labors when needed at depot. + - likewise, anybody with a scheduled diplomat meeting. + +New commands +------------ +- misery: multiplies every negative thought gained (2x by default). +- digtype: designates every tile of the same type of vein on the map for 'digging' (any dig designation). + +New tweaks +---------- +- tweak stable-cursor: keeps exact cursor position between d/k/t/q/v etc menus. +- tweak patrol-duty: makes Train orders reduce patrol timer, like the binary patch does. +- tweak readable-build-plate: fix unreadable truncation in unit pressure plate build ui. +- tweak stable-temp: fixes bug 6012; may improve FPS by 50-100% on a slow item-heavy fort. +- tweak fast-heat: speeds up item heating & cooling, thus making stable-temp act faster. +- tweak fix-dimensions: fixes subtracting small amounts from stacked liquids etc. +- tweak advmode-contained: fixes UI bug in custom reactions with container inputs in advmode. +- tweak fast-trade: Shift-Enter for selecting items quckly in Trade and Move to Depot screens. +- tweak military-stable-assign: Stop rightmost list of military->Positions from jumping to top. +- tweak military-color-assigned: In same list, color already assigned units in brown & green. + +New scripts +----------- +- fixnaked: removes thoughts about nakedness. +- setfps: set FPS cap at runtime, in case you want slow motion or speed-up. +- siren: wakes up units, stops breaks and parties - but causes bad thoughts. +- fix/population-cap: run after every migrant wave to prevent exceeding the cap. +- fix/stable-temp: counts items with temperature updates; does instant one-shot stable-temp. +- fix/loyaltycascade: fix units allegiance, eg after ordering a dwarf merchant kill. +- deathcause: shows the circumstances of death for a given body. +- digfort: designate areas to dig from a csv file. +- drainaquifer: remove aquifers from the map. +- growcrops: cheat to make farm crops instantly grow. +- magmasource: continuously spawn magma from any map tile. +- removebadthoughts: delete all negative thoughts from your dwarves. +- slayrace: instakill all units of a given race, optionally with magma. +- superdwarf: per-creature fastdwarf. +- gui/mechanisms: browse mechanism links of the current building. +- gui/room-list: browse other rooms owned by the unit when assigning one. +- gui/liquids: a GUI front-end for the liquids plugin. +- gui/rename: renaming stockpiles, workshops and units via an in-game dialog. +- gui/power-meter: front-end for the Power Meter plugin. +- gui/siege-engine: front-end for the Siege Engine plugin. +- gui/choose-weapons: auto-choose matching weapons in the military equip screen. + +New Plugins +----------- +- Dwarf Manipulator: Open the unit list, and press 'l' to access a Dwarf Therapist like UI in the game. +- Steam Engine: + Dwarven Water Reactors don't make any sense whatsoever and cause lag, so this may be + a replacement for those concerned by it. The plugin detects if a workshop with a + certain name is in the raws used by the current world, and provides the necessary + behavior. See ``hack/raw/*_steam_engine.txt`` for the necessary raw definitions. + Note: Stuff like animal treadmills might be more period, but absolutely can't be + done with tools dfhack has access to. +- Power Meter: + When activated, implements a pressure plate modification that detects power in gear + boxes built on the four adjacent N/S/W/E tiles. The gui/power-meter script implements + the necessary build configuration UI. +- Siege Engine: + When enabled and configured via gui/siege-engine, allows aiming siege engines + at a designated rectangular area with 360 degree fire range and across Z levels; + this works by rewriting the projectile trajectory immediately after it appears. + Also supports loading catapults with non-boulder projectiles, taking from a stockpile, + and restricting operator skill range like with ordinary workshops. + Disclaimer: not in any way to undermine the future siege update from Toady, but + the aiming logic of existing engines hasn't been updated since 2D, and is almost + useless above ground :(. Again, things like making siegers bring their own engines + is totally out of the scope of dfhack and can only be done by Toady. +- Add Spatter: + Detects reactions with certain names in the raws, and changes them from adding + improvements to adding item contaminants. This allows directly covering items + with poisons. The added spatters are immune both to water and 'clean items'. + Intended to give some use to all those giant cave spider poison barrels brought + by the caravans. + diff --git a/README.html b/README.html index 481058eb4a..325cd66f60 100644 --- a/README.html +++ b/README.html @@ -4,13 +4,13 @@ - + Page Redirection - If you are not redirected automatically, follow the link to the documentation. + Follow this link to the documentation. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000000..50769e0c50 --- /dev/null +++ b/README.md @@ -0,0 +1,24 @@ +#DFHack Readme + +[![Build Status](https://travis-ci.org/DFHack/dfhack.svg?branch=develop)] +(https://travis-ci.org/DFHack/dfhack) +[![Documentation Status](https://readthedocs.org/projects/dfhack/badge)] +(https://dfhack.readthedocs.org) +[![License](https://img.shields.io/badge/license-ZLib-blue.svg)] +(https://en.wikipedia.org/wiki/Zlib_License) +[![Github Issues](http://githubbadges.herokuapp.com/DFHack/dfhack/issues)] +(https://github.com/DFHack/dfhack/issues) +[![Open Pulls](http://githubbadges.herokuapp.com/DFHack/dfhack/pulls)] +(https://github.com/DFHack/dfhack/pulls) + +DFHack is a Dwarf Fortress memory access library, distributed with scripts +and plugins implementing a wide variety of useful functions and tools. + +The full documentation [is available online here](https://dfhack.readthedocs.org), +from the README.html page in the DFHack distribution, or as raw text in the `./docs` folder. +If you're an end-user, modder, or interested in contributing to DFHack - +go read those docs. + +If that's unclear or you need more help, try [the Bay12 forums thread] +(http://www.bay12forums.com/smf/index.php?topic=139553) or the #dfhack IRC +channel on freenode. diff --git a/docs/conf.py.in b/conf.py similarity index 60% rename from docs/conf.py.in rename to conf.py index 7b915ddd01..cb06d32dd7 100644 --- a/docs/conf.py.in +++ b/conf.py @@ -1,8 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# DFHack documentation build configuration file, created by -# sphinx-quickstart on Tue Sep 22 17:34:54 2015. +# DFHack documentation build configuration file # # This file is execfile()d with the current directory set to its # containing dir. @@ -14,68 +13,115 @@ # serve to show the default. import fnmatch -import io +from io import open import os import shlex import sys -from os import listdir -from os.path import isfile, join, isdir -#import sys - -currentDir = '@CMAKE_CURRENT_SOURCE_DIR@' - -def makeIncludeAll(directory, extension): - outputFile = join(directory,'include-all.rst') - #print(outputFile) - files = [ f for f in listdir(directory) if isfile(join(directory,f)) and f.endswith(extension) ] - files.sort() - out = open(outputFile, 'w') - for f in files: - #TODO: check if the file contains the BEGIN_DOCS string - #print(join(directory,f)) - fstream = io.open(join(directory,f), 'r', encoding='utf8') - data = fstream.read().replace('\n','') - fstream.close() - if 'BEGIN_DOCS' in data: - out.write('.. include:: ' + join(directory,f) + '\n :start-after: BEGIN_DOCS\n :end-before: END_DOCS\n\n') - out.close() - -def makeAllIncludeAll(directory, extension): - for root, subdirs, files in os.walk(directory): - if isdir(root): - makeIncludeAll(root, extension) - -makeAllIncludeAll(currentDir + '/scripts', '.lua') - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) + +# -- Autodoc for DFhack scripts ------------------------------------------- + +def doc_dir(dirname, files): + """Yield (command, includepath) for each script in the directory.""" + sdir = os.path.relpath(dirname, '.').replace('\\', '/').replace('../', '') + for f in files: + if f[-3:] not in ('lua', '.rb'): + continue + with open(os.path.join(dirname, f), 'r', encoding='utf8') as fstream: + text = [l.rstrip() for l in fstream.readlines() if l.strip()] + command = None + for line in text: + if command and line == len(line) * '=': + yield command, sdir + '/' + f + break + command = line + + +def document_scripts(): + """Autodoc for files with the magic script documentation marker strings. + + Creates a file for eack kind of script (base/devel/fix/gui/modtools) + with all the ".. include::" directives to pull out docs between the + magic strings. + """ + # First, we collect the commands and paths to include in our docs + scripts = [] + for root, _, files in os.walk('scripts'): + scripts.extend(doc_dir(root, files)) + # Next we split by type and create include directives sorted by command + kinds = {'base': [], 'devel': [], 'fix': [], 'gui': [], 'modtools': []} + for s in scripts: + k_fname = s[0].split('/', 1) + if len(k_fname) == 1: + kinds['base'].append(s) + else: + kinds.get(k_fname[0], []).append(s) + template = ('.. _{}:\n\n' + '.. include:: /{}\n' + ' :start-after: =begin\n' + ' :end-before: =end\n') + for key, value in kinds.items(): + kinds[key] = [template.format(x[0], x[1]) + for x in sorted(value, key=lambda x: x[0])] + # Finally, we write our _auto/* files for each kind of script + if not os.path.isdir('docs/_auto'): + os.mkdir('docs/_auto') + head = { + 'base': 'Basic Scripts', + 'devel': 'Development Scripts', + 'fix': 'Bugfixing Scripts', + 'gui': 'GUI Scripts', + 'modtools': 'Scripts for Modders'} + for k in head: + title = ('.. _{k}:\n\n{l}\n{t}\n{l}\n\n' + '.. include:: /scripts/{a}about.txt\n\n' + '.. contents::\n\n').format( + k=k, t=head[k], l=len(head[k])*'#', a=('' if k=='base' else k+'/')) + mode = 'w' if sys.version_info.major > 2 else 'wb' + with open('docs/_auto/{}.rst'.format(k), mode) as outfile: + outfile.write(title) + outfile.write('\n\n'.join(kinds[k])) + + +# Actually call the docs generator +document_scripts() + # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +needs_sphinx = '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [] +extensions = ['sphinx.ext.extlinks'] + +# This config value must be a dictionary of external sites, mapping unique +# short alias names to a base URL and a prefix. +# See http://sphinx-doc.org/ext/extlinks.html +extlinks = { + 'wiki': ('http://dwarffortresswiki.org/%s', ''), + 'forums': ('http://www.bay12forums.com/smf/index.php?topic=%s', + 'Bay12 forums thread '), + 'dffd': ('http://dffd.bay12games.com/file.php?id=%s', 'DFFD file '), + 'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s', + 'Bug '), + 'issue': ('https://github.com/DFHack/dfhack/issues/%s', 'Issue '), +} # Add any paths that contain templates here, relative to this directory. templates_path = [] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ['.rst'] # The encoding of source files. #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'README' +master_doc = 'index' # General information about the project. project = 'DFHack' @@ -86,25 +132,26 @@ def makeAllIncludeAll(directory, extension): # |version| and |release|, also used in various other places throughout the # built documents. -#def get_version(): -# """Return the DFHack version string, from CMakeLists.txt""" -# version, release = '', '' -# with open('CMakeLists.txt') as f: -# for s in f.readlines(): -# if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'): -# version = s.upper().replace('SET(DF_VERSION "', '') -# elif fnmatch.fnmatch(s.upper(), 'SET(DFHACK_RELEASE "r*")\n'): -# release = s.upper().replace('SET(DFHACK_RELEASE "', '').lower() -# return (version + '-' + release).replace('")\n', '') +def get_version(): + """Return the DFHack version string, from CMakeLists.txt""" + version = release = '' + try: + with open('CMakeLists.txt') as f: + for s in f.readlines(): + if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'): + version = s.upper().replace('SET(DF_VERSION "', '') + elif fnmatch.fnmatch(s.upper(), 'SET(DFHACK_RELEASE "r*")\n'): + release = s.upper().replace('SET(DFHACK_RELEASE "', '').lower() + return (version + '-' + release).replace('")\n', '') + except IOError: + return 'unknown' # The short X.Y version. -version = '@DFHACK_VERSION@' # The full version, including alpha/beta/rc tags. -release = '@DFHACK_VERSION@' +version = release = get_version() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -# # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = None @@ -117,32 +164,21 @@ def makeAllIncludeAll(directory, extension): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['docs/_build/*', 'depends/*'] +exclude_patterns = [ + 'README.md', + 'docs/html*', + 'depends/*', + 'scripts/3rdparty/*', + 'build*', + ] # The reST default role (used for this markup: `text`) to use for all # documents. -default_role = 'any' - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False +default_role = 'ref' # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -151,12 +187,19 @@ def makeAllIncludeAll(directory, extension): # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = '@SPHINX_THEME@' +html_theme = 'alabaster' +html_style = 'dfhack.css' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +html_theme_options = { + #'logo': 'logo.png', + 'github_user': 'DFHack', + 'github_repo': 'dfhack', + 'github_button': False, + 'travis_button': False, +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] @@ -166,7 +209,7 @@ def makeAllIncludeAll(directory, extension): #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +html_short_title = 'DFHack Docs' # The name of an image file (relative to this directory) to place at the top # of the sidebar. @@ -175,12 +218,12 @@ def makeAllIncludeAll(directory, extension): # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -html_favicon = 'dfhack-icon.ico' +html_favicon = 'docs/styles/dfhack-icon.ico' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['../images'] +html_static_path = ['docs/styles'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -189,24 +232,31 @@ def makeAllIncludeAll(directory, extension): # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +html_last_updated_fmt = '%Y-%m-%d' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = { + '**': [ + 'about.html', + 'relations.html', + 'searchbox.html', + 'localtoc.html', + ] +} # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +html_domain_indices = False # If false, no index is generated. -#html_use_index = True +html_use_index = False # If true, the index is split into individual pages for each letter. #html_split_index = False @@ -225,23 +275,6 @@ def makeAllIncludeAll(directory, extension): # base URL from which the finished HTML is served. #html_use_opensearch = '' -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - # Output file base name for HTML help builder. htmlhelp_basename = 'DFHackdoc' diff --git a/depends/protobuf/CMakeLists.txt b/depends/protobuf/CMakeLists.txt index ffad350edc..9ec13e6ca8 100644 --- a/depends/protobuf/CMakeLists.txt +++ b/depends/protobuf/CMakeLists.txt @@ -202,6 +202,7 @@ LIST(APPEND LIBPROTOBUF_FULL_SRCS ${LIBPROTOBUF_LITE_SRCS}) IF(CMAKE_COMPILER_IS_GNUCC) SET(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -Wno-sign-compare") + SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-unused-result") ENDIF() INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR}) diff --git a/docs/Authors.rst b/docs/Authors.rst index 5661e6132c..05997b3d66 100644 --- a/docs/Authors.rst +++ b/docs/Authors.rst @@ -21,15 +21,18 @@ Caldfir caldfir Chris Dombroski cdombroski Clayton Hughes David Corbett dscorbett +Deon DoctorVanGogh DoctorVanGogh Donald Ruegsegger hashaash doomchild doomchild +enjia2000 Eric Wald eswald Erik Youngren Artanis Espen Wiborg expwnent expwnent Feng Harlan Playford playfordh +IndigoFenix James Logsdon jlogsdon Japa JapaMala Jared Adams @@ -40,11 +43,14 @@ Jonas Ask kane-t kane-t Kelly Martin ab9rf Kris Parker kaypy +Kurik Amudnil Lethosor lethosor Mason11987 Mason11987 Matthew Cline Max maxthyme Max^TM melkor217 melkor217 +Meneth32 +Meph Michon van Dooren MaienM miffedmap miffedmap Mike Stewart thewonderidiot @@ -53,6 +59,7 @@ MithrilTuxedo MithrilTuxedo mizipzor mizipzor Neil Little nmlittle Nick Rart nickrart comestible +Omniclasm PeridexisErrant PeridexisErrant Petr Mrázek peterix potato @@ -64,6 +71,7 @@ rampaging-poet Raoul van Putten Raoul XQ raoulxq reverb +Raidau Raidau Rinin Rinin Robert Heinrich rh73 rofl0r rofl0r @@ -78,6 +86,7 @@ scamtank scamtank Seth Woodworth sethwoodworth simon Simon Jackson sizeak +Tacomagic Tim Walberg twalberg Timothy Collett danaris Tom Prince diff --git a/docs/Binpatches.rst b/docs/Binpatches.rst index 4ecdfa79b1..e1ae1c0eff 100644 --- a/docs/Binpatches.rst +++ b/docs/Binpatches.rst @@ -7,7 +7,7 @@ Patching the DF binary Writing scripts and plugins for DFHack is not the only way to modify Dwarf Fortress. Before DFHack, it was common for tools to manually patch the binary to change behaviour, and DFHack still contains tools to do this via -the `scripts/binpatch` command. +the `binpatch` command. .. warning:: @@ -32,8 +32,7 @@ decent skill in `memory research `. * See `this commit `_, when the 0.34.11 patches were discarded, for example patches. -* `Issue #546 `_ is about the - future of the binpatches, and may be useful reading. +* :issue:`546` is about the future of the binpatches, and may be useful reading. If you want to write a patch, the armory patches discussed here and documented below would probably be the best place to start. @@ -45,7 +44,7 @@ There are two methods to apply a patch. Patching at runtime ------------------- -The `scripts/binpatch` script checks, applies or removes binary patches +The `binpatch` script checks, applies or removes binary patches directly in memory at runtime:: binpatch [check|apply|remove] @@ -56,7 +55,7 @@ the version appropriate for the currently loaded executable. This is the preferred method; it's easier to debug, does not cause persistent problems, and leaves file checksums alone. As with many other commands, users -can simply add it to ``dfhack.init`` to reapply the patch every time DF is run. +can simply add it to `dfhack.init` to reapply the patch every time DF is run. Patching on disk @@ -107,7 +106,7 @@ armor stands, and in containers. .. note:: In order to actually be used, weapon racks have to be patched and - manually assigned to a squad. See `scripts/gui/assign-rack`. + manually assigned to a squad. See `gui/assign-rack`. Note that the buildings in the armory are used as follows: @@ -152,8 +151,8 @@ these rules is intended by Toady; the rest are invented by this plugin. gui/assign-rack --------------- -Bind to a key (the example config uses P), and activate when viewing a weapon -rack in the ``q`` mode. +Bind to a key (the example config uses :kbd:`P`), and activate when viewing a weapon +rack in the :kbd:`q` mode. .. image:: images/assign-rack.png @@ -166,12 +165,10 @@ work again. The existing issues are: * Even if assigned by the script, **the game will unassign the racks again without a binary patch**. This patch is called ``weaponrack-unassign``, - and has not been updated since 0.34.11. See `the bug report`_ for more info. - -.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 + and has not been updated since 0.34.11. See :bug:`1445` for more info. * Haulers still take equipment stored in the armory away to the stockpiles, - unless `plugins/fix-armory` is used. + unless `fix-armory` is used. The script interface simply lets you designate one of the squads that are assigned to the barracks/armory containing the selected stand as diff --git a/docs/Changelog.rst b/docs/Changelog.rst deleted file mode 100644 index 9c2b4a3293..0000000000 --- a/docs/Changelog.rst +++ /dev/null @@ -1,7 +0,0 @@ -######### -Changelog -######### - -.. contents:: - -.. include:: ../NEWS diff --git a/docs/Compile.rst b/docs/Compile.rst index a55c2d44db..f4655d8bf4 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -2,28 +2,20 @@ Compiling DFHack ################ -.. important:: - You don't need to compile DFHack unless you're developing plugins or working on the core. - For users, modders, and authors of scripts it's better to download the latest release instead. +You don't need to compile DFHack unless you're developing plugins or working on the core. + +For users, modders, and authors of scripts it's better to download +and `install the latest release instead `. .. contents:: - :depth: 2 + :depth: 2 + -=================== How to get the code =================== DFHack doesn't have any kind of system of code snapshots in place, so you will have to -get code from the github repository using git. -The code resides at https://github.com/DFHack/dfhack - -On Linux and OS X, having a ``git`` package installed is the minimal requirement (see below for OS X instructions), -but some sort of git gui or git integration for your favorite text editor/IDE will certainly help. - -On Windows, you will need some sort of Windows port of git, or a GUI. Some examples: - - * http://msysgit.github.io - this is a command line version of git for windows. - Most tutorials on git usage will apply. - * http://code.google.com/p/tortoisegit - this puts a pretty, graphical face on top of msysgit +get code from the github repository using git. How to get git is described under +the instructions for each platform. To get the code:: @@ -33,22 +25,14 @@ To get the code:: If your version of git does not support the ``--recursive`` flag, you will need to omit it and run ``git submodule update --init`` after entering the dfhack directory. -If you just want to compile DFHack or work on it by contributing patches, it's quite -enough to clone from the read-only address instead:: - - git clone --recursive git://github.com/DFHack/dfhack.git - cd dfhack - -If you want to get really involved with the development, create an account on +If you want to get involved with the development, create an account on Github, make a clone there and then use that as your remote repository instead. -Detailed instructions are beyond the scope of this document. If you need help, -join us on IRC (#dfhack channel on freenode). +We'd love that; join us on IRC (#dfhack channel on freenode) if you need help. + -=========== Build types =========== -``cmake`` allows you to pick a build type by changing this -variable: ``CMAKE_BUILD_TYPE`` :: +``cmake`` allows you to pick a build type by changing the ``CMAKE_BUILD_TYPE`` variable:: cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE @@ -58,34 +42,42 @@ Without specifying a build type or 'None', cmake uses the Valid and useful build types include 'Release', 'Debug' and 'RelWithDebInfo'. 'Debug' is not available on Windows. -===== + Linux ===== On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD. Dependencies -============ +------------ DFHack is meant to be installed into an existing DF folder, so get one ready. -For building, you need a 32-bit version of GCC. For example, to build DFHack on -a 64-bit distribution like Arch, you'll need the multilib development tools and libraries. -Alternatively, you might be able to use ``lxc`` to -`create a virtual 32-bit environment `_. +We assume that any Linux platform will have ``git`` available. + +To build DFHack you need a 32-bit version of GCC. GCC 4.5 is easiest to work +with due to avoiding libstdc++ issues (see below), but any later 4.x version +should work as well. GCC 5.x may work but is discouraged for releases because it +won't work on systems without GCC 5.x installed. On 64-bit distributions, you'll +need the multilib development tools and libraries (``gcc-multilib`` or +``gcc-4.x-multilib`` on Debian). Alternatively, you might be able to use ``lxc`` +to +:forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`. Before you can build anything, you'll also need ``cmake``. It is advisable to also get ``ccmake`` on distributions that split the cmake package into multiple parts. You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation parts). -You should be able to find them in your distro repositories (on Arch linux -``perl-xml-libxml`` and ``perl-xml-libxslt``) or through ``cpan``. +You should be able to find them in your distro repositories. + +* On Arch linux, ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``) +* On 64-bit Ubuntu, ``apt-get install zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``. +* On 32-bit Ubuntu, ``apt-get install zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``. +* Debian-derived distros should have similar requirements. To build Stonesense, you'll also need OpenGL headers. -Some additional dependencies for other distros are listed on the -`wiki `_. Build -===== +----- Building is fairly straightforward. Enter the ``build`` folder (or create an empty folder in the DFHack directory to use instead) and start the build like this:: @@ -103,15 +95,13 @@ Alternatively, you can use ccmake instead of cmake:: make install This will show a curses-based interface that lets you set all of the -extra options. +extra options. You can also use a cmake-friendly IDE like KDevelop 4 +or the cmake-gui program. -You can also use a cmake-friendly IDE like KDevelop 4 or the cmake-gui -program. -Fixing the libstdc++ version bug -================================ - -When compiling dfhack yourself, it builds against your system libc. +Incompatible libstdc++ +~~~~~~~~~~~~~~~~~~~~~~ +When compiling dfhack yourself, it builds against your system libstdc++. When Dwarf Fortress runs, it uses a libstdc++ shipped with the binary, which comes from GCC 4.5 and is incompatible with code compiled with newer GCC versions. This manifests itself with the error message:: @@ -119,74 +109,80 @@ This manifests itself with the error message:: ./libs/Dwarf_Fortress: /pathToDF/libs/libstdc++.so.6: version `GLIBCXX_3.4.15' not found (required by ./hack/libdfhack.so) -To fix this, simply remove the libstdc++ shipped with DF, it will fall back -to your system lib and everything will work fine:: +To fix this, you can compile with GCC 4.5 or remove the libstdc++ shipped with +DF, which causes DF to use your system libstdc++ instead:: cd /path/to/DF/ rm libs/libstdc++.so.6 -Alternatively, this issue can be avoided by compiling DFHack with GCC 4.5. +Note that distributing binaries compiled with newer GCC versions requires end- +users to delete libstdc++ themselves and have a libstdc++ on their system from +the same GCC version or newer. For this reason, distributing anything compiled +with GCC versions newer than 4.8 is discouraged. -======== Mac OS X ======== - DFHack functions similarly on OS X and Linux, and the majority of the information above regarding the build process (cmake and make) applies here as well. -* If you are building on 10.6, please read the subsection below titled "Snow Leopard Changes" FIRST. -* If you are building on 10.10+, read the "Yosemite Changes" subsection before building. +If you have issues building on OS X 10.10 (Yosemite) or above, try definining the +following environment variable:: -1. Download and unpack a copy of the latest DF -2. Install Xcode from Mac App Store -3. Open Xcode, go to Preferences > Downloads, and install the Command Line Tools. -4. Install dependencies + export MACOSX_DEPLOYMENT_TARGET=10.9 - Option 1: Using Homebrew: +#. Download and unpack a copy of the latest DF +#. Install Xcode from Mac App Store +#. Open Xcode, go to Preferences > Downloads, and install the Command Line Tools. +#. Install dependencies - * `Install Homebrew `_ and run: - * ``brew tap homebrew/versions`` - * ``brew install git`` - * ``brew install cmake`` - * ``brew install gcc45`` + Using `Homebrew `_:: - Option 2: Using MacPorts: + brew tap homebrew/versions + brew install git + brew install cmake + brew install gcc45 - * `Install MacPorts `_ - * Run ``sudo port install gcc45 +universal cmake +universal git-core +universal`` - This will take some time—maybe hours, depending on your machine. + Using `MacPorts `_:: - At some point during this process, it may ask you to install a Java environment; let it do so. + sudo port install gcc45 +universal cmake +universal git-core +universal -5. Install perl dependencies + Macports will take some time - maybe hours. At some point it may ask + you to install a Java environment; let it do so. + +#. Install perl dependencies 1. ``sudo cpan`` If this is the first time you've run cpan, you will need to go through the setup process. Just stick with the defaults for everything and you'll be fine. + If you are running OS X 10.6 (Snow Leopard) or earlier, good luck! + You'll need to open a separate Terminal window and run:: + + sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml + 2. ``install XML::LibXML`` 3. ``install XML::LibXSLT`` -6. Get the dfhack source:: +#. Get the dfhack source:: git clone --recursive https://github.com/DFHack/dfhack.git cd dfhack -7. Set environment variables: +#. Set environment variables: - Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``):: + Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``):: export CC=/usr/local/bin/gcc-4.5 export CXX=/usr/local/bin/g++-4.5 - Macports:: + Macports:: export CC=/opt/local/bin/gcc-mp-4.5 export CXX=/opt/local/bin/g++-mp-4.5 -8. Build dfhack:: +#. Build dfhack:: mkdir build-osx cd build-osx @@ -195,70 +191,58 @@ as well. make install -Snow Leopard Changes -==================== - -1. Add a step 6.2a (before Install XML::LibXSLT):: - In a separate Terminal window or tab, run: - ``sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml`` - -2. Add a step 7a (before building):: - In /library/LuaTypes.cpp, change line 467 to - ``int len = strlen((char*)ptr);`` - -Yosemite Changes -================ - -If you have issues building on OS X Yosemite (or above), try definining the -following environment variable:: - - export MACOSX_DEPLOYMENT_TARGET=10.9 - -======= Windows ======= On Windows, DFHack replaces the SDL library distributed with DF. Dependencies -============ -First, you need ``cmake``. Get the win32 installer version from the official -site: http://www.cmake.org/cmake/resources/software.html +------------ +You will need some sort of Windows port of git, or a GUI. Some examples: + +* `Git for Windows `_ (command-line and GUI) +* `tortoisegit `_ (GUI and File Explorer integration) +You need ``cmake``. Get the win32 installer version from +`the official site `_. It has the usual installer wizard. Make sure you let it add its binary folder to your binary search PATH so the tool can be later run from anywhere. You'll need a copy of Microsoft Visual C++ 2010. The Express version is sufficient. -Grab it from Microsoft's site. - +Grab it from `Microsoft's site `_. You'll also need the Visual Studio 2010 SP1 update. For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT. -`Strawberry Perl `_ works nicely for this. +`Strawberry Perl `_ works nicely for this and includes +all of the required packages. If you already have a different version of perl (for example the one from cygwin), you can run into some trouble. Either remove the other perl install from PATH, or -install libxml and libxslt for it instead. Strawberry perl works though and has -all the required packages. +install libxml and libxslt for it instead. Build -===== -There are several different batch files in the ``build`` folder along with a script that's used for picking the DF path. +----- +There are several different batch files in the ``build`` folder along +with a script that's used for picking the DF path. -First, run set_df_path.vbs and point the dialog that pops up at your DF folder that you want to use for development. +First, run ``set_df_path.vbs`` and point the dialog that pops up at your +DF folder that you want to use for development. Next, run one of the scripts with ``generate`` prefix. These create the MSVC solution file(s): * ``all`` will create a solution with everything enabled (and the kitchen sink). -* ``gui`` will pop up the cmake gui and let you pick and choose what to build. This is probably what you want most of the time. Set the options you are interested in, then hit configure, then generate. More options can appear after the configure step. -* ``minimal`` will create a minimal solution with just the bare necessities - the main library and standard plugins. +* ``gui`` will pop up the cmake gui and let you pick and choose what to build. + This is probably what you want most of the time. Set the options you are interested + in, then hit configure, then generate. More options can appear after the configure step. +* ``minimal`` will create a minimal solution with just the bare necessities - + the main library and standard plugins. Then you can either open the solution with MSVC or use one of the msbuild scripts: -* Scripts with ``build`` prefix will only build. +* Scripts with ``build`` prefix will only build DFHack. * Scripts with ``install`` prefix will build DFHack and install it to the previously selected DF path. * Scripts with ``package`` prefix will build and create a .zip package of DFHack. When you open the solution in MSVC, make sure you never use the Debug builds. Those aren't binary-compatible with DF. If you try to use a debug build with DF, you'll only get crashes. -So pick either Release or RelWithDebInfo build and build the INSTALL target. +For this reason the Windows "debug" scripts actually do RelWithDebInfo builds, +so pick either Release or RelWithDebInfo build and build the INSTALL target. -The ``debug`` scripts actually do RelWithDebInfo builds. diff --git a/docs/Contributing.rst b/docs/Contributing.rst index a2c12c0877..cd2495922b 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -11,7 +11,6 @@ Several things should be kept in mind when contributing code to DFHack. Code Format ----------- - * Four space indents for C++. Never use tabs for indentation in any language. * LF (Unix style) line terminators * Avoid trailing whitespace @@ -25,14 +24,18 @@ Code Format How to get new code into DFHack ------------------------------- - -* Submit pull requests to the ``develop`` branch, not the master branch. The master branch always points at the most recent release. -* Use new branches for each feature/fix so that your changes can be merged independently (i.e. not the master or develop branch of your fork). +* Submit pull requests to the ``develop`` branch, not the ``master`` branch. + (The ``master`` branch always points at the most recent release) +* Use a new branch for each feature or bugfix so that your changes can be merged independently + (i.e. not the master or develop branch of your fork). * If possible, compile on multiple platforms when changing anything that compiles -* Update ``NEWS`` and ``docs/Authors.rst`` when applicable +* It must pass CI - run ``python travis/all.py`` to check this. +* Update ``NEWS.rst`` and ``docs/Authors.rst`` when applicable. * Create a GitHub pull request once finished -* Work done against GitHub issues tagged "bug" get priority -* Submit ideas and bug reports as issues on GitHub. Posts in the forum thread can easily get missed or forgotten. +* Submit ideas and bug reports as :issue:`issues on GitHub <>`. + Posts in the forum thread can easily get missed or forgotten. +* Work on :issue:`reported problems ` + will take priority over ideas or suggestions. .. _contributing-memory-research: @@ -62,7 +65,8 @@ All the plugins can be found in the 'plugins' folder. There's no in-depth docume on how to write one yet, but it should be easy enough to copy one and just follow the pattern. ``plugins/skeleton/skeleton.cpp`` is provided for this purpose. -Other than through plugins, it is possible to use DFHack via remote access interface, or by writing Lua scripts. +Other than through plugins, it is possible to use DFHack via remote access interface, +or by writing scripts in Lua or Ruby. There are plenty of examples in the scripts folder. The most important parts of DFHack are the Core, Console, Modules and Plugins. @@ -83,7 +87,7 @@ documentation is built with Sphinx, which runs automatically at compile time. DFHack consists of variously licensed code, but invariably weak copyleft. The main license is zlib/libpng, some bits are MIT licensed, and some are -BSD licensed. See the ``LICENSE`` document for more information. +BSD licensed. See the `license` for more information. Feel free to add your own extensions and plugins. Contributing back to the DFHack repository is welcome and the right thing to do :) @@ -118,14 +122,39 @@ comprehensive interface for visualisers such as Armok Vision. Documentation Standards ======================= +DFHack documentation is built with Sphinx, and configured automatically +through CMake. If you want to build the docs *only*, use this command:: + + sphinx-build . docs/html + Whether you're adding new code or just fixing old documentation (and there's plenty), there are a few important standards for completeness and consistent style. Treat this section as a guide rather than iron law, match the surrounding text, and you'll be fine. -Every script, plugin, or command should be documented. This is an active project, -and the best place to put this documentation might change. For now, it's usually -either ``docs/Scripts.rst`` or ``docs/Plugins.rst``. +Everything should be documented! For plugins, it's a work in progress - use +``docs/Plugins.rst`` for now. Core functions and general explanations should +go in the documents for that component; if it's not clear add a new section +as some may be missing. + +Scripts can use a custom autodoc function, based on the Sphinx ``include`` +directive and Ruby docstring conventions - any lines between ``=begin`` and +``=end`` are copied into the appropriate scripts documentation page. +They **must** have a heading which exactly matches the command, underlined +with ``=====`` to the same length. For example, a lua file would have:: + + --[[=begin + + add-thought + =========== + Adds a thought or emotion to the selected unit. Can be used by other scripts, + or the gui invoked by running ``add-thought gui`` with a unit selected. + + =end]] + +Ruby scripts use the same syntax, but obviously omit the leading ``--[[`` and +trailing ``]]`` which denote a multiline comment in lua. +``=begin`` and ``=end`` are native syntax (and matched in lua for convenience). Where the heading for a section is also the name of a command, the spelling and case should exactly match the command to enter in the DFHack command line. @@ -136,13 +165,13 @@ Sphinx (our documentation system) will make sure paragraphs flow. If there aren't many options or examples to show, they can go in a paragraph of text. Use double-backticks to put commands in monospaced font, like this:: - You can use ``cleanall scattered x`` to dump tattered or abandoned items. + You can use ``cleanowned scattered x`` to dump tattered or abandoned items. If the command takes more than three arguments, format the list as a table -called Options. The table *only* lists arguments, not full commands. +called Usage. The table *only* lists arguments, not full commands. Input values are specified in angle brackets. Example:: - Options: + Usage: :arg1: A simple argument. :arg2 : Does something based on the input value. @@ -158,17 +187,19 @@ describe the effect:: If it would be helpful to mention another DFHack command, don't just type the name - add a hyperlink! Specify the link target in backticks, and it will be -replaced with the corresponding title and linked: eg ```plugins/autolabor``` -=> `plugins/autolabor`. Link targets should be the path to the file +replaced with the corresponding title and linked: eg ```autolabor``` +=> `autolabor`. Link targets should be equivalent to the command described (without file extension), and placed above the heading of that section like this:: - .. _plugins/autolabor: + .. _autolabor: autolabor ========= Add link targets if you need them, but otherwise plain headings are preferred. +Scripts using the in-source docs option, which should be all of them, have +link targets created automatically. Other ways to help ================== diff --git a/docs/Core.rst b/docs/Core.rst index 4e20803117..51d0ec9556 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -1,216 +1,106 @@ +.. _dfhack-core: + ########### DFHack Core ########### -.. contents:: - - -============== -Getting DFHack -============== -The project is currently hosted at http://www.github.com/ - -Recent releases are available in source and binary formats `on the releases -page`_, while the binaries for releases 0.40.15-r1 to 0.34.11-r4 are on DFFD_. -Even older versions are available here_. - -.. _`on the releases page`: http://github.com/DFHack/dfhack/releases -.. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15 -.. _here: http://dethware.org/dfhack/download - -All new releases are announced in `the bay12 forums thread`_, which is also a -good place for discussion and questions. - -.. _`the Bay12 DFHack thread`: -.. _`the bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=139553 +DFHack commands can be implemented in three ways, all of which +are used in the same way: -If this sounds too complicated, you might prefer to `get a Starter Pack`_. -These are packages for new players or those who don't want to set up everything -themselves, and are available - with DFHack configured - for all OSes. +:builtin: commands are implemented by the core of DFHack. They manage + other DFhack tools, interpret commands, and control basic + aspects of DF (force pause or quit). -.. _`get a Starter Pack`: http://dwarffortresswiki.org/index.php/Utility:Lazy_Newb_Pack +:plugins: are stored in ``hack/plugins/`` and must be compiled with the + same version of DFHack. They are less flexible than scripts, + but used for complex or ongoing tasks becasue they run faster. -Compatibility -============= -DFHack is available for Windows (XP or later), Linux (any modern distribution), -or OS X (10.6.8 to 10.9). +:scripts: are Ruby or Lua scripts stored in ``hack/scripts/``. + Because they don't need to be compiled, scripts are + more flexible about versions, and easier to distribute. + Most third-party DFHack addons are scripts. -Most releases only support the version of DF mentioned in their title - for -example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases -support earlier DF versions as well. Wherever possible, use the latest version -built for the target version of DF. -On Windows, DFHack is compatible with the SDL version of DF, but not the legacy version. - -It is also possible to use the Windows DFHack with Wine under Linux and OS X. - -Installation/Removal -==================== -Installing DFhack involves copying files into your DF folder. -Copy the files from a release archive so that: - -* On Windows, ``SDL.dll`` is replaced -* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script - -Uninstalling is basically the same, in reverse: - -* On Windows, first delete ``SDL.dll`` and rename ``SDLreal.dll`` to ``SDL.dll``, - then remove the other DFHack files -* On Linux, remove the DFHack files. - -The stonesense plugin might require some additional libraries on Linux. +.. contents:: -If any of the plugins or dfhack itself refuses to load, check the ``stderr.log`` -file created in your DF folder. +Built-in Commands +================= +The following commands are provided by the 'core' components +of DFhack, rather than plugins or scripts. -=============== -Getting started -=============== -If DFHack is installed correctly, it will automatically pop up a console -window once DF is started as usual on windows. Linux and Mac OS X require -running the dfhack script from the terminal, and will use that terminal for -the console. -**NOTE**: The ``dfhack-run`` executable is there for calling DFHack commands in -an already running DF+DFHack instance from external OS scripts and programs, -and is *not* the way how you use DFHack normally. +.. _cls: -DFHack has a lot of features, which can be accessed by typing commands in the -console, or by mapping them to keyboard shortcuts. Most of the newer and more -user-friendly tools are designed to be at least partially used via the latter -way. +cls +--- +Clear the terminal. Does not delete command history. -In order to set keybindings, you have to create a text configuration file -called ``dfhack.init``; the installation comes with an example version called -``dfhack.init-example``, which is fully functional, covers all of the recent -features and can be simply renamed to ``dfhack.init``. You are encouraged to look -through it to learn which features it makes available under which key combinations. -Using DFHack -============ -DFHack basically extends what DF can do with something similar to the drop-down -console found in Quake engine games. On Windows, this is a separate command line -window. On Linux, the terminal used to launch the dfhack script is taken over -(so, make sure you start from a terminal). Basic interaction with dfhack -involves entering commands into the console. For some basic instructions, -use the ``help`` command. To list all possible commands, use the ``ls`` command. -Many commands have their own help or detailed description. You can use -``command help`` or ``command ?`` to show that. +.. _die: -The command line has some nice line editing capabilities, including history -that's preserved between different runs of DF (use up/down keys to go through -the history). +die +--- +Instantly kills DF without saving. -The second way to interact with DFHack is to bind the available commands -to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally -opened with the ``h`` key). Binding the commands is done by assigning a command as -a hotkey name (with ``n``). - -A new and more flexible way is the keybinding command in the dfhack console. -However, bindings created this way are not automatically remembered between runs -of the game, so it becomes necessary to use the dfhack.init file to ensure that -they are re-created every time it is loaded. - -Interactive commands like `plugins/liquids` cannot be used as hotkeys. -Many commands come from plugins, which are stored in ``hack/plugins/`` -and must be compiled with the same version of DFHack. Others come -from scripts, which are stored in ``hack/scripts``. Scripts are much -more flexible about versions, and easier to distribute - so most third-party -DFHack addons are scripts. - -Something doesn't work, help! -============================= -First, don't panic :) - -Second, dfhack keeps a few log files in DF's folder (``stderr.log`` and -``stdout.log``). Looking at these might help you solve the problem. -If it doesn't, you can ask for help in the forum thread or on IRC. - -If you found a bug, you can report it in `the Bay12 DFHack thread`_, -`the issues tracker on github `_, -or visit `the #dfhack IRC channel on freenode -`_. - -============= -Core Commands -============= -DFHack command syntax consists of a command name, followed by arguments separated -by whitespace. To include whitespace in an argument, quote it in double quotes. -To include a double quote character, use ``\"`` inside double quotes. - -If the first non-whitespace character of a line is ``#``, the line is treated -as a comment, i.e. a silent no-op command. - -When reading commands from dfhack.init or with the ``script`` command, if the final -character on a line is a backslash then the next uncommented line is considered a -continuation of that line, with the backslash deleted. Commented lines are skipped, -so it is possible to comment out parts of a command with the ``#`` character. +.. _disable: -If the first non-whitespace character is ``:``, the command is parsed in a special -alternative mode: first, non-whitespace characters immediately following the ``:`` -are used as the command name; the remaining part of the line, starting with the first -non-whitespace character *after* the command name, is used verbatim as the first argument. -The following two command lines are exactly equivalent:: +.. _enable: - :foo a b "c d" e f - foo "a b \"c d\" e f" +enable +------ +Many plugins can be in a distinct enabled or disabled state. Some of +them activate and deactivate automatically depending on the contents +of the world raws. Others store their state in world data. However a +number of them have to be enabled globally, and the init file is the +right place to do it. -This is intended for commands like ``rb_eval`` that evaluate script language statements. +Most such plugins or scripts support the built-in ``enable`` and ``disable`` +commands. Calling them at any time without arguments prints a list +of enabled and disabled plugins, and shows whether that can be changed +through the same commands. -Almost all the commands support using the ``help `` built-in command -to retrieve further help without having to look at this document. Alternatively, -some accept a ``help`` or ``?`` as an option on their command line. +To enable or disable plugins that support this, use their names as +arguments for the command:: -.. note:: + enable manipulator search - Some tools work by displaying dialogs or overlays in the game window. - In order to avoid confusion, these tools display the word "DFHack" while active. If they - merely add keybinding hints to existing screens, they use red instead of green for the key. +.. _fpause: +fpause +------ +Forces DF to pause. This is useful when your FPS drops below 1 and you lose +control of the game. -Init files -========== -DFHack allows users to automatically run commonly-used DFHack commands when DF is first -loaded, when a game is loaded, and when a game is unloaded. -Init scripts function the same way they would if the user manually typed in their contents, -but are much more convenient. If your DF folder contains at least one file with a name -following the format ``dfhack*.init`` where ``*`` is a placeholder for any string (including -the empty string), then all such files are executed in alphabetical order as init scripts when -DF is first loaded. +.. _help: -If your DF folder does not contain any such files, then DFHack will execute ``dfhack.init-example`` -as an example of useful commands to be run automatically. If you want DFHack to do nothing on -its own, then create an empty ``dfhack.init`` file in the main DF directory, or delete ``dfhack.init-example``. +help +---- +Most commands support using the ``help `` built-in command +to retrieve further help without having to look at this document. +``? `` and ``man `` are aliases. -The file ``dfhack.init-example`` is included as an example for users to follow if they need DFHack -command executed automatically. We recommend modifying or deleting ``dfhack.init-example`` as -its settings will not be optimal for all players. +Some commands (including many scripts) instead take ``help`` or ``?`` +as an option on their command line - ie `` help``. -In order to facilitate savegave portability, mod merging, and general organization of init files, -DFHack supports multiple init files both in the main DF directory and save-specific init files in -the save folders. -DFHack looks for init files in three places. +.. _hide: -It will look for them in the main DF directory, and in ``data/save/_____/raw`` and -``data/save/_____/raw/objects`` where ``_____`` is the name of the current savegame. +hide +---- +Hides the DFHack terminal window. Only available on Windows. -When a game is loaded, DFHack looks for files of the form ``onLoad*.init``, where -``*`` can be any string, including the empty string. -When a game is unloaded, DFHack looks for files of the form ``onUnload*.init``. Again, -these files may be in any of the above three places. All matching init files will be -executed in alphebetical order. +.. _keybinding: -Setting keybindings -=================== +keybinding +---------- To set keybindings, use the built-in ``keybinding`` command. Like any other -command it can be used at any time from the console, but it is most useful -in the DFHack init file. +command it can be used at any time from the console, but bindings are not +remembered between runs of the game unless re-created in `dfhack.init`. Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, or F1-F12 are supported. @@ -239,68 +129,233 @@ as a hotkey are always considered applicable. The ``context`` part in the key specifier above can be used to explicitly restrict the UI state where the binding would be applicable. If called without parameters, the ``keybinding`` command among other things prints the current context string. + Only bindings with a ``context`` tag that either matches the current context fully, or is a prefix ending at a ``/`` boundary would be considered for execution, i.e. -for context ``foo/bar/baz``, possible matches are any of ``@foo/bar/baz``, ``@foo/bar``, -``@foo`` or none. Multiple contexts can be specified by separating them with a -pipe (``|``) - for example, ``@foo|bar|baz/foo``. +when in context ``foo/bar/baz``, keybindings restricted to any of ``@foo/bar/baz``, +``@foo/bar``, ``@foo`` or none will be active. -Hotkeys -======= -Opens an in-game screen showing DFHack keybindings that are active in the current context. +Multiple contexts can be specified by separating them with a +pipe (``|``) - for example, ``@foo|bar|baz/foo`` would match +anything under ``@foo``, ``@bar``, or ``@baz/foo``. -.. image:: images/hotkeys.png +Interactive commands like `liquids` cannot be used as hotkeys. -Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a -globally active hotkey. The default keybinding is ``Ctrl-F1``. -In-game Console -=============== -The ``command-prompt`` plugin adds an in-game DFHack terminal, where you -can enter other commands. It's default keybinding is Ctrl-Shift-P. +.. _kill-lua: -Enabling plugins -================ -Many plugins can be in a distinct enabled or disabled state. Some of -them activate and deactivate automatically depending on the contents -of the world raws. Others store their state in world data. However a -number of them have to be enabled globally, and the init file is the -right place to do it. +kill-lua +-------- +Stops any currently-running Lua scripts. By default, scripts can +only be interrupted every 256 instructions. Use ``kill-lua force`` +to interrupt the next instruction. -Most such plugins or scripts support the built-in ``enable`` and ``disable`` -commands. Calling them at any time without arguments prints a list -of enabled and disabled plugins, and shows whether that can be changed -through the same commands. -To enable or disable plugins that support this, use their names as -arguments for the command:: +.. _load: +.. _unload: +.. _reload: - enable manipulator search +load +---- +``load``, ``unload``, and ``reload`` control whether a plugin is loaded +into memory - note that plugins are loaded but disabled unless you do +something. Usage:: + load|unload|reload PLUGIN|(-a|--all) -Game progress -============= +Allows dealing with plugins individually by name, or all at once. + + +.. _ls: + +ls +-- +``ls`` does not list files like the Unix command, but rather +available commands - first built in commands, then plugins, +and scripts at the end. Usage: + +:ls -a: Also list scripts in subdirectories of ``hack/scripts/``, + which are generally not intended for direct use. +:ls : List subcommands for the given plugin. -die ---- -Instantly kills DF without saving. -quicksave +.. _plug: + +plug +---- +Lists available plugins, including their state and detailed description. + +``plug`` + Lists available plugins (*not* commands implemented by plugins) +``plug [PLUGIN] [PLUGIN] ...`` + List state and detailed description of the given plugins, + including commands implemented by the plugin. + + +.. _sc-script: + +sc-script --------- -Save immediately, without exiting. Only available in fortress mode. +Allows additional scripts to be run when certain events occur +(similar to onLoad*.init scripts) -forcepause ----------- -Forces DF to pause. This is useful when your FPS drops below 1 and you lose -control of the game. Activate with ``forcepause 1``; deactivate with ``forcepause 0``. -hide / show ------------ -Hides or shows the DFHack terminal window, respectively. To use ``show``, use -the in-game console (default keybinding ``Ctrl-Shift-P``). Only available on Windows. +.. _script: + +script +------ +Reads a text file, and runs each line as a DFHack command +as if it had been typed in by the user - treating the +input like `an init file `. + +Some other tools, such as `autobutcher` and `workflow`, export +their settings as the commands to create them - which are later +loaded with ``script`` + + +.. _show: + +show +---- +Shows the terminal window after it has been `hidden `. +Only available on Windows. You'll need to use it from a +`keybinding` set beforehand, or the in-game `command-prompt`. + +.. _type: + +type +---- +``type command`` shows where ``command`` is implemented. + +Other Commands +-------------- +The following commands are *not* built-in, but offer similarly useful functions. + +* `command-prompt` +* `hotkeys` +* `lua` +* `multicmd` +* `nopause` +* `quicksave` +* `rb` +* `repeat` + + +.. _init-files: + +Init Files +========== +DFHack allows users to automatically run commonly-used DFHack commands +when DF is first loaded, when a game is loaded, and when a game is unloaded. + +Init scripts function the same way they would if the user manually typed +in their contents, but are much more convenient. In order to facilitate +savegave portability, mod merging, and general organization of init files, +DFHack supports multiple init files both in the main DF directory and +save-specific init files in the save folders. + +DFHack looks for init files in three places each time they could be run: + +#. The main DF directory +#. :file:`data/save/{world}/raw`, where ``world`` is the current save, and +#. :file:`data/save/{world}/raw/objects` + +When reading commands from dfhack.init or with the `script` command, if the final +character on a line is a backslash then the next uncommented line is considered a +continuation of that line, with the backslash deleted. Commented lines are skipped, +so it is possible to comment out parts of a command with the ``#`` character. + + +.. _dfhack.init: + +dfhack*.init +------------ +If your DF folder contains at least one file named ``dfhack*.init`` +(where ``*`` is a placeholder for any string), then all such files +are executed in alphabetical order when DF is first started. + +DFHack is distributed with :download:`/dfhack.init-example` as an example +with an up-to-date collection of basic commands; mostly setting standard +keybindings and `enabling ` plugins. You are encouraged to look +through this file to learn which features it makes available under which +key combinations. You may also customise it and rename it to ``dfhack.init``. + +If your DF folder does not contain any ``dfhack*.init`` files, the example +will be run as a fallback. + +These files are best used for keybindings and enabling persistent plugins +which do not require a world to be loaded. + + +.. _onLoad.init: + +onLoad*.init +------------ +When a world is loaded, DFHack looks for files of the form ``onLoad*.init``, +where ``*`` can be any string, including the empty string. + +All matching init files will be executed in alphebetical order. +A world being loaded can mean a fortress, an adventurer, or legends mode. + +These files are best used for non-persistent commands, such as setting +a `fix ` script to run on `repeat`. + + +.. _onUnload.init: + +onUnload*.init +-------------- +When a world is unloaded, DFHack looks for files of the form ``onUnload*.init``. +Again, these files may be in any of the above three places. +All matching init files will be executed in alphebetical order. + +Modders often use such scripts to disable tools which should not affect +an unmodded save. + + +Other init files +---------------- + +* ``onMapLoad*.init`` and ``onMapUnload*.init`` are run when a map, + distinct from a world, is loaded. This is good for map-affecting + commands (eg `clean`), or avoiding issues in Legends mode. + +* Any lua script named ``raw/init.d/*.lua``, in the save or main DF + directory, will be run when any world or that save is loaded. + + +Miscellaneous Notes +=================== +This section is for odd but important notes that don't fit anywhere else. + +* The ``dfhack-run`` executable is there for calling DFHack commands in + an already running DF+DFHack instance from external OS scripts and programs, + and is *not* the way how you use DFHack normally. + +* If a DF :kbd:`H` hotkey is named with a DFHack command, pressing + the corresponding :kbd:`Fx` button will run that command, instead of + zooming to the set location. + +* The command line has some nice line editing capabilities, including history + that's preserved between different runs of DF (use up/down keys to go through + the history). + +* The binaries for 0.40.15-r1 to 0.34.11-r4 are on DFFD_. + Older versions are available here_. + + .. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15&limit=1000 + .. _here: http://dethware.org/dfhack/download + +* To include whitespace in the argument/s to some command, quote it in + double quotes. To include a double quote character, use ``\"``. + +* If the first non-whitespace character is ``:``, the command is parsed in + an alternative mode which is very useful for the `lua` and `rb` commands. + The following two command lines are exactly equivalent:: + + :foo a b "c d" e f + foo "a b \"c d\" e f" -nopause -------- -Disables pausing (both manual and automatic) with the exception of pause forced -by 'reveal hell'. This is nice for digging under rivers. + * non-whitespace characters following the ``:`` are the command name + * the remaining part of the line is used verbatim as the first argument diff --git a/docs/Introduction.rst b/docs/Introduction.rst new file mode 100644 index 0000000000..8a82e0f10d --- /dev/null +++ b/docs/Introduction.rst @@ -0,0 +1,107 @@ +.. _introduction: + +######################### +Introduction and Overview +######################### + +DFHack is a Dwarf Fortress memory access library, distributed with +a wide variety of useful scripts and plugins. + +The project is currently hosted at https://www.github.com/DFHack/dfhack, +and can be downloaded from `the releases page +`_. + +All new releases are announced in :forums:`the bay12 forums thread <139553>`, +which is also a good place for discussion and questions. + +For users, it provides a significant suite of bugfixes and interface +enhancements by default, and more can be enabled. There are also many tools +(such as `workflow` or `autodump`) which can make life easier. +You can even add third-party scripts and plugins to do almost anything! + +For modders, DFHack makes many things possible. Custom reactions, new +interactions, magic creature abilities, and more can be set through `modtools` +and custom raws. Non-standard DFHack scripts and inits can be stored in the +raw directory, making raws or saves fully self-contained for distribution - +or for coexistence in a single DF install, even with incompatible components. + +For developers, DFHack unites the various ways tools access DF memory and +allows easier development of new tools. As an open-source project under +`various copyleft licences `, contributions are welcome. + + +.. contents:: + + +.. _installing: + +Installing DFHack +================= +DFHack is available for the SDL version of Dwarf Frtress on Windows, +any modern Linux distribution, and OS X (10.6.8 to 10.9). +It is possible to use Windows DF+DFHack under Wine on Linux or OS X. + +Most releases only support the version of DF mentioned in their title - for +example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases +support earlier DF versions as well. Wherever possible, use the latest version +of DFHack built for the target version of DF. + +Installing DFhack involves copying files from a release archive +into your DF folder, so that: + +* On Windows, ``SDL.dll`` is replaced +* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script + +Uninstalling is basically the same, in reverse: + +* On Windows, replace ``SDL.dll`` with ``SDLreal.dll``, then remove the DFHack files. +* On Linux or OSX, remove the DFHack files. + +New players may wish to :wiki:`get a pack ` +with DFHack preinstalled. + + +Getting started +=============== +DFHack basically extends DF with something similar to the +console found in many PC games. + +If DFHack is installed correctly, it will automatically pop up a console +window once DF is started as usual on Windows. Linux and Mac OS X require +running the dfhack script from the terminal, and will use that terminal for +the console. + +* Basic interaction with dfhack involves entering commands into the console. + To learn what commands are available, you can keep reading this documentation + or skip ahead and use the `ls` and `help` commands. + +* Another way to interact with DFHack is to set in-game `keybindings ` + for certain commands. Many of the newer and user-friendly tools are designed + to be used this way. + +* Commands can also run at startup via `init files `, + on in batches at other times with the `script` command. + +* Finally, some commands are persistent once enabled, and will sit in the + background managing or changing some aspect of the game if you `enable` them. + + +.. _troubleshooting: + +Troubleshooting +=============== +Don't panic! Even if you need this section, it'll be OK :) + +If something goes wrong, check the log files in DF's folder +(``stderr.log`` and ``stdout.log``). Looking at these might help you - +or someone else - solve the problem. Take screenshots of any weird +error messages, and take notes on what you did to cause them. + +If the search function in this documentation isn't enough and +:wiki:`the DF Wiki <>` hasn't helped, try asking in: + +- the `#dfhack IRC channel on freenode `_ +- the :forums:`Bay12 DFHack thread <139553>` +- the `/r/dwarffortress `_ questions thread +- the thread for the mod or Starter Pack you're using (if any) + diff --git a/docs/Licenses.rst b/docs/Licenses.rst deleted file mode 100644 index c022277203..0000000000 --- a/docs/Licenses.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _license: - -######## -Licenses -######## - -DFHack is distributed under a range of permissive and weakly copyleft licenses. - -The core uses the ZLib license; the others are described below. - -.. include:: ../LICENSE diff --git a/docs/Lua API.rst b/docs/Lua API.rst index e938a51e06..2a3db9b160 100644 --- a/docs/Lua API.rst +++ b/docs/Lua API.rst @@ -3264,6 +3264,8 @@ sort Does not export any native functions as of now. Instead, it calls lua code to perform the actual ordering of list items. +.. _eventful: + Eventful ======== @@ -3306,6 +3308,8 @@ List of events Is called after calling (or not) native fillSidebarMenu(). Useful for job button tweaking (e.g. adding custom reactions) +.. _EventManager: + Events from EventManager ------------------------ These events are straight from EventManager module. Each of them first needs to be enabled. See functions for more info. If you register a listener before the game is loaded, be aware that no events will be triggered immediately after loading, so you might need to add another event listener for when the game first loads in some cases. @@ -3420,6 +3424,8 @@ Integrated tannery:: b=require "plugins.eventful" b.addReactionToShop("TAN_A_HIDE","LEATHERWORKS") +.. _building-hacks: + Building-hacks ============== diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 77cdf6ed98..0cd16a0754 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -6,48 +6,41 @@ DFHack plugins are the commands, that are compiled with a specific version. They can provide anything from a small keybinding, to a complete overhaul of game subsystems or the entire renderer. -Most are listed here, hopefully organised in a way you will find useful. +Most commands offered by plugins are listed here, +hopefully organised in a way you will find useful. .. contents:: - :depth: 4 + :depth: 3 -=================== -Informative Plugins -=================== +=============================== +Data inspection and visualizers +=============================== -Visualizer and data export -========================== - -.. _plugins/stonesense: +.. _stonesense: stonesense ----------- +========== An isometric visualizer that runs in a second window. This requires working graphics acceleration and at least a dual core CPU (otherwise it will slow -down DF). Invoked with ``stonesense``, or alias ``ssense``. +down DF). Usage: -For detailed information, see the `stonesense readme`_, the `wiki page`_, -or the `Bay12 forum thread`_. +:stonesense: Open the visualiser in a new window. Alias ``ssense``. +:ssense overlay: Overlay DF window, replacing the map area. + ``PRINT_MODE:2D`` strongly recommended for stability. -.. _`stonesense readme`: https://github.com/DFHack/stonesense/blob/master/README.md -.. _`wiki page`: http://dwarffortresswiki.org/index.php/Utility:Stonesense -.. _`Bay12 forum thread`: http://www.bay12forums.com/smf/index.php?topic=43260 +Stonesense can be configured by editing the :file:`stonesense/init.txt` +and :file:`stonesense/keybinds.txt` files. Additional content, such as sprites +for modded creatures, is available from the content repository on the wiki. -Stonesense works on Windows XP SP3 or later, and most modern Linux distributions. -Each stonesense version is built for a particular version of DFHack, so -releases are now done through DFHack. +For detailed information, see the `stonesense readme`_, the :wiki:`wiki page +`, or the :forums:`Bay12 forums thread <106497>`. -mapexport ---------- -Export the current loaded map as a file. This was used by visualizers for -DF 0.34.11, but is now basically obsolete. +.. _`stonesense readme`: https://github.com/DFHack/stonesense/blob/master/README.md -dwarfexport ------------ -Export dwarves to RuneSmith-compatible XML; also unused by modern tools. +.. _blueprint: blueprint ---------- +========= Exports a portion of your fortress into QuickFort style blueprint files.:: blueprint [dig] [build] [place] [query] @@ -61,14 +54,18 @@ Options (If only region and name are given, export all): :place: Export stockpile commands to "-place.csv" :query: Export query commands to "-query.csv" -Goes very well with `plugins/fortplan`, for re-importing. +Goes very well with `fortplan`, for re-importing. +.. _remotefortressreader: + +remotefortressreader +==================== +An in-development plugin for realtime fortress visualisation. +See :forums:`Armok Vision <146473>`. -Map inspection -============== cursecheck ----------- +========== Checks a single map tile or the whole map/world for cursed creatures (ghosts, vampires, necromancers, werebeasts, zombies). @@ -103,27 +100,26 @@ Examples: .. note:: - If you do a full search (with the option "all") former ghosts will show up - with the cursetype "unknown" because their ghostly flag is not set - anymore. But if you happen to find a living/active creature with cursetype - "unknown" please report that in the dfhack thread on the modding forum or - per irc. This is likely to happen with mods which introduce new types - of curses, for example. + If you do a full search (with the option "all") former ghosts will show up + with the cursetype "unknown" because their ghostly flag is not set. + + Please report any living/active creatures with cursetype "unknown" - + this is most likely with mods which introduce new types of curses. flows ------ +===== A tool for checking how many tiles contain flowing liquids. If you suspect that your magma sea leaks into HFS, you can use this tool to be sure without revealing the map. probe ------ +===== Can be used to determine tile properties like temperature. -.. _plugins/prospect: +.. _prospect: prospect --------- +======== Prints a big list of all the present minerals and plants. By default, only the visible part of the map is scanned. @@ -148,10 +144,14 @@ Options: :all: Also estimate vein mineral amounts. -.. _plugins/reveal: +.. _reveal: +.. _unreveal: +.. _revtoggle: +.. _revflood: +.. _revforget: reveal ------- +====== This reveals the map. By default, HFS will remain hidden so that the demons don't spawn. You can use ``reveal hell`` to reveal everything. With hell revealed, you won't be able to unpause until you hide the map again. If you really want @@ -160,28 +160,21 @@ to unpause with hell revealed, use ``reveal demons``. Reveal also works in adventure mode, but any of its effects are negated once you move. When you use it this way, you don't need to run ``unreveal``. -unreveal -~~~~~~~~ -Reverts the effects of ``reveal``. - -revtoggle -~~~~~~~~~ -Switches between ``reveal`` and ``unreveal``. - -revflood -~~~~~~~~ -This command will hide the whole map and then reveal all the tiles that have -a path to the in-game cursor. +Usage and related commands: -revforget -~~~~~~~~~ -When you use reveal, it saves information about what was/wasn't visible before -revealing everything. Unreveal uses this information to hide things again. -This command throws away the information. For example, use in cases where -you abandoned with the fort revealed and no longer want the data. +:reveal: Reveal the whole map, except for HFS to avoid demons spawning +:reveal hell: Also show hell, but requires ``unreveal`` before unpausing +:reveal demons: Reveals everything and allows unpausing - good luck! +:unreveal: Reverts the effects of ``reveal`` +:revtoggle: Switches between ``reveal`` and ``unreveal`` +:revflood: Hide everything, then reveal tiles with a path to the cursor + (useful to make walled-off rooms vanish) +:revforget: Discard info about what was visible before revealing the map. + Only useful where (eg) you abandoned with the fort revealed + and no longer want the data. showmood --------- +======== Shows all items needed for the currently active strange mood. @@ -191,26 +184,26 @@ Bugfixes drybuckets ========== -This utility removes water from all buckets in your fortress, allowing them to be safely used for making lye. +Removes water from all buckets in your fortress, allowing them to be used for making lye. fixdiplomats ============ -Up to version 0.31.12, Elves only sent Diplomats to your fortress to propose -tree cutting quotas due to a bug; once that bug was fixed, Elves stopped caring -about excess tree cutting. This command adds a Diplomat position to all Elven -civilizations, allowing them to negotiate tree cutting quotas - and you to -violate them and start wars. +Adds a Diplomat position to all Elven civilizations, allowing them to negotiate +tree cutting quotas - and you to violate them and start wars. +This was vanilla behaviour until ``0.31.12``, in which the "bug" was "fixed". fixmerchants ============ -This command adds the Guild Representative position to all Human civilizations, -allowing them to make trade agreements (just as they did back in 0.28.181.40d -and earlier) in case you haven't already modified your raws accordingly. +Adds the Guild Representative position to all Human civilizations, +allowing them to make trade agreements. This was the default behaviour in +``0.28.181.40d`` and earlier. + +.. _fix-unit-occupancy: fix-unit-occupancy ================== -This plugin fixes issues with unit occupancy, notably issues with phantom -"unit blocking tile" messages (`Bug 3499`_). It can be run manually, or +This plugin fixes issues with unit occupancy, notably phantom +"unit blocking tile" messages (:bug:`3499`). It can be run manually, or periodically when enabled with the built-in enable/disable commands: :(no argument): Run the plugin once immediately, for the whole map. @@ -220,21 +213,21 @@ periodically when enabled with the built-in enable/disable commands: The default is 1200 ticks, or 1 day. Ticks are only counted when the game is unpaused. -.. _`Bug 3499`: http://bay12games.com/dwarves/mantisbt/view.php?id=3499 +.. _fixveins: fixveins ======== Removes invalid references to mineral inclusions and restores missing ones. -Use this if you broke your embark with tools like tiletypes, or if you +Use this if you broke your embark with tools like `tiletypes`, or if you accidentally placed a construction on top of a valuable mineral floor. petcapRemover ============= -This plugin allows you to remove or raise the pet population cap. In vanilla +Allows you to remove or raise the pet population cap. In vanilla DF, pets will not reproduce unless the population is below 50 and the number of children of that species is below a certain percentage. This plugin allows removing the second restriction and removing or raising the first. Pets still -require PET or PET_EXOTIC tags in order to reproduce. Type help petcapRemover +require PET or PET_EXOTIC tags in order to reproduce. Type ``help petcapRemover`` for exact usage. In order to make population more stable and avoid sudden population booms as you go below the raised population cap, this plugin counts pregnancies toward the new population cap. It can still go over, but only in the @@ -248,7 +241,7 @@ Usage: :petcapRemover pregtime n: sets the pregnancy duration to n ticks. natural pregnancies are 300000 ticks for the current race and 200000 for everyone else -.. _plugins/tweak: +.. _tweak: tweak ===== @@ -287,12 +280,12 @@ One-shot subcommands: Subcommands that persist until disabled or DF quits: :adamantine-cloth-wear: Prevents adamantine clothing from wearing out while being worn (bug 6481). -:advmode-contained: Works around bug 6202, i.e. custom reactions with container inputs +:advmode-contained: Works around :bug:`6202`, custom reactions with container inputs in advmode. The issue is that the screen tries to force you to select the contents separately from the container. This forcefully skips child reagents. :civ-view-agreement: Fixes overlapping text on the "view agreement" screen -:craft-age-wear: Fixes the behavior of crafted items wearing out over time (bug 6003). +:craft-age-wear: Fixes the behavior of crafted items wearing out over time (:bug:`6003`). With this tweak, items made from cloth and leather will gain a level of wear every 20 years. :embark-profile-name: Allows the use of lowercase letters when saving embark profiles @@ -308,9 +301,9 @@ Subcommands that persist until disabled or DF quits: :import-priority-category: Allows changing the priority of all goods in a category when discussing an import agreement with the liaison -:kitchen-keys: Fixes DF kitchen meal keybindings (bug 614) +:kitchen-keys: Fixes DF kitchen meal keybindings (:bug:`614`) :kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences -:kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs (bug 9000) +:kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs (:bug:`9000`) :manager-quantity: Removes the limit of 30 jobs per manager order :max-wheelbarrow: Allows assigning more than 3 wheelbarrows to a stockpile :military-color-assigned: @@ -324,11 +317,11 @@ Subcommands that persist until disabled or DF quits: i.e. stop the rightmost list of the Positions page of the military screen from constantly resetting to the top. :nestbox-color: Fixes the color of built nestboxes -:shift-8-scroll: Gives Shift-8 (or ``*``) priority when scrolling menus, instead of scrolling the map +:shift-8-scroll: Gives Shift-8 (or :kbd:`*`) priority when scrolling menus, instead of scrolling the map :stable-cursor: Saves the exact cursor position between t/q/k/d/b/etc menus of fortress mode. :tradereq-pet-gender: Displays pet genders on the trade request screen -.. _plugins/fix-armory: +.. _fix-armory: fix-armory ========== @@ -342,17 +335,75 @@ UI Upgrades .. note:: - In order to avoid user confusion, as a matter of policy all these tools - display the word "DFHack" on the screen somewhere while active. + In order to avoid user confusion, as a matter of policy all GUI tools + display the word :guilabel:`DFHack` on the screen somewhere while active. When that is not appropriate because they merely add keybinding hints to existing DF screens, they deliberately use red instead of green for the key. + +.. _automelt: + +automelt +======== +When automelt is enabled for a stockpile, any meltable items placed +in it will be designated to be melted. +This plugin adds an option to the :kbd:`q` menu when `enabled `. + +.. _autotrade: + +autotrade +========= +When autotrade is enabled for a stockpile, any items placed in it will be +designated to be taken to the Trade Depot whenever merchants are on the map. +This plugin adds an option to the :kbd:`q` menu when `enabled `. + +.. _command-prompt: + +command-prompt +============== +An in-game DFHack terminal, where you can enter other commands. +Best used from a keybinding; by default :kbd:`Ctrl`:kbd:`Shift`:kbd:`P`. + +Usage: ``command-prompt [entry]`` + +If called with an entry, it starts with that text filled in. +Most useful for developers, who can set a keybinding to open +a laungage interpreter for lua or Ruby by starting with the +`:lua ` or `:rb ` commands. + +Otherwise somewhat similar to `gui/quickcmd`. + +.. image:: images/command-prompt.png + + +.. _hotkeys: + +hotkeys +======= +Opens an in-game screen showing which DFHack keybindings are +active in the current context. + +.. image:: images/hotkeys.png + +Type ``hotkeys`` into the DFHack console to open the screen, +or bind the command to a globally active hotkey. The default +keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. + +.. _rb: + +rb +== +Ruby language plugin, which evaluates the following arguments as a ruby string. +Best used as ``:rb [string]``, for the special parsing mode. Alias ``rb_eval``. + +.. _manipulator: + manipulator =========== An in-game equivalent to the popular program Dwarf Therapist. -To activate, open the unit screen and press ``l``. +To activate, open the unit screen and press :kbd:`l`. .. image:: images/manipulator.png @@ -366,26 +417,26 @@ military and social skills. .. image:: images/manipulator2.png -Press ``t`` to toggle between Profession and Squad view. +Press :kbd:`t` to toggle between Profession and Squad view. .. image:: images/manipulator3.png -Use the arrow keys or number pad to move the cursor around, holding Shift to +Use the arrow keys or number pad to move the cursor around, holding :kbd:`Shift` to move 10 tiles at a time. -Press the Z-Up (``<``) and Z-Down (``>``) keys to move quickly between labor/skill +Press the Z-Up (:kbd:`<`) and Z-Down (:kbd:`>`) keys to move quickly between labor/skill categories. The numpad Z-Up and Z-Down keys seek to the first or last unit -in the list. Backspace seeks to the top left corner. +in the list. :kbd:`Backspace` seeks to the top left corner. Press Enter to toggle the selected labor for the selected unit, or Shift+Enter to toggle all labors within the selected category. -Press the ``+-`` keys to sort the unit list according to the currently selected -skill/labor, and press the ``*/`` keys to sort the unit list by Name, Profession/Squad, -Happiness, or Arrival order (using Tab to select which sort method to use here). +Press the :kbd:`+`:kbd:`-` keys to sort the unit list according to the currently selected +skill/labor, and press the :kbd:`*`:kbd:`/` keys to sort the unit list by Name, Profession/Squad, +Happiness, or Arrival order (using :kbd:`Tab` to select which sort method to use here). -With a unit selected, you can press the ``v`` key to view its properties (and -possibly set a custom nickname or profession) or the ``c`` key to exit +With a unit selected, you can press the :kbd:`v` key to view its properties (and +possibly set a custom nickname or profession) or the :kbd:`c` key to exit Manipulator and zoom to its position within your fortress. The following mouse shortcuts are also available: @@ -398,9 +449,12 @@ The following mouse shortcuts are also available: * Left-click on a unit's name, profession or squad to view its properties. * Right-click on a unit's name, profession or squad to zoom to it. -Pressing ``ESC`` normally returns to the unit screen, but ``Shift-ESC`` would exit +Pressing :kbd:`Esc` normally returns to the unit screen, but :kbd:`Shift`:kbd:`Esc` would exit directly to the main dwarf mode screen. +.. comment - the link target "search" is reserved for the Sphinx search page +.. _search-plugin: + search ====== The search plugin adds search to the Stocks, Animals, Trading, Stockpile, @@ -409,25 +463,25 @@ Noble (assignment candidates), Military (position candidates), Burrows .. image:: images/search.png -Searching works the same way as the search option in "Move to Depot" does. -You will see the Search option displayed on screen with a hotkey (usually ``s``). +Searching works the same way as the search option in :guilabel:`Move to Depot`. +You will see the Search option displayed on screen with a hotkey (usually :kbd:`s`). Pressing it lets you start typing a query and the relevant list will start filtering automatically. -Pressing ENTER, ESC or the arrow keys will return you to browsing the now +Pressing :kbd:`Enter`, :kbd:`Esc` or the arrow keys will return you to browsing the now filtered list, which still functions as normal. You can clear the filter by either going back into search mode and backspacing to delete it, or pressing the "shifted" version of the search hotkey while browsing the -list (e.g. if the hotkey is ``s``, then hitting ``Shift-s`` will clear any +list (e.g. if the hotkey is :kbd:`s`, then hitting :kbd:`Shift`:kbd:`s` will clear any filter). Leaving any screen automatically clears the filter. In the Trade screen, the actual trade will always only act on items that are actually visible in the list; the same effect applies to the Trade -Value numbers displayed by the screen. Because of this, the ``t`` key is +Value numbers displayed by the screen. Because of this, the :kbd:`t` key is blocked while search is active, so you have to reset the filters first. -Pressing ``Alt-C`` will clear both search strings. +Pressing :kbd:`Alt`:kbd:`C` will clear both search strings. In the stockpile screen the option only appears if the cursor is in the rightmost list: @@ -440,18 +494,20 @@ only fat or tallow by forbidding fats, then searching for fat/tallow, and using Permit Fats again while the list is filtered. -Game interface -============== +.. _nopause: -embark-tools ------------- -A collection of embark-related tools. +nopause +======= +Disables pausing (both manual and automatic) with the exception of pause forced +by `reveal` ``hell``. This is nice for digging under rivers. -Usage:: +.. _embark-tools: - embark-tools enable/disable tool [tool]... +embark-tools +============ +A collection of embark-related tools. Usage and available tools:: -Tools: + embark-tools enable/disable tool [tool]... :anywhere: Allows embarking anywhere (including sites, mountain-only biomes, and oceans). Use with caution. @@ -460,8 +516,10 @@ Tools: area, similar to the default clay/stone indicators. :sticky: Maintains the selected local area while navigating the world map +.. _automaterial: + automaterial ------------- +============ This makes building constructions (walls, floors, fortifications, etc) a little bit easier by saving you from having to trawl through long lists of materials each time you place one. @@ -475,7 +533,7 @@ preferred material type. .. image:: images/automaterial-mat.png -Pressing ``a`` while highlighting any material will enable that material for "auto select" +Pressing :kbd:`a` while highlighting any material will enable that material for "auto select" for this construction type. You can enable multiple materials as autoselect. Now the next time you place this type of construction, the plugin will automatically choose materials for you from the kinds you enabled. If there is enough to satisfy the whole placement, @@ -486,47 +544,53 @@ When choosing the construction placement, you will see a couple of options: .. image:: images/automaterial-pos.png -Use ``a`` here to temporarily disable the material autoselection, e.g. if you need +Use :kbd:`a` here to temporarily disable the material autoselection, e.g. if you need to go to the material selection screen so you can toggle some materials on or off. -The other option (auto type selection, off by default) can be toggled on with ``t``. If you +The other option (auto type selection, off by default) can be toggled on with :kbd:`t`. If you toggle this option on, instead of returning you to the main construction menu after selecting materials, it returns you back to this screen. If you use this along with several autoselect enabled materials, you should be able to place complex constructions more conveniently. +.. _buildingplan: + buildingplan ------------- +============ When active (via ``enable buildingplan``), this plugin adds a planning mode for furniture placement. You can then place furniture and other buildings before the required materials are available, and the job will be unsuspended when the item is created. -Very useful when combined with `plugins/workflow` - you can set a constraint +Very useful when combined with `workflow` - you can set a constraint to always have one or two doors/beds/tables/chairs/etc available, and place as many as you like. The plugins then take over and fulfill the orders, with minimal space dedicated to stockpiles. +.. _confirm: + confirm -------- +======= Implements several confirmation dialogs for potentially destructive actions (for example, seizing goods from traders or deleting hauling routes). Usage: -:enable confirm, confirm enable all: - Enable all confirmations (replace with ``disable`` to disable) +:enable confirm: Enable all confirmations; alias ``confirm enable all``. + Replace with ``disable`` to disable. +:confirm help: List available confirmation dialogues. :confirm enable option1 [option2...]: - Enable (or disable) specific confirmations. Run ``confirm help`` - for a complete list of options. + Enable (or disable) specific confirmation dialogues. follow ------- +====== Makes the game view follow the currently highlighted unit after you exit from the current menu or cursor mode. Handy for watching dwarves running around. Deactivated by moving the view manually. +.. _mousequery: + mousequery ----------- +========== Adds mouse controls to the DF interface, eg click-and-drag designations. Options: @@ -542,36 +606,70 @@ Usage:: mousequery [plugin] [rbutton] [track] [edge] [live] [enable|disable] -.. _plugins/resume: +.. _resume: resume ------- +====== Allows automatic resumption of suspended constructions, along with colored UI hints for construction status. -tidlers -------- -Toggle between all possible positions where the idlers count can be placed. +.. _trackstop: trackstop ---------- -Adds a ``q`` menu for track stops, which is completely blank by default. +========= +Adds a :kbd:`q` menu for track stops, which is completely blank by default. This allows you to view and/or change the track stop's friction and dump direction settings, using the keybindings from the track stop building interface. -twaterlvl ---------- -Toggle between displaying/not displaying liquid depth as numbers. +.. _sort-items: -stockpile management --------------------- +sort-items +========== +Sort the visible item list:: + + sort-items order [order...] + +Sort the item list using the given sequence of comparisons. +The ``<`` prefix for an order makes undefined values sort first. +The ``>`` prefix reverses the sort order for defined values. + +Item order examples:: + + description material wear type quality + +The orderings are defined in ``hack/lua/plugins/sort/*.lua`` -.. _plugins/stocksettings: +.. _sort-units: -import/export -~~~~~~~~~~~~~ -The following commands allow you to save and load stockpile settings. -See `scripts/gui/stockpiles` for an in-game interface. +sort-units +========== +Sort the visible unit list:: + + sort-units order [order...] + +Sort the unit list using the given sequence of comparisons. +The ``<`` prefix for an order makes undefined values sort first. +The ``>`` prefix reverses the sort order for defined values. + +Unit order examples:: + + name age arrival squad squad_position profession + +The orderings are defined in ``hack/lua/plugins/sort/*.lua`` + +.. _stocks: + +stocks +====== +Replaces the DF stocks screen with an improved version. + +.. _stocksettings: +.. _stockpiles: + +stocksettings +============= +Offers the following commands to save and load stockpile settings. +See `gui/stockpiles` for an in-game interface. :copystock: Copies the parameters of the currently highlighted stockpile to the custom stockpile settings and switches to custom stockpile placement mode, effectively @@ -584,9 +682,9 @@ See `scripts/gui/stockpiles` for an in-game interface. :loadstock: Loads a saved stockpile settings file and applies it to the currently selected stockpile. eg: ``loadstock food_settings.dfstock`` -To use savestock and loadstock, use the ``q`` command to highlight a stockpile. +To use savestock and loadstock, use the :kbd:`q` command to highlight a stockpile. Then run savestock giving it a descriptive filename. Then, in a different (or -the same!) gameworld, you can highlight any stockpile with ``q`` then execute the +the same!) gameworld, you can highlight any stockpile with :kbd:`q` then execute the ``loadstock`` command passing it the name of that file. The settings will be applied to that stockpile. @@ -594,26 +692,11 @@ Note that files are relative to the DF folder, so put your files there or in a subfolder for easy access. Filenames should not have spaces. Generated materials, divine metals, etc are not saved as they are different in every world. -Stockpile automation -~~~~~~~~~~~~~~~~~~~~ - -Enable the autodump, automelt and autotrade plugins in your dfhack.init with:: - - enable autodump automelt autotrade - -When querying a stockpile, options will appear to toggle automation settings for this stockpile. - -When automelt is enabled for a stockpile, any meltable items placed in it will be designated -to be melted. When autotrade is enabled for a stockpile, any items placed in it will be -designated to be taken to the Trade Depot whenever merchants are on the map. -When autodump is enabled for a stockpile, any items placed in this stockpile will -automatically be designated to be dumped. - -.. _plugins/rename: +.. _rename: rename ------- -Allows renaming various things. Use `scripts/gui/rename` for an in-game interface. +====== +Allows renaming various things. Use `gui/rename` for an in-game interface. Options: @@ -631,11 +714,12 @@ Options: The building must be one of stockpile, workshop, furnace, trap, siege engine or an activity zone. +.. _rendermax: + rendermax ---------- +========= A collection of renderer replacing/enhancing filters. For better effect try changing the -black color in palette to non totally black. For more info see -`the Bay12 Rendermax thread `_. +black color in palette to non totally black. See :forums:`128487` for more info. Options: @@ -652,350 +736,114 @@ materials that color the light etc... .. image:: images/rendermax.png -Designations -============ - -burrow ------- -Miscellaneous burrow control. Allows manipulating burrows and automated burrow -expansion while digging. - -Options: +=========================== +Job and Fortress management +=========================== -:enable feature ...: - Enable features of the plugin. -:disable feature ...: - Disable features of the plugin. -:clear-unit burrow burrow ...: - Remove all units from the burrows. -:clear-tiles burrow burrow ...: - Remove all tiles from the burrows. -:set-units target-burrow src-burrow ...: - Clear target, and adds units from source burrows. -:add-units target-burrow src-burrow ...: - Add units from the source burrows to the target. -:remove-units target-burrow src-burrow ...: - Remove units in source burrows from the target. -:set-tiles target-burrow src-burrow ...: - Clear target and adds tiles from the source burrows. -:add-tiles target-burrow src-burrow ...: - Add tiles from the source burrows to the target. -:remove-tiles target-burrow src-burrow ...: - Remove tiles in source burrows from the target. +.. _autolabor: - For these three options, in place of a source burrow it is - possible to use one of the following keywords: ABOVE_GROUND, - SUBTERRANEAN, INSIDE, OUTSIDE, LIGHT, DARK, HIDDEN, REVEALED +autolabor +========= +Automatically manage dwarf labors to efficiently complete jobs. +Autolabor tries to keep as many dwarves as possible busy but +also tries to have dwarves specialize in specific skills. -Features: +The key is that, for almost all labors, once a dwarf begins a job it will finish that +job even if the associated labor is removed. Autolabor therefore frequently checks +which dwarf or dwarves should take new jobs for that labor, and sets labors accordingly. +Labors with equiptment (mining, hunting, and woodcutting), which are abandoned +if labors change mid-job, are handled slightly differently to minimise churn. -:auto-grow: When a wall inside a burrow with a name ending in '+' is dug - out, the burrow is extended to newly-revealed adjacent walls. - This final '+' may be omitted in burrow name args of commands above. - Digging 1-wide corridors with the miner inside the burrow is SLOW. +.. warning:: -dig ---- -This plugin makes many automated or complicated dig patterns easy. + *autolabor will override any manual changes you make to labors while + it is enabled, including through other tools such as Dwarf Therapist* -digv -~~~~ -Designates a whole vein for digging. Requires an active in-game cursor placed -over a vein tile. With the 'x' option, it will traverse z-levels (putting stairs -between the same-material tiles). +Simple usage: -digvx -~~~~~ -A permanent alias for 'digv x'. +:enable autolabor: Enables the plugin with default settings. (Persistent per fortress) +:disable autolabor: Disables the plugin. -digl -~~~~ -Designates layer stone for digging. Requires an active in-game cursor placed -over a layer stone tile. With the 'x' option, it will traverse z-levels -(putting stairs between the same-material tiles). With the 'undo' option it -will remove the dig designation instead (if you realize that digging out a 50 -z-level deep layer was not such a good idea after all). +Anything beyond this is optional - autolabor works well on the default settings. -diglx -~~~~~ -A permanent alias for 'digl x'. +By default, each labor is assigned to between 1 and 200 dwarves (2-200 for mining). +By default 33% of the workforce become haulers, who handle all hauling jobs as well +as cleaning, pulling levers, recovering wounded, removing constructions, and filling ponds. +Other jobs are automatically assigned as described above. Each of these settings can be adjusted. -digexp -~~~~~~ -This command is for `exploratory mining`_. +Jobs are rarely assigned to nobles with responsibilities for meeting diplomats or merchants, +never to the chief medical dwarf, and less often to the bookeeper and manager. -.. _`exploratory mining`: http://dwarffortresswiki.org/index.php/cv:Exploratory_mining +Hunting is never assigned without a butchery, and fishing is never assigned without a fishery. -There are two variables that can be set: pattern and filter. +For each labor a preference order is calculated based on skill, biased against masters of other +trades and excluding those who can't do the job. The labor is then added to the best +dwarves for that labor. We assign at least the minimum number of dwarfs, in order of preference, +and then assign additional dwarfs that meet any of these conditions: -Patterns: +* The dwarf is idle and there are no idle dwarves assigned to this labor +* The dwarf has non-zero skill associated with the labor +* The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled. -:diag5: diagonals separated by 5 tiles -:diag5r: diag5 rotated 90 degrees -:ladder: A 'ladder' pattern -:ladderr: ladder rotated 90 degrees -:clear: Just remove all dig designations -:cross: A cross, exactly in the middle of the map. +We stop assigning dwarfs when we reach the maximum allowed. -Filters: +Advanced usage: -:all: designate whole z-level -:hidden: designate only hidden tiles of z-level (default) -:designated: Take current designation and apply pattern to it. +:autolabor []: + Set number of dwarves assigned to a labor. +:autolabor haulers: Set a labor to be handled by hauler dwarves. +:autolabor disable: Turn off autolabor for a specific labor. +:autolabor reset: Return a labor to the default handling. +:autolabor reset-all: Return all labors to the default handling. +:autolabor list: List current status of all labors. +:autolabor status: Show basic status information. -After you have a pattern set, you can use 'expdig' to apply it again. +See `autolabor-artisans` for a differently-tuned setup. Examples: -``expdig diag5 hidden`` - Designate the diagonal 5 patter over all hidden tiles -``expdig`` - Apply last used pattern and filter -``expdig ladder designated`` - Take current designations and replace them with the ladder pattern +``autolabor MINE`` + Keep at least 5 dwarves with mining enabled. +``autolabor CUT_GEM 1 1`` + Keep exactly 1 dwarf with gemcutting enabled. +``autolabor COOK 1 1 3`` + Keep 1 dwarf with cooking enabled, selected only from the top 3. +``autolabor FEED_WATER_CIVILIANS haulers`` + Have haulers feed and water wounded dwarves. +``autolabor CUTWOOD disable`` + Turn off autolabor for wood cutting. -digcircle -~~~~~~~~~ -A command for easy designation of filled and hollow circles. -It has several types of options. +.. _autohauler: -Shape: +autohauler +========== +Autohauler is an autolabor fork. -:hollow: Set the circle to hollow (default) -:filled: Set the circle to filled -:#: Diameter in tiles (default = 0, does nothing) +Rather than the all-of-the-above means of autolabor, autohauler will instead +only manage hauling labors and leave skilled labors entirely to the user, who +will probably use Dwarf Therapist to do so. -Action: +Idle dwarves will be assigned the hauling labors; everyone else (including +those currently hauling) will have the hauling labors removed. This is to +encourage every dwarf to do their assigned skilled labors whenever possible, +but resort to hauling when those jobs are not available. This also implies +that the user will have a very tight skill assignment, with most skilled +labors only being assigned to just one dwarf, no dwarf having more than two +active skilled labors, and almost every non-military dwarf having at least +one skilled labor assigned. -:set: Set designation (default) -:unset: Unset current designation -:invert: Invert designations already present +Autohauler allows skills to be flagged as to prevent hauling labors from +being assigned when the skill is present. By default this is the unused +ALCHEMIST labor but can be changed by the user. -Designation types: -:dig: Normal digging designation (default) -:ramp: Ramp digging -:ustair: Staircase up -:dstair: Staircase down -:xstair: Staircase up/down -:chan: Dig channel +.. _job: -After you have set the options, the command called with no options -repeats with the last selected parameters. +job +=== +Command for general job query and manipulation. -Examples: - -``digcircle filled 3`` - Dig a filled circle with diameter = 3. -``digcircle`` - Do it again. - -digtype -~~~~~~~ -For every tile on the map of the same vein type as the selected tile, this command designates it to have the same designation as the selected tile. If the selected tile has no designation, they will be dig designated. -If an argument is given, the designation of the selected tile is ignored, and all appropriate tiles are set to the specified designation. - -Options: - -:dig: -:channel: -:ramp: -:updown: up/down stairs -:up: up stairs -:down: down stairs -:clear: clear designation - -digFlood --------- -Automatically digs out specified veins as they are discovered. It runs once -every time a dwarf finishes a dig job. It will only dig out appropriate tiles -that are adjacent to the finished dig job. To add a vein type, use ``digFlood 1 [type]``. -This will also enable the plugin. To remove a vein type, use ``digFlood 0 [type] 1`` -to disable, then remove, then re-enable. - -Usage: - -:help digflood: detailed help message -:digFlood 0: disable the plugin -:digFlood 1: enable the plugin -:digFlood 0 MICROCLINE COAL_BITUMINOUS 1: - disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin -:digFlood CLEAR: remove all inorganics from monitoring -:digFlood digAll1: ignore the monitor list and dig any vein -:digFlood digAll0: disable digAll mode - -filltraffic ------------ -Set traffic designations using flood-fill starting at the cursor. - -Traffic Type Codes: - -:H: High Traffic -:N: Normal Traffic -:L: Low Traffic -:R: Restricted Traffic - -Other Options: - -:X: Fill across z-levels. -:B: Include buildings and stockpiles. -:P: Include empty space. - -Example: - -``filltraffic H`` - When used in a room with doors, it will set traffic to HIGH in just that room. - -alltraffic ----------- -Set traffic designations for every single tile of the map (useful for resetting traffic designations). - -Traffic Type Codes: - -:H: High Traffic -:N: Normal Traffic -:L: Low Traffic -:R: Restricted Traffic - -Example: - -``alltraffic N`` - Set traffic to 'normal' for all tiles. - -restrictliquid --------------- -Restrict traffic on all visible tiles with liquid. - -restrictice ------------ -Restrict traffic on all tiles on top of visible ice. - -getplants ---------- -This tool allows plant gathering and tree cutting by RAW ID. Specify the types -of trees to cut down and/or shrubs to gather by their plant names, separated -by spaces. - -Options: - -:-t: Select trees only (exclude shrubs) -:-s: Select shrubs only (exclude trees) -:-c: Clear designations instead of setting them -:-x: Apply selected action to all plants except those specified (invert - selection) -:-a: Select every type of plant (obeys ``-t``/``-s``) - -Specifying both ``-t`` and ``-s`` will have no effect. If no plant IDs are specified, -all valid plant IDs will be listed. - - -=========================== -Job and Fortress management -=========================== - -.. _plugins/autolabor: - -autolabor -========= -Automatically manage dwarf labors to efficiently complete jobs. -Autolabor tries to keep as many dwarves as possible busy but -also tries to have dwarves specialize in specific skills. - -The key is that, for almost all labors, once a dwarf begins a job it will finish that -job even if the associated labor is removed. Autolabor therefore frequently checks -which dwarf or dwarves should take new jobs for that labor, and sets labors accordingly. -Labors with equiptment (mining, hunting, and woodcutting), which are abandoned -if labors change mid-job, are handled slightly differently to minimise churn. - -.. warning:: - - *autolabor will override any manual changes you make to labors while - it is enabled, including through other tools such as Dwarf Therapist* - -Simple usage: - -:enable autolabor: Enables the plugin with default settings. (Persistent per fortress) -:disable autolabor: Disables the plugin. - -Anything beyond this is optional - autolabor works well on the default settings. - -By default, each labor is assigned to between 1 and 200 dwarves (2-200 for mining). -By default 33% of the workforce become haulers, who handle all hauling jobs as well -as cleaning, pulling levers, recovering wounded, removing constructions, and filling ponds. -Other jobs are automatically assigned as described above. Each of these settings can be adjusted. - -Jobs are rarely assigned to nobles with responsibilities for meeting diplomats or merchants, -never to the chief medical dwarf, and less often to the bookeeper and manager. - -Hunting is never assigned without a butchery, and fishing is never assigned without a fishery. - -For each labor a preference order is calculated based on skill, biased against masters of other -trades and excluding those who can't do the job. The labor is then added to the best -dwarves for that labor. We assign at least the minimum number of dwarfs, in order of preference, -and then assign additional dwarfs that meet any of these conditions: - -* The dwarf is idle and there are no idle dwarves assigned to this labor -* The dwarf has non-zero skill associated with the labor -* The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled. - -We stop assigning dwarfs when we reach the maximum allowed. - -Advanced usage: - -:autolabor []: - Set number of dwarves assigned to a labor. -:autolabor haulers: Set a labor to be handled by hauler dwarves. -:autolabor disable: Turn off autolabor for a specific labor. -:autolabor reset: Return a labor to the default handling. -:autolabor reset-all: Return all labors to the default handling. -:autolabor list: List current status of all labors. -:autolabor status: Show basic status information. - -See `scripts/autolabor-artisans` for a differently-tunde setup. - -Examples: - -``autolabor MINE`` - Keep at least 5 dwarves with mining enabled. -``autolabor CUT_GEM 1 1`` - Keep exactly 1 dwarf with gemcutting enabled. -``autolabor COOK 1 1 3`` - Keep 1 dwarf with cooking enabled, selected only from the top 3. -``autolabor FEED_WATER_CIVILIANS haulers`` - Have haulers feed and water wounded dwarves. -``autolabor CUTWOOD disable`` - Turn off autolabor for wood cutting. - -autohauler ----------- -Rather than the all-of-the-above means of autolabor, autohauler will instead -only manage hauling labors and leave skilled labors entirely to the user, who -will probably use Dwarf Therapist to do so. - -Idle dwarves will be assigned the hauling labors; everyone else (including -those currently hauling) will have the hauling labors removed. This is to -encourage every dwarf to do their assigned skilled labors whenever possible, -but resort to hauling when those jobs are not available. This also implies -that the user will have a very tight skill assignment, with most skilled -labors only being assigned to just one dwarf, no dwarf having more than two -active skilled labors, and almost every non-military dwarf having at least -one skilled labor assigned. - -Autohauler allows skills to be flagged as to prevent hauling labors from -being assigned when the skill is present. By default this is the unused -ALCHEMIST labor but can be changed by the user. - - -Job management -============== - -.. _plugins/job: - -job ---- -Command for general job query and manipulation. - -Options: +Options: *no extra options* Print details of the current job. The job can be selected @@ -1008,8 +856,8 @@ Options: Replace the exact item type id in the job item. job-material ------------- -Alter the material of the selected job. +============ +Alter the material of the selected job. Similar to ``job item-material ...`` Invoked as:: @@ -1017,24 +865,26 @@ Invoked as:: Intended to be used as a keybinding: -* In 'q' mode, when a job is highlighted within a workshop or furnace, +* In :kbd:`q` mode, when a job is highlighted within a workshop or furnace, changes the material of the job. Only inorganic materials can be used in this mode. -* In 'b' mode, during selection of building components positions the cursor +* In :kbd:`b` mode, during selection of building components positions the cursor over the first available choice with the matching material. job-duplicate -------------- -Duplicate the selected job in a workshop: +============= +In :kbd:`q` mode, when a job is highlighted within a workshop or furnace +building, calling ``job-duplicate`` instantly duplicates the job. -* In 'q' mode, when a job is highlighted within a workshop or furnace building, - instantly duplicates the job. +.. _stockflow: stockflow ---------- +========= Allows the fortress bookkeeper to queue jobs through the manager, based on space or items available in stockpiles. +Inspired by `workflow`. + Usage: ``stockflow enable`` @@ -1048,10 +898,10 @@ Usage: ``stockflow status`` Display whether the plugin is enabled. -While enabled, the ``q`` menu of each stockpile will have two new options: +While enabled, the :kbd:`q` menu of each stockpile will have two new options: -* ``j``: Select a job to order, from an interface like the manager's screen. -* ``J``: Cycle between several options for how many such jobs to order. +* :kbd:`j`: Select a job to order, from an interface like the manager's screen. +* :kbd:`J`: Cycle between several options for how many such jobs to order. Whenever the bookkeeper updates stockpile records, new work orders will be placed on the manager's queue for each such selection, reduced by the @@ -1060,14 +910,12 @@ number of identical orders already in the queue. In fast mode, new work orders will be enqueued once per day, instead of waiting for the bookkeeper. -.. _plugins/workflow: +.. _workflow: workflow --------- -Manage control of repeat jobs. - -Check out `scripts/gui/workflow` for a simple front-end integrated -in the game UI. +======== +Manage control of repeat jobs. `gui/workflow` provides a simple +front-end integrated in the game UI. Usage: @@ -1095,7 +943,7 @@ Usage: Delete all constraints. Function -~~~~~~~~ +-------- When the plugin is enabled, it protects all repeat jobs from removal. If they do disappear due to any cause, they are immediately re-added to their workshop and suspended. @@ -1107,15 +955,14 @@ the amount has to drop before jobs are resumed; this is intended to reduce the frequency of jobs being toggled. Constraint format -~~~~~~~~~~~~~~~~~ +----------------- The constraint spec consists of 4 parts, separated with ``/`` characters:: ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,] The first part is mandatory and specifies the item type and subtype, -using the raw tokens for items, in the same syntax you would e.g. use -for a custom reaction input. For more information, see -`this page. `_ +using the raw tokens for items (the same syntax used custom reaction inputs). +For more information, see :wiki:`this wiki page `. The subsequent parts are optional: @@ -1134,7 +981,7 @@ The subsequent parts are optional: be used to ignore imported items or items below a certain quality. Constraint examples -~~~~~~~~~~~~~~~~~~~ +------------------- Keep metal bolts within 900-1000, and wood/bone within 150-200:: workflow amount AMMO:ITEM_AMMO_BOLTS/METAL 1000 100 @@ -1172,7 +1019,7 @@ Make sure there are always 80-100 units of dimple dye:: .. note:: In order for this to work, you have to set the material of the PLANT input - on the Mill Plants job to MUSHROOM_CUP_DIMPLE using the 'job item-material' + on the Mill Plants job to MUSHROOM_CUP_DIMPLE using the `job item-material ` command. Otherwise the plugin won't be able to deduce the output material. Maintain 10-100 locally-made crafts of exceptional quality:: @@ -1180,13 +1027,10 @@ Maintain 10-100 locally-made crafts of exceptional quality:: workflow count CRAFTS///LOCAL,EXCEPTIONAL 100 90 -Cleanup and garbage disposal -============================ - -.. _plugins/clean: +.. _clean: clean ------ +===== Cleans all the splatter that get scattered all over the map, items and creatures. In an old fortress, this can significantly reduce FPS lag. It can also spoil your !!FUN!!, so think before you use it. @@ -1203,15 +1047,19 @@ Extra options for ``map``: :snow: Also remove snow coverings. spotclean ---------- +========= Works like ``clean map snow mud``, but only for the tile under the cursor. Ideal if you want to keep that bloody entrance ``clean map`` would clean up. -.. _plugins/autodump: +.. _autodump: autodump --------- -This utility lets you quickly move all items designated to be dumped. +======== +This plugin adds an option to the :kbd:`q` menu for stckpiles when `enabled `. +When autodump is enabled for a stockpile, any items placed in the stockpile will +automatically be designated to be dumped. + +ALternatively, you can use it to quickly move all items designated to be dumped. Items are instantly moved to the cursor position, the dump flag is unset, and the forbid flag is set, as if it had been dumped normally. Be aware that any active dump item tasks still point at the item. @@ -1221,18 +1069,17 @@ Cursor must be placed on a floor tile so the items can be dumped there. Options: :destroy: Destroy instead of dumping. Doesn't require a cursor. -:destroy-here: Destroy items only under the cursor. Alias ``autodump-destroy-here``, for keybindings. + If called again before the game is resumed, cancels destroy. +:destroy-here: As ``destroy``, but only the selected item in the :kbd:`k` list, + or inside a container. + Alias ``autodump-destroy-here``, for keybindings. :visible: Only process items that are not hidden. :hidden: Only process hidden items. :forbidden: Only process forbidden items (default: only unforbidden). -autodump-destroy-item -~~~~~~~~~~~~~~~~~~~~~ -Destroy the selected item. The item may be selected in the ``k`` list, or inside -a container. If called again before the game is resumed, cancels destroy. cleanowned ----------- +========== Confiscates items owned by dwarfs. By default, owned food on the floor and rotten items are confistacted and dumped. @@ -1252,11 +1099,10 @@ Example: worn items with 'X' damage and above. -Fortress activity management -============================ +.. _dwarfmonitor: dwarfmonitor ------------- +============ Records dwarf activity to measure fort efficiency. Options: @@ -1271,7 +1117,7 @@ Options: Widget configuration: -The following types of widgets (defined in ``hack/lua/plugins/dwarfmonitor.lua``) +The following types of widgets (defined in :file:`hack/lua/plugins/dwarfmonitor.lua`) can be displayed on the main fortress mode screen: :date: Show the in-game date @@ -1279,7 +1125,7 @@ can be displayed on the main fortress mode screen: :weather: Show current weather (rain/snow) :cursor: Show the current mouse cursor position -The file ``dfhack-config/dwarfmonitor.json`` can be edited to control the +The file :file:`dfhack-config/dwarfmonitor.json` can be edited to control the positions and settings of all widgets displayed. This file should contain a JSON object with the key ``widgets`` containing an array of objects - see the included file in the ``dfhack-config`` folder for an example:: @@ -1317,7 +1163,7 @@ Some widgets support additional options: * ``D``: The current day, zero-padded if necessary * ``d``: The current day, *not* zero-padded - The default date format is ``Y-M-D``. + The default date format is ``Y-M-D``, per the ISO8601 standard. * ``cursor`` widget: @@ -1329,11 +1175,13 @@ Some widgets support additional options: nothing will be displayed. workNow -------- +======= Force all dwarves to look for a job immediately, or as soon as the game is unpaused. +.. _seedwatch: + seedwatch ---------- +========= Watches the numbers of seeds available and enables/disables seed and plant cooking. Each plant type can be assigned a limit. If their number falls below that limit, @@ -1360,10 +1208,10 @@ Examples: ``seedwatch all 30`` adds all plants from the abbreviation list to the watch list, the limit being 30. -.. _plugins/zone: +.. _zone: zone ----- +==== Helps a bit with managing activity zones (pens, pastures and pits) and cages. Options: @@ -1419,7 +1267,7 @@ Filters: :milkable: Race is milkable. Negatable. Usage with single units -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- One convenient way to use the zone tool is to bind the command 'zone assign' to a hotkey, maybe also the command 'zone set'. Place the in-game cursor over a pen/pasture or pit, use 'zone set' to mark it. Then you can select units @@ -1428,7 +1276,7 @@ and use 'zone assign' to assign them to their new home. Allows pitting your own dwarves, by the way. Usage with filters -~~~~~~~~~~~~~~~~~~ +------------------ All filters can be used together with the 'assign' command. Restrictions: It's not possible to assign units who are inside built cages @@ -1449,14 +1297,14 @@ are not properly added to your own stocks; slaughtering them should work). Most filters can be negated (e.g. 'not grazer' -> race is not a grazer). Mass-renaming -~~~~~~~~~~~~~ +------------- Using the 'nick' command you can set the same nickname for multiple units. If used without 'assign', 'all' or 'count' it will rename all units in the current default target zone. Combined with 'assign', 'all' or 'count' (and further optional filters) it will rename units matching the filter conditions. Cage zones -~~~~~~~~~~ +---------- Using the 'tocages' command you can assign units to a set of cages, for example a room next to your butcher shop(s). They will be spread evenly among available cages to optimize hauling to and butchering from them. For this to work you need @@ -1467,7 +1315,7 @@ would make no sense, but can be used together with 'nick' or 'remnick' and all the usual filters. Examples -~~~~~~~~ +-------- ``zone assign all own ALPACA minage 3 maxage 10`` Assign all own alpacas who are between 3 and 10 years old to the selected pasture. @@ -1490,7 +1338,7 @@ Examples on the current default zone. autonestbox ------------ +=========== Assigns unpastured female egg-layers to nestbox zones. Requires that you create pen/pasture zones above nestboxes. If the pen is bigger than 1x1 the nestbox must be in the top left corner. Only 1 unit will be assigned per pen, regardless @@ -1509,17 +1357,17 @@ Options: :sleep: Must be followed by number X. Changes the timer to sleep X frames between runs. -.. _plugins/autobutcher: +.. _autobutcher: autobutcher ------------ +=========== Assigns lifestock for slaughter once it reaches a specific count. Requires that you add the target race(s) to a watch list. Only tame units will be processed. Units will be ignored if they are: -* Nicknamed (for custom protection; you can use the `plugins/rename` ``unit`` tool - individually, or `plugins/zone` ``nick`` for groups) +* Nicknamed (for custom protection; you can use the `rename` ``unit`` tool + individually, or `zone` ``nick`` for groups) * Caged, if and only if the cage is defined as a room (to protect zoos) * Trained for war or hunting @@ -1528,7 +1376,7 @@ opposite sex or have been gelded) will be butchered before those who will. Older adults and younger children will be butchered first if the population is above the target (default 1 male, 5 female kids and adults). Note that you may need to set a target above 1 to have a reliable breeding population -due to asexuality etc. See `scripts/fix-ster` if this is a problem. +due to asexuality etc. See `fix-ster` if this is a problem. Options: @@ -1604,7 +1452,7 @@ add some new races with 'watch'. If you simply want to stop it completely use autobutcher unwatch ALPACA CAT autochop ---------- +======== Automatically manage tree cutting designation to keep available logs withing given quotas. @@ -1619,53 +1467,13 @@ cycle runs once every in game day. If you add ``enable getplants`` to your dfhack.init there will be a hotkey to open the dashboard from the chop designation menu. -treefarm --------- -Automatically manages special burrows and regularly schedules tree chopping -and digging when appropriate. - -Every time the plugin runs, it checks for burrows with a name containing the -string ``"treefarm"``. For each such burrow, it checks every tile in it for -fully-grown trees and for diggable walls. For each fully-grown tree it finds, -it designates the tree to be chopped, and for each natural wall it finds, it -designates the wall to be dug. - -Usage: - -:treefarm: Enables treefarm monitoring, starting next frame -:treefarm n: Enables treefarm monitoring, starting next frame, and sets - interval to n frames. If n is less than one, disables monitoring. - - -============== -Adventure mode -============== - -adv-bodyswap -============ -This allows taking control over your followers and other creatures in adventure -mode. For example, you can make them pick up new arms and armor and equip them -properly. - -Usage: - -* When viewing unit details, body-swaps into that unit. -* In the main adventure mode screen, reverts transient swap. - -advtools -======== -A package of different adventure mode tools. Usage: - -:list-equipped [all]: List armor and weapons equipped by your companions. - If all is specified, also lists non-metal clothing. -:metal-detector [all-types] [non-trader]: - Reveal metal armor and weapons in shops. The options - disable the checks on item type and being in shop. ================ Map modification ================ +.. _3dveins: + 3dveins ======= Removes all existing veins from the map and generates new ones using @@ -1675,24 +1483,78 @@ the command for the second time should produce no change. It is best to run it just once immediately after embark. This command is intended as only a cosmetic change, so it takes -care to exactly preserve the mineral counts reported by `plugins/prospect` ``all``. +care to exactly preserve the mineral counts reported by `prospect` ``all``. The amounts of different layer stones may slightly change in some cases if vein mass shifts between Z layers. -.. warning:: +The only undo option is to restore your save from backup. - There is no undo option other than restoring from backup. +.. _alltraffic: -changelayer -=========== -Changes material of the geology layer under cursor to the specified inorganic -RAW material. Can have impact on all surrounding regions, not only your embark! -By default changing stone to soil and vice versa is not allowed. By default +alltraffic +========== +Set traffic designations for every single tile of the map - useful for resetting +traffic designations. See also `filltraffic`, `restrictice`, and `restrictliquid`. + +Options: + +:H: High Traffic +:N: Normal Traffic +:L: Low Traffic +:R: Restricted Traffic + +.. _burrow: + +burrow +====== +Miscellaneous burrow control. Allows manipulating burrows and automated burrow +expansion while digging. + +Options: + +:enable feature ...: + Enable features of the plugin. +:disable feature ...: + Disable features of the plugin. +:clear-unit burrow burrow ...: + Remove all units from the burrows. +:clear-tiles burrow burrow ...: + Remove all tiles from the burrows. +:set-units target-burrow src-burrow ...: + Clear target, and adds units from source burrows. +:add-units target-burrow src-burrow ...: + Add units from the source burrows to the target. +:remove-units target-burrow src-burrow ...: + Remove units in source burrows from the target. +:set-tiles target-burrow src-burrow ...: + Clear target and adds tiles from the source burrows. +:add-tiles target-burrow src-burrow ...: + Add tiles from the source burrows to the target. +:remove-tiles target-burrow src-burrow ...: + Remove tiles in source burrows from the target. + + For these three options, in place of a source burrow it is + possible to use one of the following keywords: ABOVE_GROUND, + SUBTERRANEAN, INSIDE, OUTSIDE, LIGHT, DARK, HIDDEN, REVEALED + +Features: + +:auto-grow: When a wall inside a burrow with a name ending in '+' is dug + out, the burrow is extended to newly-revealed adjacent walls. + This final '+' may be omitted in burrow name args of commands above. + Digging 1-wide corridors with the miner inside the burrow is SLOW. + + +changelayer +=========== +Changes material of the geology layer under cursor to the specified inorganic +RAW material. Can have impact on all surrounding regions, not only your embark! +By default changing stone to soil and vice versa is not allowed. By default changes only the layer at the cursor position. Note that one layer can stretch across lots of z levels. By default changes only the geology which is linked to the biome under the cursor. That geology might be linked to other biomes as well, though. Mineral veins and gem clusters will stay on the map. Use -`plugins/changevein` for them. +`changevein` for them. tl;dr: You will end up with changing quite big areas in one go, especially if you use it in lower z levels. Use with care. @@ -1744,7 +1606,7 @@ Examples: Try reverting the changes manually or even better use an older savegame. You did save your game, right? -.. _plugins/changevein: +.. _changevein: changevein ========== @@ -1808,6 +1670,129 @@ replicating the old channel digging designation. It also removes any and all 'down ramps' that can remain after a cave-in (you don't have to designate anything for that to happen). +.. _dig: + +dig +=== +This plugin makes many automated or complicated dig patterns easy. + +Basic commands: + +:digv: Designate all of the selected vein for digging. +:digvx: Also cross z-levels, digging stairs as needed. Alias for ``digv x``. +:digl: Like ``digv``, for layer stone. Also supports an ``undo`` option + to remove designations, for if you accidentally set 50 levels at once. +:diglx: Also cross z-levels, digging stairs as needed. Alias for ``digl x``. + +digexp +====== +This command is for :wiki:`exploratory mining `. + +There are two variables that can be set: pattern and filter. + +Patterns: + +:diag5: diagonals separated by 5 tiles +:diag5r: diag5 rotated 90 degrees +:ladder: A 'ladder' pattern +:ladderr: ladder rotated 90 degrees +:clear: Just remove all dig designations +:cross: A cross, exactly in the middle of the map. + +Filters: + +:all: designate whole z-level +:hidden: designate only hidden tiles of z-level (default) +:designated: Take current designation and apply pattern to it. + +After you have a pattern set, you can use ``expdig`` to apply it again. + +Examples: + +``expdig diag5 hidden`` + Designate the diagonal 5 patter over all hidden tiles +``expdig`` + Apply last used pattern and filter +``expdig ladder designated`` + Take current designations and replace them with the ladder pattern + +digcircle +========= +A command for easy designation of filled and hollow circles. +It has several types of options. + +Shape: + +:hollow: Set the circle to hollow (default) +:filled: Set the circle to filled +:#: Diameter in tiles (default = 0, does nothing) + +Action: + +:set: Set designation (default) +:unset: Unset current designation +:invert: Invert designations already present + +Designation types: + +:dig: Normal digging designation (default) +:ramp: Ramp digging +:ustair: Staircase up +:dstair: Staircase down +:xstair: Staircase up/down +:chan: Dig channel + +After you have set the options, the command called with no options +repeats with the last selected parameters. + +Examples: + +``digcircle filled 3`` + Dig a filled circle with diameter = 3. +``digcircle`` + Do it again. + +digtype +======= +For every tile on the map of the same vein type as the selected tile, +this command designates it to have the same designation as the +selected tile. If the selected tile has no designation, they will be +dig designated. +If an argument is given, the designation of the selected tile is +ignored, and all appropriate tiles are set to the specified +designation. + +Options: + +:dig: +:channel: +:ramp: +:updown: up/down stairs +:up: up stairs +:down: down stairs +:clear: clear designation + +digFlood +======== +Automatically digs out specified veins as they are discovered. It runs once +every time a dwarf finishes a dig job. It will only dig out appropriate tiles +that are adjacent to the finished dig job. To add a vein type, use ``digFlood 1 [type]``. +This will also enable the plugin. To remove a vein type, use ``digFlood 0 [type] 1`` +to disable, then remove, then re-enable. + +Usage: + +:help digflood: detailed help message +:digFlood 0: disable the plugin +:digFlood 1: enable the plugin +:digFlood 0 MICROCLINE COAL_BITUMINOUS 1: + disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin +:digFlood CLEAR: remove all inorganics from monitoring +:digFlood digAll1: ignore the monitor list and dig any vein +:digFlood digAll0: disable digAll mode + +.. _feature: + feature ======= Enables management of map features. @@ -1823,14 +1808,34 @@ Options: :show X: Marks the selected map feature as discovered. :hide X: Marks the selected map feature as undiscovered. -.. _plugins/fortplan: +.. _filltraffic: + +filltraffic +=========== +Set traffic designations using flood-fill starting at the cursor. +See also `alltraffic`, `restrictice`, and `restrictliquid`. Options: + +:H: High Traffic +:N: Normal Traffic +:L: Low Traffic +:R: Restricted Traffic +:X: Fill across z-levels. +:B: Include buildings and stockpiles. +:P: Include empty space. + +Example: + +``filltraffic H`` + When used in a room with doors, it will set traffic to HIGH in just that room. + +.. _fortplan: fortplan ======== -Usage: fortplan [filename] +Usage: ``fortplan [filename]`` -Designates furniture for building according to a .csv file with -quickfort-style syntax. Companion to `scripts/digfort`. +Designates furniture for building according to a ``.csv`` file with +quickfort-style syntax. Companion to `digfort`. The first line of the file must contain the following:: @@ -1842,7 +1847,7 @@ is an optional description of where that is. You may also leave a description of the contents of the file itself following the closing parenthesis on the same line. -The syntax of the file itself is similar to `scripts/digfort` or +The syntax of the file itself is similar to `digfort` or `quickfort `_. At present, only buildings constructed of an item with the same name as the building are supported. All other characters are ignored. For example:: @@ -1855,10 +1860,28 @@ This section of a file would designate for construction a door and some furniture inside a bedroom: specifically, clockwise from top left, a cabinet, a table, a chair, a bed, and a statue. -All of the building designation uses Planning Mode, so you do not need to +All of the building designation uses `Planning Mode `, so you do not need to have the items available to construct all the buildings when you run fortplan with the .csv file. +getplants +========= +This tool allows plant gathering and tree cutting by RAW ID. Specify the types +of trees to cut down and/or shrubs to gather by their plant names, separated +by spaces. + +Options: + +:-t: Select trees only (exclude shrubs) +:-s: Select shrubs only (exclude trees) +:-c: Clear designations instead of setting them +:-x: Apply selected action to all plants except those specified (invert + selection) +:-a: Select every type of plant (obeys ``-t``/``-s``) + +Specifying both ``-t`` and ``-s`` will have no effect. If no plant IDs are specified, +all valid plant IDs will be listed. + infiniteSky =========== Automatically allocates new z-levels of sky at the top of the map as you build up, @@ -1871,33 +1894,30 @@ Usage: ``infiniteSky enable/disable`` Enables/disables monitoring of constructions. If you build anything in the second to highest z-level, it will allocate one more sky level. This is so you can continue to build stairs upward. - .. warning:: - - Bugs have been reported with this version of the plugin, so be careful. - It is possible that new z-levels will suddenly disappear and possibly - cause cave-ins. Saving and loading after creating new z-levels should - fix the problem. +:issue:`Sometimes <254>` new z-levels disappear and cause cave-ins. +Saving and loading after creating new z-levels should fix the problem. -.. _plugins/liquids: +.. _liquids: liquids ======= Allows adding magma, water and obsidian to the game. It replaces the normal dfhack command line and can't be used from a hotkey. Settings will be remembered as long as dfhack runs. Intended for use in combination with the command -``liquids-here`` (which can be bound to a hotkey). - -See also `this issue. `_ +``liquids-here`` (which can be bound to a hotkey). See also :issue:`80`. .. note:: - Spawning and deleting liquids can F up pathing data and + Spawning and deleting liquids can mess up pathing data and temperatures (creating heat traps). You've been warned. -Settings will be remembered until you quit DF. You can call liquids-here to execute +Settings will be remembered until you quit DF. You can call `liquids-here` to execute the last configured action, which is useful in combination with keybindings. -Usage: point the DF cursor at a tile you want to modify and use the commands available :) +Usage: point the DF cursor at a tile you want to modify and use the commands. + +If you only want to add or remove water or magma from one tile, +`source` may be easier to use. Commands -------- @@ -1941,6 +1961,8 @@ Brush size and shape: :column: Column from cursor, up through free space :flood: Flood-fill water tiles from cursor (only makes sense with wclean) +.. _liquids-here: + liquids-here ------------ Run the liquid spawner with the current/last settings made in liquids (if no @@ -1948,10 +1970,49 @@ settings in liquids were made it paints a point of 7/7 magma by default). Intended to be used as keybinding. Requires an active in-game cursor. +plant +===== +A tool for creating shrubs, growing, or getting rid of them. + +Subcommands: + +:create: Creates a new sapling under the cursor. Takes a raw ID as argument + (e.g. TOWER_CAP). The cursor must be located on a dirt or grass floor tile. +:grow: Turns saplings into trees; under the cursor if a sapling is selected, + or every sapling on the map if the cursor is hidden. +:extirpate: Kills the tree or shrub under the cursor, instantly turning them to ashes. +:immolate: Sets the plants on fire instead. The fires can and *will* spread ;) + +For mass effects, use one of the additional options: + +:shrubs: affect all shrubs on the map +:trees: affect all trees on the map +:all: affect every plant! + +regrass +======= +Regrows all the grass. Not much to it ;) + +.. _restrictice: + +restrictice +=========== +Restrict traffic on all tiles on top of visible ice. +See also `alltraffic`, `filltraffic`, and `restrictliquid`. + +.. _restrictliquid: + +restrictliquid +============== +Restrict traffic on all visible tiles with liquid. +See also `alltraffic`, `filltraffic`, and `restrictice`. + +.. _tiletypes: + tiletypes ========= Can be used for painting map tiles and is an interactive command, much like -liquids. +`liquids`. If something goes wrong, `fixveins` may help. The tool works with two set of options and a brush. The brush determines which tiles will be processed. First set of options is the filter, which can exclude @@ -2015,10 +2076,10 @@ Any paint or filter option (or the entire paint or filter) can be disabled entir You can use several different brushes for painting tiles: -* Point. (point) -* Rectangular range. (range) -* A column ranging from current cursor to the first solid tile above. (column) -* DF map block - 16x16 tiles, in a regular grid. (block) +:point: a single tile +:range: a rectangular range +:column: a column ranging from current cursor to the first solid tile above +:block: a DF map block - 16x16 tiles, in a regular grid Example:: @@ -2057,29 +2118,6 @@ Options: Beware that filling in hollow veins will trigger a demon invasion on top of your miner when you dig into the region that used to be hollow. -plant -===== -A tool for creating shrubs, growing, or getting rid of them. - -Subcommands: - -:create: Creates a new sapling under the cursor. Takes a raw ID as argument - (e.g. TOWER_CAP). The cursor must be located on a dirt or grass floor tile. -:grow: Turns saplings into trees; under the cursor if a sapling is selected, - or every sapling on the map if the cursor is hidden. -:extirpate: Kills the tree or shrub under the cursor, instantly turning them to ashes. -:immolate: Sets the plants on fire instead. The fires can and *will* spread ;) - -For mass effects, use one of the additional options: - -:shrubs: affect all shrubs on the map -:trees: affect all trees on the map -:all: affect every plant! - -regrass -======= -Regrows all the grass. Not much to it ;) - weather ======= Prints the current weather, and lets you change the weather to 'clear', 'rain' @@ -2091,13 +2129,41 @@ or 'snow', with those words as commands (eg ``weather rain``). Mods and Cheating ================= +.. _add-spatter: + +add-spatter +=========== +This plugin makes reactions with names starting with ``SPATTER_ADD_`` +produce contaminants on the items instead of improvements. The plugin is +intended to give some use to all those poisons that can be bought from caravans, +so they're immune to being washed away by water or destroyed by `clean`. + +.. _adv-bodyswap: + +adv-bodyswap +============ +This allows taking control over your followers and other creatures in adventure +mode. For example, you can make them pick up new arms and armor and equip them +properly. + +Usage: + +* When viewing unit details, body-swaps into that unit. +* In the main adventure mode screen, reverts transient swap. + +.. _catsplosion: + catsplosion =========== Makes cats just *multiply*. It is not a good idea to run this more than once or twice. +.. _createitem: + createitem ========== +Use `modtools/create-item` - this plugin is deprecated and will be removed soon. + Allows creating new items of arbitrary types and made of arbitrary materials. By default, items created are spawned at the feet of the selected unit. @@ -2105,7 +2171,8 @@ Specify the item and material information as you would indicate them in custom r * Separate the item and material with a space rather than a colon * If the item has no subtype, omit the :NONE -* If the item is REMAINS, FISH, FISH_RAW, VERMIN, PET, or EGG, specify a CREATURE:CASTE pair instead of a material token. +* If the item is REMAINS, FISH, FISH_RAW, VERMIN, PET, or EGG, + specify a CREATURE:CASTE pair instead of a material token. Corpses, body parts, and prepared meals cannot be created using this tool. @@ -2125,6 +2192,40 @@ Options: :building: Subsequent items will become part of the currently selected building. Good for loading traps; do not use with workshops (or deconstruct to use the item). +.. _diggingInvaders: + +diggingInvaders +=============== +Makes invaders dig or destroy constructions to get to your dwarves. + +To enable/disable the pluging, use: ``diggingInvaders (1|enable)|(0|disable)`` + +Basic usage: + +:add GOBLIN: registers the race GOBLIN as a digging invader. Case-sensitive. +:remove GOBLIN: unregisters the race GOBLIN as a digging invader. Case-sensitive. +:now: makes invaders try to dig now, if plugin is enabled +:clear: clears all digging invader races +:edgesPerTick n: makes the pathfinding algorithm work on at most n edges per tick. + Set to 0 or lower to make it unlimited. + +You can also use ``diggingInvaders setCost (race) (action) n`` to set the +pathing cost of particular action, or ``setDelay`` to set how long it takes. +Costs and delays are per-tile, and the table shows default values. + +============================== ======= ====== ================================= +Action Cost Delay Notes +============================== ======= ====== ================================= +``walk`` 1 0 base cost in the path algorithm +``destroyBuilding`` 2 1,000 delay adds to the job_completion_timer of destroy building jobs that are assigned to invaders +``dig`` 10,000 1,000 digging soil or natural stone +``destroyRoughConstruction`` 1,000 1,000 constructions made from boulders +``destroySmoothConstruction`` 100 100 constructions made from blocks or bars +============================== ======= ====== ================================= + + +.. _fastdwarf: + fastdwarf ========= Controls speedydwarf and teledwarf. Speedydwarf makes dwarves move quickly @@ -2138,7 +2239,9 @@ but do jobs at the same speed. :fastdwarf 0 1: disables speedydwarf and enables teledwarf :fastdwarf 1 1: enables both -.. _plugins/forceequip: +See `superdwarf` for a per-creature version. + +.. _forceequip: forceequip ========== @@ -2146,14 +2249,14 @@ Forceequip moves local items into a unit's inventory. It is typically used to equip specific clothing/armor items onto a dwarf, but can also be used to put armor onto a war animal or to add unusual items (such as crowns) to any unit. -For more information run ``forceequip help``. See also `scripts/modtools/equip-item`. +For more information run ``forceequip help``. See also `modtools/equip-item`. lair ==== This command allows you to mark the map as a monster lair, preventing item scatter on abandon. When invoked as ``lair reset``, it does the opposite. -Unlike `plugins/reveal`, this command doesn't save the information about tiles - you +Unlike `reveal`, this command doesn't save the information about tiles - you won't be able to restore state of real monster lairs using ``lair reset``. Options: @@ -2161,20 +2264,6 @@ Options: :lair: Mark the map as monster lair :lair reset: Mark the map as ordinary (not lair) -misery -====== -When enabled, every new negative dwarven thought will be multiplied by a factor (2 by default). - -Usage: - -:misery enable n: enable misery with optional magnitude n. If specified, n must be positive. -:misery n: same as "misery enable n" -:misery enable: same as "misery enable 2" -:misery disable: stop adding new negative thoughts. This will not remove existing - duplicated thoughts. Equivalent to "misery 1" -:misery clear: remove fake thoughts added in this session of DF. Saving makes them - permanent! Does not change factor. - mode ==== This command lets you see and change the game mode directly. @@ -2197,7 +2286,7 @@ Examples: * You switch to the adventure game mode, assume control of a creature, then save or retire. * You just created a returnable mountain home and gained an adventurer. -.. _plugins/strangemood: +.. _strangemood: strangemood =========== @@ -2220,73 +2309,32 @@ Options: Known limitations: if the selected unit is currently performing a job, the mood will not be started. +.. _siege-engine: -Behavior Mods -============= -These plugins, when activated via configuration UI or by detecting certain -structures in RAWs, modify the game engine behavior concerning the target -objects to add features not otherwise present. - -.. _plugins/siege-engine: - -Siege Engine ------------- -Siege engines are a very interesting feature, but sadly almost useless in the current state -because they haven't been updated since 2D and can only aim in four directions. This is an -attempt to bring them more up to date until Toady has time to work on it. Actual improvements, -e.g. like making siegers bring their own, are something only Toady can do. - -The siege-engine plugin enables siege engines to be linked to stockpiles, and -aimed at an arbitrary rectangular area across Z levels, instead of the original -four directions. Also, catapults can be ordered to load arbitrary objects, not -just stones. - -Configuration UI -~~~~~~~~~~~~~~~~ -The configuration front-end to the plugin is implemented by `scripts/gui/siege-engine`. -Bind it to a key (the example config uses Alt-A) and activate after selecting -a siege engine in ``q`` mode. - -.. image:: images/siege-engine.png - -The main mode displays the current target, selected ammo item type, linked stockpiles and -the allowed operator skill range. The map tile color is changed to signify if it can be -hit by the selected engine: green for fully reachable, blue for out of range, red for blocked, -yellow for partially blocked. - -Pressing ``r`` changes into the target selection mode, which works by highlighting two points -with Enter like all designations. When a target area is set, the engine projectiles are -aimed at that area, or units within it (this doesn't actually change the original aiming -code, instead the projectile trajectory parameters are rewritten as soon as it appears). - -After setting the target in this way for one engine, you can 'paste' the same area into others -just by pressing ``p`` in the main page of this script. The area to paste is kept until you quit -DF, or select another area manually. +siege-engine +============ +Siege engines in DF haven't been updated since the game was 2D, and can +only aim in four directions. This plugin allows you to: -Pressing ``t`` switches to a mode for selecting a stockpile to take ammo from. +* link siege engines to stockpiles +* load any object into a catapult, not just stones +* aim at a rectangular area in any direction, and across Z-levels -Exiting from the siege engine script via ESC reverts the view to the state prior to starting -the script. Shift-ESC retains the current viewport, and also exits from the ``q`` mode to main -menu. +The front-end is implemented by `gui/siege-engine`. -.. _plugins/power-meter: +.. _power-meter: -Power Meter ------------ +power-meter +=========== The power-meter plugin implements a modified pressure plate that detects power being supplied to gear boxes built in the four adjacent N/S/W/E tiles. -The configuration front-end is implemented by `scripts/gui/power-meter`. Bind it to a -key (the example config uses Ctrl-Shift-M) and activate after selecting Pressure Plate -in the build menu. +The configuration front-end is implemented by `gui/power-meter`. -.. image:: images/power-meter.png +.. _steam-engine: -The script follows the general look and feel of the regular pressure plate build -configuration page, but configures parameters relevant to the modded power meter building. - -Steam Engine ------------- +steam-engine +============ The steam-engine plugin detects custom workshops with STEAM_ENGINE in their token, and turns them into real steam engines. @@ -2295,42 +2343,33 @@ power, but windmills give relatively little power, and water wheels require flowing water, which must either be a real river and thus immovable and limited in supply, or actually flowing and thus laggy. -Steam engines are an alternative to water reactors that actually makes -sense, and hopefully doesn't lag. Also, unlike e.g. animal treadmills, -it can be done just by combining existing features of the game engine -in a new way with some glue code and a bit of custom logic. +Compared to the :wiki:`water reactor ` +exploit, steam engines make a lot of sense! Construction -~~~~~~~~~~~~ +------------ The workshop needs water as its input, which it takes via a passable floor tile below it, like usual magma workshops do. The magma version also needs magma. -.. admonition:: ISSUE - - Since this building is a machine, and machine collapse - code cannot be hooked, it would collapse over true open space. - As a loophole, down stair provides support to machines, while - being passable, so use them. +Due to DFHack limits, the workshop will collapse over true open space. +However down stairs are passable but support machines, so you can use them. After constructing the building itself, machines can be connected to the edge tiles that look like gear boxes. Their exact position is extracted from the workshop raws. -.. admonition:: ISSUE - - Like with collapse above, part of the code involved in - machine connection cannot be hooked. As a result, the workshop - can only immediately connect to machine components built AFTER it. - This also means that engines cannot be chained without intermediate - short axles that can be built later than both of the engines. +Like with collapse above, due to DFHack limits the workshop +can only immediately connect to machine components built AFTER it. +This also means that engines cannot be chained without intermediate +axles built after both engines. Operation -~~~~~~~~~ +--------- In order to operate the engine, queue the Stoke Boiler job (optionally on repeat). A furnace operator will come, possibly bringing a bar of fuel, and perform it. As a result, a "boiling water" item will appear -in the 't' view of the workshop. +in the :kbd:`t` view of the workshop. .. note:: @@ -2360,7 +2399,7 @@ decrease it by further 4%, and also decrease the whole steam use rate by 10%. Explosions -~~~~~~~~~~ +---------- The engine must be constructed using barrel, pipe and piston from fire-safe, or in the magma version magma-safe metals. @@ -2370,7 +2409,7 @@ toppled during operation by a building destroyer, or a tantruming dwarf. Save files -~~~~~~~~~~ +---------- It should be safe to load and view engine-using fortresses from a DF version without DFHack installed, except that in such case the engines won't work. However actually making modifications @@ -2379,16 +2418,3 @@ can easily result in inconsistent state once this plugin is available again. The effects may be as weird as negative power being generated. -add-spatter ------------ -This plugin makes reactions with names starting with ``SPATTER_ADD_`` -produce contaminants on the items instead of improvements. The produced -contaminants are immune to being washed away by water or destroyed by -the `plugins/clean` ``items`` command. - -The plugin is intended to give some use to all those poisons that can -be bought from caravans. :) - -To be really useful this needs patches from bug 808, `plugins/tweak` -``fix-dimensions`` and `plugins/tweak` ``advmode-contained``. - diff --git a/docs/Scripts.rst b/docs/Scripts.rst index bb5f108f3d..0e6ef415c7 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -2,1243 +2,16 @@ DFHack Scripts ############## -Lua or ruby scripts placed in the ``hack/scripts/`` directory are considered for -execution as if they were native DFHack commands. They are listed at the end -of the ``ls`` command output. - -Note: scripts in subdirectories of hack/scripts/ can still be called, but will -only be listed by ls if called as ``ls -a``. This is intended as a way to hide -scripts that are obscure, developer-oriented, or should be used as keybindings -or from the init file. - -``kill-lua`` stops any currently-running Lua scripts. By default, scripts can -only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt -the next instruction. - -.. contents:: - -================= -3rd-party scripts -================= - -This listing is autogenerated from ``.rst`` files in the 3rdparty scripts directory. - -.. warning:: - - Because this documentation is pulled in from external sources, - it may not match the DFHack distribution exactly. - - * Some scripts should have a prefix (eg listed as ``myscript``, - should be ``gui/myscript``) but don't. - * Some sections of documentation may refer to scripts which are - not distributed with DFHack. +Lua or ruby scripts placed in the :file:`hack/scripts/` directory +are considered for execution as if they were native DFHack commands. +The following pages document all the scripts in the DFHack standard library. .. toctree:: - :glob: :maxdepth: 2 - /scripts/3rdparty/*/* - - -======= -devel/* -======= -Scripts in this subdirectory are intended for developers, or still substantially -under development. If you don't already know what they do, best to leave them alone. - -================================================ -fix/* - scripts that fix bugs or common problems -================================================ -Scripts in this subdirectory fix various bugs and issues, some of them obscure. - -fix/blood-del -============= -Makes it so that future caravans won't bring barrels full of blood, ichor, or goo. - -fix/build-location -================== -Fixes construction jobs that are stuck trying to build a wall while standing -on the same exact tile (bug 5991), designates the tile restricted traffic to -hopefully avoid jamming it again, and unsuspends them. - -fix/dead-units -============== -Removes uninteresting dead units from the unit list. Doesn't seem to give any -noticeable performance gain, but migrants normally stop if the unit list grows -to around 3000 units, and this script reduces it back. - -fix/fat-dwarves -=============== -Avoids 5-10% FPS loss due to constant recalculation of insulation for dwarves at -maximum fatness, by reducing the cap from 1,000,000 to 999,999. - -fix/feeding-timers -================== -Reset the GiveWater and GiveFood timers of all units as appropriate. - -fix/growth-bug -============== -Fixes locally born units such that they will grow larger than their birth size. -Note that this bug was fixed in DF version 0.40.02. - -fix/item-occupancy -================== -Diagnoses and fixes issues with nonexistant 'items occupying site', usually -caused by autodump bugs or other hacking mishaps. - -fix/loyaltycascade -================== -Aborts loyalty cascades by fixing units whose own civ is the enemy. - -fix/population-cap -================== -Run this after every migrant wave to ensure your population cap is not exceeded. -The issue with the cap is that it is compared to the population number reported -by the last caravan, so once it drops below the cap, migrants continue to come -until that number is updated again. - -fix/stable-temp -=============== -Instantly sets the temperature of all free-lying items to be in equilibrium with -the environment and stops temperature updates. In order to maintain this efficient -state however, use `plugins/tweak` ``stable-temp`` and `plugins/tweak` ``fast-heat``. - -fix/stuckdoors -============== -Fix doors that are stuck open due to incorrect map occupancy flags, eg due to -incorrect use of teleport. - -======================================== -gui/* - scripts with an ingame interface -======================================== -Scripts that implement dialogs inserted into the main game window are put in this -directory. - -.. note:: - - In order to avoid user confusion, as a matter of policy all these tools - display the word "DFHack" on the screen somewhere while active. - - When that is not appropriate because they merely add keybinding hints to - existing DF screens, they deliberately use red instead of green for the key. - - -gui/advfort -=========== -This script allows to perform jobs in adventure mode. For more complete help -press '?' while script is running. It's most comfortable to use this as a -keybinding. (e.g. keybinding set Ctrl-T gui/advfort). Possible arguments: - -* -a or --nodfassign - uses different method to assign items. - -* -i or --inventory - checks inventory for possible items to use in the job. - -* -c or --cheat - relaxes item requirements for buildings (e.g. walls from bones). - implies -a - -* job - selects that job (e.g. Dig or FellTree) - -An example of player digging in adventure mode: - -.. image:: images/advfort.png - -.. admonition:: DISCLAIMER - - advfort changes only persist in non procedural sites. Namely: player forts, caves, camps. - -gui/advfort_items -================= -Does something with items in adventure mode jobs. - -.. _scripts/gui/assign-rack: - -gui/assign-rack -=============== -`This script requires a binpatch `, which has not -been available since DF 0.34.11 - -gui/autobutcher -=============== -An in-game interface for `plugins/autobutcher`. - -gui/choose-weapons -================== -Bind to a key (the example config uses Ctrl-W), and activate in the Equip->View/Customize -page of the military screen. - -Depending on the cursor location, it rewrites all 'individual choice weapon' entries -in the selected squad or position to use a specific weapon type matching the assigned -unit's top skill. If the cursor is in the rightmost list over a weapon entry, it rewrites -only that entry, and does it even if it is not 'individual choice'. - -Rationale: individual choice seems to be unreliable when there is a weapon shortage, -and may lead to inappropriate weapons being selected. - -gui/clone-uniform -================= -Bind to a key (the example config uses Ctrl-C), and activate in the Uniforms -page of the military screen with the cursor in the leftmost list. - -When invoked, the script duplicates the currently selected uniform template, -and selects the newly created copy. - -gui/companion-order -=================== -A script to issue orders for companions. Select companions with lower case chars, issue orders with upper -case. Must be in look or talk mode to issue command on tile. - -.. image:: images/companion-order.png - -* move - orders selected companions to move to location. If companions are following they will move no more than 3 tiles from you. -* equip - try to equip items on the ground. -* pick-up - try to take items into hand (also wield) -* unequip - remove and drop equipment -* unwield - drop held items -* wait - temporarily remove from party -* follow - rejoin the party after "wait" -* leave - remove from party (can be rejoined by talking) - -.. _scripts/gui/create-item: - -gui/create-item -=============== -A graphical interface for creating items. - -gui/dfstatus -============ -Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars. -Sections can be enabled/disabled/configured by editing ``dfhack-config/dfstatus.lua``. - -gui/gm-editor -============= -There are three ways to open this editor: - -* using gui/gm-editor command/keybinding - opens editor on what is selected - or viewed (e.g. unit/item description screen) - -* using gui/gm-editor - executes lua command and opens editor on - its results (e.g. gui/gm-editor "df.global.world.items.all" shows all items) - -* using gui/gm-editor dialog - shows an in game dialog to input lua command. Works - the same as version above. - -.. image:: images/gm-editor.png - -This editor allows to change and modify almost anything in df. Press '?' for an -in-game help. - -gui/gm-unit -=========== -An editor for various unit attributes. - -gui/guide-path -============== -Bind to a key (the example config uses Alt-P), and activate in the Hauling menu with -the cursor over a Guide order. - -.. image:: images/guide-path.png - -The script displays the cached path that will be used by the order; the game -computes it when the order is executed for the first time. - -gui/hack-wish -============= -An alias for `scripts/gui/create-item`. Deprecated. - -gui/hello-world -=============== -A basic example for testing, or to start your own script from. - -gui/liquids -=========== -To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mode. - -.. image:: images/liquids.png - -This script is a gui front-end to `plugins/liquids` and works similarly, -allowing you to add or remove water & magma, and create obsidian walls & floors. - -.. warning:: - - There is **no undo support**. Bugs in this plugin have been - known to create pathfinding problems and heat traps. - -The ``b`` key changes how the affected area is selected. The default *Rectangle* -mode works by selecting two corners like any ordinary designation. The ``p`` -key chooses between adding water, magma, obsidian walls & floors, or just -tweaking flags. - -When painting liquids, it is possible to select the desired level with ``+-``, -and choose between setting it exactly, only increasing or only decreasing -with ``s``. - -In addition, ``f`` allows disabling or enabling the flowing water computations -for an area, and ``r`` operates on the "permanent flow" property that makes -rivers power water wheels even when full and technically not flowing. - -After setting up the desired operations using the described keys, use ``Enter`` to apply them. - -gui/mechanisms -============== -To use, bind to a key (the example config uses Ctrl-M) and activate in the 'q' mode. - -.. image:: images/mechanisms.png - -Lists mechanisms connected to the building, and their links. Navigating the list centers -the view on the relevant linked buildings. - -To exit, press ESC or Enter; ESC recenters on the original building, while Enter leaves -focus on the current one. Shift-Enter has an effect equivalent to pressing Enter, and then -re-entering the mechanisms ui. - -gui/mod-manager -=============== -A simple way to install and remove small mods. - -It looks for specially formatted mods in df subfolder 'mods'. Mods are not -included, but some examples are `available here`_. - -.. _`available here`: https://github.com/warmist/df-mini-mods - -.. image:: images/mod-manager.png - -gui/no-dfhack-init -================== -Shows a warning at startup if no valid ``dfhack.init`` file is found. - -.. _scripts/gui/power-meter: - -gui/power-meter -=============== -An in-game interface for `plugins/power-meter`. - -.. _scripts/gui/rename: - -gui/rename -========== -Backed by `plugins/rename`, this script allows entering the desired name -via a simple dialog in the game ui. - -* ``gui/rename [building]`` in 'q' mode changes the name of a building. - - .. image:: images/rename-bld.png - - The selected building must be one of stockpile, workshop, furnace, trap, or siege engine. - It is also possible to rename zones from the 'i' menu. - -* ``gui/rename [unit]`` with a unit selected changes the nickname. - - Unlike the built-in interface, this works even on enemies and animals. - -* ``gui/rename unit-profession`` changes the selected unit's custom profession name. - - .. image:: images/rename-prof.png - - Likewise, this can be applied to any unit, and when used on animals it overrides - their species string. - -The ``building`` or ``unit`` options are automatically assumed when in relevant ui state. - -The example config binds building/unit rename to Ctrl-Shift-N, and -unit profession change to Ctrl-Shift-T. - -gui/room-list -============= -To use, bind to a key (the example config uses Alt-R) and activate in the 'q' mode, -either immediately or after opening the assign owner page. - -.. image:: images/room-list.png - -The script lists other rooms owned by the same owner, or by the unit selected in the assign -list, and allows unassigning them. - -.. _scripts/gui/siege-engine: - -gui/siege-engine -================ -An in-game interface for `plugins/siege-engine`. - -.. _scripts/gui/stockpiles: - -gui/stockpiles -============== -An in-game interface for `plugins/stocksettings`, to -load and save stockpile settings from the 'q' menu. - -Usage: - -:gui/stockpiles -save: to save the current stockpile -:gui/stockpiles -load: to load settings into the current stockpile -:gui/stockpiles -dir : set the default directory to save settings into -:gui/stockpiles -help: to see this message - -Don't forget to ``enable stockpiles`` and create the ``stocksettings`` directory in -the DF folder before trying to use the GUI. - -gui/unit-info-viewer -==================== -Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size, -and death info about a unit. Recommended keybinding Alt-I. - -.. _scripts/gui/workflow: - -gui/workflow -============ -Bind to a key (the example config uses Alt-W), and activate with a job selected -in a workshop in the 'q' mode. - -.. image:: images/workflow.png - -This script provides a simple interface to constraints managed by `plugins/workflow`. -When active, it displays a list of all constraints applicable to the -current job, and their current status. - -A constraint specifies a certain range to be compared against either individual -*item* or whole *stack* count, an item type and optionally a material. When the -current count is below the lower bound of the range, the job is resumed; if it -is above or equal to the top bound, it will be suspended. Within the range, the -specific constraint has no effect on the job; others may still affect it. - -Pressing 'I' switches the current constraint between counting stacks or items. -Pressing 'R' lets you input the range directly; 'e', 'r', 'd', 'f' adjust the -bounds by 5, 10, or 20 depending on the direction and the 'I' setting (counting -items and expanding the range each gives a 2x bonus). - -Pressing 'A' produces a list of possible outputs of this job as guessed by -workflow, and lets you create a new constraint by choosing one as template. If you -don't see the choice you want in the list, it likely means you have to adjust -the job material first using `plugins/job` ``item-material`` or `scripts/gui/workshop-job`, -as described in `plugins/workflow` documentation. In this manner, this feature -can be used for troubleshooting jobs that don't match the right constraints. - -.. image:: images/workflow-new1.png - -If you select one of the outputs with Enter, the matching constraint is simply -added to the list. If you use Shift-Enter, the interface proceeds to the -next dialog, which allows you to edit the suggested constraint parameters to -suit your need, and set the item count range. - -.. image:: images/workflow-new2.png - -Pressing 'S' (or, with the example config, Alt-W in the 'z' stocks screen) -opens the overall status screen, which was copied from the C++ implementation -by falconne for better integration with the rest of the lua script: - -.. image:: images/workflow-status.png - -This screen shows all currently existing workflow constraints, and allows -monitoring and/or changing them from one screen. The constraint list can -be filtered by typing text in the field below. - -The color of the stock level number indicates how "healthy" the stock level -is, based on current count and trend. Bright green is very good, green is good, -red is bad, bright red is very bad. - -The limit number is also color-coded. Red means that there are currently no -workshops producing that item (i.e. no jobs). If it's yellow, that means the -production has been delayed, possibly due to lack of input materials. - -The chart on the right is a plot of the last 14 days (28 half day plots) worth -of stock history for the selected item, with the rightmost point representing -the current stock value. The bright green dashed line is the target -limit (maximum) and the dark green line is that minus the gap (minimum). - -.. _scripts/gui/workshop-job: - -gui/workshop-job -================ -Bind to a key (the example config uses Alt-A), and activate with a job selected in -a workshop in the 'q' mode. - -.. image:: images/workshop-job.png - -The script shows a list of the input reagents of the selected job, and allows changing -them like the `plugins/job` ``item-type`` and `plugins/job` ``item-material`` commands. - -Specifically, pressing the 'i' key pops up a dialog that lets you select an item -type from a list. - -.. image:: images/workshop-job-item.png - -Pressing 'm', unless the item type does not allow a material, -lets you choose a material. - -.. image:: images/workshop-job-material.png - -Since there are a lot more materials than item types, this dialog is more complex -and uses a hierarchy of sub-menus. List choices that open a sub-menu are marked -with an arrow on the left. - -.. warning:: - - Due to the way input reagent matching works in DF, you must select an item type - if you select a material, or the material will be matched incorrectly in some cases. - If you press 'm' without choosing an item type, the script will auto-choose it - if there is only one valid choice, or pop up an error message box instead of the - material selection dialog. - -Note that both materials and item types presented in the dialogs are filtered -by the job input flags, and even the selected item type for material selection, -or material for item type selection. Many jobs would let you select only one -input item type. - -For example, if you choose a *plant* input item type for your prepare meal job, -it will only let you select cookable materials. - -If you choose a *barrel* item instead (meaning things stored in barrels, like -drink or milk), it will let you select any material, since in this case the -material is matched against the barrel itself. Then, if you select, say, iron, -and then try to change the input item type, now it won't let you select *plant*; -you have to unset the material first. - -.. _scripts/modtools: - -======================== -modtools/* - for modders -======================== -Scripts which provide tools for modders, often with changes to the raw files. -Not intended to be called manually by end-users. - -These scripts are mostly useful for raw modders and scripters. They all have -standard arguments: arguments are of the form ``tool -argName1 argVal1 --argName2 argVal2``. This is equivalent to ``tool -argName2 argVal2 -argName1 -argVal1``. It is not necessary to provide a value to an argument name: ``tool --argName3`` is fine. Supplying the same argument name multiple times will -result in an error. Argument names are preceded with a dash. The ``-help`` -argument will print a descriptive usage string describing the nature of the -arguments. For multiple word argument values, brackets must be used: ``tool --argName4 [ sadf1 sadf2 sadf3 ]``. In order to allow passing literal braces as -part of the argument, backslashes are used: ``tool -argName4 [ \] asdf \foo ]`` -sets ``argName4`` to ``\] asdf foo``. The ``*-trigger`` scripts have a similar -policy with backslashes. - -modtools/add-syndrome -===================== -This allows adding and removing syndromes from units. - -modtools/anonymous-script -========================= -This allows running a short simple Lua script passed as an argument instead of -running a script from a file. This is useful when you want to do something too -complicated to make with the existing modtools, but too simple to be worth its -own script file. - -modtools/create-item -==================== -This is mostly the same as the other create item tools, but it uses standard -arguments. The other versions will be phased out in a later version. - -modtools/create-unit -==================== -Creates a unit. - -.. _scripts/modtools/equip-item: - -modtools/equip-item -=================== -Force a unit to equip an item; useful in conjunction with the ``create`` -scripts above. - -See also `plugins/forceequip`. - -modtools/force -============== -This tool triggers events like megabeasts, caravans, invaders, and migrants. - -modtools/interaction-trigger -============================ -This triggers events when a unit uses an interaction on another. It works by -scanning the announcements for the correct attack verb, so the attack verb -must be specified in the interaction. It includes an option to suppress this -announcement after it finds it. - -modtools/invader-item-destroyer -=============================== -This tool configurably destroys invader items to prevent clutter or to prevent -the player from getting tools exclusive to certain races. - -modtools/item-trigger -===================== -This powerful tool triggers DFHack commands when a unit equips, unequips, or -attacks another unit with specified item types, specified item materials, or -specified item contaminants. - -modtools/moddable-gods -====================== -This is a standardized version of Putnam's moddableGods script. It allows you -to create gods on the command-line. - -modtools/outside-only -===================== -This allows you to specify certain custom buildings as outside only, or inside -only. If the player attempts to build a building in an inappropriate location, -the building will be destroyed. - -modtools/projectile-trigger -=========================== -This triggers dfhack commands when projectiles hit their targets. - -modtools/random-trigger -======================= -This triggers random dfhack commands with specified probabilities. - -modtools/reaction-product-trigger -================================= -This triggers dfhack commands when reaction products are produced, once per -product. - -modtools/reaction-trigger -========================= -Triggers dfhack commands when custom reactions complete, regardless of whether -it produced anything, once per completion. - -modtools/reaction-trigger-transition -==================================== -Scans raw files and creates a file to help modders transition from -autoSyndrome to reaction-trigger. - -modtools/skill-change -===================== -Sets or modifies a skill of a unit. - -modtools/spawn-flow -=================== -Creates flows at the specified location. - -modtools/syndrome-trigger -========================= -Triggers dfhack commands when syndromes are applied to units. - -modtools/transform-unit -======================= -Transforms a unit into another unit type, possibly permanently. - - -============= -Other Scripts -============= -These scripts are not stored in any subdirectory, and can be invoked directly. - -.. include:: ../scripts/include-all.rst - -add-thought -=========== -Adds a thought or emotion to the selected unit. Can be used by other scripts, -or the gui invoked by running ``add-thought gui`` with a unit selected. - -adaptation -========== -View or set level of cavern adaptation for the selected unit or the whole fort. -Usage: ``adaptation [value]``. The ``value`` must be -between 0 and 800,000 inclusive. - -armoks-blessing -=============== -Runs the equivalent of `scripts/rejuvenate`, `scripts/elevate-physical`, -`scripts/elevate-mental`, and `scripts/brainwash` -on all dwarves currently on the map. This is an extreme change, which sets every -stat to an ideal - legendary skills, great traits, and easy-to-satisfy preferences. -Use in moderation; it's as 'cheaty' as DFHack gets. - -autofarm -======== -Automatically handle crop selection in farm plots based on current plant stocks. -Selects a crop for planting if current stock is below a threshold. -Selected crops are dispatched on all farmplots. - -Usage:: - - autofarm start - autofarm default 30 - autofarm threshold 150 helmet_plump tail_pig - -.. _scripts/autolabor-artisans: - -autolabor-artisans -================== -Runs `plugins/autolabor`, with settings tuned for small but highly skilled workforces. - -.. _scripts/autounsuspend: - -autounsuspend -============= -Automatically unsuspend jobs in workshops, on a recurring basis. -See `scripts/unsuspend` for one-off use, or `plugins/resume` ``all``. - -ban-cooking -=========== -A more convenient way to ban cooking various categories of foods than the -kitchen interface. Usage: ``ban-cooking ``. Valid types are ``booze``, -``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds). - -.. _scripts/binpatch: - -binpatch -======== -Implements functions for in-memory binpatches. See `binpatches`. - -.. _scripts/brainwash: - -brainwash -========= -Modify the personality traits of the selected dwarf to match an 'ideal' -personality - as stable and reliable as possible. This makes dwarves very -stable, preventing tantrums even after months of misery. - -burial -====== -Sets all unowned coffins to allow burial. ``burial -pets`` also allows burial -of pets. - -command-prompt -============== -A one line command prompt in df. Same as entering command into dfhack console. Best -used as a keybinding. Can be called with optional "entry" that will start prompt with -that pre-filled. - -.. image:: images/command-prompt.png - -create-items -============ -Spawn arbitrary items under the cursor. - -The first argument gives the item category, the second gives the material, -and the optionnal third gives the number of items to create (defaults to 20). - -Currently supported item categories: ``boulder``, ``bar``, ``plant``, ``log``, -``web``. - -Instead of material, using ``list`` makes the script list eligible materials. - -The ``web`` item category will create an uncollected cobweb on the floor. - -Note that the script does not enforce anything, and will let you create -boulders of toad blood and stuff like that. -However the ``list`` mode will only show 'normal' materials. - -Examples:: - - create-items boulders COAL_BITUMINOUS 12 - create-items plant tail_pig - create-items log list - create-items web CREATURE:SPIDER_CAVE_GIANT:SILK - create-items bar CREATURE:CAT:SOAP - create-items bar adamantine - -deathcause -========== -Focus a body part ingame, and this script will display the cause of death of -the creature. -Also works when selecting units from the (``u``) unitlist viewscreen. - -dfusion -======= -Interface to a lecacy script system. - -.. _scripts/digfort: - -digfort -======= -A script to designate an area for digging according to a plan in csv format. - -This script, inspired from quickfort, can designate an area for digging. -Your plan should be stored in a .csv file like this:: - - # this is a comment - d;d;u;d;d;skip this tile;d - d;d;d;i - -Available tile shapes are named after the 'dig' menu shortcuts: -``d`` for dig, ``u`` for upstairs, ``d`` downstairs, ``i`` updown, -``h`` channel, ``r`` upward ramp, ``x`` remove designation. -Unrecognized characters are ignored (eg the 'skip this tile' in the sample). - -Empty lines and data after a ``#`` are ignored as comments. -To skip a row in your design, use a single ``;``. - -One comment in the file may contain the phrase ``start(3,5)``. It is interpreted -as an offset for the pattern: instead of starting at the cursor, it will start -3 tiles left and 5 tiles up from the cursor. - -The script takes the plan filename, starting from the root df folder (where -``Dwarf Fortress.exe`` is found). - -drain-aquifer -============= -Remove all 'aquifer' tag from the map blocks. Irreversible. - -.. _scripts/elevate-mental: - -elevate-mental -============== -Set all mental attributes of a dwarf to 2600, which is very high. -Other numbers can be passed as an argument: ``elevate-mental 100`` -for example would make the dwarf very stupid indeed. - -.. _scripts/elevate-physical: - -elevate-physical -================ -As for elevate-mental, but for physical traits. High is good for soldiers, -while having an ineffective hammerer can be useful too... - -exportlegends -============= -Controls legends mode to export data - especially useful to set-and-forget large -worlds, or when you want a map of every site when there are several hundred. - -The 'info' option exports more data than is possible in vanilla, to a -``region-date-legends_plus.xml`` file developed to extend the World -Viewer utility and potentially compatible with others. - -Options: - -:info: Exports the world/gen info, the legends XML, and a custom XML with more information -:sites: Exports all available site maps -:maps: Exports all seventeen detailed maps -:all: Equivalent to calling all of the above, in that order - -exterminate -=========== -Kills any unit of a given race. - -With no argument, lists the available races and count eligible targets. - -With the special argument ``him``, targets only the selected creature. - -With the special argument ``undead``, targets all undeads on the map, -regardless of their race. - -When specifying a race, a caste can be specified to further restrict the -targeting. To do that, append and colon and the caste name after the race. - -Any non-dead non-caged unit of the specified race gets its ``blood_count`` -set to 0, which means immediate death at the next game tick. For creatures -such as vampires, it also sets animal.vanish_countdown to 2. - -An alternate mode is selected by adding a 2nd argument to the command, -``magma``. In this case, a column of 7/7 magma is generated on top of the -targets until they die (Warning: do not call on magma-safe creatures. Also, -using this mode on birds is not recommended.) - -Will target any unit on a revealed tile of the map, including ambushers, -but ignore caged/chained creatures. - -Ex:: - - exterminate gob - exterminate gob:male - -To kill a single creature, select the unit with the 'v' cursor and:: - - exterminate him - -To purify all elves on the map with fire (may have side-effects):: - - exterminate elve magma - -fixnaked -======== -Removes all unhappy thoughts due to lack of clothing. - -.. _scripts/fix-ster: - -fix-ster -======== -Utilizes the orientation tag to either fix infertile creatures or inflict -infertility on creatures that you do not want to breed. Usage:: - - fix-ster [fert|ster] [all|animals|only:] - -``fert`` or ``ster`` is a required argument; whether to make the target fertile -or sterile. Optional arguments specify the target: no argument for the -selected unit, ``all`` for all units on the map, ``animals`` for all non-dwarf -creatures, or ``only:`` to only process matching creatures. - -forum-dwarves -============= -Saves a copy of a text screen, formatted in bbcode for posting to the Bay12 Forums. -Use ``forum-dwarves help`` for more information. - -full-heal -========= -Attempts to fully heal the selected unit. ``full-heal -r`` attempts to resurrect the unit. - -gaydar -====== -Shows the sexual orientation of units, useful for social engineering or checking -the viability of livestock breeding programs. Use ``gaydar -help`` for information -on available filters for orientation, citizenship, species, etc. - -growcrops -========= -Instantly grow seeds inside farming plots. - -With no argument, this command list the various seed types currently in -use in your farming plots. -With a seed type, the script will grow 100 of these seeds, ready to be -harvested. You can change the number with a 2nd argument. - -For example, to grow 40 plump helmet spawn:: - - growcrops plump 40 - -hfs-pit -======= -Creates a pit to the underworld at the cursor. - -Takes three arguments: diameter of the pit in tiles, whether to wall off -the pit, and whether to insert stairs. If no arguments are given, the default -is "hfs-pit 1 0 0", ie single-tile wide with no walls or stairs.:: - - hfs-pit 4 0 1 - hfs-pit 2 1 0 - -First example is a four-across pit with stairs but no walls; second is a -two-across pit with stairs but no walls. - -hotkey-notes -============ -Lists the key, name, and jump position of your hotkeys in the DFHack console. - -item-descriptions -================= -Exports a table with custom description text for every item in the game. -Used by `scripts/view-item-info`. - -lever -===== -Allow manipulation of in-game levers from the dfhack console. - -Can list levers, including state and links, with:: - - lever list - -To queue a job so that a dwarf will pull the lever 42, use ``lever pull 42``. -This is the same as 'q'uerying the building and queue a 'P'ull request. - -To magically toggle the lever immediately, use:: - - lever pull 42 --now - -locate-ore -========== -Scan the map for metal ores. - -Finds and designate for digging one tile of a specific metal ore. -Only works for native metal ores, does not handle reaction stuff (eg STEEL). - -When invoked with the ``list`` argument, lists metal ores available on the map. - -Examples:: - - locate-ore list - locate-ore hematite - locate-ore iron - -log-region -========== -When enabled in dfhack.init, each time a fort is loaded identifying information -will be written to the gamelog. Assists in parsing the file if you switch -between forts, and adds information for story-building. - -lua -=== -There are the following ways to invoke this command: - -1. ``lua`` (without any parameters) - - This starts an interactive lua interpreter. - -2. ``lua -f "filename"`` or ``lua --file "filename"`` - - This loads and runs the file indicated by filename. - -3. ``lua -s ["filename"]`` or ``lua --save ["filename"]`` - - This loads and runs the file indicated by filename from the save - directory. If the filename is not supplied, it loads "dfhack.lua". - -4. ``:lua`` *lua statement...* - - Parses and executes the lua statement like the interactive interpreter would. - -make-legendary -============== -Makes the selected dwarf legendary in one skill, a group of skills, or all -skills. View groups with ``make-legendary classes``, or all skills with -``make-legendary list``. Use ``make-legendary MINING`` when you need something -dug up, or ``make-legendary all`` when only perfection will do. - -make-monarch -============ -Make the selected unit King or Queen of your civilisation. - -markdown -======== -Save a copy of a text screen in markdown (for reddit among others). -Use 'markdown help' for more details. - -masspit -======= -Designate all creatures in cages on top of a pit/pond activity zone for pitting. -Works best with an animal stockpile on top of the zone. - -Works with a zone number as argument (eg ``Activity Zone #6`` -> ``masspit 6``) -or with the game cursor on top of the area. - -multicmd -======== -Run multiple dfhack commands. The argument is split around the -character ; and all parts are run sequentially as independent -dfhack commands. Useful for hotkeys. - -Example:: - - multicmd locate-ore iron ; digv - -points -====== -Sets available points at the embark screen to the specified number. Eg. -``points 1000000`` would allow you to buy everything, or ``points 0`` would -make life quite difficult. - -position -======== -Reports the current time: date, clock time, month, and season. Also reports -location: z-level, cursor position, window size, and mouse location. - -pref-adjust -=========== -A two-stage script: ``pref-adjust clear`` removes preferences from all dwarves, -and ``pref-adjust`` inserts an 'ideal' set which is easy to satisfy:: - - Feb Idashzefon likes wild strawberries for their vivid red color, fisher berries - for their round shape, prickle berries for their precise thorns, plump helmets - for their rounded tops, prepared meals, plants, drinks, doors, thrones, tables and - beds. When possible, she prefers to consume wild strawberries, fisher berries, - prickle berries, plump helmets, strawberry wine, fisher berry wine, prickle berry - wine, and dwarven wine. - -putontable -========== -Makes item appear on the table, like in adventure mode shops. Arguments: '-a' -or '--all' for all items. - -quicksave -========= -If called in dwarf mode, makes DF immediately auto-save the game by setting a flag -normally used in seasonal auto-save. - -region-pops -=========== -Show or modify the populations of animals in the region. - -Usage: - -:region-pops list [pattern]: - Lists encountered populations of the region, possibly restricted by pattern. -:region-pops list-all [pattern]: - Lists all populations of the region. -:region-pops boost : - Multiply all populations of TOKEN by factor. - If the factor is greater than one, increases the - population, otherwise decreases it. -:region-pops boost-all : - Same as above, but match using a pattern acceptable to list. -:region-pops incr : - Augment (or diminish) all populations of TOKEN by factor (additive). -:region-pops incr-all : - Same as above, but match using a pattern acceptable to list. - -.. _scripts/rejuvenate: - -rejuvenate -========== -Set the age of the selected dwarf to 20 years. Useful if valuable citizens are -getting old, or there are too many babies around... - -remove-stress -============= -Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or -very stressed dwarves taking on negative or greater values respectively. -Applies to the selected unit, or use "remove-stress -all" to apply to all units. - -remove-wear -=========== -Sets the wear on all items in your fort to zero. - -.. _scripts/repeat: - -repeat -====== -Repeatedly calls a lua script at the specified interval. - -This allows neat background changes to the function of the game, especially when -invoked from an init file. For detailed usage instructions, use ``repeat -help``. - -Usage examples:: - - repeat -name jim -time delay -timeUnits units -printResult true -command [ printArgs 3 1 2 ] - repeat -time 1 -timeUnits months -command [ multicmd cleanowned scattered x; clean all ] -name clean - -The first example is abstract; the second will regularly remove all contaminants -and worn items from the game. - -``-name`` sets the name for the purposes of cancelling and making sure you don't schedule the -same repeating event twice. If not specified, it's set to the first argument after ``-command``. -``-time delay -timeUnits units``; delay is some positive integer, and units is some valid time -unit for ``dfhack.timeout(delay,timeUnits,function)``. ``-command [ ... ]`` specifies the -command to be run. - -setfps -====== -Run ``setfps `` to set the FPS cap at runtime, in case you want to watch -combat in slow motion or something :) - -show-unit-syndromes -=================== -Show syndromes affecting units and the remaining and maximum duration, along -with (optionally) substantial detail on the effects. - -Use one or more of the following options: - -:showall: Show units even if not affected by any syndrome -:showeffects: Show detailed effects of each syndrome -:showdisplayeffects: Show effects that only change the look of the unit -:ignorehiddencurse: Hide syndromes the user should not be able to know about (TODO) -:selected: Show selected unit -:dwarves: Show dwarves -:livestock: Show livestock -:wildanimals: Show wild animals -:hostile: Show hostiles (e.g. invaders, thieves, forgotten beasts etc) -:world: Show all defined syndromes in the world -:export: ``export:`` sends output to the given file, showing all - syndromes affecting each unit with the maximum and present duration. - -siren -===== -Wakes up sleeping units, cancels breaks and stops parties either everywhere, -or in the burrows given as arguments. In return, adds bad thoughts about -noise, tiredness and lack of protection. Also, the units with interrupted -breaks will go on break again a lot sooner. The script is intended for -emergencies, e.g. when a siege appears, and all your military is partying. - -soundsense-season -================= -It is a well known issue that Soundsense cannot detect the correct -current season when a savegame is loaded and has to play random -season music until a season switch occurs. - -This script registers a hook that prints the appropriate string -to gamelog.txt on every map load to fix this. For best results -call the script from ``dfhack.init``. - -source -====== -Create an infinite magma or water source or drain on a tile. - -This script registers a map tile as a liquid source, and every 12 game ticks -that tile receives or remove 1 new unit of flow based on the configuration. - -Place the game cursor where you want to create the source (must be a -flow-passable tile, and not too high in the sky) and call:: - - source add [magma|water] [0-7] - -The number argument is the target liquid level (0 = drain, 7 = source). - -To add more than 1 unit everytime, call the command again on the same spot. - -To delete one source, place the cursor over its tile and use ``source delete``. -To remove all existing sources, call ``source clear``. - -The ``list`` argument shows all existing sources. - -Examples:: - - source add water - water source - source add magma 7 - magma source - source add water 0 - water drain - -startdwarf -========== -Use at the embark screen to embark with the specified number of dwarves. Eg. -``startdwarf 500`` would lead to a severe food shortage and FPS issues, while -``startdwarf 10`` would just allow a few more warm bodies to dig in. -The number must be 7 or greater. - -stripcaged -========== -For dumping items inside cages. Will mark selected items for dumping, then -a dwarf may come and actually dump it. See also `plugins/autodump`. - -With the ``items`` argument, only dumps items laying in the cage, excluding -stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor`` -will dump everything worn by caged creatures (including armor and clothing), -and ``all`` will dump everything, on a creature or not. - -``stripcaged list`` will display on the dfhack console the list of all cages -and their item content. - -Without further arguments, all commands work on all cages and animal traps on -the map. With the ``here`` argument, considers only the in-game selected cage -(or the cage under the game cursor). To target only specific cages, you can -alternatively pass cage IDs as arguments:: - - stripcaged weapons 25321 34228 - -superdwarf -========== -Similar to fastdwarf, per-creature. - -To make any creature superfast, target it ingame using 'v' and:: - - superdwarf add - -Other options available: ``del``, ``clear``, ``list``. - -This script also shortens the 'sleeping' and 'on break' periods of targets. - -teleport -======== -Teleports a unit to given coordinates. - -Examples:: - - teleport -showunitid - prints unitid beneath cursor - teleport -showpos - prints coordinates beneath cursor - teleport -unit 1234 -x 56 -y 115 -z 26 - teleports unit 1234 to 56,115,26 - -undump-buildings -================ -Undesignates building base materials for dumping. - -.. _scripts/unsuspend: - -unsuspend -========= -Unsuspend jobs in workshops, on a one-off basis. See `scripts/autounsuspend` -for regular use. - -.. _scripts/view-item-info: - -view-item-info -============== -A script to extend the item or unit viewscreen with additional information -including a custom description of each item (when available), and properties -such as material statistics, weapon attacks, armor effectiveness, and more. - -The associated script ``item-descriptions.lua`` supplies custom descriptions -of items. Individual descriptions can be added or overridden by a similar -script ``raw/scripts/more-item-descriptions.lua``. Both work as sparse lists, -so missing items simply go undescribed if not defined in the fallback. - -warn-starving -============= -If any (live) units are starving, very thirsty, or very drowsy, the game will -be paused and a warning shown and logged to the console. Use with the -`scripts/repeat` command for regular checks. - -Use ``warn-starving all`` to display a list of all problematic units. + /docs/_auto/base + /docs/_auto/devel + /docs/_auto/fix + /docs/_auto/gui + /docs/_auto/modtools diff --git a/docs/images/family-affairs.png b/docs/images/family-affairs.png new file mode 100644 index 0000000000..faf59390eb Binary files /dev/null and b/docs/images/family-affairs.png differ diff --git a/docs/styles/cp437.ttf b/docs/styles/cp437.ttf new file mode 100644 index 0000000000..f0f10a6982 Binary files /dev/null and b/docs/styles/cp437.ttf differ diff --git a/docs/images/dfhack-icon.ico b/docs/styles/dfhack-icon.ico similarity index 100% rename from docs/images/dfhack-icon.ico rename to docs/styles/dfhack-icon.ico diff --git a/docs/styles/dfhack.css b/docs/styles/dfhack.css new file mode 100644 index 0000000000..67f75b3b1e --- /dev/null +++ b/docs/styles/dfhack.css @@ -0,0 +1,40 @@ +/* make sure to sync this with the base theme's css filename */ +@import url("alabaster.css"); + +.kbd { +/* Keybinding CSS from the DF wiki; applies to :kbd:`` directives. + * Use this directive for all keypresses, to make them look like keys. + */ + border: 1px solid #aaa; + border-radius: 0.2em; + -webkit-border-radius: 0.2em; + -moz-border-radius: 0.2em; + -o-border-radius: 0.2em; -ms-border-radius: 0.2em; + -moz-box-shadow: 0.1em 0.2em 0.2em #ddd; + -webkit-box-shadow: 0.1em 0.2em 0.2em #ddd; + box-shadow: 0.1em 0.2em 0.2em #ddd; + background-color: #f9f9f9; + background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); + background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); + background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); + background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); + padding: 0.1em 0.3em; + font-family: sans-serif; + font-size: 0.8em; +} + +@font-face { + font-family: cp437; + src: url("cp437.ttf"); +} + +.guilabel { +/* In-game text CSS from the DF wiki; applies to :guilabel:`` directives. + * Use this for any text from an in-game announcement or menu. + */ + color: #CBC7C0; + font-family: cp437, 'fixedsys', monospace; + background: #000000; + font-size: 0.95em; + padding: 0.05em 0.4em; +} diff --git a/README.rst b/index.rst similarity index 55% rename from README.rst rename to index.rst index 97ac6b36ed..de587e95af 100644 --- a/README.rst +++ b/index.rst @@ -1,18 +1,26 @@ +################################## Welcome to DFHack's documentation! -================================== +################################## Introduction ============ -DFHack is a Dwarf Fortress memory access library, distributed with scripts -and plugins implementing a wide variety of useful functions and tools. +DFHack is a Dwarf Fortress memory access library, distributed with +a wide variety of useful scripts and plugins. + +The project is currently hosted at https://www.github.com/DFHack/dfhack, +and can be downloaded from `the releases page +`_. + +All new releases are announced in :forums:`the bay12 forums thread <139553>`, +which is also a good place for discussion and questions. For users, it provides a significant suite of bugfixes and interface enhancements by default, and more can be enabled. There are also many tools -(such as `plugins/workflow` or `plugins/autodump`) which can make life easier. +(such as `workflow` or `autodump`) which can make life easier. You can even add third-party scripts and plugins to do almost anything! For modders, DFHack makes many things possible. Custom reactions, new -interactions, magic creature abilities, and more can be set through `scripts ` +interactions, magic creature abilities, and more can be set through `modtools` and custom raws. Non-standard DFHack scripts and inits can be stored in the raw directory, making raws or saves fully self-contained for distribution - or for coexistence in a single DF install, even with incompatible components. @@ -22,38 +30,36 @@ allows easier development of new tools. As an open-source project under `various copyleft licences `, contributions are welcome. -Documentation -============= -DFHack documentation is generated by Sphinx. Check out the table of contents -below, or the sources in the `docs folder`_! - -.. _`docs folder`: ./docs - -User Manual: +User Manual +=========== .. toctree:: :maxdepth: 2 - docs/Core - docs/Plugins - docs/Scripts + /docs/Introduction + /docs/Core + /docs/Plugins + /docs/Scripts -Other Contents: +Other Contents +============== .. toctree:: :maxdepth: 1 - docs/Authors - docs/Licenses - docs/Changelog + /docs/Authors + /LICENSE + /NEWS -For Developers: +For Developers +============== .. toctree:: :maxdepth: 1 - docs/Contributing - docs/Compile - docs/Lua API - library/xml/SYNTAX - docs/Binpatches + /docs/Contributing + /docs/Compile + /docs/Lua API + /library/xml/SYNTAX + /library/xml/how-to-update + /docs/Binpatches diff --git a/library/Core.cpp b/library/Core.cpp index 2d537c1b35..130ec222db 100644 --- a/library/Core.cpp +++ b/library/Core.cpp @@ -553,7 +553,6 @@ string getBuiltinCommand(std::string cmd) cmd == "enable" || cmd == "disable" || cmd == "plug" || - cmd == "type" || cmd == "keybinding" || cmd == "fpause" || cmd == "cls" || diff --git a/library/Hooks-linux.cpp b/library/Hooks-linux.cpp index 31c0323f6c..b0bf5a7817 100644 --- a/library/Hooks-linux.cpp +++ b/library/Hooks-linux.cpp @@ -114,7 +114,8 @@ static int (*_SDL_Init)(uint32_t flags) = 0; DFhackCExport int SDL_Init(uint32_t flags) { // reroute stderr - freopen("stderr.log", "w", stderr); + if (!freopen("stderr.log", "w", stderr)) + fprintf(stderr, "dfhack: failed to reroute stderr\n"); // we don't reroute stdout until we figure out if this should be done at all // See: Console-linux.cpp diff --git a/library/LuaWrapper.cpp b/library/LuaWrapper.cpp index 1ce405c297..214caa4cd0 100644 --- a/library/LuaWrapper.cpp +++ b/library/LuaWrapper.cpp @@ -1310,6 +1310,18 @@ static int wtype_ipairs(lua_State *state) return 3; } +static int wtype_next_item(lua_State *state) +{ + int first = lua_tointeger(state, lua_upvalueindex(1)), + last = lua_tointeger(state, lua_upvalueindex(2)), + cur = luaL_checkint(state, lua_gettop(state) > 1 ? 2 : 1); // 'self' optional + if (cur < last) + lua_pushinteger(state, cur + 1); + else + lua_pushinteger(state, first); + return 1; +} + static void RenderTypeChildren(lua_State *state, const std::vector &children); void LuaWrapper::AssociateId(lua_State *state, int table, int val, const char *name) @@ -1347,6 +1359,11 @@ static void FillEnumKeys(lua_State *state, int ix_meta, int ftable, enum_identit lua_pushcclosure(state, wtype_ipairs, 3); lua_setfield(state, ix_meta, "__ipairs"); + lua_pushinteger(state, eid->getFirstItem()); + lua_pushinteger(state, eid->getLastItem()); + lua_pushcclosure(state, wtype_next_item, 2); + lua_setfield(state, ftable, "next_item"); + lua_pushinteger(state, eid->getFirstItem()); lua_setfield(state, ftable, "_first_item"); diff --git a/library/include/modules/Constructions.h b/library/include/modules/Constructions.h index 41959b2d72..3831d4bb18 100644 --- a/library/include/modules/Constructions.h +++ b/library/include/modules/Constructions.h @@ -59,6 +59,7 @@ DFHACK_EXPORT bool isValid(); DFHACK_EXPORT uint32_t getCount(); DFHACK_EXPORT bool copyConstruction (const int32_t index, t_construction &out); DFHACK_EXPORT df::construction * getConstruction (const int32_t index); +DFHACK_EXPORT df::construction * findAtTile(df::coord pos); DFHACK_EXPORT bool designateNew(df::coord pos, df::construction_type type, df::item_type item = df::item_type::NONE, int mat_index = -1); diff --git a/library/modules/Constructions.cpp b/library/modules/Constructions.cpp index 16c1f1b892..98410c3310 100644 --- a/library/modules/Constructions.cpp +++ b/library/modules/Constructions.cpp @@ -68,6 +68,15 @@ df::construction * Constructions::getConstruction(const int32_t index) return world->constructions[index]; } +df::construction * Constructions::findAtTile(df::coord pos) +{ + for (auto it = world->constructions.begin(); it != world->constructions.end(); ++it) { + if ((*it)->pos == pos) + return *it; + } + return NULL; +} + bool Constructions::copyConstruction(const int32_t index, t_construction &out) { if (uint32_t(index) >= getCount()) diff --git a/library/xml b/library/xml index dc76bf4247..378a580f7e 160000 --- a/library/xml +++ b/library/xml @@ -1 +1 @@ -Subproject commit dc76bf4247b78cf2525bf60a62553dadd42ca696 +Subproject commit 378a580f7e333607a64a301d598e3885954a5d9d diff --git a/plugins/CMakeLists.txt b/plugins/CMakeLists.txt index 0cb8b6df29..115f6196e1 100644 --- a/plugins/CMakeLists.txt +++ b/plugins/CMakeLists.txt @@ -133,7 +133,6 @@ if (BUILD_SUPPORTED) DFHACK_PLUGIN(getplants getplants.cpp) DFHACK_PLUGIN(hotkeys hotkeys.cpp) DFHACK_PLUGIN(infiniteSky infiniteSky.cpp) - DFHACK_PLUGIN(initflags initflags.cpp) DFHACK_PLUGIN(isoworldremote isoworldremote.cpp PROTOBUFS isoworldremote) DFHACK_PLUGIN(jobutils jobutils.cpp) DFHACK_PLUGIN(lair lair.cpp) diff --git a/plugins/advtools.cpp b/plugins/advtools.cpp index 8f613d1cc9..77cc029340 100644 --- a/plugins/advtools.cpp +++ b/plugins/advtools.cpp @@ -41,6 +41,17 @@ using df::nemesis_record; using df::historical_figure; using namespace DFHack::Translation; +/* +advtools +======== +A package of different adventure mode tools. Usage: + +:list-equipped [all]: List armor and weapons equipped by your companions. + If all is specified, also lists non-metal clothing. +:metal-detector [all-types] [non-trader]: + Reveal metal armor and weapons in shops. The options + disable the checks on item type and being in shop. +*/ DFHACK_PLUGIN("advtools"); REQUIRE_GLOBAL(world); diff --git a/plugins/automaterial.cpp b/plugins/automaterial.cpp index 56b94483b5..60ccdd52a7 100644 --- a/plugins/automaterial.cpp +++ b/plugins/automaterial.cpp @@ -32,6 +32,7 @@ #include "modules/Constructions.h" #include "modules/Buildings.h" #include "modules/Maps.h" +#include "modules/MapCache.h" #include "TileTypes.h" #include "df/job_item.h" @@ -455,24 +456,14 @@ static bool is_valid_building_site(building_site &site, bool orthogonal_check, b } else { - if (shape_basic != tiletype_shape_basic::Floor) + if (shape != tiletype_shape::STAIR_DOWN && shape_basic != tiletype_shape_basic::Floor) return false; - if (material == tiletype_material::CONSTRUCTION) + // Can build on top of a wall, but not on other construction + auto construction = Constructions::findAtTile(site.pos); + if (construction) { - // Can build on top of a wall, but not on a constructed floor - df::coord pos_below = site.pos; - pos_below.z--; - if (!Maps::isValidTilePos(pos_below)) - return false; - - auto ttype = Maps::getTileType(pos_below); - if (!ttype) - return false; - - auto shape = tileShape(*ttype); - auto shapeBasic = tileShapeBasic(shape); - if (tileShapeBasic(shape) != tiletype_shape_basic::Wall) + if (construction->flags.bits.top_of_wall==0) return false; } @@ -1129,7 +1120,7 @@ struct jobutils_hook : public df::viewscreen_dwarfmodest { ++y; OutputString(COLOR_BROWN, x, y, "Construction:", true, left_margin); - OutputString(COLOR_WHITE, x, y, int_to_string(valid_building_sites.size() + 1) + " tiles to fill", true, left_margin); + OutputString(COLOR_WHITE, x, y, int_to_string(valid_building_sites.size()) + " tiles to fill", true, left_margin); } } } diff --git a/plugins/command-prompt.cpp b/plugins/command-prompt.cpp index f762ed713a..2ac4d3af95 100644 --- a/plugins/command-prompt.cpp +++ b/plugins/command-prompt.cpp @@ -60,7 +60,7 @@ class viewscreen_commandpromptst : public dfhack_viewscreen { { show_fps=gps->display_frames; gps->display_frames=0; - cursor_pos = 0; + cursor_pos = entry.size(); frame = 0; history_idx = command_history.size(); if (history_idx > 0) diff --git a/plugins/dwarfexport/dwarfexport.cpp b/plugins/dwarfexport/dwarfexport.cpp index 8355573be8..666601b79f 100644 --- a/plugins/dwarfexport/dwarfexport.cpp +++ b/plugins/dwarfexport/dwarfexport.cpp @@ -20,6 +20,11 @@ using namespace std; #include #include #include +/* +dwarfexport +=========== +Export dwarves to RuneSmith-compatible XML; also unused by modern tools. +*/ using namespace DFHack; using df::global::ui; diff --git a/plugins/eventful.cpp b/plugins/eventful.cpp index 3a8b6da7ad..1b9d228bcc 100644 --- a/plugins/eventful.cpp +++ b/plugins/eventful.cpp @@ -8,6 +8,7 @@ #include "VTableInterpose.h" #include "df/building.h" +#include "df/building_furnacest.h" #include "df/building_workshopst.h" #include "df/construction.h" #include "df/item.h" @@ -91,8 +92,8 @@ static bool is_lua_hook(const std::string &name) /* * Hooks */ -static void handle_fillsidebar(color_ostream &out,df::building_workshopst*,bool *call_native){}; -static void handle_postfillsidebar(color_ostream &out,df::building_workshopst*){}; +static void handle_fillsidebar(color_ostream &out,df::building_actual*,bool *call_native){}; +static void handle_postfillsidebar(color_ostream &out,df::building_actual*){}; static void handle_reaction_done(color_ostream &out,df::reaction*, df::reaction_product_itemst*, df::unit *unit, std::vector *in_items,std::vector *in_reag , std::vector *out_items,bool *call_native){}; @@ -102,8 +103,8 @@ static void handle_projitem_cm(color_ostream &out,df::proj_itemst*){}; static void handle_projunit_ci(color_ostream &out,df::proj_unitst*,bool){}; static void handle_projunit_cm(color_ostream &out,df::proj_unitst*){}; -DEFINE_LUA_EVENT_2(onWorkshopFillSidebarMenu, handle_fillsidebar, df::building_workshopst*,bool* ); -DEFINE_LUA_EVENT_1(postWorkshopFillSidebarMenu, handle_postfillsidebar, df::building_workshopst*); +DEFINE_LUA_EVENT_2(onWorkshopFillSidebarMenu, handle_fillsidebar, df::building_actual*,bool* ); +DEFINE_LUA_EVENT_1(postWorkshopFillSidebarMenu, handle_postfillsidebar, df::building_actual*); DEFINE_LUA_EVENT_7(onReactionComplete, handle_reaction_done,df::reaction*, df::reaction_product_itemst*, df::unit *, std::vector *,std::vector *,std::vector *,bool *); DEFINE_LUA_EVENT_5(onItemContaminateWound, handle_contaminate_wound, df::item_actual*,df::unit* , df::unit_wound* , uint8_t , int16_t ); @@ -287,6 +288,22 @@ struct workshop_hook : df::building_workshopst{ } }; IMPLEMENT_VMETHOD_INTERPOSE(workshop_hook, fillSidebarMenu); + +struct furnace_hook : df::building_furnacest{ + typedef df::building_furnacest interpose_base; + DEFINE_VMETHOD_INTERPOSE(void,fillSidebarMenu,()) + { + CoreSuspendClaimer suspend; + color_ostream_proxy out(Core::getInstance().getConsole()); + bool call_native=true; + onWorkshopFillSidebarMenu(out,this,&call_native); + if(call_native) + INTERPOSE_NEXT(fillSidebarMenu)(); + postWorkshopFillSidebarMenu(out,this); + } +}; +IMPLEMENT_VMETHOD_INTERPOSE(furnace_hook, fillSidebarMenu); + struct product_hook : item_product { typedef item_product interpose_base; @@ -430,6 +447,7 @@ static bool find_reactions(color_ostream &out) static void enable_hooks(bool enable) { INTERPOSE_HOOK(workshop_hook,fillSidebarMenu).apply(enable); + INTERPOSE_HOOK(furnace_hook,fillSidebarMenu).apply(enable); INTERPOSE_HOOK(item_hooks,contaminateWound).apply(enable); INTERPOSE_HOOK(proj_unit_hook,checkImpact).apply(enable); INTERPOSE_HOOK(proj_unit_hook,checkMovement).apply(enable); diff --git a/plugins/initflags.cpp b/plugins/initflags.cpp deleted file mode 100644 index 7a4ad30b02..0000000000 --- a/plugins/initflags.cpp +++ /dev/null @@ -1,51 +0,0 @@ -#include "Core.h" -#include "Console.h" -#include "Export.h" -#include "PluginManager.h" - -#include "DataDefs.h" -#include "df/d_init.h" - -using std::vector; -using std::string; -using std::endl; -using namespace DFHack; -using namespace df::enums; - -DFHACK_PLUGIN("initflags"); -REQUIRE_GLOBAL(d_init); - -command_result twaterlvl(color_ostream &out, vector & parameters); -command_result tidlers(color_ostream &out, vector & parameters); - -DFhackCExport command_result plugin_init (color_ostream &out, std::vector &commands) -{ - if (d_init) { - commands.push_back(PluginCommand("twaterlvl", "Toggle display of water/magma depth.", - twaterlvl, Gui::dwarfmode_hotkey)); - commands.push_back(PluginCommand("tidlers", "Toggle display of idlers.", - tidlers, Gui::dwarfmode_hotkey)); - } - return CR_OK; -} - -DFhackCExport command_result plugin_shutdown ( color_ostream &out ) -{ - return CR_OK; -} - -command_result twaterlvl(color_ostream &out, vector & parameters) -{ - // HOTKEY COMMAND: CORE ALREADY SUSPENDED - d_init->flags1.toggle(d_init_flags1::SHOW_FLOW_AMOUNTS); - out << "Toggled the display of water/magma depth." << endl; - return CR_OK; -} - -command_result tidlers(color_ostream &out, vector & parameters) -{ - // HOTKEY COMMAND: CORE ALREADY SUSPENDED - d_init->idlers = ENUM_NEXT_ITEM(d_init_idlers, d_init->idlers); - out << "Toggled the display of idlers to " << ENUM_KEY_STR(d_init_idlers, d_init->idlers) << endl; - return CR_OK; -} diff --git a/plugins/mapexport/mapexport.cpp b/plugins/mapexport/mapexport.cpp index 0c69eeb68f..ceb03196ac 100644 --- a/plugins/mapexport/mapexport.cpp +++ b/plugins/mapexport/mapexport.cpp @@ -21,6 +21,12 @@ using namespace google::protobuf::io; using namespace DFHack; using df::global::world; +/* +mapexport +========= +Export the current loaded map as a file. This was used by visualizers for +DF 0.34.11, but is now basically obsolete. +*/ typedef std::vector PlantList; diff --git a/plugins/misery.cpp b/plugins/misery.cpp index 00c844f1d5..a4468079c7 100644 --- a/plugins/misery.cpp +++ b/plugins/misery.cpp @@ -14,6 +14,21 @@ using namespace std; using namespace DFHack; +/* +misery +====== +When enabled, every new negative dwarven thought will be multiplied by a factor (2 by default). + +Usage: + +:misery enable n: enable misery with optional magnitude n. If specified, n must be positive. +:misery n: same as "misery enable n" +:misery enable: same as "misery enable 2" +:misery disable: stop adding new negative thoughts. This will not remove existing + duplicated thoughts. Equivalent to "misery 1" +:misery clear: remove fake thoughts added in this session of DF. Saving makes them + permanent! Does not change factor. +*/ DFHACK_PLUGIN("misery"); DFHACK_PLUGIN_IS_ENABLED(is_enabled); diff --git a/plugins/treefarm.cpp b/plugins/treefarm.cpp index 68429dd93f..0e24ad28f8 100644 --- a/plugins/treefarm.cpp +++ b/plugins/treefarm.cpp @@ -20,6 +20,24 @@ //#include "df/world.h" using namespace DFHack; +/* +treefarm +======== +Automatically manages special burrows and regularly schedules tree chopping +and digging when appropriate. + +Every time the plugin runs, it checks for burrows with a name containing the +string ``"treefarm"``. For each such burrow, it checks every tile in it for +fully-grown trees and for diggable walls. For each fully-grown tree it finds, +it designates the tree to be chopped, and for each natural wall it finds, it +designates the wall to be dug. + +Usage: + +:treefarm: Enables treefarm monitoring, starting next frame +:treefarm n: Enables treefarm monitoring, starting next frame, and sets + interval to n frames. If n is less than one, disables monitoring. +*/ DFHACK_PLUGIN("treefarm"); DFHACK_PLUGIN_IS_ENABLED(enabled); diff --git a/scripts/3rdparty/kane-t b/scripts/3rdparty/kane-t index 8cf05cc897..0a75d5ff69 160000 --- a/scripts/3rdparty/kane-t +++ b/scripts/3rdparty/kane-t @@ -1 +1 @@ -Subproject commit 8cf05cc89782206235f4bef1b5ef98e1bc74e266 +Subproject commit 0a75d5ff69916cf9b3739f4b20d36ab4cfdcf824 diff --git a/scripts/3rdparty/lethosor b/scripts/3rdparty/lethosor index 38a8415ffc..0b8303f6b0 160000 --- a/scripts/3rdparty/lethosor +++ b/scripts/3rdparty/lethosor @@ -1 +1 @@ -Subproject commit 38a8415ffc23e89590260a4502fa6aeeac95146d +Subproject commit 0b8303f6b03d574e3a0b3fd8b17b7ff0014af47f diff --git a/scripts/3rdparty/maienm b/scripts/3rdparty/maienm index ac6dae2ff0..45c78449e7 160000 --- a/scripts/3rdparty/maienm +++ b/scripts/3rdparty/maienm @@ -1 +1 @@ -Subproject commit ac6dae2ff06d1576873b8e508017e8043e7aa701 +Subproject commit 45c78449e71d1ba263044fb00108509088ad0026 diff --git a/scripts/3rdparty/maxthyme b/scripts/3rdparty/maxthyme index 0c32075d22..b337e931b8 160000 --- a/scripts/3rdparty/maxthyme +++ b/scripts/3rdparty/maxthyme @@ -1 +1 @@ -Subproject commit 0c32075d2205fe3aa80794fc45b2c49e3dace8dc +Subproject commit b337e931b8b7a167ee5ce1ac6b5c3155c291f260 diff --git a/scripts/CMakeLists.txt b/scripts/CMakeLists.txt index 82edb19a9c..e9d8999707 100644 --- a/scripts/CMakeLists.txt +++ b/scripts/CMakeLists.txt @@ -4,7 +4,7 @@ DFHACK_3RDPARTY_SCRIPT_REPO(kane-t) DFHACK_3RDPARTY_SCRIPT_REPO(lethosor) DFHACK_3RDPARTY_SCRIPT_REPO(maienm) DFHACK_3RDPARTY_SCRIPT_REPO(maxthyme) -DFHACK_3RDPARTY_SCRIPT_REPO(roses) +# DFHACK_3RDPARTY_SCRIPT_REPO(roses) install(DIRECTORY ${dfhack_SOURCE_DIR}/scripts DESTINATION ${DFHACK_DATA_DESTINATION} diff --git a/scripts/about.txt b/scripts/about.txt new file mode 100644 index 0000000000..818891af5d --- /dev/null +++ b/scripts/about.txt @@ -0,0 +1,2 @@ +Basic scripts are not stored in any subdirectory, and can be invoked directly. +They are generally useful tools for any player. diff --git a/scripts/adaptation.rb b/scripts/adaptation.rb index 7ed7302d0d..6d2e630179 100644 --- a/scripts/adaptation.rb +++ b/scripts/adaptation.rb @@ -1,5 +1,14 @@ # View or set level of cavern adaptation for the selected unit or the whole fort # based on removebadthoughts.rb +=begin + +adaptation +========== +View or set level of cavern adaptation for the selected unit or the whole fort. +Usage: ``adaptation [value]``. The ``value`` must be +between 0 and 800,000 inclusive. + +=end # Color constants, values mapped to color_value enum in include/ColorText.h COLOR_GREEN = 2 diff --git a/scripts/add-thought.lua b/scripts/add-thought.lua index 27eec53228..0f82b555cd 100644 --- a/scripts/add-thought.lua +++ b/scripts/add-thought.lua @@ -1,18 +1,14 @@ -- Adds emotions to creatures. --@ module = true ---[[ -BEGIN_DOCS - -.. _scripts/add-thought +--[[=begin add-thought =========== Adds a thought or emotion to the selected unit. Can be used by other scripts, or the gui invoked by running ``add-thought gui`` with a unit selected. -END_DOCS -]] +=end]] local utils=require('utils') diff --git a/scripts/armoks-blessing.lua b/scripts/armoks-blessing.lua index c93fb04c87..0ae373c31e 100644 --- a/scripts/armoks-blessing.lua +++ b/scripts/armoks-blessing.lua @@ -3,7 +3,16 @@ -- arguments allow for skills to be adjusted as well -- WARNING: USING THIS SCRIPT WILL ADJUST ALL DWARVES IN PLAY! -- by vjek +--[[=begin +armoks-blessing +=============== +Runs the equivalent of `rejuvenate`, `elevate-physical`, `elevate-mental`, and +`brainwash` on all dwarves currently on the map. This is an extreme change, +which sets every stat to an ideal - legendary skills, great traits, and +easy-to-satisfy preferences. + +=end]] function rejuvenate(unit) if unit==nil then print ("No unit available! Aborting with extreme prejudice.") diff --git a/scripts/autofarm.rb b/scripts/autofarm.rb index cc2f29dff8..ddfa7aae90 100644 --- a/scripts/autofarm.rb +++ b/scripts/autofarm.rb @@ -1,3 +1,19 @@ + +=begin + +autofarm +======== +Automatically handle crop selection in farm plots based on current plant stocks. +Selects a crop for planting if current stock is below a threshold. +Selected crops are dispatched on all farmplots. + +Usage:: + + autofarm start + autofarm default 30 + autofarm threshold 150 helmet_plump tail_pig + +=end class AutoFarm def initialize diff --git a/scripts/autolabor-artisans.lua b/scripts/autolabor-artisans.lua index 61aa963352..22d3946469 100644 --- a/scripts/autolabor-artisans.lua +++ b/scripts/autolabor-artisans.lua @@ -1,5 +1,12 @@ -- Executes an autolabor command for each labor where skill level influences output quality. +--[[=begin + +autolabor-artisans +================== +Runs `autolabor`, with settings tuned for small but highly skilled workforces. + +=end]] local artisan_labors = { "CARPENTER", "DETAIL", diff --git a/scripts/autounsuspend.rb b/scripts/autounsuspend.rb index 9613288ba1..f493cfb680 100644 --- a/scripts/autounsuspend.rb +++ b/scripts/autounsuspend.rb @@ -1,4 +1,12 @@ # un-suspend construction jobs, on a recurring basis +=begin + +autounsuspend +============= +Automatically unsuspend jobs in workshops, on a recurring basis. +See `unsuspend` for one-off use, or `resume` ``all``. + +=end class AutoUnsuspend attr_accessor :running diff --git a/scripts/ban-cooking.rb b/scripts/ban-cooking.rb index 544447277e..906469ea5d 100644 --- a/scripts/ban-cooking.rb +++ b/scripts/ban-cooking.rb @@ -1,4 +1,13 @@ # convenient way to ban cooking categories of food +=begin + +ban-cooking +=========== +A more convenient way to ban cooking various categories of foods than the +kitchen interface. Usage: ``ban-cooking ``. Valid types are ``booze``, +``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds). + +=end already_banned = {} kitchen = df.ui.kitchen diff --git a/scripts/binpatch.lua b/scripts/binpatch.lua index b9a4cf0b17..ac77052508 100644 --- a/scripts/binpatch.lua +++ b/scripts/binpatch.lua @@ -1,4 +1,11 @@ -- Apply or remove binary patches at runtime. +--[[=begin + +binpatch +======== +Implements functions for in-memory binpatches. See `binpatches`. + +=end]] local bp = require('binpatch') diff --git a/scripts/brainwash.lua b/scripts/brainwash.lua index 717b0f221f..1950323a8c 100644 --- a/scripts/brainwash.lua +++ b/scripts/brainwash.lua @@ -1,6 +1,15 @@ -- This script will brainwash a dwarf, modifying their personality -- usage is: target a unit in DF, and execute this script in dfhack -- by vjek +--[[=begin + +brainwash +========= +Modify the personality traits of the selected dwarf to match an 'ideal' +personality - as stable and reliable as possible. This makes dwarves very +stable, preventing tantrums even after months of misery. + +=end]] function brainwash_unit(profile) local i,unit_name diff --git a/scripts/burial.lua b/scripts/burial.lua index b73ac93271..3023f91285 100644 --- a/scripts/burial.lua +++ b/scripts/burial.lua @@ -1,5 +1,13 @@ -- allows burial in unowned coffins -- by Putnam https://gist.github.com/Putnam3145/e7031588f4d9b24b9dda +--[[=begin + +burial +====== +Sets all unowned coffins to allow burial. ``burial -pets`` also allows burial +of pets. + +=end]] local utils=require('utils') diff --git a/scripts/create-items.rb b/scripts/create-items.rb index ea739f4e0a..544bd8ce0f 100644 --- a/scripts/create-items.rb +++ b/scripts/create-items.rb @@ -1,4 +1,34 @@ # create first necessity items under cursor +=begin + +create-items +============ +Spawn items under the cursor, to get your fortress started. + +The first argument gives the item category, the second gives the material, +and the optionnal third gives the number of items to create (defaults to 20). + +Currently supported item categories: ``boulder``, ``bar``, ``plant``, ``log``, +``web``. + +Instead of material, using ``list`` makes the script list eligible materials. + +The ``web`` item category will create an uncollected cobweb on the floor. + +Note that the script does not enforce anything, and will let you create +boulders of toad blood and stuff like that. +However the ``list`` mode will only show 'normal' materials. + +Examples:: + + create-items boulders COAL_BITUMINOUS 12 + create-items plant tail_pig + create-items log list + create-items web CREATURE:SPIDER_CAVE_GIANT:SILK + create-items bar CREATURE:CAT:SOAP + create-items bar adamantine + +=end category = $script_args[0] || 'help' mat_raw = $script_args[1] || 'list' diff --git a/scripts/deathcause.rb b/scripts/deathcause.rb index 4ba3d2388d..6b2f252c0e 100644 --- a/scripts/deathcause.rb +++ b/scripts/deathcause.rb @@ -1,4 +1,12 @@ # show death cause of a creature +=begin + +deathcause +========== +Select a body part ingame, or a unit from the :kbd:`u` unit list, and this +script will display the cause of death of the creature. + +=end def display_death_event(e) str = "The #{e.victim_hf_tg.race_tg.name[0]} #{e.victim_hf_tg.name} died in year #{e.year}" diff --git a/scripts/devel/about.txt b/scripts/devel/about.txt new file mode 100644 index 0000000000..12b1f18539 --- /dev/null +++ b/scripts/devel/about.txt @@ -0,0 +1,6 @@ +``devel/*`` scripts are intended for developer use, but many may +be of interest to anyone investigating odd phenomema or just messing +around. They are documented to encourage such inquiry. + +Some can PERMANENTLY DAMAGE YOUR SAVE if misused, so please be careful. +The warnings are real; if in doubt make backups before running the command. diff --git a/scripts/devel/all-bob.lua b/scripts/devel/all-bob.lua index 65c1ea2d67..08ab19fbb1 100644 --- a/scripts/devel/all-bob.lua +++ b/scripts/devel/all-bob.lua @@ -1,6 +1,14 @@ --all-bob.lua --author expwnent ---names all units bob. Useful for testing interaction trigger events +-- +--[[=begin + +devel/all-bob +============= +Changes the first name of all units to "Bob". +Useful for testing `modtools/interaction-trigger` events. + +=end]] for _,v in ipairs(df.global.world.units.all) do v.name.first_name = "Bob" diff --git a/scripts/devel/clear-script-env.lua b/scripts/devel/clear-script-env.lua new file mode 100644 index 0000000000..90c8db0ed2 --- /dev/null +++ b/scripts/devel/clear-script-env.lua @@ -0,0 +1,26 @@ +-- Clear script environment +--[[=begin + +devel/clear-script-env +====================== +Clears the environment of the specified lua script(s). + +=end]] +args = {...} +if #args < 1 then qerror("script name(s) required") end +for _, name in pairs(args) do + local file = dfhack.findScript(name) + if file then + local script = dfhack.internal.scripts[file] + if script then + local env = script.env + while next(env) do + env[next(env)] = nil + end + else + dfhack.printerr("Script not loaded: " .. name) + end + else + dfhack.printerr("Can't find script: " .. name) + end +end diff --git a/scripts/devel/cmptiles.lua b/scripts/devel/cmptiles.lua index 8421038ebe..bb08710513 100644 --- a/scripts/devel/cmptiles.lua +++ b/scripts/devel/cmptiles.lua @@ -1,5 +1,13 @@ -- Lists and/or compares two tiletype material groups. --- Usage: devel/cmptiles material1 [material2] +--[[=begin + +devel/cmptiles +============== +Lists and/or compares two tiletype material groups. + +Usage: ``devel/cmptiles material1 [material2]`` + +=end]] local nmat1,nmat2=... local mat1 = df.tiletype_material[nmat1] diff --git a/scripts/devel/export-dt-ini.lua b/scripts/devel/export-dt-ini.lua index 41a2457ceb..1d99b2d556 100644 --- a/scripts/devel/export-dt-ini.lua +++ b/scripts/devel/export-dt-ini.lua @@ -1,4 +1,11 @@ -- Exports an ini file for Dwarf Therapist. +--[[=begin + +devel/export-dt-ini +=================== +Exports an ini file containing memory addresses for Dwarf Therapist. + +=end]] local utils = require 'utils' local ms = require 'memscan' diff --git a/scripts/devel/find-offsets.lua b/scripts/devel/find-offsets.lua index ae99adbca6..17bc4f6f91 100644 --- a/scripts/devel/find-offsets.lua +++ b/scripts/devel/find-offsets.lua @@ -1,19 +1,39 @@ -- Find some offsets for linux. +--[[=begin -local utils = require 'utils' -local ms = require 'memscan' -local gui = require 'gui' +devel/find-offsets +================== +WARNING: THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS. + +Running this script on a new DF version will NOT +MAKE IT RUN CORRECTLY if any data structures +changed, thus possibly leading to CRASHES AND/OR +PERMANENT SAVE CORRUPTION. + +Finding the first few globals requires this script to be +started immediately after loading the game, WITHOUT +first loading a world. The rest expect a loaded save, +not a fresh embark. Finding current_weather requires +a special save previously processed with `devel/prepare-save` +on a DF version with working dfhack. ---[[ +The script expects vanilla game configuration, without +any custom tilesets or init file changes. Never unpause +the game unless instructed. When done, quit the game +without saving using 'die'. Arguments: - * global names to force finding them - * 'all' to force all globals - * 'nofeed' to block automated fake input searches - * 'nozoom' to disable neighboring object heuristics +* global names to force finding them +* ``all`` to force all globals +* ``nofeed`` to block automated fake input searches +* ``nozoom`` to disable neighboring object heuristics -]] +=end]] + +local utils = require 'utils' +local ms = require 'memscan' +local gui = require 'gui' local is_known = dfhack.internal.getAddress diff --git a/scripts/devel/inject-raws.lua b/scripts/devel/inject-raws.lua index 1450d1179c..cea69eb618 100644 --- a/scripts/devel/inject-raws.lua +++ b/scripts/devel/inject-raws.lua @@ -1,14 +1,26 @@ -- Injects new reaction, item and building defs into the world. +--[[=begin --- The savegame contains a list of the relevant definition tokens in --- the right order, but all details are read from raws every time. --- This allows just adding stub definitions, and simply saving and --- reloading the game. +devel/inject-raws +================= +WARNING: THIS SCRIPT CAN PERMANENLY DAMAGE YOUR SAVE. --- Usage example: ---[[ -devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER -]] +This script attempts to inject new raw objects into your +world. If the injected references do not match the actual +edited raws, your save will refuse to load, or load but crash. + +The savegame contains a list of the relevant definition tokens in +the right order, but all details are read from raws every time. +This allows just adding stub definitions, and simply saving and +reloading the game. + +This is useful enough for modders and some users to justify the danger. + +Usage example:: + + devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER + +=end]] local utils = require 'utils' diff --git a/scripts/devel/inspect-screen.lua b/scripts/devel/inspect-screen.lua index ae8334ad7a..9de6b25326 100644 --- a/scripts/devel/inspect-screen.lua +++ b/scripts/devel/inspect-screen.lua @@ -1,4 +1,11 @@ -- Read the tiles from the screen and display info about them. +--[[=begin + +devel/inspect-screen +==================== +Read the tiles from the screen and display info about them. + +=end]] local utils = require 'utils' local gui = require 'gui' diff --git a/scripts/devel/light.lua b/scripts/devel/light.lua index 532a3a4f50..e19591e11c 100644 --- a/scripts/devel/light.lua +++ b/scripts/devel/light.lua @@ -1,4 +1,15 @@ --- an experimental lighting engine for df. param: "static" to not recalc when in game. press "~" to recalculate. "`" to exit +-- an experimental lighting engine +--[[=begin + +devel/light +=========== +An experimental lighting engine for DF, using the `rendermax` plugin. + +Call ``devel/light static`` to not recalculate lighting when in game. +Press :kbd:`~` to recalculate lighting. Press :kbd:`\`` to exit. + +=end]] + local gui = require 'gui' local guidm = require 'gui.dwarfmode' local render = require 'plugins.rendermax' diff --git a/scripts/devel/list-filters.lua b/scripts/devel/list-filters.lua index 87b9f24b1c..5666315fc0 100644 --- a/scripts/devel/list-filters.lua +++ b/scripts/devel/list-filters.lua @@ -1,6 +1,12 @@ -- List input items for the building currently being built. --- --- This is where the filters in lua/dfhack/buildings.lua come from. +--[[=begin + +devel/list-filters +================== +List input items for the building currently being built. +This is where the filters in lua/dfhack/buildings.lua come from. + +=end]] local dumper = require 'dumper' local utils = require 'utils' diff --git a/scripts/devel/lsmem.lua b/scripts/devel/lsmem.lua index 75586324d9..b390adc5c4 100644 --- a/scripts/devel/lsmem.lua +++ b/scripts/devel/lsmem.lua @@ -1,4 +1,11 @@ -- Prints memory ranges of the process. +--[[=begin + +devel/lsmem +=========== +Prints memory ranges of the process. + +=end]] for _,v in ipairs(dfhack.internal.getMemRanges()) do local access = { '-', '-', '-', 'p' } diff --git a/scripts/devel/lua-example.lua b/scripts/devel/lua-example.lua index 044849ed77..bbdb04ed6c 100644 --- a/scripts/devel/lua-example.lua +++ b/scripts/devel/lua-example.lua @@ -1,4 +1,12 @@ -- Example of a lua script. +--[[=begin + +devel/lua-example +================= +An example lua script, which reports the number of times it has +been called. Useful for testing environment persistence. + +=end]] run_count = (run_count or 0) + 1 diff --git a/scripts/devel/migrants-now.lua b/scripts/devel/migrants-now.lua deleted file mode 100644 index 8eb4b0c8f2..0000000000 --- a/scripts/devel/migrants-now.lua +++ /dev/null @@ -1,9 +0,0 @@ --- Force a migrants event in next 10 ticks. - -df.global.timed_events:insert('#',{ - new = true, - type = df.timed_event_type.Migrants, - season = df.global.cur_season, - season_ticks = df.global.cur_season_tick+1, - entity = df.historical_entity.find(df.global.ui.civ_id) -}) diff --git a/scripts/devel/nuke-items.lua b/scripts/devel/nuke-items.lua index aa3f5b840d..d98901142b 100644 --- a/scripts/devel/nuke-items.lua +++ b/scripts/devel/nuke-items.lua @@ -1,6 +1,12 @@ -- Deletes ALL items not held by units, buildings or jobs. --- --- Intended solely for lag investigation. +--[[=begin + +devel/nuke-items +================ +Deletes ALL items not held by units, buildings or jobs. +Intended solely for lag investigation. + +=end]] local count = 0 diff --git a/scripts/devel/pop-screen.lua b/scripts/devel/pop-screen.lua index f1ee072c59..8bc5e45c6f 100644 --- a/scripts/devel/pop-screen.lua +++ b/scripts/devel/pop-screen.lua @@ -1,3 +1,10 @@ -- For killing bugged out gui script screens. +--[[=begin + +devel/pop-screen +================ +For killing bugged out gui script screens. + +=end]] dfhack.screen.dismiss(dfhack.gui.getCurViewscreen()) diff --git a/scripts/devel/prepare-save.lua b/scripts/devel/prepare-save.lua index c282c8a437..dd1f81e453 100644 --- a/scripts/devel/prepare-save.lua +++ b/scripts/devel/prepare-save.lua @@ -1,4 +1,16 @@ -- Prepare the current save for use with devel/find-offsets. +--[[=begin + +devel/prepare-save +================== +WARNING: THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS. + +This script prepares the current savegame to be used +with `devel/find-offsets`. It CHANGES THE GAME STATE +to predefined values, and initiates an immediate +`quicksave`, thus PERMANENTLY MODIFYING the save. + +=end]] local utils = require 'utils' diff --git a/scripts/devel/print-args.lua b/scripts/devel/print-args.lua index 199a20e7fd..46024eaa42 100644 --- a/scripts/devel/print-args.lua +++ b/scripts/devel/print-args.lua @@ -1,6 +1,13 @@ --print-args.lua --author expwnent ---prints all the arguments on their own line. useful for debugging +--[[=begin + +devel/print-args +================ +Prints all the arguments you supply to the script on their own line. +Useful for debugging other scripts. + +=end]] local args = {...} for _,arg in ipairs(args) do diff --git a/scripts/devel/print-args2.lua b/scripts/devel/print-args2.lua index 873b403119..ad870623d9 100644 --- a/scripts/devel/print-args2.lua +++ b/scripts/devel/print-args2.lua @@ -1,6 +1,13 @@ --print-args2.lua --author expwnent ---prints all the arguments on their own line with quotes around them. useful for debugging +--[[=begin + +devel/print-args2 +================= +Prints all the arguments you supply to the script on their own line +with quotes around them. + +=end]] local args = {...} print("print-args") diff --git a/scripts/devel/scanitemother.rb b/scripts/devel/scanitemother.rb index 00b093a28c..1f130603ff 100644 --- a/scripts/devel/scanitemother.rb +++ b/scripts/devel/scanitemother.rb @@ -1,5 +1,11 @@ -# list indexes in world.item.other[] where current selected item appears +# list indices in world.item.other[] where current selected item appears +=begin +devel/scanitemother +=================== +List indices in ``world.item.other[]`` where current selected item appears. + +=end tg = df.item_find raise 'select an item' if not tg diff --git a/scripts/devel/spawn-unit-helper.rb b/scripts/devel/spawn-unit-helper.rb index a7d4f610d1..437eb81db1 100644 --- a/scripts/devel/spawn-unit-helper.rb +++ b/scripts/devel/spawn-unit-helper.rb @@ -13,17 +13,23 @@ df.world.arena_spawn.creature_cnt[df.world.arena_spawn.race.length-1] = 0 puts < 14 then return false end + end + if unit.flags1.caged + or u.race ~= df.global.ui.race_id + or u.civ_id ~= df.global.ui.civ_id + or dfhack.units.isDead(u) + or dfhack.units.isOpposedToLife(u) + or u.flags1.merchant + or u.flags1.diplomat + or unit.flags1.chained + or dfhack.units.getNoblePositions(unit) ~= nil + or unit.military.squad_id ~= -1 + or dfhack.units.isCitizen(unit) + or dfhack.units.isSane(unit) + or unit.profession ~= 103 + or not dfhack.units.isDead(unit) + then return false end + return true +end + +function checkForDeserters(method,civ_id) + local allUnits = df.global.world.units.active + for i=#allUnits-1,0,-1 do -- search list in reverse + local u = allUnits[i] + if canLeave(u) and math.random(100) < desireToStay(u,method,civ_id) then + desert(u,method,civ_id) + end + end +end + +function checkmigrationnow() + local merchant_civ_ids = {} + local diplomat_civ_ids = {} + local allUnits = df.global.world.units.active + for i=0, #allUnits-1 do + local unit = allUnits[i] + if dfhack.units.isSane(unit) + and not dfhack.units.isDead(unit) + and not dfhack.units.isOpposedToLife(unit) + and not unit.flags1.tame + then + if unit.flags1.merchant then table.insert(merchant_civ_ids, unit.civ_id) end + if unit.flags1.diplomat then table.insert(diplomat_civ_ids, unit.civ_id) end + end + end + + for _, civ_id in pairs(merchant_civ_ids) do checkForDeserters('merchant', civ_id) end + for _, civ_id in pairs(diplomat_civ_ids) do checkForDeserters('diplomat', civ_id) end + checkForDeserters('wild', -1) +end + +local function event_loop() + checkmigrationnow() + dfhack.timeout(1, 'months', event_loop) +end + +dfhack.onStateChange.loadEmigration = function(code) + if code==SC_MAP_LOADED then + if enabled then + print("Emigration enabled.") + event_loop() + else + print("Emigration disabled.") + end + end +end + +if dfhack.isMapLoaded() then + dfhack.onStateChange.loadEmigration(SC_MAP_LOADED) +end + diff --git a/scripts/exportlegends.lua b/scripts/exportlegends.lua index 7b1277b3bf..3c2999412b 100644 --- a/scripts/exportlegends.lua +++ b/scripts/exportlegends.lua @@ -1,5 +1,23 @@ -- Export everything from legends mode --- Valid args: "all", "info", "maps", "sites" +--[[=begin + +exportlegends +============= +Controls legends mode to export data - especially useful to set-and-forget large +worlds, or when you want a map of every site when there are several hundred. + +The 'info' option exports more data than is possible in vanilla, to a +:file:`region-date-legends_plus.xml` file developed to extend +:forums:`World Viewer <128932>` and other legends utilities. + +Options: + +:info: Exports the world/gen info, the legends XML, and a custom XML with more information +:sites: Exports all available site maps +:maps: Exports all seventeen detailed maps +:all: Equivalent to calling all of the above, in that order + +=end]] gui = require 'gui' local args = {...} diff --git a/scripts/exterminate.rb b/scripts/exterminate.rb index b2625428f9..bc25a95b8b 100644 --- a/scripts/exterminate.rb +++ b/scripts/exterminate.rb @@ -1,7 +1,48 @@ # exterminate creatures +=begin + +exterminate +=========== +Kills any unit of a given race. + +With no argument, lists the available races and count eligible targets. + +With the special argument ``him``, targets only the selected creature. + +With the special argument ``undead``, targets all undeads on the map, +regardless of their race. + +When specifying a race, a caste can be specified to further restrict the +targeting. To do that, append and colon and the caste name after the race. + +Any non-dead non-caged unit of the specified race gets its ``blood_count`` +set to 0, which means immediate death at the next game tick. For creatures +such as vampires, it also sets animal.vanish_countdown to 2. + +An alternate mode is selected by adding a 2nd argument to the command, +``magma``. In this case, a column of 7/7 magma is generated on top of the +targets until they die (Warning: do not call on magma-safe creatures. Also, +using this mode on birds is not recommended.) The final alternate mode +is ``butcher``, which marks them for butchering but does not kill. + +Will target any unit on a revealed tile of the map, including ambushers, +but ignore caged/chained creatures. + +Ex:: + + exterminate gob + exterminate gob:male + +To kill a single creature, select the unit with the 'v' cursor and:: + + exterminate him + +To purify all elves on the map with fire (may have side-effects):: + + exterminate elve magma + +=end -# race = name of the race to eradicate, use 'him' to target only the selected creature -# use 'undead' to target all undeads race = $script_args[0] # if the 2nd parameter is 'magma', magma rain for the targets instead of instant death diff --git a/scripts/fix-ster.lua b/scripts/fix-ster.lua index bc5df8e0af..66b4f67652 100644 --- a/scripts/fix-ster.lua +++ b/scripts/fix-ster.lua @@ -3,20 +3,21 @@ -- original author: Tacomagic -- minor fixes by PeridexisErrant, Lethosor --@ module = true +--[[=begin ---[[ -This script utilizes the orientation tag to either fix infertile creatures -or inflict infertility on creatures that you do not want to breed +fix-ster +======== +Utilizes the orientation tag to either fix infertile creatures or inflict +infertility on creatures that you do not want to breed. Usage:: -Required arg: - fert: sets the flag to assure creature(s) are fertile - ster: sets the flag to assure creature(s) are sterile -Optional args: - the script will only process the currently selected creature - all: process all creatures currently on the map - animals: processes everything but dwarves on the map - only:: processes all of the creatures matching the specified creature on the map -]]-- + fix-ster [fert|ster] [all|animals|only:] + +``fert`` or ``ster`` is a required argument; whether to make the target fertile +or sterile. Optional arguments specify the target: no argument for the +selected unit, ``all`` for all units on the map, ``animals`` for all non-dwarf +creatures, or ``only:`` to only process matching creatures. + +=end]] function changeorient(unit, ori) --Sets the fertility flag based on gender. diff --git a/scripts/fix/about.txt b/scripts/fix/about.txt new file mode 100644 index 0000000000..6a2d35c7ed --- /dev/null +++ b/scripts/fix/about.txt @@ -0,0 +1 @@ +``fix/*`` scripts fix various bugs and issues, some of them obscure. diff --git a/scripts/fix/blood-del.lua b/scripts/fix/blood-del.lua index 907135eb49..88d7d27566 100644 --- a/scripts/fix/blood-del.lua +++ b/scripts/fix/blood-del.lua @@ -1,8 +1,13 @@ ---blood-del.lua --makes it so that civs won't come with barrels full of blood, ichor, or goo --author Urist Da Vinci --edited by expwnent, scamtank +--[[=begin +fix/blood-del +============= +Makes it so that future caravans won't bring barrels full of blood, ichor, or goo. + +=end]] local my_entity=df.historical_entity.find(df.global.ui.civ_id) local sText=" " local k=0 diff --git a/scripts/fix/build-location.lua b/scripts/fix/build-location.lua index 0eea2c780c..9df518ec3e 100644 --- a/scripts/fix/build-location.lua +++ b/scripts/fix/build-location.lua @@ -1,7 +1,15 @@ -- Lets constructions reconsider the build location. -- Partial work-around for http://www.bay12games.com/dwarves/mantisbt/view.php?id=5991 +--[[=begin +fix/build-location +================== +Fixes construction jobs that are stuck trying to build a wall while standing +on the same exact tile (:bug:`5991`), designates the tile restricted traffic to +hopefully avoid jamming it again, and unsuspends them. + +=end]] local utils = require('utils') local count = 0 diff --git a/scripts/fix/dead-units.lua b/scripts/fix/dead-units.lua index 2d5558179b..7687a75cce 100644 --- a/scripts/fix/dead-units.lua +++ b/scripts/fix/dead-units.lua @@ -1,5 +1,13 @@ -- Remove uninteresting dead units from the unit list. +--[[=begin +fix/dead-units +============== +Removes uninteresting dead units from the unit list. Doesn't seem to give any +noticeable performance gain, but migrants normally stop if the unit list grows +to around 3000 units, and this script reduces it back. + +=end]] local units = df.global.world.units.active local dwarf_race = df.global.ui.race_id local dwarf_civ = df.global.ui.civ_id diff --git a/scripts/fix/fat-dwarves.lua b/scripts/fix/fat-dwarves.lua index 5394f6770b..09b5eb28e3 100644 --- a/scripts/fix/fat-dwarves.lua +++ b/scripts/fix/fat-dwarves.lua @@ -2,7 +2,16 @@ -- -- See for more info: -- http://www.bay12games.com/dwarves/mantisbt/view.php?id=5971 +--[[=begin +fix/fat-dwarves +=============== +Avoids 5-10% FPS loss due to constant recalculation of insulation for dwarves at +maximum fatness, by reducing the cap from 1,000,000 to 999,999. +Recalculation is triggered in steps of 250 units, and very fat dwarves +constantly bounce off the maximum value while eating. + +=end]] local num_fat = 0 local num_lagging = 0 diff --git a/scripts/fix/feeding-timers.lua b/scripts/fix/feeding-timers.lua index 84c6d45de0..84fab70865 100644 --- a/scripts/fix/feeding-timers.lua +++ b/scripts/fix/feeding-timers.lua @@ -2,7 +2,13 @@ -- original author: tejón -- rewritten by expwnent -- see repeat.lua for how to run this every so often automatically +--[[=begin +fix/feeding-timers +================== +Reset the GiveWater and GiveFood timers of all units as appropriate. + +=end]] local args = {...} if args[1] ~= nil then print("fix/feeding-timers usage") diff --git a/scripts/fix/item-occupancy.lua b/scripts/fix/item-occupancy.lua index 09c6b30306..bcf1b89032 100644 --- a/scripts/fix/item-occupancy.lua +++ b/scripts/fix/item-occupancy.lua @@ -1,10 +1,17 @@ -- Verify item occupancy and block item list integrity. --- --- Checks: --- 1) Item has flags.on_ground <=> it is in the correct block item list --- 2) A tile has items in block item list <=> it has occupancy.item --- 3) The block item lists are sorted. +--[[=begin + +fix/item-occupancy +================== +Diagnoses and fixes issues with nonexistant 'items occupying site', usually +caused by `autodump` bugs or other hacking mishaps. Checks that: + +#. Item has ``flags.on_ground`` <=> it is in the correct block item list +#. A tile has items in block item list <=> it has ``occupancy.item`` +#. The block item lists are sorted + +=end]] local utils = require 'utils' function check_block_items(fix) diff --git a/scripts/fix/loyaltycascade.rb b/scripts/fix/loyaltycascade.rb index b1caf9b105..2cf52dd93a 100644 --- a/scripts/fix/loyaltycascade.rb +++ b/scripts/fix/loyaltycascade.rb @@ -1,5 +1,11 @@ # script to fix loyalty cascade, when you order your militia to kill friendly units +=begin +fix/loyaltycascade +================== +Aborts loyalty cascades by fixing units whose own civ is the enemy. + +=end def fixunit(unit) return if unit.race != df.ui.race_id or unit.civ_id != df.ui.civ_id links = unit.hist_figure_tg.entity_links diff --git a/scripts/fix/population-cap.lua b/scripts/fix/population-cap.lua index c2e3293fb2..483941982a 100644 --- a/scripts/fix/population-cap.lua +++ b/scripts/fix/population-cap.lua @@ -1,11 +1,18 @@ -- Communicates current population to mountainhomes to avoid cap overshooting. --- The reason for population cap problems is that the population value it --- is compared against comes from the last dwarven caravan that successfully --- left for mountainhomes. This script instantly updates it. --- Note that a migration wave can still overshoot the limit by 1-2 dwarves because --- of the last migrant bringing his family. Likewise, king arrival ignores cap. +--[[=begin +fix/population-cap +================== +Run this after every migrant wave to ensure your population cap is not exceeded. + +The reason for population cap problems is that the population value it +is compared against comes from the last dwarven caravan that successfully +left for mountainhomes. This script instantly updates it. +Note that a migration wave can still overshoot the limit by 1-2 dwarves because +of the last migrant bringing his family. Likewise, king arrival ignores cap. + +=end]] local args = {...} local ui = df.global.ui diff --git a/scripts/fix/stable-temp.lua b/scripts/fix/stable-temp.lua index 63739f8ea3..7238d88d99 100644 --- a/scripts/fix/stable-temp.lua +++ b/scripts/fix/stable-temp.lua @@ -1,5 +1,13 @@ -- Reset item temperature to the value of their tile. +--[[=begin +fix/stable-temp +=============== +Instantly sets the temperature of all free-lying items to be in equilibrium with +the environment, which stops temperature updates until something changes. +To maintain this efficient state, use `tweak fast-heat `. + +=end]] local args = {...} local apply = (args[1] == 'apply') @@ -51,6 +59,7 @@ end if apply then print('Items updated: '..count) else + print("Use 'fix/stable-temp apply' to force-change temperature.") print('Items not in equilibrium: '..count) end @@ -60,7 +69,3 @@ table.sort(tlist, function(a,b) return types[a] > types[b] end) for _,k in ipairs(tlist) do print(' '..df.item_type[k]..':', types[k]) end - -if not apply then - print("Use 'fix/stable-temp apply' to force-change temperature.") -end diff --git a/scripts/fix/stuckdoors.rb b/scripts/fix/stuckdoors.rb index 249ed58102..f99d0f2633 100644 --- a/scripts/fix/stuckdoors.rb +++ b/scripts/fix/stuckdoors.rb @@ -2,7 +2,14 @@ # this may happen after people mess with the game by (incorrectly) teleporting units or items # a door may stick open if the map occupancy flags are wrong +=begin +fix/stuckdoors +============== +Fix doors that are stuck open due to incorrect map occupancy flags, eg due to +incorrect use of `teleport`. + +=end count = 0 df.world.buildings.all.each { |bld| # for all doors diff --git a/scripts/fixnaked.lua b/scripts/fixnaked.lua index 6e154440f8..39cfd2b77a 100644 --- a/scripts/fixnaked.lua +++ b/scripts/fixnaked.lua @@ -1,4 +1,11 @@ --removes unhappy thoughts due to lack of clothing +--[[=begin + +fixnaked +======== +Removes all unhappy thoughts due to lack of clothing. + +=end]] function fixnaked() local total_fixed = 0 diff --git a/scripts/forum-dwarves.lua b/scripts/forum-dwarves.lua index eb12b3baed..23402dd6f6 100644 --- a/scripts/forum-dwarves.lua +++ b/scripts/forum-dwarves.lua @@ -2,6 +2,14 @@ -- Save a copy of a text screen for the DF forums. Use 'forumdwarves help' for more details. -- original author: Caldfir -- edited by expwnent, Mchl +--[[=begin + +forum-dwarves +============= +Saves a copy of a text screen, formatted in bbcode for posting to the Bay12 Forums. +Use ``forum-dwarves help`` for more information. + +=end]] local args = {...} diff --git a/scripts/full-heal.lua b/scripts/full-heal.lua index 13a65852d9..4759e3e9ce 100644 --- a/scripts/full-heal.lua +++ b/scripts/full-heal.lua @@ -2,7 +2,13 @@ --author Kurik Amudnil, Urist DaVinci --edited by expwnent --- attempt to fully heal a selected unit, option -r to attempt to resurrect the unit +--[[=begin + +full-heal +========= +Attempts to fully heal the selected unit. ``full-heal -r`` attempts to resurrect the unit. + +=end]] local utils=require('utils') diff --git a/scripts/gaydar.lua b/scripts/gaydar.lua index 4513bec14a..83de3ae6aa 100644 --- a/scripts/gaydar.lua +++ b/scripts/gaydar.lua @@ -1,4 +1,13 @@ local utils = require('utils') +--[[=begin + +gaydar +====== +Shows the sexual orientation of units, useful for social engineering or checking +the viability of livestock breeding programs. Use ``gaydar -help`` for information +on available filters for orientation, citizenship, species, etc. + +=end]] validArgs = utils.invert({ 'all', diff --git a/scripts/growcrops.rb b/scripts/growcrops.rb index c5ad717cc1..95bd7a81ab 100644 --- a/scripts/growcrops.rb +++ b/scripts/growcrops.rb @@ -1,4 +1,19 @@ # grow crops in farm plots. ex: growcrops helmet_plump 20 +=begin + +growcrops +========= +Instantly grow seeds inside farming plots. + +With no argument, this command list the various seed types currently in +use in your farming plots. With a seed type, the script will grow 100 of +these seeds, ready to be harvested. Set the number with a 2nd argument. + +For example, to grow 40 plump helmet spawn:: + + growcrops plump 40 + +=end material = $script_args[0] count_max = $script_args[1].to_i diff --git a/scripts/gui/about.txt b/scripts/gui/about.txt new file mode 100644 index 0000000000..1c83e50b2c --- /dev/null +++ b/scripts/gui/about.txt @@ -0,0 +1,6 @@ +``gui/*`` scripts implement dialogs in the main game window. + +In order to avoid user confusion, as a matter of policy all these tools +display the word "DFHack" on the screen somewhere while active. +When that is not appropriate because they merely add keybinding hints to +existing DF screens, they deliberately use red instead of green for the key. diff --git a/scripts/gui/advfort.lua b/scripts/gui/advfort.lua index f02fd6a697..70d4bc083b 100644 --- a/scripts/gui/advfort.lua +++ b/scripts/gui/advfort.lua @@ -1,5 +1,26 @@ -- allows to do jobs in adv. mode. +--[[=begin + +gui/advfort +=========== +This script allows to perform jobs in adventure mode. For more complete help +press :kbd:`?` while script is running. It's most comfortable to use this as a +keybinding. (e.g. ``keybinding set Ctrl-T gui/advfort``). Possible arguments: + +:-a, --nodfassign: uses different method to assign items. +:-i, --inventory: checks inventory for possible items to use in the job. +:-c, --cheat: relaxes item requirements for buildings (e.g. walls from bones). Implies -a +:job: selects that job (e.g. Dig or FellTree) + +An example of player digging in adventure mode: + +.. image:: /docs/images/advfort.png + +**WARNING:** changes only persist in non procedural sites, namely: player forts, caves, and camps. + +=end]] + --[==[ version: 0.044 changelog: diff --git a/scripts/gui/advfort_items.lua b/scripts/gui/advfort_items.lua index fb44413972..3727bf9a4a 100644 --- a/scripts/gui/advfort_items.lua +++ b/scripts/gui/advfort_items.lua @@ -1,3 +1,11 @@ + +--[[=begin + +gui/advfort_items +================= +Does something with items in adventure mode jobs. + +=end]] local _ENV = mkmodule('hack.scripts.gui.advfort_items') local gui=require('gui') diff --git a/scripts/gui/assign-rack.lua b/scripts/gui/assign-rack.lua index 92535d793c..3b18aa13e8 100644 --- a/scripts/gui/assign-rack.lua +++ b/scripts/gui/assign-rack.lua @@ -1,7 +1,15 @@ -- Assign weapon racks to squads. Requires the weaponrack-unassign patch. --- See bug 1445 for more info about the patches. +--[[=begin +gui/assign-rack +=============== +`This script requires a binpatch `, which has not +been available since DF 0.34.11 + +See :bug:`1445` for more info about the patches. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/autobutcher.lua b/scripts/gui/autobutcher.lua index 013406f33b..59f3733c12 100644 --- a/scripts/gui/autobutcher.lua +++ b/scripts/gui/autobutcher.lua @@ -1,5 +1,11 @@ -- A GUI front-end for the autobutcher plugin. +--[[=begin +gui/autobutcher +=============== +An in-game interface for `autobutcher`. + +=end]] local gui = require 'gui' local utils = require 'utils' local widgets = require 'gui.widgets' diff --git a/scripts/gui/choose-weapons.lua b/scripts/gui/choose-weapons.lua index 85ad62b6e2..f545e1d30b 100644 --- a/scripts/gui/choose-weapons.lua +++ b/scripts/gui/choose-weapons.lua @@ -1,5 +1,20 @@ -- Rewrite individual choice weapons into specific types. +--[[=begin +gui/choose-weapons +================== +Bind to a key (the example config uses :kbd:`Ctrl`:kbd:`W`), and activate in the Equip->View/Customize +page of the military screen. + +Depending on the cursor location, it rewrites all 'individual choice weapon' entries +in the selected squad or position to use a specific weapon type matching the assigned +unit's top skill. If the cursor is in the rightmost list over a weapon entry, it rewrites +only that entry, and does it even if it is not 'individual choice'. + +Rationale: individual choice seems to be unreliable when there is a weapon shortage, +and may lead to inappropriate weapons being selected. + +=end]] local utils = require 'utils' local dlg = require 'gui.dialogs' diff --git a/scripts/gui/clone-uniform.lua b/scripts/gui/clone-uniform.lua index 2257c655f6..9893c38690 100644 --- a/scripts/gui/clone-uniform.lua +++ b/scripts/gui/clone-uniform.lua @@ -1,5 +1,15 @@ -- Clone the current uniform template in the military screen. +--[[=begin +gui/clone-uniform +================= +Bind to a key (the example config uses :kbd:`Ctrl`:kbd:`C`), and activate in the Uniforms +page of the military screen with the cursor in the leftmost list. + +When invoked, the script duplicates the currently selected uniform template, +and selects the newly created copy. + +=end]] local utils = require 'utils' local gui = require 'gui' diff --git a/scripts/gui/companion-order.lua b/scripts/gui/companion-order.lua index bef1e0968a..9d901a4c94 100644 --- a/scripts/gui/companion-order.lua +++ b/scripts/gui/companion-order.lua @@ -1,4 +1,24 @@ +--[[=begin + +gui/companion-order +=================== +A script to issue orders for companions. Select companions with lower case chars, issue orders with upper +case. Must be in look or talk mode to issue command on tile. + +.. image:: /docs/images/companion-order.png + +* move - orders selected companions to move to location. If companions are following they will move no more than 3 tiles from you. +* equip - try to equip items on the ground. +* pick-up - try to take items into hand (also wield) +* unequip - remove and drop equipment +* unwield - drop held items +* wait - temporarily remove from party +* follow - rejoin the party after "wait" +* leave - remove from party (can be rejoined by talking) + +=end]] + local gui = require 'gui' local dlg = require 'gui.dialogs' local args={...} diff --git a/scripts/gui/create-item.lua b/scripts/gui/create-item.lua index 2339c28c2e..b32b91a9bc 100644 --- a/scripts/gui/create-item.lua +++ b/scripts/gui/create-item.lua @@ -4,7 +4,13 @@ -- edited by expwnent --@module = true +--[[=begin +gui/create-item +=============== +A graphical interface for creating items. + +=end]] local function getGenderString(gender) local genderStr if gender==0 then diff --git a/scripts/gui/dfstatus.lua b/scripts/gui/dfstatus.lua index 32758cfbfa..9789affbcd 100644 --- a/scripts/gui/dfstatus.lua +++ b/scripts/gui/dfstatus.lua @@ -1,6 +1,14 @@ -- a quick access status screen -- originally written by enjia2000@gmail.com (stolencatkarma) +--[[=begin + +gui/dfstatus +============ +Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars. +Sections can be enabled/disabled/configured by editing ``dfhack-config/dfstatus.lua``. + +=end]] local gui = require 'gui' function warn(msg) diff --git a/scripts/gui/family-affairs.lua b/scripts/gui/family-affairs.lua new file mode 100644 index 0000000000..51525f36e1 --- /dev/null +++ b/scripts/gui/family-affairs.lua @@ -0,0 +1,296 @@ +-- gui/family-affairs +-- derived from v1.2 @ http://www.bay12forums.com/smf/index.php?topic=147779 +local help = [[=begin + +gui/family-affairs +================== +A user-friendly interface to view romantic relationships, +with the ability to add, remove, or otherwise change them at +your whim - fantastic for depressed dwarves with a dead spouse +(or matchmaking players...). + +The target/s must be alive, sane, and in fortress mode. + +.. image:: /docs/images/family-affairs.png + :align: center + +``gui/family-affairs [unitID]`` + shows GUI for the selected unit, or the specified unit ID + +``gui/family-affairs divorce [unitID]`` + removes all spouse and lover information from the unit + and it's partner, bypassing almost all checks. + +``gui/family-affairs [unitID] [unitID]`` + divorces the two specificed units and their partners, + then arranges for the two units to marry, bypassing + almost all checks. Use with caution. + +=end]] + +local dlg = require ('gui.dialogs') + +function ErrorPopup (msg,color) + if not tostring(msg) then msg = "Error" end + if not color then color = COLOR_LIGHTRED end + dlg.showMessage("Dwarven Family Affairs", msg, color, nil) +end + +function AnnounceAndGamelog (text,l) + if not l then l = true end + dfhack.gui.showAnnouncement(text, _G["COLOR_LIGHTMAGENTA"]) + if l then + local log = io.open('gamelog.txt', 'a') + log:write(text.."\n") + log:close() + end +end + +function ListPrompt (msg, choicelist, bool, yes_func) +dlg.showListPrompt( + "Dwarven Family Affairs", + msg, + COLOR_WHITE, + choicelist, + --called if choice is yes + yes_func, + --called on cancel + function() end, + 15, + bool + ) +end + +function GetMarriageSummary (source) + local familystate = "" + + if source.relations.spouse_id ~= -1 then + if dfhack.units.isSane(df.unit.find(source.relations.spouse_id)) then + familystate = dfhack.TranslateName(source.name).." has a spouse ("..dfhack.TranslateName(df.unit.find(source.relations.spouse_id).name)..")" + end + if dfhack.units.isSane(df.unit.find(source.relations.spouse_id)) == false then + familystate = dfhack.TranslateName(source.name).."'s spouse is dead or not sane, would you like to choose a new one?" + end + end + + if source.relations.spouse_id == -1 and source.relations.lover_id ~= -1 then + if dfhack.units.isSane(df.unit.find(source.relations.lover_id)) then + familystate = dfhack.TranslateName(source.name).." already has a lover ("..dfhack.TranslateName(df.unit.find(source.relations.spouse_id).name)..")" + end + if dfhack.units.isSane(df.unit.find(source.relations.lover_id)) == false then + familystate = dfhack.TranslateName(source.name).."'s lover is dead or not sane, would you like that love forgotten?" + end + end + + if source.relations.spouse_id == -1 and source.relations.lover_id == -1 then + familystate = dfhack.TranslateName(source.name).." is not involved in romantic relationships with anyone" + end + + if source.relations.pregnancy_timer > 0 then + familystate = familystate.."\nShe is pregnant." + local father = df.historical_figure.find(source.relations.pregnancy_spouse) + if father then + familystate = familystate.." The father is "..dfhack.TranslateName(father.name).."." + end + end + + return familystate +end + +function GetSpouseData (source) + local spouse = df.unit.find(source.relations.spouse_id) + local spouse_hf + if spouse then + spouse_hf = df.historical_figure.find (spouse.hist_figure_id) + end + return spouse,spouse_hf +end + +function GetLoverData (source) + local lover = df.unit.find(source.relations.spouse_id) + local lover_hf + if lover then + lover_hf = df.historical_figure.find (lover.hist_figure_id) + end + return lover,lover_hf +end + +function EraseHFLinksLoverSpouse (hf) + for i = #hf.histfig_links-1,0,-1 do + if hf.histfig_links[i]._type == df.histfig_hf_link_spousest or hf.histfig_links[i]._type == df.histfig_hf_link_loverst then + local todelete = hf.histfig_links[i] + hf.histfig_links:erase(i) + todelete:delete() + end + end +end + +function Divorce (source) + local source_hf = df.historical_figure.find(source.hist_figure_id) + local spouse,spouse_hf = GetSpouseData (source) + local lover,lover_hf = GetLoverData (source) + + source.relations.spouse_id = -1 + source.relations.lover_id = -1 + + if source_hf then + EraseHFLinksLoverSpouse (source_hf) + end + if spouse then + spouse.relations.spouse_id = -1 + spouse.relations.lover_id = -1 + end + if lover then + spouse.relations.spouse_id = -1 + spouse.relations.lover_id = -1 + end + if spouse_hf then + EraseHFLinksLoverSpouse (spouse_hf) + end + if lover_hf then + EraseHFLinksLoverSpouse (lover_hf) + end + + local partner = spouse or lover + if not partner then + AnnounceAndGamelog(dfhack.TranslateName(source.name).." is now single") + else + AnnounceAndGamelog(dfhack.TranslateName(source.name).." and "..dfhack.TranslateName(partner.name).." are now single") + end +end + +function Marriage (source,target) + local source_hf = df.historical_figure.find(source.hist_figure_id) + local target_hf = df.historical_figure.find(target.hist_figure_id) + source.relations.spouse_id = target.id + target.relations.spouse_id = source.id + + local new_link = df.histfig_hf_link_spousest:new() -- adding hf link to source + new_link.target_hf = target_hf.id + new_link.link_strength = 100 + source_hf.histfig_links:insert('#',new_link) + + new_link = df.histfig_hf_link_spousest:new() -- adding hf link to target + new_link.target_hf = source_hf.id + new_link.link_strength = 100 + target_hf.histfig_links:insert('#',new_link) +end + +function ChooseNewSpouse (source) + + if not source then + qerror("no unit") return + end + if (source.profession == 103 or source.profession == 104) then + ErrorPopup("target is too young") return + end + if not (source.relations.spouse_id == -1 and source.relations.lover_id == -1) then + ErrorPopup("target already has a spouse or a lover") + qerror("source already has a spouse or a lover") + return + end + + local choicelist = {} + targetlist = {} + + for k,v in pairs (df.global.world.units.active) do + if dfhack.units.isCitizen(v) + and v.race == source.race + and v.sex ~= source.sex + and v.relations.spouse_id == -1 + and v.relations.lover_id == -1 + and not (v.profession == 103 or v.profession == 104) + then + table.insert(choicelist,dfhack.TranslateName(v.name)..', '..dfhack.units.getProfessionName(v)) + table.insert(targetlist,v) + end + end + + if #choicelist > 0 then + ListPrompt( + "Assign new spouse for "..dfhack.TranslateName(source.name), + choicelist, + true, + function(a,b) + local target = targetlist[a] + Marriage (source,target) + AnnounceAndGamelog(dfhack.TranslateName(source.name).." and "..dfhack.TranslateName(target.name).." have married!") + end) + else + ErrorPopup("No suitable candidates") + end +end + +function MainDialog (source) + + local familystate = GetMarriageSummary(source) + + familystate = familystate.."\nSelect action:" + local choicelist = {} + local on_select = {} + + local child = (source.profession == 103 or source.profession == 104) + local is_single = source.relations.spouse_id == -1 and source.relations.lover_id == -1 + local ready_for_marriage = single and not child + + if not child then + table.insert(choicelist,"Remove romantic relationships (if any)") + table.insert(on_select, Divorce) + if ready_for_marriage then + table.insert(choicelist,"Assign a new spouse") + table.insert(on_select,ChooseNewSpouse) + end + if not ready_for_marriage then + table.insert(choicelist,"[Assign a new spouse]") + table.insert(on_select,function () ErrorPopup ("Existing relationships must be removed if you wish to assign a new spouse.") end) + end + else + table.insert(choicelist,"Leave this child alone") + table.insert(on_select,nil) + end + + ListPrompt(familystate, choicelist, false, + function(a,b) if on_select[a] then on_select[a](source) end end) +end + + +local args = {...} + +if args[1] == "help" or args[1] == "?" then print(helpstr) return end + +if not df.global.gamemode == 0 then + print (helpstr) qerror ("invalid gamemode") return +end + +if args[1] == "divorce" and tonumber(args[2]) then + local unit = df.unit.find(args[2]) + if unit then Divorce (unit) return end +end + +if tonumber(args[1]) and tonumber(args[2]) then + local unit1 = df.unit.find(args[1]) + local unit2 = df.unit.find(args[2]) + if unit1 and unit2 then + Divorce (unit1) + Divorce (unit2) + Marriage (unit1,unit2) + return + end +end + +local selected = dfhack.gui.getSelectedUnit(true) +if tonumber(args[1]) then + selected = df.unit.find(tonumber(args[1])) or selected +end + +if selected then + if dfhack.units.isCitizen(selected) and dfhack.units.isSane(selected) then + MainDialog(selected) + else + qerror("You must select sane fortress citizen.") + return + end +else + print (helpstr) + qerror("select a sane fortress dwarf") +end diff --git a/scripts/gui/gm-editor.lua b/scripts/gui/gm-editor.lua index 817c561387..c2d371525a 100644 --- a/scripts/gui/gm-editor.lua +++ b/scripts/gui/gm-editor.lua @@ -1,4 +1,24 @@ -- Interface powered item editor. + +--[[=begin + +gui/gm-editor +============= +This editor allows to change and modify almost anything in df. Press :kbd:`?` for +in-game help. There are three ways to open this editor: + +* Callling ``gui/gm-editor`` from a command or keybinding opens the editor + on whatever is selected or viewed (e.g. unit/item description screen) + +* using gui/gm-editor - executes lua command and opens editor on + its results (e.g. ``gui/gm-editor "df.global.world.items.all"`` shows all items) + +* using gui/gm-editor dialog - shows an in game dialog to input lua command. Works + the same as version above. + +.. image:: /docs/images/gm-editor.png + +=end]] local gui = require 'gui' local dialog = require 'gui.dialogs' local widgets =require 'gui.widgets' diff --git a/scripts/gui/gm-unit.lua b/scripts/gui/gm-unit.lua index 4855527293..e25ebf944e 100644 --- a/scripts/gui/gm-unit.lua +++ b/scripts/gui/gm-unit.lua @@ -1,4 +1,12 @@ -- Interface powered (somewhat user friendly) unit editor. + +--[[=begin + +gui/gm-unit +=========== +An editor for various unit attributes. + +=end]] local gui = require 'gui' local dialog = require 'gui.dialogs' local widgets =require 'gui.widgets' diff --git a/scripts/gui/guide-path.lua b/scripts/gui/guide-path.lua index a807e032d4..aa77c9deae 100644 --- a/scripts/gui/guide-path.lua +++ b/scripts/gui/guide-path.lua @@ -1,5 +1,17 @@ -- Show and manipulate the path used by Guide Cart orders. +--[[=begin +gui/guide-path +============== +Bind to a key (the example config uses :kbd:`Alt`:kbd:`P`), and activate in the Hauling menu with +the cursor over a Guide order. + +.. image:: /docs/images/guide-path.png + +The script displays the cached path that will be used by the order; the game +computes it when the order is executed for the first time. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/hack-wish.lua b/scripts/gui/hack-wish.lua index 023ef9321c..de423abc26 100644 --- a/scripts/gui/hack-wish.lua +++ b/scripts/gui/hack-wish.lua @@ -1 +1,8 @@ --@ alias = 'gui/create-item' +--[[=begin + +gui/hack-wish +============= +An alias for `gui/create-item`. Deprecated. + +=end]] \ No newline at end of file diff --git a/scripts/gui/hello-world.lua b/scripts/gui/hello-world.lua index 122f2cd386..324aa11ad5 100644 --- a/scripts/gui/hello-world.lua +++ b/scripts/gui/hello-world.lua @@ -1,5 +1,11 @@ -- Test lua viewscreens. +--[[=begin +gui/hello-world +=============== +A basic example for testing, or to start your own script from. + +=end]] local gui = require 'gui' local text = 'Woohoo, lua viewscreen :)' diff --git a/scripts/gui/liquids.lua b/scripts/gui/liquids.lua index 322ae69524..51ebca4bf0 100644 --- a/scripts/gui/liquids.lua +++ b/scripts/gui/liquids.lua @@ -1,5 +1,36 @@ -- Interface front-end for liquids plugin. +--[[=begin +gui/liquids +=========== +To use, bind to a key (the example config uses Alt-L) and activate in the :kbd:`k` mode. + +.. image:: /docs/images/liquids.png + +This script is a gui front-end to `liquids` and works similarly, +allowing you to add or remove water & magma, and create obsidian walls & floors. + +.. warning:: + + There is **no undo support**. Bugs in this plugin have been + known to create pathfinding problems and heat traps. + +The :kbd:`b` key changes how the affected area is selected. The default :guilabel:`Rectangle` +mode works by selecting two corners like any ordinary designation. The :kbd:`p` +key chooses between adding water, magma, obsidian walls & floors, or just +tweaking flags. + +When painting liquids, it is possible to select the desired level with :kbd:`+`:kbd:`-`, +and choose between setting it exactly, only increasing or only decreasing +with :kbd:`s`. + +In addition, :kbd:`f` allows disabling or enabling the flowing water computations +for an area, and :kbd:`r` operates on the "permanent flow" property that makes +rivers power water wheels even when full and technically not flowing. + +After setting up the desired operations using the described keys, use :kbd:`Enter` to apply them. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/mechanisms.lua b/scripts/gui/mechanisms.lua index 607625524e..d65782469d 100644 --- a/scripts/gui/mechanisms.lua +++ b/scripts/gui/mechanisms.lua @@ -1,5 +1,22 @@ -- Shows mechanisms linked to the current building. +--[[=begin +gui/mechanisms +============== +To use, bind to a key (the example config uses :kbd:`Ctrl`:kbd:`M`) +and activate in :kbd:`q` mode. + +.. image:: /docs/images/mechanisms.png + +Lists mechanisms connected to the building, and their links. Navigating +the list centers the view on the relevant linked buildings. + +To exit, press :kbd:`Esc` or :kbd:`Enter`; :kbd:`Esc` recenters on +the original building, while :kbd:`Enter` leaves focus on the current +one. :kbd:`Shift`:kbd:`Enter` has an effect equivalent to pressing +:kbd:`Enter`, and then re-entering the mechanisms UI. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/mod-manager.lua b/scripts/gui/mod-manager.lua index 2f2aa92ba7..692deeb621 100644 --- a/scripts/gui/mod-manager.lua +++ b/scripts/gui/mod-manager.lua @@ -1,7 +1,20 @@ -- a graphical mod manager for df local gui=require 'gui' local widgets=require 'gui.widgets' +--[[=begin +gui/mod-manager +=============== +A simple way to install and remove small mods. + +It looks for specially formatted mods in :file:`{}/mods/`. Mods are not +included, but some examples are `available here`_. + +.. _`available here`: https://github.com/warmist/df-mini-mods + +.. image:: /docs/images/mod-manager.png + +=end]] local entity_file=dfhack.getDFPath().."/raw/objects/entity_default.txt" local init_file=dfhack.getDFPath().."/raw/init.lua" local mod_dir=dfhack.getDFPath().."/hack/mods" diff --git a/scripts/gui/no-dfhack-init.lua b/scripts/gui/no-dfhack-init.lua index f6171d5c79..c4352211dd 100644 --- a/scripts/gui/no-dfhack-init.lua +++ b/scripts/gui/no-dfhack-init.lua @@ -1,5 +1,11 @@ -- Shows the warning about missing configuration file. +--[[=begin +gui/no-dfhack-init +================== +Shows a warning at startup if no valid :file:`dfhack.init` file is found. + +=end]] local gui = require 'gui' local dlg = require 'gui.dialogs' diff --git a/scripts/gui/power-meter.lua b/scripts/gui/power-meter.lua index ac30c92730..ac10e5dc7e 100644 --- a/scripts/gui/power-meter.lua +++ b/scripts/gui/power-meter.lua @@ -1,5 +1,20 @@ -- Interface front-end for power-meter plugin. +--[[=begin +gui/power-meter +=============== +An in-game interface for `power-meter`. + +Bind it to a key (default :kbd:`Ctrl`:kbd:`Shift`:kbd:`M`) and activate +after selecting Pressure Plate in the build menu. + +.. image:: /docs/images/power-meter.png + +The script follows the general look and feel of the regular pressure +plate build configuration page, but configures parameters relevant to +the modded power meter building. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/rename.lua b/scripts/gui/rename.lua index 70a09b2fab..3433f48815 100644 --- a/scripts/gui/rename.lua +++ b/scripts/gui/rename.lua @@ -1,5 +1,35 @@ -- Rename various objects via gui. +--[[=begin +gui/rename +========== +Backed by `rename`, this script allows entering the desired name +via a simple dialog in the game ui. + +* ``gui/rename [building]`` in :kbd:`q` mode changes the name of a building. + + .. image:: /docs/images/rename-bld.png + + The selected building must be one of stockpile, workshop, furnace, trap, or siege engine. + It is also possible to rename zones from the :kbd:`i` menu. + +* ``gui/rename [unit]`` with a unit selected changes the nickname. + + Unlike the built-in interface, this works even on enemies and animals. + +* ``gui/rename unit-profession`` changes the selected unit's custom profession name. + + .. image:: /docs/images/rename-prof.png + + Likewise, this can be applied to any unit, and when used on animals it overrides + their species string. + +The ``building`` or ``unit`` options are automatically assumed when in relevant UI state. + +The example config binds building/unit rename to :kbd:`Ctrl`:kbd:`Shift`:kbd:`N`, and +unit profession change to :kbd:`Ctrl`:kbd:`Shift`:kbd:`T`. + +=end]] local gui = require 'gui' local dlg = require 'gui.dialogs' local plugin = require 'plugins.rename' diff --git a/scripts/gui/room-list.lua b/scripts/gui/room-list.lua index 1f3e663da4..ac68903178 100644 --- a/scripts/gui/room-list.lua +++ b/scripts/gui/room-list.lua @@ -1,5 +1,17 @@ -- Browses rooms owned by a unit. +--[[=begin +gui/room-list +============= +To use, bind to a key (the example config uses :kbd:`Alt`:kbd:`R`) and activate in :kbd:`q` mode, +either immediately or after opening the assign owner page. + +.. image:: /docs/images/room-list.png + +The script lists other rooms owned by the same owner, or by the unit selected in the assign +list, and allows unassigning them. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/siege-engine.lua b/scripts/gui/siege-engine.lua index 1e52008758..8ebfe0dc49 100644 --- a/scripts/gui/siege-engine.lua +++ b/scripts/gui/siege-engine.lua @@ -1,5 +1,42 @@ -- Front-end for the siege engine plugin. +--[[=begin +gui/siege-engine +================ +An in-game interface for `siege-engine`. + +Bind it to a key (the example config uses :kbd:`Alt`:kbd:`a`) and +activate after selecting a siege engine in :kbd:`q` mode. + +.. image:: /docs/images/siege-engine.png + +The main mode displays the current target, selected ammo item +type, linked stockpiles and the allowed operator skill range. The +map tile color is changed to signify if it can be hit by the +selected engine: green for fully reachable, blue for out of +range, red for blocked, yellow for partially blocked. + +Pressing :kbd:`r` changes into the target selection mode, which +works by highlighting two points with :kbd:`Enter` like all +designations. When a target area is set, the engine projectiles +are aimed at that area, or units within it (this doesn't actually +change the original aiming code, instead the projectile +trajectory parameters are rewritten as soon as it appears). + +After setting the target in this way for one engine, you can +'paste' the same area into others just by pressing :kbd:`p` in +the main page of this script. The area to paste is kept until you +quit DF, or select another area manually. + +Pressing :kbd:`t` switches to a mode for selecting a stockpile to +take ammo from. + +Exiting from the siege engine script via :kbd:`Esc` reverts the +view to the state prior to starting the script. +:kbd:`Shift`:kbd:`Esc` retains the current viewport, and also +exits from the :kbd:`q` mode to main menu. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/stockpiles.lua b/scripts/gui/stockpiles.lua index 638ae2894e..4e2f28281a 100644 --- a/scripts/gui/stockpiles.lua +++ b/scripts/gui/stockpiles.lua @@ -1,5 +1,22 @@ -- lave/load stockpile settings with a GUI +--[[=begin +gui/stockpiles +============== +An in-game interface for `stocksettings`, to +load and save stockpile settings from the :kbd:`q` menu. + +Usage: + +:gui/stockpiles -save: to save the current stockpile +:gui/stockpiles -load: to load settings into the current stockpile +:gui/stockpiles -dir : set the default directory to save settings into +:gui/stockpiles -help: to see this message + +Don't forget to ``enable stockpiles`` and create the ``stocksettings`` directory in +the DF folder before trying to use the GUI. + +=end]] local stock = require 'plugins.stockpiles' function check_enabled() diff --git a/scripts/gui/unit-info-viewer.lua b/scripts/gui/unit-info-viewer.lua index 8e42a86c8e..1d7cb763d4 100644 --- a/scripts/gui/unit-info-viewer.lua +++ b/scripts/gui/unit-info-viewer.lua @@ -3,7 +3,14 @@ -- version 1.04 -- original author: Kurik Amudnil -- edited by expwnent +--[[=begin +gui/unit-info-viewer +==================== +Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size, +and death info about a unit. Recommended keybinding :kbd:`Alt`:kbd:`I`. + +=end]] local gui = require 'gui' local widgets =require 'gui.widgets' local utils = require 'utils' diff --git a/scripts/gui/workflow.lua b/scripts/gui/workflow.lua index 77a87c9ce3..6dda9e7648 100644 --- a/scripts/gui/workflow.lua +++ b/scripts/gui/workflow.lua @@ -1,5 +1,68 @@ -- A GUI front-end for the workflow plugin. +--[[=begin +gui/workflow +============ +Bind to a key (the example config uses Alt-W), and activate with a job selected +in a workshop in :kbd:`q` mode. + +.. image:: /docs/images/workflow.png + +This script provides a simple interface to constraints managed by `workflow`. +When active, it displays a list of all constraints applicable to the +current job, and their current status. + +A constraint specifies a certain range to be compared against either individual +*item* or whole *stack* count, an item type and optionally a material. When the +current count is below the lower bound of the range, the job is resumed; if it +is above or equal to the top bound, it will be suspended. Within the range, the +specific constraint has no effect on the job; others may still affect it. + +Pressing :kbd:`i` switches the current constraint between counting stacks or items. +Pressing :kbd:`r` lets you input the range directly; +:kbd:`e`, :kbd:`r`, :kbd:`d`, :kbd:`f` adjust the +bounds by 5, 10, or 20 depending on the direction and the :kbd:`i` setting (counting +items and expanding the range each gives a 2x bonus). + +Pressing :kbd:`a` produces a list of possible outputs of this job as guessed by +workflow, and lets you create a new constraint by choosing one as template. If you +don't see the choice you want in the list, it likely means you have to adjust +the job material first using `job` ``item-material`` or `gui/workshop-job`, +as described in the `workflow` documentation. In this manner, this feature +can be used for troubleshooting jobs that don't match the right constraints. + +.. image:: /docs/images/workflow-new1.png + +If you select one of the outputs with :kbd:`Enter`, the matching constraint is simply +added to the list. If you use :kbd:`Shift`:kbd:`Enter`, the interface proceeds to the +next dialog, which allows you to edit the suggested constraint parameters to +suit your need, and set the item count range. + +.. image:: /docs/images/workflow-new2.png + +Pressing :kbd:`s` (or, with the example config, Alt-W in the :kbd:`z` stocks screen) +opens the overall status screen: + +.. image:: /docs/images/workflow-status.png + +This screen shows all currently existing workflow constraints, and allows +monitoring and/or changing them from one screen. The constraint list can +be filtered by typing text in the field below. + +The color of the stock level number indicates how "healthy" the stock level +is, based on current count and trend. Bright green is very good, green is good, +red is bad, bright red is very bad. + +The limit number is also color-coded. Red means that there are currently no +workshops producing that item (i.e. no jobs). If it's yellow, that means the +production has been delayed, possibly due to lack of input materials. + +The chart on the right is a plot of the last 14 days (28 half day plots) worth +of stock history for the selected item, with the rightmost point representing +the current stock value. The bright green dashed line is the target +limit (maximum) and the dark green line is that minus the gap (minimum). + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/workshop-job.lua b/scripts/gui/workshop-job.lua index c4e2036142..f3af15d10b 100644 --- a/scripts/gui/workshop-job.lua +++ b/scripts/gui/workshop-job.lua @@ -1,5 +1,53 @@ -- Show and modify properties of jobs in a workshop. +--[[=begin +gui/workshop-job +================ +Bind to a key (the example config uses :kbd:`Alt`:kbd:`a`), and activate with a job selected in +a workshop in the :kbd:`q` mode. + +.. image:: /docs/images/workshop-job.png + +The script shows a list of the input reagents of the selected job, and allows changing +them like the `job` ``item-type`` and `job` ``item-material`` commands. + +Specifically, pressing the :kbd:`i` key pops up a dialog that lets you select an item +type from a list. + +.. image:: /docs/images/workshop-job-item.png + +Pressing :kbd:`m`, unless the item type does not allow a material, +lets you choose a material. + +.. image:: /docs/images/workshop-job-material.png + +Since there are a lot more materials than item types, this dialog is more complex +and uses a hierarchy of sub-menus. List choices that open a sub-menu are marked +with an arrow on the left. + +.. warning:: + + Due to the way input reagent matching works in DF, you must select an item type + if you select a material, or the material will be matched incorrectly in some cases. + If you press :kbd:`m` without choosing an item type, the script will auto-choose + if there is only one valid choice, or pop up an error message box instead of the + material selection dialog. + +Note that both materials and item types presented in the dialogs are filtered +by the job input flags, and even the selected item type for material selection, +or material for item type selection. Many jobs would let you select only one +input item type. + +For example, if you choose a *plant* input item type for your prepare meal job, +it will only let you select cookable materials. + +If you choose a *barrel* item instead (meaning things stored in barrels, like +drink or milk), it will let you select any material, since in this case the +material is matched against the barrel itself. Then, if you select, say, iron, +and then try to change the input item type, now it won't let you select *plant*; +you have to unset the material first. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/hfs-pit.lua b/scripts/hfs-pit.lua index e2caf77797..c335ae2be8 100644 --- a/scripts/hfs-pit.lua +++ b/scripts/hfs-pit.lua @@ -1,5 +1,22 @@ -- Creates a pit under the target leading straight to the Underworld. Type '?' for help. -- Based on script by IndigoFenix, @ https://gist.github.com/IndigoFenix/8776696 +--[[=begin + +hfs-pit +======= +Creates a pit to the underworld at the cursor. + +Takes three arguments: diameter of the pit in tiles, whether to wall off +the pit, and whether to insert stairs. If no arguments are given, the default +is ``hfs-pit 1 0 0``, ie single-tile wide with no walls or stairs.:: + + hfs-pit 4 0 1 + hfs-pit 2 1 0 + +First example is a four-across pit with stairs but no walls; second is a +two-across pit with stairs but no walls. + +=end]] args={...} diff --git a/scripts/hotkey-notes.lua b/scripts/hotkey-notes.lua index 2b713e6bb1..428a02d640 100644 --- a/scripts/hotkey-notes.lua +++ b/scripts/hotkey-notes.lua @@ -1,4 +1,11 @@ -- prints info on assigned hotkeys to the console +--[[=begin + +hotkey-notes +============ +Lists the key, name, and jump position of your hotkeys in the DFHack console. + +=end]] for i=1, #df.global.ui.main.hotkeys do local hk = df.global.ui.main.hotkeys[i-1] diff --git a/scripts/item-descriptions.lua b/scripts/item-descriptions.lua index 9ce970c95b..fe7e7ac00f 100644 --- a/scripts/item-descriptions.lua +++ b/scripts/item-descriptions.lua @@ -1,5 +1,14 @@ -- Holds custom descriptions for view-item-info -- By PeridexisErrant +--[[=begin + +item-descriptions +================= +Exports a table with custom description text for every item in the game. +Used by `view-item-info`; see instructions there for how to override +for mods. + +=end]] -- Each line near the bottom has 53 characters of room until -- it starts clipping over the UI in an ugly fashion. diff --git a/scripts/lever.rb b/scripts/lever.rb index 6cbf38e6f2..05a159861c 100644 --- a/scripts/lever.rb +++ b/scripts/lever.rb @@ -1,4 +1,22 @@ # control your levers from the dfhack console +=begin + +lever +===== +Allow manipulation of in-game levers from the dfhack console. + +Can list levers, including state and links, with:: + + lever list + +To queue a job so that a dwarf will pull the lever 42, use ``lever pull 42``. +This is the same as :kbd:`q` querying the building and queue a :kbd:`P` pull request. + +To magically toggle the lever immediately, use:: + + lever pull 42 --now + +=end def lever_pull_job(bld) ref = DFHack::GeneralRefBuildingHolderst.cpp_new diff --git a/scripts/locate-ore.rb b/scripts/locate-ore.rb index 00ca8b87a0..1d204579ad 100644 --- a/scripts/locate-ore.rb +++ b/scripts/locate-ore.rb @@ -1,4 +1,22 @@ # scan the map for ore veins +=begin + +locate-ore +========== +Scan the map for metal ores. + +Finds and designate for digging one tile of a specific metal ore. +Only works for native metal ores, does not handle reaction stuff (eg STEEL). + +When invoked with the ``list`` argument, lists metal ores available on the map. + +Examples:: + + locate-ore list + locate-ore hematite + locate-ore iron + +=end target_ore = $script_args[0] diff --git a/scripts/log-region.lua b/scripts/log-region.lua index 31cdaf7824..733b2aea6d 100644 --- a/scripts/log-region.lua +++ b/scripts/log-region.lua @@ -1,5 +1,14 @@ -- On map load writes information about the loaded region to gamelog.txt -- By Kurik Amudnil and Warmist (http://www.bay12forums.com/smf/index.php?topic=91166.msg4467072#msg4467072) +--[[=begin + +log-region +========== +When enabled in :file:`dfhack.init`, each time a fort is loaded identifying information +will be written to the gamelog. Assists in parsing the file if you switch +between forts, and adds information for story-building. + +=end]] local function write_gamelog(msg) local log = io.open('gamelog.txt', 'a') diff --git a/scripts/lua.lua b/scripts/lua.lua index a4a5dd22f2..2183eaaddc 100644 --- a/scripts/lua.lua +++ b/scripts/lua.lua @@ -1,4 +1,28 @@ -- Execute lua commands interactively or from files. +--[[=begin + +lua +=== +There are the following ways to invoke this command: + +1. ``lua`` (without any parameters) + + This starts an interactive lua interpreter. + +2. ``lua -f "filename"`` or ``lua --file "filename"`` + + This loads and runs the file indicated by filename. + +3. ``lua -s ["filename"]`` or ``lua --save ["filename"]`` + + This loads and runs the file indicated by filename from the save + directory. If the filename is not supplied, it loads "dfhack.lua". + +4. ``:lua`` *lua statement...* + + Parses and executes the lua statement like the interactive interpreter would. + +=end]] local args={...} local cmd = args[1] diff --git a/scripts/make-legendary.lua b/scripts/make-legendary.lua index a3dc6a9575..6dfc782771 100644 --- a/scripts/make-legendary.lua +++ b/scripts/make-legendary.lua @@ -1,8 +1,16 @@ -- This script will modify a skill or the skills of a single unit --- usage is: target a unit in DF, and execute this script in dfhack -- the skill will be increased to 20 (Legendary +5) --- arguments 'list', 'classes' and 'all' added -- by vjek +--[[=begin + +make-legendary +============== +Makes the selected dwarf legendary in one skill, a group of skills, or all +skills. View groups with ``make-legendary classes``, or all skills with +``make-legendary list``. Use ``make-legendary MINING`` when you need something +dug up, or ``make-legendary all`` when only perfection will do. + +=end]] -- this function will return the number of elements, starting at zero. -- useful for counting things where #foo doesn't work diff --git a/scripts/make-monarch.lua b/scripts/make-monarch.lua index 967225589e..1c8764367b 100644 --- a/scripts/make-monarch.lua +++ b/scripts/make-monarch.lua @@ -1,4 +1,12 @@ --set target unit as king/queen +--[[=begin + +make-monarch +============ +Make the selected unit King or Queen of your civilisation. + +=end]] + local unit=dfhack.gui.getSelectedUnit() if not unit then qerror("No unit selected") end local newfig=dfhack.units.getNemesis(unit).figure diff --git a/scripts/markdown.lua b/scripts/markdown.lua index e47e598623..8cd2255733 100644 --- a/scripts/markdown.lua +++ b/scripts/markdown.lua @@ -1,6 +1,14 @@ -- Save a copy of a text screen in markdown (for reddit among others). Use 'markdown help' for more details. -- This is a derivatiwe work based upon scripts/forum-dwarves.lua by Caldfir and expwnent -- Adapted for markdown by Mchl https://github.com/Mchl +--[[=begin + +markdown +======== +Save a copy of a text screen in markdown (for reddit among others). +Use ``markdown help`` for more details. + +=end]] local args = {...} diff --git a/scripts/masspit.rb b/scripts/masspit.rb index e391509fb8..9c276faf52 100644 --- a/scripts/masspit.rb +++ b/scripts/masspit.rb @@ -1,4 +1,15 @@ # pit all caged creatures in a zone +=begin + +masspit +======= +Designate all creatures in cages on top of a pit/pond activity zone for pitting. +Works best with an animal stockpile on top of the zone. + +Works with a zone number as argument (eg ``Activity Zone #6`` -> ``masspit 6``) +or with the game cursor on top of the area. + +=end case $script_args[0] when '?', 'help' diff --git a/scripts/migrants-now.lua b/scripts/migrants-now.lua index 22719be199..b38e381158 100644 --- a/scripts/migrants-now.lua +++ b/scripts/migrants-now.lua @@ -1,2 +1,16 @@ -- Force a migrant wave (only works after hardcoded waves) ---@alias = 'devel/migrants-now' +--[[=begin + +migrants-now +============ +Forces an immediate migrant wave. Only works after migrants have +arrived naturally. Equivalent to `modtools/force` ``-eventType migrants`` + +=end]] +df.global.timed_events:insert('#',{ + new = true, + type = df.timed_event_type.Migrants, + season = df.global.cur_season, + season_ticks = df.global.cur_season_tick+1, + entity = df.historical_entity.find(df.global.ui.civ_id) +}) diff --git a/scripts/modtools/about.txt b/scripts/modtools/about.txt new file mode 100644 index 0000000000..d2924b301f --- /dev/null +++ b/scripts/modtools/about.txt @@ -0,0 +1,17 @@ +``modtools/*`` scripts provide tools for modders, often with changes +to the raw files, and are not intended to be called manually by end-users. + +These scripts are mostly useful for raw modders and scripters. They all have +standard arguments: arguments are of the form ``tool -argName1 argVal1 +-argName2 argVal2``. This is equivalent to ``tool -argName2 argVal2 -argName1 +argVal1``. It is not necessary to provide a value to an argument name: ``tool +-argName3`` is fine. Supplying the same argument name multiple times will +result in an error. Argument names are preceded with a dash. The ``-help`` +argument will print a descriptive usage string describing the nature of the +arguments. For multiple word argument values, brackets must be used: ``tool +-argName4 [ sadf1 sadf2 sadf3 ]``. In order to allow passing literal braces as +part of the argument, backslashes are used: ``tool -argName4 [ \] asdf \foo ]`` +sets ``argName4`` to ``\] asdf foo``. The ``*-trigger`` scripts have a similar +policy with backslashes. + +Any of these scripts can be called with ``-help`` for more information. diff --git a/scripts/modtools/add-syndrome.lua b/scripts/modtools/add-syndrome.lua index e151e1701b..4c04b05bd9 100644 --- a/scripts/modtools/add-syndrome.lua +++ b/scripts/modtools/add-syndrome.lua @@ -1,7 +1,12 @@ --modtools/add-syndrome.lua --author expwnent ---add syndromes to a target, or remove them +--[[=begin +modtools/add-syndrome +===================== +This allows adding and removing syndromes from units. + +=end]] local syndromeUtil = require 'syndrome-util' local utils = require 'utils' diff --git a/scripts/modtools/anonymous-script.lua b/scripts/modtools/anonymous-script.lua index 8e3ae1e7b9..3aecb918cf 100644 --- a/scripts/modtools/anonymous-script.lua +++ b/scripts/modtools/anonymous-script.lua @@ -1,9 +1,19 @@ --scripts/modtools/anonymous-script.lua --author expwnent --a tool for invoking simple lua scripts without putting them in a file first ---anonymous-script "print(args[1])" arg1 arg2 ---# prints "arg1" +--[[=begin +modtools/anonymous-script +========================= +This allows running a short simple Lua script passed as an argument instead of +running a script from a file. This is useful when you want to do something too +complicated to make with the existing modtools, but too simple to be worth its +own script file. Example:: + + anonymous-script "print(args[1])" arg1 arg2 + # prints "arg1" + +=end]] local args = {...} --automatically collect arguments to make the anonymous script more succinct diff --git a/scripts/modtools/create-item.lua b/scripts/modtools/create-item.lua index b7c88bb45f..92d8e25a7e 100644 --- a/scripts/modtools/create-item.lua +++ b/scripts/modtools/create-item.lua @@ -1,7 +1,14 @@ --scripts/modtools/create-item.lua --author expwnent --creates an item of a given type and material +--[[=begin +modtools/create-item +==================== +Replaces the `createitem` plugin, with standard +arguments. The other versions will be phased out in a later version. + +=end]] local utils = require 'utils' validArgs = --[[validArgs or--]] utils.invert({ diff --git a/scripts/modtools/create-unit.lua b/scripts/modtools/create-unit.lua index 22a4dee9d5..b1e604e7ff 100644 --- a/scripts/modtools/create-unit.lua +++ b/scripts/modtools/create-unit.lua @@ -12,6 +12,13 @@ set invasion_id, etc announcement for fake natural birth if appropriate ]] +--[[=begin + +modtools/create-unit +==================== +Creates a unit. Use ``modtools/create-unit -help`` for more info. + +=end]] --[[ if dfhack.gui.getCurViewscreen()._type ~= df.viewscreen_dwarfmodest or df.global.ui.main.mode ~= df.ui_sidebar_mode.LookAround then diff --git a/scripts/modtools/equip-item.lua b/scripts/modtools/equip-item.lua index 492fe2b1b8..359d983d68 100644 --- a/scripts/modtools/equip-item.lua +++ b/scripts/modtools/equip-item.lua @@ -1,6 +1,13 @@ -- modtools/equip-item.lua -- equip an item on a unit with a particular body part +--[[=begin +modtools/equip-item +=================== +Force a unit to equip an item with a particular body part; useful in +conjunction with the ``create`` scripts above. See also `forceequip`. + +=end]] local utils = require 'utils' function equipItem(unit, item, bodyPart, mode) diff --git a/scripts/modtools/force.lua b/scripts/modtools/force.lua index 2930d29302..2ae5300fae 100644 --- a/scripts/modtools/force.lua +++ b/scripts/modtools/force.lua @@ -2,7 +2,13 @@ -- author Putnam -- edited by expwnent -- Forces an event. +--[[=begin +modtools/force +============== +This tool triggers events like megabeasts, caravans, invaders, and migrants. + +=end]] local utils = require 'utils' local function findCiv(arg) diff --git a/scripts/modtools/interaction-trigger.lua b/scripts/modtools/interaction-trigger.lua index 10eca5d4ea..bf3a1c4f7e 100644 --- a/scripts/modtools/interaction-trigger.lua +++ b/scripts/modtools/interaction-trigger.lua @@ -1,7 +1,16 @@ --scripts/modtools/interaction-trigger.lua --author expwnent --triggers scripts when a unit does a unit interaction on another +--[[=begin +modtools/interaction-trigger +============================ +This triggers events when a unit uses an interaction on another. It works by +scanning the announcements for the correct attack verb, so the attack verb +must be specified in the interaction. It includes an option to suppress this +announcement after it finds it. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/invader-item-destroyer.lua b/scripts/modtools/invader-item-destroyer.lua index 2ec5eb5825..425d910e23 100644 --- a/scripts/modtools/invader-item-destroyer.lua +++ b/scripts/modtools/invader-item-destroyer.lua @@ -1,7 +1,14 @@ --scripts/modtools/invader-item-destroyer.lua --author expwnent --configurably deletes invader items when they die +--[[=begin +modtools/invader-item-destroyer +=============================== +This tool configurably destroys invader items to prevent clutter or to prevent +the player from getting tools exclusive to certain races. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/item-trigger.lua b/scripts/modtools/item-trigger.lua index c7f9c6d18e..78c8a43323 100644 --- a/scripts/modtools/item-trigger.lua +++ b/scripts/modtools/item-trigger.lua @@ -2,7 +2,15 @@ --author expwnent --based on itemsyndrome by Putnam --triggers scripts when a unit attacks another with a weapon type, a weapon of a particular material, or a weapon contaminated with a particular material, or when a unit equips/unequips a particular item type, an item of a particular material, or an item contaminated with a particular material +--[[=begin +modtools/item-trigger +===================== +This powerful tool triggers DFHack commands when a unit equips, unequips, or +attacks another unit with specified item types, specified item materials, or +specified item contaminants. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/moddable-gods.lua b/scripts/modtools/moddable-gods.lua index acdbd4a24f..c044d6c0af 100644 --- a/scripts/modtools/moddable-gods.lua +++ b/scripts/modtools/moddable-gods.lua @@ -1,7 +1,14 @@ --scripts/modtools/moddable-gods.lua --based on moddableGods by Putnam --edited by expwnent +--[[=begin +modtools/moddable-gods +====================== +This is a standardized version of Putnam's moddableGods script. It allows you +to create gods on the command-line. + +=end]] local utils = require 'utils' validArgs = validArgs or utils.invert({ diff --git a/scripts/modtools/outside-only.lua b/scripts/modtools/outside-only.lua index 5d2279f60e..9572f8932f 100644 --- a/scripts/modtools/outside-only.lua +++ b/scripts/modtools/outside-only.lua @@ -1,7 +1,15 @@ --scripts/modtools/outsideOnly.lua --author expwnent --enables outside only and inside only buildings +--[[=begin +modtools/outside-only +===================== +This allows you to specify certain custom buildings as outside only, or inside +only. If the player attempts to build a building in an inappropriate location, +the building will be destroyed. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/projectile-trigger.lua b/scripts/modtools/projectile-trigger.lua index 02dfb769a1..c20e8231fb 100644 --- a/scripts/modtools/projectile-trigger.lua +++ b/scripts/modtools/projectile-trigger.lua @@ -2,7 +2,13 @@ --author expwnent --based on Putnam's projectileExpansion --TODO: trigger based on contaminants +--[[=begin +modtools/projectile-trigger +=========================== +This triggers dfhack commands when projectiles hit their targets. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/random-trigger.lua b/scripts/modtools/random-trigger.lua index 4ad6813c19..a762d2dc49 100644 --- a/scripts/modtools/random-trigger.lua +++ b/scripts/modtools/random-trigger.lua @@ -1,7 +1,16 @@ --scripts/modtools/random-trigger.lua --triggers random scripts ---register a few scripts, then tell it to "go" and it will pick a random one based on the probability weights you specified. outcomes are mutually exclusive. To make independent random events, call the script multiple times. +--[[=begin +modtools/random-trigger +======================= +This triggers random dfhack commands with specified probabilities. +Register a few scripts, then tell it to "go" and it will pick one +based on the probability weights you specified. Outcomes are mutually +exclusive. To make independent random events, call the script multiple +times. + +=end]] local utils = require 'utils' local eventful = require 'plugins.eventful' diff --git a/scripts/modtools/reaction-product-trigger.lua b/scripts/modtools/reaction-product-trigger.lua index bc1cc5a482..fb6ba3029c 100644 --- a/scripts/modtools/reaction-product-trigger.lua +++ b/scripts/modtools/reaction-product-trigger.lua @@ -2,7 +2,14 @@ -- author expwnent -- trigger commands just before and after custom reactions produce items --@ module = true +--[[=begin +modtools/reaction-product-trigger +================================= +This triggers dfhack commands when reaction products are produced, once per +product. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/reaction-trigger-transition.lua b/scripts/modtools/reaction-trigger-transition.lua index 9e26758c2d..42f75f461f 100644 --- a/scripts/modtools/reaction-trigger-transition.lua +++ b/scripts/modtools/reaction-trigger-transition.lua @@ -1,8 +1,18 @@ -- scripts/modtools/reaction-trigger-transition.lua -- author expwnent --- prints useful things to the console and a file to help modders transition from autoSyndrome to reaction-trigger --- this script is basically an apology for breaking backward compatibiility +--[[=begin +modtools/reaction-trigger-transition +==================================== +Scans raw files and creates a file to help modders transition from +autoSyndrome to reaction-trigger. + +Prints useful things to the console and a file to help modders +transition from autoSyndrome to reaction-trigger. This script +is basically an apology for breaking backward compatibiility, +and will be removed eventually. + +=end]] local function maybeQuote(str) if str == '' or string.find(str,' ') then return ('"' .. str .. '"') diff --git a/scripts/modtools/reaction-trigger.lua b/scripts/modtools/reaction-trigger.lua index 93b5b0d2a2..ef20fa2e02 100644 --- a/scripts/modtools/reaction-trigger.lua +++ b/scripts/modtools/reaction-trigger.lua @@ -2,7 +2,15 @@ -- author expwnent -- replaces autoSyndrome: trigger commands when custom reactions are completed --@ module = true +--[[=begin +modtools/reaction-trigger +========================= +Triggers dfhack commands when custom reactions complete, regardless of whether +it produced anything, once per completion. Use the ``-help`` command +for more information. + +=end]] local eventful = require 'plugins.eventful' local syndromeUtil = require 'syndrome-util' local utils = require 'utils' diff --git a/scripts/modtools/skill-change.lua b/scripts/modtools/skill-change.lua index 7cdd4de677..55670fc902 100644 --- a/scripts/modtools/skill-change.lua +++ b/scripts/modtools/skill-change.lua @@ -3,7 +3,21 @@ --based on skillChange.lua by Putnam --TODO: update skill level once experience increases/decreases --TODO: skill rust? +--[[=begin +modtools/skill-change +===================== +Sets or modifies a skill of a unit. Args: + +:-help: print the help message +:-skill skillName: set the skill that we're talking about +:-mode (add/set): are we adding experience/levels or setting them? +:-granularity (experience/level): + direct experience, or experience levels? +:-unit id: id of the target unit +:-value amount: how much to set/add + +=end]] local utils = require 'utils' validArgs = validArgs or utils.invert({ diff --git a/scripts/modtools/spawn-flow.lua b/scripts/modtools/spawn-flow.lua index 3e6445120b..594c3d9179 100644 --- a/scripts/modtools/spawn-flow.lua +++ b/scripts/modtools/spawn-flow.lua @@ -1,7 +1,13 @@ --scripts/modtools/spawn-flow.lua --author expwnent --spawns flows at locations +--[[=begin +modtools/spawn-flow +=================== +Creates flows at the specified location. + +=end]] local utils = require 'utils' validArgs = validArgs or utils.invert({ diff --git a/scripts/modtools/syndrome-trigger.lua b/scripts/modtools/syndrome-trigger.lua index 9afff2641e..b03ad57839 100644 --- a/scripts/modtools/syndrome-trigger.lua +++ b/scripts/modtools/syndrome-trigger.lua @@ -1,7 +1,13 @@ --scripts/modtools/syndrome-trigger.lua --author expwnent --triggers scripts when units are infected with syndromes +--[[=begin +modtools/syndrome-trigger +========================= +Triggers dfhack commands when syndromes are applied to units. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/transform-unit.lua b/scripts/modtools/transform-unit.lua index 9a8a797721..c1cda390be 100644 --- a/scripts/modtools/transform-unit.lua +++ b/scripts/modtools/transform-unit.lua @@ -1,9 +1,15 @@ --scripts/modtools/transform-unit.lua --author expwnent --based on shapechange by Putnam ---warning: will crash arena mode if you view the unit on the same tick that it transforms ---if you wait until later, it will be fine +--[[=begin +modtools/transform-unit +======================= +Transforms a unit into another unit type, possibly permanently. +Warning: this will crash arena mode if you view the unit on the +same tick that it transforms. If you wait until later, it will be fine. + +=end]] local utils = require 'utils' normalRace = normalRace or {} diff --git a/scripts/multicmd.rb b/scripts/multicmd.rb index 593b0fa727..1481cc52c8 100644 --- a/scripts/multicmd.rb +++ b/scripts/multicmd.rb @@ -1,4 +1,16 @@ # run many dfhack commands separated by ; -# ex: multicmd locate-ore IRON ; digv ; digcircle 16 +=begin + +multicmd +======== +Run multiple dfhack commands. The argument is split around the +character ; and all parts are run sequentially as independent +dfhack commands. Useful for hotkeys. + +Example:: + + multicmd locate-ore IRON ; digv ; digcircle 16 + +=end $script_args.join(' ').split(/\s*;\s*/).each { |cmd| df.dfhack_run cmd } diff --git a/scripts/points.lua b/scripts/points.lua index 0bedd20747..1c3c2a99d9 100644 --- a/scripts/points.lua +++ b/scripts/points.lua @@ -1,3 +1,13 @@ -- by Meph -- http://www.bay12forums.com/smf/index.php?topic=135506.msg4925005#msg4925005 +--[[=begin + +points +====== +Sets available points at the embark screen to the specified number. Eg. +``points 1000000`` would allow you to buy everything, or ``points 0`` would +make life quite difficult. + +=end]] + df.global.world.worldgen.worldgen_parms.embark_points=tonumber(...) diff --git a/scripts/position.lua b/scripts/position.lua index ea824e15f4..2ff44c14a5 100644 --- a/scripts/position.lua +++ b/scripts/position.lua @@ -1,4 +1,12 @@ --prints current time and position +--[[=begin + +position +======== +Reports the current time: date, clock time, month, and season. Also reports +location: z-level, cursor position, window size, and mouse location. + +=end]] local months = { 'Granite, in early Spring.', diff --git a/scripts/pref-adjust.lua b/scripts/pref-adjust.lua index b4a3659adb..a43ee8712e 100644 --- a/scripts/pref-adjust.lua +++ b/scripts/pref-adjust.lua @@ -1,7 +1,21 @@ -- Adjust all preferences of all dwarves in play --- all preferences are cleared, then set --- WARNING: USING THIS SCRIPT WILL ADJUST ALL DWARVES IN PLAY! -- by vjek +--[[=begin + +pref-adjust +=========== +A two-stage script: ``pref-adjust clear`` removes preferences from all dwarves, +and ``pref-adjust`` inserts an 'ideal' set which is easy to satisfy:: + + Feb Idashzefon likes wild strawberries for their vivid red color, + fisher berries for their round shape, prickle berries for their + precise thorns, plump helmets for their rounded tops, prepared meals, + plants, drinks, doors, thrones, tables and beds. When possible, she + prefers to consume wild strawberries, fisher berries, prickle + berries, plump helmets, strawberry wine, fisher berry wine, prickle + berry wine, and dwarven wine. + +=end]] -- --------------------------------------------------------------------------- function brainwash_unit(unit) diff --git a/scripts/putontable.lua b/scripts/putontable.lua index 5002c8e6bb..daba8a46fc 100644 --- a/scripts/putontable.lua +++ b/scripts/putontable.lua @@ -1,4 +1,13 @@ --- Makes item appear on the table (just like in shops). '-a' or '--all' for all items. +-- Makes item appear on the table (just like in shops) +--[[=begin + +putontable +========== +Makes item appear on the table, like in adventure mode shops. +Arguments: ``-a`` or ``--all`` for all items. + +=end]] + local pos=df.global.cursor local args={...} local doall diff --git a/scripts/quicksave.lua b/scripts/quicksave.lua index 8617c6f4d0..3f4cc3954a 100644 --- a/scripts/quicksave.lua +++ b/scripts/quicksave.lua @@ -1,4 +1,12 @@ -- Makes the game immediately save the state. +--[[=begin + +quicksave +========= +If called in dwarf mode, makes DF immediately saves the game by setting a flag +normally used in seasonal auto-save. + +=end]] if not dfhack.isMapLoaded() then qerror("World and map aren't loaded.") diff --git a/scripts/region-pops.lua b/scripts/region-pops.lua index 9a2cfd1fc1..af4d36bdeb 100644 --- a/scripts/region-pops.lua +++ b/scripts/region-pops.lua @@ -1,4 +1,28 @@ -- Shows populations of animals in the region, and allows tweaking them. +--[[=begin + +region-pops +=========== +Show or modify the populations of animals in the region. + +Usage: + +:region-pops list [pattern]: + Lists encountered populations of the region, possibly restricted by pattern. +:region-pops list-all [pattern]: + Lists all populations of the region. +:region-pops boost : + Multiply all populations of TOKEN by factor. + If the factor is greater than one, increases the + population, otherwise decreases it. +:region-pops boost-all : + Same as above, but match using a pattern acceptable to list. +:region-pops incr : + Augment (or diminish) all populations of TOKEN by factor (additive). +:region-pops incr-all : + Same as above, but match using a pattern acceptable to list. + +=end]] local utils = require 'utils' diff --git a/scripts/rejuvenate.lua b/scripts/rejuvenate.lua index 597bfd5288..fe19ad5455 100644 --- a/scripts/rejuvenate.lua +++ b/scripts/rejuvenate.lua @@ -1,7 +1,13 @@ --- This script will make any "old" dwarf 20 years old --- usage is: target a unit in DF, and execute this script in dfhack --- the target will be changed to 20 years old +-- make the selected dwarf 20 years old -- by vjek +--[[=begin + +rejuvenate +========== +Set the age of the selected dwarf to 20 years. Useful if valuable citizens are +getting old, or there are too many babies around... + +=end]] function rejuvenate() local current_year,newbirthyear diff --git a/scripts/remove-stress.lua b/scripts/remove-stress.lua index ea1eb7a603..d384129fd8 100644 --- a/scripts/remove-stress.lua +++ b/scripts/remove-stress.lua @@ -1,7 +1,14 @@ -- Sets stress to negative one million --- With unit selected, affects that unit. Use "remove-stress all" to affect all units. - --By Putnam; http://www.bay12forums.com/smf/index.php?topic=139553.msg5820486#msg5820486 +--[[=begin + +remove-stress +============= +Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or +very stressed dwarves taking on negative or greater values respectively. +Applies to the selected unit, or use ``remove-stress -all`` to apply to all units. + +=end]] local utils = require 'utils' diff --git a/scripts/remove-wear.lua b/scripts/remove-wear.lua index 56fe42edcc..5e905e39f2 100644 --- a/scripts/remove-wear.lua +++ b/scripts/remove-wear.lua @@ -2,6 +2,13 @@ -- Resets all items in your fort to 0 wear -- original author: Laggy -- edited by expwnent +--[[=begin + +remove-wear +=========== +Sets the wear on all items in your fort to zero. + +=end]] local args = {...} diff --git a/scripts/repeat.lua b/scripts/repeat.lua index 0c08d8fa89..2dd84c012c 100644 --- a/scripts/repeat.lua +++ b/scripts/repeat.lua @@ -3,6 +3,30 @@ -- repeat -help for details -- author expwnent -- vaguely based on a script by Putnam +--[[=begin + +repeat +====== +Repeatedly calls a lua script at the specified interval. + +This allows neat background changes to the function of the game, especially when +invoked from an init file. For detailed usage instructions, use ``repeat -help``. + +Usage examples:: + + repeat -name jim -time delay -timeUnits units -printResult true -command [ printArgs 3 1 2 ] + repeat -time 1 -timeUnits months -command [ multicmd cleanowned scattered x; clean all ] -name clean + +The first example is abstract; the second will regularly remove all contaminants +and worn items from the game. + +``-name`` sets the name for the purposes of cancelling and making sure you don't schedule the +same repeating event twice. If not specified, it's set to the first argument after ``-command``. +``-time delay -timeUnits units``; delay is some positive integer, and units is some valid time +unit for ``dfhack.timeout(delay,timeUnits,function)``. ``-command [ ... ]`` specifies the +command to be run. + +=end]] local repeatUtil = require 'repeat-util' local utils = require 'utils' diff --git a/scripts/setfps.lua b/scripts/setfps.lua index 690f82702a..6deb68bb28 100644 --- a/scripts/setfps.lua +++ b/scripts/setfps.lua @@ -1,4 +1,12 @@ -- Set the FPS cap at runtime. +--[[=begin + +setfps +====== +Run ``setfps `` to set the FPS cap at runtime, in case you want to watch +combat in slow motion or something. + +=end]] local cap = ... local capnum = tonumber(cap) diff --git a/scripts/show-unit-syndromes.rb b/scripts/show-unit-syndromes.rb index f79a79e839..70e72cba75 100644 --- a/scripts/show-unit-syndromes.rb +++ b/scripts/show-unit-syndromes.rb @@ -1,6 +1,29 @@ -# Show syndromes affecting units and the remaining and maximum duration (v6). Call with help on the command line for further options. +# Show syndromes affecting units and the remaining and maximum duration # original author: drayath # edited by expwnent +=begin + +show-unit-syndromes +=================== +Show syndromes affecting units and the remaining and maximum duration, along +with (optionally) substantial detail on the effects. + +Use one or more of the following options: + +:help: Show the help message +:showall: Show units even if not affected by any syndrome +:showeffects: Show detailed effects of each syndrome +:showdisplayeffects: Show effects that only change the look of the unit +:selected: Show selected unit +:dwarves: Show dwarves +:livestock: Show livestock +:wildanimals: Show wild animals +:hostile: Show hostiles (e.g. invaders, thieves, forgotten beasts etc) +:world: Show all defined syndromes in the world +:export: ``export:`` sends output to the given file, showing all + syndromes affecting each unit with the maximum and present duration. + +=end #TODO: When showing effects on a unit, show the actual change to the unit # E.g. if +150%, +500 strength show actual total bonus based on the unit stats. diff --git a/scripts/siren.lua b/scripts/siren.lua index 3a799c3e2d..053290a1c0 100644 --- a/scripts/siren.lua +++ b/scripts/siren.lua @@ -1,4 +1,15 @@ -- Wakes up the sleeping, breaks up parties and stops breaks. +--[[=begin + +siren +===== +Wakes up sleeping units, cancels breaks and stops parties either everywhere, +or in the burrows given as arguments. In return, adds bad thoughts about +noise, tiredness and lack of protection. Also, the units with interrupted +breaks will go on break again a lot sooner. The script is intended for +emergencies, e.g. when a siege appears, and all your military is partying. + +=end]] local utils = require 'utils' diff --git a/scripts/soundsense-season.lua b/scripts/soundsense-season.lua index 97e07903ed..da59205885 100644 --- a/scripts/soundsense-season.lua +++ b/scripts/soundsense-season.lua @@ -1,4 +1,17 @@ -- On map load writes the current season to gamelog.txt +--[[=begin + +soundsense-season +================= +It is a well known issue that Soundsense cannot detect the correct +current season when a savegame is loaded and has to play random +season music until a season switch occurs. + +This script registers a hook that prints the appropriate string +to :file:`gamelog.txt` on every map load to fix this. For best results +call the script from :file:`dfhack.init`. + +=end]] local seasons = { [-1] = 'Nothing', -- worldgen diff --git a/scripts/source.rb b/scripts/source.rb index 176cfbf2ba..92f1a47a69 100644 --- a/scripts/source.rb +++ b/scripts/source.rb @@ -1,4 +1,35 @@ # create an infinite magma/water source/drain at the cursor +=begin + +source +====== +Create an infinite magma or water source or drain on a tile. +For more complex commands, try the `liquids` plugin. + +This script registers a map tile as a liquid source, and every 12 game ticks +that tile receives or remove 1 new unit of flow based on the configuration. + +Place the game cursor where you want to create the source (must be a +flow-passable tile, and not too high in the sky) and call:: + + source add [magma|water] [0-7] + +The number argument is the target liquid level (0 = drain, 7 = source). + +To add more than 1 unit everytime, call the command again on the same spot. + +To delete one source, place the cursor over its tile and use ``source delete``. +To remove all existing sources, call ``source clear``. + +The ``list`` argument shows all existing sources. + +Examples:: + + source add water - water source + source add magma 7 - magma source + source add water 0 - water drain + +=end $sources ||= [] diff --git a/scripts/spawnunit.lua b/scripts/spawnunit.lua index 1c29649360..348c0984eb 100644 --- a/scripts/spawnunit.lua +++ b/scripts/spawnunit.lua @@ -1,5 +1,13 @@ -- create unit at pointer or given location -- wraps modtools/create-unit.lua +--[[=begin + +spawnunit +========= +``spawnunit RACE CASTE`` creates a unit of the given race and caste at the cursor, by +wrapping `modtools/create-unit`. Run ``spawnunit help`` for more options. + +=end]] usage = [[Usage: - spawnunit RACE CASTE diff --git a/scripts/startdwarf.rb b/scripts/startdwarf.rb index 3da7c55e3d..4e7d01c07a 100644 --- a/scripts/startdwarf.rb +++ b/scripts/startdwarf.rb @@ -1,4 +1,14 @@ # patch start dwarf count +=begin + +startdwarf +========== +Use at the embark screen to embark with the specified number of dwarves. Eg. +``startdwarf 500`` would lead to a severe food shortage and FPS issues, while +``startdwarf 10`` would just allow a few more warm bodies to dig in. +The number must be 7 or greater. + +=end nr = $script_args[0].to_i diff --git a/scripts/stripcaged.rb b/scripts/stripcaged.rb index 07b8a7f22b..8cb1a0fa40 100644 --- a/scripts/stripcaged.rb +++ b/scripts/stripcaged.rb @@ -1,4 +1,27 @@ # mark stuff inside of cages for dumping. +=begin + +stripcaged +========== +For dumping items inside cages. Will mark selected items for dumping, then +a dwarf may come and actually dump them (or you can use `autodump`). + +Arguments: + +:list: display the list of all cages and their item content on the console +:items: dump items in the cage, excluding stuff worn by caged creatures +:weapons: dump equipped weapons +:armor: dump everything worn by caged creatures (including armor and clothing) +:all: dump everything in the cage, on a creature or not + +Without further arguments, all commands work on all cages and animal traps on +the map. With the ``here`` argument, considers only the in-game selected cage +(or the cage under the game cursor). To target only specific cages, you can +alternatively pass cage IDs as arguments:: + + stripcaged weapons 25321 34228 + +=end def plural(nr, name) # '1 cage' / '4 cages' diff --git a/scripts/superdwarf.rb b/scripts/superdwarf.rb index 7e3bff7007..8ea4609cbf 100644 --- a/scripts/superdwarf.rb +++ b/scripts/superdwarf.rb @@ -1,4 +1,19 @@ # give super-dwarven speed to an unit +=begin + +superdwarf +========== +Similar to `fastdwarf`, per-creature. + +To make any creature superfast, target it ingame using 'v' and:: + + superdwarf add + +Other options available: ``del``, ``clear``, ``list``. + +This script also shortens the 'sleeping' and 'on break' periods of targets. + +=end $superdwarf_onupdate ||= nil $superdwarf_ids ||= [] diff --git a/scripts/teleport.lua b/scripts/teleport.lua index cf4253ccf6..2efc0cbe41 100644 --- a/scripts/teleport.lua +++ b/scripts/teleport.lua @@ -2,6 +2,18 @@ -- teleports a unit to a location -- author Putnam -- edited by expwnent +--[[=begin + +teleport +======== +Teleports a unit to given coordinates. Examples: + +:teleport -showunitid: prints unitid beneath cursor +:teleport -showpos: prints coordinates beneath cursor +:teleport -unit 1234 -x 56 -y 115 -z 26: + teleports unit 1234 to 56,115,26 + +=end]] function teleport(unit,pos) local unitoccupancy = dfhack.maps.getTileBlock(unit.pos).occupancy[unit.pos.x%16][unit.pos.y%16] diff --git a/scripts/tidlers.lua b/scripts/tidlers.lua new file mode 100644 index 0000000000..7df5091390 --- /dev/null +++ b/scripts/tidlers.lua @@ -0,0 +1,10 @@ +--Toggle idlers count +--[[=begin + +tidlers +======= +Toggle between all possible positions where the idlers count can be placed. + +=end]] +df.global.d_init.idlers = df.d_init_idlers:next_item(df.global.d_init.idlers) +print('Toggled the display of idlers.') diff --git a/scripts/twaterlvl.lua b/scripts/twaterlvl.lua new file mode 100644 index 0000000000..50f4876863 --- /dev/null +++ b/scripts/twaterlvl.lua @@ -0,0 +1,11 @@ +-- Toggle display of water depth +--[[=begin + +twaterlvl +========= +Toggle between displaying/not displaying liquid depth as numbers. + +=end]] + +df.global.d_init.flags1.SHOW_FLOW_AMOUNTS = not df.global.d_init.flags1.SHOW_FLOW_AMOUNTS +print('Water level display toggled.') diff --git a/scripts/undump-buildings.lua b/scripts/undump-buildings.lua index 77e7fce5f6..f4cfe79094 100644 --- a/scripts/undump-buildings.lua +++ b/scripts/undump-buildings.lua @@ -1,4 +1,12 @@ -- Undesignates building base materials for dumping. +--[[=begin + +undump-buildings +================ +Undesignates building base materials for dumping. + +=end]] + function undump_buildings() local buildings = df.global.world.buildings.all local undumped = 0 diff --git a/scripts/unsuspend.rb b/scripts/unsuspend.rb index bd0c3ad78f..6669693598 100644 --- a/scripts/unsuspend.rb +++ b/scripts/unsuspend.rb @@ -1,5 +1,13 @@ # un-suspend construction jobs, one time only # same as "resume all" +=begin + +unsuspend +========= +Unsuspend jobs in workshops, on a one-off basis. See `autounsuspend` +for regular use. + +=end joblist = df.world.job_list.next count = 0 diff --git a/scripts/view-item-info.lua b/scripts/view-item-info.lua index acadb134c0..be8e14b9e2 100644 --- a/scripts/view-item-info.lua +++ b/scripts/view-item-info.lua @@ -2,14 +2,20 @@ -- Shows information on material properties, weapon or armour stats, and more. -- By PeridexisErrant, adapted from nb_item_info by Raidau --@ enable = true +local help = [[=begin -local help = [[Extended Item Viewscreen - +view-item-info +============== A script to extend the item or unit viewscreen with additional information -including properties such as material info, weapon and attack properties, -armor thickness and coverage, and more - including custom item descriptions.]] +including a custom description of each item (when available), and properties +such as material statistics, weapon attacks, armor effectiveness, and more. + +The associated script `item-descriptions`.lua supplies custom descriptions +of items. Individual descriptions can be added or overridden by a similar +script :file:`raw/scripts/more-item-descriptions.lua`. Both work as sparse lists, +so missing items simply go undescribed if not defined in the fallback. -vi_label = 'More information (DFHack):' +=end]] function isInList(list, item, helper) if not helper then @@ -372,6 +378,7 @@ function AddUsesString (viewscreen,line,indent) end function dfhack.onStateChange.item_info (code) + vi_label = 'More information (DFHack):' if not enabled then return end if code == SC_VIEWSCREEN_CHANGED and dfhack.isWorldLoaded() then standard = dfhack.matinfo.find("INORGANIC:IRON").material diff --git a/scripts/warn-starving.lua b/scripts/warn-starving.lua index 40d1ffa931..abf95f9ec8 100644 --- a/scripts/warn-starving.lua +++ b/scripts/warn-starving.lua @@ -1,6 +1,17 @@ -- Pauses the game with a warning if a creature is starving, dehydrated, or very drowsy. -- By Meneth32, PeridexisErrant, Lethosor --@ module = true +--[[=begin + +warn-starving +============= +If any (live) units are starving, very thirsty, or very drowsy, the game will +be paused and a warning shown and logged to the console. Use with the +`repeat` command for regular checks. + +Use ``warn-starving all`` to display a list of all problematic units. + +=end]] starvingUnits = starvingUnits or {} dehydratedUnits = dehydratedUnits or {} diff --git a/travis/lint.py b/travis/lint.py index ce28f4be36..9b39f01499 100644 --- a/travis/lint.py +++ b/travis/lint.py @@ -65,8 +65,11 @@ def display_lines(self, lines, total): class NewlineLinter(Linter): msg = 'Contains DOS-style newlines' + def __init__(self): + # git supports newline conversion. Catch in CI, ignore on Windows. + self.ignore = sys.platform == 'win32' and not os.environ.get('TRAVIS') def check_line(self, line): - return '\r' not in line + return self.ignore or '\r' not in line def fix_line(self, line): return line.replace('\r', '') diff --git a/travis/script-in-readme.py b/travis/script-in-readme.py index f6b83bcd00..a6804fb00d 100644 --- a/travis/script-in-readme.py +++ b/travis/script-in-readme.py @@ -1,30 +1,53 @@ -import os, sys +from io import open +import os +from os.path import basename, dirname, join, splitext +import sys -scriptdir = 'scripts' -def is_script(fname): - if not os.path.isfile(fname): - return False - return fname.endswith('.lua') or fname.endswith('.rb') +def expected_cmd(path): + """Get the command from the name of a script.""" + dname, fname = basename(dirname(path)), splitext(basename(path))[0] + if dname in ('devel', 'fix', 'gui', 'modtools'): + return dname + '/' + fname + return fname + + +def check_file(fname): + errors, doclines = 0, [] + with open(fname, errors='ignore') as f: + for l in f.readlines(): + if doclines or l.strip().endswith('=begin'): + doclines.append(l.rstrip()) + if l.startswith('=end'): + break + else: + if doclines: + print('Error: docs start but not end: ' + fname) + else: + print('Error: no documentation in: ' + fname) + return 1 + title, underline = doclines[2], doclines[3] + if underline != '=' * len(title): + print('Error: title/underline mismatch:', fname, title, underline) + errors += 1 + if title != expected_cmd(fname): + print('Warning: expected script title {}, got {}'.format( + expected_cmd(fname), title)) + errors += 1 + return errors + def main(): - files = [] - for item in os.listdir(scriptdir): - path = os.path.join(scriptdir, item) - if is_script(path): - files.append(item) - elif os.path.isdir(path) and item not in ('devel', '3rdparty'): - files.extend([item + '/' + f for f in os.listdir(path) - if is_script(os.path.join(path, f))]) - with open('docs/Scripts.rst') as f: - text = f.read() - error = 0 - for f, _ in [os.path.splitext(p) for p in files]: - heading = '\n' + f + '\n' + '=' * len(f) + '\n' - if heading not in text: - print('WARNING: {:28} not documented in docs/Scripts'.format(f)) - error = 1 - sys.exit(error) + """Check that all DFHack scripts include documentation (not 3rdparty)""" + err = 0 + for root, _, files in os.walk('scripts'): + for f in files: + # TODO: remove 3rdparty exemptions from checks + # Requires reading their CMakeLists to only apply to used scripts + if f[-3:] in {'.rb', 'lua'} and '3rdparty' not in root: + err += check_file(join(root, f)) + return err + if __name__ == '__main__': - main() + sys.exit(bool(main())) diff --git a/travis/script-syntax.py b/travis/script-syntax.py index 984ff1755a..b3a264f048 100644 --- a/travis/script-syntax.py +++ b/travis/script-syntax.py @@ -1,15 +1,11 @@ -import argparse, os, sys, subprocess +import argparse +import os +import subprocess +import sys -parser = argparse.ArgumentParser() -parser.add_argument('--path', default='.', help='Root directory') -parser.add_argument('--ext', help='Script extension', required=True) -parser.add_argument('--cmd', help='Command', required=True) -args = parser.parse_args() - -def main(): +def main(args): root_path = os.path.abspath(args.path) cmd = args.cmd.split(' ') - ext = '.' + args.ext if not os.path.exists(root_path): print('Nonexistent path: %s' % root_path) sys.exit(2) @@ -19,14 +15,24 @@ def main(): if '.git' in parts or 'depends' in parts: continue for filename in filenames: - if not filename.endswith(ext): + if not filename.endswith('.' + args.ext): continue full_path = os.path.join(cur, filename) try: subprocess.check_output(cmd + [full_path]) except subprocess.CalledProcessError: err = True + except IOError: + if not err: + print('Warning: cannot check %s script syntax' % args.ext) + err = True sys.exit(int(err)) + if __name__ == '__main__': - main() + parser = argparse.ArgumentParser() + parser.add_argument('--path', default='.', help='Root directory') + parser.add_argument('--ext', help='Script extension', required=True) + parser.add_argument('--cmd', help='Command', required=True) + args = parser.parse_args() + main(args)