Merge branch 'develop' of https://github.com/dfhack/dfhack into develop

develop
lethosor 2015-09-26 10:46:45 -04:00
commit 2bcf74d74c
31 changed files with 1348 additions and 1242 deletions

1
.gitignore vendored

@ -22,6 +22,7 @@ build/VC2010
# Sphinx generated documentation
docs/_*/
docs/html/
#except for the real one
!build/

17
.gitmodules vendored

@ -15,4 +15,19 @@
url = git://github.com/DFHack/clsocket.git
[submodule "scripts/3rdparty/lethosor"]
path = scripts/3rdparty/lethosor
url = https://github.com/DFHack/lethosor-scripts
url = git://github.com/DFHack/lethosor-scripts
[submodule "scripts/3rdparty/roses"]
path = scripts/3rdparty/roses
url = git://github.com/DFHack/roses-scripts.git
[submodule "scripts/3rdparty/maxthyme"]
path = scripts/3rdparty/maxthyme
url = git://github.com/DFHack/maxthyme-scripts.git
[submodule "scripts/3rdparty/dscorbett"]
path = scripts/3rdparty/dscorbett
url = git://github.com/DFHack/dscorbett-scripts.git
[submodule "scripts/3rdparty/kane-t"]
path = scripts/3rdparty/kane-t
url = git://github.com/DFHack/kane-t-scripts.git
[submodule "scripts/3rdparty/maienm"]
path = scripts/3rdparty/maienm
url = git://github.com/DFHack/maienm-scripts.git

@ -16,6 +16,5 @@ script:
- python travis/script-in-readme.py
- python travis/script-syntax.py --ext=lua --cmd="luac$LUA_VERSION -p"
- python travis/script-syntax.py --ext=rb --cmd="ruby -c"
- make html
notifications:
email: false

@ -0,0 +1,16 @@
# build the documentation with Sphinx
find_program(SPHINX_EXECUTABLE NAMES sphinx-build
HINTS
$ENV{SPHINX_DIR}
PATH_SUFFIXES bin
DOC "Sphinx Documentation Generator"
)
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(Sphinx DEFAULT_MSG
SPHINX_EXECUTABLE
)
mark_as_advanced(SPHINX_EXECUTABLE)

@ -10,6 +10,8 @@ else(CMAKE_CONFIGURATION_TYPES)
endif (NOT CMAKE_BUILD_TYPE)
endif(CMAKE_CONFIGURATION_TYPES)
SET(BUILD_DOCS "True" CACHE STRING "Choose whether to build the documentation (requires python and Sphinx.")
## some generic CMake magic
cmake_minimum_required(VERSION 2.8 FATAL_ERROR)
project(dfhack)
@ -200,8 +202,9 @@ endif()
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(DIRECTORY images DESTINATION ${DFHACK_USERDOC_DESTINATION})
#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})
endif()
install(DIRECTORY dfhack-config/ DESTINATION dfhack-config/default)
@ -213,6 +216,37 @@ endif()
add_subdirectory(scripts)
#find_package(Sphinx REQUIRED)
find_package(Sphinx)
if (BUILD_DOCS)
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)
add_custom_target(dfhack_docs ALL
${SPHINX_EXECUTABLE}
-q -b html
-c "${SPHINX_BINARY_BUILD_DIR}"
-d "${SPHINX_CACHE_DIR}"
"${CMAKE_CURRENT_SOURCE_DIR}"
"${SPHINX_HTML_DIR}"
COMMENT "Building HTML documentation with Sphinx")
install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html
DESTINATION ${DFHACK_USERDOC_DESTINATION}
#FILES_MATCHING PATTERN "*.lua"
# PATTERN "*.rb"
# PATTERN "3rdparty" EXCLUDE
)
endif()
# Packaging with CPack!
IF(UNIX)
if(APPLE)
@ -231,3 +265,5 @@ ELSE()
ENDIF()
set(CPACK_PACKAGE_FILE_NAME "dfhack-${DFHACK_VERSION}-${DFHACK_PACKAGE_PLATFORM_NAME}")
INCLUDE(CPack)
#INCLUDE(FindSphinx.cmake)

@ -1,99 +1,97 @@
--------------------------------------------------------------------------------
License of dfhack
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.
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:
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.
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.
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.
3. This notice may not be removed or altered from any source
distribution.
--------------------------------------------------------------------------------
License of the used 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.
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:
www.sourceforge.net/projects/tinyxml
Original code (2.0 and earlier )copyright (c) 2000-2006 Lee Thomason (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.
--------------------------------------------------------------------------------
* 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.
--------------------------------------------------------------------------------
Parts of dfhack are based on linenoise:
linenoise.c -- guerrilla 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
Does a number of crazy assumptions that happen to be true in 99.9999% of
the 2010 UNIX computers around.
--------------------------------------------------------------------------------
Copyright (c) 2010, Salvatore Sanfilippo <antirez at gmail dot com>
Copyright (c) 2010, Pieter Noordhuis <pcnoordhuis at gmail dot com>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
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 <antirez at gmail dot com>
Copyright (c) 2010, Pieter Noordhuis <pcnoordhuis at gmail dot com>
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.
@ -102,97 +100,101 @@ met:
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.
--------------------------------------------------------------------------------
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 <bjoern@hoehrmann.de>
Copyright (c) 2008-2010 Bjoern Hoehrmann <bjoern@hoehrmann.de>
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:
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 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.
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 license
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 license
Copyright 2010-2014 Jeffrey Friedl
http://regex.info/blog/
::
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

@ -1,192 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = docs/_build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/DFHack.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/DFHack.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/DFHack"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/DFHack"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

13
NEWS

@ -1,3 +1,10 @@
.. 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
=============
::
@ -72,6 +79,12 @@ DFHack Future
- 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

@ -4,13 +4,13 @@
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="0;url=./docs/_build/html/README.html">
<meta http-equiv="refresh" content="0;url=./docs/html/README.html">
<script type="text/javascript">
window.location.href = "./docs/_build/html/README.html"
window.location.href = "./docs/html/README.html"
</script>
<title>Page Redirection</title>
</head>
<body>
If you are not redirected automatically, follow the <a href='./docs/_build/html/README.html'>link to the documentation.</a>
If you are not redirected automatically, follow the <a href='./docs/html/README.html'>link to the documentation.</a>
</body>
</html>

@ -8,32 +8,33 @@ and plugins implementing a wide variety of useful functions and tools.
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!
(such as `plugins/workflow` or `plugins/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 `scripts <scripts/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.
`various copyleft licences <license>`, contributions are welcome.
Documentation
=============
DFHack documentation is generated by Sphinx. Check out the table of contents
below, or the sources in the docs folder!
below, or the sources in the `docs folder`_!
.. _`docs folder`: ./docs
User Manual:
.. toctree::
:maxdepth: 2
docs/Readme
docs/Core
docs/Plugins
docs/Scripts
@ -54,3 +55,5 @@ For Developers:
docs/Contributing
docs/Compile
docs/Lua API
library/xml/SYNTAX
docs/Binpatches

Before

Width:  |  Height:  |  Size: 2.4 KiB

After

Width:  |  Height:  |  Size: 2.4 KiB

@ -241,6 +241,10 @@ log-region
# add information to item viewscreens
view-item-info enable
gui/load-screen enable
base/roses-init --all
#######################################################
# Apply binary patches at runtime #
#######################################################

@ -1,13 +1,13 @@
List of Authors
===============
The following is a list of people who have contributed to **DFHack**, in no
The following is a list of people who have contributed to DFHack, in no
particular order.
If you should be here and aren't, please get in touch or make a pull request!
======================= ==================== ===========================
======================= ======================= ===========================
Name Github Email
======================= ==================== ===========================
======================= ======================= ===========================
Petr Mrázek peterix peterix@gmail.com
Alexander Gavrilov angavrilov angavrilov@gmail.com
doomchild doomchild lee.crabtree@gmail.com
@ -86,4 +86,4 @@ Vjek
Kris Parker kaypy
Jonas Ask jonask84@gmail.com
8Z 8Z git8z@ya.ru
======================= ==================== ===========================
======================= ======================= ===========================

@ -0,0 +1,180 @@
.. _binpatches:
######################
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.
.. warning::
We recommend using a script or plugin instead of a raw patch if
at all possible - that way your work will work for many versions
across multiple operating systems. There's a reason nobody has
written patches since ``0.34.11``!
.. contents::
Getting a patch
===============
There are no binary patches available for Dwarf Fortress versions after 0.34.11
This system is kept for the chance that someone will find it useful, so some
hints on how to write your own follow. This will require disassembly and
decent skill in `memory research <contributing-memory-research>`.
* The patches are expected to be encoded in text format used by IDA.
* See `this commit <https://github.com/DFHack/dfhack/commit/8a9e3d1a728>`_,
when the 0.34.11 patches were discarded, for example patches.
* `Issue #546 <https://github.com/DFHack/dfhack/issues/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.
Using a patch
=============
There are two methods to apply a patch.
Patching at runtime
-------------------
The `scripts/binpatch` script checks, applies or removes binary patches
directly in memory at runtime::
binpatch [check|apply|remove] <patchname>
If the name of the patch has no extension or directory separators, the
script uses ``hack/patches/<df-version>/<name>.dif``, thus auto-selecting
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.
Patching on disk
----------------
.. warning::
This method of patching is deprecated, and may be removed without notice.
You should use the runtime patching option above.
DFHack includes a small stand-alone utility for applying and removing
binary patches from the game executable. Use it from the regular operating
system console:
``binpatch check "Dwarf Fortress.exe" patch.dif``
Checks and prints if the patch is currently applied.
``binpatch apply "Dwarf Fortress.exe" patch.dif``
Applies the patch, unless it is already applied or in conflict.
``binpatch remove "Dwarf Fortress.exe" patch.dif``
Removes the patch, unless it is already removed.
If you use a permanent patch under OSX or Linux, you must update
``symbols.xml`` with the new checksum of the executable. Find the relevant
section, and add a new line::
<md5-hash value='????????????????????????????????'/>
In order to find the correct value of the hash, look into stderr.log;
DFHack prints an error there if it does not recognize the hash.
.. _binpatches/needs-patch:
Tools reliant on binpatches
===========================
Some DFHack tools require the game to be patched to work. As no patches
are currently available, the full description of each is included here.
fix-armory
----------
Enables a fix for storage of squad equipment in barracks.
Specifically, it prevents your haulers from moving squad equipment
to stockpiles, and instead queues jobs to store it on weapon racks,
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`.
Note that the buildings in the armory are used as follows:
* Weapon racks (when patched) are used to store any assigned weapons.
Each rack belongs to a specific squad, and can store up to 5 weapons.
* Armor stands belong to specific squad members and are used for
armor and shields.
* Cabinets are used to store assigned clothing for a specific squad member.
They are **never** used to store owned clothing.
* Chests (boxes, etc) are used for a flask, backpack or quiver assigned
to the squad member. Due to a probable bug, food is dropped out of the
backpack when it is stored.
.. warning::
Although armor stands, cabinets and chests properly belong only to one
squad member, the owner of the building used to create the barracks will
randomly use any containers inside the room. Thus, it is recommended to
always create the armory from a weapon rack.
Contrary to the common misconception, all these uses are controlled by the
*Individual Equipment* usage flag. The *Squad Equipment* flag is actually
intended for ammo, but the game does even less in that area than for armor
and weapons. This plugin implements the following rules almost from scratch:
* Combat ammo is stored in chests inside rooms with Squad Equipment enabled.
* If a chest is assigned to a squad member due to Individual Equipment also
being set, it is only used for that squad's ammo; otherwise, any squads
with Squad Equipment on the room will use all of the chests at random.
* Training ammo is stored in chests inside archery ranges designated from
archery targets, and controlled by the same Train flag as archery training
itself. This is inspired by some defunct code for weapon racks.
There are some minor traces in the game code to suggest that the first of
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.
.. image:: images/assign-rack.png
This script is part of a group of related fixes to make the armory storage
work again. The existing issues are:
* Weapon racks have to each be assigned to a specific squad, like with
beds/boxes/armor stands and individual squad members, but nothing in
the game does this. This issue is what this script addresses.
* 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
* Haulers still take equipment stored in the armory away to the stockpiles,
unless `plugins/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
the intended user. In order to aid in the choice, it shows the number
of currently assigned racks for every valid squad.

@ -16,13 +16,14 @@ DFHack doesn't have any kind of system of code snapshots in place, so you will h
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),
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
* 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
To get the code::
@ -75,15 +76,18 @@ Before you can build anything, you'll also need ``cmake``. It is advisable to al
``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``.
To build Stonesense, you'll also need OpenGL headers.
Some additional dependencies for other distros are listed on the `wiki <https://github.com/DFHack/dfhack/wiki/Linux-dependencies>`_.
Some additional dependencies for other distros are listed on the
`wiki <https://github.com/DFHack/dfhack/wiki/Linux-dependencies>`_.
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::
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::
cd build
cmake .. -DCMAKE_BUILD_TYPE:string=Release -DCMAKE_INSTALL_PREFIX=/home/user/DF
@ -205,7 +209,8 @@ Snow Leopard Changes
Yosemite Changes
================
If you have issues building on OS X Yosemite (or above), try definining the following environment variable::
If you have issues building on OS X Yosemite (or above), try definining the
following environment variable::
export MACOSX_DEPLOYMENT_TARGET=10.9
@ -227,9 +232,13 @@ 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: http://strawberryperl.com/
For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT.
`Strawberry Perl <http://strawberryperl.com>`_ works nicely for this.
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.
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.
Build
=====

@ -17,6 +17,61 @@ If you're not comfortable pregramming, you can help by:
All those things are crucial, and all under-represented. So if that's
your thing, the rest of this document is about contributing code - go get started!
Documentation Standards
=======================
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``.
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.
Try to keep lines within 80-100 characters, so it's readable in plain text -
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.
If the command takes more than three arguments, format the list as a table
called Options. The table *only* lists arguments, not full commands.
Input values are specified in angle brackets. Example::
Options:
:arg1: A simple argument.
:arg2 <input>: Does something based on the input value.
:Very long argument:
Is very specific.
To demonstrate usage - useful mainly when the syntax is complicated, list the
full command with arguments in monospaced font, then indent the next line and
describe the effect::
``resume all``
Resumes all suspended constructions.
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
described (without file extension), and placed above the heading of that
section like this::
.. _plugins/autolabor:
autolabor
=========
Add link targets if you need them, but otherwise plain headings are preferred.
Contributing Code
=================
Several things should be kept in mind when contributing code to DFHack.
@ -46,6 +101,8 @@ How to get new code into DFHack
* Work done against Github issues tagged "bug report" get priority
* Submit ideas and bug reports as issues on Github. Posts in the forum thread can easily get missed or forgotten.
.. _contributing-memory-research:
Memory research
---------------
If you want to do memory research, you'll need some tools and some knowledge.
@ -70,39 +127,58 @@ Using the library as a developer
Currently, the most direct way to use the library is to write a script or plugin that can be loaded by it.
All the plugins can be found in the 'plugins' folder. There's no in-depth documentation
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.
The most important parts of DFHack are the Core, Console, Modules and Plugins.
* Core acts as the centerpiece of DFHack - it acts as a filter between DF and SDL and synchronizes the various plugins with DF.
* Core acts as the centerpiece of DFHack - it acts as a filter between DF and
SDL and synchronizes the various plugins with DF.
* Console is a thread-safe console that can be used to invoke commands exported by Plugins.
* Modules actually describe the way to access information in DF's memory. You can get them from the Core. Most modules are split into two parts: high-level and low-level. High-level is mostly method calls, low-level publicly visible pointers to DF's data structures.
* Plugins are the tools that use all the other stuff to make things happen. A plugin can have a list of commands that it exports and an onupdate function that will be called each DF game tick.
Rudimentary API documentation can be built using doxygen (see build options with ``ccmake`` or ``cmake-gui``).
* Modules actually describe the way to access information in DF's memory. You
can get them from the Core. Most modules are split into two parts: high-level
and low-level. High-level is mostly method calls, low-level publicly visible
pointers to DF's data structures.
* Plugins are the tools that use all the other stuff to make things happen.
A plugin can have a list of commands that it exports and an onupdate function
that will be called each DF game tick.
Rudimentary API documentation can be built using doxygen (see build options
with ``ccmake`` or ``cmake-gui``). The full DFHack 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.
The main license is zlib/libpng, some bits are MIT licensed, and some are
BSD licensed. See the `license` document 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 :)
DF data structure definitions
-----------------------------
DFHack uses information about the game data structures, represented via xml files
in the ``library/xml/`` submodule.
DFHack uses information about the game data structures, represented via xml files in the library/xml/ submodule.
See https://github.com/DFHack/df-structures
See https://github.com/DFHack/df-structures, and the documentation linked in the index.
Data structure layouts are described in files following the df.\*.xml name pattern. This information is transformed by a perl script into C++ headers describing the structures, and associated metadata for the Lua wrapper. These headers and data are then compiled into the DFHack libraries, thus necessitating a compatibility break every time layouts change; in return it significantly boosts the efficiency and capabilities of DFHack code.
Data structure layouts are described in files following the ``df.\*.xml`` name pattern.
This information is transformed by a perl script into C++ headers describing the
structures, and associated metadata for the Lua wrapper. These headers and data
are then compiled into the DFHack libraries, thus necessitating a compatibility
break every time layouts change; in return it significantly boosts the efficiency
and capabilities of DFHack code.
Global object addresses are stored in symbols.xml, which is copied to the dfhack release package and loaded as data at runtime.
Global object addresses are stored in ``symbols.xml``, which is copied to the dfhack
release package and loaded as data at runtime.
Remote access interface
-----------------------
DFHack supports remote access by exchanging Google protobuf messages via a TCP socket. Both the core and plugins can define remotely accessible methods. The ``dfhack-run`` command uses this interface to invoke ordinary console commands.
DFHack supports remote access by exchanging Google protobuf messages via a TCP
socket. Both the core and plugins can define remotely accessible methods. The
``dfhack-run`` command uses this interface to invoke ordinary console commands.
Currently the supported set of requests is limited, because the developers don't know what exactly is most useful.
``remotefortressreader`` provides a fairly comprehensive interface for visualisers such as Armok Vision.
Currently the supported set of requests is limited, because the developers don't
know what exactly is most useful. ``remotefortressreader`` provides a fairly
comprehensive interface for visualisers such as Armok Vision.

@ -1,6 +1,6 @@
#############
DFHack Readme
#############
###########
DFHack Core
###########
.. contents::
@ -21,6 +21,7 @@ Even older versions are available here_.
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
If this sounds too complicated, you might prefer to `get a Starter Pack`_.
@ -48,18 +49,18 @@ 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, the 'dfhack' script is placed in the same folder as the 'df' script
* 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.
* 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.
If any of the plugins or dfhack itself refuses to load, check the stderr.log
If any of the plugins or dfhack itself refuses to load, check the ``stderr.log``
file created in your DF folder.
@ -71,7 +72,7 @@ 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
**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.
@ -86,18 +87,16 @@ called ``dfhack.init``; the installation comes with an example version called
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.
For more information, refer to the rest of this document.
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
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.
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.
``command help`` or ``command ?`` to show that.
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
@ -105,17 +104,21 @@ the history).
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').
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 'liquids' cannot be used as hotkeys.
Interactive commands like `plugins/liquids` cannot be used as hotkeys.
Most of the commands come from plugins. Those reside in 'hack/plugins/'.
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!
=============================
@ -125,11 +128,14 @@ 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.
If you found a bug, you can report it in `the Bay12 DFHack thread`_,
`the issues tracker on github <https://github.com/DFHack/dfhack/issues>`_,
or visit `the #dfhack IRC channel on freenode
<https://webchat.freenode.net/?channels=dfhack>`_.
Commands
========
=============
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.
@ -137,8 +143,10 @@ 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.
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.
If the first non-whitespace character is ``:``, the command is parsed in a special
alternative mode: first, non-whitespace characters immediately following the ``:``
@ -151,27 +159,52 @@ The following two command lines are exactly equivalent::
This is intended for commands like ``rb_eval`` that evaluate script language statements.
Almost all the commands support using the 'help <command-name>' built-in command
Almost all the commands support using the ``help <command-name>`` built-in command
to retrieve further help without having to look at this document. Alternatively,
some accept a 'help'/'?' option on their command line.
some accept a ``help`` or ``?`` as an option on their command line.
.. note::
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.
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.
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``.
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.
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.
The init file
=============
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.
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``.
The file ``dfhack.init-example`` is included as an example for users to follow if they need DFHack command executed automatically.
We highly recommend modifying or deleting ``dfhack.init-example`` as its settings will not be optimal for all players.
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.
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.
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 sorted and executed in alphebetical order.
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.
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.
Setting keybindings
===================
@ -192,22 +225,22 @@ Possible ways to call the command:
``keybinding set <key> "cmdline" "cmdline"...``
Clear, and then add bindings for the specified key.
The *<key>* parameter above has the following *case-sensitive* syntax::
The ``<key>`` parameter above has the following *case-sensitive* syntax::
[Ctrl-][Alt-][Shift-]KEY[@context[|context...]]
where the *KEY* part can be any recognized key and [] denote optional parts.
When multiple commands are bound to the same key combination, DFHack selects
the first applicable one. Later 'add' commands, and earlier entries within one
'add' command have priority. Commands that are not specifically intended for use
the first applicable one. Later ``add`` commands, and earlier entries within one
``add`` command have priority. Commands that are not specifically intended for use
as a hotkey are always considered applicable.
The *context* part in the key specifier above can be used to explicitly restrict
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.
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``.
@ -221,6 +254,11 @@ Opens an in-game screen showing DFHack keybindings that are active in the curren
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.
Enabling plugins
================
Many plugins can be in a distinct enabled or disabled state. Some of
@ -240,15 +278,6 @@ arguments for the command::
enable manipulator search
In-game interface tools
=======================
Some tools work by displaying dialogs or overlays in the game window.
In order to avoid user confusion, as a matter of policy all these tools
must 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.
Game progress
=============
@ -275,31 +304,3 @@ nopause
Disables pausing (both manual and automatic) with the exception of pause forced
by 'reveal hell'. This is nice for digging under rivers.
Patched binaries
================
As an alternative to permanently modifying the binary, you can use the
``binpatch`` dfhack command to apply patches live in memory during a DF session.
In this case, updating symbols.xml is not necessary - otherwise Linux and OSX
users of patched binaries may have to find the relevant section in ``symbols.xml``,
and add a new line with the checksum of their executable::
<md5-hash value='????????????????????????????????'/>
In order to find the correct value of the hash, look into stderr.log;
DFHack prints an error there if it does not recognize the hash.
DFHack includes a small stand-alone utility for applying and removing
binary patches from the game executable. Use it from the regular operating
system console:
``binpatch check "Dwarf Fortress.exe" patch.dif``
Checks and prints if the patch is currently applied.
``binpatch apply "Dwarf Fortress.exe" patch.dif``
Applies the patch, unless it is already applied or in conflict.
``binpatch remove "Dwarf Fortress.exe" patch.dif``
Removes the patch, unless it is already removed.
The patches are expected to be encoded in text format used by IDA.

@ -1,3 +1,5 @@
.. _license:
########
Licenses
########
@ -7,4 +9,3 @@ 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
:literal:

File diff suppressed because it is too large Load Diff

@ -4,11 +4,12 @@ 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.
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.
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
@ -16,6 +17,30 @@ 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.
.. toctree::
:glob:
:maxdepth: 2
/scripts/3rdparty/*/*
=======
devel/*
=======
@ -77,7 +102,7 @@ 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 ``tweak stable-temp`` and ``tweak fast-heat``.
state however, use `plugins/tweak` ``stable-temp`` and `plugins/tweak` ``fast-heat``.
fix/stuckdoors
==============
@ -124,39 +149,18 @@ An example of player digging in adventure mode:
gui/advfort_items
=================
Does something with items in advnedute mode jobs.
Does something with items in adventure mode jobs.
.. _scripts/gui/assign-rack:
gui/assign-rack
===============
Bind to a key (the example config uses P), and activate when viewing a weapon
rack in the 'q' mode.
.. image:: images/assign-rack.png
This script is part of a group of related fixes to make the armory storage
work again. The existing issues are:
* Weapon racks have to each be assigned to a specific squad, like with
beds/boxes/armor stands and individual squad members, but nothing in
the game does this. This issue is what this script addresses.
* Even if assigned by the script, **the game will unassign the racks again without a binary patch**.
This patch is called ``weaponrack-unassign``, and can be applied via
the binpatch program, or the matching script. See `the bug report`_ for more info.
.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445
* Haulers still take equipment stored in the armory away to the stockpiles,
unless the ``fix-armory`` plugin above 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
the intended user. In order to aid in the choice, it shows the number
of currently assigned racks for every valid squad.
`This script requires a binpatch <binpatches/needs-patch>`, which has not
been available since DF 0.34.11
gui/autobutcher
===============
An in-game interface for the ``autobutcher`` plugin.
An in-game interface for `plugins/autobutcher`.
gui/choose-weapons
==================
@ -195,6 +199,8 @@ case. Must be in look or talk mode to issue command on tile.
* 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.
@ -238,7 +244,7 @@ computes it when the order is executed for the first time.
gui/hack-wish
=============
An alias for ``gui/create-item``. Deprecated.
An alias for `scripts/gui/create-item`. Deprecated.
gui/hello-world
===============
@ -250,10 +256,13 @@ To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mo
.. image:: images/liquids.png
This script is a gui front-end to the liquids plugin and works similar to it,
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.
Note that there is **no undo support**, and that bugs in this plugin have been
known to create pathfinding problems and heat traps.
.. 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``
@ -298,13 +307,17 @@ 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 the ``power-meter`` plugin.
An in-game interface for `plugins/power-meter`.
.. _scripts/gui/rename:
gui/rename
==========
Backed by the rename plugin, this script allows entering the desired name
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.
@ -340,28 +353,36 @@ either immediately or after opening the assign owner page.
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 the ``siege-engine`` plugin.
An in-game interface for `plugins/siege-engine`.
.. _scripts/gui/stockpiles:
gui/stockpiles
==============
Load and save stockpile settings from the 'q' menu.
Usage::
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 <path> set the default directory to save settings into
gui/stockpiles -help to see this message
:gui/stockpiles -save: to save the current stockpile
:gui/stockpiles -load: to load settings into the current stockpile
:gui/stockpiles -dir <path>: 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 this plugin.
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
@ -369,8 +390,8 @@ in a workshop in the 'q' mode.
.. image:: images/workflow.png
This script provides a simple interface to constraints managed by the workflow
plugin. When active, it displays a list of all constraints applicable to the
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
@ -387,8 +408,8 @@ 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 ``job item-material`` or ``gui/workshop-job``,
as described in ``workflow`` documentation above. In this manner, this feature
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
@ -423,6 +444,8 @@ 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
@ -431,7 +454,7 @@ 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 ``job item-type`` and ``job item-material`` commands.
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.
@ -469,6 +492,8 @@ 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
========================
@ -508,11 +533,15 @@ 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.
@ -604,7 +633,8 @@ or the gui invoked by running ``add-thought gui`` with a unit selected.
armoks-blessing
===============
Runs the equivalent of rejuvenate, elevate-physical, elevate-mental, and brainwash
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.
@ -621,14 +651,18 @@ Usage::
autofarm default 30
autofarm threshold 150 helmet_plump tail_pig
.. _scripts/autolabor-artisans:
autolabor-artisans
==================
Runs the ``autolabor`` plugin, with settings tuned for small but highly skilled workforces.
Runs `plugins/autolabor`, with settings tuned for small but highly skilled workforces.
.. _scripts/autounsuspend:
autounsuspend
=============
Automatically unsuspend construction jobs, on a recurring basis.
See ``unsuspend`` for one-off use, or ``resume all``.
Automatically unsuspend jobs in workshops, on a recurring basis.
See `scripts/unsuspend` for one-off use, or `plugins/resume` ``all``.
ban-cooking
===========
@ -636,15 +670,13 @@ A more convenient way to ban cooking various categories of foods than the
kitchen interface. Usage: ``ban-cooking <type>``. Valid types are ``booze``,
``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds).
.. _scripts/binpatch:
binpatch
========
Checks, applies or removes binary patches directly in memory at runtime::
binpatch check/apply/remove <patchname>
Implements functions for in-memory binpatches. See `binpatches`.
If the name of the patch has no extension or directory separators, the
script uses ``hack/patches/<df-version>/<name>.dif``, thus auto-selecting
the version appropriate for the currently loaded executable.
.. _scripts/brainwash:
brainwash
=========
@ -702,6 +734,8 @@ 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.
@ -726,18 +760,22 @@ 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).
``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,
@ -802,6 +840,8 @@ 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
@ -863,7 +903,7 @@ 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 ``view-item-info``.
Used by `scripts/view-item-info`.
lever
=====
@ -897,7 +937,10 @@ Examples::
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.
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:
@ -988,7 +1031,26 @@ normally used in seasonal auto-save.
region-pops
===========
Show or modify the populations of animals in the region. Use ``region-pops`` for details.
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 <TOKEN> <factor>:
Multiply all populations of TOKEN by factor.
If the factor is greater than one, increases the
population, otherwise decreases it.
:region-pops boost-all <pattern> <factor>:
Same as above, but match using a pattern acceptable to list.
:region-pops incr <TOKEN> <factor>:
Augment (or diminish) all populations of TOKEN by factor (additive).
:region-pops incr-all <pattern> <factor>:
Same as above, but match using a pattern acceptable to list.
.. _scripts/rejuvenate:
rejuvenate
==========
@ -1005,6 +1067,8 @@ 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.
@ -1034,8 +1098,22 @@ 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. Call
``show-unit-syndromes help`` for further options.
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:<filename>`` sends output to the given file, showing all
syndromes affecting each unit with the maximum and present duration.
siren
=====
@ -1071,12 +1149,12 @@ 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 ``delete``.
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.
Ex::
Examples::
source add water - water source
source add magma 7 - magma source
@ -1092,7 +1170,7 @@ 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 ``autodump``.
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``
@ -1119,7 +1197,7 @@ To make any creature superfast, target it ingame using 'v' and::
Other options available: ``del``, ``clear``, ``list``.
This plugin also shortens the 'sleeping' and 'on break' periods of targets.
This script also shortens the 'sleeping' and 'on break' periods of targets.
teleport
========
@ -1135,10 +1213,14 @@ undump-buildings
================
Undesignates building base materials for dumping.
.. _scripts/unsuspend:
unsuspend
=========
Unsuspend construction jobs, on a one-off basis. See ``autounsuspend`` for regular use.
Equivalent to ``resume all``.
Unsuspend jobs in workshops, on a one-off basis. See `scripts/autounsuspend`
for regular use.
.. _scripts/view-item-info:
view-item-info
==============
@ -1155,6 +1237,6 @@ 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.
`scripts/repeat` command for regular checks.
Use ``warn-starving all`` to display a list of all problematic units.

@ -56,21 +56,21 @@ author = 'The DFHack Team'
# |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 = '', ''
# 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', '')
# The short X.Y version.
version = get_version()
version = '@DFHACK_VERSION@'
# The full version, including alpha/beta/rc tags.
release = get_version()
release = '@DFHACK_VERSION@'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@ -91,7 +91,7 @@ exclude_patterns = ['docs/_build/*', 'depends/*']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
default_role = 'any'
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
@ -121,7 +121,7 @@ todo_include_todos = False
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'alabaster'
html_theme = '@SPHINX_THEME@'
# 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
@ -145,7 +145,7 @@ html_theme = 'alabaster'
# 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 = None
html_favicon = '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,

@ -372,12 +372,12 @@ install(DIRECTORY lua/
DESTINATION ${DFHACK_LUA_DESTINATION}
FILES_MATCHING PATTERN "*.lua")
install(DIRECTORY ${dfhack_SOURCE_DIR}/scripts
DESTINATION ${DFHACK_DATA_DESTINATION}
FILES_MATCHING PATTERN "*.lua"
PATTERN "*.rb"
PATTERN "3rdparty" EXCLUDE
)
#install(DIRECTORY ${dfhack_SOURCE_DIR}/scripts
# DESTINATION ${DFHACK_DATA_DESTINATION}
# FILES_MATCHING PATTERN "*.lua"
# PATTERN "*.rb"
# PATTERN "3rdparty" EXCLUDE
# )
install(DIRECTORY ${dfhack_SOURCE_DIR}/patches
DESTINATION ${DFHACK_DATA_DESTINATION}

@ -1 +1 @@
Subproject commit 32960d38410e7caedf2b38cff7ef3f21c1785bbd
Subproject commit 4c327037df627682812d2770aa77349702d09633

@ -1,263 +0,0 @@
@ECHO OFF
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set BUILDDIR=docs\_build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
set I18NSPHINXOPTS=%SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)
if "%1" == "" goto help
if "%1" == "help" (
:help
echo.Please use `make ^<target^>` where ^<target^> is one of
echo. html to make standalone HTML files
echo. dirhtml to make HTML files named index.html in directories
echo. singlehtml to make a single large HTML file
echo. pickle to make pickle files
echo. json to make JSON files
echo. htmlhelp to make HTML files and a HTML help project
echo. qthelp to make HTML files and a qthelp project
echo. devhelp to make HTML files and a Devhelp project
echo. epub to make an epub
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. xml to make Docutils-native XML files
echo. pseudoxml to make pseudoxml-XML files for display purposes
echo. linkcheck to check all external links for integrity
echo. doctest to run all doctests embedded in the documentation if enabled
echo. coverage to run coverage check of the documentation if enabled
goto end
)
if "%1" == "clean" (
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
del /q /s %BUILDDIR%\*
goto end
)
REM Check if sphinx-build is available and fallback to Python version if any
%SPHINXBUILD% 2> nul
if errorlevel 9009 goto sphinx_python
goto sphinx_ok
:sphinx_python
set SPHINXBUILD=python -m sphinx.__init__
%SPHINXBUILD% 2> nul
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
:sphinx_ok
if "%1" == "html" (
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)
if "%1" == "dirhtml" (
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
)
if "%1" == "singlehtml" (
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
)
if "%1" == "pickle" (
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the pickle files.
goto end
)
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the JSON files.
goto end
)
if "%1" == "htmlhelp" (
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
goto end
)
if "%1" == "qthelp" (
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\DFHack.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\DFHack.ghc
goto end
)
if "%1" == "devhelp" (
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished.
goto end
)
if "%1" == "epub" (
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
)
if "%1" == "latex" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
if errorlevel 1 exit /b 1
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdf" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf
cd %~dp0
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdfja" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf-ja
cd %~dp0
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "text" (
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The text files are in %BUILDDIR%/text.
goto end
)
if "%1" == "man" (
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The manual pages are in %BUILDDIR%/man.
goto end
)
if "%1" == "texinfo" (
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
goto end
)
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
goto end
)
if "%1" == "changes" (
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
if errorlevel 1 exit /b 1
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
)
if "%1" == "linkcheck" (
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
if errorlevel 1 exit /b 1
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
goto end
)
if "%1" == "doctest" (
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
if errorlevel 1 exit /b 1
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
)
if "%1" == "coverage" (
%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
if errorlevel 1 exit /b 1
echo.
echo.Testing of coverage in the sources finished, look at the ^
results in %BUILDDIR%/coverage/python.txt.
goto end
)
if "%1" == "xml" (
%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The XML files are in %BUILDDIR%/xml.
goto end
)
if "%1" == "pseudoxml" (
%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
goto end
)
:end

@ -0,0 +1 @@
Subproject commit 544f890a62622e2c6188991afe61fdf3c0513227

@ -0,0 +1 @@
Subproject commit e808649108be6bc97323b54151d621c57aded51f

@ -1 +1 @@
Subproject commit ceed207e38220e21067a91b8d6f7b9680a476f69
Subproject commit e3666a7385ca00565b95f3d7c6d41f6e7955816f

@ -0,0 +1 @@
Subproject commit 8cffa1266d8903b568cf48366dd6f57095e3ae97

@ -0,0 +1 @@
Subproject commit a0f48ba8a8fb7e32cb57125e31f76979e3687a1d

@ -0,0 +1 @@
Subproject commit 9341dd35f83bcc2c4e41cdd4ee16060a049d374d

@ -1,2 +1,14 @@
include(Scripts.cmake)
DFHACK_3RDPARTY_SCRIPT_REPO(dscorbett)
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)
install(DIRECTORY ${dfhack_SOURCE_DIR}/scripts
DESTINATION ${DFHACK_DATA_DESTINATION}
FILES_MATCHING PATTERN "*.lua"
PATTERN "*.rb"
PATTERN "3rdparty" EXCLUDE
)