Merge remote-tracking branch 'PeridexisErrant/docs-again' into develop

develop
lethosor 2015-11-07 15:50:11 -05:00
commit e176c3ea05
49 changed files with 1544 additions and 1390 deletions

@ -18,7 +18,7 @@ script:
- python travis/lint.py
- python travis/script-in-readme.py
- python travis/script-syntax.py --ext=lua --cmd="luac5.2 -p"
- python travis/script-syntax.py --ext=rb --cmd="ruby -c"
- python travis/script-syntax.py --ext=rb --cmd="ruby -c" --path scripts/
- mkdir build-travis
- cd build-travis
- cmake .. && make -j3

@ -214,7 +214,7 @@ if (BUILD_DOCS)
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.rb"
)
set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst index.rst)
set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst)
set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo")
set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE)

@ -4,14 +4,53 @@
Licenses
########
DFHack is distributed under a range of permissive and weakly copyleft licenses.
The core uses the ZLib license; the others are described below.
License of DFHack
=================
https://github.com/peterix/dfhack
Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com)
DFHack is distributed under the Zlib license, with some MIT-
and BSD-licensed components. These licenses protect your right
to use DFhack for any purpose, distribute copies, and so on.
The core, plugins, scripts, and other DFHack code all use the
ZLib license unless noted otherwise. By contributing to DFHack,
authors release the contributed work under this license.
DFHack also draws on several external packages.
Their licenses are summarised here and reproduced below.
=============== ============= =================================================
Component License Copyright
=============== ============= =================================================
DFHack_ Zlib \(c\) 2009-2012, Petr Mrázek
clsocket_ BSD 3-clause \(c\) 2007-2009, CarrierLabs, LLC.
dirent_ MIT \(c\) 2006, Toni Ronkko
JSON.lua_ CC-BY-SA_ \(c\) 2010-2014, Jeffrey Friedl
jsoncpp_ MIT \(c\) 2007-2010, Baptiste Lepilleur
linenoise_ BSD 2-clause \(c\) 2010, Salvatore Sanfilippo & Pieter Noordhuis
lua_ MIT \(c\) 1994-2008, Lua.org, PUC-Rio.
luafilesystem_ MIT \(c\) 2003-2014, Kepler Project
protobuf_ BSD 3-clause \(c\) 2008, Google Inc.
tinythread_ Zlib \(c\) 2010, Marcus Geelnard
tinyxml_ Zlib \(c\) 2000-2006, Lee Thomason
UTF-8-decoder_ MIT \(c\) 2008-2010, Bjoern Hoehrmann
=============== ============= =================================================
.. _DFHack: https://github.com/DFHack/dfhack
.. _clsocket: https://github.com/DFHack/clsocket
.. _dirent: https://github.com/tronkko/dirent
.. _JSON.lua: http://regex.info/blog/lua/json
.. _jsoncpp: https://github.com/open-source-parsers/jsoncpp
.. _linenoise: http://github.com/antirez/linenoise
.. _lua: http://www.lua.org
.. _luafilesystem: https://github.com/keplerproject/luafilesystem
.. _protobuf: https://github.com/google/protobuf
.. _tinythread: http://tinythreadpp.bitsnbites.eu/
.. _tinyxml: http://www.sourceforge.net/projects/tinyxml
.. _UTF-8-decoder: http://bjoern.hoehrmann.de/utf-8/decoder/dfa
.. _CC-BY-SA: http://creativecommons.org/licenses/by/3.0/deed.en_US
Zlib License
============
See https://en.wikipedia.org/wiki/Zlib_License
::
This software is provided 'as-is', without any express or implied
@ -24,8 +63,8 @@ Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com)
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.
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.
@ -33,196 +72,11 @@ Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com)
3. This notice may not be removed or altered from any source
distribution.
clsocket license
================
::
Copyright (c) 2007-2009 CarrierLabs, LLC. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.
3. The name of the author may not be used to endorse or promote products
derived from this software without specific prior written permission.
4. The name "CarrierLabs" must not be used to
endorse or promote products derived from this software without
prior written permission. For written permission, please contact
mark@carrierlabs.com.
THIS SOFTWARE IS PROVIDED BY MARK CARRIER ``AS IS'' AND ANY
EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MARK CARRIER OR
ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.
Lua license
MIT License
===========
Lua is licensed under the terms of the MIT license reproduced below.
This means that Lua is free software and can be used for both academic
and commercial purposes at absolutely no cost.
For details and rationale, see http://www.lua.org/license.html .
::
Copyright (C) 1994-2008 Lua.org, PUC-Rio.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
Protobuf license
================
::
Copyright 2008, Google Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
* Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Code generated by the Protocol Buffer compiler is owned by the owner
of the input file used when generating it. This code is not
standalone and requires a support library to be linked with it. This
support library is itself covered by the above license.
License of tinyxml (XML reader library)
=======================================
http://www.sourceforge.net/projects/tinyxml
Original code, 2.0 and earlier, copyright 2000-2006 Lee Thomason (http://www.grinninglizard.com)
::
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any
damages arising from the use of this software.
Permission is granted to anyone to use this software for any
purpose, including commercial applications, and to alter it and
redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must
not claim that you wrote the original software. If you use this
software in a product, an acknowledgment in the product documentation
would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and
must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source
distribution.
tinythread license
==================
::
Copyright (c) 2010 Marcus Geelnard
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source
distribution.
zlib license
============
::
Copyright (C) 1995-2010 Jean-loup Gailly and Mark Adler
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
dirent.h - dirent API for Microsoft Visual Studio
=================================================
See https://en.wikipedia.org/wiki/MIT_License
::
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
@ -237,35 +91,27 @@ dirent.h - dirent API for Microsoft Visual Studio
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.
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.
You can find the latest source code at http://github.com/antirez/linenoise
BSD Licenses
============
See https://en.wikipedia.org/wiki/BSD_licenses
::
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
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
@ -279,91 +125,21 @@ You can find the latest source code at http://github.com/antirez/linenoise
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
``linenoise`` adds no further clauses.
UTF-8 Decoder
=============
See http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details.
::
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:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
luafilesystem
=============
Parts of dfhack are based on luafilesystem:
::
Copyright (c) 2003-2014 Kepler Project.
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
jsoncpp
========
::
Copyright (c) 2007-2010 Baptiste Lepilleur
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
``protobuf`` adds the following clause::
3. Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
JSON.lua
========
Copyright 2010-2014 Jeffrey Friedl, http://regex.info/blog/
``clsocket`` adds the following clauses::
Latest version: http://regex.info/blog/lua/json
3. The name of the author may not be used to endorse or promote
products derived from this software without specific prior
written permission.
This code is released under a Creative Commons CC-BY "Attribution" License:
http://creativecommons.org/licenses/by/3.0/deed.en_US
4. The name "CarrierLabs" must not be used to endorse or promote
products derived from this software without prior written
permission. For written permission, please contact
mark@carrierlabs.com

@ -105,7 +105,7 @@ Fixes
- help: now recognizes built-in commands, like "help"
- `manipulator`: fixed crash when selecting custom professions when none are found
- `remotefortressreader`: fixed crash when attempting to send map info when no map was loaded
- `search`: fixed crash in unit list after cancelling a job; fixed crash when disabling stockpile category after searching in a subcategory
- `search-plugin`: fixed crash in unit list after cancelling a job; fixed crash when disabling stockpile category after searching in a subcategory
- `stockpiles`: now checks/sanitizes filenames when saving
- `stocks`: fixed a crash when right-clicking
- `steam-engine`: fixed a crash on arena load; number keys (e.g. 2/8) take priority over cursor keys when applicable
@ -160,7 +160,7 @@ Misc Improvements
- `prospect`: works from within command-prompt
- `quicksave`: Restricted to fortress mode
- `remotefortressreader`: Exposes more information
- `search`:
- `search-plugin`:
- Supports noble suggestion screen (e.g. suggesting a baron)
- Supports fortress mode loo[k] menu
@ -201,8 +201,8 @@ Lua
New Internal Commands
---------------------
- `hide, show`: hide and show the console on Windows
- sc-script: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts)
- `hide`, `show`: hide and show the console on Windows
- `sc-script`: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts)
New Plugins
-----------
@ -474,8 +474,8 @@ Misc Improvements
- `EventManager`: deals with frame_counter getting reset properly now.
- `modtools/item-trigger`: fixed equip/unequip bug and corrected minor documentation error
- `teleport`: Updated with proper argument handling and proper unit-at-destination handling.
- `autotrade <Stockpile automation>`: Removed the newly obsolete :guilabel:`Mark all` functionality.
- `search`: Adapts to the new trade screen column width
- `autotrade`: Removed the newly obsolete :guilabel:`Mark all` functionality.
- `search-plugin`: Adapts to the new trade screen column width
- `tweak fast-trade <tweak>`: Switching the fast-trade keybinding to Shift-Up/Shift-Down, due to Select All conflict
@ -490,8 +490,8 @@ Fixes
-----
- Stopped duplicate load/unload events when unloading a world
- Stopped ``-e`` from being echoed when DFHack quits on Linux
- `automelt <Stockpile automation>`: now uses a faster method to locate items
- `autotrade <Stockpile automation>`: "Mark all" no longer double-marks bin contents
- `automelt`: now uses a faster method to locate items
- `autotrade`: "Mark all" no longer double-marks bin contents
- `drain-aquifer`: new script replaces the buggy plugin
- `embark-tools`: no longer conflicts with keys on the notes screen
- `fastdwarf`: Fixed problems with combat/attacks
@ -541,18 +541,18 @@ Internals
New Plugins
-----------
- `hotkeys`: Shows ingame viewscreen with all dfhack keybindings active in current mode.
- `automelt <Stockpile automation>`: allows marking stockpiles so any items placed in them will be designated for melting
- `automelt`: allows marking stockpiles so any items placed in them will be designated for melting
Fixes
-----
- possible crash fixed for `gui/hack-wish`
- `search`: updated to not conflict with BUILDJOB_SUSPEND
- `search-plugin`: updated to not conflict with BUILDJOB_SUSPEND
- `workflow`: job_material_category -> dfhack_material_category
Misc Improvements
-----------------
- now you can use ``@`` to print things in interactive Lua with subtley different semantics
- optimizations for stockpiles for `autotrade <Stockpile automation>` and `stockflow`
- optimizations for stockpiles for `autotrade` and `stockflow`
- updated `exportlegends` to work with new maps, dfhack 40.11 r1+
@ -565,7 +565,7 @@ Internals
Fixes
-----
- `3dveins`: should no longer hang/crash on specific maps
- `autotrade <Stockpile automation>`, `search`: fixed some layout issues
- `autotrade`, `search-plugin`: fixed some layout issues
- `deathcause`: updated
- `gui/hack-wish`: should work now
- `reveal`: no longer allocates data for nonexistent map blocks

@ -4,13 +4,13 @@
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="0;url=./docs/html/index.html">
<meta http-equiv="refresh" content="0;url=./docs/html/docs/index.html">
<script type="text/javascript">
window.location.href = "./docs/html/index.html"
window.location.href = "./docs/html/docs/index.html"
</script>
<title>Page Redirection</title>
</head>
<body>
Follow this <a href='./docs/html/index.html'>link to the documentation.</a>
Follow this <a href='./docs/html/docs/index.html'>link to the documentation.</a>
</body>
</html>

@ -1,8 +1,7 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# DFHack documentation build configuration file, created by
# sphinx-quickstart on Tue Sep 22 17:34:54 2015.
# DFHack documentation build configuration file
#
# This file is execfile()d with the current directory set to its
# containing dir.
@ -18,25 +17,24 @@ from io import open
import os
import shlex
import sys
import shutil
# -- Autodoc for DFhack scripts -------------------------------------------
def doc_dir(dirname, files):
"""Yield (command, includepath) for each script in the directory."""
sdir = os.path.relpath(dirname, '.').replace('\\', '/').replace('../', '')
for f in files:
if f[-3:] not in {'lua', '.rb'}:
if f[-3:] not in ('lua', '.rb'):
continue
with open(os.path.join(dirname, f), 'r', encoding='utf8') as fstream:
text = [l.rstrip() for l in fstream.readlines() if l.strip()]
command = None
for line in text:
if line == len(line) * '=':
if command is not None:
if command and line == len(line) * '=':
yield command, sdir + '/' + f
break
command = line
# later, print an error for missing docs here
def document_scripts():
@ -89,11 +87,6 @@ def document_scripts():
document_scripts()
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
@ -113,24 +106,22 @@ extlinks = {
'Bay12 forums thread '),
'dffd': ('http://dffd.bay12games.com/file.php?id=%s', 'DFFD file '),
'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s',
'Bug ')
'Bug '),
'issue': ('https://github.com/DFHack/dfhack/issues/%s', 'Issue '),
}
# some aliases for link directives
extlinks['forum'] = extlinks['forums']
# Add any paths that contain templates here, relative to this directory.
templates_path = []
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
master_doc = 'docs/index'
# General information about the project.
project = 'DFHack'
@ -145,7 +136,7 @@ def get_version():
"""Return the DFHack version string, from CMakeLists.txt"""
version = release = ''
try:
with open('../CMakeLists.txt') as f:
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 "', '')
@ -179,19 +170,9 @@ exclude_patterns = ['docs/_build/*', 'depends/*', 'scripts/3rdparty/*', 'build*'
# documents.
default_role = 'ref'
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
@ -245,7 +226,7 @@ html_static_path = ['docs/styles']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
html_last_updated_fmt = '%Y-%m-%d'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
@ -255,9 +236,9 @@ html_static_path = ['docs/styles']
html_sidebars = {
'**': [
'about.html',
'localtoc.html',
'relations.html',
'searchbox.html',
'localtoc.html',
]
}
@ -288,19 +269,6 @@ html_use_index = False
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
#html_search_language = 'en'
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'DFHackdoc'

@ -21,15 +21,18 @@ Caldfir caldfir
Chris Dombroski cdombroski
Clayton Hughes
David Corbett dscorbett
Deon
DoctorVanGogh DoctorVanGogh
Donald Ruegsegger hashaash
doomchild doomchild
enjia2000
Eric Wald eswald
Erik Youngren Artanis
Espen Wiborg
expwnent expwnent
Feng
Harlan Playford playfordh
IndigoFenix
James Logsdon jlogsdon
Japa JapaMala
Jared Adams
@ -40,11 +43,14 @@ Jonas Ask
kane-t kane-t
Kelly Martin ab9rf
Kris Parker kaypy
Kurik Amudnil
Lethosor lethosor
Mason11987 Mason11987
Matthew Cline
Max maxthyme Max^TM
melkor217 melkor217
Meneth32
Meph
Michon van Dooren MaienM
miffedmap miffedmap
Mike Stewart thewonderidiot
@ -53,6 +59,7 @@ MithrilTuxedo MithrilTuxedo
mizipzor mizipzor
Neil Little nmlittle
Nick Rart nickrart comestible
Omniclasm
PeridexisErrant PeridexisErrant
Petr Mrázek peterix
potato
@ -64,6 +71,7 @@ rampaging-poet
Raoul van Putten
Raoul XQ raoulxq
reverb
Raidau Raidau
Rinin Rinin
Robert Heinrich rh73
rofl0r rofl0r
@ -78,6 +86,7 @@ scamtank scamtank
Seth Woodworth sethwoodworth
simon
Simon Jackson sizeak
Tacomagic
Tim Walberg twalberg
Timothy Collett danaris
Tom Prince

@ -32,8 +32,7 @@ decent skill in `memory research <contributing-memory-research>`.
* 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.
* :issue:`546` is about the future of the binpatches, and may be useful reading.
If you want to write a patch, the armory patches discussed here and documented
below would probably be the best place to start.
@ -56,7 +55,7 @@ the version appropriate for the currently loaded executable.
This is the preferred method; it's easier to debug, does not cause persistent
problems, and leaves file checksums alone. As with many other commands, users
can simply add it to ``dfhack.init`` to reapply the patch every time DF is run.
can simply add it to `dfhack.init` to reapply the patch every time DF is run.
Patching on disk
@ -152,8 +151,8 @@ these rules is intended by Toady; the rest are invented by this plugin.
gui/assign-rack
---------------
Bind to a key (the example config uses P), and activate when viewing a weapon
rack in the ``q`` mode.
Bind to a key (the example config uses :kbd:`P`), and activate when viewing a weapon
rack in the :kbd:`q` mode.
.. image:: images/assign-rack.png
@ -166,9 +165,7 @@ work again. The existing issues are:
* Even if assigned by the script, **the game will unassign the racks again
without a binary patch**. This patch is called ``weaponrack-unassign``,
and has not been updated since 0.34.11. See `the bug report`_ for more info.
.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445
and has not been updated since 0.34.11. See :bug:`1445` for more info.
* Haulers still take equipment stored in the armory away to the stockpiles,
unless `fix-armory` is used.

@ -2,28 +2,20 @@
Compiling DFHack
################
.. important::
You don't need to compile DFHack unless you're developing plugins or working on the core.
For users, modders, and authors of scripts it's better to download the latest release instead.
You don't need to compile DFHack unless you're developing plugins or working on the core.
For users, modders, and authors of scripts it's better to download
and `install the latest release instead <installing>`.
.. contents::
:depth: 2
===================
How to get the code
===================
DFHack doesn't have any kind of system of code snapshots in place, so you will have to
get code from the github repository using git.
The code resides at https://github.com/DFHack/dfhack
On Linux and OS X, having a ``git`` package installed is the minimal requirement (see below for OS X instructions),
but some sort of git gui or git integration for your favorite text editor/IDE will certainly help.
On Windows, you will need some sort of Windows port of git, or a GUI. Some examples:
* http://msysgit.github.io - this is a command line version of git for windows.
Most tutorials on git usage will apply.
* http://code.google.com/p/tortoisegit - this puts a pretty, graphical face on top of msysgit
get code from the github repository using git. How to get git is described under
the instructions for each platform.
To get the code::
@ -33,22 +25,14 @@ To get the code::
If your version of git does not support the ``--recursive`` flag, you will need to omit it and run
``git submodule update --init`` after entering the dfhack directory.
If you just want to compile DFHack or work on it by contributing patches, it's quite
enough to clone from the read-only address instead::
git clone --recursive git://github.com/DFHack/dfhack.git
cd dfhack
If you want to get really involved with the development, create an account on
If you want to get involved with the development, create an account on
Github, make a clone there and then use that as your remote repository instead.
Detailed instructions are beyond the scope of this document. If you need help,
join us on IRC (#dfhack channel on freenode).
We'd love that; join us on IRC (#dfhack channel on freenode) if you need help.
===========
Build types
===========
``cmake`` allows you to pick a build type by changing this
variable: ``CMAKE_BUILD_TYPE`` ::
``cmake`` allows you to pick a build type by changing the ``CMAKE_BUILD_TYPE`` variable::
cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE
@ -58,34 +42,38 @@ Without specifying a build type or 'None', cmake uses the
Valid and useful build types include 'Release', 'Debug' and
'RelWithDebInfo'. 'Debug' is not available on Windows.
=====
Linux
=====
On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD.
Dependencies
============
------------
DFHack is meant to be installed into an existing DF folder, so get one ready.
For building, you need a 32-bit version of GCC. For example, to build DFHack on
a 64-bit distribution like Arch, you'll need the multilib development tools and libraries.
Alternatively, you might be able to use ``lxc`` to
`create a virtual 32-bit environment <http://www.bay12forums.com/smf/index.php?topic=139553.msg5435310#msg5435310>`_.
We assume that any Linux platform will have ``git`` available.
To build DFHack you need a 32-bit version of GCC. On 64-bit distributions
(which is most of them), this means you'll need the multilib development tools
and libraries. Alternatively, you might be able to use ``lxc`` to
:forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`.
Before you can build anything, you'll also need ``cmake``. It is advisable to also get
``ccmake`` on distributions that split the cmake package into multiple parts.
You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation parts).
You should be able to find them in your distro repositories (on Arch linux
``perl-xml-libxml`` and ``perl-xml-libxslt``) or through ``cpan``.
You should be able to find them in your distro repositories.
* On Arch linux, ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``)
* On 64-bit Ubuntu, ``apt-get install zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``.
* On 32-bit Ubuntu, ``apt-get install zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``.
* Debian-derived distros should have similar requirements.
To build Stonesense, you'll also need OpenGL headers.
Some additional dependencies for other distros are listed on the
`wiki <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::
@ -103,14 +91,12 @@ Alternatively, you can use ccmake instead of cmake::
make install
This will show a curses-based interface that lets you set all of the
extra options.
You can also use a cmake-friendly IDE like KDevelop 4 or the cmake-gui
program.
extra options. You can also use a cmake-friendly IDE like KDevelop 4
or the cmake-gui program.
Fixing the libstdc++ version bug
================================
Incompatible libstdc++
~~~~~~~~~~~~~~~~~~~~~~
When compiling dfhack yourself, it builds against your system libc.
When Dwarf Fortress runs, it uses a libstdc++ shipped with the binary, which
comes from GCC 4.5 and is incompatible with code compiled with newer GCC versions.
@ -119,62 +105,64 @@ This manifests itself with the error message::
./libs/Dwarf_Fortress: /pathToDF/libs/libstdc++.so.6: version
`GLIBCXX_3.4.15' not found (required by ./hack/libdfhack.so)
To fix this, simply remove the libstdc++ shipped with DF, it will fall back
to your system lib and everything will work fine::
To fix this, you can compile DFHack with GCC 4.5 - or simply remove the
libstdc++ shipped with DF, and it will fall back to your system lib::
cd /path/to/DF/
rm libs/libstdc++.so.6
Alternatively, this issue can be avoided by compiling DFHack with GCC 4.5.
========
Mac OS X
========
DFHack functions similarly on OS X and Linux, and the majority of the
information above regarding the build process (cmake and make) applies here
as well.
* If you are building on 10.6, please read the subsection below titled "Snow Leopard Changes" FIRST.
* If you are building on 10.10+, read the "Yosemite Changes" subsection before building.
If you have issues building on OS X Yosemite (or above), try definining the
following environment variable::
export MACOSX_DEPLOYMENT_TARGET=10.9
1. Download and unpack a copy of the latest DF
2. Install Xcode from Mac App Store
3. Open Xcode, go to Preferences > Downloads, and install the Command Line Tools.
4. Install dependencies
#. Download and unpack a copy of the latest DF
#. Install Xcode from Mac App Store
#. Open Xcode, go to Preferences > Downloads, and install the Command Line Tools.
#. Install dependencies
Option 1: Using Homebrew:
Using `Homebrew <http://brew.sh/>`_::
* `Install Homebrew <http://brew.sh/>`_ and run:
* ``brew tap homebrew/versions``
* ``brew install git``
* ``brew install cmake``
* ``brew install gcc45``
brew tap homebrew/versions
brew install git
brew install cmake
brew install gcc45
Option 2: Using MacPorts:
Using `MacPorts <https://www.macports.org>`_::
* `Install MacPorts <http://www.macports.org/>`_
* Run ``sudo port install gcc45 +universal cmake +universal git-core +universal``
This will take some time—maybe hours, depending on your machine.
sudo port install gcc45 +universal cmake +universal git-core +universal
At some point during this process, it may ask you to install a Java environment; let it do so.
Macports will take some time - maybe hours. At some point it may ask
you to install a Java environment; let it do so.
5. Install perl dependencies
#. Install perl dependencies
1. ``sudo cpan``
If this is the first time you've run cpan, you will need to go through the setup
process. Just stick with the defaults for everything and you'll be fine.
If you are running Snow Leopard (ie 10.6 or earlier), good luck!
You'll need to open a separate Terminal window and run::
sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml
2. ``install XML::LibXML``
3. ``install XML::LibXSLT``
6. Get the dfhack source::
#. Get the dfhack source::
git clone --recursive https://github.com/DFHack/dfhack.git
cd dfhack
7. Set environment variables:
#. Set environment variables:
Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``)::
@ -186,7 +174,7 @@ as well.
export CC=/opt/local/bin/gcc-mp-4.5
export CXX=/opt/local/bin/g++-mp-4.5
8. Build dfhack::
#. Build dfhack::
mkdir build-osx
cd build-osx
@ -195,42 +183,24 @@ as well.
make install
Snow Leopard Changes
====================
1. Add a step 6.2a (before Install XML::LibXSLT)::
In a separate Terminal window or tab, run:
``sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml``
2. Add a step 7a (before building)::
In <dfhack directory>/library/LuaTypes.cpp, change line 467 to
``int len = strlen((char*)ptr);``
Yosemite Changes
================
If you have issues building on OS X Yosemite (or above), try definining the
following environment variable::
export MACOSX_DEPLOYMENT_TARGET=10.9
=======
Windows
=======
On Windows, DFHack replaces the SDL library distributed with DF.
Dependencies
============
First, you need ``cmake``. Get the win32 installer version from the official
site: http://www.cmake.org/cmake/resources/software.html
------------
You will need some sort of Windows port of git, or a GUI. Some examples:
* `Git for Windows <https://git-for-windows.github.io>`_ (command-line and GUI)
* `tortoisegit <https://tortoisegit.org>`_ (GUI and File Explorer integration)
You need ``cmake``. Get the win32 installer version from
`the official site <http://www.cmake.org/cmake/resources/software.html>`_.
It has the usual installer wizard. Make sure you let it add its binary folder
to your binary search PATH so the tool can be later run from anywhere.
You'll need a copy of Microsoft Visual C++ 2010. The Express version is sufficient.
Grab it from Microsoft's site.
You'll also need the Visual Studio 2010 SP1 update.
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 <http://strawberryperl.com>`_ works nicely for this.
@ -241,24 +211,30 @@ install libxml and libxslt for it instead. Strawberry perl works though and has
all the required packages.
Build
=====
There are several different batch files in the ``build`` folder along with a script that's used for picking the DF path.
-----
There are several different batch files in the ``build`` folder along
with a script that's used for picking the DF path.
First, run set_df_path.vbs and point the dialog that pops up at your DF folder that you want to use for development.
First, run ``set_df_path.vbs`` and point the dialog that pops up at your
DF folder that you want to use for development.
Next, run one of the scripts with ``generate`` prefix. These create the MSVC solution file(s):
* ``all`` will create a solution with everything enabled (and the kitchen sink).
* ``gui`` will pop up the cmake gui and let you pick and choose what to build. This is probably what you want most of the time. Set the options you are interested in, then hit configure, then generate. More options can appear after the configure step.
* ``minimal`` will create a minimal solution with just the bare necessities - the main library and standard plugins.
* ``gui`` will pop up the cmake gui and let you pick and choose what to build.
This is probably what you want most of the time. Set the options you are interested
in, then hit configure, then generate. More options can appear after the configure step.
* ``minimal`` will create a minimal solution with just the bare necessities -
the main library and standard plugins.
Then you can either open the solution with MSVC or use one of the msbuild scripts:
* Scripts with ``build`` prefix will only build.
* Scripts with ``build`` prefix will only build DFHack.
* Scripts with ``install`` prefix will build DFHack and install it to the previously selected DF path.
* Scripts with ``package`` prefix will build and create a .zip package of DFHack.
When you open the solution in MSVC, make sure you never use the Debug builds. Those aren't
binary-compatible with DF. If you try to use a debug build with DF, you'll only get crashes.
So pick either Release or RelWithDebInfo build and build the INSTALL target.
The ``debug`` scripts actually do RelWithDebInfo builds.
For this reason the Windows "debug" scripts actually do RelWithDebInfo builds,
so pick either Release or RelWithDebInfo build and build the INSTALL target.

@ -11,7 +11,6 @@ Several things should be kept in mind when contributing code to DFHack.
Code Format
-----------
* Four space indents for C++. Never use tabs for indentation in any language.
* LF (Unix style) line terminators
* Avoid trailing whitespace
@ -25,14 +24,18 @@ Code Format
How to get new code into DFHack
-------------------------------
* Submit pull requests to the ``develop`` branch, not the master branch. The master branch always points at the most recent release.
* Use new branches for each feature/fix so that your changes can be merged independently (i.e. not the master or develop branch of your fork).
* Submit pull requests to the ``develop`` branch, not the ``master`` branch.
(The ``master`` branch always points at the most recent release)
* Use a new branch for each feature or bugfix so that your changes can be merged independently
(i.e. not the master or develop branch of your fork).
* If possible, compile on multiple platforms when changing anything that compiles
* Update ``NEWS`` and ``docs/Authors.rst`` when applicable
* It must pass CI - run ``python travis/all.py`` to check this.
* Update ``NEWS.rst`` and ``docs/Authors.rst`` when applicable.
* Create a GitHub pull request once finished
* Work done against GitHub issues tagged "bug" get priority
* Submit ideas and bug reports as issues on GitHub. Posts in the forum thread can easily get missed or forgotten.
* Submit ideas and bug reports as :issue:`issues on GitHub <>`.
Posts in the forum thread can easily get missed or forgotten.
* Work on :issue:`reported problems <?q=is:open+-label:idea>`
will take priority over ideas or suggestions.
.. _contributing-memory-research:
@ -62,7 +65,8 @@ All the plugins can be found in the 'plugins' folder. There's no in-depth docume
on how to write one yet, but it should be easy enough to copy one and just follow the pattern.
``plugins/skeleton/skeleton.cpp`` is provided for this purpose.
Other than through plugins, it is possible to use DFHack via remote access interface, or by writing Lua scripts.
Other than through plugins, it is possible to use DFHack via remote access interface,
or by writing scripts in Lua or Ruby. There are plenty of examples in the scripts folder.
The most important parts of DFHack are the Core, Console, Modules and Plugins.
@ -164,10 +168,10 @@ text. Use double-backticks to put commands in monospaced font, like this::
You can use ``cleanowned scattered x`` to dump tattered or abandoned items.
If the command takes more than three arguments, format the list as a table
called Options. The table *only* lists arguments, not full commands.
called Usage. The table *only* lists arguments, not full commands.
Input values are specified in angle brackets. Example::
Options:
Usage:
:arg1: A simple argument.
:arg2 <input>: Does something based on the input value.

@ -1,216 +1,106 @@
.. _dfhack-core:
###########
DFHack Core
###########
.. contents::
==============
Getting DFHack
==============
The project is currently hosted at http://www.github.com/
Recent releases are available in source and binary formats `on the releases
page`_, while the binaries for releases 0.40.15-r1 to 0.34.11-r4 are on DFFD_.
Even older versions are available here_.
.. _`on the releases page`: http://github.com/DFHack/dfhack/releases
.. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15
.. _here: http://dethware.org/dfhack/download
All new releases are announced in `the bay12 forums thread`_, which is also a
good place for discussion and questions.
.. _`the Bay12 DFHack thread`:
.. _`the bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=139553
If this sounds too complicated, you might prefer to `get a Starter Pack`_.
These are packages for new players or those who don't want to set up everything
themselves, and are available - with DFHack configured - for all OSes.
.. _`get a Starter Pack`: http://dwarffortresswiki.org/index.php/Utility:Lazy_Newb_Pack
Compatibility
=============
DFHack is available for Windows (XP or later), Linux (any modern distribution),
or OS X (10.6.8 to 10.9).
Most releases only support the version of DF mentioned in their title - for
example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases
support earlier DF versions as well. Wherever possible, use the latest version
built for the target version of DF.
On Windows, DFHack is compatible with the SDL version of DF, but not the legacy version.
It is also possible to use the Windows DFHack with Wine under Linux and OS X.
Installation/Removal
====================
Installing DFhack involves copying files into your DF folder.
Copy the files from a release archive so that:
* On Windows, ``SDL.dll`` is replaced
* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script
DFHack commands can be implemented in three ways, all of which
are used in the same way:
Uninstalling is basically the same, in reverse:
:builtin: commands are implemented by the core of DFHack. They manage
other DFhack tools, interpret commands, and control basic
aspects of DF (force pause or quit).
* 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.
:plugins: are stored in ``hack/plugins/`` and must be compiled with the
same version of DFHack. They are less flexible than scripts,
but used for complex or ongoing tasks becasue they run faster.
The stonesense plugin might require some additional libraries on Linux.
:scripts: are Ruby or Lua scripts stored in ``hack/scripts/``.
Because they don't need to be compiled, scripts are
more flexible about versions, and easier to distribute.
Most third-party DFHack addons are scripts.
If any of the plugins or dfhack itself refuses to load, check the ``stderr.log``
file created in your DF folder.
.. contents::
===============
Getting started
===============
If DFHack is installed correctly, it will automatically pop up a console
window once DF is started as usual on windows. Linux and Mac OS X require
running the dfhack script from the terminal, and will use that terminal for
the console.
**NOTE**: The ``dfhack-run`` executable is there for calling DFHack commands in
an already running DF+DFHack instance from external OS scripts and programs,
and is *not* the way how you use DFHack normally.
DFHack has a lot of features, which can be accessed by typing commands in the
console, or by mapping them to keyboard shortcuts. Most of the newer and more
user-friendly tools are designed to be at least partially used via the latter
way.
In order to set keybindings, you have to create a text configuration file
called ``dfhack.init``; the installation comes with an example version called
``dfhack.init-example``, which is fully functional, covers all of the recent
features and can be simply renamed to ``dfhack.init``. You are encouraged to look
through it to learn which features it makes available under which key combinations.
Using DFHack
============
DFHack basically extends what DF can do with something similar to the drop-down
console found in Quake engine games. On Windows, this is a separate command line
window. On Linux, the terminal used to launch the dfhack script is taken over
(so, make sure you start from a terminal). Basic interaction with dfhack
involves entering commands into the console. For some basic instructions,
use the ``help`` command. To list all possible commands, use the ``ls`` command.
Many commands have their own help or detailed description. You can use
``command help`` or ``command ?`` to show that.
The command line has some nice line editing capabilities, including history
that's preserved between different runs of DF (use up/down keys to go through
the history).
The second way to interact with DFHack is to bind the available commands
to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally
opened with the ``h`` key). Binding the commands is done by assigning a command as
a hotkey name (with ``n``).
A new and more flexible way is the keybinding command in the dfhack console.
However, bindings created this way are not automatically remembered between runs
of the game, so it becomes necessary to use the dfhack.init file to ensure that
they are re-created every time it is loaded.
Built-in Commands
=================
The following commands are provided by the 'core' components
of DFhack, rather than plugins or scripts.
Interactive commands like `liquids` cannot be used as hotkeys.
Many commands come from plugins, which are stored in ``hack/plugins/``
and must be compiled with the same version of DFHack. Others come
from scripts, which are stored in ``hack/scripts``. Scripts are much
more flexible about versions, and easier to distribute - so most third-party
DFHack addons are scripts.
.. _cls:
Something doesn't work, help!
=============================
First, don't panic :)
cls
---
Clear the terminal. Does not delete command history.
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 <https://github.com/DFHack/dfhack/issues>`_,
or visit `the #dfhack IRC channel on freenode
<https://webchat.freenode.net/?channels=dfhack>`_.
.. _die:
=============
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.
die
---
Instantly kills DF without saving.
If the first non-whitespace character of a line is ``#``, the line is treated
as a comment, i.e. a silent no-op command.
When reading commands from dfhack.init or with the ``script`` command, if the final
character on a line is a backslash then the next uncommented line is considered a
continuation of that line, with the backslash deleted. Commented lines are skipped,
so it is possible to comment out parts of a command with the ``#`` character.
.. _disable:
If the first non-whitespace character is ``:``, the command is parsed in a special
alternative mode: first, non-whitespace characters immediately following the ``:``
are used as the command name; the remaining part of the line, starting with the first
non-whitespace character *after* the command name, is used verbatim as the first argument.
The following two command lines are exactly equivalent::
.. _enable:
:foo a b "c d" e f
foo "a b \"c d\" e f"
enable
------
Many plugins can be in a distinct enabled or disabled state. Some of
them activate and deactivate automatically depending on the contents
of the world raws. Others store their state in world data. However a
number of them have to be enabled globally, and the init file is the
right place to do it.
This is intended for commands like ``rb_eval`` that evaluate script language statements.
Most such plugins or scripts support the built-in ``enable`` and ``disable``
commands. Calling them at any time without arguments prints a list
of enabled and disabled plugins, and shows whether that can be changed
through the same commands.
Almost all the commands support using the ``help <command-name>`` built-in command
to retrieve further help without having to look at this document. Alternatively,
some accept a ``help`` or ``?`` as an option on their command line.
To enable or disable plugins that support this, use their names as
arguments for the command::
.. note::
enable manipulator search
Some tools work by displaying dialogs or overlays in the game window.
In order to avoid confusion, these tools display the word "DFHack" while active. If they
merely add keybinding hints to existing screens, they use red instead of green for the key.
.. _fpause:
fpause
------
Forces DF to pause. This is useful when your FPS drops below 1 and you lose
control of the game.
Init files
==========
DFHack allows users to automatically run commonly-used DFHack commands when DF is first
loaded, when a game is loaded, and when a game is unloaded.
Init scripts function the same way they would if the user manually typed in their contents,
but are much more convenient. If your DF folder contains at least one file with a name
following the format ``dfhack*.init`` where ``*`` is a placeholder for any string (including
the empty string), then all such files are executed in alphabetical order as init scripts when
DF is first loaded.
.. _help:
If your DF folder does not contain any such files, then DFHack will execute ``dfhack.init-example``
as an example of useful commands to be run automatically. If you want DFHack to do nothing on
its own, then create an empty ``dfhack.init`` file in the main DF directory, or delete ``dfhack.init-example``.
help
----
Most commands support using the ``help <command>`` built-in command
to retrieve further help without having to look at this document.
``? <cmd>`` and ``man <cmd>`` are aliases.
The file ``dfhack.init-example`` is included as an example for users to follow if they need DFHack
command executed automatically. We recommend modifying or deleting ``dfhack.init-example`` as
its settings will not be optimal for all players.
Some commands (including many scripts) instead take ``help`` or ``?``
as an option on their command line - ie ``<cmd> help``.
In order to facilitate savegave portability, mod merging, and general organization of init files,
DFHack supports multiple init files both in the main DF directory and save-specific init files in
the save folders.
DFHack looks for init files in three places.
.. _hide:
It will look for them in the main DF directory, and in ``data/save/_____/raw`` and
``data/save/_____/raw/objects`` where ``_____`` is the name of the current savegame.
hide
----
Hides the DFHack terminal window. Only available on Windows.
When a game is loaded, DFHack looks for files of the form ``onLoad*.init``, where
``*`` can be any string, including the empty string.
When a game is unloaded, DFHack looks for files of the form ``onUnload*.init``. Again,
these files may be in any of the above three places. All matching init files will be
executed in alphebetical order.
.. _keybinding:
Setting keybindings
===================
keybinding
----------
To set keybindings, use the built-in ``keybinding`` command. Like any other
command it can be used at any time from the console, but it is most useful
in the DFHack init file.
command it can be used at any time from the console, but bindings are not
remembered between runs of the game unless re-created in `dfhack.init`.
Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, or F1-F12 are supported.
@ -239,78 +129,233 @@ as a hotkey are always considered applicable.
The ``context`` part in the key specifier above can be used to explicitly restrict
the UI state where the binding would be applicable. If called without parameters,
the ``keybinding`` command among other things prints the current context string.
Only bindings with a ``context`` tag that either matches the current context fully,
or is a prefix ending at a ``/`` boundary would be considered for execution, i.e.
for context ``foo/bar/baz``, possible matches are any of ``@foo/bar/baz``, ``@foo/bar``,
``@foo`` or none. Multiple contexts can be specified by separating them with a
pipe (``|``) - for example, ``@foo|bar|baz/foo``.
when in context ``foo/bar/baz``, keybindings restricted to any of ``@foo/bar/baz``,
``@foo/bar``, ``@foo`` or none will be active.
Hotkeys
=======
Opens an in-game screen showing DFHack keybindings that are active in the current context.
Multiple contexts can be specified by separating them with a
pipe (``|``) - for example, ``@foo|bar|baz/foo`` would match
anything under ``@foo``, ``@bar``, or ``@baz/foo``.
.. image:: images/hotkeys.png
Interactive commands like `liquids` cannot be used as hotkeys.
Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a
globally active hotkey. The default keybinding is ``Ctrl-F1``.
.. _command-prompt:
.. _kill-lua:
In-game command prompt
======================
The ``command-prompt`` plugin adds an in-game DFHack terminal, where you
can enter other commands. It's default keybinding is Ctrl-Shift-P.
kill-lua
--------
Stops any currently-running Lua scripts. By default, scripts can
only be interrupted every 256 instructions. Use ``kill-lua force``
to interrupt the next instruction.
A one line command prompt in df. Same as entering command into dfhack console. Best
used as a keybinding. Can be called with optional "entry" that will start prompt with
that pre-filled.
.. image:: images/command-prompt.png
.. _load:
.. _unload:
.. _reload:
Enabling plugins
================
Many plugins can be in a distinct enabled or disabled state. Some of
them activate and deactivate automatically depending on the contents
of the world raws. Others store their state in world data. However a
number of them have to be enabled globally, and the init file is the
right place to do it.
load
----
``load``, ``unload``, and ``reload`` control whether a plugin is loaded
into memory - note that plugins are loaded but disabled unless you do
something. Usage::
Most such plugins or scripts support the built-in ``enable`` and ``disable``
commands. Calling them at any time without arguments prints a list
of enabled and disabled plugins, and shows whether that can be changed
through the same commands.
load|unload|reload PLUGIN|(-a|--all)
To enable or disable plugins that support this, use their names as
arguments for the command::
Allows dealing with plugins individually by name, or all at once.
enable manipulator search
.. _ls:
Game progress
=============
ls
--
``ls`` does not list files like the Unix command, but rather
available commands - first built in commands, then plugins,
and scripts at the end. Usage:
:ls -a: Also list scripts in subdirectories of ``hack/scripts/``,
which are generally not intended for direct use.
:ls <plugin>: List subcommands for the given plugin.
.. _plug:
plug
----
Lists available plugins, including their state and detailed description.
``plug``
Lists available plugins (*not* commands implemented by plugins)
``plug [PLUGIN] [PLUGIN] ...``
List state and detailed description of the given plugins,
including commands implemented by the plugin.
die
---
Instantly kills DF without saving.
quicksave
.. _sc-script:
sc-script
---------
Save immediately, without exiting. Only available in fortress mode.
Allows additional scripts to be run when certain events occur
(similar to onLoad*.init scripts)
forcepause
----------
Forces DF to pause. This is useful when your FPS drops below 1 and you lose
control of the game. Activate with ``forcepause 1``; deactivate with ``forcepause 0``.
.. _`hide, show`:
.. _script:
script
------
Reads a text file, and runs each line as a DFHack command
as if it had been typed in by the user - treating the
input like `an init file <init-files>`.
Some other tools, such as `autobutcher` and `workflow`, export
their settings as the commands to create them - which are later
loaded with ``script``
.. _show:
show
----
Shows the terminal window after it has been `hidden <hide>`.
Only available on Windows. You'll need to use it from a
`keybinding` set beforehand, or the in-game `command-prompt`.
.. _type:
type
----
``type command`` shows where ``command`` is implemented.
Other Commands
--------------
The following commands are *not* built-in, but offer similarly useful functions.
* `command-prompt`
* `hotkeys`
* `lua`
* `multicmd`
* `nopause`
* `quicksave`
* `rb`
* `repeat`
.. _init-files:
Init Files
==========
DFHack allows users to automatically run commonly-used DFHack commands
when DF is first loaded, when a game is loaded, and when a game is unloaded.
Init scripts function the same way they would if the user manually typed
in their contents, but are much more convenient. In order to facilitate
savegave portability, mod merging, and general organization of init files,
DFHack supports multiple init files both in the main DF directory and
save-specific init files in the save folders.
DFHack looks for init files in three places each time they could be run:
#. The main DF directory
#. :file:`data/save/{world}/raw`, where ``world`` is the current save, and
#. :file:`data/save/{world}/raw/objects`
When reading commands from dfhack.init or with the `script` command, if the final
character on a line is a backslash then the next uncommented line is considered a
continuation of that line, with the backslash deleted. Commented lines are skipped,
so it is possible to comment out parts of a command with the ``#`` character.
.. _dfhack.init:
dfhack*.init
------------
If your DF folder contains at least one file named ``dfhack*.init``
(where ``*`` is a placeholder for any string), then all such files
are executed in alphabetical order when DF is first started.
DFHack is distributed with :download:`/dfhack.init-example` as an example
with an up-to-date collection of basic commands; mostly setting standard
keybindings and `enabling <enable>` plugins. You are encouraged to look
through this file to learn which features it makes available under which
key combinations. You may also customise it and rename it to ``dfhack.init``.
If your DF folder does not contain any ``dfhack*.init`` files, the example
will be run as a fallback.
These files are best used for keybindings and enabling persistent plugins
which do not require a world to be loaded.
.. _onLoad.init:
onLoad*.init
------------
When a world is loaded, DFHack looks for files of the form ``onLoad*.init``,
where ``*`` can be any string, including the empty string.
All matching init files will be executed in alphebetical order.
A world being loaded can mean a fortress, an adventurer, or legends mode.
These files are best used for non-persistent commands, such as setting
a `fix <fix>` script to run on `repeat`.
.. _onUnload.init:
onUnload*.init
--------------
When a world is unloaded, DFHack looks for files of the form ``onUnload*.init``.
Again, these files may be in any of the above three places.
All matching init files will be executed in alphebetical order.
Modders often use such scripts to disable tools which should not affect
an unmodded save.
hide / show
-----------
Hides or shows the DFHack terminal window, respectively. To use ``show``, use
the in-game console (default keybinding ``Ctrl-Shift-P``). Only available on Windows.
Other init files
----------------
* ``onMapLoad*.init`` and ``onMapUnload*.init`` are run when a map,
distinct from a world, is loaded. This is good for map-affecting
commands (eg `clean`), or avoiding issues in Legends mode.
* Any lua script named ``raw/init.d/*.lua``, in the save or main DF
directory, will be run when any world or that save is loaded.
Miscellaneous Notes
===================
This section is for odd but important notes that don't fit anywhere else.
* The ``dfhack-run`` executable is there for calling DFHack commands in
an already running DF+DFHack instance from external OS scripts and programs,
and is *not* the way how you use DFHack normally.
* If a DF :kbd:`H` hotkey is named with a DFHack command, pressing
the corresponding :kbd:`Fx` button will run that command, instead of
zooming to the set location.
* The command line has some nice line editing capabilities, including history
that's preserved between different runs of DF (use up/down keys to go through
the history).
* The binaries for 0.40.15-r1 to 0.34.11-r4 are on DFFD_.
Older versions are available here_.
.. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15&limit=1000
.. _here: http://dethware.org/dfhack/download
* To include whitespace in the argument/s to some command, quote it in
double quotes. To include a double quote character, use ``\"``.
* If the first non-whitespace character is ``:``, the command is parsed in
an alternative mode which is very useful for the `lua` and `rb` commands.
The following two command lines are exactly equivalent::
:foo a b "c d" e f
foo "a b \"c d\" e f"
nopause
-------
Disables pausing (both manual and automatic) with the exception of pause forced
by 'reveal hell'. This is nice for digging under rivers.
* non-whitespace characters following the ``:`` are the command name
* the remaining part of the line is used verbatim as the first argument

@ -0,0 +1,107 @@
.. _introduction:
#########################
Introduction and Overview
#########################
DFHack is a Dwarf Fortress memory access library, distributed with
a wide variety of useful scripts and plugins.
The project is currently hosted at https://www.github.com/DFHack/dfhack,
and can be downloaded from `the releases page
<http://github.com/DFHack/dfhack/releases>`_.
All new releases are announced in :forums:`the bay12 forums thread <139553>`,
which is also a good place for discussion and questions.
For users, it provides a significant suite of bugfixes and interface
enhancements by default, and more can be enabled. There are also many tools
(such as `workflow` or `autodump`) which can make life easier.
You can even add third-party scripts and plugins to do almost anything!
For modders, DFHack makes many things possible. Custom reactions, new
interactions, magic creature abilities, and more can be set through `modtools`
and custom raws. Non-standard DFHack scripts and inits can be stored in the
raw directory, making raws or saves fully self-contained for distribution -
or for coexistence in a single DF install, even with incompatible components.
For developers, DFHack unites the various ways tools access DF memory and
allows easier development of new tools. As an open-source project under
`various copyleft licences <license>`, contributions are welcome.
.. contents::
.. _installing:
Installing DFHack
=================
DFHack is available for the SDL version of Dwarf Frtress on Windows,
any modern Linux distribution, and OS X (10.6.8 to 10.9).
It is possible to use Windows DF+DFHack under Wine on Linux or OS X.
Most releases only support the version of DF mentioned in their title - for
example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases
support earlier DF versions as well. Wherever possible, use the latest version
of DFHack built for the target version of DF.
Installing DFhack involves copying files from a release archive
into your DF folder, so that:
* On Windows, ``SDL.dll`` is replaced
* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script
Uninstalling is basically the same, in reverse:
* On Windows, replace ``SDL.dll`` with ``SDLreal.dll``, then remove the DFHack files.
* On Linux or OSX, remove the DFHack files.
New players may wish to :wiki:`get a pack <Utility:Lazy_Newb_Pack>`
with DFHack preinstalled.
Getting started
===============
DFHack basically extends DF with something similar to the
console found in many PC games.
If DFHack is installed correctly, it will automatically pop up a console
window once DF is started as usual on Windows. Linux and Mac OS X require
running the dfhack script from the terminal, and will use that terminal for
the console.
* Basic interaction with dfhack involves entering commands into the console.
To learn what commands are available, you can keep reading this documentation
or skip ahead and use the `ls` and `help` commands.
* Another way to interact with DFHack is to set in-game `keybindings <keybinding>`
for certain commands. Many of the newer and user-friendly tools are designed
to be used this way.
* Commands can also run at startup via `init files <init-files>`,
on in batches at other times with the `script` command.
* Finally, some commands are persistent once enabled, and will sit in the
background managing or changing some aspect of the game if you `enable` them.
.. _troubleshooting:
Troubleshooting
===============
Don't panic! Even if you need this section, it'll be OK :)
If something goes wrong, check the log files in DF's folder
(``stderr.log`` and ``stdout.log``). Looking at these might help you -
or someone else - solve the problem. Take screenshots of any weird
error messages, and take notes on what you did to cause them.
If the search function in this documentation isn't enough and
:wiki:`the DF Wiki <>` hasn't helped, try asking in:
- the `#dfhack IRC channel on freenode <https://webchat.freenode.net/?channels=dfhack>`_
- the :forums:`Bay12 DFHack thread <139553>`
- the `/r/dwarffortress <https://dwarffortress.reddit.com>`_ questions thread
- the thread for the mod or Starter Pack you're using (if any)

File diff suppressed because it is too large Load Diff

@ -2,20 +2,10 @@
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.
Lua or ruby scripts placed in the :file:`hack/scripts/` directory
are considered for execution as if they were native DFHack commands.
Note: scripts in subdirectories of hack/scripts/ can still be called, but will
only be listed by ls if called as ``ls -a``. This is intended as a way to hide
scripts that are obscure, developer-oriented, or should be used as keybindings
or from the init file. See the page for each type for details.
``kill-lua`` stops any currently-running Lua scripts. By default, scripts can
only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt
the next instruction.
The following pages document all the standard DFHack scripts.
The following pages document all the scripts in the DFHack standard library.
.. toctree::
:maxdepth: 2

@ -4,8 +4,15 @@ Welcome to DFHack's documentation!
Introduction
============
DFHack is a Dwarf Fortress memory access library, distributed with scripts
and plugins implementing a wide variety of useful functions and tools.
DFHack is a Dwarf Fortress memory access library, distributed with
a wide variety of useful scripts and plugins.
The project is currently hosted at https://www.github.com/DFHack/dfhack,
and can be downloaded from `the releases page
<http://github.com/DFHack/dfhack/releases>`_.
All new releases are announced in :forums:`the bay12 forums thread <139553>`,
which is also a good place for discussion and questions.
For users, it provides a significant suite of bugfixes and interface
enhancements by default, and more can be enabled. There are also many tools
@ -29,9 +36,10 @@ User Manual
.. toctree::
:maxdepth: 2
docs/Core
docs/Plugins
docs/Scripts
/docs/Introduction
/docs/Core
/docs/Plugins
/docs/Scripts
Other Contents
==============
@ -39,9 +47,9 @@ Other Contents
.. toctree::
:maxdepth: 1
docs/Authors
LICENSE
NEWS
/docs/Authors
/LICENSE
/NEWS
For Developers
==============
@ -49,8 +57,9 @@ For Developers
.. toctree::
:maxdepth: 1
docs/Contributing
docs/Compile
docs/Lua API
library/xml/SYNTAX
docs/Binpatches
/docs/Contributing
/docs/Compile
/docs/Lua API
/library/xml/SYNTAX
/library/xml/how-to-update
/docs/Binpatches

@ -41,6 +41,17 @@ using df::nemesis_record;
using df::historical_figure;
using namespace DFHack::Translation;
/*
advtools
========
A package of different adventure mode tools. Usage:
:list-equipped [all]: List armor and weapons equipped by your companions.
If all is specified, also lists non-metal clothing.
:metal-detector [all-types] [non-trader]:
Reveal metal armor and weapons in shops. The options
disable the checks on item type and being in shop.
*/
DFHACK_PLUGIN("advtools");
REQUIRE_GLOBAL(world);

@ -20,6 +20,11 @@ using namespace std;
#include <df/unit_soul.h>
#include <df/unit_labor.h>
#include <df/unit_skill.h>
/*
dwarfexport
===========
Export dwarves to RuneSmith-compatible XML; also unused by modern tools.
*/
using namespace DFHack;
using df::global::ui;

@ -21,6 +21,12 @@ using namespace google::protobuf::io;
using namespace DFHack;
using df::global::world;
/*
mapexport
=========
Export the current loaded map as a file. This was used by visualizers for
DF 0.34.11, but is now basically obsolete.
*/
typedef std::vector<df::plant *> PlantList;

@ -14,6 +14,21 @@
using namespace std;
using namespace DFHack;
/*
misery
======
When enabled, every new negative dwarven thought will be multiplied by a factor (2 by default).
Usage:
:misery enable n: enable misery with optional magnitude n. If specified, n must be positive.
:misery n: same as "misery enable n"
:misery enable: same as "misery enable 2"
:misery disable: stop adding new negative thoughts. This will not remove existing
duplicated thoughts. Equivalent to "misery 1"
:misery clear: remove fake thoughts added in this session of DF. Saving makes them
permanent! Does not change factor.
*/
DFHACK_PLUGIN("misery");
DFHACK_PLUGIN_IS_ENABLED(is_enabled);

@ -20,6 +20,24 @@
//#include "df/world.h"
using namespace DFHack;
/*
treefarm
========
Automatically manages special burrows and regularly schedules tree chopping
and digging when appropriate.
Every time the plugin runs, it checks for burrows with a name containing the
string ``"treefarm"``. For each such burrow, it checks every tile in it for
fully-grown trees and for diggable walls. For each fully-grown tree it finds,
it designates the tree to be chopped, and for each natural wall it finds, it
designates the wall to be dug.
Usage:
:treefarm: Enables treefarm monitoring, starting next frame
:treefarm n: Enables treefarm monitoring, starting next frame, and sets
interval to n frames. If n is less than one, disables monitoring.
*/
DFHACK_PLUGIN("treefarm");
DFHACK_PLUGIN_IS_ENABLED(enabled);

@ -1,2 +1,6 @@
``devel/*`` scripts are intended for developers, or still substantially unfinished.
If you don't already know what they do, best to leave them alone.
``devel/*`` scripts are intended for developer use, but many may
be of interest to anyone investigating odd phenomema or just messing
around. They are documented to encourage such inquiry.
Some can PERMANENTLY DAMAGE YOUR SAVE if misused, so please be careful.
The warnings are real; if in doubt make backups before running the command.

@ -1,6 +1,14 @@
--all-bob.lua
--author expwnent
--names all units bob. Useful for testing interaction trigger events
--
--[[=begin
devel/all-bob
=============
Changes the first name of all units to "Bob".
Useful for testing `modtools/interaction-trigger` events.
=end]]
for _,v in ipairs(df.global.world.units.all) do
v.name.first_name = "Bob"

@ -1,5 +1,13 @@
-- Lists and/or compares two tiletype material groups.
-- Usage: devel/cmptiles material1 [material2]
--[[=begin
devel/cmptiles
==============
Lists and/or compares two tiletype material groups.
Usage: ``devel/cmptiles material1 [material2]``
=end]]
local nmat1,nmat2=...
local mat1 = df.tiletype_material[nmat1]

@ -1,4 +1,11 @@
-- Exports an ini file for Dwarf Therapist.
--[[=begin
devel/export-dt-ini
===================
Exports an ini file containing memory addresses for Dwarf Therapist.
=end]]
local utils = require 'utils'
local ms = require 'memscan'

@ -1,19 +1,39 @@
-- Find some offsets for linux.
--[[=begin
local utils = require 'utils'
local ms = require 'memscan'
local gui = require 'gui'
devel/find-offsets
==================
WARNING: THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS.
Running this script on a new DF version will NOT
MAKE IT RUN CORRECTLY if any data structures
changed, thus possibly leading to CRASHES AND/OR
PERMANENT SAVE CORRUPTION.
Finding the first few globals requires this script to be
started immediately after loading the game, WITHOUT
first loading a world. The rest expect a loaded save,
not a fresh embark. Finding current_weather requires
a special save previously processed with `devel/prepare-save`
on a DF version with working dfhack.
--[[
The script expects vanilla game configuration, without
any custom tilesets or init file changes. Never unpause
the game unless instructed. When done, quit the game
without saving using 'die'.
Arguments:
* global names to force finding them
* 'all' to force all globals
* 'nofeed' to block automated fake input searches
* 'nozoom' to disable neighboring object heuristics
* global names to force finding them
* ``all`` to force all globals
* ``nofeed`` to block automated fake input searches
* ``nozoom`` to disable neighboring object heuristics
]]
=end]]
local utils = require 'utils'
local ms = require 'memscan'
local gui = require 'gui'
local is_known = dfhack.internal.getAddress

@ -1,14 +1,26 @@
-- Injects new reaction, item and building defs into the world.
--[[=begin
-- The savegame contains a list of the relevant definition tokens in
-- the right order, but all details are read from raws every time.
-- This allows just adding stub definitions, and simply saving and
-- reloading the game.
devel/inject-raws
=================
WARNING: THIS SCRIPT CAN PERMANENLY DAMAGE YOUR SAVE.
-- Usage example:
--[[
devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER
]]
This script attempts to inject new raw objects into your
world. If the injected references do not match the actual
edited raws, your save will refuse to load, or load but crash.
The savegame contains a list of the relevant definition tokens in
the right order, but all details are read from raws every time.
This allows just adding stub definitions, and simply saving and
reloading the game.
This is useful enough for modders and some users to justify the danger.
Usage example::
devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER
=end]]
local utils = require 'utils'

@ -1,4 +1,11 @@
-- Read the tiles from the screen and display info about them.
--[[=begin
devel/inspect-screen
====================
Read the tiles from the screen and display info about them.
=end]]
local utils = require 'utils'
local gui = require 'gui'

@ -1,4 +1,15 @@
-- an experimental lighting engine for df. param: "static" to not recalc when in game. press "~" to recalculate. "`" to exit
-- an experimental lighting engine
--[[=begin
devel/light
===========
An experimental lighting engine for DF, using the `rendermax` plugin.
Call ``devel/light static`` to not recalculate lighting when in game.
Press :kbd:`~` to recalculate lighting. Press :kbd:`\`` to exit.
=end]]
local gui = require 'gui'
local guidm = require 'gui.dwarfmode'
local render = require 'plugins.rendermax'

@ -1,6 +1,12 @@
-- List input items for the building currently being built.
--
-- This is where the filters in lua/dfhack/buildings.lua come from.
--[[=begin
devel/list-filters
==================
List input items for the building currently being built.
This is where the filters in lua/dfhack/buildings.lua come from.
=end]]
local dumper = require 'dumper'
local utils = require 'utils'

@ -1,4 +1,11 @@
-- Prints memory ranges of the process.
--[[=begin
devel/lsmem
===========
Prints memory ranges of the process.
=end]]
for _,v in ipairs(dfhack.internal.getMemRanges()) do
local access = { '-', '-', '-', 'p' }

@ -1,4 +1,12 @@
-- Example of a lua script.
--[[=begin
devel/lua-example
=================
An example lua script, which reports the number of times it has
been called. Useful for testing environment persistence.
=end]]
run_count = (run_count or 0) + 1

@ -1,9 +0,0 @@
-- Force a migrants event in next 10 ticks.
df.global.timed_events:insert('#',{
new = true,
type = df.timed_event_type.Migrants,
season = df.global.cur_season,
season_ticks = df.global.cur_season_tick+1,
entity = df.historical_entity.find(df.global.ui.civ_id)
})

@ -1,6 +1,12 @@
-- Deletes ALL items not held by units, buildings or jobs.
--
-- Intended solely for lag investigation.
--[[=begin
devel/nuke-items
================
Deletes ALL items not held by units, buildings or jobs.
Intended solely for lag investigation.
=end]]
local count = 0

@ -1,3 +1,10 @@
-- For killing bugged out gui script screens.
--[[=begin
devel/pop-screen
================
For killing bugged out gui script screens.
=end]]
dfhack.screen.dismiss(dfhack.gui.getCurViewscreen())

@ -1,4 +1,16 @@
-- Prepare the current save for use with devel/find-offsets.
--[[=begin
devel/prepare-save
==================
WARNING: THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS.
This script prepares the current savegame to be used
with `devel/find-offsets`. It CHANGES THE GAME STATE
to predefined values, and initiates an immediate
`quicksave`, thus PERMANENTLY MODIFYING the save.
=end]]
local utils = require 'utils'

@ -1,6 +1,13 @@
--print-args.lua
--author expwnent
--prints all the arguments on their own line. useful for debugging
--[[=begin
devel/print-args
================
Prints all the arguments you supply to the script on their own line.
Useful for debugging other scripts.
=end]]
local args = {...}
for _,arg in ipairs(args) do

@ -1,6 +1,13 @@
--print-args2.lua
--author expwnent
--prints all the arguments on their own line with quotes around them. useful for debugging
--[[=begin
devel/print-args2
=================
Prints all the arguments you supply to the script on their own line
with quotes around them.
=end]]
local args = {...}
print("print-args")

@ -1,5 +1,11 @@
# list indexes in world.item.other[] where current selected item appears
# list indices in world.item.other[] where current selected item appears
=begin
devel/scanitemother
===================
List indices in ``world.item.other[]`` where current selected item appears.
=end
tg = df.item_find
raise 'select an item' if not tg

@ -13,17 +13,23 @@ df.world.raws.creatures.all.length.times { |r_idx|
df.world.arena_spawn.creature_cnt[df.world.arena_spawn.race.length-1] = 0
puts <<EOS
Arena spawn data initialized.
=begin
Now enter the 'k' menu, change mode using:
rb_eval df.gametype = :DWARF_ARENA
devel/spawn-unit-helper
=======================
Setup stuff to allow arena creature spawn after a mode change.
spawn creatures ('c' ingame),
With Arena spawn data initialized:
revert to game mode using:
rb_eval df.gametype = #{df.gametype.inspect}
- enter the :kbd:`k` menu and change mode using
``rb_eval df.gametype = :DWARF_ARENA``
To convert spawned creatures to livestock, select each one with the 'v' menu, and enter:
rb_eval df.unit_find.civ_id = df.ui.civ_id
- spawn creatures (:kbd:`c` ingame)
- revert to game mode using ``rb_eval df.gametype = #{df.gametype.inspect}``
- To convert spawned creatures to livestock, select each one with
the :kbd:`v` menu, and enter ``rb_eval df.unit_find.civ_id = df.ui.civ_id``
=end
EOS

@ -1,4 +1,11 @@
-- Generates an image using multiple octaves of perlin noise.
--[[=begin
devel/test-perlin
=================
Generates an image using multiple octaves of perlin noise.
=end]]
local args = {...}
local rng = dfhack.random.new(3)

@ -1,3 +1,10 @@
# unforbid all items
=begin
devel/unforbidall
=================
Unforbid all items.
=end
df.world.items.all.each { |i| i.flags.forbid = false }

@ -1,4 +1,11 @@
-- Show the internal path a unit is currently following.
--[[=begin
devel/unit-path
===============
Show the internal path a unit is currently following.
=end]]
local utils = require 'utils'
local gui = require 'gui'

@ -1,4 +1,13 @@
-- Logs minecart coordinates and speeds to console.
--[[=begin
devel/watch-minecarts
=====================
Logs minecart coordinates and speeds to console.
Usage: ``devel/watch-minecarts start|stop``
=end]]
last_stats = last_stats or {}

@ -5,6 +5,15 @@ gui/power-meter
===============
An in-game interface for `power-meter`.
Bind it to a key (default :kbd:`Ctrl`:kbd:`Shift`:kbd:`M`) and activate
after selecting Pressure Plate in the build menu.
.. image:: /docs/images/power-meter.png
The script follows the general look and feel of the regular pressure
plate build configuration page, but configures parameters relevant to
the modded power meter building.
=end]]
local utils = require 'utils'
local gui = require 'gui'

@ -1,11 +1,16 @@
-- Force a migrant wave (only works after hardcoded waves)
--@alias = 'devel/migrants-now'
--[[=begin
migrants-now
============
Forces an immediate migrant wave. Only works after migrants have
arrived naturally. Alias for ``devel/migrants-now``; equivalent to
`modtools/force` ``-eventType migrants``
arrived naturally. Equivalent to `modtools/force` ``-eventType migrants``
=end]]
df.global.timed_events:insert('#',{
new = true,
type = df.timed_event_type.Migrants,
season = df.global.cur_season,
season_ticks = df.global.cur_season_tick+1,
entity = df.historical_entity.find(df.global.ui.civ_id)
})

@ -4,6 +4,7 @@
source
======
Create an infinite magma or water source or drain on a tile.
For more complex commands, try the `liquids` plugin.
This script registers a map tile as a liquid source, and every 12 game ticks
that tile receives or remove 1 new unit of flow based on the configuration.

@ -65,8 +65,11 @@ class Linter(object):
class NewlineLinter(Linter):
msg = 'Contains DOS-style newlines'
def __init__(self):
# git supports newline conversion. Catch in CI, ignore on Windows.
self.ignore = sys.platform == 'win32' and not os.environ.get('TRAVIS')
def check_line(self, line):
return '\r' not in line
return self.ignore or '\r' not in line
def fix_line(self, line):
return line.replace('\r', '')

@ -1,17 +1,19 @@
from io import open
import os
from os.path import basename, dirname, join, splitext
import sys
scriptdirs = (
'scripts',
#'scripts/devel', # devel scripts don't have to be documented
'scripts/fix',
'scripts/gui',
'scripts/modtools')
def expected_cmd(path):
"""Get the command from the name of a script."""
dname, fname = basename(dirname(path)), splitext(basename(path))[0]
if dname in ('devel', 'fix', 'gui', 'modtools'):
return dname + '/' + fname
return fname
def check_file(fname):
doclines = []
errors, doclines = 0, []
with open(fname, errors='ignore') as f:
for l in f.readlines():
if doclines or l.strip().endswith('=begin'):
@ -27,23 +29,24 @@ def check_file(fname):
title, underline = doclines[2], doclines[3]
if underline != '=' * len(title):
print('Error: title/underline mismatch:', fname, title, underline)
return 1
start = fname.split('/')[-2]
if start != 'scripts' and not title.startswith(start):
print('Error: title is missing start string: {} {} {}'.format(fname, start, title))
return 1
return 0
errors += 1
if title != expected_cmd(fname):
print('Warning: expected script title {}, got {}'.format(
expected_cmd(fname), title))
errors += 1
return errors
def main():
"""Check that all DFHack scripts include documentation (not 3rdparty)"""
errors = 0
for path in scriptdirs:
for f in os.listdir(path):
f = path + '/' + f
if os.path.isfile(f) and f[-3:] in {'.rb', 'lua'}:
errors += check_file(f)
return errors
err = 0
for root, _, files in os.walk('scripts'):
for f in files:
# TODO: remove 3rdparty exemptions from checks
# Requires reading their CMakeLists to only apply to used scripts
if f[-3:] in {'.rb', 'lua'} and '3rdparty' not in root:
err += check_file(join(root, f))
return err
if __name__ == '__main__':

@ -1,15 +1,11 @@
import argparse, os, sys, subprocess
import argparse
import os
import subprocess
import sys
parser = argparse.ArgumentParser()
parser.add_argument('--path', default='.', help='Root directory')
parser.add_argument('--ext', help='Script extension', required=True)
parser.add_argument('--cmd', help='Command', required=True)
args = parser.parse_args()
def main():
def main(args):
root_path = os.path.abspath(args.path)
cmd = args.cmd.split(' ')
ext = '.' + args.ext
if not os.path.exists(root_path):
print('Nonexistent path: %s' % root_path)
sys.exit(2)
@ -19,14 +15,24 @@ def main():
if '.git' in parts or 'depends' in parts:
continue
for filename in filenames:
if not filename.endswith(ext):
if not filename.endswith('.' + args.ext):
continue
full_path = os.path.join(cur, filename)
try:
subprocess.check_output(cmd + [full_path])
except subprocess.CalledProcessError:
err = True
except IOError:
if not err:
print('Warning: cannot check %s script syntax' % args.ext)
err = True
sys.exit(int(err))
if __name__ == '__main__':
main()
parser = argparse.ArgumentParser()
parser.add_argument('--path', default='.', help='Root directory')
parser.add_argument('--ext', help='Script extension', required=True)
parser.add_argument('--cmd', help='Command', required=True)
args = parser.parse_args()
main(args)